fluffy-context 0.8.0 → 1.0.0-beta.2

package/dist/src/cognition/journal.js

@@ -1,10 +1,13 @@
 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',
@@ -18,7 +21,6 @@ const eventTypes = new Set([
     '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);
@@ -36,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);
 }
@@ -244,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');
@@ -257,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 = {}) {
@@ -265,8 +257,11 @@ 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);
+    options.onProgress?.({ phase: 'verify-journal', completed: 0, total: files.length, unit: 'segments' });
+    let completed = 0;
+    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];
@@ -277,7 +272,7 @@ 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'}`);
             }
@@ -290,12 +285,46 @@ export async function readJournal(startPath, options = {}) {
             previousHash = event.hash;
             events.push(event);
         }
+        options.onProgress?.({ phase: 'verify-journal', completed: ++completed, total: files.length, unit: 'segments' });
     }
     return events;
 }
 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 readJournal(root, { allowPartialTail: false, onProgress: options.onProgress });
+        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) {
+            options.onProgress?.({ phase: 'archive', completed: 0, total: eligible.length, unit: 'segments' });
+            for (const [index, file] of eligible.entries()) {
+                await archiveSegment(root, file);
+                options.onProgress?.({ phase: 'archive', completed: index + 1, total: eligible.length, unit: 'segments' });
+            }
+            // 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 readJournal(root, { allowPartialTail: false, onProgress: options.onProgress });
+            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);
@@ -343,8 +372,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.d.ts

@@ -1,5 +1,6 @@
+import type { ProgressReporter } from './progress.js';
 import { type MigrationReport } from './types.js';
-export declare function importV1(startPath?: string): Promise<MigrationReport>;
+export declare function importV1(startPath?: string, onProgress?: ProgressReporter): Promise<MigrationReport>;
 export declare function reconcileV1State(startPath?: string): Promise<void>;
 export declare function verifyV1Import(startPath?: string): Promise<{
     verified: boolean;

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';
@@ -41,13 +41,14 @@ async function readOptional(filePath) {
         throw error;
     }
 }
-async function sourceRecords(projectRoot) {
+async function sourceRecords(projectRoot, onProgress) {
     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();
+    onProgress?.({ phase: 'scan-contexts', completed: 0, total: contextIds.length, unit: 'contexts' });
     for (const contextId of contextIds) {
         const contextFile = contextMetadataPath(projectRoot, contextId);
         const contextContent = await readFile(contextFile, 'utf8');
@@ -73,6 +74,7 @@ async function sourceRecords(projectRoot) {
                 sourceHash: sha256(content),
             });
         }
+        onProgress?.({ phase: 'scan-contexts', completed: contextIds.indexOf(contextId) + 1, total: contextIds.length, unit: 'contexts' });
     }
     const noteFile = path.join(projectRoot, '.context', 'notes.json');
     const knowledgeFile = path.join(projectRoot, '.context', 'knowledge.json');
@@ -106,7 +108,11 @@ 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: true, autoStart: true, allowHookStartup: true, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
-    await Promise.all([atomicWriteJson(cognitionManifestPath(projectRoot), manifest), atomicWriteJson(cognitionPolicyPath(projectRoot), policy)]);
+    // Interrupted imports must not replace an existing project's opt-out policy.
+    if (await readOptional(cognitionManifestPath(projectRoot)) === null)
+        await atomicWriteJson(cognitionManifestPath(projectRoot), manifest);
+    if (await readOptional(cognitionPolicyPath(projectRoot)) === null)
+        await atomicWriteJson(cognitionPolicyPath(projectRoot), policy);
 }
 async function quarantineReadiness(projectRoot, readiness) {
     await mkdir(cognitionQuarantineDirectory(projectRoot), { recursive: true });
@@ -117,7 +123,7 @@ async function quarantineReadiness(projectRoot, readiness) {
         issues: readiness.issues,
     });
 }
