checksums

Overview ¶

Package checksums owns forge's file-ownership machinery: which bytes does forge certify as its own render, which files has the user taken over, and what may a generate run overwrite.

── The mechanism (2026-06 redesign) ──────────────────────────────────

Tier-1 (regenerated-every-run) files are SELF-CERTIFYING: each one embeds its own content hash in the "Code generated by forge. DO NOT EDIT." header (`forge:hash=<sha256>` — see stamp.go for the hash spec and comment-syntax matrix). The pristine check is purely local: recompute vs embedded. There is no global manifest for Tier-1 — the old .forge/checksums.json was shared mutable state OUTSIDE the files it described, and it produced the fr-9a54388f0b failure class: a manifest committed from a WIP lane made a clean clone of green HEAD unable to regenerate itself, and every regen rewrote the manifest (pure-bookkeeping commits, constant conflicts between parallel agents).

Verification outcomes at a Tier-1 write site:

• no file on disk → new file: write it.
• marker matches body → pristine render of SOME vintage. If it differs from the current render, it is byte-indistinguishable from a deliberate edit (FRICTION fr-2c1c2328c7), so by DEFAULT the write SKIPS it loudly (once-per-file notice). Overwriting requires explicit opt-in: `--heal` (whole tree) or `--force` (this file).
• marker mismatches body → hand-edited: the stomp guard refuses, naming the file (per-run-scoped `--force` overwrites, `forge disown` transfers ownership).
• no marker, file exists → forge never certified these bytes at a path it owns: write (matches the legacy untracked-path behavior).

── What little persistent state remains under .forge/ ───────────────

• .forge/disowned.json — the one-way ownership door. Path + reason
• timestamp per `forge disown`. Generate skips these paths while the file exists; deleting the file re-adopts it. Committed.
• .forge/hashes.json — the scoped fallback for the few Tier-1 output formats that cannot carry comments (JSON). path → body hash of the last render. Deliberately minimal: this exception must not regrow the global manifest. Committed.

Scaffold ("yours") files carry NO marker and are user-owned from birth: forge writes each one exactly once, keyed on the file's own absence (WriteScaffoldIfMissing). Once the file exists forge NEVER overwrites it — no flag, no exception. To refresh one, delete it and regenerate. This is the single non-Tier-1 tier: there is no separate "scaffold reset" machinery (deleting the file IS the reset).

Public-identifier extraction for generated Go files.

The rename-detection pass (see RenameWarnings in this package) needs to know which exported names a Tier-1 Go file declared in its most recent render, so it can diff against the current render and flag dropped names whose callers may not have been updated. This file owns the AST parse that produces that list.

Non-Go files (.tsx, .yaml, .k, …) return an empty exports list — rename detection is currently scoped to Go callers because Go is the language where forge's codegen emits public package-level symbols that other (hand-written) packages depend on by name. Extending to TypeScript or KCL is straightforward but not needed by the current FRICTION class.

Canonical Go formatting — the formatter half of the self-certification contract for .go output.

── Why the writer formats before it stamps ───────────────────────────

