fluffy-context 0.7.2 → 0.7.7

package/dist/src/cognition/usage-report.d.ts

@@ -0,0 +1,40 @@
+export type UsageReportFormat = 'json' | 'ascii';
+export type UsageGranularity = 'day' | 'week' | 'month';
+export interface UsageReportOptions {
+    since?: string;
+    until?: string;
+    days?: number;
+    month?: string;
+    granularity?: UsageGranularity;
+    baselineTokens?: number;
+    baselineSource?: 'manual' | 'recorded-control';
+}
+export interface UsageMetric<T> {
+    value: T | null;
+    quality: 'measured' | 'estimated' | 'derived' | 'unavailable';
+    unit: string;
+    method?: string;
+}
+interface Window {
+    from: string;
+    to: string;
+    kind: 'rolling' | 'calendar-month' | 'explicit';
+    granularity: UsageGranularity;
+}
+export interface UsageReport {
+    schemaVersion: 1;
+    generatedAt: string;
+    projectRoot: string;
+    window: Window;
+    dataQuality: Record<string, unknown>;
+    assets: Record<string, unknown>;
+    reuse: Record<string, unknown>;
+    investment: Record<string, unknown>;
+    payback: Record<string, unknown>;
+    operations: Record<string, unknown>;
+    trends: Array<Record<string, unknown>>;
+    warnings: string[];
+}
+export declare function buildUsageReport(startPath: string | undefined, options?: UsageReportOptions): Promise<UsageReport>;
+export declare function formatUsageReport(report: Record<string, any>): string;
+export {};

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

