fluffy-context 0.3.1 → 0.5.0

package/dist/src/cognition/migration-v1.js

@@ -0,0 +1,199 @@
+import crypto from 'node:crypto';
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { loadManifest } from '../runtime/init.js';
+import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+import { rebuildSnapshot } from '../runtime/runtime.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { withLock } from '../storage/lock.js';
+import { cognitionManifestPath, cognitionPolicyPath, cognitionQuarantineDirectory, cognitionV1ImportPath, cognitionV1SyncPath, contextMetadataPath, contextsRoot, locksDirectory, manifestPath, snapshotPath, snapshotsDirectory, } from '../storage/layout.js';
+import { readJson } from '../storage/json-store.js';
+import { appendEvent } from './journal.js';
+import { rebuildProjections } from './projections.js';
+import { v1Fingerprint } from './v1-bridge.js';
+import { migrationReadiness } from './readiness.js';
+import { COGNITION_LAYOUT_VERSION } from './types.js';
+function sha256(value) {
+    return crypto.createHash('sha256').update(value).digest('hex');
+}
+function isNotFound(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+async function readOptional(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return null;
+        throw error;
+    }
+}
+async function sourceRecords(projectRoot) {
+    const sources = [];
+    const records = [];
+    const snapshotAnchors = new Map();
+    const v1ManifestPath = manifestPath(projectRoot);
+    sources.push({ filePath: v1ManifestPath, content: await readFile(v1ManifestPath, 'utf8') });
+    const contextIds = (await readdir(contextsRoot(projectRoot))).sort();
+    for (const contextId of contextIds) {
+        const contextFile = contextMetadataPath(projectRoot, contextId);
+        const contextContent = await readFile(contextFile, 'utf8');
+        sources.push({ filePath: contextFile, content: contextContent });
+        const context = await readJson(contextFile);
+        const snapshots = (await readdir(snapshotsDirectory(projectRoot, contextId))).filter((file) => file.endsWith('.json')).sort();
+        for (const file of snapshots) {
+            const snapshotId = file.slice(0, -'.json'.length);
+            const filePath = snapshotPath(projectRoot, contextId, snapshotId);
+            const content = await readFile(filePath, 'utf8');
+            sources.push({ filePath, content });
+            const snapshot = await readJson(filePath);
+            await rebuildSnapshot(projectRoot, contextId, snapshotId);
+            const git = { branch: snapshot.branch, head: snapshot.commit };
+            snapshotAnchors.set(`${contextId}:${snapshotId}`, git);
+            records.push({
+                kind: 'context',
+                id: `${contextId}:${snapshotId}`,
+                occurredAt: snapshot.createdAt,
+                git,
+                record: { context, snapshot },
+                sourcePath: filePath,
+                sourceHash: sha256(content),
+            });
+        }
+    }
+    const noteFile = path.join(projectRoot, '.context', 'notes.json');
+    const knowledgeFile = path.join(projectRoot, '.context', 'knowledge.json');
+    const deadendFile = path.join(projectRoot, '.context', 'deadends.json');
+    for (const [kind, filePath] of [['note', noteFile], ['knowledge', knowledgeFile], ['deadend', deadendFile]]) {
+        const content = await readOptional(filePath);
+        if (content === null)
+            continue;
+        sources.push({ filePath, content });
+        const sourceHash = sha256(content);
+        const items = kind === 'note' ? await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })
+            : kind === 'knowledge' ? await listKnowledge(projectRoot, true)
+                : await listDeadends(projectRoot, true);
+        for (const item of items) {
+            const record = item;
+            const id = typeof record.noteId === 'string' ? record.noteId : typeof record.knowledgeId === 'string' ? record.knowledgeId : record.deadendId;
+            const occurredAt = item.createdAt;
+            const contextId = 'contextId' in item ? item.contextId : 'sourceContextId' in item ? item.sourceContextId : null;
+            const snapshotId = 'snapshotId' in item ? item.snapshotId : 'sourceSnapshotId' in item ? item.sourceSnapshotId : null;
+            if (snapshotId && !contextId)
+                throw new Error(`${kind} ${id} has a snapshot without a context`);
+            if (contextId && snapshotId)
+                await rebuildSnapshot(projectRoot, contextId, snapshotId);
+            records.push({ kind, id, occurredAt, git: contextId && snapshotId ? snapshotAnchors.get(`${contextId}:${snapshotId}`) ?? { branch: null, head: null } : { branch: null, head: null }, record: item, sourcePath: filePath, sourceHash });
+        }
+    }
+    const sourceHash = sha256(sources.sort((left, right) => left.filePath.localeCompare(right.filePath)).map((source) => `${source.filePath}\0${sha256(source.content)}`).join('\n'));
+    return { records: records.sort((left, right) => left.occurredAt.localeCompare(right.occurredAt) || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id)), sourceHash };
+}
+async function writeV2Metadata(projectRoot) {
+    const v1 = await loadManifest(projectRoot);
+    const manifest = { schemaVersion: 2, layoutVersion: COGNITION_LAYOUT_VERSION, projectId: v1.projectId, createdAt: new Date().toISOString(), policyVersion: 1 };
+    const policy = { schemaVersion: 2, enabled: false, allowHookStartup: false, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
+    await Promise.all([atomicWriteJson(cognitionManifestPath(projectRoot), manifest), atomicWriteJson(cognitionPolicyPath(projectRoot), policy)]);
+}
+async function quarantineReadiness(projectRoot, readiness) {
+    await mkdir(cognitionQuarantineDirectory(projectRoot), { recursive: true });
+    await atomicWriteJson(path.join(cognitionQuarantineDirectory(projectRoot), 'v1-readiness.json'), {
+        schemaVersion: 2,
+        recordedAt: new Date().toISOString(),
+        eligible: readiness.eligible,
+        issues: readiness.issues,
+    });
+}
+export async function importV1(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return withLock(`${locksDirectory(projectRoot)}/cognition-migration.lock`, async () => {
+        const readiness = await migrationReadiness(projectRoot);
+        if (!readiness.eligible) {
+            const report = { ...readiness, applied: false, importedEventIds: [] };
+            await quarantineReadiness(projectRoot, report);
+            return report;
+        }
+        const { records, sourceHash } = await sourceRecords(projectRoot);
+        const existingReceipt = await readOptional(cognitionV1ImportPath(projectRoot));
+        if (existingReceipt) {
+            const receipt = JSON.parse(existingReceipt);
+            if (receipt.schemaVersion !== 2 || receipt.sourceHash !== sourceHash)
+                throw new Error('v1 source changed after import; v2 historical import is immutable');
+            await rebuildProjections(projectRoot);
+            await atomicWriteJson(cognitionV1SyncPath(projectRoot), { schemaVersion: 2, fingerprint: await v1Fingerprint(projectRoot), updatedAt: new Date().toISOString() });
+            return { ...readiness, applied: true, importedEventIds: receipt.eventIds };
+        }
+        await writeV2Metadata(projectRoot);
+        const importedEventIds = [];
+        for (const record of records) {
+            const status = record.record.status;
+            const event = await appendEvent(projectRoot, {
+                type: record.kind === 'context' ? 'context.checkpoint.imported'
+                    : record.kind === 'note' ? 'note.recorded'
+                        : record.kind === 'knowledge' ? status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed'
+                            : status === 'verified' ? 'deadend.verified' : 'deadend.proposed',
+                occurredAt: record.occurredAt,
+                source: { kind: 'migration' },
+                idempotencyKey: `v1:${record.sourceHash}:${record.kind}:${record.id}`,
+                git: { worktreeId: null, branch: record.git.branch, ref: record.git.branch, head: record.git.head },
+                payload: { record: record.record, sourcePath: record.sourcePath, sourceHash: record.sourceHash, anchorProvenance: record.git.branch === null && record.git.head === null ? 'global' : 'snapshot' },
+            });
+            importedEventIds.push(event.event.eventId);
+        }
+        await rebuildProjections(projectRoot);
+        await atomicWriteJson(cognitionV1SyncPath(projectRoot), { schemaVersion: 2, fingerprint: await v1Fingerprint(projectRoot), updatedAt: new Date().toISOString() });
+        const receipt = { schemaVersion: 2, sourceHash, importedAt: new Date().toISOString(), eventIds: importedEventIds, counts: readiness.counts };
+        await atomicWriteJson(cognitionV1ImportPath(projectRoot), receipt);
+        return { ...readiness, v2Present: true, applied: true, importedEventIds };
+    });
+}
+export async function reconcileV1State(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    await withLock(`${locksDirectory(projectRoot)}/cognition-migration.lock`, async () => {
+        const readiness = await migrationReadiness(projectRoot);
+        if (!readiness.eligible)
+            return;
+        const { records, sourceHash } = await sourceRecords(projectRoot);
+        for (const record of records) {
+            const status = record.record.status;
+            await appendEvent(projectRoot, {
+                type: record.kind === 'context' ? 'context.state.recorded'
+                    : record.kind === 'note' ? record.record.absorbedBySnapshotId ? 'note.absorbed' : record.record.status === 'resolved' ? 'note.resolved' : 'note.recorded'
+                        : record.kind === 'knowledge' ? status === 'verified' ? 'knowledge.verified' : 'knowledge.proposed'
+                            : status === 'verified' ? 'deadend.verified' : 'deadend.proposed',
+                occurredAt: record.occurredAt,
+                source: { kind: 'migration' },
+                idempotencyKey: `v1-live-sync:${sourceHash}:${record.kind}:${record.id}`,
+                git: { worktreeId: null, branch: record.git.branch, ref: record.git.branch, head: record.git.head },
+                payload: { record: record.record, sourcePath: record.sourcePath, sourceHash: record.sourceHash, anchorProvenance: record.git.branch === null && record.git.head === null ? 'global' : 'snapshot' },
+            });
+        }
+        await rebuildProjections(projectRoot);
+        await atomicWriteJson(cognitionV1SyncPath(projectRoot), { schemaVersion: 2, fingerprint: await v1Fingerprint(projectRoot), updatedAt: new Date().toISOString() });
+    });
+}
+export async function verifyV1Import(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    try {
+        const readiness = await migrationReadiness(projectRoot);
+        if (!readiness.eligible)
+            return { verified: false, issues: readiness.issues };
+        const receipt = JSON.parse(await readFile(cognitionV1ImportPath(projectRoot), 'utf8'));
+        const { sourceHash } = await sourceRecords(projectRoot);
+        if (receipt.sourceHash !== sourceHash)
+            return { verified: false, issues: ['v1 source changed after import'] };
+        const { projection, cursor } = await rebuildProjections(projectRoot);
+        const actual = { contexts: Object.keys(projection.contexts).length, notes: Object.keys(projection.notes).length, knowledge: Object.keys(projection.knowledge).length, deadends: Object.keys(projection.deadends).length };
+        const expected = { contexts: readiness.counts.snapshots, notes: readiness.counts.notes, knowledge: readiness.counts.knowledge, deadends: readiness.counts.deadends };
+        const issues = Object.entries(expected).flatMap(([key, count]) => actual[key] === count ? [] : [`${key} projection count mismatch`]);
+        if (!cursor.lastEventId && receipt.eventIds.length > 0)
+            issues.push('projection cursor is missing');
+        return { verified: issues.length === 0, issues };
+    }
+    catch (error) {
+        return { verified: false, issues: [error instanceof Error ? error.message : 'invalid v1 import'] };
+    }
+}

package/dist/src/cognition/orient.d.ts

@@ -0,0 +1,9 @@
+export interface V2OrientationPlan {
+    contextId: string;
+    snapshotId: string;
+    knowledgeIds: ReadonlySet<string>;
+    deadendIds: ReadonlySet<string>;
+    noteIds: ReadonlySet<string>;
+}
+export declare function selectV2Orientation(projectRoot: string, contextId?: string): Promise<V2OrientationPlan | null>;
+export declare function v2Enabled(projectRoot: string): Promise<boolean>;

package/dist/src/cognition/orient.js

@@ -0,0 +1,85 @@
+import { access } from 'node:fs/promises';
+import { readGitWorktreeState } from '../git/git-adapter.js';
+import { cognitionManifestPath, cognitionPolicyPath } from '../storage/layout.js';
+import { readJson } from '../storage/json-store.js';
+import { loadManifest } from '../runtime/init.js';
+import { readJournal } from './journal.js';
+import { projectEvents, workspaceKey } from './projections.js';
+import { v1Synced } from './v1-bridge.js';
+function contextReference(value) {
+    const boundary = value.lastIndexOf(':');
+    if (boundary <= 0 || boundary === value.length - 1)
+        return null;
+    return { contextId: value.slice(0, boundary), snapshotId: value.slice(boundary + 1) };
+}
+function record(event) {
+    const payload = event.payload;
+    return payload.record && typeof payload.record === 'object' && !Array.isArray(payload.record) ? payload.record : null;
+}
+function applicable(event, current) {
+    if (event.git.ref === null && event.git.branch === null)
+        return true;
+    return event.git.ref === current.ref && event.git.branch === current.branch && (event.git.worktreeId === null || event.git.worktreeId === current.worktreeId);
+}
+function latestRecords(events, current, contextId) {
+    const knowledge = new Map();
+    const deadends = new Map();
+    const notes = new Map();
+    for (const event of events) {
+        const item = record(event);
+        if (!item)
+            continue;
+        if (['knowledge.proposed', 'knowledge.verified'].includes(event.type) && typeof item.knowledgeId === 'string')
+            knowledge.set(item.knowledgeId, { event, record: item });
+        if (['deadend.proposed', 'deadend.verified'].includes(event.type) && typeof item.deadendId === 'string')
+            deadends.set(item.deadendId, { event, record: item });
+        if (['note.recorded', 'note.resolved', 'note.absorbed'].includes(event.type) && typeof item.noteId === 'string')
+            notes.set(item.noteId, { event, record: item });
+    }
+    return {
+        knowledgeIds: new Set([...knowledge].flatMap(([id, item]) => item.record.status === 'verified' && applicable(item.event, current) ? [id] : [])),
+        deadendIds: new Set([...deadends].flatMap(([id, item]) => item.record.status === 'verified' && applicable(item.event, current) ? [id] : [])),
+        noteIds: new Set([...notes].flatMap(([id, item]) => item.record.contextId === contextId && item.record.status === 'open' && item.record.absorbedBySnapshotId === null && applicable(item.event, current) ? [id] : [])),
+    };
+}
+export async function selectV2Orientation(projectRoot, contextId) {
+    try {
+        const [manifest, cognition, policy] = await Promise.all([
+            loadManifest(projectRoot),
+            readJson(cognitionManifestPath(projectRoot)),
+            readJson(cognitionPolicyPath(projectRoot)),
+        ]);
+        if (cognition.schemaVersion !== 2 || cognition.projectId !== manifest.projectId || !policy.enabled || !await v1Synced(projectRoot))
+            return null;
+        const [events, current] = await Promise.all([readJournal(projectRoot), readGitWorktreeState(projectRoot)]);
+        if (events.length === 0)
+            return null;
+        const projection = projectEvents(events);
+        let selected = null;
+        if (contextId) {
+            const matching = [...Object.keys(projection.contexts)].reverse().find((reference) => contextReference(reference)?.contextId === contextId);
+            selected = matching ? contextReference(matching) : null;
+        }
+        else {
+            const exact = projection.workspaces[workspaceKey(current)];
+            const legacy = Object.values(projection.workspaces).find((workspace) => workspace.worktreeId === null && (workspace.ref === current.ref || workspace.branch === current.branch));
+            const reference = (exact?.activeContextRef ? exact : legacy)?.activeContextRef;
+            selected = reference ? contextReference(reference) : null;
+        }
+        if (!selected || !projection.contexts[`${selected.contextId}:${selected.snapshotId}`])
+            return null;
+        return { ...selected, ...latestRecords(events, current, selected.contextId) };
+    }
+    catch {
+        return null;
+    }
+}
+export async function v2Enabled(projectRoot) {
+    try {
+        await access(cognitionManifestPath(projectRoot));
+        return (await readJson(cognitionPolicyPath(projectRoot))).enabled;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/cognition/projections.d.ts

@@ -0,0 +1,7 @@
+import type { CognitionEvent, CognitionGitAnchor, CognitionProjection, ProjectionCursor } from './types.js';
+export declare function workspaceKey(anchor: Pick<CognitionGitAnchor, 'worktreeId' | 'branch' | 'ref'>): string;
+export declare function projectEvents(events: CognitionEvent[]): CognitionProjection;
+export declare function rebuildProjections(projectRoot: string): Promise<{
+    projection: CognitionProjection;
+    cursor: ProjectionCursor;
+}>;

package/dist/src/cognition/projections.js

@@ -0,0 +1,127 @@
+import crypto from 'node:crypto';
+import { readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { cognitionBranchesDirectory, cognitionContextsProjectionPath, cognitionDeadendsProjectionPath, cognitionKnowledgeProjectionPath, cognitionNotesProjectionPath, cognitionProjectionCursorPath, } from '../storage/layout.js';
+import { readJournal } from './journal.js';
+export function workspaceKey(anchor) {
+    return crypto.createHash('sha256')
+        .update(`${anchor.worktreeId ?? 'default'}\0${anchor.ref ?? anchor.branch ?? 'detached'}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+function workspaceFor(event, existing) {
+    const key = workspaceKey(event.git);
+    return {
+        schemaVersion: 2,
+        workspaceKey: key,
+        worktreeId: event.git.worktreeId,
+        branch: event.git.branch,
+        ref: event.git.ref,
+        head: event.git.head,
+        activeContextRef: existing?.activeContextRef ?? null,
+        openObservationEventIds: existing?.openObservationEventIds ?? [],
+        pathFocus: existing?.pathFocus ?? [],
+        recentEventIds: [...(existing?.recentEventIds ?? []), event.eventId].slice(-50),
+        lastActivatedAt: event.occurredAt,
+    };
+}
+function recordPayload(event) {
+    const payload = event.payload;
+    if (!payload.record || typeof payload.record !== 'object' || Array.isArray(payload.record))
+        return null;
+    return payload;
+}
+function recordId(record, kind) {
+    const field = kind === 'note' ? 'noteId' : kind === 'knowledge' ? 'knowledgeId' : 'deadendId';
+    return typeof record[field] === 'string' ? record[field] : null;
+}
+function latestOpenObservationIds(events, notes) {
+    const latest = new Map();
+    for (const event of events) {
+        if (!['note.recorded', 'note.resolved', 'note.absorbed'].includes(event.type))
+            continue;
+        const payload = recordPayload(event);
+        const note = payload?.record;
+        if (!note)
+            continue;
+        const noteId = recordId(note, 'note');
+        if (!noteId)
+            continue;
+        notes[noteId] = payload;
+        latest.set(noteId, { eventId: event.eventId, record: note });
+    }
+    return new Set([...latest.values()].flatMap(({ eventId, record }) => record.status === 'open' && record.absorbedBySnapshotId === null ? [eventId] : []));
+}
+export function projectEvents(events) {
+    const projection = { schemaVersion: 2, contexts: {}, notes: {}, knowledge: {}, deadends: {}, workspaces: {} };
+    const openObservationIds = latestOpenObservationIds(events, projection.notes);
+    for (const event of events) {
+        const key = workspaceKey(event.git);
+        const workspace = workspaceFor(event, projection.workspaces[key]);
+        const payload = recordPayload(event);
+        const record = payload?.record;
+        if ((event.type === 'context.checkpoint.imported' || event.type === 'context.state.recorded') && record) {
+            const snapshot = record.snapshot;
+            if (snapshot && typeof snapshot.contextId === 'string' && typeof snapshot.snapshotId === 'string') {
+                const contextRef = `${snapshot.contextId}:${snapshot.snapshotId}`;
+                projection.contexts[contextRef] = payload;
+                workspace.activeContextRef = contextRef;
+            }
+        }
+        if (event.type === 'note.recorded' && record) {
+            const noteId = recordId(record, 'note');
+            if (noteId)
+                projection.notes[noteId] = payload;
+        }
+        if ((event.type === 'knowledge.proposed' || event.type === 'knowledge.verified') && record) {
+            const knowledgeId = recordId(record, 'knowledge');
+            if (knowledgeId)
+                projection.knowledge[knowledgeId] = payload;
+        }
+        if ((event.type === 'deadend.proposed' || event.type === 'deadend.verified') && record) {
+            const deadendId = recordId(record, 'deadend');
+            if (deadendId)
+                projection.deadends[deadendId] = payload;
+        }
+        if (event.type === 'note.recorded' && openObservationIds.has(event.eventId)) {
+            workspace.openObservationEventIds = [...workspace.openObservationEventIds, event.eventId].slice(-50);
+        }
+        projection.workspaces[key] = workspace;
+    }
+    return projection;
+}
+async function removeObsoleteWorkspaceFiles(projectRoot, workspaceKeys) {
+    try {
+        const files = await readdir(cognitionBranchesDirectory(projectRoot));
+        await Promise.all(files
+            .filter((file) => file.endsWith('.json') && !workspaceKeys.has(file.slice(0, -'.json'.length)))
+            .map((file) => rm(path.join(cognitionBranchesDirectory(projectRoot), file), { force: true })));
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+}
+export async function rebuildProjections(projectRoot) {
+    const events = await readJournal(projectRoot);
+    const projection = projectEvents(events);
+    const last = events.at(-1);
+    const cursor = {
+        schemaVersion: 2,
+        lastEventId: last?.eventId ?? null,
+        lastEventHash: last?.hash ?? null,
+        updatedAt: last?.observedAt ?? null,
+    };
+    await removeObsoleteWorkspaceFiles(projectRoot, new Set(Object.keys(projection.workspaces)));
+    await Promise.all([
+        atomicWriteJson(cognitionContextsProjectionPath(projectRoot), projection.contexts),
+        atomicWriteJson(cognitionNotesProjectionPath(projectRoot), projection.notes),
+        atomicWriteJson(cognitionKnowledgeProjectionPath(projectRoot), projection.knowledge),
+        atomicWriteJson(cognitionDeadendsProjectionPath(projectRoot), projection.deadends),
+        ...Object.values(projection.workspaces).map((workspace) => atomicWriteJson(`${cognitionBranchesDirectory(projectRoot)}/${workspace.workspaceKey}.json`, workspace)),
+    ]);
+    await atomicWriteJson(cognitionProjectionCursorPath(projectRoot), cursor);
+    return { projection, cursor };
+}

package/dist/src/cognition/readiness.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationReadiness } from './types.js';
+export declare function migrationReadiness(startPath?: string): Promise<MigrationReadiness>;

package/dist/src/cognition/readiness.js

@@ -0,0 +1,81 @@
+import { access, readdir } from 'node:fs/promises';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { contextMetadataPath, contextsRoot, cognitionManifestPath, manifestPath, snapshotPath, snapshotsDirectory } from '../storage/layout.js';
+import { readJson } from '../storage/json-store.js';
+import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+import { rebuildSnapshot } from '../runtime/runtime.js';
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function migrationReadiness(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const counts = { contexts: 0, snapshots: 0, notes: 0, knowledge: 0, deadends: 0 };
+    const issues = [];
+    const v1Present = await exists(manifestPath(projectRoot));
+    const v2Present = await exists(cognitionManifestPath(projectRoot));
+    if (!v1Present) {
+        issues.push('v1 manifest is missing');
+        return { projectRoot, eligible: false, v1Present, v2Present, counts, issues };
+    }
+    try {
+        const manifest = await readJson(manifestPath(projectRoot));
+        if (manifest.schemaVersion !== 1 || manifest.layoutVersion !== 'compact-json-v1' || manifest.projectRoot !== projectRoot) {
+            issues.push('v1 manifest is invalid');
+        }
+    }
+    catch (error) {
+        issues.push(`v1 manifest: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    let contextIds = [];
+    try {
+        contextIds = await readdir(contextsRoot(projectRoot));
+    }
+    catch (error) {
+        issues.push(`v1 contexts: ${error instanceof Error ? error.message : 'unavailable'}`);
+    }
+    for (const contextId of contextIds) {
+        try {
+            const context = await readJson(contextMetadataPath(projectRoot, contextId));
+            if (context.schemaVersion !== 1 || context.id !== contextId || context.projectRoot !== projectRoot) {
+                throw new Error('invalid context metadata');
+            }
+            counts.contexts += 1;
+            const snapshots = (await readdir(snapshotsDirectory(projectRoot, contextId))).filter((entry) => entry.endsWith('.json'));
+            counts.snapshots += snapshots.length;
+            for (const snapshotFile of snapshots) {
+                const snapshotId = snapshotFile.slice(0, -'.json'.length);
+                await readJson(snapshotPath(projectRoot, contextId, snapshotId));
+                await rebuildSnapshot(projectRoot, contextId, snapshotId);
+            }
+        }
+        catch (error) {
+            issues.push(`context ${contextId}: ${error instanceof Error ? error.message : 'invalid'}`);
+        }
+    }
+    try {
+        counts.notes = (await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })).length;
+    }
+    catch (error) {
+        issues.push(`notes: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    try {
+        counts.knowledge = (await listKnowledge(projectRoot, true)).length;
+    }
+    catch (error) {
+        issues.push(`knowledge: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    try {
+        counts.deadends = (await listDeadends(projectRoot, true)).length;
+    }
+    catch (error) {
+        issues.push(`deadends: ${error instanceof Error ? error.message : 'invalid'}`);
+    }
+    return { projectRoot, eligible: issues.length === 0, v1Present, v2Present, counts, issues };
+}

package/dist/src/cognition/runtime.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeLease, RuntimeStatus } from './types.js';
+export interface RuntimeServer {
+    lease: RuntimeLease;
+    close(reason?: string): Promise<void>;
+}
+export declare function serveRuntime(startPath?: string): Promise<RuntimeServer>;
+export declare function runtimeStatus(startPath?: string): Promise<RuntimeStatus>;
+export declare function enableRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function disableRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function startRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function stopRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function observeRuntime(startPath?: string): Promise<boolean>;