Land FOC Platform v1 demo-to-production stack

[snissn]

Goal

Land the FOC Platform v1 demo-to-production stack selected in spec.md: platform EOA/KMS payer, FOC session-key coordinator, hosted coordination, section 6.7 registry semantics, Token Host Builder-generated app/admin/read/upload scaffolding, and a reproducible Filecoin Calibration demo with production hardening gates.

Current Evidence

• README.md and spec.md are the only files in this repository today.
• Closed planning issue: Land Token Host Builder-first plan for FOC Platform Stack #3
• The spec selects the v1 default: platform EOA/KMS payer, FOC session keys, hosted coordinator, onchain request/object/usage/receipt state, and Token Host Builder-first scaffolding.
• Existing external Token Host Builder follow-ups:
  • Add app.focPlatform schema and manifest extension tokenhost/tokenhost-builder#79
  • Support FOC Platform registry lifecycle generation or wrapper mode tokenhost/tokenhost-builder#80
  • Generate FOC Platform admin and reconciliation surfaces tokenhost/tokenhost-builder#81
  • Add FOC Platform receipt-aware upload runner path tokenhost/tokenhost-builder#82

Desired State

The repo contains an executable implementation, not only a spec:

• FocPlatformRegistry preserves the section 6.7 lifecycle, access, idempotency, receipt, and accounting invariants.
• A hosted coordinator uses Synapse SDK and FOC session keys to execute uploads and finalize compact receipts.
• A platform API/relay surface exposes normal product upload/status/object/usage flows.
• Token Host Builder is used strongly for generated app, admin/read surfaces, upload adapter wiring, manifest metadata, and sponsored transaction UX.
• A Calibration demo is reproducible and the production-readiness boundary is explicit.

Scope

• Build the first executable FOC Platform implementation from the current spec.
• Keep FocPlatformRegistry / section 6.7 semantics authoritative unless Token Host Builder proves equivalent generated module support.
• Use Token Host Builder strongly for generated demo app, admin/read surfaces, upload adapter wiring, manifest metadata, and sponsored transaction UX.
• Produce a Calibration-backed demo that is honest about what is demo-ready versus production-ready.

Non-Goals And Boundary

• Do not make smart-account payer, contract treasury payer, direct browser-to-FOC upload, BYO coordinator, or proof/challenge finalization v1 defaults without Phase 0 evidence plus a spec update.
• Do not treat generic Token Host CRUD generation as production-equivalent to section 6.7 lifecycle/accounting/receipt semantics.
• Do not put platform root keys, coordinator private keys, or privileged session keys into browser or generated static artifacts.

Dependency Graph

M0 Phase 0 compatibility report
M1 Repo/toolchain/CI scaffold

Core lane:
  M2 FocPlatformRegistry v1 contract
  M3 Vertical-slice upload spine
  M4 Contract deploy/read/index surface
  M5 Hosted Synapse/session-key coordinator
  M6 Platform API/relay surface

Demo/generated lane:
  M7 Token Host Builder wrapper/demo app
  M8 Admin/reconciliation views

Release lane:
  M9 End-to-end Calibration demo
  M10 Production hardening/runbook

Node	Issue	Blocks / enables
M0	#6	Blocks production registry/coordinator/demo claims; validates v1 FOC assumptions
M1	#7	Blocks all implementation PRs that need repo commands/CI
M2	#8	Blocks vertical slice, deploy/read model, coordinator, API, and demo integration
M3	#9	Enables early demo/UI integration with a dev/mocked coordinator path
M4	#10	Enables API, coordinator, Token Host wrapper, admin, and demo release
M5	#11	Enables real FOC upload/finalization and end-to-end demo
M6	#12	Enables product/generated clients to drive the lifecycle
M7	#13	Enables public generated demo app path; can use wrapper mode if builder custom module lags
M8	#14	Enables operator/admin/reconciliation demo proof
M9	#15	Proves demo-ready lifecycle on Calibration
M10	#16	Closes production-minded hardening/runbook boundary

External Token Host Builder Dependencies

• Add app.focPlatform schema and manifest extension tokenhost/tokenhost-builder#79: app.focPlatform schema and manifest extension.
• Support FOC Platform registry lifecycle generation or wrapper mode tokenhost/tokenhost-builder#80: registry lifecycle generation or wrapper mode.
• Generate FOC Platform admin and reconciliation surfaces tokenhost/tokenhost-builder#81: admin and reconciliation surfaces.
• Add FOC Platform receipt-aware upload runner path tokenhost/tokenhost-builder#82: receipt-aware upload runner path.

The platform graph must not wait for perfect builder generation before proving the v1 platform path. Use wrapper mode around the hand-written registry whenever builder work lags, and keep any remaining builder gap linked.

North-Star Gates

