fluffy-context 0.7.2 → 0.7.6

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

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

package/dist/src/agent/api.js

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

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

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

package/dist/src/agent/index.js

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

package/dist/src/cli/main.js

@@ -2,6 +2,7 @@
 import { checkpoint, resume } from '../runtime/runtime.js';
 import { contextOrient } from '../agent/api.js';
 import { compileContext } from '../compiler/compile.js';
+import { contextExpand } from '../agent/api.js';
 import { importV1, verifyV1Import } from '../cognition/migration-v1.js';
 import { recordUse } from '../cognition/feedback.js';
 import { verifyJournal } from '../cognition/journal.js';
@@ -131,6 +132,27 @@ Options:
   --knowledge-limit <number> Maximum knowledge matches (default: 10)
   --deadend-limit <number>   Maximum deadend matches (default: 10)
   --note-limit <number>      Maximum open notes (default: 20)
+  --activity-limit <number>  Maximum recent activity groups (default: 20)`,
+    expand: `usage: ctx expand [options]
+
+Expand one selected compiler candidate without writing project state.
+
+Options:
+  --path <path>              Project path
+  --manifest-hash <hash>     Manifest identity hash from ctx compile
+  --candidate-id <id>        Selected candidate ID
+  --item-hash <hash>         Selected item hash
+  --level <level>            structured|evidence
+  --max-chars <number>       Maximum expanded characters
+  --compile-max-chars <number> Original compile budget (default: 4000)
+  --context <id>             Context ID
+  --query <text>             Original compile query
+  --scenario <scenario>      resume|implementation|debugging|verification|handoff|exploration|unknown
+  --scope <scope>            Exact consensus scope
+  --paths <paths>            Comma-separated project-relative paths
+  --knowledge-limit <number> Maximum knowledge matches (default: 10)
+  --deadend-limit <number>   Maximum deadend matches (default: 10)
+  --note-limit <number>      Maximum open notes (default: 20)
   --activity-limit <number>  Maximum recent activity groups (default: 20)`,
     agent: `usage: ctx agent serve
 
@@ -139,7 +161,7 @@ Start an MCP stdio server for Agent integrations.
 Run "ctx agent serve --help" for details.`,
     'agent serve': `usage: ctx agent serve
 
-Start an MCP stdio server exposing the context_orient tool.
+Start an MCP stdio server exposing context_orient, context_expand, context_compile, context_resume, context_note_list, context_note_add, and context_checkpoint tools.
 
 The server owns standard input/output; do not use it interactively.`,
     hook: `usage: ctx hook claude-code session-start|user-prompt
