@holmes-lab/holmes-kit 0.24.0 → 0.25.0

package/dist/holmes/semantic/vector-coverage.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Whether the semantic layer is doing anything at all.
+ *
+ * Measured on this repository 2026-09-19: the resolved tier was `cloud`, and of 602 scanned files
+ * ZERO had a cached document vector under that model — while 327 sat in the same cache under
+ * `bge-m3`, a model this project no longer resolves to. Every `cachedDocVector` returned null, so
+ * `rerankHitsBySemantic` reordered nothing and `semanticAlternates` emitted nothing. Neither said
+ * so, and `doctor` printed `PASS semantic tier` throughout — a statement about a key and a model
+ * name, not about whether one lookup would succeed.
+ *
+ * An inert layer and a layer that examined every candidate and agreed with the lexical ordering
+ * produce byte-identical output. That is the defect this module removes: it makes zero say zero.
+ *
+ * OBSERVATION ONLY. Nothing here reads into a ranking, a selection or any verdict.
+ */
+/** The shape the scanner returns, narrowed to what the document text needs. */
+export interface ScannedLike {
+    sourcePath: string;
+    symbols: ReadonlyArray<{
+        qualifiedName: string;
+    }>;
+}
+export type CoverageState = 'covered' | 'inert' | 'not-adopted' | 'unknown';
+export interface CoverageInput {
+    /** The RESOLVED tier. `none` is the shipped default (zero egress) and means never opted in. */
+    tier: string;
+    /** The resolved model's cache tag. null when it cannot be determined. */
+    modelTag: string | null;
+    total: number;
+    covered: number;
+}
+export interface VectorCoverage {
+    state: CoverageState;
+    covered: number;
+    total: number;
+    /** null whenever a ratio would be invented — an unjudgeable count or an empty scan. */
+    ratio: number | null;
+    modelTag: string | null;
+}
+/** The maximum document text length; part of the cache key, so it is part of the contract. */
+export declare const DOC_TEXT_LIMIT = 2000;
+/**
+ * THE definition of the text whose hash keys a document vector.
+ *
+ * It existed as an inline expression in five places, four of them in `maintenance-analyze.ts` and
+ * one in `issue_localize`'s rerank — two of which are the surfaces this module's coverage claims to
+ * describe. A separate copy here would be free to drift, and a drifted instrument reports a
+ * coverage the product does not have. One definition, or the build fails.
+ */
+export declare function docTextOf(file: ScannedLike): string;
+/** The same text, indexed by source path — the form the three ranking passes consume. */
+export declare function docTextIndex(scanned: ReadonlyArray<ScannedLike>): Map<string, string>;
+/**
+ * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
+ * without a cache on disk, and it cannot be wrong about ordering or locking.
+ */
+export declare function vectorCoverage(input: CoverageInput): VectorCoverage;
+/** Empty when there is nothing to say. Never silent when there is. */
+export declare function coverageLine(v: VectorCoverage): string;
+/**
+ * How many scanned files have a cached document vector, judged by a lookup the CALLER supplies.
+ *
+ * The lookup is injected so this module stays free of the cache's I/O and locking, and so the
+ * count is taken through the same public accessor the ranking surfaces use — a private key
+ * recomputed here could agree with the cache today and drift from it tomorrow.
+ */
+export declare function countCovered(scanned: ReadonlyArray<ScannedLike>, isCached: (docText: string) => boolean): number;
+export type WarmReason = 'warmed' | 'suppressed' | 'not-adopted';
+export interface PersistedCoverage {
+    coverage: VectorCoverage;
+    reason: WarmReason;
+    at: string;
+    stored?: number;
+    head?: string;
+}
+export declare const COVERAGE_STATE_FILE = "semantic-coverage.json";
+/** Best-effort: a verdict that cannot be written is not worth failing a refresh over. */
+export declare function writeCoverageState(root: string, p: PersistedCoverage): void;
+/** null means NOT RUN — missing, unreadable, or not shaped like a verdict. Never throws. */
+export declare function readCoverageState(root: string): PersistedCoverage | null;
+/**
+ * The turn-boundary line. Empty when there is nothing to say; NEVER empty when there is.
+ *
+ * `null` is the case this exists for. A workspace whose refresh never ran looks exactly like a
+ * healthy one if absence is allowed to be silent, and that silence is what hid zero coverage for
+ * twelve days.
+ */
+export declare function coverageStopLine(p: PersistedCoverage | null, currentHead?: string): string;

