Skip to content

feat: content-addressed provenance with sig: prefix#12

Merged
laulauland merged 1 commit intomainfrom
lau/content-sig
Mar 30, 2026
Merged

feat: content-addressed provenance with sig: prefix#12
laulauland merged 1 commit intomainfrom
lau/content-sig

Conversation

@laulauland
Copy link
Copy Markdown
Member

Summary

Replace VCS-based provenance (@git-sha) with content-addressed signatures (@sig:<xxhash3-hex>). Staleness is detected by comparing fingerprints directly — no VCS calls needed.

This fixes:

How it works

drift link computes an XxHash3 fingerprint of the file (or symbol's AST subtree) and stamps it as @sig:<16-hex-chars>. drift check recomputes the fingerprint and compares — match means ok, differ means STALE.

For supported tree-sitter languages (TypeScript, Python, Rust, Go, Zig, Java), the fingerprint is AST-normalized so formatting-only changes don't trigger staleness. Unsupported languages fall back to raw content hash.

Blame is decoupled from provenance — derived from the spec file's last-modified commit instead of the provenance value.

Migration

Legacy @<git-sha> provenance continues to work. drift link always stamps sig: going forward. Specs migrate organically as they get relinked.

Changes

  • main.zigcheckAnchorBySig, computeFingerprint, computeContentSig for sig-based check/link
  • main.zigrunLink computes content sigs instead of git rev-parse
  • frontmatter.zig — test verifying anchorFileIdentity handles sig: prefix
  • docs/ — updated DESIGN.md, CLI.md, DECISIONS.md, SKILL.md

Test plan

  • drift link spec.md file.ts stamps @sig: provenance
  • drift link spec.md (blanket) computes per-anchor sigs
  • drift check with @sig: anchors: ok when content matches, STALE when different
  • Legacy @<git-sha> anchors continue to work
  • Formatting-only changes don't trigger staleness for supported languages
  • Blame info shown when STALE (derived from spec's last commit)

Replace VCS-based provenance (@git-sha) with content-addressed signatures
(@sig:<xxhash3-hex>). Staleness is now detected by comparing fingerprints
directly — no VCS calls needed. This fixes provenance invalidation from
rebasing/amending (issue #10) and enables linking uncommitted files (#9).

For supported languages, signatures use AST-normalized fingerprints (same
tree-sitter infrastructure). For unsupported languages, raw XxHash3 hash.
Blame is decoupled from provenance — derived from spec's last-modified
commit instead.

Legacy @<git-sha> provenance continues to work unchanged.
@laulauland laulauland merged commit 963bd07 into main Mar 30, 2026
5 checks passed
@laulauland laulauland deleted the lau/content-sig branch March 30, 2026 11:25
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