The embedded forge:hash marker certifies exact bytes (modulo the line-ending/trailing-newline normalization documented in stamp.go). Go files, however, live under tooling that routinely rewrites bytes without changing meaning: gofmt realigns whitespace, goimports regroups import blocks (stdlib / third-party / local). If forge stamps a render that is NOT already in that canonical form, the first formatter pass over the tree turns every pristine render into byte drift, and the Tier-1 stomp guard reads it as a hand-edit (fr: control-plane 2026-07-08 — four internal/*/mock_gen.go files hard-blocked `forge generate` solely because a goimports pass had regrouped and aliased their imports).

The fix has two halves:

1. Format-before-stamp: WriteGeneratedFile passes every .go render through CanonicalGoSource BEFORE computing the stamp, so the certified bytes are a fixed point of the canonical formatter and a user's formatter pass is a no-op.
2. Normalize-on-compare: where a marker mismatches (the guard, the writer's Modified branch), the on-disk bytes are re-hashed AFTER the same canonical formatting; a match means formatter-only drift — still forge's render, not a hand-edit. Non-Go formats keep exact-byte semantics.

── The canonical formatter ───────────────────────────────────────────

CanonicalGoSource is goimports' formatting engine (golang.org/x/tools/imports.Process) in FormatOnly mode: gofmt plus import-block merging, sorting, and group splitting — but never the filesystem-scanning insertion/removal of imports, which would make output environment-dependent. The local-import prefix is the project's MODULE PATH, matching the two places forge already commits to that convention for user projects:

• the generate pipeline's post-write pass: `goimports -local <module> -w …` (runGoimportsOnGenerated), and
• the scaffolded .golangci.yml: `formatters.settings.goimports.local-prefixes: [<module>]`.

A pass of `goimports -local <module>` (or a golangci-lint fmt run with the scaffolded config) over canonical output is therefore a byte-level no-op. The one remaining semantic pass — the pipeline's real goimports fixing an import list — is already covered by RestampWritten.

Ownership inspector — single source of truth for "what does forge own at relPath, and how should we treat it?".

Background (2026-06-04 collapse pass): four parallel call sites in the generate pipeline each re-derived their own view of disowned / Tier-1 / Tier-2 ownership. The Inspector collapses those walks behind a small interface. In the self-certifying era ownership is read from the files themselves (the forge:hash marker scan) plus the two small state files (.forge/disowned.json, .forge/hashes.json) — there is no manifest to walk.

Scope: the Inspector answers questions about a *single project's* on-disk state. Call NewInspector once per pipeline run with the loaded *FileChecksums and project root; per-directory and per-file results are memoized so repeated queries inside one run don't re-read the disk.

One-time migration off the legacy global manifest (.forge/checksums.json) onto self-certifying files.

Runs automatically (and loudly) on the first `forge generate` / `forge upgrade` in a project that still carries the legacy manifest. Per legacy Tier-1 entry, in order:

• on-disk bytes match the entry's recorded hash OR any hash in its render history → the file is a pristine forge render of some vintage: stamp the forge:hash marker into it (comment-incapable formats get a scoped .forge/hashes.json entry instead);
• bytes match NOTHING the manifest recorded → provenance unknown. This is kalshi's exact mess (fr-9a54388f0b): a manifest committed from a different work lane than the committed bytes. The entry is returned as Unverified; the generate pipeline gives each such path one rescue attempt (side-render the fresh template output and compare bodies — a match proves pristineness and stamps the file), and everything unrescued is stamped with the UnverifiedMarkerValue sentinel so the stomp guard names it on every run until the user resolves it (--force to regenerate, `forge disown` to keep).

Disowned (and legacy forked) entries convert to .forge/disowned.json. Plain Tier-2 entries are dropped — scaffold-once files are user-owned from birth and need no record. Legacy Tier-1 entries whose path the CURRENT forge no longer emits are dropped too (the file stays, now plainly user-owned — stamping it would feed the stale-artifact sweep a file no emitter will ever refresh).

The legacy manifest is DELETED at the end. The migration is metadata-only and durable: it lands once, even if the same run later aborts at the stomp guard.

Side-render bookkeeping.

Two consumers remain now that the fork lifecycle is gone:

• `forge generate --explain-drift` parks transient fresh renders under `.forge/render/<relpath>` so the post-pipeline diff can show "on-disk vs what regeneration would produce" without touching the user's drifted file (WriteSideRenderNoBase).
• `forge unfork --merge` — the one-release migration aid for LEGACY forks — three-way-merges ours/base/theirs from `.forge/render/<relpath>` and `.forge/render-base/<relpath>`, renders parked by pre-disown forge versions. Current forge never writes render-base; the constants survive only so the migration tool can find what older versions left behind.

Both directories sit under `.forge/`, which the scaffolded project .gitignore already excludes (only disowned.json / hashes.json / friction.jsonl are negated back in) — side renders are per-developer state, never committed.

Stage-then-validate rollback journal for `forge generate`.

FRICTION cp-forge fr-40f7ec9bd9: `forge generate --force` on a clean clone rewrote Tier-1 files across the whole tree (CI workflows, skills, mocks, ORM, KCL), ran `go mod tidy`, and only THEN failed the final "go build (validate generated code)" step — exiting non-zero with the tree left mid-regen and recovery left to the user's `git checkout`. A generate run that fails its own validation must not leave the tree in a state the user has to hand-repair.

The fix is a write journal recorded at the SINGLE chokepoint every forge write flows through (WriteGeneratedFile / WriteScaffoldIfMissing / writeUnstampable, plus the in-place restamp and disown marker-strip). Before any of those mutate a path on disk, the journal captures the path's EXACT pre-run bytes (or records that it did not exist). On a post-write failure — most importantly the final `go build` validate — the pipeline calls RestoreRollback, which rewrites every journaled path back to its captured pre-run state (re-creating, overwriting, or deleting as needed). On success the pipeline calls CommitRollback, which simply drops the journal.

Scope — deliberately bounded to forge-WRITTEN files:

• The journal restores exactly the files forge's writers touched this run (Tier-1 codegen, scaffold-once "yours" files, comment-incapable outputs, restamps, disown marker strips). That is the "mid-regen broken tree" the friction names.
• It does NOT snapshot the whole working tree. External-tool churn (`buf generate` into gen/, `go mod tidy` rewriting go.mod/go.sum, `sqlc`, KCL render) is deterministic from the proto/config inputs and is NOT what leaves a half-regenerated Tier-1 tree; snapshotting it would manufacture spurious rollback diffs (e.g. a legitimately re-tidied go.sum) on every failed run.
• goimports/restamp rewrite files that are THEMSELVES already in the journal (forge wrote them earlier this run), so restoring the journal also undoes those in-place rewrites.

The journal is process-global (like the rest of this package's per-run state) and reset by BeginRollbackJournal at the head of each pipeline run. Non-pipeline callers (forge upgrade, project creation) never call Begin, so journaling stays OFF and their writes are recorded nowhere — they have their own recovery stories.

Self-certifying generated files: the embedded forge:hash marker.

Every Tier-1 (regenerated-every-run) file forge emits carries its own content hash inside the existing "Code generated by forge. DO NOT EDIT." header block:

// forge:hash=<sha256-hex>

The pristine check is purely local — recompute the hash over the file's bytes and compare with the embedded value. No global manifest is consulted, so the file's provenance travels WITH the file through git clones, parallel work lanes, cherry-picks, and partial commits (the failure class that killed .forge/checksums.json for Tier-1: kalshi fr-9a54388f0b — a committed manifest recorded from a WIP lane made a green tree unable to reproduce itself).

── Hash spec (deliberate, documented) ────────────────────────────────

BodyHash(content) = sha256 over content transformed as follows:

1. CRLF → LF. A git autocrlf checkout (or an editor that re-encodes line endings) must not turn a pristine render into "hand-edited". Forge itself always emits LF.
2. Every line containing "forge:hash=" is removed in its entirety, including its line terminator (the hash cannot cover itself). Forge emits exactly one marker line; removal is defensive against duplicates.
3. Trailing newlines are normalized to exactly one (a non-empty body always ends "\n"; an empty body stays empty). Editors and formatters disagree about final newlines; the count carries no content.

Anything else — including trailing whitespace inside lines — is hashed verbatim: it IS content.

Go files get one additional accommodation, OUTSIDE the hash spec: the Tier-1 writer canonical-formats .go renders (gofmt + goimports import grouping, module path as the local prefix) BEFORE stamping, and the verification sites re-hash mismatching .go bytes after the same canonical formatting before concluding "hand-edited" — formatter-only byte drift is not semantic drift. See goformat.go. Verify itself stays exact-byte; the tolerance lives at the path-aware call sites (ScanMarkers, WriteGeneratedFile).

── Marker line syntax per format ─────────────────────────────────────

//  forge:hash=…   .go .ts .tsx .js .jsx .mjs .cjs .proto .alloy .kt .rs
#   forge:hash=…   .yaml .yml .k .kcl .sh .bash .toml .tf .py .env
                   .example .gitignore .dockerignore Dockerfile
                   Makefile CODEOWNERS
--  forge:hash=…   .sql
<!-- forge:hash=… -->   .md .markdown .html .htm
/*  forge:hash=… */     .css

Comment-incapable formats (JSON et al.) are NOT stampable: callers route those few files through the scoped .forge/hashes.json fallback (see FileChecksums.Unstampable) — deliberately minimal so the exception cannot resurrect the global manifest.

── Marker placement ──────────────────────────────────────────────────

Stamp inserts the marker line, in order of preference:

1. immediately after the first line containing "Code generated by forge" within the first stampBannerScanLines lines (the standard banner — keeps prologue-sensitive files like "use client" TSX and frontmatter-led SKILL.md correct, since the banner already sits after those prologues);
2. for .md: after the closing --- of a leading YAML frontmatter block (Claude Code requires frontmatter at byte 0);
3. after a #! shebang line;
4. at the very top.