fluffy-context 0.3.0 → 0.5.0

package/README.md

@@ -1,8 +1,10 @@
 # Context Runtime
 
-`fluffy-context` 是面向 AI 编程会话的本地 Context Runtime CLI。0.3.0 提供可重复、安全调用的任务定位入口、MCP 工具，以及 Claude Code 的阶段性工作流引导，让 Agent 不必自行拼接恢复、共识发现与短期记录。
+`fluffy-context` 正在从面向 AI 编程会话的本地 Context Runtime CLI，演进为 **Agent 无关的本地 Knowledge Runtime**。它负责自动捕获开发过程中产生的事件、候选共识、问题、不可达路径和分支工作状态，并向任意 Agent 注入有界、可验证的业务认知。
 
-它更接近“Context 的 Git”，而不是代码备份工具：Git 仍然负责代码和真实文件变更；Context Runtime 负责 AI 工作状态、已验证共识与交接信息的本地保存和恢复。
+Git 仍然负责代码和真实文件变更，Issue 系统仍然负责任务，项目文档仍然负责设计；`fluffy-context` 补齐的是持续演进的项目认知层。最终架构是 `project → knowledge runtime → LLM`：CLI、MCP、Claude Hook 和未来 IDE/Agent 集成只是事件入口与信息注入适配器，而不是认知本体。
+
+0.5.0 在 v2 迁移、可验证事件日志、确定性投影和按项目 Runtime 基础上，完成首个 branch-aware 注入闭环：迁移并启用 Runtime 后，Orient、MCP 与 Claude Hook 会按当前 worktree/ref 选择 Context，避免跨分支任务状态泄漏。v1 的 checkpoint、Note、Knowledge 与 Deadend 写入会最佳努力镜像为 v2 事件；Runtime 也会协调检测到的外部 v1 变更。自动产物默认仍仅进入 Candidate，Verified Knowledge 仍需治理确认。
 
 ## 适用场景
 
@@ -92,10 +94,43 @@ ctx activity --context <context-id> --open
 ctx knowledge discover "支付回调"
 ctx knowledge verify <knowledge-id>
 ctx deadend verify <deadend-id>