@@ -341,7 +363,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|checkpoint|resume|orient|compile|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
+    return `usage: ctx init|checkpoint|resume|orient|compile|expand|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -466,6 +488,39 @@ async function run(args) {
             }));
             return;
         }
+        case 'expand': {
+            const valueOptions = ['--path', '--manifest-hash', '--candidate-id', '--item-hash', '--level', '--max-chars', '--compile-max-chars', '--context', '--query', '--scenario', '--scope', '--paths', '--knowledge-limit', '--deadend-limit', '--note-limit', '--activity-limit'];
+            validateOptions(args.slice(1), valueOptions, valueOptions);
+            validatePositionals(positionals(args.slice(1), valueOptions), 0, HELP.expand);
+            const level = enumOption(args, '--level', ['structured', 'evidence']);
+            if (!level)
+                throw new Error('--level is required');
+            const manifestHash = option(args, '--manifest-hash');
+            if (!manifestHash)
+                throw new Error('--manifest-hash is required');
+            const compileMaxChars = numericOption(args, '--compile-max-chars', 4000);
+            await ensureRuntimeForSession(target, { source: 'cli', timeoutMs: 1_000 }).catch(() => undefined);
+            print(await contextExpand(target, {
+                manifestHash,
+                candidateId: option(args, '--candidate-id'),
+                itemHash: option(args, '--item-hash'),
+                level: level,
+                maxChars: option(args, '--max-chars') === undefined ? undefined : numericOption(args, '--max-chars', 0),
+                compile: {
+                    contextId: option(args, '--context'),
+                    query: option(args, '--query'),
+                    scenario: enumOption(args, '--scenario', ['resume', 'implementation', 'debugging', 'verification', 'handoff', 'exploration', 'unknown']),
+                    scope: option(args, '--scope'),
+                    paths: listOption(args, '--paths'),
+                    maxChars: compileMaxChars,
+                    knowledgeLimit: numericOption(args, '--knowledge-limit', 10),
+                    deadendLimit: numericOption(args, '--deadend-limit', 10),
+                    noteLimit: numericOption(args, '--note-limit', 20),
+                    activityLimit: numericOption(args, '--activity-limit', 20),
+                },
+            }));
+            return;
+        }
         case 'agent':
             if (args[1] !== 'serve')
                 throw new Error(HELP.agent);

package/dist/src/cognition/journal.js

@@ -55,6 +55,22 @@ function validGitAnchor(value) {
 function validIsoDate(value) {
     return typeof value === 'string' && Number.isFinite(Date.parse(value));
 }
+function validatePayloadBoundary(input) {
+    const payload = input.payload;
+    if (input.type === 'host.prompt.submitted' && (typeof payload.intent !== 'string' || payload.intent.trim().length === 0)) {
+        throw new Error('host prompt intent must not be empty');
+    }
+    if (['note.recorded', 'note.resolved', 'note.absorbed'].includes(input.type)) {
+        const record = payload.record;
+        if (!isRecord(record) || typeof record.message !== 'string' || record.message.trim().length === 0)
+            throw new Error('note message must not be empty');
+    }
+    if (input.type === 'workspace.paths.changed') {
+        const changes = payload.changes;
+        if (!Array.isArray(changes) || changes.length === 0)
+            throw new Error('workspace activity must contain changes');
+    }
+}
 function validateEventShape(event, projectId, file, line) {
     if (!isRecord(event)
         || event.schemaVersion !== 2
@@ -140,6 +156,7 @@ export async function verifyJournal(startPath) {
     return readJournal(startPath, { allowPartialTail: false });
 }
 export async function appendEvent(startPath, input) {
+    validatePayloadBoundary(input);
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/cognition-journal.lock`, async () => {
         await recoverPartialTail(projectRoot);

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.6',
         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.6',
+        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);
+}

package/dist/src/compiler/sources.js

@@ -110,21 +110,17 @@ export async function loadCompilerSources(startPath, options) {
     return { orientation, anchor, events, workspace, fallbackReason };
 }
 export function latestHostIntent(events, anchor) {
-    return [...events].reverse().find((event) => {
-        if (event.type !== 'host.prompt.submitted')
+    const event = [...events].reverse().find((candidate) => {
+        if (candidate.type !== 'host.prompt.submitted')
             return false;
-        if (event.git.worktreeId !== null && event.git.worktreeId !== anchor.worktreeId)
+        if (candidate.git.worktreeId !== null && candidate.git.worktreeId !== anchor.worktreeId)
             return false;
-        if (event.git.ref !== null && event.git.ref !== anchor.ref)
+        if (candidate.git.ref !== null && candidate.git.ref !== anchor.ref)
             return false;
-        const payload = event.payload;
+        const payload = candidate.payload;
         return typeof payload.intent === 'string' && payload.intent.trim().length > 0;
-    })?.payload
-        ? (() => {
-            const event = [...events].reverse().find((item) => item.type === 'host.prompt.submitted' && item.git.worktreeId === anchor.worktreeId && item.git.ref === anchor.ref && typeof item.payload.intent === 'string');
-            if (!event)
-                return null;
-            return { value: event.payload.intent, eventId: event.eventId };
-        })()
-        : null;
+    });
+    if (!event)
+        return null;
+    return { value: event.payload.intent, eventId: event.eventId };
 }

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