@@ -0,0 +1,232 @@
+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 { readJournal } from './journal.js';
+import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+function metric(value, quality, unit, method) {
+    return { value, quality, unit, ...(method ? { method } : {}) };
+}
+function iso(value) {
+    const time = Date.parse(value);
+    if (!Number.isFinite(time))
+        throw new Error(`invalid ISO date: ${value}`);
+    return new Date(time).toISOString();
+}
+function windowOf(options, now = new Date()) {
+    if (options.month && !/^\d{4}-\d{2}$/.test(options.month))
+        throw new Error('--month must be YYYY-MM');
+    if (options.since && options.month)
+        throw new Error('--since and --month cannot be combined');
+    if (options.days !== undefined && (!Number.isInteger(options.days) || options.days < 0))
+        throw new Error('--days must be a non-negative integer');
+    const to = options.until ? iso(options.until) : now.toISOString();
+    const toMs = Date.parse(to);
+    if (options.month) {
+        const [year, month] = options.month.split('-').map(Number);
+        const from = new Date(Date.UTC(year, month - 1, 1));
+        const end = new Date(Date.UTC(year, month, 1));
+        if (month < 1 || month > 12 || end.getUTCMonth() !== month % 12)
+            throw new Error('--month must be a valid calendar month');
+        return { from: from.toISOString(), to: end.toISOString(), kind: 'calendar-month', granularity: options.granularity ?? 'week' };
+    }
+    const from = options.since ? iso(options.since) : new Date(toMs - (options.days ?? 30) * 86_400_000).toISOString();
+    if (Date.parse(from) > toMs)
+        throw new Error('--since must not be after --until');
+    return { from, to, kind: options.since || options.until ? 'explicit' : 'rolling', granularity: options.granularity ?? 'day' };
+}
+function inWindow(event, window) {
+    const time = Date.parse(event.occurredAt);
+    return time >= Date.parse(window.from) && time < Date.parse(window.to);
+}
+function dayStart(value, granularity) {
+    const date = new Date(value);
+    if (granularity === 'month')
+        return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1)).toISOString();
+    if (granularity === 'week') {
+        const day = date.getUTCDay();
+        return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() - (day === 0 ? 6 : day - 1))).toISOString();
+    }
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())).toISOString();
+}
+async function contexts(projectRoot) {
+    let ids = [];
+    try {
+        ids = await readdir(contextsRoot(projectRoot));
+    }
+    catch {
+        return { items: [], snapshots: 0 };
+    }
+    const items = [];
+    let snapshots = 0;
+    for (const id of ids) {
+        try {
+            const item = await readJson(contextMetadataPath(projectRoot, id), (value) => isRecord(value) && value.schemaVersion === 1 && value.id === id);
+            items.push(item);
+            snapshots += (await readdir(snapshotsDirectory(projectRoot, id))).filter((file) => file.endsWith('.json')).length;
+        }
+        catch { /* invalid files are reported by doctor */ }
+    }
+    return { items, snapshots };
+}
+function usagePayload(event) {
+    if (event.type !== 'usage.operation.completed' || !isRecord(event.payload))
+        return null;
+    const payload = event.payload;
+    return (payload.operation === 'orient' || payload.operation === 'compile' || payload.operation === 'expand' || payload.operation === 'resume')
+        && (payload.interface === 'cli' || payload.interface === 'mcp' || payload.interface === 'agent' || payload.interface === 'hook')
+        && typeof payload.success === 'boolean'
+        && typeof payload.durationMs === 'number' && Number.isFinite(payload.durationMs) && payload.durationMs >= 0
+        && typeof payload.inputChars === 'number' && Number.isFinite(payload.inputChars) && payload.inputChars >= 0
+        && typeof payload.outputChars === 'number' && Number.isFinite(payload.outputChars) && payload.outputChars >= 0
+        && typeof payload.inputBytes === 'number' && Number.isFinite(payload.inputBytes) && payload.inputBytes >= 0
+        && typeof payload.outputBytes === 'number' && Number.isFinite(payload.outputBytes) && payload.outputBytes >= 0
+        && typeof payload.estimatedInputTokens === 'number' && Number.isFinite(payload.estimatedInputTokens) && payload.estimatedInputTokens >= 0
+        && typeof payload.estimatedOutputTokens === 'number' && Number.isFinite(payload.estimatedOutputTokens) && payload.estimatedOutputTokens >= 0
+        && payload.estimatedMethod === 'chars-div-four'
+        ? payload : null;
+}
+function percentile(values, fraction) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1)];
+}
+function operationStats(events) {
+    const groups = new Map();
+    for (const event of events) {
+        const payload = usagePayload(event);
+        if (!payload)
+            continue;
+        const key = payload.operation;
+        groups.set(key, [...(groups.get(key) ?? []), payload]);
+    }
+    const byOperation = {};
+    for (const [operation, values] of groups) {
+        const durations = values.map((item) => item.durationMs);
+        byOperation[operation] = {
+            calls: values.length,
+            successes: values.filter((item) => item.success).length,
+            failures: values.filter((item) => !item.success).length,
+            successRate: values.filter((item) => item.success).length / values.length,
+            errorRate: values.filter((item) => !item.success).length / values.length,
+            durationMs: { average: durations.reduce((sum, value) => sum + value, 0) / values.length, p50: percentile(durations, 0.5), p95: percentile(durations, 0.95), max: Math.max(...durations) },
+            inputChars: values.reduce((sum, item) => sum + item.inputChars, 0),
+            outputChars: values.reduce((sum, item) => sum + item.outputChars, 0),
+            inputBytes: values.reduce((sum, item) => sum + item.inputBytes, 0),
+            outputBytes: values.reduce((sum, item) => sum + item.outputBytes, 0),
+            estimatedInputTokens: values.reduce((sum, item) => sum + item.estimatedInputTokens, 0),
+            estimatedOutputTokens: values.reduce((sum, item) => sum + item.estimatedOutputTokens, 0),
+        };
+    }
+    return byOperation;
+}
+export async function buildUsageReport(startPath, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const window = windowOf(options);
+    let events = [];
+    let journalVerified = true;
+    try {
+        events = await readJournal(projectRoot);
+    }
+    catch (error) {
+        if (!(error instanceof Error && /ENOENT|manifest|not initialized/i.test(error.message)))
+            throw error;
+        journalVerified = false;
+    }
+    const scoped = events.filter((event) => inWindow(event, window));
+    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);
+    const notes = await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: 0 });
+    const contextData = await contexts(projectRoot);
+    const used = new Map();
+    for (const event of events.filter((item) => item.type === 'record.used')) {
+        const payload = event.payload;
+        if (typeof payload.entity === 'string' && typeof payload.entityId === 'string')
+            used.set(`${payload.entity}:${payload.entityId}`, (used.get(`${payload.entity}:${payload.entityId}`) ?? 0) + 1);
+    }
+    const verified = [...knowledge.filter((item) => item.status === 'verified').map((item) => `knowledge:${item.knowledgeId}`), ...deadends.filter((item) => item.status === 'verified').map((item) => `deadend:${item.deadendId}`)];
+    const usedVerified = verified.filter((key) => (used.get(key) ?? 0) > 0).length;
+    const recordUsed = scoped.filter((event) => event.type === 'record.used').length;
+    const lifecycle = (type) => scoped.filter((event) => event.type === type).length;
+    const buckets = new Map();
+    for (const event of scoped) {
+        const key = dayStart(event.occurredAt, window.granularity);
+        const bucket = buckets.get(key) ?? { operations: 0, usageOperations: 0, recordsUsed: 0, outputChars: 0, estimatedOutputTokens: 0, knowledgeCreated: 0, knowledgeVerified: 0, deadendsCreated: 0, deadendsVerified: 0 };
+        const payload = usagePayload(event);
+        if (payload) {
+            bucket.operations += 1;
+            bucket.usageOperations += 1;
+            bucket.outputChars += payload.outputChars;
+            bucket.estimatedOutputTokens += payload.estimatedOutputTokens;
+        }
+        if (event.type === 'record.used')
+            bucket.recordsUsed += 1;
+        if (event.type === 'knowledge.proposed')
+            bucket.knowledgeCreated += 1;
+        if (event.type === 'knowledge.verified')
+            bucket.knowledgeVerified += 1;
+        if (event.type === 'deadend.proposed')
+            bucket.deadendsCreated += 1;
+        if (event.type === 'deadend.verified')
+            bucket.deadendsVerified += 1;
+        buckets.set(key, bucket);
+    }
+    const ctxTokens = usageEvents.reduce((sum, item) => sum + item.payload.estimatedOutputTokens, 0);
+    const baseline = options.baselineTokens ?? null;
+    const savings = baseline === null ? null : baseline - ctxTokens;
+    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;
+        return {
+            periodStart,
+            ...values,
+            cumulativeOutputChars,
+            cumulativeEstimatedOutputTokens: cumulativeInvestmentTokens,
+            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 },
+        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') },
+        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,
+        },
+        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'] : [])],
+    };
+}
+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}`];
+    return `${lines.join('\n')}\n`;
+}

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

@@ -0,0 +1,5 @@
+import type { CognitionEventSource, UsageOperationCompletedPayload } from './types.js';
+export type UsageOperation = UsageOperationCompletedPayload['operation'];
+export type UsageInterface = UsageOperationCompletedPayload['interface'];
+export declare function recordUsageOperation(startPath: string | undefined, operation: UsageOperation, source: CognitionEventSource, input: unknown, output: unknown, startedAt: number, success: boolean, error?: unknown, interfaceName?: UsageInterface): Promise<void>;
+export declare function withUsageTelemetry<T>(startPath: string | undefined, operation: UsageOperation, source: CognitionEventSource, input: unknown, action: () => Promise<T>, interfaceName?: UsageInterface): Promise<T>;

package/dist/src/cognition/usage.js

@@ -0,0 +1,48 @@
+import { appendEvent } from './journal.js';
+function errorClass(error) {
+    return error instanceof Error ? error.constructor.name : typeof error;
+}
+function interfaceFor(source) {
+    return source === 'mcp' ? 'mcp' : source === 'claude-hook' ? 'hook' : source === 'agent' ? 'agent' : 'cli';
+}
+export async function recordUsageOperation(startPath, operation, source, input, output, startedAt, success, error, interfaceName = interfaceFor(source)) {
+    const inputText = typeof input === 'string' ? input : JSON.stringify(input ?? null);
+    const outputText = typeof output === 'string' ? output : JSON.stringify(output ?? null);
+    const payload = {
+        operation,
+        interface: interfaceName,
+        success,
+        durationMs: Math.max(0, Date.now() - startedAt),
+        inputChars: inputText.length,
+        outputChars: outputText.length,
+        inputBytes: Buffer.byteLength(inputText),
+        outputBytes: Buffer.byteLength(outputText),
+        estimatedInputTokens: Math.ceil(inputText.length / 4),
+        estimatedOutputTokens: Math.ceil(outputText.length / 4),
+        estimatedMethod: 'chars-div-four',
+        ...(success ? {} : { errorClass: errorClass(error) }),
+    };
+    try {
+        await appendEvent(startPath, {
+            type: 'usage.operation.completed',
+            source: { kind: source },
+            idempotencyKey: `usage:${operation}:${source}:${startedAt}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+            payload,
+        });
+    }
+    catch {
+        // Observability must not affect the operation being observed.
+    }
+}
+export async function withUsageTelemetry(startPath, operation, source, input, action, interfaceName = interfaceFor(source)) {
+    const startedAt = Date.now();
+    try {
+        const result = await action();
+        await recordUsageOperation(startPath, operation, source, input, result, startedAt, true, undefined, interfaceName);
+        return result;
+    }
+    catch (error) {
+        await recordUsageOperation(startPath, operation, source, input, { error: errorClass(error) }, startedAt, false, error, interfaceName);
+        throw error;
+    }
+}

