Skip to content

fix(docs): use content-addressed manual provenance - #79

Merged
kegouro merged 1 commit into
mainfrom
fix/docs-content-addressed-provenance
Aug 3, 2026
Merged

fix(docs): use content-addressed manual provenance#79
kegouro merged 1 commit into
mainfrom
fix/docs-content-addressed-provenance

Conversation

@kegouro

@kegouro kegouro commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Problem

The documentation-sync check coupled the identity of the current manual
artifacts to a manually recorded historical Git commit.

Legitimate updates to the manual could therefore make the recorded commit
stale even when the committed artifacts were internally consistent. Updating
the commit hash would only postpone the same failure.

Resolution

This PR replaces the historical-commit invariant with deterministic,
content-addressed provenance.

The committed manifest records, for each published manual artifact:

  • repository-relative path;
  • exact byte size;
  • SHA-256 digest.

Covered artifacts:

  • docs/user-guide.md
  • docs/user-guide.tex
  • docs/user-guide.pdf

scripts/update_manual_provenance.py provides:

  • --write for explicit deterministic regeneration;
  • --check for read-only CI verification.

The manifest is canonical UTF-8 JSON with LF termination and contains no
timestamps, usernames, absolute paths, cache paths, temporary paths, branch
names, or manually maintained Git commit hashes.

CI behavior

check_docs_sync.py now verifies the committed files against the manifest.
The check still fails on missing, modified, stale, malformed, or unexpected
artifacts.

Git history is no longer required, so full-history checkout was removed from
the documentation workflow.

Verification

  • focused provenance tests: 7 passed;
  • deliberate byte and size tampering detected;
  • missing, stale, malformed and non-portable manifests rejected;
  • repeated --write output byte-identical;
  • --check confirmed non-mutating;
  • documentation sync passed;
  • visual-system verification passed;
  • MkDocs strict build passed;
  • Ruff passed;
  • Black passed;
  • Mypy passed;
  • documentation links passed;
  • diff check passed.

Scope

This proves exact artifact identity only. It does not claim semantic
correctness or reproducible PDF generation.

No scientific algorithms, numerical fixtures, APIs, validation thresholds,
or maturity claims are changed.

@kegouro
kegouro merged commit f99b184 into main Aug 3, 2026
6 checks passed
@kegouro
kegouro deleted the fix/docs-content-addressed-provenance branch August 3, 2026 09:05
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.

1 participant