@@ -2,6 +2,8 @@ import type { CognitionGitAnchor, WorkspacePathChange } from '../cognition/types
 import type { ContextOrientResult } from '../agent/types.js';
 import type { Deadend, Knowledge, Note, ResumeSummary, StructuredContext } from '../runtime/types.js';
 export type ContextScenario = 'resume' | 'implementation' | 'debugging' | 'verification' | 'handoff' | 'exploration' | 'unknown';
+export type ContextLevel = 'signal' | 'summary' | 'structured' | 'evidence';
+export type ContextExpandLevel = 'structured' | 'evidence';
 export type ContextSourceKind = 'current-context' | 'checkpoint' | 'note' | 'journal' | 'knowledge' | 'deadend';
 export type ContextCandidateSection = 'summary' | 'pending' | 'decision' | 'risk' | 'note' | 'knowledge' | 'deadend' | 'activity';
 export type ContextSignalOrigin = 'explicit' | 'deterministic';
@@ -41,6 +43,12 @@ export interface ContextBudget {
     reservedForRenderer: number;
     sections?: Partial<Record<ContextCandidateSection, number>>;
 }
+export interface ContextTokenEstimate {
+    input: number;
+    output: number;
+    unit: 'estimated-tokens';
+    method: 'chars-div-four';
+}
 export interface ContextSourceApplicability {
     project: true;
     branchMode: 'global' | 'exact' | 'unsupported';
@@ -100,6 +108,10 @@ export interface ContextCandidate<T = unknown> {
     selectedChars: number;
     selected: boolean;
     truncated: boolean;
+    level: ContextLevel;
+    itemHash: string;
+    tokenEstimate: number;
+    expandable: boolean;
 }
 export type ContextExclusionReason = 'no_active_context' | 'context_mismatch' | 'status_not_verified' | 'not_open' | 'absorbed' | 'applicability_mismatch' | 'scope_mismatch' | 'path_mismatch' | 'query_no_match' | 'result_limit' | 'budget' | 'unsupported_applicability' | 'v2_unavailable';
 export interface ContextExclusion {
@@ -138,6 +150,11 @@ export interface ContextManifestProvenance {
     selectedEventIds: string[];
     fallbackReason: string | null;
 }
+export interface ContextManifestIdentity {
+    manifestHash: string;
+    selectedItemHashes: string[];
+    tokenEstimate: ContextTokenEstimate;
+}
 export interface ContextCompileOptions {
     contextId?: string;
     query?: string;
@@ -154,9 +171,37 @@ export interface ContextCompileOptions {
     sessionId?: string;
     eventId?: string;
 }
+export interface ContextExpandInput {
+    manifestHash: string;
+    candidateId?: string;
+    itemHash?: string;
+    level: ContextExpandLevel;
+    maxChars?: number;
+    compile: ContextCompileOptions;
+}
+export interface ContextExpandResult {
+    status: 'complete' | 'partial';
+    projectRoot: string;
+    manifestHash: string;
+    candidateId: string;
+    itemHash: string;
+    previousLevel: ContextLevel;
+    requestedLevel: ContextExpandLevel;
+    resolvedLevel: ContextExpandLevel;
+    source: ContextSourceDescriptor;
+    content: unknown | null;
+    text: string;
+    budget: {
+        requestedChars: number;
+        usedChars: number;
+        remainingChars: number;
+        truncated: boolean;
+    };
+    provenance: ContextManifestProvenance;
+}
 export interface ContextManifest {
     schemaVersion: 1;
-    compilerVersion: '0.7.2';
+    compilerVersion: '0.7.6';
     rankingVersion: 'compiler-ranking-v2';
     status: 'ready' | 'no_context';
     projectRoot: string;
@@ -178,6 +223,7 @@ export interface ContextManifest {
     };
     selected: ContextCandidate[];
     excluded: ContextExclusion[];
+    identity: ContextManifestIdentity;
     budget: ContextBudgetReport;
     truncation: ContextTruncation;
     provenance: ContextManifestProvenance;