fluffy-context 0.6.0 → 0.7.6

package/dist/src/agent/api.d.ts

@@ -1,8 +1,10 @@
 import type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, CheckpointInput, ContextSearchOptions, ContextSearchResult } from '../runtime/types.js';
 import type { ContextOrientOptions, ContextOrientResult, ContextUseInput } from './types.js';
+import type { ContextExpandInput, ContextExpandResult } from '../compiler/types.js';
 export declare function saveContext(startPath: string | undefined, input: CheckpointInput, options?: {
     minSaveIntervalMs?: number;
 }): Promise<AgentSaveResult>;
+export declare function contextExpand(startPath: string | undefined, input: ContextExpandInput): Promise<ContextExpandResult>;
 export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions): Promise<AgentLoadResult>;
 export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions): Promise<ContextOrientResult>;
 export declare function recordContextUse(startPath: string | undefined, input: ContextUseInput): Promise<{

package/dist/src/agent/api.js

@@ -8,6 +8,7 @@ import { selectV2Orientation } from '../cognition/orient.js';
 import { discoverV2Deadends, discoverV2Knowledge } from '../cognition/retrieval.js';
 import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
+import { expandContext } from '../compiler/expand.js';
 function normalized(value) {
     return value.trim().toLocaleLowerCase();
 }
@@ -138,6 +139,10 @@ export async function saveContext(startPath, input, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     return { projectRoot, result: await checkpoint(projectRoot, input, options) };
 }
+export async function contextExpand(startPath, input) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return expandContext(projectRoot, input);
+}
 export async function loadContext(startPath, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);

package/dist/src/agent/index.d.ts

@@ -1,3 +1,6 @@
 export * from './api.js';
 export type { ContextOrientContext, ContextUseInput, ContextOrientExplanation, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
 export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';
+export { compileContext } from '../compiler/compile.js';
+export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';
+export type { ContextActivityRecord, ContextAnchor, ContextBudget, ContextBudgetReport, ContextCandidate, ContextCandidateSection, ContextCompileOptions, ContextExpandInput, ContextExpandLevel, ContextExpandResult, ContextExclusion, ContextExclusionReason, ContextIntent, ContextIntentSignal, ContextLevel, ContextManifest, ContextProvenance, ContextScenario, ContextSourceDescriptor, ContextTruncation, } from '../compiler/types.js';

package/dist/src/agent/index.js

@@ -1 +1,3 @@
 export * from './api.js';
+export { compileContext } from '../compiler/compile.js';
+export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';

package/dist/src/cli/main.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { checkpoint, resume } from '../runtime/runtime.js';
 import { contextOrient } from '../agent/api.js';
+import { compileContext } from '../compiler/compile.js';
+import { contextExpand } from '../agent/api.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
-import { readJournal } from '../cognition/journal.js';
+import { verifyJournal } from '../cognition/journal.js';
 import { projectEvents } from '../cognition/projections.js';
-import { disableRuntime, enableRuntime, runtimeStatus, serveRuntime, startRuntime, stopRuntime } from '../cognition/runtime.js';
+import { disableRuntime, enableRuntime, ensureRuntimeForSession, runtimeStatus, serveRuntime, setFilesystemEvents, startRuntime, stopRuntime } from '../cognition/runtime.js';
+import { loadRuntimePolicy } from '../cognition/policy.js';
 import { migrationReadiness } from '../cognition/readiness.js';
 import { runClaudeCodeHook } from '../hooks/claude-code.js';
 import { readGitWorktreeState } from '../git/git-adapter.js';
@@ -115,6 +118,42 @@ Options:
   --knowledge-limit <number> Maximum knowledge matches (default: 10)
   --deadend-limit <number>   Maximum deadend matches (default: 10)
   --note-limit <number>      Maximum open notes (default: 20)`,
+    compile: `usage: ctx compile [query] [options]
+
+Compile bounded, provider-neutral context with source provenance and selection explanations.
+
+Options:
+  --path <path>              Project path
+  --context <id>             Context ID
+  --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
+  --scope <scope>            Exact consensus scope
+  --paths <paths>            Comma-separated project-relative paths
+  --max-chars <number>       Maximum compiled characters
+  --knowledge-limit <number> Maximum knowledge matches (default: 10)
+  --deadend-limit <number>   Maximum deadend matches (default: 10)
+  --note-limit <number>      Maximum open notes (default: 20)
+  --activity-limit <number>  Maximum recent activity groups (default: 20)`,
+    expand: `usage: ctx expand [options]
+
+Expand one selected compiler candidate without writing project state.
+
+Options:
+  --path <path>              Project path
+  --manifest-hash <hash>     Manifest identity hash from ctx compile
+  --candidate-id <id>        Selected candidate ID
+  --item-hash <hash>         Selected item hash
+  --level <level>            structured|evidence
+  --max-chars <number>       Maximum expanded characters
+  --compile-max-chars <number> Original compile budget (default: 4000)
+  --context <id>             Context ID
+  --query <text>             Original compile query
+  --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
+  --scope <scope>            Exact consensus scope
+  --paths <paths>            Comma-separated project-relative paths
+  --knowledge-limit <number> Maximum knowledge matches (default: 10)
+  --deadend-limit <number>   Maximum deadend matches (default: 10)
+  --note-limit <number>      Maximum open notes (default: 20)
+  --activity-limit <number>  Maximum recent activity groups (default: 20)`,
     agent: `usage: ctx agent serve
 
 Start an MCP stdio server for Agent integrations.
@@ -122,7 +161,7 @@ Start an MCP stdio server for Agent integrations.
 Run "ctx agent serve --help" for details.`,
     'agent serve': `usage: ctx agent serve
 
-Start an MCP stdio server exposing the context_orient tool.
+Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, and context_checkpoint tools.
 
 The server owns standard input/output; do not use it interactively.`,
     hook: `usage: ctx hook claude-code session-start|user-prompt
@@ -289,6 +328,18 @@ Options:
     runtime: `usage: ctx runtime enable|disable|start|stop|status [--path <path>]
 
 Control the local event-driven Knowledge Runtime after v1 migration verification.`,
+    filesystem: `usage: ctx filesystem enable|disable|status [--path <path>]
+
+Control whether the Runtime records filtered file metadata changes.`,
+    'filesystem enable': `usage: ctx filesystem enable [--path <path>]
+
+Enable filtered filesystem change observation and restart a running Runtime.`,
+    'filesystem disable': `usage: ctx filesystem disable [--path <path>]
+
+Disable filesystem change observation and restart a running Runtime.`,
+    'filesystem status': `usage: ctx filesystem status [--path <path>]
+
+Show the filesystem observation policy and Runtime status.`,
     'runtime status': `usage: ctx runtime status [--path <path>]
 
 Show the read-only runtime policy, migration and authenticated lease status.
@@ -312,7 +363,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 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|migrate|runtime|feedback|journal [options]
+    return `usage: ctx init|checkpoint|resume|orient|compile|expand|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -340,7 +391,8 @@ function printHelp(args) {
         || (command === 'journal' && 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]));
