query reports a v4 index against a v3 reader and falls back forever without rebuilding

[MongLong0214]

Every commitlore_query call in this repository returns:

"diagnostics": [
  "the index is unavailable (index was built by schema v4, this build expects v3);
   answering with a full scan"
]

The answer is still correct — it fell back to scanning history — but the index that exists on disk is newer than the build that reads it, and the build never reconciles them.

Reproduction

• macOS, commitlore --version → 0.8.2
• Index present at .git/commitlore/index.db, 946176 bytes, written while 0.8.2 was the installed version
• Call commitlore_query with {"kind": "context", "path": "<any tracked path>"}
• The diagnostic appears on every call

Why the direction matters

A v3 reader meeting a v4 index means the writer is ahead of the reader in the same installation. Either two components of one release disagree about the schema version, or an index written by a newer build survived a downgrade with nothing to invalidate it. Both leave a stale artifact that is never rebuilt: the fallback works, so nothing ever forces the index to be regenerated, and it silently stays unusable.

Cost

The fallback is a full history scan. On this repository that is currently cheap, but the point of the index is that it does not stay cheap. A degradation that always succeeds is one nobody notices until the scan is the bottleneck.

What would resolve it

Either a version check that rebuilds the index when the schema does not match instead of only reporting it, or a stated compatibility rule that makes the mismatch impossible within one release. Reporting-and-falling-back leaves the artifact permanently stale.

What I could not determine

Which component wrote the v4 index — whether an earlier 0.8.x on this machine wrote v4 and 0.8.2 reads v3, or whether the CLI and the MCP server within 0.8.2 disagree. I did not attempt a rebuild, so whether deleting .git/commitlore/index.db regenerates a v3 index is unverified.

[MongLong0214]

Classified against the A–Z review (document_version 4.1.0, evidence main@b578ca9890) as a symptom of F-001 — runtime identity and upgrade convergence (P0), not as an independent defect.

The finding records this exact machine state:

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 dev-<hash>
Index writer        schema v4
MCP reader          schema v3

Every one of those is called commitlore, which is why the symptom reads as a bug in whichever surface the user happened to be looking at.

This issue stays open and its evidence stays as reported. It is not a duplicate to be closed — it is the reproduction that proves the convergence failure is real rather than theoretical, and it is what the fix has to satisfy. Work is tracked under F-001 with the completion condition:

CLI identity == hook identity == live MCP identity == plugin identity

matching on entrypoint and package root, not on a version string alone.

[MongLong0214]

Linked to #635 as a candidate of the same root cause — several execution surfaces running different builds — rather than as a duplicate. This issue's own acceptance criteria stay as written and are not absorbed by the umbrella.

Measured on one machine at one moment: four commitlore runtimes answering as MCP servers (0.6.0, v0.8.1, v0.8.2, dev-3b70a1be), two of them from package roots that no longer exist on disk, alongside a PATH CLI at 0.8.2 and a Claude plugin cache at 0.8.0.

If the convergence work closes this symptom, that will be shown against this issue's criteria before it is closed here.

[MongLong0214]

Some of this is now answerable from the code, and one part of it changed under this issue today.

The read path does try to rebuild

runQuery opens through ensureIndex (src/core/query.ts:372), which calls updateIndex without allowRebuild: false, and that defaults to true (src/core/index-db.ts:1421). On a health problem it resets the file and rebuilds. The never-rebuilding openCurrentIndex exists but has no caller in src/.

So "reporting and falling back with nothing that forces a rebuild" is not what the source says. The observed diagnostic on every call therefore needs a different explanation than a missing rebuild.

The likeliest one is the direction of the mismatch

The report is a v4 index read by a v3 build — the writer is newer than the reader. SCHEMA_VERSION on main is 4, so the reader was an older installation.

That is the multi-runtime shape F-001 was opened for, and it makes the persistence self-explanatory without any missing rebuild: if the older runtime does rebuild, it writes v3, and the newer runtime then rebuilds it back to v4. Each sees a mismatch, each rebuilds, and neither ever finds the other's. The diagnostic on every call is what that looks like from one side.

If that is what happened, the fallback is not the bug — rebuilding is, because rebuilding is what makes it a loop instead of a single degradation.

What I did not verify

I did not reproduce the ping-pong. Doing it needs two installations with different SCHEMA_VERSION values sharing one repository, which is exactly the field configuration and not something the suite currently builds. Until someone does, "the older runtime rebuilds it back down" is a reading of the code, not a measurement.

Related work that landed today