+ctx migrate v1 --dry-run
+ctx migrate v1 --apply
+ctx migrate verify
+ctx runtime enable
+ctx runtime start
+ctx runtime status
+ctx runtime stop
 ctx status
 ctx doctor
 ```
 
+### v2 迁移与本地 Runtime
+
+v2 与既有 `.context/` 数据并存，迁移绝不会重写或修复 v1 文件。先执行只读检查，再显式导入并验证投影一致性：
+
+```bash
+ctx migrate v1 --dry-run
+ctx migrate v1 --apply
+ctx migrate verify
+```
+
+只有完成迁移后才可启用 Runtime：
+
+```bash
+ctx runtime enable
+ctx runtime start
+ctx runtime status
+ctx runtime stop
+ctx runtime disable
+```
+
+Runtime 是单项目、按需启动的本地守护进程。它只绑定 `127.0.0.1` 的动态端口，并要求存储在项目本地 `.context/v2/runtime/secret` 中的能力令牌；令牌不会显示在 CLI 状态输出或写入事件日志。启动后，Runtime 持续观察当前 worktree 的 Git 状态：初始状态会记录 `git.state.observed`，分支/ref 切换记录 `git.branch.changed`，HEAD 更新记录 `git.head.changed`。这些事件会重建 branch workspace 投影，但不会自动创建 checkpoint 或将候选信息提升为已验证共识。
+
+完成迁移并显式 `ctx runtime enable` 后，`ctx orient`、MCP `context_orient` 与 Claude Hook 会优先选择当前 worktree/ref 的 v2 workspace；它不会借用其他分支的 Context。没有匹配 workspace、v2 状态不可用或 Runtime 已禁用时，接口会安全回退到既有 v1 选择逻辑。Runtime 停止时仍可读取已验证的 v2 状态，但运行中的 Runtime 负责持续 Git 观察和 v1 写入镜像。
+
+Claude Hook 仅在宿主提供稳定的 session 与 event 标识时记录 `host.session.started` 或 `host.prompt.submitted`。提示只保存按 `promptIntentMaxChars` 截断并经过敏感值脱敏后的 intent，绝不保存原始提示；缺少稳定标识时不写入事件。默认 Hook 不启动守护进程；将 v2 policy 的 `allowHookStartup` 设为 `true` 后，SessionStart 才会在严格超时内尽力启动 Runtime，失败仍会 fail open。UserPromptSubmit 不会启动 Runtime。
+
 ### `ctx checkpoint` 和 `ctx resume`
 
 第一次 checkpoint 创建 baseline，后续变化创建 patch。相同内容返回 `no_change`；短时间内的变化可能返回 `rate_limited`，应在完成更多阶段工作后再保存。`ctx resume` 返回轻量摘要和按需使用的完整 details，并会保留其既有的 `lastUsedAt` 更新语义。
@@ -187,6 +222,6 @@ npm pack --dry-run --json
 
 ## 当前范围
 
-0.3.0 聚焦单项目、本地优先的可靠闭环和 Agent 采用路径：有界 Orient、显式 checkpoint、确定性 Knowledge/Deadend discovery、MCP `context_orient` 与可选的 Claude Code Hook 集成。
+0.5.0 聚焦单项目、本地优先的 branch-aware Knowledge Runtime MVP：有界 Orient、显式 checkpoint、确定性 Knowledge/Deadend discovery、MCP `context_orient`、可选 Claude Code Hook，以及 v1 到 v2 的显式事件日志迁移和 Git-aware 本地 Runtime。完成迁移并启用 Runtime 后，Orient、MCP 与 Hook 使用当前 worktree/ref 的 workspace 选择分支正确的 Context，并在 v2 不可用时保持 v1 回退；Runtime 负责可靠捕获生命周期、Git 元数据与后续 v1 写入镜像。带稳定宿主标识的 Hook 事件仅以脱敏、限长 intent 进入 journal。
 
-远程同步、多人协作、复杂语义检索、自动模型总结、自动 checkpoint、Context merge，以及更多状态变更型 MCP 工具不属于当前版本范围。
+远程同步、多人协作、复杂语义检索、自动模型总结、自动 checkpoint、Context merge、自动验证候选共识，以及更多状态变更型 MCP 工具不属于当前版本范围。

package/dist/src/agent/api.js

@@ -2,7 +2,8 @@ import { readdir } from 'node:fs/promises';
 import { resolveProjectRoot } from '../project/project-resolver.js';
 import { contextsRoot, contextMetadataPath } from '../storage/layout.js';
 import { isRecord, readJson } from '../storage/json-store.js';
-import { checkpoint, rebuildSnapshot, resume } from '../runtime/runtime.js';
+import { checkpoint, rebuildSnapshot, resume, resumeSnapshot } from '../runtime/runtime.js';
+import { selectV2Orientation } from '../cognition/orient.js';
 import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
 function normalized(value) {
@@ -157,7 +158,10 @@ export async function contextOrient(startPath, options = {}) {
         throw new Error('context orient query must not be empty');
     let loaded;
     try {
-        loaded = await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
+        const v2 = await selectV2Orientation(projectRoot, options.contextId);
+        loaded = v2
+            ? await resumeSnapshot(projectRoot, v2.contextId, v2.snapshotId, options.maxChars ?? 4000)
+            : await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
     }
     catch (error) {
         if (error instanceof Error && error.message === 'no active context found') {
@@ -176,26 +180,33 @@ export async function contextOrient(startPath, options = {}) {
         }
         throw error;
     }
-    const notes = await listNotes(projectRoot, {
+    const v2 = await selectV2Orientation(projectRoot, options.contextId);
+    const notes = (await listNotes(projectRoot, {
         contextId: loaded.context.id,
         openOnly: true,
-        limit: options.noteLimit ?? 20,
+        limit: v2 ? Number.MAX_SAFE_INTEGER : options.noteLimit ?? 20,
         maxChars: options.maxChars ?? 4000,
-    });
+    })).filter((note) => !v2 || v2.noteIds.has(note.noteId)).slice(0, options.noteLimit ?? 20);
     const knowledge = query === null
         ? emptyKnowledge('')
         : await discoverKnowledge(projectRoot, query, {
             scope: options.scope,
-            limit: options.knowledgeLimit ?? 10,
+            limit: v2 ? Number.MAX_SAFE_INTEGER : options.knowledgeLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
     const deadends = query === null
         ? emptyDeadends('')
         : await discoverDeadends(projectRoot, query, {
             scope: options.scope,
-            limit: options.deadendLimit ?? 10,
+            limit: v2 ? Number.MAX_SAFE_INTEGER : options.deadendLimit ?? 10,
             maxChars: options.maxChars ?? 4000,
         });
+    const applicableKnowledge = v2
+        ? { ...knowledge, total: knowledge.hits.filter((hit) => v2.knowledgeIds.has(hit.knowledge.knowledgeId)).length, hits: knowledge.hits.filter((hit) => v2.knowledgeIds.has(hit.knowledge.knowledgeId)).slice(0, options.knowledgeLimit ?? 10) }
+        : knowledge;
+    const applicableDeadends = v2
+        ? { ...deadends, total: deadends.hits.filter((hit) => v2.deadendIds.has(hit.deadend.deadendId)).length, hits: deadends.hits.filter((hit) => v2.deadendIds.has(hit.deadend.deadendId)).slice(0, options.deadendLimit ?? 10) }
+        : deadends;
     const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
     const resumeSummary = {
         progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
@@ -214,8 +225,8 @@ export async function contextOrient(startPath, options = {}) {
         || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
         || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
         || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
-    const limitedKnowledgeResult = limitKnowledge(knowledge, budget);
-    const limitedDeadendResult = limitDeadends(deadends, budget);
+    const limitedKnowledgeResult = limitKnowledge(applicableKnowledge, budget);
+    const limitedDeadendResult = limitDeadends(applicableDeadends, budget);
     const limitedNotesResult = limitNotes(notes, budget);
     return {
         status: 'ready',

package/dist/src/cli/main.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import { checkpoint, resume } from '../runtime/runtime.js';
 import { contextOrient } from '../agent/api.js';
+import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
+import { disableRuntime, enableRuntime, runtimeStatus, serveRuntime, startRuntime, stopRuntime } from '../cognition/runtime.js';
+import { migrationReadiness } from '../cognition/readiness.js';
 import { runClaudeCodeHook } from '../hooks/claude-code.js';
 import { inspectClaudeIntegration, installClaudeIntegration } from '../integrations/claude-code.js';
 import { doctor, status } from '../runtime/diagnostics.js';
@@ -235,9 +238,51 @@ Options:
   --open                 Only open notes
   --limit <number>       Maximum items (default: 50)
   --max-chars <number>   Maximum message characters`,
