Skip to content

feat(manifest): add per-file digest provenance - #87

Merged
stacknil merged 8 commits into
mainfrom
stacknil/issue-84-per-file-digest-provenance
Aug 12, 2026
Merged

feat(manifest): add per-file digest provenance#87
stacknil merged 8 commits into
mainfrom
stacknil/issue-84-per-file-digest-provenance

Conversation

@stacknil

@stacknil stacknil commented Aug 10, 2026

Copy link
Copy Markdown
Owner

Summary

Closes #84.

  • Add required input_file_digests and config_file_digests to current run manifests.
  • Hash each file's exact bytes with SHA-256; no YAML parsing or reserialization.
  • Preserve the existing input_digest and config_digest algorithms and all six v1.2 aggregate values.
  • Keep the published strict run-manifest/v1 schema frozen and version the new shape as run-manifest/v2.
  • Normalize shipped keys to canonical repository-relative POSIX paths in lexical order.
  • Give copied demos stable demos/<demo>/... identities and external window inputs explicit external/input/... or external/config/... identities, without local path leakage.
  • Pin manifest-covered inputs/configs and writer-generated text artifacts to LF so exact-byte values and clean rewrites reproduce across Windows and Linux clones.
  • Keep structured artifact diff reporting (Add structured artifact-contract diff reporting #85) out of scope.

Design decision

The legacy aggregate contract remains label-sorted and LF/CRLF-normalized for UTF-8 text. Per-file digests use exact raw bytes. Aggregate and per-file maps must reference the same resolved file set, and each distinct file is read once so both contracts derive from one byte snapshot.

Because the published v1 schema has additionalProperties: false, the new fields are not honestly additive for strict v1 validators. The v1 schema remains unchanged at schemas/run_manifest.schema.json; current writers identify and validate against schemas/run_manifest.v2.schema.json.

Main risk

This is an intentional manifest schema-version transition: consumers pinned to v1 must select the v2 schema before consuming current manifests. The LF checkout contract renormalizes four historical CRLF/mixed tracked input/config files and one generated report at the Git blob boundary. All five were confirmed content-identical when EOL differences are ignored.

Compatibility impact

  • Legacy v1 manifests remain valid against the frozen v1 schema.
  • Strict v1 validators are expected to reject v2 manifests.
  • V2 requires both per-file maps and canonical path keys.
  • Existing aggregate digest algorithms and committed values remain unchanged.
  • Standalone/external runs use stable logical namespaces instead of machine-dependent paths.
  • Writer-guaranteed LF reports/manifests remain clean after regeneration under core.autocrlf=true.

Rollback path

Revert the PR merge commit to restore v1 writers and artifacts. Consumers can continue validating retained v1 manifests with the frozen v1 schema. If the LF checkout contract is reverted independently, regenerate manifests against the chosen shipped-byte contract before publication.

Validation

  • Delayed four-way read-only diff review completed; identified v1 versioning, path identity, same-file-set, and single-snapshot issues were addressed.
  • python scripts/check_release_contract.py — 29 committed artifacts matched, 6 visual snapshots smoke-generated, 8 schema tests passed, 202 full tests passed.
  • Fresh remote shallow clone at 7bc939f — the same release gate passed; six manifests were independently rehashed with read_bytes(); tracked worktree remained clean after the gate.
  • Independent compatibility audit — frozen v1 acceptance, expected v1/v2 rejection boundary, v2 validation, unchanged aggregate values, canonical sorted paths, and exact SHA-256 values all passed.
  • Final diff review confirmed the frozen v1 schema blob is unchanged, five EOL-only files have no content changes, no local identity/path leakage is present, and all four current GitHub checks pass.

@stacknil
stacknil marked this pull request as ready for review August 12, 2026 08:27
@stacknil
stacknil merged commit ecb0bb2 into main Aug 12, 2026
4 checks passed
@stacknil
stacknil deleted the stacknil/issue-84-per-file-digest-provenance branch August 12, 2026 08:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add per-file digest provenance to run_manifest

1 participant