+        || (command === 'runtime' && ['enable', 'disable', 'start', 'stop', 'status', 'serve'].includes(args[1]))
+        || (command === 'filesystem' && ['enable', 'disable', 'status'].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];
@@ -405,6 +457,7 @@ async function run(args) {
             validateOptions(args.slice(1), valueOptions, valueOptions);
             const query = positionals(args.slice(1), valueOptions);
             validatePositionals(query, 1, HELP.orient);
+            await ensureRuntimeForSession(target, { source: 'cli', timeoutMs: 1_000 }).catch(() => undefined);
             print(await contextOrient(target, {
                 contextId: option(args, '--context'),
                 query: query[0],
@@ -416,6 +469,58 @@ async function run(args) {
             }));
             return;
         }
+        case 'compile': {
+            const valueOptions = ['--path', '--context', '--scenario', '--scope', '--paths', '--max-chars', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            const query = positionals(args.slice(1), valueOptions);
+            validatePositionals(query, 1, HELP.compile);
+            print(await compileContext(target, {
+                contextId: option(args, '--context'),
+                query: query[0],
+                scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
+                scope: option(args, '--scope'),
+                paths: listOption(args, '--paths'),
+                maxChars: numericOption(args, '--max-chars', 4000),
+                knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
+                deadendLimit: numericOption(args, '--deadend-limit', 10),
+                noteLimit: numericOption(args, '--note-limit', 20),
+                activityLimit: numericOption(args, '--activity-limit', 20),
+            }));
+            return;
+        }
+        case 'expand': {
+            const valueOptions = ['--path', '--manifest-hash', '--candidate-id', '--item-hash', '--level', '--max-chars', '--compile-max-chars', '--context', '--query', '--scenario', '--scope', '--paths', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            validatePositionals(positionals(args.slice(1), valueOptions), 0, HELP.expand);
+            const level = enumOption(args, '--level', ['structured', 'evidence']);
+            if (!level)
+                throw new Error('--level is required');
+            const manifestHash = option(args, '--manifest-hash');
+            if (!manifestHash)
+                throw new Error('--manifest-hash is required');
+            const compileMaxChars = numericOption(args, '--compile-max-chars', 4000);
+            await ensureRuntimeForSession(target, { source: 'cli', timeoutMs: 1_000 }).catch(() => undefined);
+            print(await contextExpand(target, {
+                manifestHash,
+                candidateId: option(args, '--candidate-id'),
+                itemHash: option(args, '--item-hash'),
+                level: level,
+                maxChars: option(args, '--max-chars') === undefined ? undefined : numericOption(args, '--max-chars', 0),
+                compile: {
+                    contextId: option(args, '--context'),
+                    query: option(args, '--query'),
+                    scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
+                    scope: option(args, '--scope'),
+                    paths: listOption(args, '--paths'),
+                    maxChars: compileMaxChars,
+                    knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
+                    deadendLimit: numericOption(args, '--deadend-limit', 10),
+                    noteLimit: numericOption(args, '--note-limit', 20),
+                    activityLimit: numericOption(args, '--activity-limit', 20),
+                },
+            }));
+            return;
+        }
         case 'agent':
             if (args[1] !== 'serve')
                 throw new Error(HELP.agent);
@@ -511,13 +616,27 @@ async function run(args) {
             print(await recordUse(target, { entity: args[2], entityId: values[0], eventId: option(args, '--event-id') ?? '' }));
             return;
         }
+        case 'filesystem': {
+            if (!['enable', 'disable', 'status'].includes(args[1]))
+                throw new Error(HELP.filesystem);
+            validateOptions(args.slice(2), ['--path'], ['--path']);
+            validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP[`filesystem ${args[1]}`]);
+            if (args[1] === 'status') {
+                const status = await runtimeStatus(target);
+                print({ projectRoot: status.projectRoot, migrated: status.migrated, enabled: status.enabled, running: status.running, filesystemEventsEnabled: status.migrated ? (await loadRuntimePolicy(status.projectRoot)).filesystemEventsEnabled : false });
+            }
+            else {
+                print(await setFilesystemEvents(target, args[1] === 'enable'));
+            }
+            return;
+        }
         case 'journal': {
             if (args[1] !== 'verify')
                 throw new Error(HELP.journal);
             validateOptions(args.slice(2), ['--path'], ['--path']);
             validatePositionals(positionals(args.slice(2), ['--path']), 0, HELP['journal verify']);
             const root = target ?? process.cwd();
-            const events = await readJournal(root);
+            const events = await verifyJournal(root);
             const projection = projectEvents(events);
             const last = events.at(-1);
             print({ verified: true, eventCount: events.length, cursor: { eventId: last?.eventId ?? null, hash: last?.hash ?? null }, counts: { contexts: Object.keys(projection.contexts).length, notes: Object.keys(projection.notes).length, knowledge: Object.keys(projection.knowledge).length, deadends: Object.keys(projection.deadends).length } });

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

@@ -0,0 +1,41 @@
+import type { CognitionGitAnchor } from './types.js';
+export type WatchCallback = (eventType: string, filename: string | Buffer | null) => void;
+export type WatchFactory = (projectRoot: string, callback: WatchCallback) => {
+    close(): void;
+};
+export interface FilesystemObserverOptions {
+    anchor?: () => CognitionGitAnchor;
+    debounceMs?: number;
+    maxPaths?: number;
+    maxPayloadBytes?: number;
+    watchFactory?: WatchFactory;
+    onChanged?: (result: FilesystemObservationResult) => void;
+}
+export interface FilesystemObservationResult {
+    changed: boolean;
+    paths: string[];
+}
+export declare class FilesystemObserver {
+    private readonly projectRoot;
+    private readonly debounceMs;
+    private readonly maxPaths;
+    private readonly maxPayloadBytes;
+    private readonly anchor;
+    private readonly watchFactory;
+    private readonly onChanged;
+    private readonly pendingPaths;
+    private readonly known;
+    private watcher;
+    private timer;
+    private pending;
+    private closed;
+    constructor(projectRoot: string, options?: FilesystemObserverOptions);
+    start(): void;
+    stop(): void;
+    observeNow(): Promise<FilesystemObservationResult>;
+    flush(): Promise<FilesystemObservationResult>;
+    drain(): Promise<void>;
+    close(): void;
+    private scheduleFlush;
+    private process;
+}

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

@@ -0,0 +1,164 @@
+import { watch } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { filterPaths } from '../capture/context-filter.js';
+import { appendEvent } from './journal.js';
+const defaultDebounceMs = 250;
+const defaultMaxPaths = 100;
+const defaultMaxPayloadBytes = 16 * 1024;
+function defaultWatchFactory(projectRoot, callback) {
+    return watch(projectRoot, { recursive: true }, callback);
+}
+function normalizeCandidate(projectRoot, filename) {
+    if (filename === null)
+        return null;
+    const value = filename.toString().replaceAll('\\', '/').replace(/^\.\//, '');
+    if (!value || value.startsWith('/') || /^[A-Za-z]:\//.test(value))
+        return null;
+    const absolute = resolve(projectRoot, value);
+    const relative = absolute.slice(resolve(projectRoot).length).replaceAll('\\', '/').replace(/^\/+/, '');
+    return relative || null;
+}
+function metadataEqual(left, right) {
+    return left?.sizeBytes === right.sizeBytes && left.mtimeMs === right.mtimeMs;
+}
+function payloadSize(payload) {
+    return Buffer.byteLength(JSON.stringify(payload), 'utf8');
+}
+export class FilesystemObserver {
+    projectRoot;
+    debounceMs;
+    maxPaths;
+    maxPayloadBytes;
+    anchor;
+    watchFactory;
+    onChanged;
+    pendingPaths = new Map();
+    known = new Map();
+    watcher = null;
+    timer = null;
+    pending = Promise.resolve({ changed: false, paths: [] });
+    closed = false;
+    constructor(projectRoot, options = {}) {
+        this.projectRoot = projectRoot;
+        this.debounceMs = options.debounceMs ?? defaultDebounceMs;
+        this.maxPaths = options.maxPaths ?? defaultMaxPaths;
+        this.maxPayloadBytes = options.maxPayloadBytes ?? defaultMaxPayloadBytes;
+        this.anchor = options.anchor ?? (() => ({ worktreeId: null, branch: null, ref: null, head: null }));
+        this.watchFactory = options.watchFactory ?? defaultWatchFactory;
+        this.onChanged = options.onChanged;
+    }
+    start() {
+        if (this.closed || this.watcher)
+            return;
+        this.watcher = this.watchFactory(this.projectRoot, (eventType, filename) => {
+            const relative = normalizeCandidate(this.projectRoot, filename);
+            if (relative)
+                this.pendingPaths.set(relative, eventType);
+            this.scheduleFlush();
+        });
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.watcher?.close();
+        this.watcher = null;
+        this.closed = true;
+    }
+    observeNow() {
+        return this.flush();
+    }
+    async flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        const paths = [...this.pendingPaths.entries()];
+        this.pendingPaths.clear();
+        if (paths.length === 0)
+            return { changed: false, paths: [] };
+        const operation = this.pending.then(() => this.process(paths), () => this.process(paths));
+        this.pending = operation;
+        return operation;
+    }
+    async drain() {
+        await this.pending;
+        if (this.pendingPaths.size > 0)
+            await this.flush();
+        await this.pending;
+    }
+    close() {
+        this.stop();
+    }
+    scheduleFlush(delay = this.debounceMs) {
+        if (this.timer || this.closed)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush().catch(() => undefined);
+        }, delay);
+    }
+    async process(paths) {
+        const filtered = await filterPaths(this.projectRoot, paths.map(([relative]) => relative));
+        const eventTypes = new Map(paths);
+        const changes = [];
+        for (const relative of filtered.slice(0, this.maxPaths)) {
+            const absolute = resolve(this.projectRoot, relative);
+            let current = null;
+            try {
+                const value = await stat(absolute);
+                if (!value.isFile())
+                    continue;
+                current = { sizeBytes: value.size, mtimeMs: value.mtimeMs };
+            }
+            catch {
+                current = null;
+            }
+            const previous = this.known.get(relative);
+            if (current && metadataEqual(previous, current))
+                continue;
+            if (!current && !previous)
+                continue;
+            if (current)
+                this.known.set(relative, current);
+            else
+                this.known.delete(relative);
+            changes.push({
+                path: relative,
+                kind: current ? (previous ? 'modified' : eventTypes.get(relative) === 'rename' ? 'created' : 'modified') : 'deleted',
+                fileType: 'file',
+                ...(current ? { sizeBytes: current.sizeBytes, mtimeMs: current.mtimeMs } : {}),
+            });
+        }
+        if (changes.length === 0)
+            return { changed: false, paths: [] };
+        const limitedChanges = changes.slice(0, this.maxPaths);
+        const basePayload = {
+            schemaVersion: 1,
+            paths: limitedChanges.map((change) => change.path),
+            changes: limitedChanges,
+            pathCount: limitedChanges.length,
+            coalesced: paths.length > 1,
+            truncated: filtered.length > limitedChanges.length || payloadSize({ changes: limitedChanges }) > this.maxPayloadBytes,
+        };
+        while (basePayload.changes.length > 1 && payloadSize(basePayload) > this.maxPayloadBytes) {
+            basePayload.changes.pop();
+            basePayload.paths.pop();
+            basePayload.pathCount = basePayload.changes.length;
+            basePayload.truncated = true;
+        }
+        if (basePayload.changes.length === 0 || payloadSize(basePayload) > this.maxPayloadBytes)
+            return { changed: false, paths: [] };
+        const result = await appendEvent(this.projectRoot, {
+            type: 'workspace.paths.changed',
+            source: { kind: 'fs-observer' },
+            idempotencyKey: `fs:paths:${basePayload.paths.join(',')}:${basePayload.changes.map((change) => `${change.kind}:${change.sizeBytes ?? ''}:${change.mtimeMs ?? ''}`).join(',')}`,
+            git: this.anchor(),
+            payload: basePayload,
+        });
+        const observation = { changed: result.appended, paths: basePayload.paths };
+        if (observation.changed)
+            this.onChanged?.(observation);
+        return observation;
+    }
+}

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

@@ -4,6 +4,7 @@ export declare class GitObserver {
     private previous;
     private pending;
     constructor(projectRoot: string);
+    get current(): GitWorktreeState | null;
     observeNow(): Promise<{
         state: GitWorktreeState;
         changed: boolean;

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

@@ -1,6 +1,5 @@
 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 };
 }
@@ -14,6 +13,9 @@ export class GitObserver {
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
+    get current() {
+        return this.previous;
+    }
     observeNow() {
         const observation = this.pending.then(() => this.observe());
         this.pending = observation.then(() => undefined, () => undefined);
@@ -55,7 +57,6 @@ export class GitObserver {
             });
         }
         this.previous = state;
-        await rebuildProjections(this.projectRoot);
         return { state, changed: true };
     }
 }

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