+    migrate: `usage: ctx migrate v1 --dry-run|--apply [--path <path>]
+       ctx migrate verify [--path <path>]
+
+Inspect, explicitly import, or verify v1 Context data for the event-journal runtime.`,
+    'migrate v1': `usage: ctx migrate v1 --dry-run|--apply [--path <path>]
+
+Validate v1 Context, Snapshot, Note, Knowledge, and Deadend data for v2 migration.
+
+Options:
+  --dry-run              Inspect only; no v2 data is created
+  --apply                Explicitly append immutable v1 provenance events
+  --path <path>          Project path`,
+    'migrate verify': `usage: ctx migrate verify [--path <path>]
+
+Rebuild v2 projections and verify imported v1 parity.
+
+Options:
+  --path <path>          Project path`,
+    runtime: `usage: ctx runtime enable|disable|start|stop|status [--path <path>]
+
+Control the local event-driven Knowledge Runtime after v1 migration verification.`,
+    'runtime status': `usage: ctx runtime status [--path <path>]
+
+Show the read-only runtime policy, migration and authenticated lease status.
+
+Options:
+  --path <path>          Project path`,
+    'runtime enable': `usage: ctx runtime enable [--path <path>]
+
+Explicitly enable the migrated local Knowledge Runtime.`,
+    'runtime disable': `usage: ctx runtime disable [--path <path>]
+
+Stop the local runtime and disable future startup without deleting v2 history.`,
+    'runtime start': `usage: ctx runtime start [--path <path>]
+
+Start the enabled runtime as a loopback-only background process.`,
+    'runtime stop': `usage: ctx runtime stop [--path <path>]
+
+Stop the local runtime through authenticated loopback IPC.`,
+    'runtime serve': `usage: ctx runtime serve [--path <path>]
+
+Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity [options]
+    return `usage: ctx init|checkpoint|resume|orient|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -256,7 +301,15 @@ function printHelp(args) {
         process.stdout.write(`${usage()}\n`);
         return true;
     }
