@rasensio/aidlc 1.67.0 → 1.72.0

package/dist/hooks/lifecycle-context.js

@@ -0,0 +1,212 @@
+/**
+ * What a harness hook needs to know about the lifecycle: which instance is
+ * claimed in this checkout, what phase it is in, and what comes next.
+ *
+ * Read-only by contract (hooks-carry-lifecycle-state/AC-8). Everything here runs
+ * inside a `SessionStart` or `PreToolUse` hook, on every session start or every
+ * edit, so it reads only the claims and the claimed instances' own files — never
+ * every instance, ledger or cache. `aidlc status --json` reads all of those and
+ * took 3.5 s on this repository; the CLI itself starts in 0.16 s (AC-10).
+ *
+ * Requirements: hooks-carry-lifecycle-state/AC-1..AC-9
+ * Design: design.md C2
+ *
+ * @module
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { loadTemplates as loadBuiltInTemplates } from '@rasensio/aidlc-content';
+import { nextStep } from '../core/lifecycle.js';
+import { loadTemplates, resolveTemplate } from '../core/template-resolver.js';
+import { loadSnapshot } from '../state/snapshot-store.js';
+import { parseTasks } from '../tasks/parser.js';
+import { gitDirs } from '../concurrency/common-dir.js';
+import { readClaims } from '../concurrency/claim-store.js';
+/** Phases in which code is not yet written — what the phase guard asks about. */
+export const PLANNING_PHASES = ['ideation', 'requirements', 'design'];
+/** Longest line either hook prints (AC-9). */
+export const MAX_LINE = 200;
+function canonical(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/**
+ * Instances claimed in this checkout, sorted by name (AC-6).
+ *
+ * Held here means recorded from this working directory: the claim's
+ * `worktree_path` is this checkout, or it has none and this is the primary
+ * checkout. Staleness is deliberately not consulted — claims renew only at phase
+ * transitions, and one phase routinely outlasts the 60-minute window, so a
+ * live-only rule would go quiet on a compaction deep into implementation, the
+ * case this hook exists for (design D3). Session ids are not compared either:
+ * they change across `startup`.
+ */
+export function claimsHere(projectRoot) {
+    const git = gitDirs(projectRoot);
+    const here = canonical(projectRoot);
+    const held = [];
+    for (const [name, claim] of readClaims(projectRoot, git?.common ?? null)) {
+        if (!existsSync(join(projectRoot, '.aidlc', 'state', name, 'instance.yaml')))
+            continue;
+        // `aidlc claim` records `worktree_path` only from a linked worktree, so a
+        // claim without one was taken in the primary checkout. Outside git the claims
+        // live in this checkout's own instance.yaml files. Not `dirname(common dir)`:
+        // the project can sit below the repository root, and then that is not here.
+        const heldHere = claim.worktree_path ? canonical(claim.worktree_path) === here : git === null || !git.linked;
+        if (heldHere)
+            held.push(name);
+    }
+    return held.sort();
+}
+/** `current_phase` of one instance, or null when its state cannot be read. */
+export function currentPhase(projectRoot, name) {
+    try {
+        const state = loadSnapshot(join(projectRoot, '.aidlc', 'state'), name, 'instance.yaml');
+        return typeof state.current_phase === 'string' ? state.current_phase : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Built-in templates plus the project's own, as `aidlc continue` loads them. */
+function loadAllTemplates(projectRoot) {
+    const templates = new Map();
+    for (const tpl of loadBuiltInTemplates()) {
+        templates.set(tpl.name, tpl.raw);
+    }
+    const customDir = join(projectRoot, '.aidlc', 'templates');
+    if (existsSync(customDir)) {
+        for (const [name, tpl] of loadTemplates(customDir))
+            templates.set(name, tpl);
+    }
+    return templates;
+}
+/**
+ * Phase files keyed by the phase named in the file name, an unreadable one
+ * skipped — both exactly as `aidlc continue` does, so the next step stays the one
+ * it reports (AC-2).
+ */
+function loadPhaseStates(stateDir, name) {
+    const phases = new Map();
+    for (const entry of readdirSync(join(stateDir, name))) {
+        if (!entry.startsWith('phase-') || !entry.endsWith('.yaml'))
+            continue;
+        try {
+            phases.set(entry.slice('phase-'.length, -'.yaml'.length), loadSnapshot(stateDir, name, entry));
+        }
+        catch {
+            // skipped, as continue.ts skips it
+        }
+    }
+    return phases;
+}
+/**
+ * One instance's phase and next step, or null when any of its state cannot be
+ * read (AC-7) — a hook must never stop a session starting.
+ */
+export function instanceContext(projectRoot, name) {
+    try {
+        const stateDir = join(projectRoot, '.aidlc', 'state');
+        const state = loadSnapshot(stateDir, name, 'instance.yaml');
+        const templates = loadAllTemplates(projectRoot);
+        const raw = templates.get(state.template);
+        if (!raw)
+            return null;
+        const step = nextStep(state, loadPhaseStates(stateDir, name), resolveTemplate(raw, templates));
+        return {
+            name,
+            template: state.template,
+            scope: state.scope,
+            phase: String(state.current_phase),
+            step,
+            openTask: state.current_phase === 'implementation' ? lowestOpenTask(stateDir, name) : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function lowestOpenTask(stateDir, name) {
+    let content;
+    try {
+        content = readFileSync(join(stateDir, name, 'tasks.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    // parseTasks orders by id, so the first open one is the lowest-numbered.
+    const task = parseTasks(content).tasks.find((t) => t.state === 'open');
+    return task ? { id: task.id, title: task.title } : null;
+}
+/**
+ * One printable line: control characters (escape codes included) become spaces,
+ * and anything past `max` is cut with an ellipsis (AC-9).
+ */
+export function plainLine(text, max = MAX_LINE) {
+    const plain = text.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+    return plain.length <= max ? plain : `${plain.slice(0, max - 1)}…`;
+}
+const RESUME = 'Resume with the aidlc-continue skill.';
+function nextStepLine(ctx) {
+    if (ctx.openTask !== null) {
+        // The title is what gets shortened, so the pointer at the end survives (AC-9).
+        const head = `Next step: T${ctx.openTask.id} — `;
+        const tail = `, the lowest open task in tasks.md. ${RESUME}`;
+        const room = MAX_LINE - head.length - tail.length;
+        const title = plainLine(ctx.openTask.title, Math.max(room, 1));
+        return `${head}${title}${tail}`;
+    }
+    switch (ctx.step.kind) {
+        case 'artifact':
+            return `Next step: produce ${ctx.step.artifact}. ${RESUME}`;
+        case 'phase':
+            return (`Next step: the ${ctx.phase} phase is complete — enter ${ctx.step.phase} ` +
+                `(aidlc transition ${ctx.name}). ${RESUME}`);
+        case 'complete':
+            return 'Next step: none — every phase is complete.';
+    }
+}
+/** The three lines for one claimed instance (AC-1). */
+function singleLines(projectRoot, ctx) {
+    const skill = `.aidlc/skills/aidlc-${ctx.phase}.md`;
+    const pointer = existsSync(join(projectRoot, skill)) ? ` Phase instructions: ${skill}` : '';
+    return [
+        `AIDLC: instance ${ctx.name} is claimed in this checkout (${ctx.template} template, ${ctx.scope} scope).`,
+        `Phase: ${ctx.phase}.${pointer}`,
+        nextStepLine(ctx),
+    ].map((line) => plainLine(line));
+}
+/** One line naming every claimed instance, or as many as fit (AC-5, AC-9). */
+function severalLine(contexts) {
+    const head = `AIDLC: ${contexts.length} instances are claimed in this checkout — `;
+    const tail = '. Run aidlc status to see which to continue.';
+    const named = contexts.map((c) => `${c.name} (${c.phase})`);
+    for (let shown = named.length; shown > 0; shown--) {
+        const rest = named.length - shown;
+        const list = named.slice(0, shown).join(', ') + (rest > 0 ? `, and ${rest} more` : '');
+        const line = `${head}${list}${tail}`;
+        if (line.length <= MAX_LINE)
+            return line;
+    }
+    return plainLine(`${head}${named.join(', ')}${tail}`);
+}
+/**
+ * What `aidlc hook session-start` prints: three lines for one claim, one line
+ * for several, nothing for none (AC-1, AC-4, AC-5). An instance whose state
+ * cannot be read is left out (AC-7).
+ */
+export function sessionStartLines(projectRoot) {
+    const contexts = claimsHere(projectRoot)
+        .map((name) => instanceContext(projectRoot, name))
+        .filter((ctx) => ctx !== null);
+    if (contexts.length === 0)
+        return [];
+    if (contexts.length === 1)
+        return singleLines(projectRoot, contexts[0]);
+    return [severalLine(contexts)];
+}
+//# sourceMappingURL=lifecycle-context.js.map

package/dist/hooks/lifecycle-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-context.js","sourceRoot":"","sources":["../../src/hooks/lifecycle-context.ts"],"names":[],"mappings":"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"}

package/dist/knowledge/engine.d.ts

@@ -2,11 +2,15 @@
  * Knowledge engine facade — opens the YAML store and SQLite index together
  * and wires up the standard recovery paths:
  *
- * - Missing/empty index with YAML present → auto-rebuild from sources.
+ * - Index whose recorded source fingerprint disagrees with the sources on disk
+ *   → auto-rebuild from sources. This covers the missing index, the empty one,
+ *   and — the case it was added for — sources that arrived by `git pull`, merge
+ *   or branch switch rather than through this CLI.
  * - Outdated index schema → delete and rebuild (the index is a disposable
  *   cache; YAML is the source of truth — design DD2).
  *
- * Requirements: KG 3.2, 3.3, 11.4
+ * Requirements: KG 3.2, 3.3, 11.4; knowledge-index-misses-merged-yaml/AC-1, AC-2,
+ * AC-6, AC-11, AC-13
  *
  * @module
  */
@@ -17,6 +21,7 @@ import { KnowledgeReader } from './reader.js';
 import { ContextGenerator } from './context-generator.js';
 import { StalenessDetector } from './staleness.js';
 import { KNOWLEDGE_DIR } from './types.js';
+import type { Entity } from './types.js';
 /**
  * Relative path of the knowledge directory within a project.
  *
@@ -34,6 +39,18 @@ export interface KnowledgeEngine {
     staleness: StalenessDetector;
     /** Parse warnings emitted by an auto-rebuild, if one ran. */
     warnings: string[];
+    /**
+     * The entities the open-time rebuild replaced, or `null` when the cache was served.
+     *
+     * `knowledge sync` exists to report what a merge did (KG Req 12.4), and it does that
+     * by diffing the pre-pull index against the post-pull YAML. Now that opening the
+     * engine rebuilds a stale index, that diff would always be empty — the "before" it
+     * read from the index would already be the "after". So the one thing that can still
+     * see the pre-pull state keeps it: it is captured here, on the rebuild branch only,
+     * where the whole YAML was about to be re-read anyway. A cache hit pays nothing
+     * (knowledge-index-misses-merged-yaml/AC-8, design DD7).
+     */
+    replaced: Entity[] | null;
     close(): void;
 }
 /**

package/dist/knowledge/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/knowledge/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAiB,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAgDlE;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE5D"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/knowledge/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAiB,MAAM,yBAAyB,CAAC;AAGrE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,SAAS,EAAE,iBAAiB,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAmElE;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/knowledge/engine.js

@@ -2,19 +2,24 @@
  * Knowledge engine facade — opens the YAML store and SQLite index together
  * and wires up the standard recovery paths:
  *
- * - Missing/empty index with YAML present → auto-rebuild from sources.
+ * - Index whose recorded source fingerprint disagrees with the sources on disk
+ *   → auto-rebuild from sources. This covers the missing index, the empty one,
+ *   and — the case it was added for — sources that arrived by `git pull`, merge
+ *   or branch switch rather than through this CLI.
  * - Outdated index schema → delete and rebuild (the index is a disposable
  *   cache; YAML is the source of truth — design DD2).
  *
- * Requirements: KG 3.2, 3.3, 11.4
+ * Requirements: KG 3.2, 3.3, 11.4; knowledge-index-misses-merged-yaml/AC-1, AC-2,
+ * AC-6, AC-11, AC-13
  *
  * @module
  */
 import { join } from 'node:path';
-import { existsSync, rmSync } from 'node:fs';
+import { rmSync } from 'node:fs';
 import { YamlSourceStore } from './yaml-source.js';
 import { SqliteIndex, INDEX_DB_FILE } from './index/sqlite-index.js';
 import { IndexOutdatedError } from './index/knowledge-index.js';
+import { fingerprintSources, rebuildFromSources } from './source-fingerprint.js';
 import { KnowledgeWriter } from './writer.js';
 import { KnowledgeReader } from './reader.js';
 import { ContextGenerator } from './context-generator.js';
@@ -38,7 +43,6 @@ export function openKnowledge(projectRoot) {
     const source = new YamlSourceStore(knowledgeDir);
     const warnings = [];
     const dbPath = join(knowledgeDir, INDEX_DB_FILE);
-    const dbExisted = existsSync(dbPath);
     let index;
     try {
         index = new SqliteIndex(knowledgeDir);
@@ -56,13 +60,32 @@ export function openKnowledge(projectRoot) {
             throw err;
         }
     }
-    // Fresh index but sources exist → populate from YAML (KG Req 3.2).
-    if ((!dbExisted || index.getAllEntities().length === 0) && source.exists()) {
-        const loaded = source.loadAll();
-        if (loaded.entities.length > 0 || loaded.relationships.length > 0) {
-            index.rebuild(loaded.entities, loaded.relationships);
-        }
-        warnings.push(...loaded.warnings);
+    // The sources moved since the index was built → rebuild before anything is served
+    // (AC-1, AC-2). Checked here, at open, rather than lazily on first query, so there
+    // is no window in which a reader sees a stale row.
+    //
+    // This one condition replaces `(!dbExisted || index.getAllEntities().length === 0)
+    // && source.exists()`, and each half of that is worth a line on why it is gone:
+    //
+    // - `!dbExisted || getAllEntities().length === 0` only ever asked "is the cache
+    //   empty", which is why YAML arriving by merge was invisible. It also read the
+    //   whole entities table on *every* open — `||` does not short-circuit in the
+    //   direction it needed — so dropping it is where AC-16's headroom comes from
+    //   (design DD7). A matching fingerprint already means these contents were built
+    //   from these sources, so an empty index with a matching fingerprint means the
+    //   sources are empty, and serving empty is correct.
+    // - `source.exists()` skipped the rebuild precisely when there was nothing to
+    //   rebuild from, so deleting the YAML left the index serving every deleted fact
+    //   forever. An empty tree fingerprints differently from a populated one, so the
+    //   deletion is now indexed like any other change (AC-3, design DD8).
+    //
+    // A project that has no graph at all stamps the empty-tree fingerprint on its
+    // first open and is a cache hit from then on (AC-13).
+    let replaced = null;
+    if (index.getSourceFingerprint() !== fingerprintSources(source)) {
+        // Kept before it is overwritten, for `knowledge sync` — see `replaced` above.
+        replaced = index.getAllEntities();
+        warnings.push(...rebuildFromSources(source, index).warnings);
     }
     const writer = new KnowledgeWriter(source, index);
     const reader = new KnowledgeReader(index);
@@ -76,6 +99,7 @@ export function openKnowledge(projectRoot) {
         context,
         staleness,
         warnings,
+        replaced,
         close: () => index.close(),
     };
 }

package/dist/knowledge/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/knowledge/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/knowledge/engine.ts"],"names":[],"mappings":"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"}

package/dist/knowledge/index/knowledge-index.d.ts

@@ -38,8 +38,34 @@ export interface KnowledgeIndex {
     relationshipsTo(id: string): Relationship[];
     relationshipsFor(ids: string[]): Relationship[];
     countRelationshipsByType(type: string): number;
-    /** Replace all index contents from parsed YAML sources (KG Req 3.3). */
-    rebuild(entities: Entity[], relationships: Relationship[]): void;
+    /**
+     * Replace all index contents from parsed YAML sources (KG Req 3.3).
+     *
+     * **An implementation MUST discard any recorded source fingerprint it is not
+     * given**, atomically with the contents. The freshness invariant rests on it: a
+     * fingerprint may exist only because a caller vouched for *these* contents, so
+     * that the way to get a stale cache hit is to stamp a fingerprint you did not
+     * earn — a much smaller thing to keep right than remembering to clear one. An
+     * implementation that keeps the old record instead lets `compact`, which rebuilds
+     * from deduplicated entities rather than a plain load, serve contents the
+     * fingerprint does not describe (knowledge-index-misses-merged-yaml/AC-4).
+     *
+     * @param fingerprint - Source fingerprint these contents were built from, recorded
+     *   in the same transaction. Omit — or pass `null` — when the caller cannot vouch
+     *   for a source state; the record is then cleared and the next open rebuilds.
+     */
+    rebuild(entities: Entity[], relationships: Relationship[], fingerprint?: string | null): void;
+    /**
+     * Fingerprint of the YAML sources these contents were built from, or `null` when
+     * none is recorded.
+     *
+     * "Which source state am I a cache of" is a property of a cache, so it belongs on
+     * this interface rather than beside it. `null` means rebuild, never "assume fresh"
+     * (knowledge-index-misses-merged-yaml/AC-4).
+     */
+    getSourceFingerprint(): string | null;
+    /** Record the fingerprint the current contents were built from. */
+    setSourceFingerprint(fingerprint: string): void;
     close(): void;
 }
 //# sourceMappingURL=knowledge-index.d.ts.map

package/dist/knowledge/index/knowledge-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-index.d.ts","sourceRoot":"","sources":["../../../src/knowledge/index/knowledge-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,8FAA8F;AAC9F,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAO5C;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B,oFAAoF;IACpF,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,EAAE,CAAC;IAChE,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IAChD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IACrE,+EAA+E;IAC/E,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9C,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1C,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9C,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC5C,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;IAChD,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAEjE,KAAK,IAAI,IAAI,CAAC;CACf"}
+{"version":3,"file":"knowledge-index.d.ts","sourceRoot":"","sources":["../../../src/knowledge/index/knowledge-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,8FAA8F;AAC9F,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAO5C;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B,oFAAoF;IACpF,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,EAAE,CAAC;IAChE,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IAChD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IACrE,+EAA+E;IAC/E,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9C,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1C,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9C,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC5C,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;IAChD,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/C;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAE9F;;;;;;;OAOG;IACH,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAAC;IAEtC,mEAAmE;IACnE,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhD,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/knowledge/index/sqlite-index.d.ts

@@ -15,6 +15,21 @@ import type { Entity, Relationship } from '../types.js';
 import type { KnowledgeIndex, SearchOptions, EntityFilter } from './knowledge-index.js';
 /** Filename of the index database inside the knowledge directory. */
 export declare const INDEX_DB_FILE = "index.db";
+/**
+ * Schema version of the index **cache**, deliberately separate from
+ * `KNOWLEDGE_SCHEMA_VERSION`, which versions the YAML **sources**.
+ *
+ * One constant used to serve both. Bumping it to add this version's
+ * `source_fingerprint` table would also have stamped `schemaVersion: 2` into every
+ * YAML `_meta` the next `compact` rewrote, and an older CLI reading those files warns
+ * about them (`yaml-source.ts`) — user-visible churn in the source of truth caused by
+ * a change to a cache. Splitting them costs this comment and one import
+ * (knowledge-index-misses-merged-yaml/AC-14, design DD3).
+ *
+ * Version 2 adds `source_fingerprint`. An index at version 1 is discarded and rebuilt
+ * by the `IndexOutdatedError` path `openKnowledge` already owns (AC-11).
+ */
+export declare const INDEX_SCHEMA_VERSION = 2;
 export declare class SqliteIndex implements KnowledgeIndex {
     private readonly db;
     private ftsAvailable;
@@ -42,7 +57,10 @@ export declare class SqliteIndex implements KnowledgeIndex {
     relationshipsTo(id: string): Relationship[];
     relationshipsFor(ids: string[]): Relationship[];
     countRelationshipsByType(type: string): number;
-    rebuild(entities: Entity[], relationships: Relationship[]): void;
+    rebuild(entities: Entity[], relationships: Relationship[], fingerprint?: string | null): void;
+    getSourceFingerprint(): string | null;
+    setSourceFingerprint(fingerprint: string): void;
+    private writeFingerprint;
     close(): void;
     private syncFts;
     private syncFileMapping;

package/dist/knowledge/index/sqlite-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-index.d.ts","sourceRoot":"","sources":["../../../src/knowledge/index/sqlite-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAExF,qEAAqE;AACrE,eAAO,MAAM,aAAa,aAAa,CAAC;AAwBxC,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;gBACS,YAAY,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;IAYzD,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,YAAY;IAgEpB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAOzC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAwBlC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ9B,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,EAAE;IAenE,OAAO,CAAC,SAAS;IA2BjB,OAAO,CAAC,UAAU;IAkBlB,cAAc,CAAC,MAAM,GAAE,YAAiB,GAAG,MAAM,EAAE;IAYnD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,YAAiB,GAAG,MAAM,EAAE;IAcxE,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAW7C,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAWzC,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAU3C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE;IAO7C,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE;IAO3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE;IAY/C,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAW9C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,IAAI;IAiBhE,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,SAAS;CAOlB;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD"}
+{"version":3,"file":"sqlite-index.d.ts","sourceRoot":"","sources":["../../../src/knowledge/index/sqlite-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAExF,qEAAqE;AACrE,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAwBtC,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;gBACS,YAAY,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;IAYzD,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,YAAY;IAwEpB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAOzC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAwBlC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ9B,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,EAAE;IAenE,OAAO,CAAC,SAAS;IA2BjB,OAAO,CAAC,UAAU;IAkBlB,cAAc,CAAC,MAAM,GAAE,YAAiB,GAAG,MAAM,EAAE;IAYnD,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,YAAiB,GAAG,MAAM,EAAE;IAcxE,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAW7C,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAWzC,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAU3C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE;IAO7C,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE;IAO3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE;IAY/C,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAW9C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,EAAE,WAAW,GAAE,MAAM,GAAG,IAAW,GAAG,IAAI;IAiCnG,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAcrC,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI/C,OAAO,CAAC,gBAAgB;IAMxB,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,SAAS;CAOlB;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD"}

package/dist/knowledge/index/sqlite-index.js

@@ -14,10 +14,25 @@
 import { DatabaseSync } from 'node:sqlite';
 import { join } from 'node:path';
 import { mkdirSync } from 'node:fs';
-import { AGENT_INFERRED_SOURCE, KNOWLEDGE_SCHEMA_VERSION } from '../types.js';
+import { AGENT_INFERRED_SOURCE } from '../types.js';
 import { IndexOutdatedError } from './knowledge-index.js';
 /** Filename of the index database inside the knowledge directory. */
 export const INDEX_DB_FILE = 'index.db';
+/**
+ * Schema version of the index **cache**, deliberately separate from
+ * `KNOWLEDGE_SCHEMA_VERSION`, which versions the YAML **sources**.
+ *
+ * One constant used to serve both. Bumping it to add this version's
+ * `source_fingerprint` table would also have stamped `schemaVersion: 2` into every
+ * YAML `_meta` the next `compact` rewrote, and an older CLI reading those files warns
+ * about them (`yaml-source.ts`) — user-visible churn in the source of truth caused by
+ * a change to a cache. Splitting them costs this comment and one import
+ * (knowledge-index-misses-merged-yaml/AC-14, design DD3).
+ *
+ * Version 2 adds `source_fingerprint`. An index at version 1 is discarded and rebuilt
+ * by the `IndexOutdatedError` path `openKnowledge` already owns (AC-11).
+ */
+export const INDEX_SCHEMA_VERSION = 2;
 export class SqliteIndex {
     db;
     ftsAvailable = true;
@@ -42,9 +57,9 @@ export class SqliteIndex {
         if (version === 0) {
             this.createSchema();
         }
-        else if (version < KNOWLEDGE_SCHEMA_VERSION) {
+        else if (version < INDEX_SCHEMA_VERSION) {
             // Refuse to serve; migration is rebuild-from-YAML (KG Req 11.4)
-            throw new IndexOutdatedError(version, KNOWLEDGE_SCHEMA_VERSION);
+            throw new IndexOutdatedError(version, INDEX_SCHEMA_VERSION);
         }
     }
     readSchemaVersion() {
@@ -94,6 +109,14 @@ export class SqliteIndex {
         PRIMARY KEY (file_path, entity_id)
       );
 
+      -- Which source state this cache mirrors. One row, pinned by the CHECK so a
+      -- second fingerprint cannot accumulate behind the first and be read instead
+      -- (knowledge-index-misses-merged-yaml/AC-4).
+      CREATE TABLE IF NOT EXISTS source_fingerprint (
+        id          INTEGER PRIMARY KEY CHECK (id = 1),
+        fingerprint TEXT NOT NULL
+      );
+
       CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
       CREATE INDEX IF NOT EXISTS idx_entities_confidence ON entities(confidence);
       CREATE INDEX IF NOT EXISTS idx_relationships_from ON relationships(from_entity);
@@ -114,7 +137,7 @@ export class SqliteIndex {
         }
         this.db
             .prepare('INSERT INTO _schema_version (version, created_at) VALUES (?, ?)')
-            .run(KNOWLEDGE_SCHEMA_VERSION, new Date().toISOString());
+            .run(INDEX_SCHEMA_VERSION, new Date().toISOString());
     }
     // -------------------------------------------------------------------------
     // Entities
@@ -273,7 +296,7 @@ export class SqliteIndex {
     // -------------------------------------------------------------------------
     // Rebuild
     // -------------------------------------------------------------------------
-    rebuild(entities, relationships) {
+    rebuild(entities, relationships, fingerprint = null) {
         this.db.exec('BEGIN');
         try {
             this.db.exec('DELETE FROM relationships');
@@ -281,10 +304,23 @@ export class SqliteIndex {
             this.db.exec('DELETE FROM entities');
             if (this.ftsAvailable)
                 this.db.exec('DELETE FROM entities_fts');
+            // Replacing the contents invalidates any claim about which sources they came
+            // from, so the old record goes unconditionally and the caller's — if it has
+            // one — is written in the same transaction.
+            //
+            // Inside the transaction rather than after it, because two processes rebuilding
+            // at once could otherwise pair one's contents with the other's fingerprint:
+            // A loads sources S1, B loads S2 and commits, A commits S1 over it, then the two
+            // stamp in either order. Stamping separately leaves S1's rows under S2's
+            // fingerprint — a stale read that no later open would notice, because the
+            // fingerprint matches. One transaction makes contents and record move together.
+            this.db.exec('DELETE FROM source_fingerprint');
             for (const entity of entities)
                 this.upsertEntity(entity);
             for (const rel of relationships)
                 this.upsertRelationship(rel);
+            if (fingerprint !== null)
+                this.writeFingerprint(fingerprint);
             this.db.exec('COMMIT');
         }
         catch (err) {
@@ -292,6 +328,31 @@ export class SqliteIndex {
             throw err;
         }
     }
+    // -------------------------------------------------------------------------
+    // Source freshness
+    // -------------------------------------------------------------------------
+    getSourceFingerprint() {
+        try {
+            const row = this.db
+                .prepare('SELECT fingerprint FROM source_fingerprint WHERE id = 1')
+                .get();
+            return row?.fingerprint ?? null;
+        }
+        catch {
+            // No such table: an index from before this schema version, reached by a path
+            // that skipped the version check. `null` is the fail-safe answer — it rebuilds
+            // (AC-4) — and it is why this returns a value rather than throwing.
+            return null;
+        }
+    }
+    setSourceFingerprint(fingerprint) {
+        this.writeFingerprint(fingerprint);
+    }
+    writeFingerprint(fingerprint) {
+        this.db
+            .prepare('INSERT OR REPLACE INTO source_fingerprint (id, fingerprint) VALUES (1, ?)')
+            .run(fingerprint);
+    }
     close() {
         this.db.close();
     }