distribution/.agents/runs/2026-06-02-orchestration-planning/discussion-round-1-opus.md

Discussion Round 1 - Opus

Agreements

Opus accepts Snarky's eight decisions:

• Ship the NAS release console first.
• Drop pub/alias/namespace re-export from the critical path.
• Replace Milestone 1 with a walking skeleton.
• Make Linux/NAS the first runtime target.
• Allow FFI as a thin, named, replaceable boundary.
• Keep orchestration sequential and artifact-driven.
• Remove Release.channel, add release state, and use promotion history for rollback.
• Use the v1 access model with app visibility, roles, scoped tokens, and signed install links.

Opus also accepts Snarky's challenges: temporary boundaries must be named, M1 can be small but the product model cannot be vague, FFI must be Linux-first, and the mock redesign must preserve iOS install truth.

Remaining Technical Objections

1. The cross-repo sx governance stop is still unresolved.

   FFI reduces compiler-bug surface but does not remove it. #foreign and comptime are themselves active sx risk areas. If an M1 slice trips an sx bug, sx/CLAUDE.md requires filing an issue, marking blocked, ending the session, and not working around it. The distribution orchestration needs an explicit sx-blocked state and handoff.

2. M1 std signatures must pin to landed sx error handling.

   Do not implement against planned error semantics. Pin to the current landed shape and record the checkpoint/commit.

3. M1 APK inspection must not become an AXML decoder.

   For M1, artifact inspection means opening the zip central directory and confirming AndroidManifest.xml exists with size/offset. Decoding binary Android XML is M2.

4. Enterprise install readiness depends on proxy HTTPS.

   distd cannot self-satisfy the Enterprise HTTPS requirement if TLS is behind a reverse proxy. dist doctor can validate config/reachability, not TLS termination by distd.

5. Public visibility needs an iOS artifact-only carve-out.

   An iOS artifact-only IPA should never be anonymously downloadable, even on a public app.

Refinements To Snarky

• M1 JSON output should be the same shape later used by HTTP and remote dist ci publish.
• M1 artifact inspection is zip-entry presence/size only.
• FFI boundaries should be named:
  • miniz/libzip or zlib for zip reads
  • libsqlite3 deferred to M2
  • HMAC for signed links in M2
  • SHA-256 remains a compiler-risk choice, not a portability mandate
• rejected is terminal.
• M1 releases can go draft -> published with validation=not_run.
• Signed install links are HMAC over (artifact_id, expiry) with a server key.
• Download auth should be a table across actor/auth mode, visibility, and platform.

Minimal Plan Patch Order

1. git init and baseline commit.
2. Patch Subplan 01:
   • remove dangling references
   • park pub as language-track work
   • pin error model to landed sx state
   • mark FFI-first/Linux boundaries
3. Patch PLAN.md:
   • replace the first milestone with the walking skeleton
   • demote HTTP/SQLite/UI/Docker to later milestones
4. Patch Subplan 02:
   • remove Release.channel
   • add Release.state
   • add validation outcome
   • add ChannelPromotion
5. Patch Subplan 03:
   • local publish first
   • add dist.json schema and example
   • add idempotency key and rerun behavior
6. Patch Subplan 05:
   • label validation checks as required, warning, informational, or not_supported
   • scope M1 APK to zip-entry presence
7. Patch Subplan 04:
   • split Enterprise and MDM
   • add TLS-by-proxy caveat
   • define concrete routes and JSON shapes
8. Add access-policy section:
   • roles
   • visibility
   • token scopes
   • signed-link HMAC
   • download authorization table
   • iOS artifact-only never public
9. Patch orchestration:
   • add sx-blocked state
   • split Opus read-only consultation approval from write implementation approval

What Opus Needs Before Any Code

1. Answer the sx governance question: on an M1 compiler bug, does the distribution run hard-stop and file in sx/issues, or is there a sanctioned narrow-workaround budget?
2. Pin the current landed sx error-handling shape.
3. Approve the dist.json schema and idempotency key.
4. Approve the download authorization table.
5. Confirm libsqlite3 is M2 and M1 is DB-free.
6. For the mock branch, provide a Snarky brief.md with seed data and required UI states.