fluffy-context 0.3.1 → 0.6.0

package/dist/src/cognition/git-observer.js

@@ -0,0 +1,61 @@
+import { readGitWorktreeState } from '../git/git-adapter.js';
+import { appendEvent } from './journal.js';
+import { rebuildProjections } from './projections.js';
+function anchor(state) {
+    return { worktreeId: state.worktreeId, branch: state.branch, ref: state.ref, head: state.commit };
+}
+function key(state) {
+    return `${state.worktreeId ?? 'none'}\0${state.ref ?? 'detached'}\0${state.commit ?? 'missing'}`;
+}
+export class GitObserver {
+    projectRoot;
+    previous = null;
+    pending = Promise.resolve();
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    observeNow() {
+        const observation = this.pending.then(() => this.observe());
+        this.pending = observation.then(() => undefined, () => undefined);
+        return observation;
+    }
+    async drain() {
+        await this.pending;
+    }
+    async observe() {
+        const state = await readGitWorktreeState(this.projectRoot);
+        const previous = this.previous;
+        const changed = !previous || key(previous) !== key(state);
+        if (!changed)
+            return { state, changed: false };
+        const currentKey = key(state);
+        await appendEvent(this.projectRoot, {
+            type: 'git.state.observed',
+            source: { kind: 'git-observer' },
+            idempotencyKey: `git:state:${currentKey}`,
+            git: anchor(state),
+            payload: { detached: state.detached, fingerprint: state.fingerprint },
+        });
+        if (previous && (previous.ref !== state.ref || previous.branch !== state.branch || previous.worktreeId !== state.worktreeId)) {
+            await appendEvent(this.projectRoot, {
+                type: 'git.branch.changed',
+                source: { kind: 'git-observer' },
+                idempotencyKey: `git:branch:${previous.worktreeId ?? 'none'}:${previous.ref ?? 'detached'}:${currentKey}`,
+                git: anchor(state),
+                payload: { previous: anchor(previous), current: anchor(state) },
+            });
+        }
+        if (previous && previous.commit !== state.commit) {
+            await appendEvent(this.projectRoot, {
+                type: 'git.head.changed',
+                source: { kind: 'git-observer' },
+                idempotencyKey: `git:head:${previous.worktreeId ?? 'none'}:${previous.commit ?? 'missing'}:${currentKey}`,
+                git: anchor(state),
+                payload: { previous: anchor(previous), current: anchor(state) },
+            });
+        }
+        this.previous = state;
+        await rebuildProjections(this.projectRoot);
+        return { state, changed: true };
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { CognitionEvent, CognitionEventSource, CognitionEventType, CognitionGitAnchor } from './types.js';
+export interface AppendEventInput<T = Record<string, unknown>> {
+    eventId?: string;
+    type: CognitionEventType;
+    occurredAt?: string;
+    source?: {
+        kind: CognitionEventSource;
+        instanceId?: string;
+    };
+    correlationId?: string;
+    idempotencyKey: string;
+    git?: CognitionGitAnchor;
+    privacy?: {
+        classification: 'metadata' | 'redacted-text';
+        redactionCount: number;
+    };
+    payload: T;
+}
+export declare function eventHash<T>(event: Omit<CognitionEvent<T>, 'hash'>): string;
+export declare function readJournal(startPath?: string): Promise<CognitionEvent[]>;
+export declare function appendEvent<T>(startPath: string | undefined, input: AppendEventInput<T>): Promise<{
+    event: CognitionEvent<T>;
+    appended: boolean;
+}>;

package/dist/src/cognition/journal.js

@@ -0,0 +1,113 @@
+import crypto from 'node:crypto';
+import { appendFile, mkdir, readFile, readdir, truncate } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { loadManifest } from '../runtime/init.js';
+import { withLock } from '../storage/lock.js';
+import { cognitionJournalDirectory, locksDirectory } from '../storage/layout.js';
+const segmentName = '00000001.ndjson';
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(',')}}`;
+}
+function digest(value) {
+    return crypto.createHash('sha256').update(canonical(value)).digest('hex');
+}
+function eventId() {
+    return `evt-${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
+}
+export function eventHash(event) {
+    return digest(event);
+}
+async function journalFiles(projectRoot) {
+    try {
+        return (await readdir(cognitionJournalDirectory(projectRoot))).filter((file) => file.endsWith('.ndjson')).sort();
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function recoverPartialTail(projectRoot) {
+    const files = await journalFiles(projectRoot);
+    const file = files.at(-1);
+    if (!file)
+        return;
+    const filePath = path.join(cognitionJournalDirectory(projectRoot), file);
+    const content = await readFile(filePath, 'utf8');
+    if (content.endsWith('\n'))
+        return;
+    const boundary = content.lastIndexOf('\n');
+    const tail = content.slice(boundary + 1);
+    try {
+        JSON.parse(tail);
+    }
+    catch {
+        await truncate(filePath, boundary < 0 ? 0 : boundary + 1);
+    }
+}
+export async function readJournal(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const events = [];
+    let previousHash = null;
+    for (const file of await journalFiles(projectRoot)) {
+        const content = await readFile(path.join(cognitionJournalDirectory(projectRoot), file), 'utf8');
+        const lines = content.split('\n');
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index];
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch (error) {
+                if (index === lines.length - 1 && !content.endsWith('\n'))
+                    break;
+                throw new Error(`invalid journal record ${file}:${index + 1}: ${error instanceof Error ? error.message : 'invalid JSON'}`);
+            }
+            const { hash, ...withoutHash } = event;
+            if (event.schemaVersion !== 2 || !event.eventId || event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
+                throw new Error(`invalid journal hash chain at ${file}:${index + 1}`);
+            }
+            previousHash = event.hash;
+            events.push(event);
+        }
+    }
+    return events;
+}
+export async function appendEvent(startPath, input) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return withLock(`${locksDirectory(projectRoot)}/cognition-journal.lock`, async () => {
+        await recoverPartialTail(projectRoot);
+        const existing = await readJournal(projectRoot);
+        const duplicate = existing.find((event) => event.idempotencyKey === input.idempotencyKey);
+        if (duplicate)
+            return { event: duplicate, appended: false };
+        const now = new Date().toISOString();
+        const eventWithoutHash = {
+            eventId: input.eventId ?? eventId(),
+            schemaVersion: 2,
+            type: input.type,
+            occurredAt: input.occurredAt ?? now,
+            observedAt: now,
+            projectId: (await loadManifest(projectRoot)).projectId,
+            source: input.source ?? { kind: 'cli' },
+            ...(input.correlationId ? { correlationId: input.correlationId } : {}),
+            idempotencyKey: input.idempotencyKey,
+            git: input.git ?? { worktreeId: null, branch: null, ref: null, head: null },
+            privacy: input.privacy ?? { classification: 'metadata', redactionCount: 0 },
+            payload: input.payload,
+            previousHash: existing.at(-1)?.hash ?? null,
+        };
+        const event = { ...eventWithoutHash, hash: eventHash(eventWithoutHash) };
+        await mkdir(cognitionJournalDirectory(projectRoot), { recursive: true });
+        await appendFile(path.join(cognitionJournalDirectory(projectRoot), segmentName), `${JSON.stringify(event)}\n`, 'utf8');
+        return { event, appended: true };
+    });
+}