@@ -17,7 +17,10 @@ export interface AppendEventInput<T = Record<string, unknown>> {
     payload: T;
 }
 export declare function eventHash<T>(event: Omit<CognitionEvent<T>, 'hash'>): string;
-export declare function readJournal(startPath?: string): Promise<CognitionEvent[]>;
+export declare function readJournal(startPath?: string, options?: {
+    allowPartialTail?: boolean;
+}): Promise<CognitionEvent[]>;
+export declare function verifyJournal(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

@@ -5,6 +5,15 @@ 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 eventTypes = new Set([
+    'runtime.enabled', 'runtime.started', 'runtime.stopped', 'host.session.started', 'host.prompt.submitted',
+    'git.state.observed', 'git.branch.changed', 'git.head.changed', 'workspace.paths.changed',
+    'context.checkpoint.imported', 'context.state.recorded', 'note.recorded', 'note.resolved', 'note.absorbed',
+    'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
+    'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected', 'record.used',
+    'projection.advanced', 'projection.failed',
+]);
+const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'git-observer', 'fs-observer', 'migration']);
 const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
@@ -33,6 +42,65 @@ async function journalFiles(projectRoot) {
         throw error;
     }
 }
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function validGitAnchor(value) {
+    return isRecord(value)
+        && (typeof value.worktreeId === 'string' || value.worktreeId === null)
+        && (typeof value.branch === 'string' || value.branch === null)
+        && (typeof value.ref === 'string' || value.ref === null)
+        && (typeof value.head === 'string' || value.head === null);
+}
+function validIsoDate(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function validatePayloadBoundary(input) {
+    const payload = input.payload;
+    if (input.type === 'host.prompt.submitted' && (typeof payload.intent !== 'string' || payload.intent.trim().length === 0)) {
+        throw new Error('host prompt intent must not be empty');
+    }
+    if (['note.recorded', 'note.resolved', 'note.absorbed'].includes(input.type)) {
+        const record = payload.record;
+        if (!isRecord(record) || typeof record.message !== 'string' || record.message.trim().length === 0)
+            throw new Error('note message must not be empty');
+    }
+    if (input.type === 'workspace.paths.changed') {
+        const changes = payload.changes;
+        if (!Array.isArray(changes) || changes.length === 0)
+            throw new Error('workspace activity must contain changes');
+    }
+}
+function validateEventShape(event, projectId, file, line) {
+    if (!isRecord(event)
+        || event.schemaVersion !== 2
+        || typeof event.eventId !== 'string'
+        || event.eventId.length === 0
+        || typeof event.type !== 'string'
+        || !eventTypes.has(event.type)
+        || !validIsoDate(event.occurredAt)
+        || !validIsoDate(event.observedAt)
+        || event.projectId !== projectId
+        || !isRecord(event.source)
+        || typeof event.source.kind !== 'string'
+        || !sourceKinds.has(event.source.kind)
+        || (event.source.instanceId !== undefined && typeof event.source.instanceId !== 'string')
+        || (event.correlationId !== undefined && typeof event.correlationId !== 'string')
+        || typeof event.idempotencyKey !== 'string'
+        || event.idempotencyKey.length === 0
+        || !validGitAnchor(event.git)
+        || !isRecord(event.privacy)
+        || (event.privacy.classification !== 'metadata' && event.privacy.classification !== 'redacted-text')
+        || typeof event.privacy.redactionCount !== 'number'
+        || !Number.isSafeInteger(event.privacy.redactionCount)
+        || event.privacy.redactionCount < 0
+        || !isRecord(event.payload)
+        || (event.previousHash !== null && typeof event.previousHash !== 'string')
+        || typeof event.hash !== 'string'
+        || event.hash.length === 0) {
+        throw new Error(`invalid journal record schema at ${file}:${line}`);
+    }
+}
 async function recoverPartialTail(projectRoot) {
     const files = await journalFiles(projectRoot);
     const file = files.at(-1);
@@ -46,13 +114,15 @@ async function recoverPartialTail(projectRoot) {
     const tail = content.slice(boundary + 1);
     try {
         JSON.parse(tail);
+        await appendFile(filePath, '\n', 'utf8');
     }
     catch {
         await truncate(filePath, boundary < 0 ? 0 : boundary + 1);
     }
 }
-export async function readJournal(startPath) {
+export async function readJournal(startPath, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
+    const projectId = (await loadManifest(projectRoot)).projectId;
     const events = [];
     let previousHash = null;
     for (const file of await journalFiles(projectRoot)) {
@@ -67,12 +137,13 @@ export async function readJournal(startPath) {
                 event = JSON.parse(line);
             }
             catch (error) {
-                if (index === lines.length - 1 && !content.endsWith('\n'))
+                if (options.allowPartialTail !== false && index === lines.length - 1 && !content.endsWith('\n'))
                     break;
                 throw new Error(`invalid journal record ${file}:${index + 1}: ${error instanceof Error ? error.message : 'invalid JSON'}`);
             }
+            validateEventShape(event, projectId, file, index + 1);
             const { hash, ...withoutHash } = event;
-            if (event.schemaVersion !== 2 || !event.eventId || event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
+            if (event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
                 throw new Error(`invalid journal hash chain at ${file}:${index + 1}`);
             }
             previousHash = event.hash;
@@ -81,14 +152,39 @@ export async function readJournal(startPath) {
     }
     return events;
 }
+export async function verifyJournal(startPath) {
+    return readJournal(startPath, { allowPartialTail: false });
+}
 export async function appendEvent(startPath, input) {
+    validatePayloadBoundary(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)
+        if (duplicate) {
+            const candidate = {
+                type: input.type,
+                source: input.source ?? { kind: 'cli' },
+                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,
+            };
+            const existingSemantic = {
+                type: duplicate.type,
+                source: duplicate.source,
+                correlationId: duplicate.correlationId,
+                idempotencyKey: duplicate.idempotencyKey,
+                git: duplicate.git,
+                privacy: duplicate.privacy,
+                payload: duplicate.payload,
+            };
+            if (canonical(candidate) !== canonical(existingSemantic))
+                throw new Error(`idempotency key conflict: ${input.idempotencyKey}`);
             return { event: duplicate, appended: false };
+        }
         const now = new Date().toISOString();
         const eventWithoutHash = {
             eventId: input.eventId ?? eventId(),