plan: portable-core-contracts

[yihanzhu]

Closes #178

Pre-code plan gate

This PR proposes the exact implementation plan for the accepted portable-core-contracts spec. It records spec blob f5b218626dec8484518295e901e427e3ff8f3daf and changes only work/portable-core-contracts/plan.md.

The plan is the first commit on ystack/impl/portable-core-contracts; the current reviewed head is 874d9724a16150b40c9fabeb8ecf2f81f0618f1b, followed only by its plan-review fix. No implementation code or implementation PR exists.

Plan outcome

• One inactive implementation PR, expected at about 900–1,100 normally formatted lines under the accepted review-size exception.
• One product schema source: core/v1/contracts.jq.
• One public front door: scripts/core-contract.sh.
• One test-only fixture builder plus one real-CLI adversarial test suite with at least 60 mutations.
• Four implementation/review sections in one PR: raw-byte/schema boundary, profile relations, stage truth, and tests/docs/CI.
• Exact jq 1.6 Linux and macOS/Rosetta asset hashes, exact stable error ownership, exact validation order, and exact proof commands.
• No Git read, adapter/candidate execution, model call, policy evaluation, credential access, external write, profile activation, install change, or /yshifu change.

Review

Independent implementability and security/compliance reviews are clean. Their one shared finding was resolved before this commit: parsed depth/member/string/integer limits return E_LIMIT from contracts.jq, while raw byte size remains the wrapper's E_LIMIT. The fixed validation order is raw bytes → parsed limits → shape → ref → relation.

Formal round-0 found an unbounded MANIFEST... list. Round-1 bounds validate-profile-set to 1–8 manifest arguments, returns E_USAGE for 0 or 9+ before opening any input, and requires 0/1/8/9 sentinel-path tests. Independent implementability and security reviews of that exact fix are clean.

Formal round-1 reviewed exact head 874d9724a16150b40c9fabeb8ecf2f81f0618f1b against base 1c2f1844041f5323d742e0e389b2f43fea6eeb7e and found no actionable correctness issue: #179 (comment). GitHub CI is green on the same head.

Exact-head proof

Clean isolated worktree at 874d9724a16150b40c9fabeb8ecf2f81f0618f1b against base 1c2f1844041f5323d742e0e389b2f43fea6eeb7e:

• plan stage scope: only work/portable-core-contracts/plan.md changed;
• plan is the first commit after the merged spec base;
• required headings, spec-blob, and intent freshness: passed;
• structure check: passed;
• ShellCheck 0.11.0: passed;
• north-star resolver: 74 passed, 0 failed;
• north-star gate/consumer: 226 passed, 0 failed;
• models parser: 63 passed, 0 failed;
• degraded-review gates: 91 passed, 0 failed;
• pending-stage, round-cap, and quota tests: passed;
• rename/doctor cases: 27 passed, 0 failed;
• rename gate and git diff --check: passed.

Merging this PR accepts only this exact plan and permits implementation to begin. It does not accept code, create a live validator, activate a profile, or grant agent merge authority. Any later plan change invalidates this acceptance. Human merge only.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: b9c82bc
Reviewed-base: 1c2f184
reviewer: operator-default @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/179-73462/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The plan leaves the variable manifest input list unbounded, undermining its fixed resource limits and allowing avoidable local resource exhaustion.

Review comment:

• [P2] Bound manifest arguments before snapshotting — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.OM6BvkCOXa/work/portable-core-contracts/plan.md:60-64
  For validate-profile-set, MANIFEST... has no count limit, so a caller can supply many 1 MiB files and make the wrapper consume unbounded temporary storage and jq input before the exact-set relation rejects them. A profile has at most eight bindings, so reject more than eight manifest arguments before reading any files and test that boundary.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 874d972
Reviewed-base: 1c2f184
reviewer: operator-default @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/179-90160/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The plan matches the accepted spec, records the correct spec blob, bounds manifest inputs, preserves the inactive-validator scope, and provides suitable implementation and proof steps. No actionable correctness issue was found.

[yihanzhu]

Final handoff — plan review clean, CI green

Plan head 874d9724a16150b40c9fabeb8ecf2f81f0618f1b passed every exact-head local gate and GitHub CI against base 1c2f1844041f5323d742e0e389b2f43fea6eeb7e.

Formal round-1 found no actionable correctness issue: #179 (comment)

The PR changes only work/portable-core-contracts/plan.md. The same plan head is present on ystack/impl/portable-core-contracts; there is still no implementation code or implementation PR.

merge-ready is applied. Merging accepts this exact pre-code plan and permits implementation to begin. Any later plan change invalidates this acceptance. Human merge only.