Roadmap item 4: Add local Git materializer protocol

[yihanzhu]

Summary

• Add the pure input, receipt, and stage-result protocol for core.forge.materialize-candidate.v2.
• Validate the complete profile, resolved profile, manifests, request, materialization contract, and patch payload links.
• Project one canonical path-free receipt and core-valid result without executing materialization.

Scope

Tracks Roadmap item 4 without closing an intake issue. This protocol is the missing dependency between the merged GitHub forge observation payload and a real inactive local candidate materializer. The runtime remains a separate unit; default-profile assembly waits for its durable merge identity.

Safety

This unit has no product executable. It cannot read or write a repository, run hooks or filters, use a credential or network, contact a provider, grant authority or qualification, activate a profile, or perform an external effect.

Targeted proof

• protocol matrix: 27 focused checks
• portable-core schema: all categories pass with zero failures
• ShellCheck 0.11.0, bash syntax, rename, and diff checks pass

The preserved one-concern branch was adopted by merging current main normally. It was not rebased or force-pushed.

[cloudflare-workers-and-pages]

Deploying ystack with    Cloudflare Pages

Latest commit:	4b71b0b
Status:	✅  Deploy successful!
Preview URL:	https://c03d2692.fabrica-6yx.pages.dev
Branch Preview URL:	https://codex-local-git-materializer.fabrica-6yx.pages.dev

View logs

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 9058c55
Reviewed-base: ec4203d
reviewer: operator-default @ high

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

The protocol can project receipts and passing results from unvalidated or insufficiently bound inputs. It also fails to enforce payload identity and two explicit materialization limits, undermining the exact evidence relations it is intended to establish.

Full review comments:

• [P2] Verify payload bytes against their declared digest — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.R5WeWXAMHW/adapters/local-git-materializer/v1/protocol.jq:74-78
  If .payloads[].data is replaced with another well-formed contract or patch while its declared SHA remains unchanged, validation still succeeds because payload_matches_input compares only two caller-controlled digest strings. The extraction commands can then return altered bytes while the receipt cites the original content reference, breaking evidence identity; require a trusted computed digest of data before accepting the payload.

• [P2] Bind receipt source fields to the stage request — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.R5WeWXAMHW/adapters/local-git-materializer/v1/protocol.jq:188-192
  For a valid input, the caller can omit source_repository_id or pass any repository and any correctly sized commit/tree OIDs; this condition validates only OID syntax. The resulting receipt still carries the validated request reference, falsely attributing unrelated source material to that request, so validate the repository ID and require the repository, algorithm, commit, and tree to equal the request's target revision and source-tree input.

• [P2] Validate the envelope on every projection command — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.R5WeWXAMHW/adapters/local-git-materializer/v1/protocol.jq:299-307
  The contract, patch, receipt, and stage-result entry points bypass input_ok, so invoking them directly on a malformed or stale envelope can still extract data or emit evidence. Because the public command interface does not enforce a prior validation call—and separate invocations can observe different input bytes—each projection command should fail unless its current input passes input_ok.

• [P2] Apply max_patch_bytes to the supplied patch — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.R5WeWXAMHW/adapters/local-git-materializer/v1/protocol.jq:160-163
  A contract can set max_patch_bytes to 1 while the input carries a much larger patch and still pass validation, because the limit is only range-checked inside the contract and never compared with the patch's byte length. This allows a supposedly validated materialization input to exceed its requested bound; require the patch payload's utf8bytelength to be at most the parsed contract limit.

• [P2] Enforce the contract's changed-path limit in receipts — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.R5WeWXAMHW/adapters/local-git-materializer/v1/protocol.jq:198-199
  With a valid contract whose max_changed_paths is 1, passing changed_path_count=2 still produces a receipt because only the generic integer shape is checked. That receipt can subsequently back passed deterministic evidence despite reporting a contract violation, so compare the count against the validated contract before emitting it.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 06dd4f5
Reviewed-base: ec4203d
reviewer: operator-default @ high

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

The safety-focused contract tests pass for the wrong reason and therefore do not protect the contract validation logic from regression.

Review comment:

• [P2] Synchronize trusted payloads in contract rejection tests — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.t6mP6sTgao/scripts/test/local-git-materializer-protocol.test.sh:110-112
  These unsafe-path mutations, and the subsequent mode/flag mutations, change only .payloads, so payload_matches_input rejects them because they no longer equal trust_context.verified_payloads before materialization_contract_ok is reached. If path, mode, or limit validation regresses, this negative matrix still remains green; mutate the matching verified content too, as the byte-limit case below does, so each test exercises its intended guard.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 7152a76
Reviewed-base: ec4203d
reviewer: operator-default @ high

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

The result projection can create core-valid passing evidence for an arbitrary, unvalidated receipt digest, bypassing the receipt-side guards added by this patch.

Review comment:

• [P2] Bind stage results to a validated receipt — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.1r1nDW9mw8/adapters/local-git-materializer/v1/protocol.jq:301-302
  With any otherwise valid input, stage-result accepts an arbitrary 64-hex receipt_sha256 and emits a completed result with passed deterministic evidence, even if receipt was never produced or would have failed its source and changed-path checks. Require the receipt content as a verified pair and relate its digest, request, attempt, and outcome before projecting a successful result.

[yihanzhu]

Round-cap escalation: the third independent review on exact head 7152a7698848286ffe2eb58900498b3112149c0d found one unresolved Important issue. stage-result can emit passed deterministic evidence for an arbitrary receipt digest without receiving and validating the receipt content against its source, attempt, request, limits, and outcome.

The branch and worktree are preserved and clean. No merge or further revision will occur without an operator ruling.

Operator question: authorize one final revision strictly limited to adding a caller-verified receipt pair, binding its digest/request/attempt/outcome to stage-result, and adding focused regressions; or direct that PR #228 be abandoned/rescoped?

[yihanzhu]

Operator ruling received directly in the active construction task: authorize one final revision only. Exact scope: add a caller-verified receipt pair; bind its digest, request, attempt, and outcome before stage-result may emit passing evidence; add focused regressions. No runtime, profile assembly, capability, permission, or external-effect change is authorized.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: e639cd8
Reviewed-base: ec4203d
reviewer: operator-default @ high

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

The protocol can emit a passing stage result for internally inconsistent candidate Git identities. The otherwise inactive implementation remains bounded, but this evidence-validation gap should be fixed before the protocol is consumed by a runtime.

Review comment:

• [P2] Reject one-sided candidate identity changes — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.igbOS5OGqH/adapters/local-git-materializer/v1/protocol.jq:350-352
  Bugs: For a changed outcome, this or accepts either an unchanged commit with a different tree, which is impossible because a commit fixes its tree, or a new commit with the source tree despite claiming changed paths. Such a receipt can therefore back passing deterministic evidence for an inconsistent candidate; require both commit and tree identities to differ and test both one-sided cases.

[yihanzhu]

Post-authorization final-review escalation: exact head e639cd8fab323a43dd1ee9030f3979c97ca1f3fa has one unresolved Important finding. The changed-outcome relation currently uses OR, so it accepts an unchanged commit with a changed tree or a changed commit with the unchanged source tree. A Git commit fixes its tree; passing evidence must require both candidate commit and candidate tree to differ for changed.

The branch/worktree are preserved and clean; CI is green. No merge or further edit will occur without a new operator ruling.

Operator question: authorize one last two-line semantic correction (or → and) plus the two one-sided identity regressions, followed by fresh exact CI and one final review?

[yihanzhu]

Operator explicitly authorized this exact final correction in the active construction task: on PR #228 change or to and, add the two one-sided commit/tree regressions, and clear needs-human. No other scope is authorized.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 5ee7d61
Reviewed-base: ec4203d
reviewer: operator-default @ high

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

The stage-result path can validate and attest a nested source tree even though receipt generation requires the repository root. This leaves inconsistent validation paths at the protocol's evidence boundary.

Review comment:

• [P2] Require the receipt source to be the root tree — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.hHxgmSpH7L/adapters/local-git-materializer/v1/protocol.jq:329-334
  When a core-valid request identifies a nested tree using location:{kind:"path",...}, input_ok accepts it and this comparison validates a supplied receipt using only that tree's ID. Consequently, stage-result can emit passing evidence for a receipt that the receipt command itself rejects at its root-location check, while the path-free receipt hides the narrower source scope. Mirror the receipt projection's location == {kind:"root"} constraint here.

[yihanzhu]

Final-review fail-closed escalation: exact head 5ee7d613ff7254a44b3deb65c9c062f50019d6f9 still has one unresolved Important finding. receipt requires the source git object to be the repository root, but stage-result receipt validation currently accepts a nested {kind:"path"} tree with the same ID. That lets passing evidence attest a receipt the receipt projection itself would reject.

The explicitly authorized OR-to-AND correction and its two tests are complete; this is a distinct omitted root-location invariant. The branch/worktree remain clean and CI is green. No merge or further edit will occur without operator disposition.

Operator question: authorize one additional exact two-file revision to require source_ref.location == {kind:"root"} in stage-result receipt validation and add the nested-tree regression; or direct that #228 be replaced/rescoped?

[yihanzhu]

Operator explicitly authorized the exact root-location correction in the active construction task. Scope is limited to requiring source_ref.location == {kind:"root"} in stage-result receipt validation and adding one fully rebound nested-tree regression.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 4b71b0b
Reviewed-base: ec4203d
reviewer: operator-default @ high

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

No actionable correctness issues were found in the diff. The protocol consistently validates its input graph, payload bindings, receipt relations, and stage-result projection, with focused negative coverage for the relevant boundaries.

[yihanzhu]

Operator authorized the exact downstream runtime conflict disposition in the active construction task: on codex/local-git-materializer-v1, keep the reviewed protocol from main, retain the runtime branch only for materialize.sh, runtime tests, and corresponding additive docs/manifest entries, then continue the Roadmap automatically.