package/dist/src/compiler/compile.js

@@ -1,4 +1,5 @@
 import { filterPaths } from '../capture/context-filter.js';
+import { contentHash, estimateTokens, rebuildManifestHash } from './identity.js';
 import { queryTerms } from '../cognition/retrieval.js';
 import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
 import { listNotes } from '../runtime/notes.js';
@@ -84,8 +85,9 @@ function matched(text, terms) {
 }
 function makeCandidate(section, source, content, text, terms, matchedFields, discriminator) {
     const hit = matched(text, terms);
+    const candidateId = `${section}:${source.sourceId}:${matchedFields.join('.')}:${discriminator}`;
     return {
-        candidateId: `${section}:${source.sourceId}:${matchedFields.join('.')}:${discriminator}`,
+        candidateId,
         section,
         source,
         content,
@@ -98,6 +100,10 @@ function makeCandidate(section, source, content, text, terms, matchedFields, dis
         selectedChars: 0,
         selected: false,
         truncated: false,
+        level: 'summary',
+        itemHash: contentHash({ candidateId, source, content, text }),
+        tokenEstimate: estimateTokens(text),
+        expandable: true,
     };
 }
 function applicable(candidate, intent) {
@@ -233,7 +239,7 @@ export async function compileContext(startPath, options = {}) {
     const intent = intentFor(sources, options, normalizedPaths);
     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: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })).filter((note) => !orientation || orientation.notes.some((selected) => selected.noteId === note.noteId)) : [];