package/dist/holmes/semantic/vector-coverage.js

@@ -0,0 +1,210 @@
+"use strict";
+// @implements A-SPEC-682
+/**
+ * Whether the semantic layer is doing anything at all.
+ *
+ * Measured on this repository 2026-09-19: the resolved tier was `cloud`, and of 602 scanned files
+ * ZERO had a cached document vector under that model — while 327 sat in the same cache under
+ * `bge-m3`, a model this project no longer resolves to. Every `cachedDocVector` returned null, so
+ * `rerankHitsBySemantic` reordered nothing and `semanticAlternates` emitted nothing. Neither said
+ * so, and `doctor` printed `PASS semantic tier` throughout — a statement about a key and a model
+ * name, not about whether one lookup would succeed.
+ *
+ * An inert layer and a layer that examined every candidate and agreed with the lexical ordering
+ * produce byte-identical output. That is the defect this module removes: it makes zero say zero.
+ *
+ * OBSERVATION ONLY. Nothing here reads into a ranking, a selection or any verdict.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COVERAGE_STATE_FILE = exports.DOC_TEXT_LIMIT = void 0;
+exports.docTextOf = docTextOf;
+exports.docTextIndex = docTextIndex;
+exports.vectorCoverage = vectorCoverage;
+exports.coverageLine = coverageLine;
+exports.countCovered = countCovered;
+exports.writeCoverageState = writeCoverageState;
+exports.readCoverageState = readCoverageState;
+exports.coverageStopLine = coverageStopLine;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** The maximum document text length; part of the cache key, so it is part of the contract. */
+exports.DOC_TEXT_LIMIT = 2000;
+/**
+ * THE definition of the text whose hash keys a document vector.
+ *
+ * It existed as an inline expression in five places, four of them in `maintenance-analyze.ts` and
+ * one in `issue_localize`'s rerank — two of which are the surfaces this module's coverage claims to
+ * describe. A separate copy here would be free to drift, and a drifted instrument reports a
+ * coverage the product does not have. One definition, or the build fails.
+ */
+function docTextOf(file) {
+    return (file.sourcePath + ' ' + file.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, exports.DOC_TEXT_LIMIT);
+}
+/** The same text, indexed by source path — the form the three ranking passes consume. */
+function docTextIndex(scanned) {
+    return new Map(scanned.map((f) => [f.sourcePath, docTextOf(f)]));
+}
+const isCount = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+/**
+ * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
+ * without a cache on disk, and it cannot be wrong about ordering or locking.
+ */
+function vectorCoverage(input) {
+    const total = isCount(input.total) ? Math.floor(input.total) : 0;
+    const covered = isCount(input.covered) ? Math.min(Math.floor(input.covered), total) : 0;
+    const modelTag = typeof input.modelTag === 'string' && input.modelTag !== '' ? input.modelTag : null;
+    const base = { covered, total, modelTag };
+    // A project at the shipped default never opted in. It is not failing at something it declined.
+    if (input.tier === 'none' || input.tier === '')
+        return { state: 'not-adopted', ratio: null, ...base };
+    // No model tag means no lookup key: the count could not be taken. Saying `covered: 0` here would
+    // report an inert layer that may well be working — the two must not share a shape.
+    if (modelTag === null)
+        return { state: 'unknown', ratio: null, ...base };
+    // Nothing was scanned, so nothing was missed. An empty scan is evidence about the scan, not the
+    // cache, and a ratio over zero files would be invented.
+    if (total === 0)
+        return { state: 'unknown', ratio: null, ...base };
+    if (covered === 0)
+        return { state: 'inert', ratio: 0, ...base };
+    return { state: 'covered', ratio: covered / total, ...base };
+}
+/** Empty when there is nothing to say. Never silent when there is. */
+function coverageLine(v) {
+    if (v.state === 'not-adopted')
+        return '';
+    if (v.state === 'unknown') {
+        // An empty scan has nothing to report; an unjudgeable count with files present does.
+        if (v.total === 0)
+            return '';
+        return 'document-vector coverage could not be judged — the resolved model has no cache tag, '
+            + 'so whether a lookup would succeed is unknown';
+    }
+    if (v.state === 'inert') {
+        return `the semantic layer is INERT: 0 of ${v.total} scanned files have a cached document vector `
+            + `under ${v.modelTag ?? 'the resolved model'} — every lookup returns nothing, so reranking `
+            + 'reorders nothing and alternates emit nothing. This reads identically to agreement.';
+    }
+    const pct = v.ratio === null ? '' : ` (${(v.ratio * 100).toFixed(1)}%)`;
+    return `document-vector coverage ${v.covered} of ${v.total}${pct} under ${v.modelTag ?? 'the resolved model'}`;
+}
+/**
+ * How many scanned files have a cached document vector, judged by a lookup the CALLER supplies.
+ *
+ * The lookup is injected so this module stays free of the cache's I/O and locking, and so the
+ * count is taken through the same public accessor the ranking surfaces use — a private key
+ * recomputed here could agree with the cache today and drift from it tomorrow.
+ */
+function countCovered(scanned, isCached) {
+    let n = 0;
+    for (const f of scanned) {
+        if (isCached(docTextOf(f)))
+            n++;
+    }
+    return n;
+}
+exports.COVERAGE_STATE_FILE = 'semantic-coverage.json';
+const statePath = (root) => path.join(root, '.ax', 'state', exports.COVERAGE_STATE_FILE);
+/** Best-effort: a verdict that cannot be written is not worth failing a refresh over. */
+function writeCoverageState(root, p) {
+    try {
+        const file = statePath(root);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(p, null, 2) + '\n');
+    }
+    catch { /* the refresh is fail-soft; so is recording it */ }
+}
+/** null means NOT RUN — missing, unreadable, or not shaped like a verdict. Never throws. */
+function readCoverageState(root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(statePath(root), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const o = parsed;
+    const c = o.coverage;
+    if (typeof c !== 'object' || c === null)
+        return null;
+    if (typeof c.state !== 'string' || typeof c.covered !== 'number' || typeof c.total !== 'number')
+        return null;
+    if (o.reason !== 'warmed' && o.reason !== 'suppressed' && o.reason !== 'not-adopted')
+        return null;
+    return { coverage: c, reason: o.reason, at: typeof o.at === 'string' ? o.at : '',
+        ...(typeof o.stored === 'number' ? { stored: o.stored } : {}),
+        ...(typeof o.head === 'string' && o.head !== '' ? { head: o.head } : {}) };
+}
+/**
+ * The turn-boundary line. Empty when there is nothing to say; NEVER empty when there is.
+ *
+ * `null` is the case this exists for. A workspace whose refresh never ran looks exactly like a
+ * healthy one if absence is allowed to be silent, and that silence is what hid zero coverage for
+ * twelve days.
+ */
+function coverageStopLine(p, currentHead) {
+    if (p === null) {
+        return 'semantic vectors: not run — no refresh has recorded a coverage verdict for this '
+            + 'workspace, so whether the semantic layer contributes anything is unknown';
+    }
+    if (p.reason === 'not-adopted' || p.coverage.state === 'not-adopted')
+        return '';
+    // The verdict is machine-local; the CODE it describes arrives from other machines through Git.
+    // A pull brings in symbols this verdict never saw, and the document text those symbols key is
+    // what every vector lookup hashes — so a verdict from another commit describes a tree that no
+    // longer exists. Report it as needing re-measurement: neither healthy nor broken. Absence of a
+    // head on either side is not a mismatch; it is simply unjudgeable, and silence is correct there
+    // because the other states already speak for themselves.
+    if (typeof p.head === 'string' && p.head !== '' && typeof currentHead === 'string'
+        && currentHead !== '' && p.head !== currentHead) {
+        return `semantic vectors: the coverage verdict was recorded at another commit (${p.head.slice(0, 7)}, `
+            + `now ${currentHead.slice(0, 7)}) — work merged since then changes the symbols the vectors key on, `
+            + 'so coverage needs re-measuring';
+    }
+    if (p.reason === 'suppressed') {
+        // An owner who turned the transfer off must not be shown a fault. Report the number, name the
+        // switch, and say nothing that reads as breakage.
+        return `semantic vectors: automatic warming is switched off (HOLMES_NO_SEMANTIC_WARM); `
+            + `coverage stands at ${p.coverage.covered} of ${p.coverage.total} — run rtm_reindex to warm on demand`;
+    }
+    const line = coverageLine(p.coverage);
+    if (p.coverage.state === 'covered' && p.stored !== undefined && p.stored < p.coverage.covered) {
+        return `${line} — ${p.coverage.covered - p.stored} vector(s) were computed but never stored`;
+    }
+    return p.coverage.state === 'covered' ? '' : line;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",