Gate	Current	Target	Required evidence	If the gate fails
Calibration session-key path	Spec only	One object uploaded through platform EOA/KMS root plus FOC session-key coordinator	tx hashes/logs, SDK/tool commands, receipt evidence	Keep Phase 0 open and block production coordinator/contract claims
Registry lifecycle correctness	Spec only	Section 6.7 lifecycle, access, idempotency, receipt, and accounting invariants pass focused tests	contract tests and event/error assertions	Block dependent API/coordinator/demo claims
Generated demo integration	Spec only	Token Host generated/wrapped app can drive or display the upload flow without weakening registry semantics	build artifact, manifest, UI/demo proof	Use wrapper mode or keep builder issue linked as blocker
Reconstructable state	Spec only	Object, usage, coordinator, and receipt state can be reconstructed from chain/events plus FOC evidence	index/read tests and reconciliation proof	Add/keep reconciliation blocker before production hardening closes
Secret isolation	Spec only	no root/coordinator private key material in browser/static/generated artifacts	config review, secret scan, docs	Block release/demo publication
Reproducible demo	None	exact commands run on a clean checkout against Calibration	runbook, env template, final evidence table	Keep demo issue open

Branch And PR Policy

No repo-local AGENTS.md, CONTRIBUTING.md, or PR template exists today. Until the repo adds stricter governance:

• Work happens on topic branches.
• Direct pushes to main are avoided unless explicitly authorized.
• Each child issue lands through a focused PR.
• PRs must be mergeable before merge: latest-head checks, focused tests, required evidence, and resolved review threads.
• Codex, Copilot, and CodeRabbit reviews are requested only after the PR is mature enough to avoid review-credit churn: coherent code, focused tests, required evidence or rationale, current PR body/status evidence, no known local blockers, and latest-head CI running or green.
• Stale non-head CI runs should be canceled when CI exists; only latest-head checks count.

Required PR Body Sections

• Linked tracker issue and graph node.
• Start-phase test/evidence plan.
• Close-phase test evidence.
• Close-phase demo/compatibility evidence when relevant.
• Security/secret-handling assessment when touching coordinator, API, generated UI, deployment, or credentials.
• AI review status and unresolved thread summary.

Completion Criteria

This umbrella closes only when:

• M0-M10 are complete or explicitly superseded by linked replacement issues.
• The end-to-end Calibration demo has reproducible evidence.
• Token Host Builder is used for the generated app/demo/admin surface or the exact external blockers are linked and wrapper mode remains documented.
• Production-readiness claims are limited to what the evidence proves.

[snissn]

FOC Platform Issue Graph State

Updated: 2026-07-02T03:37:34Z
Coordinator: Codex issue graph executor
Parent tracker: #5

Direct-Onchain Dashboard Stack (#27)

Status: merged/closed. The ordered dashboard graph completed in dependency order:

Node	Issue	PR	Status	Merge commit / closeout
D0	#29 Land onchain pagination views for FocPlatformRegistry	#34	merged / closed	4d5a9e81c4f94ffd49d0c98f3ec601a3558c9e4b
D1	#30 Clarify direct-onchain read requirements for admin views	#35	merged / closed	590a16004121e4c7a9c7ccfea9c6e97d030e4bc9
D2	#31 Wire Token Host wrapper to FOC Platform onchain list reads	#36	merged / closed	66a2ae41d89ddc53bd9c1e5916a3996ef23ec5a9
D3	#32 Build direct-onchain admin dashboard for platform usage	#37	merged / closed	ff85d8eeac9903d731796f7147c9f0096dd20def
D4	#33 Publish Calibration evidence for direct-onchain dashboard reads	#38	merged / closed	8964571ff133318f13dfa7df6d60bcfcf537e011

Calibration Worker / Ops Stack

Issue	PR	Status	Merge commit / closeout
#15 Ship end-to-end Calibration demo	#26	merged / closed	8238260ea65c91ac5c649e46480372a49572156e
#16 Harden production operations and runbook	#28	merged / closed	080b349d9e73008adc41139935fdc9fa1552a542

Current Evidence

• PR Publish Calibration direct-read dashboard evidence #38 merged at 2026-07-02T03:37:34Z and closed Publish Calibration evidence for direct-onchain dashboard reads #33.
• Latest direct-read evidence targets Calibration registry 0x8F6563Bb9E53aeDfE9d87d4C1E162f0371649c18, deploy tx 0xae42c13c50c1b268a1d38389e27d8fa776264b405e28a1cf11a974dd4b178eae, deploy block 3854411, runtime hash 0x2c49443e7a9ebf3337453240e706df249d29f4f217ec948d6c10e9502a199d1f.
• Public Worker URL: https://foc-platform-calibration-demo.snissn.workers.dev
• Worker version recorded in docs/evidence: c83bd91f-164e-4a48-9d0a-06518cd51212.

Merge Gates Used For PR #38

• Local: node --test test/calibration-worker.test.mjs, pnpm lint, pnpm test, pnpm worker:dry-run passed on final head.
• CI: CI / test passed on head ba98bf68ea8c82cbae0d7cbf8c8c26e556521da3.
• Reviews: all GitHub review threads resolved. GitHub Codex found and the branch fixed two metadata issues on earlier heads. Current-head GitHub Codex was repeatedly requested after the mature head but did not respond; this was recorded on PR Publish Calibration direct-read dashboard evidence #38 as reviewer nonresponse, with an independent current-head Codex subagent review finding no merge-blocking issue.

Remaining Parent #5 Work

The direct-onchain dashboard stack is complete, but parent #5 remains open because production blockers remain outside this dashboard stack:

• Land Phase 0 Calibration compatibility report #6 Land Phase 0 Calibration compatibility report: open.
• Build hosted Synapse session-key coordinator #11 Build hosted Synapse session-key coordinator: open.

No production-readiness claim should hide those remaining blockers.