@crouton-kit/tsym 0.1.0 → 0.2.0

package/dist/output.js

@@ -7,7 +7,7 @@ export function xml(name, attributes = {}, body = '') {
 export function escapeAttribute(value) { return value.replace(/"/g, '"'); }
 export function renderCompletion(completion, json) {
     const exitCode = completionCode(completion);
-    const payload = json ? JSON.stringify(completion) + '\n' : render(completion) + '\n';
+    const payload = json ? JSON.stringify(publicCompletion(completion)) + '\n' : render(completion) + '\n';
     const stdout = payload;
     const stderr = receipt(completion);
     return { stdout, stderr, exitCode };
@@ -21,11 +21,17 @@ export function completionCode(completion) {
 }
 function render(completion) {
     if (isAnswer(completion))
-        return nodes(completion.data);
+        return `${completion.context ? `${completion.context.endsWith('\n') ? completion.context : `${completion.context}\n`}` : ''}${nodes(completion.data)}`;
     if (completion.category === 'invocation')
         return renderInvocationError(completion);
     return renderToolError(completion);
 }
+function publicCompletion(completion) {
+    if (!isAnswer(completion))
+        return completion;
+    const { displayedFiles: _, context: __, contextError: ___, ...answer } = completion;
+    return answer;
+}
 function nodes(data) { return (Array.isArray(data) ? data : [data]).map(renderNode).join('\n'); }
 export function renderNode(node) {
     const attributes = Object.entries(node.attributes ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => ` ${key}="${escapeAttribute(String(value))}"`).join('');
@@ -47,7 +53,8 @@ function receipt(completion) {
     if (isAnswer(completion)) {
         const answer = completion;
         const base = answer.receipt ?? `${answer.count} answer${answer.count === 1 ? '' : 's'}, 0 ms`;
-        return answer.startupMs === undefined ? base : `${base} (server started, ${answer.startupMs} ms)`;
+        const receipt = answer.startupMs === undefined ? base : `${base} (server started, ${answer.startupMs} ms)`;
+        return answer.contextError ? `${answer.contextError}\n${receipt}` : receipt;
     }
     return completion.category === 'invocation' ? `invocation rejected, 0 ms` : `tool failed, 0 ms`;
 }

package/dist/relations/store-relations.d.ts

@@ -9,6 +9,20 @@ export interface ReferenceRow {
     qualifiedName: string;
     role: string;
 }
+export interface MemberSummary {
+    key: string;
+    address: string;
+    path: string;
+    line: number;
+    col: number;
+    kind: string;
+    qualifiedName: string;
+    callers: number;
+    calls: number;
+    refs: number;
+    container: string;
+}
+export declare function memberSummaries(context: SemanticContext, record: DeclarationRecord): Promise<MemberSummary[]>;
 export declare function references(context: SemanticContext, record: DeclarationRecord, filters: {
     in: readonly string[];
     exclude: readonly string[];

package/dist/relations/store-relations.js

@@ -1,8 +1,19 @@
 import path from 'node:path';
+import { directMembers } from '../core/members.js';
 import { matchesPathFilters } from '../core/receipt.js';
 import { query } from '../store/query.js';
 import { graphAfterExclusion, GraphBuilder, projectGraph } from './graph.js';
 import { nodeFor } from './types.js';
+export async function memberSummaries(context, record) {
+    const container = recordKey(context, record);
+    const members = directMembers(storeRows(context, 'MATCH (member:Declaration) WHERE member.container = $container RETURN member.key AS key, member.at AS at, member.file AS file, member.line AS line, member.col AS col, member.kind AS kind, member.qname AS qname, member.container AS container', { container }).map((row) => ({ key: text(row, 'key'), address: text(row, 'at'), path: text(row, 'file'), line: number(row, 'line'), col: number(row, 'col'), kind: text(row, 'kind'), qualifiedName: text(row, 'qname'), container: text(row, 'container') })), container);
+    const callers = relatedKeys(context, 'MATCH (caller:Declaration)-[call:CALLS]->(member:Declaration) WHERE member.container = $container AND call.dispatch = false RETURN member.key AS member, caller.key AS related', container);
+    addRelatedKeys(callers, relatedKeys(context, 'MATCH (member:Declaration)-[:IMPLEMENTS]->(:Declaration)<-[call:CALLS]-(caller:Declaration) WHERE member.container = $container AND call.dispatch = true RETURN member.key AS member, caller.key AS related', container));
+    const calls = relatedKeys(context, 'MATCH (member:Declaration)-[call:CALLS]->(target:Declaration) WHERE member.container = $container AND call.dispatch = false RETURN member.key AS member, target.key AS related', container);
+    addRelatedKeys(calls, relatedKeys(context, 'MATCH (member:Declaration)-[call:CALLS]->(contract:Declaration)<-[:IMPLEMENTS]-(target:Declaration) WHERE member.container = $container AND call.dispatch = true RETURN member.key AS member, target.key AS related', container));
+    const refs = new Map(storeRows(context, 'MATCH (:Declaration)-[reference:REFERENCES]->(member:Declaration) WHERE member.container = $container RETURN member.key AS member, count(reference) AS refs', { container }).map((row) => [text(row, 'member'), number(row, 'refs')]));
+    return members.map((member) => ({ ...member, callers: callers.get(member.key)?.size ?? 0, calls: calls.get(member.key)?.size ?? 0, refs: refs.get(member.key) ?? 0 }));
+}
 export async function references(context, record, filters) {
     const rows = storeRows(context, 'MATCH (owner:Declaration)-[reference:REFERENCES]->(target:Declaration) WHERE target.key = $key RETURN owner.file AS file, owner.kind AS kind, owner.qname AS qname, reference.line AS line, reference.col AS col, reference.role AS role', { key: recordKey(context, record) });
     return rows.flatMap((row) => {
@@ -156,3 +167,16 @@ function unresolvedSite(record, row, name, reason, dispatch) {
 function text(row, key) { return String(row[key] ?? ''); }
 function number(row, key) { return Number(row[key]); }
 function boolean(row, key) { return row[key] === true; }
+function relatedKeys(context, statement, container) {
+    const related = new Map();
+    for (const row of storeRows(context, statement, { container })) {
+        const member = text(row, 'member');
+        (related.get(member) ?? related.set(member, new Set()).get(member)).add(text(row, 'related'));
+    }
+    return related;
+}
+function addRelatedKeys(target, additional) {
+    for (const [member, keys] of additional)
+        for (const key of keys)
+            (target.get(member) ?? target.set(member, new Set()).get(member)).add(key);
+}

package/dist/server/client.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { closeSync, existsSync, openSync } from 'node:fs';
+import { attachReadContext } from '../context-exposure.js';
 import { connect } from 'node:net';
 import { fileURLToPath } from 'node:url';
 import { discoverRoot, ensureStateDirectory, pathsForRoot } from './lifecycle.js';
@@ -19,7 +20,7 @@ class DeadlineExpired extends Error {
 }
 export async function invokeResident(invocation) {
     const root = discoverRoot(invocation.root);
-    return send(root, 'invoke', invocation, true);
+    return attachReadContext(invocation, await send(root, 'invoke', invocation, true));
 }
 export async function serverStatus(rootOverride) {
     const root = discoverRoot(rootOverride);
@@ -151,9 +152,11 @@ function exchange(paths, payload) {
                     break;
                 case 'project-load-start':
                 case 'project-load-end':
+                    deadlinePhase = 'project-load';
+                    break;
                 case 'index-build-start':
                 case 'index-build-end':
-                    deadlinePhase = 'project-load';
+                    deadlinePhase = 'index-build';
                     break;
                 case 'running':
                     deadlinePhase = 'running';
@@ -203,6 +206,8 @@ function withStartup(completion, startupStartedAt) {
 function deadlineFailure(paths, deadline) {
     if (deadline.phase === 'project-load')
         return { category: 'tool', code: 'project-load-timeout', message: 'TypeScript did not load the workspace project before its deadline.', logPath: paths.log, next: 'Repair the project, then retry.' };
+    if (deadline.phase === 'index-build')
+        return { category: 'tool', code: 'index-build-timeout', message: 'The workspace index did not build before its deadline.', logPath: paths.log, next: 'Repair the project, then retry.' };
     if (deadline.phase === 'running')
         return { category: 'tool', code: 'request-timeout', message: 'The semantic request exceeded its deadline.', logPath: paths.log, received: deadline.command ?? 'no semantic operation started', next: 'Retry after repairing the workspace or narrowing the command.' };
     return { category: 'tool', code: 'server-unavailable', message: 'The resident did not begin this request before its admission deadline.', logPath: paths.log, next: 'Retry after the current request completes.' };

package/dist/server/main.js

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { DatabaseSync } from 'node:sqlite';
 import { createServer } from 'node:net';
 import { appendFileSync, chmodSync, existsSync, openSync, readdirSync } from 'node:fs';
+import path from 'node:path';
 import { discoverRoot, ensureStateDirectory, idleSeconds, pathsForRoot, publishState, removeEndpoint } from './lifecycle.js';
 import { NdjsonReader, WIRE_VERSION, writeFrame } from './wire.js';
 import { createSemanticContext } from './context.js';
@@ -11,7 +12,8 @@ import { ingestCommits } from '../index/commits.js';
 import { refreshIndex } from '../index/refresh.js';
 import { IndexStateController } from '../index/state.js';
 import { watchIndex } from '../index/watch.js';
-import { canReuse, hasSourceDrift, metadataFor, readMetadata, writeMetadata } from '../store/meta.js';
+import { discardIncompatibleStore, formatIdentity, hasDrift, metadataFor, readMetadata, writeMetadata } from '../store/meta.js';
+import { copyStore, refuseSeed, seedFromSibling } from '../store/seed.js';
 import { EngineBinaryError, Store } from '../store/store.js';
 import { executeSemantic } from '../commands/handlers.js';
 import { findNode } from '../commands/tree.js';
@@ -46,6 +48,7 @@ async function main() {
     const bootedAt = new Date();
     const bootedAtMonotonic = performance.now();
     let bootstrapped = false;
+    let seededFrom;
     let loading = false;
     let stopping = false;
     let retired = false;
@@ -53,6 +56,7 @@ async function main() {
     let queue = [];
     let currentCommand;
     let loadDeadlineAt;
+    let indexBuildDeadlineAt;
     let activeDeadlineAt;
     let activeTimer;
     let idleTimer;
@@ -210,10 +214,13 @@ async function main() {
                 socket.destroy();
         exitAfterCleanup();
     };
-    const projectLoadTimeout = () => {
+    const startupDeadlineFailure = (phase) => phase === 'project-load'
+        ? toolError('project-load-timeout', 'TypeScript did not load the workspace project before its deadline.', 'Repair the project, then retry.')
+        : toolError('index-build-timeout', 'The workspace index did not build before its deadline.', 'Repair the project, then retry.');
+    const startupTimeout = (phase) => {
         if (retired)
             return;
-        const completion = toolError('project-load-timeout', 'TypeScript did not load the workspace project before its deadline.', 'Repair the project, then retry.');
+        const completion = startupDeadlineFailure(phase);
         if (active) {
             respond(active.socket, active.request.requestId, completion);
             finishSocket(active.socket);
@@ -238,68 +245,109 @@ async function main() {
         if (active)
             sendPhase(active.socket, active.request.requestId, 'running', 120_000);
     };
-    const loadProjects = async () => {
+    const loadProjects = async (startup) => {
         loading = true;
-        loadDeadlineAt = performance.now() + 60_000;
-        if (active)
-            sendPhase(active.socket, active.request.requestId, 'project-load-start', 60_000);
-        for (const queued of queue) {
-            pauseQueueDeadline(queued);
-            sendPhase(queued.socket, queued.request.requestId, 'project-load-start', 60_000);
-        }
-        let timedOut = false;
+        const sendStartupPhase = (phase, remainingMs) => {
+            if (active)
+                sendPhase(active.socket, active.request.requestId, phase, remainingMs);
+            for (const queued of queue)
+                sendPhase(queued.socket, queued.request.requestId, phase, remainingMs);
+            if (startup)
+                sendPhase(startup.socket, startup.requestId, phase, remainingMs);
+        };
         let deadlineTimer;
+        const deadline = (phase, durationMs) => new Promise((_, reject) => {
+            deadlineTimer = setTimeout(() => reject(new DeadlineExceeded(phase)), durationMs);
+            deadlineTimer.unref();
+        });
         try {
-            await Promise.race([
+            loadDeadlineAt = performance.now() + 60_000;
+            for (const queued of queue)
+                pauseQueueDeadline(queued);
+            sendStartupPhase('project-load-start', 60_000);
+            semantic ??= createSemanticContext(root);
+            const { program, projects } = semantic;
+            const { configured, identity, expected } = await Promise.race([
                 (async () => {
-                    semantic ??= createSemanticContext(root);
-                    const { program, projects } = semantic;
                     await projects.bootstrap();
-                    store = new Store(paths.store);
-                    if (active)
-                        sendPhase(active.socket, active.request.requestId, 'index-build-start', remaining(loadDeadlineAt));
-                    // The watcher starts before the build, not after it: buildIndex takes tens of seconds on a large workspace,
-                    // and an edit landing in that window would otherwise never be recorded, publishing a stale index as current.
-                    // buildIndex is synchronous, so no watch callback can run until index is assigned below.
-                    watcher = watchIndex(root, projects.configured(), refresh, (error) => append(paths, `index refresh failure: ${safe(error)}`), (flush) => index?.markStale(flush));
                     const configured = projects.configured();
-                    const expected = metadataFor(root, configured, headCommit(root));
-                    const metadata = readMetadata(store.path);
-                    let built;
-                    if (!forceRebuild && canReuse(metadata, expected)) {
+                    const identity = formatIdentity();
+                    if (discardIncompatibleStore(paths.store, identity))
+                        append(paths, 'discarded an incompatible store');
+                    const expected = metadataFor(root, configured, headCommit(root), 0, identity);
+                    if (!forceRebuild && readMetadata(paths.store) === null) {
+                        const seeded = await seedFromSibling(root, paths, expected, identity);
+                        if (seeded) {
+                            seededFrom = seeded.root;
+                            append(paths, `store seeded from ${seeded.root} bytes=${seeded.bytes} duration=${Math.round(seeded.durationMs)}ms`);
+                        }
+                        else
+                            append(paths, 'store seed skipped: no identical sibling');
+                    }
+                    return { configured, identity, expected };
+                })(),
+                deadline('project-load', 60_000),
+            ]);
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+            deadlineTimer = undefined;
+            loadDeadlineAt = undefined;
+            store = new Store(paths.store);
+            indexBuildDeadlineAt = performance.now() + 180_000;
+            sendStartupPhase('index-build-start', 180_000);
+            // The watcher starts before the build, not after it: buildIndex takes tens of seconds on a large workspace,
+            // and an edit landing in that window would otherwise never be recorded, publishing a stale index as current.
+            // buildIndex is synchronous, so no watch callback can run until index is assigned below.
+            watcher = watchIndex(root, configured, refresh, (error) => append(paths, `index refresh failure: ${safe(error)}`), (flush) => index?.markStale(flush));
+            const metadata = readMetadata(store.path);
+            let built;
+            await Promise.race([
+                (async () => {
+                    if (!forceRebuild && metadata !== null) {
                         const reused = reuseIndex(store);
-                        built = hasSourceDrift(metadata, expected)
-                            ? refreshIndex(root, program, configured, store, reused, { fileChanges: { invalidateAll: true } }).built
-                            : reused;
+                        if (hasDrift(metadata, expected)) {
+                            const refreshed = refreshIndex(root, program, configured, store, reused, { fileChanges: { invalidateAll: true } }, identity);
+                            append(paths, `index refresh stored=${refreshed.stored} changedFiles=${refreshed.changedFiles.length} duration=${Math.round(refreshed.built.receipt.durationMs)}ms`);
+                            built = refreshed.built;
+                        }
+                        else
+                            built = reused;
                     }
                     else {
-                        built = buildIndex(root, program, configured, store);
+                        built = buildIndex(root, program, configured, store, identity);
                     }
-                    index = new IndexStateController({ indexedAt: indexedAt(root), state: 'current', built }, (snapshot) => {
-                        semantic.index = snapshot;
-                        publishState(paths, publishedState(snapshot));
-                    });
-                    semantic.store = store;
-                    if (active)
-                        sendPhase(active.socket, active.request.requestId, 'index-build-end', remaining(loadDeadlineAt));
                 })(),
-                new Promise((_, reject) => { deadlineTimer = setTimeout(() => { timedOut = true; reject(new DeadlineExceeded('project-load')); }, 60_000); deadlineTimer.unref(); }),
+                deadline('index-build', 180_000),
             ]);
+            if (deadlineTimer)
+                clearTimeout(deadlineTimer);
+            deadlineTimer = undefined;
+            const indexBuildRemaining = remaining(indexBuildDeadlineAt);
+            indexBuildDeadlineAt = undefined;
+            index = new IndexStateController({ indexedAt: indexedAt(root), state: 'current', built: built }, (snapshot) => {
+                semantic.index = snapshot;
+                publishState(paths, publishedState(snapshot));
+            });
+            semantic.store = store;
+            sendStartupPhase('index-build-end', indexBuildRemaining);
             bootstrapped = true;
         }
         finally {
             if (deadlineTimer)
                 clearTimeout(deadlineTimer);
+            if (!bootstrapped) {
+                // A failed load must leave nothing open, or the next attempt fails on store ownership instead of its real cause.
+                watcher?.close();
+                watcher = undefined;
+                store?.close();
+                store = undefined;
+            }
             loading = false;
             loadDeadlineAt = undefined;
-            if (!timedOut && !retired) {
-                if (active)
-                    sendPhase(active.socket, active.request.requestId, 'project-load-end', 60_000);
-                for (const queued of queue) {
-                    sendPhase(queued.socket, queued.request.requestId, 'project-load-end', 60_000);
+            indexBuildDeadlineAt = undefined;
+            if (bootstrapped && !retired)
+                for (const queued of queue)
                     armQueueDeadline(queued);
-                }
-            }
         }
     };
     const processQueue = async () => {
@@ -343,8 +391,8 @@ async function main() {
                 respond(queued.socket, queued.request.requestId, completion);
         }
         catch (error) {
-            if (error instanceof DeadlineExceeded && error.phase === 'project-load') {
-                projectLoadTimeout();
+            if (error instanceof DeadlineExceeded) {
+                startupTimeout(error.phase);
                 return;
             }
             if (error instanceof Ts7ServerDiedError) {
@@ -357,8 +405,16 @@ async function main() {
                     respond(queued.socket, queued.request.requestId, { category: 'tool', code: error.code, attributes: { platform: error.platform }, message: error.message });
                 return;
             }
-            if (!retired)
-                respond(queued.socket, queued.request.requestId, toolError('project-load-failed', 'TypeScript could not load the workspace project.', error instanceof Error ? error.message : 'Read the log and repair the project.'));
+            if (!retired) {
+                if (!bootstrapped)
+                    respond(queued.socket, queued.request.requestId, toolError('project-load-failed', 'TypeScript could not load the workspace project.', error instanceof Error ? error.message : 'Read the log and repair the project.'));
+                else {
+                    append(paths, `command failed command=${currentCommand ?? 'unknown'}\n${error instanceof Error && error.stack ? error.stack : safe(error)}`);
+                    const failure = toolError('command-failed', safe(error), 'Read the resident log, then retry the command.');
+                    failure.received = currentCommand ?? 'unknown';
+                    respond(queued.socket, queued.request.requestId, failure);
+                }
+            }
         }
         finally {
             if (activeTimer)
@@ -415,12 +471,32 @@ async function main() {
             finishSocket(socket);
             return;
         }
+        if (request.operation === 'seed') {
+            const dest = request.seed?.dest;
+            const refusal = refuseSeed(dest, path.dirname(paths.state), bootstrapped && store !== undefined, store?.busy ?? false);
+            if (refusal)
+                respond(socket, request.requestId, toolError('server-unavailable', refusal, 'Retry after the resident is ready with a new destination under the tsym cache.'));
+            else {
+                try {
+                    store.checkpoint();
+                    const bytes = copyStore(paths.store, dest);
+                    respond(socket, request.requestId, { data: { element: 'seed', attributes: { root, store: dest, bytes } }, count: 1 });
+                }
+                catch (error) {
+                    respond(socket, request.requestId, toolError('server-unavailable', 'The resident could not copy its store.', error instanceof Error ? error.message : 'Retry after the current refresh completes.'));
+                }
+            }
+            finishSocket(socket);
+            return;
+        }
         if (request.operation === 'status' && forceRebuild && !bootstrapped) {
             try {
-                await loadProjects();
+                await loadProjects({ socket, requestId: request.requestId });
             }
             catch (error) {
-                if (error instanceof EngineBinaryError || error instanceof TypeScriptBinaryError)
+                if (error instanceof DeadlineExceeded)
+                    respond(socket, request.requestId, startupDeadlineFailure(error.phase));
+                else if (error instanceof EngineBinaryError || error instanceof TypeScriptBinaryError)
                     respond(socket, request.requestId, { category: 'tool', code: error.code, attributes: { platform: error.platform }, message: error.message });
                 else
                     respond(socket, request.requestId, toolError('project-load-failed', 'TypeScript could not load the workspace project.', error instanceof Error ? error.message : 'Read the log and repair the project.'));
@@ -442,7 +518,7 @@ async function main() {
             const snapshot = index?.current();
             const receipt = snapshot?.built.receipt;
             const indexedCommit = readMetadata(paths.store)?.indexedCommit;
-            respond(socket, request.requestId, { data: { element: 'server', attributes: { root, state, pid: process.pid, port: paths.port, log: paths.log, idle: `${idleSeconds()}s`, uptime: `${Math.floor(performance.now() - bootedAtMonotonic)}ms`, memory, typescript: semantic ? bundledTypeScriptVersion() : undefined, store: paths.store, indexedCommit, declarations: receipt?.declarations, edges: receipt ? Object.values(receipt.relationships).reduce((total, count) => total + count, 0) : undefined, notInProgram: semantic ? unconfiguredFileCount(root, semantic.projects.records()) : undefined, index: snapshot?.state, indexDuration: receipt ? `${Math.round(receipt.durationMs)}ms` : undefined } }, count: 1 });
+            respond(socket, request.requestId, { data: { element: 'server', attributes: { root, state, pid: process.pid, port: paths.port, log: paths.log, idle: `${idleSeconds()}s`, uptime: `${Math.floor(performance.now() - bootedAtMonotonic)}ms`, memory, typescript: semantic ? bundledTypeScriptVersion() : undefined, store: paths.store, seededFrom, indexedCommit, declarations: receipt?.declarations, edges: receipt ? Object.values(receipt.relationships).reduce((total, count) => total + count, 0) : undefined, notInProgram: semantic ? unconfiguredFileCount(root, semantic.projects.records()) : undefined, index: snapshot?.state, indexDuration: receipt ? `${Math.round(receipt.durationMs)}ms` : undefined } }, count: 1 });
             return;
         }
         if (request.operation === 'stop') {
@@ -453,7 +529,7 @@ async function main() {
                     clearTimeout(idleTimer);
                 publishState(paths, publishedState());
                 for (const [invokeSocket, requestId] of invokeSockets) {
-                    const deadlineAt = active?.socket === invokeSocket ? (loading ? loadDeadlineAt : activeDeadlineAt) : undefined;
+                    const deadlineAt = active?.socket === invokeSocket ? (loading ? indexBuildDeadlineAt ?? loadDeadlineAt : activeDeadlineAt) : undefined;
                     sendPhase(invokeSocket, requestId, 'stopping', deadlineAt === undefined ? undefined : remaining(deadlineAt));
                 }
                 const completion = toolError('server-unavailable', 'The resident is stopping.', 'Wait for stop to complete before invoking tsym.');

package/dist/server/wire.d.ts

@@ -1,6 +1,6 @@
 import type { Answer, Invocation, InvocationError, ToolError } from '../commands/types.js';
 export declare const WIRE_VERSION = 1;
-export type Operation = 'invoke' | 'status' | 'stop';
+export type Operation = 'invoke' | 'status' | 'stop' | 'seed';
 export interface WireInvocation {
     path: string[];
     cwd: string;
@@ -14,6 +14,9 @@ export interface WireRequest {
     root: string;
     operation: Operation;
     invocation?: WireInvocation;
+    seed?: {
+        dest: string;
+    };
 }
 export interface PhaseFrame {
     type: 'phase';

package/dist/store/load.js

@@ -31,8 +31,8 @@ export function replaceFiles(store, files, graph) {
     validateGraph(graph);
     return store.transaction(() => {
         const history = checkpointHistory(store, replaced);
-        for (const file of replaced)
-            store.execute(`MATCH (d:Declaration) WHERE d.file = ${literal(file)} DETACH DELETE d`);
+        if (replaced.size > 0)
+            store.execute('MATCH (d:Declaration) WHERE d.file IN $files DETACH DELETE d', { files: [...replaced] });
         copyRows(store, 'Declaration', declarationColumns, graph.declarations);
         copyMissingExternals(store, graph.externals);
         copyMissingCommits(store, graph.commits ?? []);

package/dist/store/meta.d.ts

@@ -1,12 +1,10 @@
 import type { ConfiguredProjects } from '../ts7/projects.js';
-export interface IndexedFileMeta {
-    size: number;
-    mtimeMs: number;
-}
+export type IndexedFileMeta = string;
 export interface StoreMetadata {
     schemaVersion: number;
     tsVersion: string;
     tsymBuild: string;
+    root: string;
     indexedCommit: string;
     configSet: string[];
     configHashes: Record<string, string>;
@@ -18,11 +16,17 @@ export interface StoreMetadata {
 }
 export declare function metadataPath(storePath: string): string;
 export declare function readMetadata(storePath: string): StoreMetadata | null;
+/** A store this build cannot read, or without readable metadata, is deleted so the next build starts from nothing. */
+export declare function discardIncompatibleStore(storePath: string, identity: StoreFormatIdentity): boolean;
 export declare function writeMetadata(storePath: string, metadata: StoreMetadata): void;
 /** Captures every input whose change can alter the configured-program graph. */
-export declare function metadataFor(root: string, projects: ConfiguredProjects, indexedCommit: string, indexDurationMs?: number, tsVersion?: string): StoreMetadata;
-/** A persisted store can be rehydrated only when its schema, program shape, and checkpoint still match. */
-export declare function canReuse(metadata: StoreMetadata | null, expected: StoreMetadata): boolean;
-/** Source changes do not invalidate the graph shape; startup rehydrates then performs the ordinary refresh. */
-export declare function hasSourceDrift(metadata: StoreMetadata, expected: StoreMetadata): boolean;
+export interface StoreFormatIdentity {
+    schemaVersion: number;
+    tsVersion: string;
+    tsymBuild: string;
+}
+export declare function formatIdentity(tsVersion?: string): StoreFormatIdentity;
+export declare function metadataFor(root: string, projects: ConfiguredProjects, indexedCommit: string, indexDurationMs?: number, identity?: StoreFormatIdentity): StoreMetadata;
+export declare function hasDrift(metadata: StoreMetadata, expected: StoreMetadata): boolean;
+export declare function sameFormat(metadata: Pick<StoreMetadata, 'schemaVersion' | 'tsVersion' | 'tsymBuild'>, identity: StoreFormatIdentity): boolean;
 export declare function hashTsymBuild(dist?: string): string;

package/dist/store/meta.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as ts from 'ts5';
@@ -20,6 +20,22 @@ export function readMetadata(storePath) {
         throw error;
     }
 }
+/** A store this build cannot read, or without readable metadata, is deleted so the next build starts from nothing. */
+export function discardIncompatibleStore(storePath, identity) {
+    if (!existsSync(storePath))
+        return false;
+    let metadata = null;
+    try {
+        metadata = readMetadata(storePath);
+    }
+    catch {
+        metadata = null;
+    }
+    if (metadata !== null && sameFormat(metadata, identity))
+        return false;
+    rmSync(storePath, { recursive: true, force: true });
+    return true;
+}
 export function writeMetadata(storePath, metadata) {
     if (metadata.schemaVersion !== STORE_SCHEMA_VERSION)
         throw new Error(`Store metadata schema version must be ${STORE_SCHEMA_VERSION}.`);
@@ -29,37 +45,33 @@ export function writeMetadata(storePath, metadata) {
     writeFileSync(temporary, `${JSON.stringify(metadata)}\n`, { mode: 0o600 });
     renameSync(temporary, target);
 }
-/** Captures every input whose change can alter the configured-program graph. */
-export function metadataFor(root, projects, indexedCommit, indexDurationMs = 0, tsVersion = bundledTsVersion()) {
+export function formatIdentity(tsVersion = bundledTsVersion()) {
+    return { schemaVersion: STORE_SCHEMA_VERSION, tsVersion, tsymBuild: hashTsymBuild() };
+}
+export function metadataFor(root, projects, indexedCommit, indexDurationMs = 0, identity = formatIdentity()) {
     const configs = [...new Set(projects.records().map((project) => path.resolve(project.config)))].sort();
     const shapeConfigs = inheritedConfigs(configs);
     const files = [...new Set(projects.records().flatMap((project) => [...project.files]))].sort();
     return {
-        schemaVersion: STORE_SCHEMA_VERSION,
-        tsVersion,
-        tsymBuild: hashTsymBuild(),
+        ...identity,
+        root,
         indexedCommit,
         configSet: configs.map((file) => relative(root, file)),
         configHashes: Object.fromEntries(shapeConfigs.map((file) => [relative(root, file), hashFile(file)])),
         packageHash: hashOptional(path.join(root, 'package.json')),
         lockfileHash: lockfiles.map((name) => `${name}:${hashOptional(path.join(root, name))}`).join('|'),
         indexDurationMs,
-        files: Object.fromEntries(files.map((file) => {
-            const stat = statSync(file);
-            return [relative(root, file), { size: stat.size, mtimeMs: stat.mtimeMs }];
-        })),
+        files: Object.fromEntries(files.map((file) => [relative(root, file), hashFile(file)])),
     };
 }
-/** A persisted store can be rehydrated only when its schema, program shape, and checkpoint still match. */
-export function canReuse(metadata, expected) {
-    return metadata !== null && JSON.stringify(shapeOf(metadata)) === JSON.stringify(shapeOf(expected));
+export function hasDrift(metadata, expected) {
+    return JSON.stringify(driftShape(metadata)) !== JSON.stringify(driftShape(expected));
 }
-/** Source changes do not invalidate the graph shape; startup rehydrates then performs the ordinary refresh. */
-export function hasSourceDrift(metadata, expected) {
-    return JSON.stringify(metadata.files) !== JSON.stringify(expected.files);
+export function sameFormat(metadata, identity) {
+    return metadata.schemaVersion === identity.schemaVersion && metadata.tsVersion === identity.tsVersion && metadata.tsymBuild === identity.tsymBuild;
 }
-function shapeOf(metadata) {
-    const { files: _files, indexDurationMs: _duration, ...shape } = metadata;
+function driftShape(metadata) {
+    const { indexedCommit: _commit, indexDurationMs: _duration, ...shape } = metadata;
     return shape;
 }
 function inheritedConfigs(configs) {

package/dist/store/schema.d.ts

@@ -1,4 +1,4 @@
-export declare const STORE_SCHEMA_VERSION = 2;
+export declare const STORE_SCHEMA_VERSION = 3;
 export declare const NODE_TABLES: readonly ["CREATE NODE TABLE Declaration(key STRING, at STRING, name STRING, qname STRING, kind STRING, exported BOOL, file STRING, dir STRING, top STRING, line INT64, col INT64, endLine INT64, lines INT64, declCount INT64, container STRING, PRIMARY KEY(key))", "CREATE NODE TABLE External(key STRING, module STRING, name STRING, PRIMARY KEY(key))", "CREATE NODE TABLE Commit(hash STRING, ts STRING, author STRING, subject STRING, PRIMARY KEY(hash))"];
 export declare const RELATION_TABLES: readonly ["CREATE REL TABLE CONTAINS(FROM Declaration TO Declaration)", "CREATE REL TABLE REFERENCES(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, col INT64, role STRING)", "CREATE REL TABLE CALLS(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, col INT64, dispatch BOOL)", "CREATE REL TABLE IMPLEMENTS(FROM Declaration TO Declaration)", "CREATE REL TABLE EXTENDS(FROM Declaration TO Declaration)", "CREATE REL TABLE TYPE_MENTION(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, col INT64, position STRING)", "CREATE REL TABLE IMPORTS(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, names STRING)", "CREATE REL TABLE EXPORTS(FROM Declaration TO Declaration, name STRING, line INT64, col INT64)", "CREATE REL TABLE CHANGED(FROM Commit TO Declaration, added INT64, removed INT64)", "CREATE REL TABLE RENAMED_FROM(FROM Declaration TO Commit, oldKey STRING, basis STRING)"];
 export declare const SCHEMA_STATEMENTS: readonly ["CREATE NODE TABLE Declaration(key STRING, at STRING, name STRING, qname STRING, kind STRING, exported BOOL, file STRING, dir STRING, top STRING, line INT64, col INT64, endLine INT64, lines INT64, declCount INT64, container STRING, PRIMARY KEY(key))", "CREATE NODE TABLE External(key STRING, module STRING, name STRING, PRIMARY KEY(key))", "CREATE NODE TABLE Commit(hash STRING, ts STRING, author STRING, subject STRING, PRIMARY KEY(hash))", "CREATE REL TABLE CONTAINS(FROM Declaration TO Declaration)", "CREATE REL TABLE REFERENCES(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, col INT64, role STRING)", "CREATE REL TABLE CALLS(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, col INT64, dispatch BOOL)", "CREATE REL TABLE IMPLEMENTS(FROM Declaration TO Declaration)", "CREATE REL TABLE EXTENDS(FROM Declaration TO Declaration)", "CREATE REL TABLE TYPE_MENTION(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, col INT64, position STRING)", "CREATE REL TABLE IMPORTS(FROM Declaration TO Declaration, FROM Declaration TO External, line INT64, names STRING)", "CREATE REL TABLE EXPORTS(FROM Declaration TO Declaration, name STRING, line INT64, col INT64)", "CREATE REL TABLE CHANGED(FROM Commit TO Declaration, added INT64, removed INT64)", "CREATE REL TABLE RENAMED_FROM(FROM Declaration TO Commit, oldKey STRING, basis STRING)"];

package/dist/store/schema.js

@@ -1,4 +1,4 @@
-export const STORE_SCHEMA_VERSION = 2;
+export const STORE_SCHEMA_VERSION = 3;
 export const NODE_TABLES = [
     'CREATE NODE TABLE Declaration(key STRING, at STRING, name STRING, qname STRING, kind STRING, exported BOOL, file STRING, dir STRING, top STRING, line INT64, col INT64, endLine INT64, lines INT64, declCount INT64, container STRING, PRIMARY KEY(key))',
     'CREATE NODE TABLE External(key STRING, module STRING, name STRING, PRIMARY KEY(key))',

package/dist/store/seed.d.ts

@@ -0,0 +1,13 @@
+import { type ServerPaths } from '../server/lifecycle.js';
+import { type StoreFormatIdentity, type StoreMetadata } from './meta.js';
+export interface SeedReceipt {
+    root: string;
+    bytes: number;
+    durationMs: number;
+}
+/** Finds compatible sibling stores and installs one only after a complete copy validates. */
+export declare function seedFromSibling(root: string, paths: ServerPaths, expected: StoreMetadata, identity: StoreFormatIdentity): Promise<SeedReceipt | undefined>;
+/** Copies a resident's store after the owner checkpointed it. The owner excludes its process-local marker. */
+export declare function copyStore(source: string, destination: string): number;
+/** Returns the wire refusal reason, keeping the owner’s destination safety contract testable. */
+export declare function refuseSeed(dest: unknown, cacheBase: string, bootstrapped: boolean, busy: boolean): string | undefined;