-export async function importV1(startPath) {
+export async function importV1(startPath, onProgress) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/cognition-migration.lock`, async () => {
         const readiness = await migrationReadiness(projectRoot);
@@ -126,7 +132,7 @@ export async function importV1(startPath) {
             await quarantineReadiness(projectRoot, report);
             return report;
         }
-        const { records, sourceHash } = await sourceRecords(projectRoot);
+        const { records, sourceHash } = await sourceRecords(projectRoot, onProgress);
         const existingReceipt = await readOptional(cognitionV1ImportPath(projectRoot));
         if (existingReceipt) {
             const receipt = JSON.parse(existingReceipt);
@@ -138,6 +144,7 @@ export async function importV1(startPath) {
         }
         await writeV2Metadata(projectRoot);
         const importedEventIds = [];
+        onProgress?.({ phase: 'import-records', completed: 0, total: records.length, unit: 'records' });
         for (const record of records) {
             const event = await appendEvent(projectRoot, {
                 type: eventType(record),
@@ -148,6 +155,7 @@ export async function importV1(startPath) {
                 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);
+            onProgress?.({ phase: 'import-records', completed: importedEventIds.length, total: records.length, unit: 'records' });
         }
         await rebuildProjections(projectRoot);
         await atomicWriteJson(cognitionV1SyncPath(projectRoot), { schemaVersion: 2, fingerprint: await v1Fingerprint(projectRoot), updatedAt: new Date().toISOString() });
@@ -162,13 +170,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' },
             });

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

@@ -0,0 +1,7 @@
+export interface ProgressUpdate {
+    phase: string;
+    completed: number;
+    total: number | null;
+    unit?: string;
+}
+export type ProgressReporter = (update: ProgressUpdate) => void;

package/dist/src/cognition/progress.js

@@ -0,0 +1 @@
+export {};

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

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

package/dist/src/cognition/readiness.js

@@ -14,7 +14,7 @@ async function exists(filePath) {
         return false;
     }
 }
-export async function migrationReadiness(startPath) {
+export async function migrationReadiness(startPath, onProgress) {
     const projectRoot = await resolveProjectRoot(startPath);
     const counts = { contexts: 0, snapshots: 0, notes: 0, knowledge: 0, deadends: 0 };
     const issues = [];
@@ -40,7 +40,8 @@ export async function migrationReadiness(startPath) {
     catch (error) {
         issues.push(`v1 contexts: ${error instanceof Error ? error.message : 'unavailable'}`);
     }
-    for (const contextId of contextIds) {
+    onProgress?.({ phase: 'inspect-contexts', completed: 0, total: contextIds.length, unit: 'contexts' });
+    for (const [index, contextId] of contextIds.entries()) {
         try {
             const context = await readJson(contextMetadataPath(projectRoot, contextId));
             if (context.schemaVersion !== 1 || context.id !== contextId || context.projectRoot !== projectRoot) {
@@ -58,6 +59,7 @@ export async function migrationReadiness(startPath) {
         catch (error) {
             issues.push(`context ${contextId}: ${error instanceof Error ? error.message : 'invalid'}`);
         }
+        onProgress?.({ phase: 'inspect-contexts', completed: index + 1, total: contextIds.length, unit: 'contexts' });
     }
     try {
         counts.notes = (await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })).length;

package/dist/src/cognition/runtime.js

@@ -249,6 +249,10 @@ export async function serveRuntime(startPath, options = {}) {
         return closing;
     };
     const touch = () => {
+        // Draining observations during shutdown can still notify activity. Never
+        // recreate an inactivity timer after closeServer has cleared the timers.
+        if (closing)
+            return;
         if (inactivity)
             clearTimeout(inactivity);
         inactivity = setTimeout(() => { void close('inactivity').catch(() => undefined); }, inactivityTimeoutMs);

package/dist/src/cognition/usage-report.js

@@ -2,6 +2,8 @@ import { readdir } from 'node:fs/promises';
 import { resolveProjectRoot } from '../project/project-resolver.js';
 import { readJson, isRecord } from '../storage/json-store.js';
 import { contextsRoot, contextMetadataPath, snapshotsDirectory } from '../storage/layout.js';
+import { journalStorage } from './journal-segments.js';
+import { readAdmissionStats } from './admission.js';
 import { readJournal } from './journal.js';
 import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
@@ -123,6 +125,8 @@ function operationStats(events) {
     return byOperation;
 }
 export async function buildUsageReport(startPath, options = {}) {
+    if (options.baselineTokens !== undefined && (!Number.isSafeInteger(options.baselineTokens) || options.baselineTokens < 0))
+        throw new Error('baselineTokens must be a non-negative safe integer');
     const projectRoot = await resolveProjectRoot(startPath);
     const window = windowOf(options);
     let events = [];
@@ -136,6 +140,13 @@ export async function buildUsageReport(startPath, options = {}) {
         journalVerified = false;
     }
     const scoped = events.filter((event) => inWindow(event, window));
+    const storage = await journalStorage(projectRoot, true);
+    const admission = await readAdmissionStats(projectRoot);
+    const journalBytes = storage.bytes;
+    const eventTypes = {};
+    for (const event of scoped)
+        eventTypes[event.type] = (eventTypes[event.type] ?? 0) + 1;
+    const semanticEvents = scoped.filter((event) => /^(context\.|knowledge\.|deadend\.|note\.|experience\.|evolution\.|skill\.|recipe\.|record\.used)/.test(event.type)).length;
     const usageEvents = scoped.map((event) => ({ event, payload: usagePayload(event) })).filter((item) => item.payload !== null);
     const knowledge = await listKnowledge(projectRoot, true);
     const deadends = await listDeadends(projectRoot, true);
@@ -175,21 +186,21 @@ export async function buildUsageReport(startPath, options = {}) {
         buckets.set(key, bucket);
     }
     const ctxTokens = usageEvents.reduce((sum, item) => sum + item.payload.estimatedOutputTokens, 0);
+    const inputTokens = usageEvents.reduce((sum, item) => sum + item.payload.estimatedInputTokens, 0);
+    const totalTokens = ctxTokens + inputTokens;
     const baseline = options.baselineTokens ?? null;
-    const savings = baseline === null ? null : baseline - ctxTokens;
+    const savings = baseline === null || usageEvents.length === 0 ? null : baseline - totalTokens;
     const investment = metric(ctxTokens, 'estimated', 'tokens', 'chars-div-four');
     const rawAssets = verified.length;
     const usedCount = verified.reduce((sum, key) => sum + Math.min(used.get(key) ?? 0, 3), 0);
     const trendEntries = [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b));
     let cumulativeInvestmentTokens = 0;
     let cumulativeOutputChars = 0;
-    let paybackPeriodStart = null;
     const trends = trendEntries.map(([periodStart, values]) => {
         cumulativeInvestmentTokens += values.estimatedOutputTokens;
         cumulativeOutputChars += values.outputChars;
-        const cumulativeSavings = baseline === null ? null : baseline - cumulativeInvestmentTokens;
-        if (paybackPeriodStart === null && cumulativeSavings !== null && cumulativeSavings >= cumulativeInvestmentTokens)
-            paybackPeriodStart = periodStart;
+        // A window-total baseline cannot establish when savings occurred.
+        const cumulativeSavings = null;
         return {
             periodStart,
             ...values,
@@ -198,35 +209,39 @@ export async function buildUsageReport(startPath, options = {}) {
             cumulativeEstimatedSavings: cumulativeSavings,
         };
     });
-    const paybackReached = paybackPeriodStart !== null;
-    const paybackPeriodDays = paybackPeriodStart === null ? null : Math.max(0, (Date.parse(paybackPeriodStart) - Date.parse(window.from)) / 86_400_000);
     return {
         schemaVersion: 1, generatedAt: new Date().toISOString(), projectRoot, window,
-        dataQuality: { journalVerified, journalEventCount: events.length, windowEventCount: scoped.length, usageEventCount: usageEvents.length, firstUsageAt: usageEvents[0]?.event.occurredAt ?? null, lastUsageAt: usageEvents.at(-1)?.event.occurredAt ?? null, measuredMetricCount: usageEvents.length * 7, estimatedMetricCount: usageEvents.length * 2 + (ctxTokens > 0 ? 1 : 0), unavailableMetricCount: 1 },
+        dataQuality: { journalVerified, journalBytes, journalStorage: storage, admission, eventTypes, semanticEventRatio: metric(scoped.length ? semanticEvents / scoped.length : null, 'derived', 'ratio', 'semantic lifecycle events / window events; not a correctness score'), journalEventCount: events.length, windowEventCount: scoped.length, usageEventCount: usageEvents.length, firstUsageAt: usageEvents[0]?.event.occurredAt ?? null, lastUsageAt: usageEvents.at(-1)?.event.occurredAt ?? null, measuredMetricCount: usageEvents.length * 7, estimatedMetricCount: usageEvents.length * 2 + (ctxTokens > 0 ? 1 : 0), unavailableMetricCount: 1 },
         assets: {
             knowledge: { total: knowledge.length, candidate: knowledge.filter((item) => item.status === 'candidate').length, verified: knowledge.filter((item) => item.status === 'verified').length, retired: knowledge.filter((item) => ['deprecated', 'rejected'].includes(item.status)).length, created: lifecycle('knowledge.proposed'), verifiedInWindow: lifecycle('knowledge.verified') },
             deadends: { total: deadends.length, candidate: deadends.filter((item) => item.status === 'candidate').length, verified: deadends.filter((item) => item.status === 'verified').length, retired: deadends.filter((item) => ['obsolete', 'rejected'].includes(item.status)).length, created: lifecycle('deadend.proposed'), verifiedInWindow: lifecycle('deadend.verified') },
             notes: { total: notes.length, createdInWindow: lifecycle('note.recorded') }, contexts: { total: contextData.items.length, active: contextData.items.filter((item) => ['active', 'stable'].includes(item.status)).length, snapshots: contextData.snapshots }, rawVerifiedAssetCount: rawAssets, effectiveAssetPoints: metric(rawAssets + usedCount * 0.25, 'derived', 'asset-points'), assumptions: { reuseBonusPerUse: 0.25, maxBonusUses: 3 },
         },
         reuse: { recordUsedInWindow: recordUsed, recordUsedTotal: events.filter((event) => event.type === 'record.used').length, usedVerifiedAssetCount: usedVerified, verifiedAssetReuseRate: metric(rawAssets === 0 ? null : usedVerified / rawAssets, 'derived', 'ratio') },
-        investment: { contextOutputTokens: investment, providerTokens: metric(null, 'unavailable', 'tokens') },
+        investment: { contextOutputTokens: investment, contextInputTokens: metric(inputTokens, 'estimated', 'tokens', 'chars-div-four'), totalContextTokens: metric(totalTokens, 'estimated', 'tokens', 'chars-div-four'), providerTokens: metric(null, 'unavailable', 'tokens') },
         payback: {
             baselineTokens: baseline,
             baselineSource: options.baselineSource ?? null,
             estimatedSavings: savings === null ? metric(null, 'unavailable', 'tokens') : metric(savings, 'estimated', 'tokens'),
-            estimatedROI: baseline === null || ctxTokens === 0 ? null : savings / ctxTokens,
-            status: baseline === null ? 'no_baseline' : paybackReached ? 'reached' : 'not_reached',
-            paybackAt: paybackPeriodStart,
-            paybackPeriodDays,
+            estimatedROI: savings === null || totalTokens === 0 ? null : savings / totalTokens,
+            status: baseline === null ? 'no_baseline' : 'unpaired_baseline',
+            paybackAt: null,
+            paybackPeriodDays: null,
         },
         operations: { available: usageEvents.length > 0, byOperation: operationStats(scoped), reason: usageEvents.length > 0 ? null : 'operation output telemetry is not yet recorded' },
         trends,
-        warnings: [...(!journalVerified ? ['v2 journal unavailable; lifecycle metrics may be incomplete'] : []), 'Provider token usage is unavailable', ...(usageEvents.length === 0 ? ['Token investment is unavailable until operation output telemetry is recorded'] : [])],
+        warnings: [...(!journalVerified ? ['v2 journal unavailable; lifecycle metrics may be incomplete'] : []), 'Provider token usage is unavailable', 'chars-div-four is a rough estimate, especially for CJK; context compression is not proven task savings', ...(baseline !== null ? ['Window baseline is unpaired; no causal savings or payback date can be established'] : []), ...(usageEvents.length === 0 ? ['Token investment is unavailable until operation output telemetry is recorded'] : [])],
     };
 }
 export function formatUsageReport(report) {
     const assets = report.assets;
     const payback = report.payback;
-    const lines = ['fluffy-context usage report', `Window: ${String(report.window.from).slice(0, 10)} to ${String(report.window.to).slice(0, 10)}`, '', 'ASSET VALUE', `  Verified knowledge       ${assets.knowledge.verified}`, `  Verified deadends        ${assets.deadends.verified}`, `  Used verified assets     ${report.reuse.usedVerifiedAssetCount}`, `  Asset points             ${assets.effectiveAssetPoints.value.toFixed(2)}  derived`, '', 'TOKEN INVESTMENT', `  Estimated tokens         ${report.investment.contextOutputTokens.value}  estimated`, '  Provider tokens          n/a  unavailable', '', 'RETURN', `  Baseline tokens          ${payback.baselineTokens ?? 'n/a'}`, `  Estimated savings        ${payback.estimatedSavings.value ?? 'n/a'}`, `  ROI                      ${payback.estimatedROI ?? 'n/a'}`, `  Payback                  ${payback.status}`, '', 'COMMAND OUTPUT TREND', `  Usage events             ${report.dataQuality.usageEventCount}`, '', 'DATA QUALITY', `  Journal verified         ${report.dataQuality.journalVerified ? 'yes' : 'no'}`, `  Window events            ${report.dataQuality.windowEventCount}`, `  Warnings                 ${report.warnings.length}`];
+    const lines = ['fluffy-context usage report', `Window: ${String(report.window.from).slice(0, 10)} to ${String(report.window.to).slice(0, 10)}`, '', 'ASSET VALUE', `  Verified knowledge       ${assets.knowledge.verified}`, `  Verified deadends        ${assets.deadends.verified}`, `  Used verified assets     ${report.reuse.usedVerifiedAssetCount}`, `  Asset points             ${assets.effectiveAssetPoints.value.toFixed(2)}  derived`, '', 'TOKEN INVESTMENT', `  Estimated tokens         ${report.investment.totalContextTokens.value}  estimated (input + output)`, '  Provider tokens          n/a  unavailable', '', 'RETURN', `  Baseline tokens          ${payback.baselineTokens ?? 'n/a'}`, `  Estimated savings        ${payback.estimatedSavings.value ?? 'n/a'}`, `  ROI                      ${payback.estimatedROI ?? 'n/a'}`, `  Payback                  ${payback.status}`, '', 'COMMAND OUTPUT TREND', `  Usage events             ${report.dataQuality.usageEventCount}`, '', 'DATA QUALITY', `  Journal verified         ${report.dataQuality.journalVerified ? 'yes' : 'no'}`, `  Window events            ${report.dataQuality.windowEventCount}`, `  Warnings                 ${report.warnings.length}`];
+    lines.push(`  Journal bytes            ${report.dataQuality.journalBytes}`, `  Semantic event ratio     ${report.dataQuality.semanticEventRatio.value ?? 'n/a'}  derived`, '', 'EVENT TYPES');
+    lines.push(`  Archives                 ${report.dataQuality.journalStorage.archives}`, `  Expanded journal bytes   ${report.dataQuality.journalStorage.expandedBytes}`);
+    for (const [type, count] of Object.entries(report.dataQuality.eventTypes))
+        lines.push(`  ${type}: ${count}`);
+    lines.push(`  Budget-rejected observations ${Object.values(report.dataQuality.admission.dropped).reduce((sum, count) => Number(sum) + Number(count), 0)}`);
+    lines.push('', ...report.warnings.map((warning) => `  ${warning}`));
     return `${lines.join('\n')}\n`;
 }

package/dist/src/compiler/compile.js

@@ -197,32 +197,32 @@ function activityText(record) {
     return `activity: ${changes}`;
 }
 function createCandidates(sources, intent, notes, knowledge, deadends, activities) {
-    if (sources.orientation.status !== 'ready')
-        return [];
-    const { context, snapshot, resumeSummary } = sources.orientation;
     const terms = intent.normalizedTerms;
     const candidates = [];
-    const contextSource = sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'current-context', context.id, context.id, snapshot.snapshotId, context.status, null, resumeSummary.relatedFiles);
-    const summaryFields = [
-        ['title', context.title, 'summary'],
-        ['progressSummary', resumeSummary.progressSummary, 'summary'],
-        ['lastError', resumeSummary.lastError, 'risk'],
-    ];
-    for (const [field, value, section] of summaryFields) {
-        const text = textForSummary(field, value);
-        if (text)
-            candidates.push(makeCandidate(section, contextSource, { field, value }, text, terms, [field], field));
-    }
-    const listFields = [
-        ['pendingTasks', resumeSummary.pendingTasks, 'pending'],
-        ['completed', resumeSummary.completed, 'summary'],
-        ['decisions', resumeSummary.decisions, 'decision'],
-        ['risks', resumeSummary.risks, 'risk'],
-        ['relatedFiles', resumeSummary.relatedFiles, 'summary'],
-    ];
-    for (const [field, values, section] of listFields) {
-        for (const [index, value] of values.entries()) {
-            candidates.push(makeCandidate(section, contextSource, { field, value }, `${field}: ${value}`, terms, [field], `${field}:${index}`));
+    if (sources.orientation.status === 'ready') {
+        const { context, snapshot, resumeSummary } = sources.orientation;
+        const contextSource = sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'current-context', context.id, context.id, snapshot.snapshotId, context.status, null, resumeSummary.relatedFiles);
+        const summaryFields = [
+            ['title', context.title, 'summary'],
+            ['progressSummary', resumeSummary.progressSummary, 'summary'],
+            ['lastError', resumeSummary.lastError, 'risk'],
+        ];
+        for (const [field, value, section] of summaryFields) {
+            const text = textForSummary(field, value);
+            if (text)
+                candidates.push(makeCandidate(section, contextSource, { field, value }, text, terms, [field], field));
+        }
+        const listFields = [
+            ['pendingTasks', resumeSummary.pendingTasks, 'pending'],
+            ['completed', resumeSummary.completed, 'summary'],
+            ['decisions', resumeSummary.decisions, 'decision'],
+            ['risks', resumeSummary.risks, 'risk'],
+            ['relatedFiles', resumeSummary.relatedFiles, 'summary'],
+        ];
+        for (const [field, values, section] of listFields) {
+            for (const [index, value] of values.entries()) {
+                candidates.push(makeCandidate(section, contextSource, { field, value }, `${field}: ${value}`, terms, [field], `${field}:${index}`));
+            }
         }
     }
     for (const note of notes) {
@@ -288,8 +288,8 @@ export async function compileContext(startPath, options = {}) {
     const orientation = sources.orientation;
     const maxChars = intent.budget.total;
     const notes = orientation.status === 'ready' ? (await listNotes(sources.anchor.projectRoot, { contextId: orientation.context.id, openOnly: true, limit: options.noteLimit ?? 50, maxChars: Number.MAX_SAFE_INTEGER })).filter((note) => orientation.notes.some((selected) => selected.noteId === note.noteId)) : [];
-    const knowledge = orientation.status === 'ready' && intent.query ? await listKnowledge(sources.anchor.projectRoot, true) : [];
-    const deadends = orientation.status === 'ready' && intent.query ? await listDeadends(sources.anchor.projectRoot, true) : [];
+    const knowledge = intent.query ? await listKnowledge(sources.anchor.projectRoot, true) : [];
+    const deadends = intent.query ? await listDeadends(sources.anchor.projectRoot, true) : [];
     const activities = await extractActivity(sources.anchor.projectRoot, sources.events, sources.anchor, sources.workspace, options.activityLimit ?? 20);
     const all = createCandidates(sources, intent, notes, knowledge, deadends, activities);
     const excluded = [];
@@ -374,8 +374,9 @@ export async function compileContext(startPath, options = {}) {
     };
     const tokenEstimate = estimateTokens(manifestText(selected));
     const selectedItemHashes = selected.map((item) => item.itemHash);
+    const status = orientation.status === 'ready' || selected.length > 0 ? 'ready' : 'no_context';
     const manifestHash = rebuildManifestHash({
-        status: orientation.status,
+        status,
         projectRoot: sources.anchor.projectRoot,
         mode: orientation.explanation.mode,
         anchor: sources.anchor,
@@ -390,7 +391,7 @@ export async function compileContext(startPath, options = {}) {
         schemaVersion: 1,
         compilerVersion: '0.7.7',
         rankingVersion: 'compiler-ranking-v2',
-        status: orientation.status,
+        status,
         projectRoot: sources.anchor.projectRoot,
         mode: orientation.explanation.mode,
         anchor: sources.anchor,

package/dist/src/compiler/inject.d.ts

@@ -0,0 +1,23 @@
+import type { ContextCompileOptions, ContextScenario } from './types.js';
+export declare function inferScenario(query: string): ContextScenario;
+export interface InjectionOptions extends ContextCompileOptions {
+    explain?: boolean;
+}
+export declare function injectContext(startPath: string | undefined, options?: InjectionOptions, interfaceName?: 'cli' | 'hook' | 'agent' | 'mcp'): Promise<{
+    next: string | null;
+    sources?: {
+        candidateId: string;
+        itemHash: string;
+        section: import("./types.js").ContextCandidateSection;
+        provenance: import("./types.js").ContextProvenance;
+    }[] | undefined;
+    status: "ready" | "no_context";
+    scenario: ContextScenario;
+    text: string;
+    budget: {
+        maxChars: number;
+        usedChars: number;
+    };
+    manifestHash: string;
+    sourceCount: number;
+}>;

package/dist/src/compiler/inject.js

@@ -0,0 +1,27 @@
+import { compileContext } from './compile.js';
+import { withUsageTelemetry } from '../cognition/usage.js';
+export function inferScenario(query) {
+    if (/error|fail|bug|异常|报错|失败|修复/i.test(query))
+        return 'debugging';
+    if (/test|verify|验证|测试/i.test(query))
+        return 'verification';
+    if (/resume|恢复|继续/i.test(query))
+        return 'resume';
+    if (/handoff|交接|总结/i.test(query))
+        return 'handoff';
+    if (/implement|add|build|实现|新增|开发/i.test(query))
+        return 'implementation';
+    return 'exploration';
+}
+export async function injectContext(startPath, options = {}, interfaceName = 'agent') {
+    return withUsageTelemetry(startPath, 'compile', interfaceName === 'hook' ? 'claude-hook' : interfaceName, options, async () => {
+        const scenario = options.scenario ?? inferScenario(options.query ?? '');
+        const manifest = await compileContext(startPath, { ...options, scenario, maxChars: options.maxChars ?? 2400, activityLimit: options.activityLimit ?? 0 });
+        return { status: manifest.status, scenario, text: manifest.text,
+            budget: { maxChars: manifest.budget.requested.total, usedChars: manifest.budget.usedChars },
+            manifestHash: manifest.identity.manifestHash,
+            sourceCount: manifest.selected.length,
+            ...(options.explain ? { sources: manifest.selected.map((item) => ({ candidateId: item.candidateId, itemHash: item.itemHash, section: item.section, provenance: item.source.provenance })) } : {}),
+            next: manifest.truncation.truncated ? 'Use ctx compile / ctx expand for selected evidence.' : null };
+    }, interfaceName);
+}