fluffy-context 0.8.0 → 1.0.0-beta.1

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,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];
@@ -277,7 +270,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'}`);
             }
@@ -296,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);
@@ -343,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' },
             });

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);
+}

package/dist/src/hooks/claude-code.js

@@ -1,10 +1,10 @@
-import { contextOrient } from '../agent/api.js';
 import { appendEvent } from '../cognition/journal.js';
 import { v2Enabled } from '../cognition/orient.js';
 import { ensureRuntimeForSession, touchRuntime } from '../cognition/runtime.js';
 import { loadRuntimePolicy } from '../cognition/policy.js';
 import { readGitWorktreeState } from '../git/git-adapter.js';
 import { resolveProjectRoot } from '../project/project-resolver.js';
+import { injectContext } from '../compiler/inject.js';
 const HOOK_RESPONSE = '{}\n';
 function text(value) {
     return typeof value === 'string' ? value : undefined;
@@ -13,50 +13,6 @@ function compact(value, maxChars) {
     const normalized = value.replace(/\s+/g, ' ').trim();
     return normalized.length <= maxChars ? normalized : `${normalized.slice(0, maxChars - 1)}…`;
 }
-function lines(label, values, limit) {
-    return values.slice(0, limit).map((value) => `- ${label}: ${compact(value, 240)}`);
-}
-function readyContext(result) {
-    const content = [
-        `当前 Context：${compact(result.context.title, 160)}`,
-        `进度：${compact(result.resumeSummary.progressSummary, 360)}`,
-        ...lines('待办', result.resumeSummary.pendingTasks, 4),
-        ...lines('决策', result.resumeSummary.decisions, 3),
-        ...lines('风险', result.resumeSummary.risks, 3),
-        ...result.knowledge.hits.slice(0, 5).map((hit) => `- 已验证知识：${compact(hit.knowledge.statement, 240)}`),
-        ...result.deadends.hits.slice(0, 3).map((hit) => `- 已验证死路（避免）：${compact(hit.deadend.attempt, 180)}；${compact(hit.deadend.reason, 180)}`),
-        ...result.notes.slice(0, 8).map((note) => `- 开放 Note：${compact(note.message, 220)}`),
-    ];
-    if (result.truncated)
-        content.push('- 上下文已按预算截断；需要时使用 context_orient 或 ctx orient 进一步查询。');
-    return content;
-}
-function sessionContext(result) {
-    const phases = [
-        '开发阶段：Orient → Plan → Implement → Verify → Handoff。',
-        '先基于以下上下文明确计划；实现中记录重要观察/决策/阻塞为 ctx note；验证后显式 ctx checkpoint，总结完成、待办、决策和风险。不要自动保存 Snapshot。',
-    ];
-    if (result.status === 'no_context') {
-        phases.push('当前没有可恢复的 Context。开始有意义的工作后，使用 ctx checkpoint 创建一个。');
-    }
-    else {
-        phases.push(...readyContext(result));
-    }
-    return phases.join('\n');
-}
-function promptContext(result) {
-    const phases = [
-        '开发阶段：Implement → Verify → Handoff。',
-        '实现时用 ctx note 记录重要观察、决策或阻塞；完成后运行适用的验证。阶段结束时显式 ctx checkpoint（可 --absorb-notes），不要由 Hook 自动保存。',
-    ];
-    if (result.status === 'no_context') {
-        phases.push('当前没有可恢复的 Context；如果这项工作会继续，先建立 checkpoint。');
-    }
-    else {
-        phases.push(...readyContext(result));
-    }
-    return phases.join('\n');
-}
 function stableId(input, name) {
     return name === 'session' ? text(input.session_id) ?? text(input.sessionId) : text(input.event_id) ?? text(input.eventId);
 }
@@ -111,17 +67,22 @@ export async function runClaudeCodeHook(event, raw) {
         await capture(event, input).catch(() => undefined);
         await touchRuntime(text(input.cwd)).catch(() => false);
         const cwd = text(input.cwd);
-        const result = event === 'session-start'
-            ? await contextOrient(cwd, { maxChars: 1200, noteLimit: 8 })
-            : await contextOrient(cwd, {
-                query: compact(text(input.prompt) ?? '', 500) || undefined,
-                maxChars: 1800,
-                knowledgeLimit: 5,
-                deadendLimit: 3,
-                noteLimit: 8,
-            });
-        const additionalContext = event === 'session-start' ? sessionContext(result) : promptContext(result);
-        return `${JSON.stringify({ additionalContext })}\n`;
+        const result = await injectContext(cwd, {
+            query: compact(text(input.prompt) ?? '', 500) || undefined,
+            scenario: event === 'session-start' ? 'resume' : undefined,
+            trigger: event === 'session-start' ? 'session-start' : 'prompt',
+            adapter: 'claude-code',
+            maxChars: event === 'session-start' ? 1200 : 1800,
+            knowledgeLimit: 5,
+            deadendLimit: 3,
+            noteLimit: 8,
+        }, 'hook');
+        const guidance = event === 'session-start' ? 'Orient → Plan → Implement → Verify → Handoff' : 'Implement → Verify → Handoff';
+        const additionalContext = `${guidance}\n将项目上下文作为证据；重要发现用 ctx note，阶段结束用 ctx checkpoint。\n${result.status === 'no_context' ? '当前没有可恢复的 Context。\n' : ''}${result.text}`;
+        return `${JSON.stringify({ hookSpecificOutput: {
+                hookEventName: event === 'session-start' ? 'SessionStart' : 'UserPromptSubmit',
+                additionalContext,
+            } })}\n`;
     }
     catch {
         return HOOK_RESPONSE;