• Give every CommitLore surface one runtime identity #644 gives every surface one runtime identity and has doctor report divergence, so the configuration behind this becomes visible instead of being inferred from a diagnostic.
• Bind the cached signature verdict to the keyring that produced it #655 binds a different cached value — the signature status — to the environment that produced it, on the same healthProblem → rebuild path. Worth noting for whoever fixes this: that path is now load-bearing for two different staleness questions, and a change to when it rebuilds affects both.

Suggested next step

Decide the rule before touching the code: when a reader meets an index newer than itself, is the correct answer to rebuild it downward, or to leave it and scan? The second is a single bounded cost; the first is a loop whenever two runtimes share a repository. The issue's own "stated compatibility rule" option is the one that closes it without a fix that can oscillate.

[MongLong0214]

Measured against current main — the schema mismatch no longer reproduces

main at 63e48fa, built from source, queried in this repository:

runtime    version 0.8.2   build_id 9bad7d49d946
coverage   partial
fromIndex  true
diagnostics: ["the index is incomplete: the build stopped after its time budget
              with 961 commit(s) or note(s) unread …"]

The reported diagnostic — index was built by schema v4, this build expects v3;
answering with a full scan — is absent. What appears instead is the scan budget,
which is designed behaviour and now says so in coverage.

Not closing yet, and why

The SSOT's disposition is conditional: close as a duplicate of #660 if converged
v1 runtimes eliminate it, fix forward-only schema convergence if it still
reproduces. The first branch looks satisfied, but this measurement is one machine
— the same machine that produced the original report, now carrying a rebuilt
index.

That is a weak negative control. A defect about a reader older than the index
it reads cannot be ruled out by a reader that just rewrote that index.

The measurement that settles it is #660's own acceptance: refresh the
marketplace, update the plugin, start a new session, and read the runtime back.
If the schema diagnostic is absent there — where a genuinely older reader would
be doing the reading — the duplicate disposition is earned rather than assumed.

Recording this now so the next measurement is a confirmation rather than a
rediscovery. build_id makes it answerable: the reader's identity travels with
the answer, which is what was missing when this was filed.

[MongLong0214]

The measurement that decides this, and why it must run on an old reader

The SSOT disposition is conditional: duplicate of #660 if converged v1
runtimes eliminate it, fix forward-only schema convergence if it still
reproduces. So this closes on an observation, not on a judgement.

Why the obvious measurement does not count

Running current main here produces no schema diagnostic — only the scan
budget. That looks like the answer and is not one: this defect is about a
reader older than the index it reads, and a reader that has just rewritten
the index cannot demonstrate the absence of that. A negative control that cannot
fail is not evidence, which is the reason this issue is still open rather than
closed on my earlier measurement.

What to run, and where

From a session whose plugin cache holds a pre-1.0.0 generation — before
updating, not after — call:

commitlore_query  {"kind":"limits","path":"<any tracked path in this repository>"}

Read the whole diagnostics array.

diagnostics contains	disposition
index was built by schema v4, this build expects v3 … answering with a full scan	reproduces. Forward-only schema convergence is a GA blocker; fix and close completed
only budget-related text (the index is incomplete … time budget)	the old reader does not see it either — close as duplicate of #660, since what remains is which generation answers

The path must be one with records, in a repository whose index was built by a
current CLI. An empty answer decides nothing.

The order that matters

Run this before the plugin is updated for #660. Updating destroys the only
condition under which this is measurable — an old reader meeting a new index —
and it cannot be recreated afterwards without deliberately installing an old
generation.

That ordering is the whole reason this comment exists ahead of the release.

[MongLong0214]

Closing as a duplicate of #660 in cause. Measured rather than assumed.

The measurement

Run at 17:45 from a session whose MCP runtime is a pre-1.0.0 plugin generation — the only condition under which this is measurable, since it requires a reader older than the index it reads:

commitlore_query {"kind":"limits"}
scanned: 3 · records: 2 · history: "ready" · fromIndex: true
diagnostics: []

No index was built by schema v4, this build expects v3. Two records served with their trailers intact.

Scope of that measurement, stated

The old reader was reading that machine's repository index, not necessarily one written by a v4 writer. If a v4 index exists only elsewhere, this run did not exercise the pairing. The criterion agreed in advance was measure it from the old reader's session, and under those conditions the schema mismatch did not appear — so the disposition follows the criterion rather than a preference.

Why duplicate rather than fixed

Nothing was changed to make this stop reproducing. What remains is the question underneath it: which generation is answering. That is #660, whose acceptance is now written as a checkable condition — a session started after installing reports the installed release, compared through runtime.build_id.

Reopen if the schema diagnostic appears again with a build_id recorded beside it. That pairing is what v1.0.0 added and what makes a repeat report actionable instead of a second round of this one.