@spexcode/spec-core 0.6.7 → 0.6.8

package/dist/anchors.d.ts

@@ -9,8 +9,8 @@ export type Unit = {
 export type Extractor = {
     id: string;
     claims(ext: string): boolean;
-    ready(): true | string;
-    extract(content: string, filename: string): Unit[];
+    ready(): true | string | Promise<true | string>;
+    extract(content: string, filename: string): Unit[] | Promise<Unit[]>;
     memoKey: (filename: string) => string;
 };
 export type CodeEntry = {
@@ -56,6 +56,16 @@ export type LangSpec = {
 export declare function heuristicExtractor(spec: LangSpec): Extractor;
 export declare const JS_LANG_R5B: LangSpec;
 export declare const PYTHON_LANG: LangSpec;
+type TreeSitterNode = any;
+export type TreeSitterLanguageRow = {
+    id: string;
+    extensions: string[];
+    grammar: string;
+    schema: string;
+    units(root: TreeSitterNode): Unit[];
+};
+export declare const TREE_SITTER_ROWS: TreeSitterLanguageRow[];
+export declare function treeSitterExtractor(row: TreeSitterLanguageRow): Extractor;
 export declare function extractors(root: string): Extractor[];
 export declare function extractorFor(regs: Extractor[], ext: string): Extractor | null;
 export declare const extOf: (path: string) => string;
@@ -92,3 +102,4 @@ export type AnchorHitQuery = {
 export declare function anchorHitQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<AnchorHit[][]>;
 export declare function anchorHitExists(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<boolean[]>;
 export declare function anchorHitCommits(root: string, win: DriftPathEvent[], symbols: string[], regs: Extractor[]): Promise<AnchorHit[]>;
+export {};

package/dist/anchors.js

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { gitRequiredA, gitObjectFormat, isGitObjectId, batchRevisionOids, batchBlobTexts, combinedDiffOwnedChanges, driftPathWindow, readImmutableHunkFacts, persistImmutableHunkFacts, withEventLedgerBuild } from './git.js';
 const RS = '\x1e';
@@ -50,7 +50,9 @@ export function parseRelation(raws, relation) {
     }
     return { entries: order.map((p) => ({ path: p, selectors: byPath.get(p).selectors })), problems };
 }
-// ---- extractor: ts-ast (the designated extractor for the JS family) ----
+// ---- legacy extractor: ts-ast ----
+// Kept as a public compatibility helper only. The production language registry below routes every shipped
+// language through Tree-sitter WASM and never selects this host-dependent path.
 // Parse-only via the HOST project's own typescript, so the parse matches what the project itself compiles
 // with. If it cannot resolve, ready() returns a loud unverified verdict and lint skips these anchors
 // without crashing (no bundled compiler, regex fallback, or fake pass for JS).
@@ -310,9 +312,7 @@ export function heuristicExtractor(spec) {
         },
     };
 }
-// The validated JS-family reference row (R5b: name precision 99.7% / recall 100% / range 98.9% on the
-// 41-file oracle) — NOT registered for JS (ts-ast is designated); kept as the engine's reference shape
-// and the benchmark's scoring subject.
+// Historical JS-family reference row retained for compatibility callers; not a production registry row.
 export const JS_LANG_R5B = {
     id: 'heuristic-js',
     extensions: [...JS_EXTS],
@@ -330,9 +330,7 @@ export const JS_LANG_R5B = {
     },
     boundary: /^(?:[A-Za-z_$]|\/\/|\/\*)/,
 };
-// Python is a LangSpec DATA row over the same generic engine: declaration names come from patterns;
-// significant indentation supplies lexical qualification and ranges. It is intentionally structural,
-// not a Python runtime or full grammar (the user-facing boundary is documented by [[code-anchor]]).
+// Historical Python row retained for compatibility callers; Tree-sitter owns shipped Python anchors.
 const PY_ID = String.raw `[\p{ID_Start}_][\p{ID_Continue}_]*`;
 export const PYTHON_LANG = {
     id: 'heuristic-python',
@@ -349,15 +347,313 @@ export const PYTHON_LANG = {
     indentScopes: { decorator: /^\s*@/ },
     boundary: /^\S/,
 };
+let treeSitterModulePromise;
+let treeSitterInitPromise;
+const treeSitterLanguagePromises = new Map();
+function treeSitterRuntimePath() {
+    const require = createRequire(import.meta.url);
+    return require.resolve('@vscode/tree-sitter-wasm');
+}
+async function treeSitterModule() {
+    if (!treeSitterModulePromise)
+        treeSitterModulePromise = import(treeSitterRuntimePath()).then((m) => m.default ?? m);
+    return treeSitterModulePromise;
+}
+async function treeSitterLanguage(row) {
+    const existing = treeSitterLanguagePromises.get(row.grammar);
+    if (existing)
+        return existing;
+    const pending = (async () => {
+        const mod = await treeSitterModule();
+        if (!treeSitterInitPromise) {
+            const runtime = dirname(treeSitterRuntimePath());
+            treeSitterInitPromise = mod.Parser.init({ locateFile: (file) => join(runtime, file) }).then(() => mod);
+        }
+        await treeSitterInitPromise;
+        return mod.Language.load(join(dirname(treeSitterRuntimePath()), `tree-sitter-${row.grammar}.wasm`));
+    })();
+    treeSitterLanguagePromises.set(row.grammar, pending);
+    return pending;
+}
+const nodeField = (node, field) => node?.childForFieldName?.(field) ?? null;
+const nodeChildren = (node) => (node?.namedChildren ?? []).filter(Boolean);
+const nodeAllChildren = (node) => (node?.children ?? []).filter(Boolean);
+const nodeText = (node) => node?.text ?? '';
+const treeHasSyntaxError = (root) => {
+    if (root?.hasError)
+        return true;
+    const pending = [root];
+    while (pending.length) {
+        const node = pending.pop();
+        if (node.isError || node.isMissing)
+            return true;
+        pending.push(...nodeAllChildren(node));
+    }
+    return false;
+};
+const nodeLineRange = (node, start = node.startPosition.row + 1, end = node.endPosition.row + 1) => ({ start, end });
+const simpleName = (node) => nodeText(node).replace(/^\s+|\s+$/g, '');
+const lastTypeName = (text) => {
+    const clean = text.replace(/^\s*\(/, '').replace(/\)\s*$/, '').replace(/^\s*[*&]+/, '');
+    const base = clean.split(/[.[\]<>\s]/, 1)[0];
+    return (base.split('.').pop() ?? base).replace(/[^\p{L}\p{N}_$]/gu, '');
+};
+function tsTreeUnits(root) {
+    const units = [];
+    const add = (name, kind, node, typeOnly = false, start) => {
+        if (!name)
+            return;
+        units.push({ name, kind, ...nodeLineRange(node, start), ...(typeOnly ? { typeOnly: true } : {}) });
+    };
+    const methodUnits = (className, body) => {
+        for (const member of nodeChildren(body)) {
+            if (member.type !== 'method_definition' || !nodeField(member, 'body'))
+                continue;
+            const name = nodeText(nodeField(member, 'name')) || nodeText(member.namedChildren?.[0]) || '(computed)';
+            add(`${className}.${name === 'constructor' ? 'constructor' : name}`, 'method', member);
+        }
+    };
+    for (const raw of nodeChildren(root)) {
+        const top = raw.type === 'export_statement' ? nodeChildren(raw) : [raw];
+        for (const node of top) {
+            if (node.type === 'function_declaration')
+                add(nodeText(nodeField(node, 'name')), 'function', node);
+            else if (node.type === 'class_declaration') {
+                const name = nodeText(nodeField(node, 'name'));
+                add(name, 'class', node);
+                methodUnits(name, nodeField(node, 'body'));
+            }
+            else if (node.type === 'lexical_declaration' || node.type === 'variable_declaration') {
+                for (const decl of nodeChildren(node).filter((child) => child.type === 'variable_declarator')) {
+                    const name = nodeText(nodeField(decl, 'name'));
+                    if (!/^[A-Za-z_$][\w$]*$/u.test(name))
+                        continue;
+                    const value = nodeField(decl, 'value');
+                    add(name, value?.type === 'arrow_function' || value?.type === 'function' ? 'const-fn' : 'const-data', node);
+                }
+            }
+            else if (node.type === 'enum_declaration')
+                add(nodeText(nodeField(node, 'name')), 'enum', node);
+            else if (node.type === 'interface_declaration')
+                add(nodeText(nodeField(node, 'name')), 'interface', node, true);
+            else if (node.type === 'type_alias_declaration')
+                add(nodeText(nodeField(node, 'name')), 'type', node, true);
+        }
+    }
+    return units;
+}
+function pythonTreeUnits(root) {
+    const units = [];
+    const definition = (node) => node.type === 'decorated_definition'
+        ? nodeChildren(node).find((child) => child.type === 'function_definition' || child.type === 'class_definition') ?? null
+        : node;
+    const visitContainer = (container, scopes) => {
+        for (const child of nodeChildren(container)) {
+            const inner = definition(child);
+            if (!inner || (inner.type !== 'function_definition' && inner.type !== 'class_definition')) {
+                visitContainer(child, scopes);
+                continue;
+            }
+            const name = nodeText(nodeField(inner, 'name'));
+            const qualified = [...scopes.map((scope) => scope.name), name].filter(Boolean).join('.');
+            const wrapperStart = child.type === 'decorated_definition' ? child.startPosition.row + 1 : undefined;
+            const kind = inner.type === 'class_definition' ? 'class' : (scopes.at(-1)?.classLike ? 'method' : 'function');
+            units.push({ name: qualified, kind, ...nodeLineRange(inner, wrapperStart) });
+            const body = nodeField(inner, 'body');
+            if (body)
+                visitContainer(body, [...scopes, { name, classLike: inner.type === 'class_definition' }]);
+        }
+    };
+    visitContainer(root, []);
+    return units;
+}
+function goTreeUnits(root) {
+    const units = [];
+    for (const node of root.descendantsOfType?.(['const_declaration', 'function_declaration', 'method_declaration', 'type_declaration']) ?? []) {
+        if (node.type === 'const_declaration') {
+            for (const spec of nodeChildren(node).filter((child) => child.type === 'const_spec')) {
+                const name = nodeText(nodeField(spec, 'name')) || nodeText(nodeChildren(spec)[0]);
+                if (name)
+                    units.push({ name, kind: 'const-data', ...nodeLineRange(spec) });
+            }
+        }
+        else if (node.type === 'function_declaration') {
+            units.push({ name: nodeText(nodeField(node, 'name')), kind: 'function', ...nodeLineRange(node) });
+        }
+        else if (node.type === 'method_declaration') {
+            const receiver = nodeField(node, 'receiver');
+            const parameter = nodeChildren(receiver).find((child) => child.type === 'parameter_declaration');
+            const receiverType = nodeField(parameter, 'type') ?? nodeChildren(parameter)[1];
+            const receiverName = lastTypeName(nodeText(receiverType));
+            const methodName = nodeText(nodeField(node, 'name'));
+            units.push({ name: receiverName ? `${receiverName}.${methodName}` : methodName, kind: 'method', ...nodeLineRange(node) });
+        }
+        else {
+            for (const spec of nodeChildren(node).filter((child) => child.type === 'type_spec')) {
+                const name = nodeText(nodeField(spec, 'name')) || nodeText(nodeChildren(spec)[0]);
+                const shape = nodeChildren(spec).find((child) => ['struct_type', 'interface_type'].includes(child.type));
+                const kind = shape?.type === 'struct_type' ? 'struct' : shape?.type === 'interface_type' ? 'interface' : 'type';
+                if (name)
+                    units.push({ name, kind, ...nodeLineRange(spec) });
+            }
+        }
+    }
+    return units;
+}
+function rustImplName(node) {
+    const header = nodeText(node).split('{', 1)[0];
+    const forMatch = header.match(/\bfor\s+([A-Za-z_][\w:]*)/u);
+    if (forMatch)
+        return forMatch[1].split('::').pop() ?? forMatch[1];
+    const names = nodeChildren(node).filter((child) => child.type === 'type_identifier' || child.type === 'scoped_type_identifier');
+    return lastTypeName(nodeText(names[0]));
+}
+function rustTreeUnits(root) {
+    const units = [];
+    for (const node of root.descendantsOfType?.(['const_item', 'function_item', 'struct_item', 'enum_item', 'trait_item']) ?? []) {
+        const name = nodeText(nodeField(node, 'name')) || nodeText(nodeChildren(node).find((child) => child.type === 'type_identifier'));
+        if (!name)
+            continue;
+        const parent = node.parent;
+        let impl = parent;
+        while (impl && impl.type !== 'impl_item' && impl.type !== 'source_file')
+            impl = impl.parent;
+        const implName = impl?.type === 'impl_item' ? rustImplName(impl) : '';
+        const kind = node.type === 'function_item' ? (implName ? 'method' : 'function')
+            : node.type === 'const_item' ? 'const-data'
+                : node.type === 'struct_item' ? 'struct'
+                    : node.type === 'enum_item' ? 'enum' : 'trait';
+        units.push({ name: implName && node.type === 'function_item' ? `${implName}.${name}` : name, kind, ...nodeLineRange(node) });
+    }
+    return units;
+}
+function javaTreeUnits(root) {
+    const units = [];
+    const visitClass = (node, scopes) => {
+        const name = nodeText(nodeField(node, 'name')) || nodeText(nodeChildren(node).find((child) => child.type === 'identifier'));
+        if (!name)
+            return;
+        const qualified = [...scopes, name].join('.');
+        const kind = node.type === 'class_declaration' ? 'class' : node.type === 'interface_declaration' ? 'interface' : 'enum';
+        units.push({ name: qualified, kind, ...nodeLineRange(node) });
+        const body = nodeField(node, 'body');
+        for (const child of nodeChildren(body)) {
+            if (child.type === 'field_declaration' && /\bfinal\b/u.test(nodeText(child))) {
+                for (const variable of nodeChildren(child).filter((part) => part.type === 'variable_declarator')) {
+                    const field = nodeText(nodeField(variable, 'name')) || nodeText(nodeChildren(variable).find((part) => part.type === 'identifier'));
+                    if (field)
+                        units.push({ name: `${qualified}.${field}`, kind: 'const-data', ...nodeLineRange(child) });
+                }
+            }
+            else if (child.type === 'method_declaration' || child.type === 'constructor_declaration') {
+                const method = nodeText(nodeField(child, 'name')) || nodeText(nodeChildren(child).find((part) => part.type === 'identifier'));
+                if (method)
+                    units.push({ name: `${qualified}.${child.type === 'constructor_declaration' ? 'constructor' : method}`, kind: 'method', ...nodeLineRange(child) });
+            }
+            else if (child.type.endsWith('_declaration') && ['class_declaration', 'interface_declaration', 'enum_declaration'].includes(child.type))
+                visitClass(child, [...scopes, name]);
+        }
+    };
+    const walk = (node) => {
+        for (const child of nodeChildren(node)) {
+            if (['class_declaration', 'interface_declaration', 'enum_declaration'].includes(child.type))
+                visitClass(child, []);
+            else
+                walk(child);
+        }
+    };
+    walk(root);
+    return units;
+}
+function rubyTreeUnits(root) {
+    const units = [];
+    const rubyName = (name) => name.replaceAll('::', '.');
+    const nameOf = (node) => rubyName(nodeText(nodeField(node, 'name')) || nodeText(nodeChildren(node).find((child) => ['constant', 'identifier'].includes(child.type))));
+    const visit = (container, scopes) => {
+        for (const child of nodeChildren(container)) {
+            if (child.type === 'class' || child.type === 'module') {
+                const name = nameOf(child);
+                if (!name)
+                    continue;
+                const qualified = [...scopes.map((scope) => scope.name), name].join('.');
+                units.push({ name: qualified, kind: child.type === 'class' ? 'class' : 'module', ...nodeLineRange(child) });
+                visit(nodeField(child, 'body') ?? child, [...scopes, { name, kind: child.type }]);
+            }
+            else if (child.type === 'assignment' && nodeField(child, 'left')?.type === 'constant') {
+                const name = rubyName(nodeText(nodeField(child, 'left')));
+                if (name)
+                    units.push({ name: [...scopes.map((scope) => scope.name), name].join('.'), kind: 'const-data', ...nodeLineRange(child) });
+            }
+            else if (child.type === 'method' || child.type === 'singleton_method') {
+                const name = nameOf(child);
+                if (!name)
+                    continue;
+                const receiver = child.type === 'singleton_method' ? rubyName(nodeText(nodeField(child, 'object'))) : '';
+                const qualified = receiver && receiver !== 'self' ? `${receiver}.${name}` : [...scopes.map((scope) => scope.name), name].join('.');
+                units.push({ name: qualified, kind: child.type === 'singleton_method' || scopes.length ? 'method' : 'function', ...nodeLineRange(child) });
+            }
+            else
+                visit(child, scopes);
+        }
+    };
+    visit(root, []);
+    return units;
+}
+export const TREE_SITTER_ROWS = [
+    { id: 'tree-sitter-typescript', extensions: ['ts', 'mts', 'cts'], grammar: 'typescript', schema: 'ts-v1', units: tsTreeUnits },
+    { id: 'tree-sitter-tsx', extensions: ['tsx'], grammar: 'tsx', schema: 'tsx-v1', units: tsTreeUnits },
+    { id: 'tree-sitter-javascript', extensions: ['js', 'jsx', 'mjs', 'cjs'], grammar: 'javascript', schema: 'js-v1', units: tsTreeUnits },
+    { id: 'tree-sitter-python', extensions: ['py', 'pyi'], grammar: 'python', schema: 'python-v1', units: pythonTreeUnits },
+    { id: 'tree-sitter-go', extensions: ['go'], grammar: 'go', schema: 'go-v1', units: goTreeUnits },
+    { id: 'tree-sitter-rust', extensions: ['rs'], grammar: 'rust', schema: 'rust-v1', units: rustTreeUnits },
+    { id: 'tree-sitter-java', extensions: ['java'], grammar: 'java', schema: 'java-v1', units: javaTreeUnits },
+    { id: 'tree-sitter-ruby', extensions: ['rb'], grammar: 'ruby', schema: 'ruby-v1', units: rubyTreeUnits },
+];
+export function treeSitterExtractor(row) {
+    let readiness;
+    const getLanguage = () => treeSitterLanguage(row);
+    return {
+        id: row.id,
+        claims: (ext) => row.extensions.includes(ext),
+        async ready() {
+            if (readiness !== undefined)
+                return readiness;
+            try {
+                await getLanguage();
+                readiness = true;
+            }
+            catch (error) {
+                readiness = `Tree-sitter extractor '${row.id}' cannot load grammar '${row.grammar}': ${error?.message ?? String(error)} — reinstall SpexCode or remove the #anchor`;
+            }
+            return readiness;
+        },
+        async extract(content, filename) {
+            const language = await getLanguage();
+            const mod = await treeSitterModule();
+            const parser = new mod.Parser().setLanguage(language);
+            let tree;
+            try {
+                tree = parser.parse(content);
+                if (!tree?.rootNode || treeHasSyntaxError(tree.rootNode))
+                    throw new Error(`${filename} has Tree-sitter syntax errors`);
+                return row.units(tree.rootNode);
+            }
+            finally {
+                tree?.delete?.();
+                parser.delete?.();
+            }
+        },
+        memoKey(filename) { return JSON.stringify({ schema: 'tree-sitter-wasm-v1', row: row.id, grammar: row.grammar, rowSchema: row.schema, filename }); },
+    };
+}
 // ---- registry: extension -> its ONE designated extractor ----
-// The registry's shape is the Extractor INTERFACE, not any engine: a future language row may be a
-// heuristicExtractor(LangSpec) or a web-tree-sitter extractor carrying its own wasm-grammar/query
-// config — whatever the implementation needs rides inside its own factory, never in the registry.
+// The registry is one Tree-sitter language adapter: every shipped extension is a grammar DATA row.
 export function extractors(root) {
-    return [tsAstExtractor(root), ...[PYTHON_LANG].map(heuristicExtractor)];
+    void root;
+    return TREE_SITTER_ROWS.map(treeSitterExtractor);
 }
 // first claiming extractor IS the designation (the registry order defines it); null = no anchor support
-// for this language yet (lint ERRORS — the remedy is a LangSpec data row, or dropping the anchor).
+// for this language yet (lint ERRORS — the remedy is a Tree-sitter language row, or dropping the anchor).
 export function extractorFor(regs, ext) {
     return regs.find((x) => x.claims(ext)) ?? null;
 }
@@ -417,7 +713,7 @@ async function unitsAtFileRevision(commit, path, x, objectFormat, oid, text) {
         throw new Error(`git cat-file --batch omitted object ${oid} for ${commit}:${path}`);
     let result;
     try {
-        result = { units: x.extract(text, path) };
+        result = { units: await x.extract(text, path) };
     }
     catch (e) {
         result = { unparseable: e?.message ?? String(e) };
@@ -626,7 +922,7 @@ async function runAnchorQueriesInLedger(root, queries, regs, stopAtFirstHit) {
                 continue;
             const ref = revisions.get(key), oid = oidByRef.get(key) ?? null;
             const x = extractorFor(regs, extOf(ref.path));
-            const ready = x?.ready();
+            const ready = x ? await x.ready() : undefined;
             if (!x || ready !== true) {
                 units.set(key, { unparseable: !x ? `no designated extractor for ${ref.path}` : String(ready) });
                 continue;

package/dist/git.d.ts

@@ -153,6 +153,10 @@ export type ReviewDiffFile = {
     additions: number;
     deletions: number;
 };
+export declare function parseStatPath(token: string): {
+    from: string;
+    to: string;
+};
 export declare function mergeBaseDiff(wtPath: string, mainRef?: string, headRef?: string): Promise<ReviewDiffFile[]>;
 export declare function mergeConflicts(wtPath: string, mainRef?: string, headRef?: string): Promise<boolean>;
 type WorktreeSpecDemand = {

package/dist/git.js

@@ -230,15 +230,15 @@ export async function batchRevisionOids(root, revisions, options = {}) {
     });
 }
 export async function batchBlobTexts(root, oids) {
-    const unique = [...new Set(oids.filter(Boolean))];
+    const objectIds = [...new Set(oids.filter(Boolean))];
     const files = new Map();
-    if (!unique.length)
+    if (!objectIds.length)
         return files;
-    for (const oid of unique)
+    for (const oid of objectIds)
         if (!isGitObjectId(root, oid))
             throw new Error(`invalid object id '${oid}'`);
-    for (let cursor = 0; cursor < unique.length; cursor += BATCH_BLOB_CHUNK) {
-        const chunk = unique.slice(cursor, cursor + BATCH_BLOB_CHUNK);
+    for (let cursor = 0; cursor < objectIds.length; cursor += BATCH_BLOB_CHUNK) {
+        const chunk = objectIds.slice(cursor, cursor + BATCH_BLOB_CHUNK);
         const out = await batchBuffer(['-C', root, 'cat-file', '--batch'], chunk.join('\n') + '\n', BATCH_BLOB_MAX_BUFFER);
         let offset = 0;
         for (const oid of chunk) {
@@ -1609,12 +1609,12 @@ function canonicalPathProjector(renamesByFrom, topology) {
                 continue;
             }
             seen.add(candidate);
-            const unique = new Map();
+            const applicableByIdentity = new Map();
             for (const rename of renamesByFrom.get(candidate) ?? []) {
                 if (!precedes(rename.hash, event))
-                    unique.set(`${rename.hash}\0${rename.to}`, rename);
+                    applicableByIdentity.set(`${rename.hash}\0${rename.to}`, rename);
             }
-            const applicable = [...unique.values()];
+            const applicable = [...applicableByIdentity.values()];
             if (!applicable.length) {
                 resolved.add(candidate);
                 continue;
@@ -2531,7 +2531,7 @@ function parseNameStatus(out) {
     return rows;
 }
 const DIFF_STATUS = { A: 'added', M: 'modified', D: 'deleted', R: 'renamed', C: 'copied', T: 'type-changed' };
-function parseStatPath(token) {
+export function parseStatPath(token) {
     const b = token.indexOf('{'), arrow = token.indexOf(' => ', b), close = token.indexOf('}', arrow);
     if (b >= 0 && arrow > b && close > arrow) {
         const pre = token.slice(0, b), post = token.slice(close + 1);

package/dist/layout.d.ts

@@ -111,8 +111,10 @@ export type RawRecord = {
     createdAt: number;
     harness?: string;
     harness_session_id?: string;
+    runtime_start_token?: string;
     stopped?: boolean;
     archived?: boolean;
+    closed_at?: string;
     cold_proof?: string;
     adapter_recovery?: string;
     launcher?: string;
@@ -125,6 +127,15 @@ export type RawRecord = {
     runtime_revision?: string;
     runtime_metadata?: Record<string, string>;
     base?: string;
+    diff_comments?: Array<{
+        id: string;
+        file_path: string;
+        line_start: number;
+        line_end: number;
+        body: string;
+        diff_identity: string;
+        sent_at: string | null;
+    }>;
     launch_readiness_pending?: '' | RawLaunchReadinessPending;
 };
 export declare const SESSION_LIFECYCLES: readonly ["active", "idle", "awaiting", "parked", "error", "asking", "queued"];
@@ -139,6 +150,7 @@ export type RawLaunchReadinessOriginal = {
     note: string | null;
     stopped: boolean;
     archived: boolean;
+    closed_at?: string | null;
     cold_proof: string | null;
     adapter_recovery: string | null;
 };

package/dist/layout.js

@@ -136,7 +136,7 @@ export function mainRoot(proj) {
 }
 // @@@ global per-session store - Fork A: NO SpexCode files live in the worktree any more, so the worktree's
 // spec/code tree is pristine (zero per-session pollution). Every per-session runtime artifact — the
-// structured record (session.json) AND the launcher products (prompt, launch, launch.sh) AND the recorded comms AND
+// runtime envelope (runtime.json) AND the launcher products (prompt, launch, launch.sh) AND the recorded comms AND
 // the spec-discipline sentinels — lives in a per-USER GLOBAL store, keyed by the harness `session_id` so two
 // agents in one folder never clobber, and grouped PER PROJECT (mirroring Claude's ~/.claude/projects/<enc>/)
 // so the board enumerates ONE directory. This is the single seam that knows where the store sits; sessions.ts
@@ -169,7 +169,7 @@ export function treeSlotDir(wt) {
 // all keyed by session_id under <home>/projects/<enc>/sessions/.
 export function sessionsRoot() { return join(runtimeRoot(), 'sessions'); }
 export function sessionStoreDir(id) { return join(sessionsRoot(), id); }
-export function sessionRecordPath(id) { return join(sessionStoreDir(id), 'session.json'); }
+export function sessionRecordPath(id) { return join(sessionStoreDir(id), 'runtime.json'); }
 export function sessionArtifactPath(id, name) { return join(sessionStoreDir(id), name); }
 export const SESSION_LIFECYCLES = ['active', 'idle', 'awaiting', 'parked', 'error', 'asking', 'queued'];
 export const SESSION_PROPOSALS = ['merge', 'nothing', 'close'];
@@ -190,6 +190,7 @@ export function rawLaunchReadinessOriginal(raw) {
         || !(original.proposal === null || original.proposal === '' || isSessionProposal(original.proposal))
         || !(typeof original.note === 'string' || original.note === null)
         || typeof original.stopped !== 'boolean' || typeof original.archived !== 'boolean'
+        || !(typeof original.closed_at === 'string' || original.closed_at === null || original.closed_at === undefined)
         || !(typeof original.cold_proof === 'string' || original.cold_proof === null)
         || !(typeof original.adapter_recovery === 'string' || original.adapter_recovery === null)) {
         throw new Error(`session '${raw.session_id}' has an invalid launch_readiness_pending fence`);
@@ -281,6 +282,7 @@ export function projectPublicRecordEntry(id, entry) {
                 note: original.note || null,
                 stopped: original.stopped,
                 archived: original.archived,
+                closed_at: original.closed_at ?? undefined,
                 cold_proof: original.cold_proof ?? undefined,
                 adapter_recovery: original.adapter_recovery ?? undefined,
                 launch_readiness_pending: '',

package/dist/resilience.d.ts

@@ -1,2 +1,3 @@
+export declare function isTrashWorktreePath(path: string): boolean;
 export declare function guardWorktree<T>(dir: string, fn: () => T | Promise<T>, degraded: () => T): Promise<T | null>;
 export declare function installProcessGuards(): void;

package/dist/resilience.js

@@ -1,7 +1,15 @@
 import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
 function describe(e) {
     return e instanceof Error ? e.message : String(e);
 }
+// Delayed close deletion lives below this directory and is never a live worktree input.
+export function isTrashWorktreePath(path) {
+    const normalized = resolve(path);
+    const parts = normalized.split(/[\\/]+/);
+    const worktrees = parts.lastIndexOf('.worktrees');
+    return worktrees >= 0 && parts[worktrees + 1] === '.trash';
+}
 // run a per-worktree DETAIL read; on a throw, branch on whether the worktree DIRECTORY still exists.
 //   dir gone   → the worktree was genuinely removed mid-read → return null so the caller omits it.
 //   dir present → a flaky detail read (ENOENT race on a sibling file, or a git index/ref lock under a

package/dist/review/reviewFilters.d.ts

@@ -68,6 +68,7 @@ export const EVAL_FILTER_KIND: Readonly<{
     RESULT: "result";
     BLIND: "blind";
     UNMEASURED: "unmeasured";
+    DEFERRED: "deferred";
     DANGLING: "dangling";
 }>;
 export function evidenceList(reading: any): any;

package/dist/review/reviewFilters.js

@@ -11,6 +11,7 @@ export const EVAL_FILTER_KIND = Object.freeze({
     RESULT: 'result',
     BLIND: 'blind',
     UNMEASURED: 'unmeasured',
+    DEFERRED: 'deferred',
     DANGLING: 'dangling',
 });
 export const evidenceList = (reading) => reading?.evidence?.length ? reading.evidence
@@ -146,9 +147,11 @@ export function issueFilterModel(items, raw = {}, context = {}) {
 const evalIsResult = (entry) => entry.filterKind === EVAL_FILTER_KIND.RESULT;
 const verdictOf = (entry) => evalIsResult(entry)
     ? (entry.verdict?.status || 'unscored')
-    : entry.filterKind === EVAL_FILTER_KIND.BLIND || entry.filterKind === EVAL_FILTER_KIND.UNMEASURED
-        ? 'unmeasured'
-        : 'unscored';
+    : entry.filterKind === EVAL_FILTER_KIND.DEFERRED
+        ? 'deferred'
+        : entry.filterKind === EVAL_FILTER_KIND.BLIND || entry.filterKind === EVAL_FILTER_KIND.UNMEASURED
+            ? 'unmeasured'
+            : 'unscored';
 const reviewStateOf = (entry) => (evalIsResult(entry) && entry.fresh && entry.humanOk ? 'reviewed' : 'current');
 // the ONE freshness axis of the Eval adapter — the facet's option values and the verdict sections' split
 // read it, so a chip and its Freshness menu can never disagree about what "stale" counts.
@@ -194,6 +197,7 @@ const EVAL_CONFIG = {
             { value: 'fail', label: 'reviewList.verdict.fail', split: true },
             { value: 'pass', label: 'reviewList.verdict.pass', split: true },
             { value: 'unmeasured', label: 'reviewList.verdict.unmeasured' },
+            { value: 'deferred', label: 'reviewList.verdict.deferred' },
         ],
     },
     facets: [

package/dist/review/reviewQuery.d.ts

@@ -31,6 +31,7 @@ export const ISSUE_QUERY_DEFAULT: "is:issue state:open";
 export const EVAL_QUERY_DEFAULT: "is:eval";
 export function scopedEvalQuery(sessionId: any): any;
 export function nodeEvalQuery(nodeId: any): any;
+export function nodeIssueQuery(nodeId: any): any;
 export function quoteValue(v: any): string;
 export function tokenize(text: any): ({
     ws: boolean;

package/dist/review/reviewQuery.js

@@ -8,6 +8,10 @@ export const EVAL_QUERY_DEFAULT = 'is:eval';
 export const scopedEvalQuery = (sessionId) => setToken(EVAL_QUERY_DEFAULT, 'scope', sessionId);
 // the aggregate score/count doors' address ([[eval-score-badge]]): the default view, node-filtered.
 export const nodeEvalQuery = (nodeId) => setToken(EVAL_QUERY_DEFAULT, 'node', nodeId);
+// a node's OPEN issues ([[context-dock]]): the issue list's default view, node-filtered. Same shape and
+// same reason as the eval twin — a surface that wants "this node's issues" asks for a text, never for a
+// second filter path, so the panel and the list it links to are literally the same query.
+export const nodeIssueQuery = (nodeId) => setToken(ISSUE_QUERY_DEFAULT, 'node', nodeId);
 const KEY_RE = /^([A-Za-z][A-Za-z0-9-]*):(.*)$/s;
 const unquote = (v) => (v.length >= 2 && v.startsWith('"') && v.endsWith('"') ? v.slice(1, -1) : v);
 export const quoteValue = (v) => (/\s/.test(String(v)) ? `"${v}"` : String(v));

package/dist/specs.d.ts

@@ -9,6 +9,7 @@ export type SpecParts = {
     expandedSpec: string;
 };
 declare function parseParts(body: string): SpecParts | null;
+export declare function bodyMentions(body: string): string[];
 export type DerivedStatus = 'pending' | 'active' | 'merged' | 'drift';
 export declare function deriveStatus(d: {
     version: number;
@@ -43,6 +44,7 @@ export declare function specContent(id: string): {
     body: string;
     parts: ReturnType<typeof parseParts>;
 } | null;
+export declare function specDir(id: string): string | null;
 export type LoadSpecsOptions = {
     tip?: string;
     history?: HistoryIndex | null;

package/dist/specs.js

@@ -68,6 +68,29 @@ function parseParts(body) {
     const t = (a) => a.join('\n').trim();
     return { rawSource: t(acc.rawSource), expandedSpec: t(acc.expandedSpec) };
 }
+// the `[[id]]` reference grammar as a spec BODY writes it. Its consumer is the lint rule that rejects a
+// dangling reference — the one place a `[[name]]` has to be judged against the node universe. It is a
+// parser and not a projection: the loader once shipped the surviving ids as a `mentions` edge on every
+// node, and that edge is gone, because a prose mention is a fact about the GRAPH and never was a fact
+// about the node the reader has open ([[context-dock]]). Prose only: a fenced block or an inline
+// `code span` is sample text (`[[node]]`, `[[<id>]]` placeholders live there), not a reference. Distinct,
+// in first-appearance order; whether a name resolves to a real node is the caller's judgement.
+const MENTION_RE = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/gu;
+export function bodyMentions(body) {
+    const out = new Set();
+    let inFence = false;
+    for (const rawLine of body.split('\n')) {
+        if (/^\s*```/.test(rawLine)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        for (const m of rawLine.replace(/`[^`]*`/g, '').matchAll(MENTION_RE))
+            out.add(m[1]);
+    }
+    return [...out];
+}
 export function deriveStatus(d) {
     if (d.fmStatus === 'pending' && !d.hasCode && d.drift === 0)
         return 'pending';
@@ -228,6 +251,13 @@ export function specContent(id) {
     const r = raws().find((x) => x.id === id);
     return r ? { body: r.body.trim(), parts: parseParts(r.body) } : null;
 }
+// Where a node LIVES, repo-relative — its own folder, not its spec.md. A node's folder is the unit (the
+// same rule the plugin instances are built on), so anything that wants to see what a node carries besides
+// its body asks the spec tree's own reader rather than re-deriving a path from an id.
+export function specDir(id) {
+    const r = raws().find((x) => x.id === id);
+    return r ? r.relPath.replace(/\/spec\.md$/, '') : null;
+}
 export async function loadSpecs(root = ROOT, options = {}) {
     // The default pair shares one immutable-event snapshot; explicit sides let callers skip or supply either
     // projection. Every node below is then a pure in-memory lookup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-core",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "type": "module",
   "description": "SpexCode's dependency-minimal spec graph core.",
   "files": [
@@ -17,6 +17,9 @@
   "engines": {
     "node": ">=22"
   },
+  "dependencies": {
+    "@vscode/tree-sitter-wasm": "0.3.1"
+  },
   "publishConfig": {
     "access": "public"
   },