package/dist/src/cognition/migration-v1.d.ts

@@ -0,0 +1,7 @@
+import { type MigrationReport } from './types.js';
+export declare function importV1(startPath?: string): Promise<MigrationReport>;
+export declare function reconcileV1State(startPath?: string): Promise<void>;
+export declare function verifyV1Import(startPath?: string): Promise<{
+    verified: boolean;
+    issues: string[];
+}>;

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

@@ -0,0 +1,201 @@
+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';
+}
+function eventType(record, live = false) {
+    const status = record.record.status;
+    if (record.kind === 'context')
+        return live ? 'context.state.recorded' : 'context.checkpoint.imported';
+    if (record.kind === 'note')
+        return record.record.absorbedBySnapshotId ? 'note.absorbed' : record.record.status === 'resolved' ? 'note.resolved' : 'note.recorded';
+    if (record.kind === 'knowledge')
+        return status === 'verified' ? 'knowledge.verified' : status === 'deprecated' ? 'knowledge.deprecated' : status === 'rejected' ? 'knowledge.rejected' : 'knowledge.proposed';
+    return status === 'verified' ? 'deadend.verified' : status === 'obsolete' ? 'deadend.obsoleted' : status === 'rejected' ? 'deadend.rejected' : 'deadend.proposed';
+}
+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 event = await appendEvent(projectRoot, {
+                type: eventType(record),
+                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) {
+            await appendEvent(projectRoot, {
+                type: eventType(record, true),
+                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,13 @@
+import type { CognitionEvent, CognitionRetrievalProjection } from './types.js';
+export interface V2OrientationPlan {
+    contextId: string;
+    snapshotId: string;
+    knowledgeIds: ReadonlySet<string>;
+    deadendIds: ReadonlySet<string>;
+    noteIds: ReadonlySet<string>;
+    retrieval: CognitionRetrievalProjection;
+    currentGit: CognitionEvent['git'];
+    selection: 'requested-context' | 'exact-worktree-ref' | 'legacy-ref-branch';
+}
+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,94 @@
+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 { buildRetrievalProjection } from './retrieval.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;
+        let selection = 'requested-context';
+        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;
+            selection = exact?.activeContextRef ? 'exact-worktree-ref' : 'legacy-ref-branch';
+        }
+        if (!selected || !projection.contexts[`${selected.contextId}:${selected.snapshotId}`])
+            return null;
+        return {
+            ...selected,
+            ...latestRecords(events, current, selected.contextId),
+            retrieval: buildRetrievalProjection(events),
+            currentGit: { worktreeId: current.worktreeId, branch: current.branch, ref: current.ref, head: current.commit },
+            selection,
+        };
+    }
+    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,130 @@
+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, cognitionRetrievalProjectionPath, } from '../storage/layout.js';
+import { readJournal } from './journal.js';
+import { buildRetrievalProjection } from './retrieval.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 (['knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected'].includes(event.type) && record) {
+            const knowledgeId = recordId(record, 'knowledge');
+            if (knowledgeId)
+                projection.knowledge[knowledgeId] = payload;
+        }
+        if (['deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected'].includes(event.type) && 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 retrieval = buildRetrievalProjection(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),
+        atomicWriteJson(cognitionRetrievalProjectionPath(projectRoot), retrieval),
+        ...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>;