-    const key = args[1] === 'verify' || args[1] === 'add' || args[1] === 'list' || args[1] === 'discover' || args[1] === 'serve' || args[1] === 'claude' ? `${command} ${args[1]}` : command;
+    const nested = (command === 'agent' && args[1] === 'serve')
+        || (command === 'hook' && args[1] === 'claude-code')
+        || (command === 'integrate' && args[1] === 'claude')
+        || (command === 'knowledge' && ['verify', 'discover'].includes(args[1]))
+        || (command === 'deadend' && args[1] === 'verify')
+        || (command === 'note' && ['add', 'list'].includes(args[1]))
+        || (command === 'migrate' && ['v1', 'verify'].includes(args[1]))
+        || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]));
+    const key = nested ? `${command} ${args[1]}` : command;
     const nestedKey = key === 'integrate claude' && (args[2] === 'inspect' || args[2] === 'install') ? `${key} ${args[2]}` : key;
     const help = HELP[nestedKey];
     if (!help)
@@ -413,6 +466,47 @@ async function run(args) {
             }
             return;
         }
+        case 'migrate': {
+            if (args[1] === 'v1') {
+                validateOptions(args.slice(2), ['--dry-run', '--apply', '--path'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['migrate v1']);
+                if (args.includes('--dry-run') === args.includes('--apply'))
+                    throw new Error(HELP['migrate v1']);
+                print(args.includes('--apply') ? await importV1(target) : await migrationReadiness(target));
+            }
+            else if (args[1] === 'verify') {
+                validateOptions(args.slice(2), ['--path'], ['--path']);
+                validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['migrate verify']);
+                print(await verifyV1Import(target));
+            }
+            else {
+                throw new Error(HELP.migrate);
+            }
+            return;
+        }
+        case 'runtime': {
+            if (!['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
+                throw new Error(HELP.runtime);
+            validateOptions(args.slice(2), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP[`runtime ${args[1]}`]);
+            if (args[1] === 'enable')
+                print(await enableRuntime(target));
+            else if (args[1] === 'disable')
+                print(await disableRuntime(target));
+            else if (args[1] === 'start')
+                print(await startRuntime(target));
+            else if (args[1] === 'stop')
+                print(await stopRuntime(target));
+            else if (args[1] === 'status')
+                print(await runtimeStatus(target));
+            else {
+                const runtime = await serveRuntime(target);
+                process.once('SIGINT', () => { void runtime.close('signal'); });
+                process.once('SIGTERM', () => { void runtime.close('signal'); });
+                await new Promise(() => undefined);
+            }
+            return;
+        }
         case 'activity': {
             const valueOptions = ['--path', '--context', '--since', '--limit', '--max-chars'];
             validateOptions(args.slice(1), [...valueOptions, '--open'], valueOptions);

package/dist/src/cognition/git-observer.d.ts

@@ -0,0 +1,13 @@
+import { type GitWorktreeState } from '../git/git-adapter.js';
+export declare class GitObserver {
+    private readonly projectRoot;
+    private previous;
+    private pending;
+    constructor(projectRoot: string);
+    observeNow(): Promise<{
+        state: GitWorktreeState;
+        changed: boolean;
+    }>;
+    drain(): Promise<void>;
+    private observe;
+}

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[];
+}>;