server-deploy/docs/superpowers/plans/2026-09-25-package-inspection.md

Package Verification and Inspection Implementation Plan

For agentic workers: Execute with test-driven-development; package worker and local inspection work have disjoint write scopes. No commits, production connections, or deployment writes.

Goal: Add read-only package verification and a factual local prerequisite report to deployctl.

Architecture: A shared bounded strict JSON decoder supports nested typed arrays. An immutable package verifier returns verified manifest and file bytes, never executes templates. A local probe reports OS/architecture and tool/runtime presence, with unperformed checks explicitly marked unknown.

Tech Stack: Go standard library. Existing local Windows and Ubuntu WSL test runtimes.

Spec: docs/2026-09-25-complete-optimization-proposal.md sections 5, 7, 12, 14.

Boundaries and integration

• Parent owns internal/wire, internal/inspect, internal/cli, docs and CLI tests.
• Package worker owns only internal/appbundle; requirements are in package-verifier-brief.md beside this plan.
• Package code consumes wire.Decode(reader io.Reader, target any, limit int64) error.
• CLI consumes appbundle.Verify(directory, expectedDigest string) (Verified, error); Verified has Manifest, Files map[string][]byte, Digest string. CLI never prints file bodies.
• Local inspect is not full host acceptance; Docker daemon, Compose, firewall, DNS, permissions and port availability remain explicitly unverified.
• Expected digest must come from a trusted channel. Matching it does not establish publisher identity on its own.

Task 1: Shared strict wire decoder

• Move strict JSON decoder from internal/cli to internal/wire, keeping all CLI tests passing.
• Add failing tests for nested array unknown/missing/case-alias fields and null elements, duplicate keys and input limit.
• Extend recursive validation through typed slices and reject invalid UTF-8. Preserve canonical UTC timestamp policy.
• Test the API wire.Decode(strings.NewReader(input), &value, 1024) using real JSON.

Task 2: Application package verifier

• Worker implements bounded manifest validation, pinned multi-component images, exact file inventory, SHA-256 content checks and path/symlink rejection using tests first.
• Parent reviews written code and runs all tests, including Linux symlink cases.
• Independent review checks all file access and integrity boundaries.

Task 3: Read-only inspection and CLI

• internal/inspect provides Collect() Report and a testable filesystem probe. Report includes OS, architecture, Linux support, systemd runtime presence and Docker client presence, with explicit unchecked prerequisites.
• Missing or inaccessible files produce missing/unknown observations, never false success. No shell commands, network, credentials or environment changes.
• CLI inspect emits observations with deploymentReady=false.
• CLI verify-package accepts {directory, expectedDigest}, emits manifest, digest, file count and executable=false; rejects invalid input with redacted diagnostics.
• Add actual CLI tests for new commands and unsupported writes.

Verification

• Windows go test/vet, CLI smoke; Linux full tests, race check and build.
• Record separate implemented, unverified and not-yet-supported capabilities.

Execution notes

Task 1 + Task 2 share only the Decode interface; Task 2 must not modify it. Task 3 consumes their exports without exposing package bytes. Directory paths are accepted only for read-only local verification. Files remain subject to trusted staging ownership; future execution must use the verified snapshot rather than reopening mutable package files.

Independent review found an alternate Docker path omitted when the primary path was invalid or inaccessible. Three failing regression cases reproduced it before the fix. Fallback now prefers presence, then uncertainty, invalidity and absence. Focused re-review found no remaining issues. Final Windows and Linux checks passed; see implementation-status.md for the initial non-reproduced Linux compiler error.