knodin 0.10.2 → 0.10.4

package/dist/src/engine/text-matches.js

@@ -0,0 +1,309 @@
+/**
+ * Exact-text search with per-match classification (EASFDC-8496).
+ *
+ * The point of this module is the one thing `rg` cannot do: say *what a match
+ * is*. A product-name rename spans UI strings, prose and identifiers, and the
+ * reported case that motivated this had visible `NOVA` labels needing change
+ * while `NOVA-CANARY-…` was a deliberate security token that must not. A flat
+ * text search returns both and leaves a human to separate them by eye across
+ * however many hits a large repository yields.
+ *
+ * knodin can do better only because it already parses these files. For a file
+ * with a grammar, a match resolves to the smallest syntax node containing it,
+ * and the parser's own node type is the evidence. For a file without one, the
+ * strongest honest claim is about the file, not the match.
+ *
+ * That gap is not hidden. Every match carries the `basis` it was classified on,
+ * so a reviewer can see which answers came from a parse tree and which are an
+ * inference from a file extension. Classification will sometimes be wrong; it
+ * is offered as evidence a human is reviewing, never as a decision already
+ * taken on their behalf.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { walkRepoFiles } from "./file-walker.js";
+const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
+/** Upper bound on `TextMatch.enclosingText`, so one row cannot flood a preview. */
+const ENCLOSING_TEXT_LIMIT = 120;
+function isWordCharacter(value) {
+    return value !== undefined && WORD_CHARACTER.test(value);
+}
+/**
+ * Map a grammar's node type onto a coarse class.
+ *
+ * Deliberately substring-based rather than an exhaustive per-language table.
+ * Across the grammars this project loads, the same concept appears as `string`,
+ * `string_literal`, `template_string`, `interpreted_string_literal`, `comment`,
+ * `line_comment`, `identifier`, `property_identifier` and more, and any fixed
+ * list would silently degrade to "unclassified" the first time a grammar is
+ * updated or added. An unrecognised type keeps `unclassified` while the real
+ * node type still travels on the match, so nothing is lost by guessing less.
+ */
+export function classifyNodeType(nodeType) {
+    const normalized = nodeType.toLowerCase();
+    if (normalized.includes("comment"))
+        return "comment";
+    if (normalized.includes("string") || normalized.includes("char_literal"))
+        return "string-literal";
+    if (normalized.includes("identifier") || normalized === "word")
+        return "identifier";
+    return "unclassified";
+}
+/**
+ * Extensions whose contents are prose rather than code.
+ *
+ * A file-type claim, and labelled as one: `basis: "file-type"`. Prose is the
+ * common case for the renames this feature exists to serve, so saying nothing
+ * at all about a markdown file would leave most matches unclassified.
+ */
+const PROSE_EXTENSIONS = new Set([".md", ".mdx", ".markdown", ".txt", ".rst", ".adoc", ".org"]);
+function extensionOf(file) {
+    const base = file.slice(file.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+export function classifyByFileType(file) {
+    return PROSE_EXTENSIONS.has(extensionOf(file)) ? "prose" : "unclassified";
+}
+/** Every occurrence of `term`, non-overlapping, left to right. */
+function findOccurrences(content, term, caseSensitive) {
+    if (term.length === 0)
+        return [];
+    const haystack = caseSensitive ? content : content.toLowerCase();
+    const needle = caseSensitive ? term : term.toLowerCase();
+    const found = [];
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            break;
+        found.push({
+            startIndex: at,
+            endIndex: at + term.length,
+            // Sliced from the ORIGINAL content, so the reported text carries the
+            // case actually on disk rather than the case that was searched for.
+            matchedText: content.slice(at, at + term.length),
+        });
+        from = at + term.length;
+    }
+    return found;
+}
+/** Byte-free line/column lookup, built once per file rather than per match. */
+function lineStarts(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i++)
+        if (content[i] === "\n")
+            starts.push(i + 1);
+    return starts;
+}
+function lineIndexFor(starts, index) {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (starts[mid] <= index)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low;
+}
+/**
+ * A tree-sitter abort is permanent and process-wide, not a per-file failure.
+ *
+ * Mirrors the engine's own guard (EASFDC-8445): swallowing one of these turns a
+ * dead WASM module into "this file has no matches" for every remaining file,
+ * which is precisely the silent-undercount this feature must not produce.
+ */
+function isWasmAbort(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.name === "ExitStatus");
+}
+/**
+ * Classify each match in one file against its parse tree.
+ *
+ * Parses once for the whole file, not once per match. Returns null when the
+ * file has no grammar, leaving the caller to fall back to a file-type claim.
+ */
+function classifyAgainstTree(parser, content, raw) {
+    const tree = parser.parse(content);
+    if (!tree)
+        return null;
+    try {
+        return raw.map((match) => {
+            // `endIndex - 1` because the range is inclusive: passing the exclusive
+            // end can select the following sibling for a match ending at a
+            // boundary, which mislabels exactly the tokens that sit flush against
+            // punctuation — quotes, most of all.
+            const node = tree.rootNode.descendantForIndex(match.startIndex, Math.max(match.startIndex, match.endIndex - 1));
+            const nodeType = node?.type ?? "";
+            const text = node?.text ?? "";
+            return {
+                classification: classifyNodeType(nodeType),
+                nodeType,
+                // Bounded: a match inside a large node (a whole template literal,
+                // a long comment) must not turn one row of a preview into a page.
+                enclosingText: text.length > ENCLOSING_TEXT_LIMIT ? `${text.slice(0, ENCLOSING_TEXT_LIMIT)}…` : text,
+            };
+        });
+    }
+    finally {
+        tree.delete();
+    }
+}
+/**
+ * Search already-read files for an exact term and classify every hit.
+ *
+ * `loadLanguage` is injected rather than imported so this module can be tested
+ * without standing up the engine's grammar loader, and so a caller that already
+ * knows a file has no grammar can skip the lookup.
+ *
+ * The parser is created lazily and freed in a `finally`: this walks the same
+ * ground as the leak that left 174,205 files silently unparsed, and a search
+ * over a large repository touches enough files to reproduce it exactly.
+ */
+export async function searchFiles(files, term, loadLanguage, newParser, options = {}) {
+    const caseSensitive = options.caseSensitive ?? true;
+    const matches = [];
+    const uncovered = [];
+    let filesSearched = 0;
+    for (const { file, content } of files) {
+        const raw = findOccurrences(content, term, caseSensitive);
+        filesSearched++;
+        if (raw.length === 0)
+            continue;
+        let classified = null;
+        let language = null;
+        try {
+            language = await loadLanguage(file);
+        }
+        catch {
+            // A grammar that will not load costs classification, not the match.
+            language = null;
+        }
+        if (language) {
+            const parser = newParser();
+            try {
+                parser.setLanguage(language);
+                classified = classifyAgainstTree(parser, content, raw);
+            }
+            catch (error) {
+                if (isWasmAbort(error))
+                    throw error;
+                // Parsing failed on this file only. The matches are still real and
+                // still reported — just without node evidence.
+                classified = null;
+                uncovered.push({
+                    file,
+                    reason: `matched but could not be parsed for classification: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+            finally {
+                try {
+                    parser.delete();
+                }
+                catch {
+                    /* a dead module has nothing to reclaim */
+                }
+            }
+        }
+        const starts = lineStarts(content);
+        raw.forEach((match, position) => {
+            const lineIndex = lineIndexFor(starts, match.startIndex);
+            const lineStart = starts[lineIndex];
+            const nextStart = starts[lineIndex + 1] ?? content.length + 1;
+            const node = classified?.[position] ?? null;
+            matches.push({
+                file,
+                line: lineIndex + 1,
+                column: match.startIndex - lineStart + 1,
+                startIndex: match.startIndex,
+                endIndex: match.endIndex,
+                lineText: content.slice(lineStart, Math.max(lineStart, nextStart - 1)).replace(/\r$/, ""),
+                matchedText: match.matchedText,
+                caseMatchesQuery: match.matchedText === term,
+                withinLargerWord: isWordCharacter(content[match.startIndex - 1]) ||
+                    isWordCharacter(content[match.endIndex]),
+                classification: node ? node.classification : classifyByFileType(file),
+                basis: node ? "parse-node" : language ? "none" : "file-type",
+                nodeType: node ? node.nodeType : null,
+                enclosingText: node ? node.enclosingText : null,
+            });
+        });
+    }
+    return { matches, uncovered, filesSearched, searched: true };
+}
+/**
+ * Read a file for searching, or say why it could not be.
+ *
+ * Binary detection is a NUL-byte sniff over the head of the file rather than an
+ * extension list: the extensions that matter here are open-ended, and a
+ * misjudged binary read produces garbage matches rather than an honest skip.
+ */
+function readSearchable(absolute) {
+    let buffer;
+    try {
+        buffer = fs.readFileSync(absolute);
+    }
+    catch (error) {
+        return { reason: `unreadable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (buffer.subarray(0, 8192).includes(0))
+        return { reason: "binary" };
+    return { content: buffer.toString("utf8") };
+}
+/**
+ * Exact-text search across a whole repository (R1).
+ *
+ * Enumerates with the indexer's prune rules but NOT its source-extension
+ * filter. That difference is the requirement: a product-name rename lives in
+ * markdown, UI strings and changelogs, so restricting the search to files that
+ * yield symbols would answer a different question than the one being asked.
+ *
+ * Every file that could not be searched is returned in `uncovered` (R5). A
+ * rename that silently skipped files would leave a half-renamed repository
+ * looking finished, which is the worst available outcome for this operation.
+ */
+export async function searchRepoText(repoPath, term, loadLanguage, newParser, options = {}) {
+    let candidates;
+    try {
+        // Checked explicitly because `walkRepoFiles` swallows a missing directory
+        // and returns an empty list. Without this, searching a path that does not
+        // exist reports a completed search over zero files — "the term appears
+        // nowhere", which is the precise failure AC5 exists to make impossible.
+        const stats = fs.statSync(repoPath);
+        if (!stats.isDirectory())
+            throw new Error("not a directory");
+        candidates = walkRepoFiles(repoPath);
+    }
+    catch (error) {
+        // Enumeration failed, so nothing was searched. Reported as `searched:
+        // false` rather than as an empty match list, which would read as "the
+        // term appears nowhere" (AC5).
+        return {
+            matches: [],
+            uncovered: [
+                {
+                    file: repoPath,
+                    reason: `could not enumerate: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            filesSearched: 0,
+            searched: false,
+        };
+    }
+    const readable = [];
+    const uncovered = [];
+    for (const file of candidates) {
+        const outcome = readSearchable(path.join(repoPath, file));
+        if ("reason" in outcome)
+            uncovered.push({ file, reason: outcome.reason });
+        else
+            readable.push({ file, content: outcome.content });
+    }
+    const result = await searchFiles(readable, term, loadLanguage, newParser, options);
+    // Files skipped at read time and files that failed classification are both
+    // gaps in the same claim, so they are reported through one list.
+    return { ...result, uncovered: [...uncovered, ...result.uncovered] };
+}

package/dist/src/init-progress.js

@@ -20,7 +20,7 @@ function formatDuration(seconds) {
         return `${Math.ceil(seconds)}s`;
     return `${Math.floor(seconds / 60)}m ${Math.ceil(seconds % 60)}s`;
 }
-export function formatProgress(event, ratePerSecond, operation = "init") {
+export function formatProgress(event, ratePerSecond, operation = "init", bytesPerSecond) {
     const model = event.modelFile ? ` (${event.modelFile})` : "";
     const total = event.phaseTotal;
     if (total === undefined)
@@ -29,13 +29,34 @@ export function formatProgress(event, ratePerSecond, operation = "init") {
         ? `${formatBytes(event.phaseCompleted)} / ${formatBytes(total)}`
         : `${formatCount(event.phaseCompleted)} / ${formatCount(total)}`;
     const percent = total > 0 ? ` (${Math.floor((event.phaseCompleted / total) * 100)}%)` : "";
-    const eta = ratePerSecond && total > event.phaseCompleted
-        ? ` • ~${formatDuration((total - event.phaseCompleted) / ratePerSecond)} remaining`
+    // Both counters, because they answer different questions and on a real
+    // repository they disagree. Measured on a 902,960-file Salesforce checkout:
+    // 435 files over 1 MB hold 78% of the bytes, so "71% of files" was about a
+    // quarter of the work. Showing only files is what made a working index look
+    // wedged for twenty minutes.
+    const bytesTotal = event.phaseBytesTotal;
+    const bytesDone = event.phaseBytesCompleted;
+    const bytes = bytesTotal !== undefined && bytesDone !== undefined && bytesTotal > 0
+        ? ` • ${formatBytes(bytesDone)} / ${formatBytes(bytesTotal)} (${Math.floor((bytesDone / bytesTotal) * 100)}%)`
         : "";
+    // Prefer the byte rate: it tracks the shape of the work rather than the
+    // length of the list. Falls back to the item rate when the phase carries no
+    // byte size, which keeps model download and embedding phases as they were.
+    const byteEta = bytesPerSecond && bytesTotal !== undefined && bytesDone !== undefined && bytesTotal > bytesDone
+        ? (bytesTotal - bytesDone) / bytesPerSecond
+        : undefined;
+    const itemEta = ratePerSecond && total > event.phaseCompleted
+        ? (total - event.phaseCompleted) / ratePerSecond
+        : undefined;
+    const remaining = byteEta ?? itemEta;
+    // Labelled an estimate because it is one, and because a confidently wrong
+    // number is worse than an obviously approximate one — this workload spans
+    // three orders of magnitude in cost per file.
+    const eta = remaining === undefined ? "" : ` • ~${formatDuration(remaining)} remaining (est.)`;
     const rate = ratePerSecond && event.phase !== "embedding-model"
         ? ` • ${ratePerSecond.toFixed(ratePerSecond >= 10 ? 0 : 1)}/s`
         : "";
-    return `[${operation}:${event.phase}] ${counter}${percent} ${event.message}${model}${rate}${eta}`;
+    return `[${operation}:${event.phase}] ${counter}${percent}${bytes} ${event.message}${model}${rate}${eta}`;
 }
 /**
  * Human-only init feedback. It writes to stderr, leaving stdout stable for the
@@ -61,6 +82,7 @@ export function createInitProgressRenderer(options) {
     let lastPercentBucket = -1;
     let phaseStartedElapsedMs = 0;
     let phaseStartedCompleted = 0;
+    let phaseStartedBytes = 0;
     const scheduleHeartbeat = () => {
         if (heartbeat !== undefined || stopped)
             return;
@@ -126,17 +148,26 @@ export function createInitProgressRenderer(options) {
             if (phaseChanged) {
                 phaseStartedElapsedMs = event.elapsedMs;
                 phaseStartedCompleted = event.phaseCompleted;
+                phaseStartedBytes = event.phaseBytesCompleted ?? 0;
             }
             const phaseElapsedSeconds = Math.max(0, event.elapsedMs - phaseStartedElapsedMs) / 1_000;
             const ratePerSecond = phaseElapsedSeconds > 0 && event.phaseCompleted > phaseStartedCompleted
                 ? (event.phaseCompleted - phaseStartedCompleted) / phaseElapsedSeconds
                 : undefined;
+            // Measured from the start of the phase, not from process start, so the
+            // cold-start window (wasm init, grammar load, embedder setup) does not
+            // drag the estimate. Extrapolating from that window overstated a real
+            // run by roughly ten times.
+            const bytesDone = event.phaseBytesCompleted;
+            const bytesPerSecond = phaseElapsedSeconds > 0 && bytesDone !== undefined && bytesDone > phaseStartedBytes
+                ? (bytesDone - phaseStartedBytes) / phaseElapsedSeconds
+                : undefined;
             const completed = event.phaseTotal !== undefined && event.phaseCompleted >= event.phaseTotal;
             if (tty && !phaseChanged && !completed && now() - lastWriteAt < TTY_THROTTLE_MS)
                 return;
             if (!tty && !phaseChanged && bucket <= lastPercentBucket && !completed)
                 return;
-            write(formatProgress(event, ratePerSecond, operation));
+            write(formatProgress(event, ratePerSecond, operation, bytesPerSecond));
             lastPhase = event.phase;
             lastPercentBucket = Math.max(lastPercentBucket, bucket);
         },

package/dist/src/init.js

@@ -7,6 +7,7 @@ import { compareBytes } from "./compare.js";
 import { isIndexableSourcePath } from "./engine/source-policy.js";
 import { lookupMirror } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
+import { stableInterpreterPath } from "./node-runtime.js";
 import { acquireRepairLease, LIFECYCLE_LEASE_TOKEN_ENV } from "./repair-lease.js";
 import { installKnodinSkills, removeKnodinSkills } from "./skill-management.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
@@ -426,7 +427,13 @@ function backgroundScript(command) {
     // silently switch which runtime executes, which is its own bug.
     const [interpreter, ...rest] = command;
     const invocation = ['"$KNODIN_NODE"', ...rest.map(shellQuote)].join(" ");
-    const preferred = shellQuote(interpreter ?? process.execPath);
+    // Recorded through `stableInterpreterPath` so a Homebrew interpreter is
+    // written as its version-stable `opt` path rather than the versioned Cellar
+    // path Node reports. Without it the preferred path is guaranteed to break on
+    // the next `brew upgrade` and every hook leans on the fallback below to stay
+    // alive — which works, but means the recorded path is wrong from the moment
+    // it is written (EASFDC-8497).
+    const preferred = shellQuote(stableInterpreterPath(interpreter ?? process.execPath));
     return String.raw `#!/bin/sh
 # knodin packaged background refresh. Generated by knodin init.
 set -u

package/dist/src/lifecycle-health.js

@@ -136,6 +136,39 @@ function inspectManagedHooks(repo, hooksDirectory) {
         routing: hookRouting(wrappers, managerNative),
     };
 }
+/**
+ * The interpreter a generated hook records, when that interpreter is gone.
+ *
+ * Existence and the executable bit say the script is runnable; they say nothing
+ * about whether the runtime on its first line still exists. A hook written
+ * against a Homebrew Cellar path stops working at the next `brew upgrade` and
+ * fails with exit 127 in the background, where the only trace is a log file
+ * (EASFDC-8497). Health then reported "degraded" without ever naming the cause,
+ * and `repair` could not help because the fault is in the hook's contents, not
+ * in graph state.
+ *
+ * Returns null when the hook is fine, unreadable, or shaped differently than
+ * expected — an unparseable hook is not evidence of a missing interpreter, and
+ * guessing here would invent a failure rather than report one.
+ */
+function recordedInterpreterIfMissing(backgroundScriptPath) {
+    let contents;
+    try {
+        contents = fs.readFileSync(backgroundScriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const recorded = /^KNODIN_NODE='([^']+)'/m.exec(contents)?.[1];
+    if (!recorded)
+        return null;
+    if (fs.existsSync(recorded))
+        return null;
+    // A working `node` on PATH means the hook's own fallback will carry it, so
+    // this is not currently breaking anything — but the recorded path is still
+    // wrong and the next environment without that fallback breaks silently.
+    return recorded;
+}
 function readRefreshFailure(repo) {
     const failurePath = path.join(repo, ".knodin", "hooks", HOOK_FAILURE_FILE);
     if (!fs.existsSync(failurePath))
@@ -218,6 +251,9 @@ export function inspectLifecycleHealth(repoPath) {
     const issues = missingHooks.map((hook) => `${hook} no longer routes through knodin's active Git hook path`);
     if (!backgroundReady)
         issues.push("background indexer is missing or not executable");
+    const staleInterpreter = backgroundReady ? recordedInterpreterIfMissing(background) : null;
+    if (staleInterpreter)
+        issues.push(`background indexer records a Node interpreter that no longer exists (${staleInterpreter}); run \`knodin init\` to rewrite the hook`);
     const lastError = readRefreshFailure(repo);
     if (lastError)
         issues.push(`${lastError} See .knodin/indexer.log for details`);

package/dist/src/node-runtime.js

@@ -155,3 +155,36 @@ export function handoffCurrentProcessToSupportedNodeRuntime() {
         listDirectories,
     });
 }
+/**
+ * Rewrite a Homebrew Cellar path to the version-stable `opt` path it came from.
+ *
+ * `process.execPath` is symlink-resolved by Node, so invoking a stable entry
+ * point does not preserve it:
+ *
+ *   $ /opt/homebrew/opt/node/bin/node -p "process.execPath"
+ *   /opt/homebrew/Cellar/node/26.7.0/bin/node
+ *
+ * Both stable Homebrew entry points report the versioned path, which means the
+ * caller cannot avoid this by launching differently — by the time knodin can
+ * read its own interpreter, the durable path is already gone. Anything that
+ * records `execPath` for later therefore records a path Homebrew deletes on the
+ * next `brew upgrade`, and a managed hook written against it dies with exit 127
+ * (EASFDC-8497, and the 174k-file class of failure before it: a background
+ * process failing where nobody is looking).
+ *
+ * `<prefix>/opt/<formula>` is the symlink Homebrew repoints on upgrade, so the
+ * path survives by construction rather than by a runtime fallback. Derived from
+ * the matched prefix rather than hardcoding `/opt/homebrew`, so Intel
+ * (`/usr/local`) and Linuxbrew layouts work unchanged.
+ *
+ * Returns the input untouched when it is not a Cellar path, or when the `opt`
+ * path does not exist — a rewrite is only safe if the destination is real.
+ */
+export function stableInterpreterPath(executable, exists = (candidate) => fs.existsSync(candidate)) {
+    const match = /^(.*)\/Cellar\/([^/]+)\/[^/]+\/(.+)$/.exec(executable);
+    if (!match)
+        return executable;
+    const [, prefix, formula, remainder] = match;
+    const candidate = `${prefix}/opt/${formula}/${remainder}`;
+    return exists(candidate) ? candidate : executable;
+}

package/dist/src/release-compatibility.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseVersion } from "./update-policy.js";
+/**
+ * Classify a version transition.
+ *
+ * Returns `null` when the transition is not a forward release — equal versions,
+ * a downgrade, or an unparseable input — so callers distinguish "cannot say"
+ * from a confident answer. Returning a default here would put a guess into
+ * published metadata, which is the failure this whole change removes.
+ *
+ * ## The 0.x rule, stated rather than inherited
+ *
+ * Pre-1.0, the MINOR is the breaking axis: `0.10.x` to `0.11.0` breaks, while
+ * `0.10.1` to `0.10.2` does not. This is conventional SemVer for major-zero and
+ * it is also what this project's own history shows — `0.9.0` and `0.10.0` were
+ * genuinely breaking and were labelled so, while `0.10.1` and `0.10.2` were
+ * bugfix releases published under the same label because the field was a
+ * constant.
+ *
+ * `policyAllows` in update-policy.ts deliberately does NOT encode this: it
+ * treats major-zero like any other major, which is correct for deciding whether
+ * an automatic update is safe but would classify every 0.x release as
+ * non-breaking here. Reusing it would be the obvious mistake.
+ */
+export function classifyCompatibility(previous, next) {
+    const from = parseVersion(previous);
+    const to = parseVersion(next);
+    if (!from || !to)
+        return null;
+    const [fromMajor, fromMinor, fromPatch] = from.core;
+    const [toMajor, toMinor, toPatch] = to.core;
+    // Not a forward release. A caller asking about a downgrade or a no-op has a
+    // different problem than a mislabelled release.
+    if (toMajor < fromMajor)
+        return null;
+    if (toMajor === fromMajor && toMinor < fromMinor)
+        return null;
+    if (toMajor === fromMajor && toMinor === fromMinor && toPatch <= fromPatch)
+        return null;
+    if (toMajor !== fromMajor)
+        return "breaking";
+    // Major-zero: the minor carries what the major carries after 1.0.
+    if (toMajor === 0)
+        return toMinor !== fromMinor ? "breaking" : "compatible";
+    return toMinor !== fromMinor ? "compatible-with-additions" : "compatible";
+}
+/**
+ * The version of the release immediately before `version`, taken from the
+ * release-notes directory.
+ *
+ * Derived from `docs/releases/` rather than git tags on purpose: the repository
+ * has no previous-tag lookup anywhere, this needs no subprocess, and the notes
+ * are already required to exist for the release being cut — `docs-integrity`
+ * asserts the current version's file is present and packaged. Using a source
+ * that is already load-bearing means this cannot silently disagree with what
+ * ships.
+ *
+ * Returns `null` when there is no earlier release, which is a real state for the
+ * first one.
+ */
+export function previousReleaseVersion(releasesDir, version) {
+    let entries;
+    try {
+        entries = fs.readdirSync(releasesDir);
+    }
+    catch {
+        return null;
+    }
+    const target = parseVersion(version);
+    if (!target)
+        return null;
+    let best = null;
+    for (const entry of entries) {
+        if (path.extname(entry) !== ".md")
+            continue;
+        const candidateText = path.basename(entry, ".md");
+        const candidate = parseVersion(candidateText);
+        if (!candidate)
+            continue;
+        if (compareCore(candidate.core, target.core) >= 0)
+            continue;
+        if (!best || compareCore(candidate.core, best.core) > 0)
+            best = { text: candidateText, core: candidate.core };
+    }
+    return best?.text ?? null;
+}
+function compareCore(left, right) {
+    for (let index = 0; index < 3; index++) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}

package/dist/src/release-preflight.js

@@ -3,6 +3,7 @@ import { createHash, createPublicKey } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { compareBytes } from "./compare.js";
+import { classifyCompatibility, previousReleaseVersion } from "./release-compatibility.js";
 import { validateRootCeremonyManifest } from "./update-ceremony.js";
 import { canonicalizeUpdateMetadata, verifyUpdateRootChain, } from "./update-trust.js";
 export const RELEASE_PREFLIGHT_REPOSITORY_COMMANDS = [
@@ -486,6 +487,23 @@ export function evaluateReleasePreflight(options) {
     const packageManifest = record(parseJson(packageFile.bytes, "package manifest"), "package manifest");
     if (packageManifest.version !== plan.version)
         fail("package version does not equal release-plan version");
+    // `knodin.compatibility` ships in the tarball and is read out of it by the
+    // Homebrew tap. Nothing inside this repository consumes it, so a wrong value
+    // reaches consumers without anything failing — it was a hardcoded "breaking"
+    // across four releases, two of which were bugfix patches. This is the last
+    // gate that sees the manifest before it is published.
+    const declaredCompatibility = record(packageManifest.knodin ?? {}, "package manifest knodin block").compatibility;
+    const previousRelease = previousReleaseVersion(path.join(repositoryRoot, "docs", "releases"), plan.version);
+    if (previousRelease !== null) {
+        const derived = classifyCompatibility(previousRelease, plan.version);
+        // A null derivation means the version did not move forward, which the
+        // version check above should already have caught; failing here rather than
+        // skipping keeps an unexplained state from passing silently.
+        if (derived === null)
+            fail(`cannot classify compatibility from ${previousRelease} to ${plan.version}`);
+        else if (declaredCompatibility !== derived)
+            fail(`package knodin.compatibility is ${JSON.stringify(declaredCompatibility)} but ${previousRelease} to ${plan.version} is ${derived}`);
+    }
     const workflowFile = readBoundedRegularFile(repositoryRoot, path.join(repositoryRoot, plan.workflow.path), "C64 candidate workflow", MAX_MANIFEST_BYTES);
     if (!git.isTracked(workflowFile.relativePath))
         fail("C64 candidate workflow must be checked in");