+    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 activities = await extractActivity(sources.anchor.projectRoot, sources.events, sources.anchor, sources.workspace, options.activityLimit ?? 20);
@@ -301,9 +307,21 @@ export async function compileContext(startPath, options = {}) {
         deadends: selected.filter((item) => item.section === 'deadend'),
         activity: selected.filter((item) => item.section === 'activity'),
     };
+    const tokenEstimate = estimateTokens(manifestText(selected));
+    const selectedItemHashes = selected.map((item) => item.itemHash);
+    const manifestHash = rebuildManifestHash({
+        status: orientation.status,
+        projectRoot: sources.anchor.projectRoot,
+        mode: orientation.explanation.mode,
+        anchor: sources.anchor,
+        intent,
+        selected,
+        budget: { requested: intent.budget, usedChars, remainingChars: Math.max(0, maxChars - usedChars), sections: sectionStats },
+        truncation,
+    });
     return {
         schemaVersion: 1,
-        compilerVersion: '0.7.2',
+        compilerVersion: '0.7.7',
         rankingVersion: 'compiler-ranking-v2',
         status: orientation.status,
         projectRoot: sources.anchor.projectRoot,
@@ -316,6 +334,11 @@ export async function compileContext(startPath, options = {}) {
         sections,
         selected,
         excluded,
+        identity: {
+            manifestHash,
+            selectedItemHashes,
+            tokenEstimate: { input: tokenEstimate, output: tokenEstimate, unit: 'estimated-tokens', method: 'chars-div-four' },
+        },
         budget: { requested: intent.budget, usedChars, remainingChars: Math.max(0, maxChars - usedChars), sections: sectionStats },
         truncation,
         provenance: {

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

@@ -0,0 +1,2 @@
+import type { ContextExpandInput, ContextExpandResult } from './types.js';
+export declare function expandContext(startPath: string | undefined, input: ContextExpandInput): Promise<ContextExpandResult>;

package/dist/src/compiler/expand.js

@@ -0,0 +1,187 @@
+import { compileContext } from './compile.js';
+import { extractActivity } from './activity.js';
+import { validateManifestIdentity } from './identity.js';
+import { readJournal } from '../cognition/journal.js';
+import { projectEvents, workspaceKey } from '../cognition/projections.js';
+import { rebuildSnapshot } from '../runtime/runtime.js';
+import { listDeadends, listKnowledge } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+function truncateText(value, maxChars) {
+    if (value.length <= maxChars)
+        return { text: value, truncated: false };
+    if (maxChars <= 0)
+        return { text: '', truncated: true };
+    return { text: `${value.slice(0, maxChars - 1)}…`, truncated: true };
+}
+function isExpandLevel(value) {
+    return value === 'structured' || value === 'evidence';
+}
+function validateInput(input) {
+    if (!input.manifestHash.trim())
+        throw new Error('context expand manifest hash must not be empty');
+    if (!input.candidateId?.trim() && !input.itemHash?.trim())
+        throw new Error('context expand requires candidateId or itemHash');
+    if (!isExpandLevel(input.level))
+        throw new Error('context expand level must be structured or evidence');
+    if (input.maxChars !== undefined && (!Number.isSafeInteger(input.maxChars) || input.maxChars < 0))
+        throw new Error('context expand maxChars must be a non-negative integer');
+}
+function selectedCandidate(manifest, input) {
+    const byId = input.candidateId ? manifest.selected.find((item) => item.candidateId === input.candidateId) : undefined;
+    const byHash = input.itemHash ? manifest.selected.find((item) => item.itemHash === input.itemHash) : undefined;
+    if (byId && byHash && byId.candidateId !== byHash.candidateId)
+        throw new Error('context expand candidate selectors do not match');
+    const candidate = byId ?? byHash;
+    if (!candidate)
+        throw new Error('context expand candidate not selected');
+    if (!candidate.expandable)
+        throw new Error('context expand candidate is not expandable');
+    if (candidate.level !== 'summary')
+        throw new Error('context expand candidate is already expanded');
+    return candidate;
+}
+function contextField(content, candidate) {
+    const field = candidate.content.field;
+    if (typeof field !== 'string')
+        throw new Error('context expand current context field is invalid');
+    if (field === 'title')
+        return candidate.content.value ?? '';
+    if (field === 'progressSummary' || field === 'lastError')
+        return content[field];
+    if (field === 'pendingTasks' || field === 'completed' || field === 'decisions' || field === 'risks' || field === 'relatedFiles') {
+        const discriminator = candidate.candidateId.split(':').at(-1) ?? '';
+        const index = Number(discriminator);
+        const values = content[field];
+        if (!Number.isInteger(index) || index < 0 || index >= values.length)
+            throw new Error(`context expand current context item is unavailable: ${field}`);
+        return values[index];
+    }
+    throw new Error(`context expand unsupported current context field: ${field}`);
+}
+function currentContextText(value, candidate) {
+    const field = candidate.content.field;
+    if (typeof field !== 'string')
+        throw new Error('context expand current context field is invalid');
+    return `${field}: ${Array.isArray(value) ? value.join(', ') : value ?? ''}`;
+}
+function recordText(source, value) {
+    if (source.kind === 'note') {
+        const note = value;
+        return `${note.kind}: ${note.message}`;
+    }
+    if (source.kind === 'knowledge')
+        return value.statement;
+    const deadend = value;
+    return `${deadend.attempt}: ${deadend.reason}`;
+}
+function evidenceText(source, value, structuredText) {
+    return `${structuredText}\nevidence: ${JSON.stringify({
+        source: source.provenance,
+        ...(source.kind === 'knowledge' ? { supportingEvidence: value.supportingEvidence } : {}),
+        ...(source.kind === 'deadend' ? { observedEvidence: value.observedEvidence } : {}),
+        ...(source.kind === 'note' ? { relatedFiles: value.relatedFiles } : {}),
+    })}`;
+}
+function recordApplicability(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const applicability = value.applicability;
+    if (!applicability || typeof applicability !== 'object' || Array.isArray(applicability))
+        return undefined;
+    return applicability;
+}
+function ensureApplicable(source, value, manifest) {
+    const applicability = recordApplicability(value);
+    if (!applicability)
+        return;
+    if (applicability.branchMode !== source.applicability.branchMode)
+        throw new Error(`context expand source applicability changed: ${source.entityId}`);
+    if (applicability.branchMode === 'exact') {
+        const branch = manifest.anchor.ref ?? manifest.anchor.branch ?? 'detached';
+        const branches = (applicability.branches ?? []).map((item) => item.toLowerCase());
+        if (branches.length > 0 && !branches.includes(branch.toLowerCase()) && !branches.includes((manifest.anchor.branch ?? '').toLowerCase()))
+            throw new Error(`context expand source is not applicable: ${source.entityId}`);
+        if (applicability.sourceCommit && applicability.sourceCommit !== manifest.anchor.head)
+            throw new Error(`context expand source commit is not applicable: ${source.entityId}`);
+        if (source.applicability.worktreeId && source.applicability.worktreeId !== manifest.anchor.worktreeId)
+            throw new Error(`context expand source worktree is not applicable: ${source.entityId}`);
+        if (source.applicability.ref && source.applicability.ref !== manifest.anchor.ref)
+            throw new Error(`context expand source ref is not applicable: ${source.entityId}`);
+    }
+    if (source.scope && typeof value.scope === 'string' && source.scope !== value.scope)
+        throw new Error(`context expand source scope changed: ${source.entityId}`);
+    const paths = applicability.paths ?? [];
+    if (source.paths.length > 0 && paths.length > 0 && !source.paths.some((path) => paths.includes(path)))
+        throw new Error(`context expand source paths changed: ${source.entityId}`);
+}
+async function resolveCandidate(projectRoot, manifest, candidate, level) {
+    const source = candidate.source;
+    if (source.kind === 'current-context') {
+        if (!source.contextId || !source.snapshotId)
+            throw new Error('context expand current context source is incomplete');
+        const content = await rebuildSnapshot(projectRoot, source.contextId, source.snapshotId);
+        const value = contextField(content, candidate);
+        const text = currentContextText(value, candidate);
+        return { content: level === 'evidence' ? { field: candidate.content.field, value, source: source.provenance } : { field: candidate.content.field, value }, text: level === 'evidence' ? evidenceText(source, { value }, text) : text };
+    }
+    if (source.kind === 'note') {
+        const note = (await listNotes(projectRoot, { contextId: source.contextId ?? undefined, limit: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })).find((item) => item.noteId === source.entityId);
+        if (!note)
+            throw new Error(`context expand note not found: ${source.entityId}`);
+        const text = recordText(source, note);
+        return { content: level === 'evidence' ? { ...note, provenance: source.provenance } : note, text: level === 'evidence' ? evidenceText(source, note, text) : text };
+    }
+    if (source.kind === 'knowledge') {
+        const knowledge = (await listKnowledge(projectRoot, true)).find((item) => item.knowledgeId === source.entityId);
+        if (!knowledge || knowledge.status !== 'verified')
+            throw new Error(`context expand knowledge is no longer verified: ${source.entityId}`);
+        ensureApplicable(source, knowledge, manifest);
+        const text = recordText(source, knowledge);
+        return { content: level === 'evidence' ? { ...knowledge, provenance: source.provenance } : knowledge, text: level === 'evidence' ? evidenceText(source, knowledge, text) : text };
+    }
+    if (source.kind === 'deadend') {
+        const deadend = (await listDeadends(projectRoot, true)).find((item) => item.deadendId === source.entityId);
+        if (!deadend || deadend.status !== 'verified')
+            throw new Error(`context expand deadend is no longer verified: ${source.entityId}`);
+        ensureApplicable(source, deadend, manifest);
+        const text = recordText(source, deadend);
+        return { content: level === 'evidence' ? { ...deadend, provenance: source.provenance } : deadend, text: level === 'evidence' ? evidenceText(source, deadend, text) : text };
+    }
+    if (source.kind === 'journal') {
+        const events = manifest.provenance.journalRead ? await readJournal(projectRoot) : [];
+        const projection = events.length > 0 ? projectEvents(events) : null;
+        const workspace = projection?.workspaces[workspaceKey(manifest.anchor)] ?? null;
+        const records = await extractActivity(projectRoot, events, manifest.anchor, workspace, Number.MAX_SAFE_INTEGER);
+        const activity = records.find((item) => item.eventId === source.entityId);
+        if (!activity)
+            throw new Error(`context expand activity not found: ${source.entityId}`);
+        return { content: activity, text: `activity: ${activity.changes.map((change) => `${change.path} (${change.kind})`).join(', ')}` };
+    }
+    throw new Error(`context expand source kind is not supported: ${source.kind}`);
+}
+export async function expandContext(startPath, input) {
+    validateInput(input);
+    const manifest = await compileContext(startPath, input.compile);
+    if (!validateManifestIdentity(manifest) || manifest.identity.manifestHash !== input.manifestHash)
+        throw new Error('context expand manifest hash mismatch');
+    const candidate = selectedCandidate(manifest, input);
+    const resolved = await resolveCandidate(manifest.projectRoot, manifest, candidate, input.level);
+    const limited = truncateText(resolved.text, input.maxChars ?? Number.MAX_SAFE_INTEGER);
+    const content = limited.truncated ? null : resolved.content;
+    const requestedChars = input.maxChars ?? resolved.text.length;
+    return {
+        status: limited.truncated ? 'partial' : 'complete',
+        projectRoot: manifest.projectRoot,
+        manifestHash: manifest.identity.manifestHash,
+        candidateId: candidate.candidateId,
+        itemHash: candidate.itemHash,
+        previousLevel: candidate.level,
+        requestedLevel: input.level,
+        resolvedLevel: input.level,
+        source: candidate.source,
+        content,
+        text: limited.text,
+        budget: { requestedChars, usedChars: limited.text.length, remainingChars: Math.max(0, requestedChars - limited.text.length), truncated: limited.truncated },
+        provenance: manifest.provenance,
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { ContextManifest } from './types.js';
+export declare function canonicalJson(value: unknown): string;
+export declare function contentHash(value: unknown): string;
+export declare function estimateTokens(value: string): number;
+export declare function rebuildManifestHash(manifest: Pick<ContextManifest, 'status' | 'projectRoot' | 'mode' | 'anchor' | 'intent' | 'selected' | 'budget' | 'truncation'>): string;
+export declare function validateManifestIdentity(manifest: ContextManifest): boolean;

package/dist/src/compiler/identity.js

@@ -0,0 +1,36 @@
+import crypto from 'node:crypto';
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+}
+export function contentHash(value) {
+    return crypto.createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+export function estimateTokens(value) {
+    return value.length === 0 ? 0 : Math.ceil(value.length / 4);
+}
+export function rebuildManifestHash(manifest) {
+    return contentHash({
+        schemaVersion: 1,
+        compilerVersion: '0.7.7',
+        rankingVersion: 'compiler-ranking-v2',
+        status: manifest.status,
+        projectRoot: manifest.projectRoot,
+        mode: manifest.mode,
+        anchor: manifest.anchor,
+        intent: manifest.intent,
+        selectedItemHashes: manifest.selected.map((item) => item.itemHash),
+        budget: { usedChars: manifest.budget.usedChars, maxChars: manifest.budget.requested.total },
+        truncation: manifest.truncation,
+    });
+}
+export function validateManifestIdentity(manifest) {
+    return manifest.identity.manifestHash === rebuildManifestHash(manifest)
+        && JSON.stringify(manifest.identity.selectedItemHashes) === JSON.stringify(manifest.selected.map((item) => item.itemHash))
+        && manifest.identity.tokenEstimate.input === estimateTokens(manifest.text)
+        && manifest.identity.tokenEstimate.output === estimateTokens(manifest.text);
+}