canonical-artifact.json is a derived file under version control, and it serialises every branch that touches dist

[MongLong0214]

installer/canonical-artifact.json records checksums over all of dist/. Because dist/ is tracked (274 files) and every branch rebuilds it, any two branches that touch dist conflict on this file by construction — not on the source change, on the manifest.

The cost is not linear. Draining N concurrent dist-touching branches forces N(N-1)/2 rebuild-and-recommit cycles, because each merge invalidates the manifest of every branch still open. With four branches that is six forced canonical rebuilds that carry no review value.

What the manifest asserts, and who already proves it

Its fields are format, builder, runtimeAssets, source, artifact. builder, format and runtimeAssets are constants read from scripts/canonical-artifact-contract.mjs — source. source.sha256 digests the declared inputs, and artifact digests the built bundle. Both are computed from the tree. Every field is derivable from the commit it sits in.

Meanwhile .github/workflows/ci.yml already proves the property that matters, without reference to the manifest:

npm run build:canonical
find dist -type f -print0 | sort -z | xargs -0 sha256sum > "$first"
npm run build:canonical
find dist -type f -print0 | sort -z | xargs -0 sha256sum > "$second"
cmp "$first" "$second" || exit 1
git diff --exit-code -- dist/ installer/canonical-artifact.json

The canonical builder runs twice and must produce identical bytes, then the committed dist/ must equal that rebuild. That is the integrity claim, and it needs no manifest.

Why the committed copy cannot catch what it appears to catch

artifact:verify compares the committed manifest against a manifest recomputed from the tree. But the manifest is written by npm run artifact:manifest from whatever is in dist/ — the same step that produced dist, in the same command. It therefore cannot detect a bad dist; it can only ever confirm itself.

The one failure it does catch is rebuilt dist, forgot to refresh the manifest — a workflow slip that exists only because the manifest is committed. The check is paying for its own existence.

Where the manifest genuinely earns its place

At the tag. release.yml checks out the release commit, rebuilds canonically, and verifies — and a published statement of which builder image, which platform, which source inputs produced the shipped bundle is real supply-chain value a consumer can read. That value is needed at release, which is exactly where it is not conflicting with anything.

Nothing reads it at install time: install.sh and install.ps1 do not reference it.

Proposed shape

• keep the canonical rebuild and git diff --exit-code -- dist/ on every branch — that is the real check and it is manifest-free
• generate the manifest at release from the tag, and publish it as a release asset rather than tracking it
• branches then never touch the file, and the conflict class disappears

Before acting, one thing to check

The grep above covers this repository only. If any downstream consumer — a marketplace, a mirror, an external verifier — reads installer/canonical-artifact.json at a path inside a tag, then it must remain a tracked file at tags and only the per-branch refresh should move. That question decides between the two shapes and I could not answer it from inside this repo.

Ownership

I designed this in #605 and got it wrong. I put a derived artifact under version control, which is the same shape ADR-0003 rules against for the SQLite index: derived state is a cache, not a source of truth. The provenance goal was right; binding it to every feature branch commit was not.

Not urgent — F-001 is the open P0 and this comes after it.

[MongLong0214]

A live instance, measured on #636 while it waits its turn in the merge order.

$ git merge-tree --write-tree --name-only origin/main origin/fix-572-mcp-identity
dist/commitlore.mjs
installer/canonical-artifact.json

CONFLICT (content): Merge conflict in dist/commitlore.mjs
CONFLICT (content): Merge conflict in installer/canonical-artifact.json
Auto-merging test/doctor.test.ts

Every conflict is a build output. test/doctor.test.ts — the one source file #636 shares with main's recent history — merges cleanly. There is no semantic disagreement between #636 and main at all.

The PR nevertheless shows DIRTY, which is why it has never had CI run on it: GitHub will not schedule checks for an unmergeable branch. So the artifact tax is not only costing rebuild cycles, it is withholding the first CI signal from a branch that has no actual conflict. That failure mode was not visible when the tax looked like a serialisation cost alone.

Under the proposed shape — canonical rebuild plus git diff --exit-code -- dist/ on branches, manifest generated at release — this branch would be mergeable today.

[MongLong0214]

Measured cost, 2026-08-14

This issue reads as a theoretical concern. It was not one today, and the record below is what a future prioritisation should weigh rather than the argument in the original post.

Every rebuild forced, and by what

branch	forced by	conflicting files	source conflicts
#636	#641 merge	dist/commitlore.mjs, installer/canonical-artifact.json	0
#636	#644 + #651 + #654 + #655 merges	same two	0
#636	#656 merge	same two	0
#641	#644 merge	dist ×3, manifest	1 (genuine, src/mcp/server.ts)
#656	#655 merge	same two	0
#655	#654 merge	— (rebase only)	0

Seven forced canonical rebuilds in one day. Six of them had zero source conflict — the branches did not disagree about anything a reviewer would care about.

Each cycle is a Docker canonical rebuild plus a full CI round, so roughly 30 minutes of wall clock, and it repeats every time another PR merges while one is in flight.

The part that is worse than the arithmetic

GitHub does not schedule checks for an unmergeable branch. #636 spent part of today showing no checks reported while it was DIRTY for build-output reasons alone, so the tax was not only costing rebuilds — it was withholding the CI signal from a branch that had no actual conflict, including the run that was supposed to adjudicate a Windows failure.

Why it did not compound further

Only because the queue drained to one PR. With four in flight the same day, draining them costs N(N−1)/2 forced rebuilds by construction, and nothing in the current shape prevents that.

Direction (not for today)

While dist/ and installer/canonical-artifact.json are committed per branch, this does not go away. The options are to generate the manifest at release, regenerate it on merge, or stop tracking dist/ — each is a contract change, which is what this issue is for.

[MongLong0214]

A second failure mode, found today

The tax was recorded here as forced rebuilds and withheld CI. There is a third shape, and it is worse because it passes locally.

ERROR: canonical artifact verification failed:
  - source checksum does not match this checkout
  - dist file list or a dist file checksum does not match the canonical manifest

CI refused #664's artifact. The rebuild had run — on a working tree that also carried uncommitted work for a different change. So dist held code the branch's committed source did not contain, and npm run artifact:verify passed locally because both sides of the comparison read the same contaminated tree.

Removing the unrelated edits and rebuilding returned the aggregate to the value it had before they entered the worktree, which is what confirmed it.

Why this belongs to this issue

The manifest binds dist to committed source, while a local build reads the working tree. Any uncommitted edit anywhere under src/ therefore makes the local verification meaningless — it will agree with itself and disagree with CI. That is a property of committing a derived artifact, not of any one branch.

It also compounds the original complaint: the more often a branch is forced to rebuild, the more often somebody rebuilds while something else is in the tree.

Running count for the day

Twelve forced canonical rebuilds, of which eleven had zero source conflict, plus this one — a rebuild that ran correctly and still produced a wrong artifact. The direction each of the three proposed shapes points is unchanged; this adds a reason that generating the manifest at release rather than per branch also removes a class of error nobody can see locally.