Skip to content

Give every CommitLore surface one runtime identity - #644

Merged
MongLong0214 merged 6 commits into
mainfrom
fix-f001-runtime-identity
Aug 14, 2026
Merged

Give every CommitLore surface one runtime identity#644
MongLong0214 merged 6 commits into
mainfrom
fix-f001-runtime-identity

Conversation

@MongLong0214

Copy link
Copy Markdown
Owner

Summary

Closes F-001 (P0). Addresses the convergence half of #633, #634 and #635.

Every execution surface answers to the name commitlore, and nothing established that they were the same program. Measured on one machine:

PATH CLI            0.8.2
Git hook pin        0.8.0
Claude plugin cache 0.8.0
Codex plugin cache  0.8.2
MCP asset lookup    0.6.0 or a dev-<hash> root that no longer exists
Index writer        schema v4
MCP reader          schema v3

A shared runtime identity — version, entrypoint, package root, index schema — is now produced by one function, reported by each surface, and compared by doctor in a single report.

RED, verified independently against unmodified main

The delegated report offered a failing test run as its RED, but those failures were module-resolution errors: the tests could not load a file that does not exist on main yet. That proves nothing about the defect, so the RED was re-established by hand.

On main, a repository whose hook pin names an older install:

fail  hook runtime — the hook exited 1 under the restricted PATH — cause unclear:
      commitlore: cannot find the CLI this hook was installed with.

cause unclear. The version mismatch is the cause, and the user is not told.

On this branch, same repository, same state:

warn  runtime identity — hook identity differs from CLI:
      hook v0.8.0; entry …/v0.8.0/dist/commitlore.mjs; root …/v0.8.0; schema v4
      CLI  v0.8.2; entry …/wt-f001/dist/commitlore.mjs; root …/wt-f001; schema v4
      fix: commitlore hooks install

A false positive, found and removed

The first implementation compared entrypoint filenames, so it warned on a correct installation: one install ships both dist/commitlore.mjs and dist/cli.js, and a hook recorded against one while the CLI runs from the other is the same install reached two ways.

A check that fires on a healthy machine stops being believed, which would have cost more than the defect it reports. Convergence is now decided on the installation — package root, version, index schema — with the entrypoint kept in the report because it is what a person needs when the roots genuinely differ.

Verified by hand in both directions:

scenario result
two entrypoints inside one root ok
a genuinely older install warn, naming both roots, with the fix line

Scope

Runtime identity only. Capture asset readiness is F-002 (#641) and trust-grade equivalence across routes is F-003; neither is touched here. No daemon, no hosted service, no new database — the existing shared core, doctor registry and hooks carry it.

Test plan

  • runtime-identity, doctor, hooks, index-db: 123 cases
  • doctor and init together: 96 cases
  • init: 24 · doctor: 72
  • npx tsc --noEmit
  • Canonical build, manifest refreshed, npm run artifact:verify
  • Clean-install / upgrade / rollback walk with identity agreeing after each

The pinned doctor check list and count moved 16 → 17 for the added check, which is what those assertions exist to make visible.

CommitLore surfaces shared a command name while selecting independent entrypoints
and package roots, so an upgrade could leave hooks, plugins, MCP, and index
readers on incompatible programs. Record and compare the full runtime identity
and make doctor prescribe surface-specific convergence.

Ruled-out: version-only comparison | equal version strings still allow different entrypoints and package roots
Blast: system
Undo: easy
Certainty: firm
Record-Id: r-runtime001
Provenance: authored
Verified: npx tsc --noEmit; runtime-identity, doctor, hooks, init, index-db, installer-hosts, mcp, codex-plugin, and doctor-snapshot Vitest suites; linux/amd64 npm ci and npm run build; dist 280 files
Two shipped entrypoints under one package root are the same runtime. A warning
on a correct installation stops the identity check being believed when it
matters.

This narrows the finding faithfully: it targets surfaces running different
installs; two files inside one install are not different installs.

Ruled-out: filename equality | two shipped entrypoints of one install are one runtime
Blast: module
Undo: easy
Certainty: firm
Record-Id: r-oneinstall001
Provenance: authored
Verified: npx tsc --noEmit; npx vitest run test/init.test.ts; npx vitest run test/doctor.test.ts; npx vitest run test/runtime-identity.test.ts test/hooks.test.ts test/index-db.test.ts; npx vitest run test/doctor.test.ts test/init.test.ts; docker linux/amd64 npm ci, build, artifact:manifest; npm ci; npm run artifact:verify
…01-runtime-identity

# Conflicts:
#	dist/commitlore.mjs
#	dist/mcp/server.js
#	dist/mcp/server.js.map
#	installer/canonical-artifact.json
Provenance: authored
Record-Id: r-canonf001b
Verified: docker linux/amd64 build and artifact:manifest; artifact:verify reports e9d85e41; 280 files in dist; 101 cases across doctor, init and runtime-identity
@github-actions

github-actions Bot commented Aug 14, 2026

Copy link
Copy Markdown

CommitLore — record lint

Trailers: clean — 6 commits in origin/main..5ce45604d08151ce71ad08c8ba47d62ffd12e5f4
Active constraints: not read — commitlore: git log --follow accepts exactly one pathspec, so renames are not followed for 44 paths; query one path at a time to follow its rename chain (44 changed paths)

Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR.

@MongLong0214
MongLong0214 merged commit 31cf0d1 into main Aug 14, 2026
12 checks passed
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