fluffy-context 0.7.7 → 1.0.0-beta.1

package/dist/src/cognition/journal-segments.js

@@ -0,0 +1,129 @@
+import { appendFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gzip, gunzip } from 'node:zlib';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { cognitionJournalDirectory } from '../storage/layout.js';
+const compress = promisify(gzip);
+const decompress = promisify(gunzip);
+export const JOURNAL_SEGMENT_BYTES = 1024 * 1024;
+export async function journalFiles(root) {
+    let files;
+    try {
+        files = await readdir(cognitionJournalDirectory(root));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const segments = new Map();
+    for (const file of files) {
+        if (!file.endsWith('.ndjson') && !file.endsWith('.ndjson.gz'))
+            continue;
+        if (!/^\d{8}\.ndjson(?:\.gz)?$/.test(file))
+            throw new Error(`unrecognized journal segment: ${file}`);
+        const base = file.replace(/\.gz$/, '');
+        if (!segments.has(base) || file.endsWith('.gz'))
+            segments.set(base, file);
+    }
+    return [...segments.values()].sort();
+}
+async function optional(file) {
+    try {
+        return await readFile(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function readSegment(root, name) {
+    const file = path.join(cognitionJournalDirectory(root), name);
+    if (!name.endsWith('.gz')) {
+        const raw = await optional(file);
+        // An unlocked reader may race a successful archive publication.
+        return raw ?? readSegment(root, `${name}.gz`);
+    }
+    let decoded;
+    try {
+        decoded = await decompress(await readFile(file));
+    }
+    catch (error) {
+        throw new Error(`invalid journal archive ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const raw = await optional(file.slice(0, -3));
+    if (raw && !raw.equals(decoded))
+        throw new Error(`journal archive/raw mismatch: ${name}`);
+    return decoded;
+}
+// Caller holds cognition-journal.lock. Publish and validate before removing raw
+// bytes; a crash with both representations is safe and validated on every read.
+export async function archiveSegment(root, name) {
+    if (name.endsWith('.gz')) {
+        await readSegment(root, name);
+        await rm(path.join(cognitionJournalDirectory(root), name.slice(0, -3)), { force: true });
+        return;
+    }
+    const source = path.join(cognitionJournalDirectory(root), name);
+    const raw = await readFile(source);
+    if (!raw.length)
+        return;
+    if (raw.at(-1) !== 10)
+        throw new Error(`cannot archive incomplete journal segment: ${name}`);
+    const target = `${source}.gz`;
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, await compress(raw, { level: 9 }), { flag: 'wx' });
+        await rename(temporary, target);
+        if (!(await readSegment(root, `${name}.gz`)).equals(raw))
+            throw new Error(`archive verification failed: ${name}`);
+        await rm(source);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function appendJournalLine(root, line) {
+    const directory = cognitionJournalDirectory(root);
+    await mkdir(directory, { recursive: true });
+    const latest = (await journalFiles(root)).at(-1);
+    let number = latest ? Number(latest.slice(0, 8)) : 1;
+    if (latest?.endsWith('.gz'))
+        number += 1;
+    else if (latest && (await stat(path.join(directory, latest))).size >= JOURNAL_SEGMENT_BYTES) {
+        await archiveSegment(root, latest);
+        number += 1;
+    }
+    if (number > 99_999_999)
+        throw new Error('journal segment limit exceeded');
+    await appendFile(path.join(directory, `${String(number).padStart(8, '0')}.ndjson`), line, 'utf8');
+}
+export async function journalStorage(root, expand = false) {
+    const files = await journalFiles(root);
+    let bytes = 0;
+    let expandedBytes = expand ? 0 : null;
+    let archives = 0;
+    for (const file of files) {
+        let metadata;
+        try {
+            metadata = await stat(path.join(cognitionJournalDirectory(root), file));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && !file.endsWith('.gz')) {
+                metadata = await stat(path.join(cognitionJournalDirectory(root), `${file}.gz`));
+            }
+            else
+                throw error;
+        }
+        bytes += metadata.size;
+        if (file.endsWith('.gz')) {
+            archives += 1;
+            bytes += (await optional(path.join(cognitionJournalDirectory(root), file.slice(0, -3))))?.length ?? 0;
+        }
+        if (expandedBytes !== null)
+            expandedBytes += (await readSegment(root, file)).length;
+    }
+    return { bytes, expandedBytes, archives, segments: files.length };
+}

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

@@ -21,6 +21,19 @@ export declare function readJournal(startPath?: string, options?: {
     allowPartialTail?: boolean;
 }): Promise<CognitionEvent[]>;
 export declare function verifyJournal(startPath?: string): Promise<CognitionEvent[]>;
+export declare function compactJournal(startPath?: string, options?: {
+    apply?: boolean;
+    minBytes?: number;
+}): Promise<{
+    applied: boolean;
+    eligible: string[];
+    events: number;
+    headHash: string | null;
+    bytesBefore: number;
+    bytesAfter: number;
+    savedBytes: number;
+    archives: number;
+}>;
 export declare function appendEvent<T>(startPath: string | undefined, input: AppendEventInput<T>): Promise<{
     event: CognitionEvent<T>;
     appended: boolean;

package/dist/src/cognition/journal.js

@@ -1,21 +1,26 @@
 import crypto from 'node:crypto';
-import { appendFile, mkdir, readFile, readdir, truncate } from 'node:fs/promises';
+import { appendFile, readFile, 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';
+import { appendJournalLine, archiveSegment, journalFiles, journalStorage, readSegment } from './journal-segments.js';
+import { loadRuntimePolicy } from './policy.js';
+import { recordAdmissionDrop } from './admission.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',
+    'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected',
+    'experience.recorded',
+    'evolution.proposed', 'evolution.candidate.accepted', 'evolution.verified', 'evolution.published', 'evolution.rejected', 'evolution.deprecated', 'evolution.superseded',
+    'skill.materialized', 'recipe.materialized', 'skill.invoked', 'skill.outcome.recorded', 'record.used',
     'usage.operation.completed',
     'projection.advanced', 'projection.failed',
 ]);
 const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'agent', 'git-observer', 'fs-observer', 'migration']);
-const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
         return JSON.stringify(value);
@@ -33,16 +38,6 @@ function eventId() {
 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;
-    }
-}
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -56,6 +51,79 @@ function validGitAnchor(value) {
 function validIsoDate(value) {
     return typeof value === 'string' && Number.isFinite(Date.parse(value));
 }
+function validEvolutionId(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error(`${label} must not be empty`);
+}
+function validNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function validLineage(value) {
+    return isRecord(value)
+        && (value.entity === 'knowledge' || value.entity === 'deadend' || value.entity === 'skill' || value.entity === 'compiler-recipe' || value.entity === 'experience' || value.entity === 'proposal')
+        && typeof value.entityId === 'string' && value.entityId.trim().length > 0
+        && (value.relation === 'supports' || value.relation === 'contradicts' || value.relation === 'supersedes' || value.relation === 'used_for');
+}
+function validEvolutionEvidence(value) {
+    return isRecord(value)
+        && typeof value.eventId === 'string' && value.eventId.trim().length > 0
+        && (value.relation === 'derived_from' || value.relation === 'supports' || value.relation === 'contradicts' || value.relation === 'validated_by');
+}
+function validApplicability(value) {
+    return isRecord(value)
+        && value.project === true
+        && (value.branchMode === 'global' || value.branchMode === 'exact' || value.branchMode === 'ancestor-of-source' || value.branchMode === 'descendant-of-source')
+        && (value.branches === undefined || Array.isArray(value.branches) && value.branches.every((item) => typeof item === 'string' && item.trim().length > 0))
+        && (value.paths === undefined || Array.isArray(value.paths) && value.paths.every((item) => typeof item === 'string' && item.trim().length > 0))
+        && (value.sourceCommit === undefined || typeof value.sourceCommit === 'string' || value.sourceCommit === null)
+        && (value.dependencyConstraints === undefined || Array.isArray(value.dependencyConstraints) && value.dependencyConstraints.every((item) => typeof item === 'string' && item.trim().length > 0));
+}
+function validEvolutionTransition(from, to) {
+    if ((from !== 'candidate' && from !== 'verified' && from !== 'published' && from !== 'rejected' && from !== 'deprecated' && from !== 'superseded' && from !== 'obsolete') || (to !== 'verified' && to !== 'published' && to !== 'rejected' && to !== 'deprecated' && to !== 'superseded' && to !== 'obsolete'))
+        return false;
+    return (from === 'candidate' && (to === 'verified' || to === 'rejected' || to === 'deprecated'))
+        || (from === 'verified' && (to === 'published' || to === 'deprecated' || to === 'superseded' || to === 'obsolete'))
+        || (from === 'published' && (to === 'deprecated' || to === 'superseded' || to === 'obsolete'));
+}
+function validSkill(value) {
+    return isRecord(value)
+        && typeof value.skillId === 'string' && value.skillId.trim().length > 0
+        && value.schemaVersion === 1
+        && typeof value.proposalId === 'string' && value.proposalId.trim().length > 0
+        && typeof value.title === 'string' && value.title.trim().length > 0
+        && Array.isArray(value.procedure) && value.procedure.length > 0 && value.procedure.length <= 32 && value.procedure.every((step) => typeof step === 'string' && step.trim().length > 0)
+        && validApplicability(value.applicability)
+        && value.status === 'candidate'
+        && typeof value.contentHash === 'string' && value.contentHash.trim().length > 0
+        && Array.isArray(value.lineage) && value.lineage.every(validLineage)
+        && validIsoDate(value.createdAt);
+}
+const recipeSources = new Set(['context', 'knowledge', 'deadend', 'note']);
+const recipeSections = new Set(['summary', 'pending', 'decision', 'risk', 'note', 'knowledge', 'deadend', 'activity']);
+function validRecipe(value) {
+    if (!isRecord(value))
+        return false;
+    const allowed = new Set(['recipeId', 'schemaVersion', 'proposalId', 'title', 'applicability', 'preferredSources', 'preferredSections', 'sectionBudgets', 'status', 'contentHash', 'lineage', 'createdAt']);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return false;
+    const validPreferences = (items, allowedItems) => items === undefined
+        || (Array.isArray(items) && items.length <= allowedItems.size && items.every((item) => typeof item === 'string' && allowedItems.has(item)) && new Set(items).size === items.length);
+    const sectionBudgets = isRecord(value.sectionBudgets) ? value.sectionBudgets : null;
+    const validBudgets = value.sectionBudgets === undefined || (sectionBudgets !== null
+        && Object.keys(sectionBudgets).every((key) => recipeSections.has(key) && validNonNegativeInteger(sectionBudgets[key]) && sectionBudgets[key] <= 100_000));
+    return typeof value.recipeId === 'string' && value.recipeId.trim().length > 0
+        && value.schemaVersion === 1
+        && typeof value.proposalId === 'string' && value.proposalId.trim().length > 0
+        && typeof value.title === 'string' && value.title.trim().length > 0
+        && validApplicability(value.applicability)
+        && validPreferences(value.preferredSources, recipeSources)
+        && validPreferences(value.preferredSections, recipeSections)
+        && validBudgets
+        && value.status === 'candidate'
+        && typeof value.contentHash === 'string' && value.contentHash.trim().length > 0
+        && Array.isArray(value.lineage) && value.lineage.every(validLineage)
+        && validIsoDate(value.createdAt);
+}
 function validatePayloadBoundary(input) {
     const payload = input.payload;
     if (input.type === 'host.prompt.submitted' && (typeof payload.intent !== 'string' || payload.intent.trim().length === 0)) {
@@ -82,6 +150,58 @@ function validatePayloadBoundary(input) {
         if (!Array.isArray(changes) || changes.length === 0)
             throw new Error('workspace activity must contain changes');
     }
+    if (input.type === 'experience.recorded') {
+        const experience = payload.record;
+        if (!isRecord(experience))
+            throw new Error('experience record is required');
+        validEvolutionId(experience.experienceId, 'experience id');
+        if (experience.schemaVersion !== 1 || !Array.isArray(experience.sourceEventIds) || experience.sourceEventIds.length === 0 || !experience.sourceEventIds.every((value) => typeof value === 'string' && value.trim().length > 0) || !Array.isArray(experience.sourceContextIds) || !experience.sourceContextIds.every((value) => typeof value === 'string') || !Array.isArray(experience.sourceSnapshotIds) || !experience.sourceSnapshotIds.every((value) => typeof value === 'string') || !Array.isArray(experience.paths) || !experience.paths.every((value) => typeof value === 'string') || !validGitAnchor(experience.git) || !isRecord(experience.privacy) || (experience.privacy.classification !== 'metadata' && experience.privacy.classification !== 'redacted-text') || !validNonNegativeInteger(experience.privacy.redactionCount) || !isRecord(experience.extractor) || typeof experience.extractor.id !== 'string' || experience.extractor.id.trim().length === 0 || typeof experience.extractor.version !== 'string' || experience.extractor.version.trim().length === 0 || typeof experience.contentHash !== 'string' || experience.contentHash.trim().length === 0 || typeof experience.summary !== 'string' || experience.summary.trim().length === 0 || !validIsoDate(experience.createdAt))
+            throw new Error('invalid experience record');
+    }
+    if (input.type === 'evolution.proposed') {
+        const proposal = payload.record;
+        if (!isRecord(proposal))
+            throw new Error('evolution proposal record is required');
+        validEvolutionId(proposal.proposalId, 'proposal id');
+        if (proposal.schemaVersion !== 1 || (proposal.targetKind !== 'knowledge' && proposal.targetKind !== 'deadend' && proposal.targetKind !== 'skill' && proposal.targetKind !== 'compiler-recipe') || typeof proposal.targetId !== 'string' || proposal.targetId.trim().length === 0 || proposal.status !== 'candidate' || !Array.isArray(proposal.sourceExperienceIds) || proposal.sourceExperienceIds.length === 0 || !proposal.sourceExperienceIds.every((value) => typeof value === 'string' && value.trim().length > 0) || !Array.isArray(proposal.evidence) || proposal.evidence.length === 0 || !proposal.evidence.every(validEvolutionEvidence) || !Array.isArray(proposal.lineage) || !proposal.lineage.every(validLineage) || !validApplicability(proposal.applicability) || typeof proposal.contentHash !== 'string' || proposal.contentHash.trim().length === 0 || typeof proposal.summary !== 'string' || proposal.summary.trim().length === 0 || !isRecord(proposal.extractor) || typeof proposal.extractor.id !== 'string' || proposal.extractor.id.trim().length === 0 || typeof proposal.extractor.version !== 'string' || proposal.extractor.version.trim().length === 0 || !validIsoDate(proposal.createdAt))
+            throw new Error('invalid evolution proposal record');
+    }
+    if (input.type === 'evolution.candidate.accepted') {
+        const artifact = payload.record;
+        if (!isRecord(artifact) || typeof artifact.artifactId !== 'string' || artifact.artifactId.trim().length === 0 || artifact.schemaVersion !== 1 || typeof artifact.proposalId !== 'string' || artifact.proposalId.trim().length === 0 || (artifact.kind !== 'skill' && artifact.kind !== 'compiler-recipe') || artifact.status !== 'candidate' || !validApplicability(artifact.applicability) || typeof artifact.contentHash !== 'string' || artifact.contentHash.trim().length === 0 || !Array.isArray(artifact.lineage) || !artifact.lineage.every(validLineage) || typeof artifact.rationale !== 'string' || artifact.rationale.trim().length === 0 || !validIsoDate(artifact.createdAt))
+            throw new Error('invalid evolution candidate artifact');
+    }
+    if (['evolution.verified', 'evolution.published', 'evolution.rejected', 'evolution.deprecated', 'evolution.superseded'].includes(input.type)) {
+        const transition = payload.transition;
+        if (!isRecord(transition) || (transition.entity !== 'knowledge' && transition.entity !== 'deadend' && transition.entity !== 'skill' && transition.entity !== 'compiler-recipe' && transition.entity !== 'proposal') || typeof transition.entityId !== 'string' || transition.entityId.trim().length === 0 || !validEvolutionTransition(transition.from, transition.to) || typeof transition.reason !== 'string' || transition.reason.trim().length === 0 || (transition.supersedes !== undefined && !validLineage(transition.supersedes)))
+            throw new Error('invalid evolution lifecycle transition');
+        if ((input.type === 'evolution.verified' && transition.to !== 'verified') || (input.type === 'evolution.published' && transition.to !== 'published') || (input.type === 'evolution.rejected' && transition.to !== 'rejected') || (input.type === 'evolution.deprecated' && transition.to !== 'deprecated') || (input.type === 'evolution.superseded' && (transition.to !== 'superseded' || !validLineage(transition.supersedes))))
+            throw new Error('evolution lifecycle event does not match transition');
+    }
+    if (input.type === 'skill.materialized') {
+        if (!validSkill(payload.record))
+            throw new Error('invalid skill record');
+    }
+    if (input.type === 'recipe.materialized') {
+        if (!validRecipe(payload.record))
+            throw new Error('invalid compiler recipe record');
+    }
+    if (input.type === 'skill.invoked') {
+        const invocation = payload.record;
+        if (!isRecord(invocation))
+            throw new Error('skill invocation record is required');
+        validEvolutionId(invocation.invocationId, 'invocation id');
+        if (typeof invocation.skillId !== 'string' || invocation.skillId.trim().length === 0 || typeof invocation.callerEventId !== 'string' || invocation.callerEventId.trim().length === 0 || typeof invocation.inputHash !== 'string' || invocation.inputHash.trim().length === 0 || !validIsoDate(invocation.occurredAt))
+            throw new Error('invalid skill invocation record');
+    }
+    if (input.type === 'skill.outcome.recorded') {
+        const outcome = payload.record;
+        if (!isRecord(outcome))
+            throw new Error('skill outcome record is required');
+        validEvolutionId(outcome.outcomeId, 'outcome id');
+        if (typeof outcome.invocationId !== 'string' || outcome.invocationId.trim().length === 0 || typeof outcome.callerEventId !== 'string' || outcome.callerEventId.trim().length === 0 || (outcome.outcome !== 'success' && outcome.outcome !== 'failure' && outcome.outcome !== 'partial' && outcome.outcome !== 'irrelevant' && outcome.outcome !== 'unknown') || typeof outcome.summary !== 'string' || outcome.summary.trim().length === 0 || !validIsoDate(outcome.occurredAt))
+            throw new Error('invalid skill outcome record');
+    }
 }
 function validateEventShape(event, projectId, file, line) {
     if (!isRecord(event)
@@ -116,7 +236,7 @@ function validateEventShape(event, projectId, file, line) {
 async function recoverPartialTail(projectRoot) {
     const files = await journalFiles(projectRoot);
     const file = files.at(-1);
-    if (!file)
+    if (!file || file.endsWith('.gz'))
         return;
     const filePath = path.join(cognitionJournalDirectory(projectRoot), file);
     const content = await readFile(filePath, 'utf8');
@@ -129,7 +249,7 @@ async function recoverPartialTail(projectRoot) {
         await appendFile(filePath, '\n', 'utf8');
     }
     catch {
-        await truncate(filePath, boundary < 0 ? 0 : boundary + 1);
+        await truncate(filePath, boundary < 0 ? 0 : Buffer.byteLength(content.slice(0, boundary + 1), 'utf8'));
     }
 }
 export async function readJournal(startPath, options = {}) {
@@ -137,8 +257,9 @@ export async function readJournal(startPath, options = {}) {
     const projectId = (await loadManifest(projectRoot)).projectId;
     const events = [];
     let previousHash = null;
-    for (const file of await journalFiles(projectRoot)) {
-        const content = await readFile(path.join(cognitionJournalDirectory(projectRoot), file), 'utf8');
+    const files = await journalFiles(projectRoot);
+    for (const file of files) {
+        const content = (await readSegment(projectRoot, file)).toString('utf8');
         const lines = content.split('\n');
         for (let index = 0; index < lines.length; index += 1) {
             const line = lines[index];
@@ -149,11 +270,12 @@ export async function readJournal(startPath, options = {}) {
                 event = JSON.parse(line);
             }
             catch (error) {
-                if (options.allowPartialTail !== false && index === lines.length - 1 && !content.endsWith('\n'))
+                if (options.allowPartialTail !== false && file === files.at(-1) && !file.endsWith('.gz') && 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);
+            validatePayloadBoundary(event);
             const { hash, ...withoutHash } = event;
             if (event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
                 throw new Error(`invalid journal hash chain at ${file}:${index + 1}`);
@@ -167,6 +289,36 @@ export async function readJournal(startPath, options = {}) {
 export async function verifyJournal(startPath) {
     return readJournal(startPath, { allowPartialTail: false });
 }
+export async function compactJournal(startPath, options = {}) {
+    const root = await resolveProjectRoot(startPath);
+    const minBytes = options.minBytes ?? 1;
+    if (!Number.isSafeInteger(minBytes) || minBytes < 0)
+        throw new Error('minBytes must be a non-negative integer');
+    const operation = async () => {
+        const events = await verifyJournal(root);
+        const before = await journalStorage(root);
+        const eligible = [];
+        for (const file of await journalFiles(root)) {
+            if (!file.endsWith('.gz') && (await readSegment(root, file)).length >= minBytes)
+                eligible.push(file);
+        }
+        if (options.apply) {
+            for (const file of eligible)
+                await archiveSegment(root, file);
+            // Complete deletion after an interrupted publication, but only after validation.
+            for (const file of await journalFiles(root))
+                if (file.endsWith('.gz'))
+                    await archiveSegment(root, file);
+            const replay = await verifyJournal(root);
+            if (replay.length !== events.length || replay.at(-1)?.hash !== events.at(-1)?.hash)
+                throw new Error('journal replay changed during compaction');
+        }
+        const after = options.apply ? await journalStorage(root) : before;
+        return { applied: options.apply === true, eligible, events: events.length, headHash: events.at(-1)?.hash ?? null,
+            bytesBefore: before.bytes, bytesAfter: after.bytes, savedBytes: before.bytes - after.bytes, archives: after.archives };
+    };
+    return options.apply ? withLock(`${locksDirectory(root)}/cognition-journal.lock`, operation) : operation();
+}
 export async function appendEvent(startPath, input) {
     validatePayloadBoundary(input);
     const projectRoot = await resolveProjectRoot(startPath);
@@ -214,8 +366,22 @@ export async function appendEvent(startPath, input) {
             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');
+        const line = `${JSON.stringify(event)}\n`;
+        if (['workspace.paths.changed', 'host.prompt.submitted', 'usage.operation.completed'].includes(input.type)) {
+            let limit;
+            try {
+                limit = (await loadRuntimePolicy(projectRoot)).retentionMaxBytes;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (limit !== undefined && (await journalStorage(projectRoot)).bytes + Buffer.byteLength(line) > limit) {
+                await recordAdmissionDrop(projectRoot, input.type);
+                throw new Error('observation budget exceeded; semantic records remain writable');
+            }
+        }
+        await appendJournalLine(projectRoot, line);
         return { event, appended: true };
     });
 }

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

@@ -10,7 +10,7 @@ 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 { appendEvent, readJournal } from './journal.js';
 import { rebuildProjections } from './projections.js';
 import { v1Fingerprint } from './v1-bridge.js';
 import { migrationReadiness } from './readiness.js';
@@ -162,13 +162,49 @@ export async function reconcileV1State(startPath) {
         const readiness = await migrationReadiness(projectRoot);
         if (!readiness.eligible)
             return;
-        const { records, sourceHash } = await sourceRecords(projectRoot);
+        const { records } = await sourceRecords(projectRoot);
+        const existing = await readJournal(projectRoot);
+        // Compare the latest entity state, not the whole-store hash. Read counters
+        // are not project knowledge and must not duplicate historical checkpoints.
+        const semantic = (record) => {
+            if (record.context && record.snapshot) {
+                const context = record.context;
+                return sha256(JSON.stringify({ snapshot: record.snapshot, status: context.status, title: context.title, tags: context.tags, dependencies: context.dependencies }));
+            }
+            return sha256(JSON.stringify(record));
+        };
+        const identity = (record) => {
+            if (record.context && record.snapshot) {
+                const snapshot = record.snapshot;
+                return `context:${snapshot.contextId}:${snapshot.snapshotId}`;
+            }
+            if (typeof record.noteId === 'string')
+                return `note:${record.noteId}`;
+            if (typeof record.knowledgeId === 'string')
+                return `knowledge:${record.knowledgeId}`;
+            if (typeof record.deadendId === 'string')
+                return `deadend:${record.deadendId}`;
+            return null;
+        };
+        const latest = new Map();
+        for (const event of existing) {
+            const record = event.payload.record;
+            if (record) {
+                const key = identity(record);
+                if (key)
+                    latest.set(key, semantic(record));
+            }
+        }
         for (const record of records) {
+            const key = `${record.kind}:${record.id}`;
+            const contentHash = semantic(record.record);
+            if (latest.get(key) === contentHash)
+                continue;
             await appendEvent(projectRoot, {
                 type: eventType(record, true),
                 occurredAt: record.occurredAt,
                 source: { kind: 'migration' },
-                idempotencyKey: `v1-live-sync:${sourceHash}:${record.kind}:${record.id}`,
+                idempotencyKey: `v1-live-sync-v2:${existing.at(-1)?.hash ?? 'empty'}:${key}:${contentHash}`,
                 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' },
             });