autodev-cli 1.4.97 → 1.4.101

package/out/graphStore.js

@@ -23,6 +23,14 @@
  *   3. Every `evaluation` identifies a `rubric`.
  *   4. Superseded nodes remain addressable — supersede never deletes; it links a
  *      new version with a `supersedes` edge and flags the old one.
+ *
+ * MATERIALISATION (Tier 0). The log is append-only, so reload is incremental: we
+ * remember a byte offset and apply only the newly-appended tail on top of the
+ * live maps (apply is idempotent last-writer-wins) — a full clear+rebuild only
+ * happens when the file shrank (a rewrite). Two derived indexes are kept in step:
+ * an adjacency index (nodeId → incident edges) and an entity canonical-key index
+ * (name → entity id) so `UsageService` / `usage-service` / `usage service` all
+ * resolve to ONE entity.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -59,6 +67,10 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GraphStore = exports.GraphInvariantError = exports.EDGE_TYPES = exports.NODE_TYPES = void 0;
+exports.tokenize = tokenize;
+exports.canonicalKey = canonicalKey;
+exports.estimateTokens = estimateTokens;
+exports.parseSourcePath = parseSourcePath;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
@@ -75,22 +87,192 @@ exports.EDGE_TYPES = [
 class GraphInvariantError extends Error {
 }
 exports.GraphInvariantError = GraphInvariantError;
+/**
+ * Legacy display slug — kept for backward-compatible id resolution of graphs
+ * written before the canonical-key dedup landed. New entity ids use
+ * {@link canonicalKey}. `slug("UsageService")` and `slug("usage-service")`
+ * DIVERGE, which is exactly the bug canonicalKey fixes; slug survives only so
+ * old `entity:usageservice`-style ids still resolve via the fallback path.
+ */
 function slug(s) {
     return s.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
 }
+/**
+ * Split a label into normalised word tokens: break camelCase / PascalCase and
+ * acronym boundaries into words, lowercase, and split on any non-alphanumeric.
+ * `"UsageService"` → `["usage","service"]`, `"usage-service"` → `["usage","service"]`,
+ * `"HTTPServer v2"` → `["http","server","v2"]`.
+ */
+function tokenize(s) {
+    return String(s || '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase boundary
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ACRONYMWord → ACRONYM Word
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+/**
+ * Canonical dedup key for an entity name: a **sorted, de-duplicated token set**.
+ * This collapses camelCase, kebab-case and spaced spellings AND word order to a
+ * single key, so `UsageService`, `usage-service` and `usage service` map to one
+ * `entity:` id. Sorting means `"Service Usage"` also collapses onto the same key.
+ */
+function canonicalKey(s) {
+    const toks = Array.from(new Set(tokenize(s))).sort();
+    return toks.join('-').slice(0, 60) || 'x';
+}
 function shortId() { return crypto.randomBytes(5).toString('hex'); }
+/** Rough token estimate for budgeting — ~4 chars/token. */
+function estimateTokens(s) {
+    return Math.ceil((s ? s.length : 0) / 4);
+}
+// ── Tier 2 constants ─────────────────────────────────────────────────────────
+/** Node types whose `file:line` source triggers the parent_of auto-scaffold (item 1). */
+const SCAFFOLD_SOURCE_TYPES = new Set(['claim', 'artifact', 'decision', 'note']);
+/** Regenerate the materialised snapshot when the uncovered JSONL tail exceeds this many bytes. */
+const SNAPSHOT_TAIL_BYTES = 256 * 1024;
+/** …or this many ops applied since the last snapshot (item 3). */
+const SNAPSHOT_TAIL_OPS = 2000;
+/**
+ * Parse a `file:line`-style source into its cumulative path segments — the spine
+ * an auto-scaffold builds (item 1). `"src/foo/bar.ts:12"` → `["src","src/foo",
+ * "src/foo/bar.ts"]`; `"pay.ts:10"` → `["pay.ts"]`. Returns null for a URL, a
+ * source-node id (`source:ab12`), or anything that doesn't look like a path — the
+ * scaffold is deterministic and conservative, never a guess.
+ */
+function parseSourcePath(source) {
+    let s = String(source || '').trim();
+    if (!s) {
+        return null;
+    }
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) {
+        return null;
+    } // url (http://, file://, …)
+    s = s.replace(/:\d+(:\d+)?$/, ''); // strip :line(:col)
+    s = s.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    if (!s || s.includes('..')) {
+        return null;
+    }
+    // must look like a file path: has a '/' or a dotted extension (rules out `source:ab12`)
+    const looksPath = s.includes('/') || /\.[a-z0-9]+$/i.test(s);
+    if (!looksPath) {
+        return null;
+    }
+    const parts = s.split('/').filter((x) => x && x !== '.');
+    if (!parts.length || parts.length > 20) {
+        return null;
+    }
+    const cumulative = [];
+    let acc = '';
+    for (const p of parts) {
+        acc = acc ? `${acc}/${p}` : p;
+        cumulative.push(acc);
+    }
+    return cumulative;
+}
+// atomicity ceiling for a lock-free appendFileSync: writes at or below PIPE_BUF
+// (4096 on Linux) can't interleave with a concurrent writer. We warn a little
+// below it so a serialized op line that risks a torn interleave is never silent.
+const PIPE_BUF_SAFE = 4000;
+const EDGE_ONTOLOGY = {
+    produced: [{ from: ['agent_run'], to: ['artifact'] }],
+    evaluates: [{ from: ['evaluation'], to: ['artifact', 'agent_run'] }],
+    supports: [{ from: '*', to: ['claim'] }],
+    contradicts: [{ from: '*', to: ['claim'] }],
+    resolved_to: [{ from: '*', to: ['entity'] }],
+    derived_from: [{ from: '*', to: '*' }],
+    parent_of: [{ from: '*', to: '*' }],
+    depends_on: [{ from: '*', to: '*' }],
+    mentions: [{ from: '*', to: '*' }],
+    relates_to: [{ from: '*', to: '*' }],
+    revises: [{ from: '*', to: '*' }],
+    supersedes: [{ from: '*', to: '*' }],
+};
+function describeRule(r) {
+    const f = r.from === '*' ? '*' : r.from.join('|');
+    const t = r.to === '*' ? '*' : r.to.join('|');
+    return `(${f})→(${t})`;
+}
+/** @returns true if the triple is allowed, else a human-readable rejection reason. */
+function edgeAllowed(rel, fromType, toType) {
+    const rules = EDGE_ONTOLOGY[rel];
+    if (!rules) {
+        return true;
+    } // unknown relation types are validated earlier; stay permissive here
+    for (const r of rules) {
+        const okFrom = r.from === '*' || r.from.includes(fromType);
+        const okTo = r.to === '*' || r.to.includes(toType);
+        if (okFrom && okTo) {
+            return true;
+        }
+    }
+    return `edge "${rel}" expects ${rules.map(describeRule).join(' or ')}, but got (${fromType})→(${toType})`;
+}
+// ── Relevance ranking (Tier 1, item 1) ──────────────────────────────────────
+// A deliberately VECTORLESS scorer: field-weighted TF·IDF over the resident node
+// set, lifted by recency + degree. Honours PageIndex's "similarity ≠ relevance" —
+// no embeddings, fully explainable. Field weights: name > summary ≈ aliases > body.
+const FIELD_WEIGHTS = [
+    { field: 'name', weight: 3 },
+    { field: 'summary', weight: 2 },
+    { field: 'aliases', weight: 2 },
+    { field: 'body', weight: 1 },
+];
+/** Weight of the recency lift in finalScore = textScore·(1 + wRecency·decay + wDegree·log1p(deg)). */
+const W_RECENCY = 0.5;
+/** Weight of the connectivity (degree) lift. */
+const W_DEGREE = 0.3;
+/** Recency half-life-ish constant in days: exp(-ageDays/RECENCY_TAU). */
+const RECENCY_TAU_DAYS = 30;
+/** Guaranteed-inclusion floor for an exact-substring hit that scored 0 on tokens
+ *  (keeps the old substring behaviour a strict subset of ranked results). */
+const SUBSTR_FLOOR = 0.001;
+/** Provenance strength for best-first expansion: strong provenance edges outrank weak ones. */
+const EDGE_STRENGTH = {
+    supports: 3, derived_from: 3, produced: 3, evaluates: 3, depends_on: 3, parent_of: 3,
+    supersedes: 2, revises: 2, resolved_to: 2, contradicts: 2,
+    mentions: 1, relates_to: 1,
+};
 class GraphStore {
     identity;
     dir;
     file;
+    /** Disposable materialised cache for cold-start (item 3). JSONL stays the sole source of truth. */
+    snapshotFile;
+    snapshotEnabled;
+    /** Byte offset the on-disk snapshot covers (0 = none loaded/written this session). */
+    snapshotCoversBytes = 0;
+    /** Ops applied since the last snapshot was written/loaded — the regeneration trigger. */
+    opsSinceSnapshot = 0;
     nodes = new Map();
     edges = new Map();
+    /** nodeId → incident edges (both directions). Rebuilt on clear, kept in step in apply(). */
+    adjacency = new Map();
+    /** entity canonical-key → entity node id — the dedup + legacy-id resolution index. */
+    entityIndex = new Map();
     lastSize = -1;
     lastMtimeMs = -1;
-    constructor(workspaceRoot, identity) {
+    /** byte offset up to (and including) the last COMPLETE log line we've applied. */
+    lastOffset = 0;
+    /** total log ops applied since the last full rebuild (for dead-weight telemetry). */
+    appliedOps = 0;
+    /** complete-but-corrupt (JSON-unparseable) MIDDLE lines seen; a torn FINAL line is NOT counted. */
+    parseFailures = 0;
+    /** wall-clock ms of the last (incremental or full) reload. */
+    lastReplayMs = 0;
+    /** Monotonic node-set version bumped by apply() — the invalidation signal reload uses. */
+    mutationSeq = 0;
+    /** IDF over the resident node set, memoised until mutationSeq changes (item 1). */
+    idfCache = null;
+    idfCacheSeq = -1;
+    constructor(workspaceRoot, identity, opts) {
         this.identity = identity;
         this.dir = path.join(workspaceRoot, '.autodev', 'graph');
         this.file = path.join(this.dir, 'graph.jsonl');
+        this.snapshotFile = path.join(this.dir, 'graph.snapshot.json');
+        // Snapshot is on by default; pass { snapshot: false } for a pure full-replay store
+        // (used by tests to prove snapshot+tail == full replay).
+        this.snapshotEnabled = opts?.snapshot !== false;
         this.reloadIfChanged();
     }
     /** Where the graph lives (for messages). */
@@ -101,7 +283,27 @@ class GraphStore {
             fs.mkdirSync(this.dir, { recursive: true });
         }
     }
-    /** Re-materialise from disk when the log changed under us (another agent wrote). */
+    clear() {
+        this.nodes.clear();
+        this.edges.clear();
+        this.adjacency.clear();
+        this.entityIndex.clear();
+        this.appliedOps = 0;
+        this.parseFailures = 0;
+        this.lastOffset = 0;
+        this.idfCache = null;
+        this.snapshotCoversBytes = 0;
+        this.opsSinceSnapshot = 0;
+    }
+    /**
+     * Re-materialise from disk when the log changed under us (another agent wrote).
+     * INCREMENTAL: since the log is append-only we treat `lastOffset` as a byte
+     * cursor and apply only the newly-appended tail on top of the live maps (apply
+     * is idempotent). A full clear+rebuild happens only when the file shrank below
+     * our cursor (a rewrite). A torn final line is left unconsumed and picked up on
+     * a later tick once the writer finishes it. This is provably identical to a
+     * full replay because apply() is last-writer-wins and the log is append-only.
+     */
     reloadIfChanged() {
         let st = null;
         try {
@@ -111,21 +313,195 @@ class GraphStore {
             st = null;
         }
         if (!st) {
-            if (this.lastSize !== 0) {
-                this.nodes.clear();
-                this.edges.clear();
-                this.lastSize = 0;
-                this.lastMtimeMs = 0;
+            if (this.nodes.size || this.edges.size || this.lastOffset !== 0) {
+                this.clear();
             }
+            this.lastSize = 0;
+            this.lastMtimeMs = 0;
+            this.lastOffset = 0;
             return;
         }
         if (st.size === this.lastSize && st.mtimeMs === this.lastMtimeMs) {
             return;
         }
-        this.nodes.clear();
-        this.edges.clear();
-        const text = fs.readFileSync(this.file, 'utf8');
-        for (const line of text.split('\n')) {
+        const t0 = Date.now();
+        const firstLoad = this.lastSize < 0;
+        if (st.size < this.lastOffset) {
+            // the file was truncated/rewritten under us — rebuild from scratch.
+            this.clear();
+            this.loadFromScratch(st.size);
+        }
+        else if (firstLoad) {
+            // cold start — try the materialised snapshot, else full replay.
+            this.loadFromScratch(st.size);
+        }
+        else {
+            // append-only growth — fold just the new tail onto the current state.
+            this.replayRange(this.lastOffset, st.size);
+        }
+        this.lastReplayMs = Date.now() - t0;
+        this.lastSize = st.size;
+        this.lastMtimeMs = st.mtimeMs;
+        if (this.snapshotEnabled) {
+            this.maybeWriteSnapshot(st.size);
+        }
+    }
+    // ── materialised snapshot (Tier 2, item 3) ─────────────────────────────────
+    /**
+     * Cold-start load: if a valid snapshot covers a prefix of the current log, adopt
+     * it and tail-replay only the uncovered bytes; otherwise full-replay. The
+     * snapshot is a DISPOSABLE cache — a missing / stale / corrupt one simply falls
+     * back to full replay, and the JSONL is never touched.
+     */
+    loadFromScratch(size) {
+        if (this.snapshotEnabled && this.tryLoadSnapshot(size)) {
+            this.replayRange(this.lastOffset, size); // fold the tail beyond the snapshot
+            return;
+        }
+        this.clear();
+        this.replayRange(0, size);
+    }
+    /** sha256 of the first min(4096, covers) bytes of the log — the cheap rewrite guard. */
+    headSig(covers) {
+        const n = Math.min(4096, covers);
+        const fd = fs.openSync(this.file, 'r');
+        try {
+            const b = Buffer.allocUnsafe(n);
+            let read = 0;
+            while (read < n) {
+                const k = fs.readSync(fd, b, read, n - read, read);
+                if (k <= 0) {
+                    break;
+                }
+                read += k;
+            }
+            return crypto.createHash('sha256').update(b.subarray(0, read)).digest('hex');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    /**
+     * Adopt the on-disk snapshot iff it is a valid prefix of the current log:
+     * `coversBytes` in (0, size] AND the head-signature still matches (guards against
+     * a rewritten/truncated log whose prefix changed). Rebuilds the derived indexes
+     * from the resident node/edge set rather than trusting serialized indexes.
+     */
+    tryLoadSnapshot(size) {
+        try {
+            if (!fs.existsSync(this.snapshotFile)) {
+                return false;
+            }
+            const snap = JSON.parse(fs.readFileSync(this.snapshotFile, 'utf8'));
+            const covers = Number(snap.coversBytes);
+            if (!Number.isFinite(covers) || covers <= 0 || covers > size) {
+                return false;
+            }
+            if (!Array.isArray(snap.nodes) || !Array.isArray(snap.edges)) {
+                return false;
+            }
+            if (typeof snap.headSig !== 'string' || this.headSig(covers) !== snap.headSig) {
+                return false;
+            }
+            // valid → adopt. Populate the maps and rebuild adjacency + entity indexes.
+            this.clear();
+            for (const n of snap.nodes) {
+                this.nodes.set(n.id, n);
+                this.indexEntity(n);
+            }
+            for (const e of snap.edges) {
+                this.edges.set(e.id, e);
+                this.indexEdge(e);
+            }
+            this.appliedOps = this.nodes.size + this.edges.size;
+            this.mutationSeq++;
+            this.idfCache = null;
+            this.lastOffset = covers;
+            this.snapshotCoversBytes = covers;
+            this.opsSinceSnapshot = 0;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Regenerate the snapshot when the uncovered tail grew past the byte/op threshold. */
+    maybeWriteSnapshot(size) {
+        const uncoveredBytes = size - this.snapshotCoversBytes;
+        if (uncoveredBytes >= SNAPSHOT_TAIL_BYTES || this.opsSinceSnapshot >= SNAPSHOT_TAIL_OPS) {
+            this.writeSnapshot();
+        }
+    }
+    /**
+     * Write the snapshot atomically (temp file + rename) so a partial write is never
+     * visible and concurrent multi-agent regenerations can't corrupt it — the loser
+     * of a rename race simply leaves a consistent, self-describing file behind. Snaps
+     * only the byte prefix we've fully applied (`lastOffset`), so a torn final line is
+     * never captured.
+     */
+    writeSnapshot() {
+        const covers = this.lastOffset;
+        if (covers <= 0) {
+            return false;
+        }
+        try {
+            this.ensureDir();
+            const snap = {
+                coversBytes: covers,
+                generatedAt: new Date().toISOString(),
+                generatedBy: this.identity.agentId,
+                headSig: this.headSig(covers),
+                nodes: [...this.nodes.values()],
+                edges: [...this.edges.values()],
+            };
+            const tmp = `${this.snapshotFile}.${process.pid}.${shortId()}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify(snap));
+            fs.renameSync(tmp, this.snapshotFile);
+            this.snapshotCoversBytes = covers;
+            this.opsSinceSnapshot = 0;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Force a snapshot now (test hook / explicit checkpoint). No-op when snapshots are disabled. */
+    materializeSnapshot() {
+        this.reloadIfChanged();
+        return this.snapshotEnabled ? this.writeSnapshot() : false;
+    }
+    /** Read bytes [start,end), apply every COMPLETE line, and advance lastOffset past them. */
+    replayRange(start, end) {
+        if (end <= start) {
+            this.lastOffset = end;
+            return;
+        }
+        let buf;
+        const fd = fs.openSync(this.file, 'r');
+        try {
+            const len = end - start;
+            const b = Buffer.allocUnsafe(len);
+            let read = 0;
+            while (read < len) {
+                const n = fs.readSync(fd, b, read, len - read, start + read);
+                if (n <= 0) {
+                    break;
+                }
+                read += n;
+            }
+            buf = read === len ? b : b.subarray(0, read);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        // Only apply up to the last newline; the trailing bytes (if any) are a torn
+        // final line — leave the cursor before them so the next tick re-reads them.
+        const lastNl = buf.lastIndexOf(0x0A);
+        if (lastNl < 0) {
+            return;
+        } // no complete line yet
+        const complete = buf.subarray(0, lastNl + 1).toString('utf8');
+        for (const line of complete.split('\n')) {
             const t = line.trim();
             if (!t) {
                 continue;
@@ -135,21 +511,30 @@ class GraphStore {
                 op = JSON.parse(t);
             }
             catch {
+                this.parseFailures++;
                 continue;
-            } // tolerate a torn final line
+            } // a complete but corrupt MIDDLE line — surfaced in stats
             this.apply(op);
         }
-        this.lastSize = st.size;
-        this.lastMtimeMs = st.mtimeMs;
+        this.lastOffset = start + lastNl + 1;
     }
     apply(op) {
+        this.appliedOps++;
+        this.opsSinceSnapshot++;
+        this.mutationSeq++; // invalidates the IDF cache (same signal reload rides)
         if (op.op === 'node') {
             const { op: _o, ...node } = op;
             this.nodes.set(node.id, node);
+            this.indexEntity(node);
         }
         else if (op.op === 'edge') {
             const { op: _o, ...edge } = op;
+            const prev = this.edges.get(edge.id);
+            if (prev) {
+                this.unindexEdge(prev);
+            }
             this.edges.set(edge.id, edge);
+            this.indexEdge(edge);
         }
         else if (op.op === 'supersede') {
             const old = this.nodes.get(op.id);
@@ -159,19 +544,79 @@ class GraphStore {
             }
         }
     }
+    indexEntity(n) {
+        if (n.type !== 'entity') {
+            return;
+        }
+        // name wins; aliases fill gaps so they can resolve the same entity.
+        this.entityIndex.set(canonicalKey(n.name), n.id);
+        for (const a of n.aliases || []) {
+            const k = canonicalKey(a);
+            if (!this.entityIndex.has(k)) {
+                this.entityIndex.set(k, n.id);
+            }
+        }
+    }
+    indexEdge(e) {
+        this.pushAdj(e.from, e);
+        if (e.to !== e.from) {
+            this.pushAdj(e.to, e);
+        }
+    }
+    pushAdj(nid, e) {
+        const list = this.adjacency.get(nid);
+        if (list) {
+            list.push(e);
+        }
+        else {
+            this.adjacency.set(nid, [e]);
+        }
+    }
+    unindexEdge(e) {
+        for (const nid of new Set([e.from, e.to])) {
+            const list = this.adjacency.get(nid);
+            if (!list) {
+                continue;
+            }
+            const i = list.findIndex((x) => x.id === e.id);
+            if (i >= 0) {
+                list.splice(i, 1);
+            }
+        }
+    }
     append(op) {
         this.ensureDir();
-        fs.appendFileSync(this.file, JSON.stringify(op) + '\n');
+        const line = JSON.stringify(op) + '\n';
+        const bytes = Buffer.byteLength(line, 'utf8');
+        // SAFETY (Tier 0, item 3): appendFileSync is only atomic below PIPE_BUF; a
+        // larger line can interleave with a concurrent agent's append in this
+        // lock-free model. Never silent — warn on stderr with a pointer to the cause.
+        if (bytes > PIPE_BUF_SAFE) {
+            const id = op.id ?? op.op;
+            process.stderr.write(`[graph] warning: op ${id} serialises to ${bytes} bytes (> ${PIPE_BUF_SAFE}); ` +
+                `appendFileSync is not atomic above PIPE_BUF and may interleave with a concurrent writer — ` +
+                `consider shortening its body/props.\n`);
+        }
+        fs.appendFileSync(this.file, line);
+        this.apply(op);
         try {
             const st = fs.statSync(this.file);
             this.lastSize = st.size;
             this.lastMtimeMs = st.mtimeMs;
+            this.lastOffset = st.size; // our own write is fully consumed
         }
         catch { /* stat best-effort */ }
-        this.apply(op);
     }
     // ── writes ───────────────────────────────────────────────────────────────
     addNode(input) {
+        return this.addNodeInternal(input, { scaffold: true });
+    }
+    /**
+     * The write path. `scaffold:true` (the public {@link addNode}) additionally runs
+     * the deterministic parent_of auto-scaffold (item 1); the scaffold's own entity
+     * writes pass `scaffold:false` so they never recurse.
+     */
+    addNodeInternal(input, opts) {
         this.reloadIfChanged();
         const type = String(input.type || '').toLowerCase().trim();
         if (!exports.NODE_TYPES.includes(type)) {
@@ -193,16 +638,25 @@ class GraphStore {
         if (type === 'evaluation' && !String(input.rubric || '').trim()) {
             throw new GraphInvariantError('an "evaluation" needs a rubric (pass rubric:"what criteria were checked")');
         }
-        // Stable ids: entities dedupe by normalised name so resolution is idempotent;
-        // everything else gets a fresh id unless the caller pins one (upsert).
-        const id = String(input.id || '').trim()
-            || (type === 'entity' ? `entity:${slug(name)}` : `${type}:${shortId()}`);
+        // Stable ids: entities dedupe by a sorted-token-set canonical key so
+        // UsageService / usage-service / "usage service" resolve to ONE id — and old
+        // graphs stay addressable because the key index is seeded from stored names.
+        // Everything else gets a fresh id unless the caller pins one (upsert).
+        const id = String(input.id || '').trim() || this.mintId(type, name, input.aliases);
         const now = new Date().toISOString();
         const existing = this.nodes.get(id);
+        // Stamp when the summary was (re)written so staleness — gaining children or being
+        // superseded AFTER the summary — is detectable without a separate op format.
+        const summaryProvided = input.summary != null && String(input.summary).trim() !== '';
+        let props = input.props ?? existing?.props;
+        if (summaryProvided) {
+            props = { ...(props || {}), summaryAt: now };
+        }
         const node = {
             id, type, name,
             body: input.body ?? existing?.body,
-            props: input.props ?? existing?.props,
+            summary: summaryProvided ? String(input.summary).trim() : existing?.summary,
+            props,
             source: input.source ?? existing?.source,
             inference: input.inference ?? existing?.inference,
             version: input.version ?? existing?.version,
@@ -215,8 +669,92 @@ class GraphStore {
             updatedAt: now,
         };
         this.append({ op: 'node', ...node });
+        if (opts.scaffold) {
+            this.scaffold(node);
+        }
         return { node, created: !existing };
     }
+    // ── parent_of auto-scaffold from source paths / area tags (Tier 2, item 1) ──
+    /**
+     * Deterministically fill the parent_of tree from a fact's provenance — NO LLM.
+     * A `file:line` source on a claim/artifact/decision/note upserts `entity` nodes
+     * for the file and its ancestor dirs and links a `dir → file → fact` spine; a
+     * `props.area` tag upserts an area entity and parents the fact under it. Every
+     * derived node/edge carries this run's provenance and a `props.autoScaffold=true`
+     * marker, and is idempotent (deterministic ids + edge dedup) so re-adds and
+     * concurrent writers converge instead of duplicating.
+     */
+    scaffold(node) {
+        try {
+            if (SCAFFOLD_SOURCE_TYPES.has(node.type) && node.source) {
+                this.scaffoldFromSource(node);
+            }
+            const area = node.props?.area;
+            if (typeof area === 'string' && area.trim()) {
+                this.scaffoldFromArea(node, area.trim());
+            }
+        }
+        catch { /* scaffolding is best-effort — it must never fail the primary write */ }
+    }
+    scaffoldFromSource(node) {
+        const segs = parseSourcePath(node.source);
+        if (!segs || !segs.length) {
+            return;
+        }
+        let prevId = null;
+        for (let i = 0; i < segs.length; i++) {
+            const p = segs[i];
+            const isFile = i === segs.length - 1;
+            const id = `entity:path:${p}`;
+            this.addNodeInternal({ type: 'entity', name: p, id, props: { autoScaffold: true, kind: isFile ? 'file' : 'dir', path: p } }, { scaffold: false });
+            if (prevId) {
+                this.linkParentOf(prevId, id, node.source);
+            }
+            prevId = id;
+        }
+        if (prevId) {
+            this.linkParentOf(prevId, node.id, node.source);
+        }
+    }
+    scaffoldFromArea(node, area) {
+        const id = `entity:area:${slug(area)}`;
+        this.addNodeInternal({ type: 'entity', name: area, id, props: { autoScaffold: true, kind: 'area', area } }, { scaffold: false });
+        this.linkParentOf(id, node.id);
+    }
+    /** Is there already an edge of `type` from→to? (idempotency for scaffold/rollup edges). */
+    hasEdge(type, from, to) {
+        for (const e of this.adjacency.get(from) || []) {
+            if (e.type === type && e.from === from && e.to === to) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Add a parent_of edge (marked autoScaffold) unless it already exists. */
+    linkParentOf(from, to, source) {
+        if (from === to || this.hasEdge('parent_of', from, to)) {
+            return;
+        }
+        this.addEdge({ type: 'parent_of', from, to, source, props: { autoScaffold: true } });
+    }
+    /** Deterministic id for a new node: entities dedupe by canonical key (+ aliases), others are fresh. */
+    mintId(type, name, aliases) {
+        if (type !== 'entity') {
+            return `${type}:${shortId()}`;
+        }
+        const key = canonicalKey(name);
+        let existingId = this.entityIndex.get(key);
+        if (!existingId) {
+            for (const a of aliases || []) {
+                const hit = this.entityIndex.get(canonicalKey(a));
+                if (hit) {
+                    existingId = hit;
+                    break;
+                }
+            }
+        }
+        return existingId || `entity:${key}`;
+    }
     addEdge(input) {
         this.reloadIfChanged();
         const type = String(input.type || '').toLowerCase().trim();
@@ -228,12 +766,20 @@ class GraphStore {
         if (!from || !to) {
             throw new GraphInvariantError('edge needs both "from" and "to" node ids');
         }
-        if (!this.nodes.has(from)) {
+        const fromNode = this.nodes.get(from);
+        const toNode = this.nodes.get(to);
+        if (!fromNode) {
             throw new GraphInvariantError(`edge "from" node not found: ${from}`);
         }
-        if (!this.nodes.has(to)) {
+        if (!toNode) {
             throw new GraphInvariantError(`edge "to" node not found: ${to}`);
         }
+        // SAFETY (Tier 0, item 6): reject an obviously-wrong (fromType, relation,
+        // targetType) triple — e.g. evaluates: commit→task — with a helpful message.
+        const verdict = edgeAllowed(type, fromNode.type, toNode.type);
+        if (verdict !== true) {
+            throw new GraphInvariantError(verdict);
+        }
         const edge = {
             id: `edge:${shortId()}`, type, from, to,
             props: input.props, source: input.source,
@@ -269,25 +815,122 @@ class GraphStore {
             return this.nodes.get(idOrName);
         }
         const needle = idOrName.toLowerCase();
-        // exact name match first, then alias, then the entity-slug convention
+        // exact name match first, then alias, then the entity canonical-key index,
+        // then the legacy slug convention (so pre-canonical graphs still resolve).
         for (const n of this.nodes.values()) {
             if (n.name.toLowerCase() === needle) {
                 return n;
             }
         }
         for (const n of this.nodes.values()) {
-            if ((n.aliases || []).some(a => a.toLowerCase() === needle)) {
+            if ((n.aliases || []).some((a) => a.toLowerCase() === needle)) {
                 return n;
             }
         }
+        const eid = this.entityIndex.get(canonicalKey(idOrName));
+        if (eid && this.nodes.has(eid)) {
+            return this.nodes.get(eid);
+        }
         return this.nodes.get(`entity:${slug(idOrName)}`);
     }
-    query(opts) {
+    /** Incident `contradicts` edges of a node, resolved to {id,name} of the other endpoint. */
+    contradictionsFor(id) {
+        const out = [];
+        for (const e of this.adjacency.get(id) || []) {
+            if (e.type !== 'contradicts') {
+                continue;
+            }
+            const otherId = e.from === id ? e.to : e.from;
+            out.push({ id: otherId, name: this.nodes.get(otherId)?.name ?? otherId });
+        }
+        return out;
+    }
+    /** Node degree (incident edge count) — shared ranking infra for Tier 1. */
+    degree(id) {
+        return (this.adjacency.get(id) || []).length;
+    }
+    // ── relevance ranking (Tier 1, item 1) ────────────────────────────────────
+    /** IDF over the resident node set, memoised until the node set mutates. */
+    idf() {
+        if (this.idfCache && this.idfCacheSeq === this.mutationSeq) {
+            return this.idfCache;
+        }
+        const df = new Map();
+        const N = this.nodes.size || 1;
+        for (const n of this.nodes.values()) {
+            const toks = new Set([
+                ...tokenize(n.name),
+                ...tokenize(n.summary || ''),
+                ...tokenize((n.aliases || []).join(' ')),
+                ...tokenize(n.body || ''),
+            ]);
+            for (const t of toks) {
+                df.set(t, (df.get(t) || 0) + 1);
+            }
+        }
+        const idf = new Map();
+        for (const [t, d] of df) {
+            idf.set(t, Math.log(1 + N / (1 + d)));
+        }
+        this.idfCache = idf;
+        this.idfCacheSeq = this.mutationSeq;
+        return idf;
+    }
+    /** Exponential recency lift in [0,1]: 1 at now, decaying with age (τ≈30d). */
+    recencyDecay(ts) {
+        const ms = Date.parse(ts || '');
+        if (!isFinite(ms)) {
+            return 0;
+        }
+        const days = Math.max(0, (Date.now() - ms) / 86400000);
+        return Math.exp(-days / RECENCY_TAU_DAYS);
+    }
+    /** Field-weighted TF·IDF text score for a node against a set of query terms. */
+    scoreNode(n, terms, idf) {
+        if (!terms.length) {
+            return { score: 0, matched: [] };
+        }
+        const fieldTokens = {
+            name: tokenize(n.name),
+            summary: tokenize(n.summary || ''),
+            aliases: tokenize((n.aliases || []).join(' ')),
+            body: tokenize(n.body || ''),
+        };
+        let score = 0;
+        const matched = [];
+        for (const term of terms) {
+            let tf = 0;
+            for (const { field, weight } of FIELD_WEIGHTS) {
+                for (const tok of fieldTokens[field]) {
+                    if (tok === term) {
+                        tf += weight;
+                    }
+                }
+            }
+            if (tf > 0) {
+                score += tf * (idf.get(term) || 0);
+                matched.push(term);
+            }
+        }
+        return { score, matched };
+    }
+    /**
+     * Relevance-ranked query (Tier 1, item 1). OR-semantics: a node is a hit if it
+     * matches ≥1 query term OR contains the intent as an exact substring (the old
+     * behaviour, kept as a guaranteed-inclusion signal → strict superset). Ranked by
+     * `textScore·(1 + wRecency·decay + wDegree·log1p(degree))`. `mode:'recent'` keeps
+     * the pure recency order; superseded nodes hidden unless includeSuperseded.
+     */
+    scoredQuery(opts) {
         this.reloadIfChanged();
         const limit = Math.max(1, Math.min(200, opts.limit ?? 30));
         const type = opts.type ? String(opts.type).toLowerCase() : undefined;
-        const text = opts.text ? String(opts.text).toLowerCase() : undefined;
-        const out = [];
+        const text = opts.text ? String(opts.text) : undefined;
+        const textLower = text ? text.toLowerCase() : undefined;
+        const terms = text ? Array.from(new Set(tokenize(text))) : [];
+        const idf = terms.length ? this.idf() : null;
+        const mode = opts.mode ?? 'relevance';
+        const rows = [];
         for (const n of this.nodes.values()) {
             if (opts.id && n.id !== opts.id) {
                 continue;
@@ -298,22 +941,55 @@ class GraphStore {
             if (!opts.includeSuperseded && n.supersededBy) {
                 continue;
             }
-            if (text) {
-                const hay = `${n.name}\n${n.body ?? ''}\n${(n.aliases || []).join(' ')}`.toLowerCase();
-                if (!hay.includes(text)) {
+            if (textLower) {
+                const { score: ts, matched } = this.scoreNode(n, terms, idf);
+                const hay = `${n.name}\n${n.summary ?? ''}\n${n.body ?? ''}\n${(n.aliases || []).join(' ')}`.toLowerCase();
+                const substring = hay.includes(textLower);
+                let textScore = ts;
+                if (substring && textScore <= 0) {
+                    textScore = SUBSTR_FLOOR;
+                } // guaranteed inclusion
+                if (textScore <= 0) {
                     continue;
-                }
+                } // no term hit and no substring — a real miss
+                const final = textScore * (1 + W_RECENCY * this.recencyDecay(n.updatedAt) + W_DEGREE * Math.log1p(this.degree(n.id)));
+                rows.push({ node: n, score: final, textScore, matched, substring });
+            }
+            else {
+                rows.push({ node: n, score: this.recencyDecay(n.updatedAt), textScore: 0, matched: [], substring: false });
             }
-            out.push(n);
         }
-        // freshest first — recent verified facts are the most useful context
-        out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-        return out.slice(0, limit);
+        rows.sort((a, b) => {
+            if (mode === 'recent' || !textLower) {
+                const r = (b.node.updatedAt || '').localeCompare(a.node.updatedAt || '');
+                if (r !== 0) {
+                    return r;
+                }
+                return b.score - a.score;
+            }
+            if (b.score !== a.score) {
+                return b.score - a.score;
+            }
+            return (b.node.updatedAt || '').localeCompare(a.node.updatedAt || '');
+        });
+        return rows.slice(0, limit);
+    }
+    /**
+     * Search nodes by type and/or text. Thin wrapper over {@link scoredQuery}: with
+     * `text` it returns relevance-ranked hits (item 1); without, recency order. The
+     * old pure-substring behaviour survives as a guaranteed-inclusion subset.
+     */
+    query(opts) {
+        return this.scoredQuery(opts).map((r) => r.node);
     }
     /**
      * Bounded neighbourhood around a node — the playbook's "context construction
      * from a graph": resolve the entity, expand a hop or two over allowed edge
      * types, and return a small, citable subgraph rather than the whole graph.
+     * Uses the adjacency index (O(visited degree), not O(E·hops)) and returns the
+     * BFS hop-distance per node so the caller can rank/token-budget the result.
+     * `includeConflicts` (default true) always follows `contradicts` edges so a
+     * conflicting claim can never be hidden by an `edgeTypes` filter.
      */
     neighbors(opts) {
         this.reloadIfChanged();
@@ -324,57 +1000,529 @@ class GraphStore {
         const hops = Math.max(1, Math.min(3, opts.hops ?? 1));
         const edgeLimit = Math.max(1, Math.min(200, opts.limit ?? 40));
         const allow = opts.edgeTypes && opts.edgeTypes.length
-            ? new Set(opts.edgeTypes.map(e => e.toLowerCase())) : null;
-        const seen = new Set([center.id]);
+            ? new Set(opts.edgeTypes.map((e) => e.toLowerCase())) : null;
+        if (allow && opts.includeConflicts !== false) {
+            allow.add('contradicts');
+        }
+        const dist = new Map([[center.id, 0]]);
         const nodeOut = new Map([[center.id, center]]);
         const edgeOut = [];
+        const edgeSeen = new Set();
         let frontier = [center.id];
         for (let h = 0; h < hops && edgeOut.length < edgeLimit; h++) {
             const next = [];
-            for (const e of this.edges.values()) {
-                if (allow && !allow.has(e.type)) {
-                    continue;
-                }
-                const touchesFrontier = frontier.includes(e.from) || frontier.includes(e.to);
-                if (!touchesFrontier) {
-                    continue;
-                }
-                if (!edgeOut.find(x => x.id === e.id)) {
-                    edgeOut.push(e);
-                    if (edgeOut.length >= edgeLimit) {
-                        break;
+            for (const nid of frontier) {
+                for (const e of this.adjacency.get(nid) || []) {
+                    if (allow && !allow.has(e.type)) {
+                        continue;
                     }
-                }
-                for (const nid of [e.from, e.to]) {
-                    if (!seen.has(nid)) {
-                        seen.add(nid);
-                        const nn = this.nodes.get(nid);
+                    if (!edgeSeen.has(e.id)) {
+                        edgeSeen.add(e.id);
+                        edgeOut.push(e);
+                        if (edgeOut.length >= edgeLimit) {
+                            break;
+                        }
+                    }
+                    const other = e.from === nid ? e.to : e.from;
+                    if (!nodeOut.has(other)) {
+                        const nn = this.nodes.get(other);
                         if (nn) {
-                            nodeOut.set(nid, nn);
-                            next.push(nid);
+                            nodeOut.set(other, nn);
+                            dist.set(other, h + 1);
+                            next.push(other);
                         }
                     }
                 }
+                if (edgeOut.length >= edgeLimit) {
+                    break;
+                }
             }
             frontier = next;
             if (!frontier.length) {
                 break;
             }
         }
-        return { center, nodes: [...nodeOut.values()], edges: edgeOut };
+        return { center, nodes: [...nodeOut.values()], edges: edgeOut, dist: Object.fromEntries(dist) };
+    }
+    // ── summaries (Tier 1, item 3) ────────────────────────────────────────────
+    /** Distinct neighbour nodes of a node (via the adjacency index). */
+    neighborNodes(id) {
+        const out = [];
+        const seen = new Set();
+        for (const e of this.adjacency.get(id) || []) {
+            const other = e.from === id ? e.to : e.from;
+            if (seen.has(other)) {
+                continue;
+            }
+            seen.add(other);
+            const nn = this.nodes.get(other);
+            if (nn) {
+                out.push(nn);
+            }
+        }
+        return out;
+    }
+    /** `parent_of` children of a node (this node as the parent). */
+    childrenOf(id) {
+        const out = [];
+        for (const e of this.adjacency.get(id) || []) {
+            if (e.type === 'parent_of' && e.from === id) {
+                const c = this.nodes.get(e.to);
+                if (c) {
+                    out.push(c);
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * DETERMINISTIC one-line rollup for an interior/hub node with NO authored
+     * summary — NO LLM call. Synthesised from structure: child (or, absent
+     * `parent_of` children, neighbour) type counts + the top child names by degree.
+     * Returns undefined for a leaf/low-degree node (nothing to summarise).
+     */
+    rollupSummary(id) {
+        let kids = this.childrenOf(id);
+        if (!kids.length) {
+            if (this.degree(id) < 3) {
+                return undefined;
+            } // a leaf — no structure to roll up
+            kids = this.neighborNodes(id);
+        }
+        if (!kids.length) {
+            return undefined;
+        }
+        const counts = new Map();
+        for (const k of kids) {
+            counts.set(k.type, (counts.get(k.type) || 0) + 1);
+        }
+        const countStr = [...counts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([t, c]) => `${c} ${t}`)
+            .join(', ');
+        const top = [...kids]
+            .sort((a, b) => this.degree(b.id) - this.degree(a.id))
+            .slice(0, 3)
+            .map((k) => k.name);
+        return `${countStr} · top: ${top.join(', ')}`;
+    }
+    /**
+     * The summary to SHOW for a node: the authored one if present, else the
+     * deterministic structural rollup (flagged synthesized), else nothing.
+     */
+    effectiveSummary(node) {
+        if (node.summary && node.summary.trim()) {
+            return { text: node.summary.trim(), synthesized: false };
+        }
+        const roll = this.rollupSummary(node.id);
+        return roll ? { text: roll, synthesized: true } : undefined;
+    }
+    /**
+     * An AUTHORED summary is stale when the node has been superseded, or gained a
+     * `parent_of` child AFTER the summary was written (`props.summaryAt`). Nodes
+     * with no authored summary are "unsummarized", not stale.
+     */
+    summaryStale(node) {
+        if (!node.summary || !node.summary.trim()) {
+            return false;
+        }
+        if (node.supersededBy) {
+            return true;
+        }
+        const at = Date.parse(String(node.props?.summaryAt ?? node.updatedAt));
+        if (!isFinite(at)) {
+            return false;
+        }
+        for (const e of this.adjacency.get(node.id) || []) {
+            if (e.type === 'parent_of' && e.from === node.id && Date.parse(e.createdAt) > at) {
+                return true;
+            }
+        }
+        return false;
+    }
+    mapEntry(node) {
+        const es = this.effectiveSummary(node);
+        return {
+            id: node.id, type: node.type, name: node.name,
+            summary: es?.text, synthesized: es?.synthesized,
+            stale: this.summaryStale(node) || undefined,
+            degree: this.degree(node.id),
+        };
+    }
+    // ── cold-start anchor index (Tier 1, item 2) ───────────────────────────────
+    /**
+     * "Where do I start" for an agent with no id/name in hand. Ranks entities (and
+     * any node when `focusType` unset) by degree() over the adjacency index, and
+     * bundles the open `question`s, freshest `decision`s, and live `contradicts`
+     * pairs it already knows how to find. Purely read-side; render via graphRender.
+     */
+    map(opts) {
+        this.reloadIfChanged();
+        const topK = Math.max(1, Math.min(50, opts?.maxChildren ?? 10));
+        const focus = opts?.focusType ? String(opts.focusType).toLowerCase() : undefined;
+        const live = [...this.nodes.values()].filter((n) => !n.supersededBy);
+        const hubs = live
+            .filter((n) => this.degree(n.id) > 0 && (!focus || n.type === focus))
+            .sort((a, b) => this.degree(b.id) - this.degree(a.id) || (b.updatedAt || '').localeCompare(a.updatedAt || ''))
+            .slice(0, topK)
+            .map((n) => this.mapEntry(n));
+        const freshest = (t) => live
+            .filter((n) => n.type === t)
+            .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''))
+            .slice(0, topK)
+            .map((n) => this.mapEntry(n));
+        // live (unsuperseded on both ends) contradicts pairs, deduped
+        const seenPair = new Set();
+        const contradictions = [];
+        for (const e of this.edges.values()) {
+            if (e.type !== 'contradicts') {
+                continue;
+            }
+            const a = this.nodes.get(e.from);
+            const b = this.nodes.get(e.to);
+            if (!a || !b || a.supersededBy || b.supersededBy) {
+                continue;
+            }
+            const key = [a.id, b.id].sort().join('|');
+            if (seenPair.has(key)) {
+                continue;
+            }
+            seenPair.add(key);
+            contradictions.push({ a: { id: a.id, name: a.name }, b: { id: b.id, name: b.name } });
+            if (contradictions.length >= topK) {
+                break;
+            }
+        }
+        const pinned = this.pinnedNodes().slice(0, topK).map((n) => this.mapEntry(n));
+        return { pinned, hubs, questions: freshest('question'), decisions: freshest('decision'), contradictions };
+    }
+    // ── pinned "core" tier (Tier 2, item 4) ────────────────────────────────────
+    /** A node is pinned by `props.pinned===true` or by the reserved `props.area==='core'`. */
+    isPinnedNode(n) {
+        const p = (n.props || {});
+        return p.pinned === true || p.area === 'core';
+    }
+    /** Live pinned nodes (project invariants) — always prepended within budget. */
+    pinnedNodes() {
+        this.reloadIfChanged();
+        return [...this.nodes.values()]
+            .filter((n) => !n.supersededBy && this.isPinnedNode(n))
+            .sort((a, b) => this.degree(b.id) - this.degree(a.id) || (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+    }
+    /** Set/clear the pin flag on a node (upsert; the node stays otherwise unchanged). */
+    pin(idOrName, pinned = true) {
+        this.reloadIfChanged();
+        const n = this.getNode(idOrName);
+        if (!n) {
+            throw new GraphInvariantError(`${pinned ? 'pin' : 'unpin'}: node not found: ${idOrName}`);
+        }
+        const { node } = this.addNodeInternal({ type: n.type, name: n.name, id: n.id, props: { ...(n.props || {}), pinned } }, { scaffold: false });
+        return node;
+    }
+    // ── reasoning-based best-first retrieval (Tier 1, item 4) ──────────────────
+    /**
+     * Vectorless, explainable, CITABLE retrieval — the PageIndex centrepiece done
+     * without embeddings and without a server-side model (the calling agent is the
+     * reasoner). Seed with the item-1 ranked query on `intent`, then best-first
+     * expand a relevance-priority frontier: pop the best node, expand 1 hop
+     * (strong provenance edges — supports/derived_from/produced/evaluates/
+     * depends_on/parent_of — before weak relates_to/mentions), score newly-found
+     * nodes against the intent, push. Stop at node_budget. Each returned row cites
+     * `[id]` with the matched terms and the edge-path from its seed.
+     */
+    search(opts) {
+        this.reloadIfChanged();
+        const budget = Math.max(1, Math.min(60, opts.nodeBudget ?? 12));
+        const hops = Math.max(1, Math.min(4, opts.hops ?? 2));
+        const intent = String(opts.intent || '');
+        const terms = Array.from(new Set(tokenize(intent)));
+        const idf = this.idf();
+        const rows = new Map();
+        const frontier = [];
+        const seedK = Math.min(budget, Math.max(3, Math.ceil(budget / 2)));
+        for (const s of this.scoredQuery({ text: intent, mode: 'relevance', limit: seedK })) {
+            rows.set(s.node.id, { node: s.node, score: s.score, matched: s.matched, seedId: s.node.id, depth: 0, path: [] });
+            frontier.push({ id: s.node.id, score: s.score, depth: 0 });
+        }
+        while (frontier.length && rows.size < budget) {
+            frontier.sort((a, b) => b.score - a.score);
+            const cur = frontier.shift();
+            if (cur.depth >= hops) {
+                continue;
+            }
+            const curRec = rows.get(cur.id);
+            if (!curRec) {
+                continue;
+            }
+            const incident = [...(this.adjacency.get(cur.id) || [])]
+                .sort((x, y) => (EDGE_STRENGTH[y.type] || 0) - (EDGE_STRENGTH[x.type] || 0));
+            for (const e of incident) {
+                if (rows.size >= budget) {
+                    break;
+                }
+                const otherId = e.from === cur.id ? e.to : e.from;
+                if (rows.has(otherId)) {
+                    continue;
+                }
+                const other = this.nodes.get(otherId);
+                if (!other || other.supersededBy) {
+                    continue;
+                } // superseded hidden by default
+                const { score: ts, matched } = this.scoreNode(other, terms, idf);
+                const textScore = ts > 0 ? ts : SUBSTR_FLOOR * 0.5; // reachable-but-off-intent nodes stay citable, ranked low
+                const final = textScore * (1 + W_RECENCY * this.recencyDecay(other.updatedAt) + W_DEGREE * Math.log1p(this.degree(otherId)));
+                const dir = e.from === cur.id ? 'out' : 'in';
+                const path = [...curRec.path, `${e.type}${dir === 'out' ? '→' : '←'} ${other.type}:${other.id}`];
+                rows.set(otherId, { node: other, score: final, matched, seedId: curRec.seedId, depth: cur.depth + 1, path, via: { edge: e.type, fromId: cur.id, dir } });
+                frontier.push({ id: otherId, score: final, depth: cur.depth + 1 });
+            }
+        }
+        const out = [...rows.values()]
+            .sort((a, b) => b.score - a.score)
+            .map((r) => {
+            const es = this.effectiveSummary(r.node);
+            return {
+                id: r.node.id, type: r.node.type, name: r.node.name,
+                score: r.score, matched: r.matched,
+                summary: es?.text, synthesized: es?.synthesized,
+                inference: r.node.inference,
+                seedId: r.seedId, via: r.via, path: r.path,
+                conflicts: this.contradictionsFor(r.node.id),
+            };
+        });
+        return { intent, terms, budget, hops, rows: out };
+    }
+    // ── navigable table-of-contents (Tier 2, item 2) ───────────────────────────
+    parentOfChildIds(id) {
+        const out = [];
+        for (const e of this.adjacency.get(id) || []) {
+            if (e.type === 'parent_of' && e.from === id) {
+                out.push(e.to);
+            }
+        }
+        return out;
+    }
+    hasParentOfParent(id) {
+        return (this.adjacency.get(id) || []).some((e) => e.type === 'parent_of' && e.to === id);
+    }
+    hasParentOfChild(id) {
+        return (this.adjacency.get(id) || []).some((e) => e.type === 'parent_of' && e.from === id);
+    }
+    /** Connected components of `pool` over the given (undirected) edge types. */
+    components(pool, edgeTypes) {
+        const idset = new Set(pool.map((n) => n.id));
+        const parent = new Map();
+        const find = (x) => { while (parent.get(x) !== x) {
+            parent.set(x, parent.get(parent.get(x)));
+            x = parent.get(x);
+        } return x; };
+        for (const n of pool) {
+            parent.set(n.id, n.id);
+        }
+        const allow = new Set(edgeTypes);
+        for (const e of this.edges.values()) {
+            if (!allow.has(e.type) || !idset.has(e.from) || !idset.has(e.to)) {
+                continue;
+            }
+            const ra = find(e.from), rb = find(e.to);
+            if (ra !== rb) {
+                parent.set(ra, rb);
+            }
+        }
+        const groups = new Map();
+        for (const n of pool) {
+            const r = find(n.id);
+            const g = groups.get(r);
+            if (g) {
+                g.push(n);
+            }
+            else {
+                groups.set(r, [n]);
+            }
+        }
+        return [...groups.values()];
+    }
+    /**
+     * Depth-bounded, summarized hierarchy (PageIndex-style "text-stripped overview →
+     * drill"). The spine is `parent_of` (roots = entities with no incoming parent_of);
+     * where that spine is sparse the uncovered remainder falls back to deterministic
+     * clustering (by `props.area`, else connected components over relates_to/
+     * depends_on). Each level shows the top `maxChildren` by degree and collapses the
+     * rest to `+K more`. Summaries reuse {@link effectiveSummary}. Pass `root` to
+     * expand one branch.
+     */
+    toc(opts) {
+        this.reloadIfChanged();
+        const depth = Math.max(1, Math.min(6, opts?.depth ?? 2));
+        const maxChildren = Math.max(1, Math.min(50, opts?.maxChildren ?? 8));
+        const focus = opts?.focusType ? String(opts.focusType).toLowerCase() : undefined;
+        const build = (n, d, seen) => {
+            seen.add(n.id);
+            let kids = this.parentOfChildIds(n.id)
+                .map((id) => this.nodes.get(id))
+                .filter((c) => !!c && !c.supersededBy && !seen.has(c.id));
+            if (focus) {
+                kids = kids.filter((c) => c.type === focus);
+            }
+            kids.sort((a, b) => this.degree(b.id) - this.degree(a.id) || (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+            const childCount = kids.length;
+            const cap = d > 1 ? maxChildren : 0;
+            const shown = kids.slice(0, cap);
+            const children = shown.map((c) => build(c, d - 1, seen));
+            const es = this.effectiveSummary(n);
+            const more = childCount - shown.length;
+            return { id: n.id, type: n.type, name: n.name, summary: es?.text, synthesized: es?.synthesized, childCount, children, moreChildren: more > 0 ? more : undefined };
+        };
+        if (opts?.root) {
+            const r = this.getNode(opts.root);
+            return r ? { roots: [build(r, depth, new Set())] } : { roots: [] };
+        }
+        const seen = new Set();
+        const live = [...this.nodes.values()].filter((n) => !n.supersededBy);
+        const spineRoots = live
+            .filter((n) => this.hasParentOfChild(n.id) && !this.hasParentOfParent(n.id))
+            .sort((a, b) => this.degree(b.id) - this.degree(a.id) || (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+        const roots = spineRoots.map((r) => build(r, depth, seen));
+        // Fall back to clustering for significant nodes the spine didn't cover.
+        const synthCluster = (id, label, members) => {
+            const sorted = [...members].sort((a, b) => this.degree(b.id) - this.degree(a.id));
+            const shown = sorted.slice(0, maxChildren);
+            const children = shown.map((m) => build(m, 1, seen));
+            const more = members.length - shown.length;
+            return { id, type: 'cluster', name: label, summary: `${members.length} node(s)`, childCount: members.length, children, moreChildren: more > 0 ? more : undefined };
+        };
+        const remaining = live.filter((n) => !seen.has(n.id) && this.degree(n.id) > 0);
+        const clusterRoots = [];
+        if (remaining.length) {
+            const byArea = new Map();
+            const rest = [];
+            for (const n of remaining) {
+                const area = typeof n.props?.area === 'string' ? n.props.area : undefined;
+                if (area) {
+                    const g = byArea.get(area);
+                    if (g) {
+                        g.push(n);
+                    }
+                    else {
+                        byArea.set(area, [n]);
+                    }
+                }
+                else {
+                    rest.push(n);
+                }
+            }
+            for (const [area, members] of byArea) {
+                clusterRoots.push(synthCluster(`cluster:area:${slug(area)}`, `area: ${area}`, members));
+            }
+            for (const comp of this.components(rest, ['relates_to', 'depends_on'])) {
+                if (comp.length === 1) {
+                    continue;
+                } // a lone node with only foreign edges — not a cluster
+                const rep = [...comp].sort((a, b) => this.degree(b.id) - this.degree(a.id))[0];
+                clusterRoots.push(synthCluster(`cluster:${rep.id}`, `cluster: ${rep.name}`, comp));
+            }
+            clusterRoots.sort((a, b) => b.childCount - a.childCount);
+        }
+        return { roots: [...roots, ...clusterRoots], clustered: roots.length === 0 && clusterRoots.length > 0 };
+    }
+    // ── hierarchical rollup / summary nodes (Tier 2, item 5) ────────────────────
+    /** Deterministic id for a cluster's rollup node, so concurrent rollups upsert not duplicate. */
+    rollupId(center) {
+        const key = center.id.startsWith('entity:') ? center.id.slice('entity:'.length) : center.id.replace(/[^a-z0-9]+/gi, '-');
+        return `summary:${key || 'x'}`;
+    }
+    /** parent_of descendants of a node (transitive), excluding itself. */
+    descendants(id) {
+        const out = new Set();
+        const stack = [id];
+        while (stack.length) {
+            const cur = stack.pop();
+            for (const cid of this.parentOfChildIds(cur)) {
+                if (cid !== id && !out.has(cid)) {
+                    out.add(cid);
+                    stack.push(cid);
+                }
+            }
+        }
+        return [...out];
+    }
+    rollupFromMembers(memberIds) {
+        const counts = new Map();
+        for (const mid of memberIds) {
+            const n = this.nodes.get(mid);
+            if (n) {
+                counts.set(n.type, (counts.get(n.type) || 0) + 1);
+            }
+        }
+        const countStr = [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([t, c]) => `${c} ${t}`).join(', ');
+        const top = memberIds.map((id) => this.nodes.get(id)).filter((n) => !!n)
+            .sort((a, b) => this.degree(b.id) - this.degree(a.id)).slice(0, 3).map((n) => n.name);
+        return `${memberIds.length} member(s): ${countStr}${top.length ? ` · top: ${top.join(', ')}` : ''}`;
+    }
+    /** The rollup/summary node for a cluster centre, if one has been created. */
+    rollupNodeFor(idOrName) {
+        this.reloadIfChanged();
+        const c = this.getNode(idOrName);
+        if (!c) {
+            return undefined;
+        }
+        return this.nodes.get(this.rollupId(c));
+    }
+    /**
+     * Create or upsert a hierarchical rollup for a cluster (item 5). The cluster is a
+     * centre entity's `parent_of` descendants, or — absent a spine — its N-hop
+     * neighbourhood. The rollup is a `note` with `props.rollup=true` and a
+     * DETERMINISTIC id (`summary:<centre-key>`) so concurrent rollups of the same
+     * cluster upsert rather than duplicate; it links `derived_from → each member`
+     * (members stay fully addressable in `props.members`) and hangs under the centre
+     * via `parent_of` so it's discoverable in the TOC. Summary text is agent-supplied
+     * or the deterministic Tier-1 rollup (no LLM on the default path).
+     */
+    rollup(opts) {
+        this.reloadIfChanged();
+        const center = opts.idOrName ? this.getNode(opts.idOrName) : undefined;
+        if (!center) {
+            throw new GraphInvariantError(`graph_rollup: centre node not found: ${opts.idOrName ?? ''}`);
+        }
+        const id = this.rollupId(center);
+        let members = this.descendants(center.id);
+        if (!members.length) {
+            const hops = Math.max(1, Math.min(3, opts.hops ?? 1));
+            const res = this.neighbors({ idOrName: center.id, hops, limit: 500 });
+            members = (res ? res.nodes : []).map((n) => n.id).filter((mid) => mid !== center.id);
+        }
+        members = members.filter((mid) => mid !== id && !mid.startsWith('summary:'));
+        const summaryText = (opts.summary && opts.summary.trim())
+            ? opts.summary.trim()
+            : (this.rollupSummary(center.id) || this.rollupFromMembers(members));
+        const { node, created } = this.addNodeInternal({
+            type: 'note', id, name: `Rollup: ${center.name}`,
+            summary: summaryText,
+            props: { rollup: true, of: center.id, members },
+        }, { scaffold: false });
+        this.linkParentOf(center.id, id);
+        for (const m of members) {
+            if (m === id || !this.nodes.has(m)) {
+                continue;
+            }
+            if (!this.hasEdge('derived_from', id, m)) {
+                this.addEdge({ type: 'derived_from', from: id, to: m });
+            }
+        }
+        return { node, members, created };
     }
     stats() {
         this.reloadIfChanged();
         const nodesByType = {};
         const edgesByType = {};
-        let superseded = 0, openQuestions = 0;
-        const touched = new Set();
+        let superseded = 0, openQuestions = 0, estTokens = 0;
         for (const e of this.edges.values()) {
             edgesByType[e.type] = (edgesByType[e.type] || 0) + 1;
-            touched.add(e.from);
-            touched.add(e.to);
+            estTokens += estimateTokens(`${e.type}${e.from}${e.to}${e.source ?? ''}`);
         }
-        let isolated = 0;
+        // Types that benefit most from a summary (item 3).
+        const SUMMARY_TYPES = new Set(['entity', 'decision', 'question', 'artifact', 'agent_run']);
+        let isolated = 0, unsummarized = 0, staleSummaries = 0, spinelessHubs = 0, pinned = 0;
         for (const n of this.nodes.values()) {
             nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
             if (n.supersededBy) {
@@ -383,14 +1531,42 @@ class GraphStore {
             if (n.type === 'question' && !n.supersededBy) {
                 openQuestions++;
             }
-            if (!touched.has(n.id) && !n.supersededBy) {
+            if (this.degree(n.id) === 0 && !n.supersededBy) {
                 isolated++;
             }
+            const hasSummary = !!(n.summary && n.summary.trim());
+            if (!n.supersededBy && SUMMARY_TYPES.has(n.type) && !hasSummary) {
+                unsummarized++;
+            }
+            if (hasSummary && this.summaryStale(n)) {
+                staleSummaries++;
+            }
+            if (!n.supersededBy && this.isPinnedNode(n)) {
+                pinned++;
+            }
+            // A hub with children (degree≥3) but NO parent_of spine — nudge to scaffold the tree (item 1).
+            if (!n.supersededBy && n.type === 'entity' && this.degree(n.id) >= 3
+                && !this.hasParentOfChild(n.id) && !this.hasParentOfParent(n.id)) {
+                spinelessHubs++;
+            }
+            estTokens += estimateTokens(`${n.name}${n.summary ?? ''}${n.body ?? ''}`);
         }
         const contradictions = edgesByType['contradicts'] || 0;
+        const live = this.nodes.size + this.edges.size;
+        const deadWeight = Math.max(0, this.appliedOps - live);
         return {
             nodeCount: this.nodes.size, edgeCount: this.edges.size,
             nodesByType, edgesByType, superseded, isolated, contradictions, openQuestions,
+            unsummarized, staleSummaries,
+            spinelessHubs, pinned,
+            fileBytes: this.lastSize < 0 ? 0 : this.lastSize,
+            totalOps: this.appliedOps,
+            deadWeight,
+            deadWeightRatio: this.appliedOps ? deadWeight / this.appliedOps : 0,
+            lastReplayMs: this.lastReplayMs,
+            estTokens,
+            parseFailures: this.parseFailures,
+            tornFinalLine: this.lastOffset < this.lastSize,
         };
     }
 }