fluffy-context 0.6.0 → 0.7.6

package/dist/src/compiler/activity.js

@@ -0,0 +1,79 @@
+import { filterPaths } from '../capture/context-filter.js';
+import { workspaceKey } from '../cognition/projections.js';
+const changeKinds = new Set(['created', 'modified', 'deleted', 'renamed', 'unknown']);
+function normalizedPath(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replaceAll('\\', '/');
+    return normalized.length > 0 ? normalized : null;
+}
+function stableCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function metadataNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function parsePayload(event) {
+    const payload = event.payload;
+    return payload.schemaVersion === 1 && typeof payload === 'object' && payload !== null ? payload : null;
+}
+async function activityForEvent(projectRoot, event, focus) {
+    const payload = parsePayload(event);
+    if (!payload)
+        return null;
+    const rawPaths = Array.isArray(payload.paths) ? payload.paths.map(normalizedPath).filter((value) => value !== null) : [];
+    const rawChanges = Array.isArray(payload.changes) ? payload.changes : [];
+    const changePaths = rawChanges.map((change) => normalizedPath(change?.path)).filter((value) => value !== null);
+    const allowed = await filterPaths(projectRoot, [...new Set([...rawPaths, ...changePaths])]);
+    if (allowed.length === 0)
+        return null;
+    const allowedSet = new Set(allowed);
+    const changes = [];
+    for (const change of rawChanges) {
+        const path = normalizedPath(change?.path);
+        if (!path || !allowedSet.has(path))
+            continue;
+        changes.push({
+            path,
+            kind: changeKinds.has(change?.kind) ? change.kind : 'unknown',
+            fileType: 'file',
+            ...(metadataNumber(change?.sizeBytes) !== undefined ? { sizeBytes: metadataNumber(change?.sizeBytes) } : {}),
+            ...(metadataNumber(change?.mtimeMs) !== undefined ? { mtimeMs: metadataNumber(change?.mtimeMs) } : {}),
+        });
+    }
+    const fallbackChanges = changes.length > 0 ? changes : allowed.map((path) => ({ path, kind: 'unknown', fileType: 'file' }));
+    const paths = [...new Set(fallbackChanges.map((change) => change.path))].sort(stableCompare);
+    return {
+        eventId: event.eventId,
+        occurredAt: event.occurredAt,
+        anchor: {
+            projectRoot,
+            worktreeId: event.git.worktreeId,
+            branch: event.git.branch,
+            ref: event.git.ref,
+            head: event.git.head,
+        },
+        paths,
+        changes: fallbackChanges.sort((left, right) => stableCompare(left.path, right.path)),
+        pathCount: typeof payload.pathCount === 'number' && Number.isSafeInteger(payload.pathCount) && payload.pathCount >= paths.length ? payload.pathCount : paths.length,
+        coalesced: payload.coalesced === true,
+        truncated: payload.truncated === true,
+        focusMatch: paths.some((path) => focus.includes(path)),
+    };
+}
+export async function extractActivity(projectRoot, events, anchor, workspace, limit) {
+    if (limit <= 0 || !workspace)
+        return [];
+    const currentWorkspace = workspaceKey(anchor);
+    const matching = events
+        .filter((event) => event.type === 'workspace.paths.changed' && workspaceKey(event.git) === currentWorkspace)
+        .sort((left, right) => right.occurredAt.localeCompare(left.occurredAt) || right.eventId.localeCompare(left.eventId))
+        .slice(0, limit);
+    const records = [];
+    for (const event of matching) {
+        const record = await activityForEvent(projectRoot, event, workspace.pathFocus);
+        if (record)
+            records.push(record);
+    }
+    return records;
+}

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

@@ -0,0 +1,2 @@
+import type { ContextCompileOptions, ContextManifest } from './types.js';
+export declare function compileContext(startPath?: string, options?: ContextCompileOptions): Promise<ContextManifest>;

package/dist/src/compiler/compile.js

@@ -0,0 +1,353 @@
+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';
+import { extractActivity } from './activity.js';
+import { latestHostIntent, loadCompilerSources, sourceDescriptor } from './sources.js';
+const scenarioKeywords = [
+    { scenario: 'debugging', words: ['bug', 'error', 'fail', 'failure', 'exception', 'regression', 'debug', '失败', '报错', '异常', '修复'] },
+    { scenario: 'verification', words: ['test', 'verify', 'check', 'build', '测试', '验证', '检查', '构建'] },
+    { scenario: 'handoff', words: ['handoff', 'summary', '交接', '总结', '移交'] },
+    { scenario: 'implementation', words: ['implement', 'add', 'change', 'feature', '实现', '新增', '修改', '功能'] },
+    { scenario: 'exploration', words: ['search', 'investigate', 'find', 'explore', '查找', '调查', '分析', '探索'] },
+    { scenario: 'resume', words: ['resume', 'continue', 'restore', '继续', '恢复'] },
+];
+const priorities = {
+    summary: 100,
+    pending: 95,
+    risk: 94,
+    decision: 92,
+    note: 85,
+    knowledge: 75,
+    deadend: 73,
+    activity: 70,
+};
+function clean(value) {
+    return value.normalize('NFC').trim().toLowerCase();
+}
+function stableCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function anchorFromSources(sources) {
+    return sources.anchor;
+}
+function signal(source, value, origin, confidence) {
+    return { source, value, origin, confidence };
+}
+function inferScenario(query, explicit) {
+    if (explicit)
+        return { scenario: explicit, signals: [signal('explicit-scenario', explicit, 'explicit', 'high')] };
+    if (!query)
+        return { scenario: 'resume', signals: [] };
+    const normalized = clean(query);
+    const matches = scenarioKeywords.flatMap(({ scenario, words }) => words.filter((word) => normalized.includes(clean(word))).map((word) => ({ scenario, word })));
+    if (matches.length === 0)
+        return { scenario: 'unknown', signals: [] };
+    const selected = matches[0].scenario;
+    return {
+        scenario: selected,
+        signals: matches.map(({ scenario, word }) => signal('context-state', `${scenario}:${word}`, 'deterministic', 'medium')),
+    };
+}
+function sourcePaths(record) {
+    const applicability = record.applicability;
+    if (!applicability || typeof applicability !== 'object' || Array.isArray(applicability))
+        return [];
+    const paths = applicability.paths;
+    return Array.isArray(paths) ? paths.filter((value) => typeof value === 'string') : [];
+}
+function sourceApplicability(record, descriptor) {
+    const applicability = record.applicability;
+    if (!applicability || typeof applicability !== 'object' || Array.isArray(applicability))
+        return descriptor;
+    const value = applicability;
+    const branchMode = value.branchMode === 'global' || value.branchMode === 'exact' ? value.branchMode : descriptor.applicability.branchMode;
+    const branches = Array.isArray(value.branches) ? value.branches.filter((item) => typeof item === 'string').map(clean).sort(stableCompare) : descriptor.applicability.branches;
+    const paths = sourcePaths(record).map((item) => item.replaceAll('\\', '/')).sort(stableCompare);
+    return {
+        ...descriptor,
+        scope: typeof record.scope === 'string' ? record.scope : descriptor.scope,
+        paths,
+        applicability: {
+            ...descriptor.applicability,
+            branchMode,
+            branches,
+            paths,
+            ref: descriptor.applicability.ref,
+        },
+    };
+}
+function matched(text, terms) {
+    const normalized = clean(text);
+    const matchedTerms = terms.filter((term) => normalized.includes(term));
+    return { score: matchedTerms.length, matchedTerms };
+}
+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,
+        content,
+        text,
+        priority: priorities[section],
+        score: hit.score,
+        matchedTerms: hit.matchedTerms,
+        matchedFields,
+        originalChars: text.length,
+        selectedChars: 0,
+        selected: false,
+        truncated: false,
+        level: 'summary',
+        itemHash: contentHash({ candidateId, source, content, text }),
+        tokenEstimate: estimateTokens(text),
+        expandable: true,
+    };
+}
+function applicable(candidate, intent) {
+    const source = candidate.source;
+    if (source.privacy.classification === 'unknown')
+        return { ok: false, reason: 'v2_unavailable' };
+    if (source.status && ['candidate', 'deprecated', 'rejected', 'obsolete'].includes(source.status))
+        return { ok: false, reason: 'status_not_verified' };
+    if (source.applicability.branchMode === 'unsupported')
+        return { ok: false, reason: 'unsupported_applicability' };
+    if (source.applicability.branchMode === 'exact') {
+        const branch = intent.anchor.ref ?? intent.anchor.branch ?? 'detached';
+        if (source.applicability.branches.length > 0 && !source.applicability.branches.includes(branch) && !source.applicability.branches.includes(intent.anchor.branch ?? ''))
+            return { ok: false, reason: 'applicability_mismatch' };
+        if (source.applicability.worktreeId && source.applicability.worktreeId !== intent.anchor.worktreeId)
+            return { ok: false, reason: 'applicability_mismatch' };
+        if (source.applicability.ref && source.applicability.ref !== intent.anchor.ref)
+            return { ok: false, reason: 'applicability_mismatch' };
+    }
+    if (intent.scope && source.scope && clean(intent.scope) !== clean(source.scope))
+        return { ok: false, reason: 'scope_mismatch' };
+    if (intent.paths.length > 0 && source.paths.length > 0 && !source.paths.some((path) => intent.paths.includes(path)))
+        return { ok: false, reason: 'path_mismatch' };
+    if (intent.query && ['knowledge', 'deadend'].includes(candidate.section) && candidate.matchedTerms.length === 0)
+        return { ok: false, reason: 'query_no_match' };
+    return { ok: true };
+}
+function sortCandidates(left, right) {
+    return right.priority - left.priority
+        || right.score - left.score
+        || right.matchedTerms.length - left.matchedTerms.length
+        || stableCompare(left.candidateId, right.candidateId);
+}
+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 textForSummary(label, value) {
+    return value ? `${label}: ${value}` : '';
+}
+function activityText(record) {
+    const changes = record.changes.map((change) => `${change.path} (${change.kind})`).join(', ');
+    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}`));
+        }
+    }
+    for (const note of notes) {
+        const source = sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'note', note.noteId, note.contextId, note.snapshotId, note.status, null, note.relatedFiles);
+        candidates.push(makeCandidate('note', source, note, `${note.kind}: ${note.message}`, terms, ['kind', 'message'], note.noteId));
+    }
+    for (const item of knowledge) {
+        const source = sourceApplicability(item, sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'knowledge', item.knowledgeId, item.sourceContextIds[0] ?? null, item.sourceSnapshotIds[0] ?? null, item.status, item.scope, sourcePaths(item)));
+        candidates.push(makeCandidate('knowledge', source, item, item.statement, terms, ['statement', 'kind', 'scope'], item.knowledgeId));
+    }
+    for (const item of deadends) {
+        const source = sourceApplicability(item, sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'deadend', item.deadendId, item.sourceContextId, item.sourceSnapshotId, item.status, item.scope, sourcePaths(item)));
+        candidates.push(makeCandidate('deadend', source, item, `${item.attempt}: ${item.reason}`, terms, ['attempt', 'reason', 'scope'], item.deadendId));
+    }
+    for (const item of activities) {
+        const source = sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'journal', item.eventId, null, null, null, null, item.paths);
+        candidates.push(makeCandidate('activity', source, item, activityText(item), terms, ['paths'], item.eventId));
+    }
+    return candidates;
+}
+function emptyTruncation() {
+    return { truncated: false, summary: false, pending: false, decisions: false, risks: false, notes: false, knowledge: false, deadends: false, activity: false, candidatesOmittedByBudget: 0, candidatesPartiallyTruncated: 0 };
+}
+function manifestText(selected) {
+    return selected.map((candidate) => candidate.text).join('\n');
+}
+function intentFor(sources, options, normalizedPaths) {
+    const orientation = sources.orientation;
+    const host = latestHostIntent(sources.events, sources.anchor);
+    const query = options.query?.trim() || host?.value.trim() || (orientation.status === 'ready' ? orientation.context.title : null);
+    const inferred = inferScenario(query, options.scenario);
+    const signals = [
+        ...(options.query ? [signal('explicit-query', options.query.trim(), 'explicit', 'high')] : []),
+        ...(host && !options.query ? [signal('host-prompt', host.value, 'deterministic', 'medium')] : []),
+        ...(normalizedPaths.map((value) => signal('path', value, 'explicit', 'high'))),
+        ...(inferred.signals),
+    ];
+    return {
+        schemaVersion: 1,
+        trigger: options.trigger ?? 'manual',
+        query,
+        normalizedTerms: query ? queryTerms(query).map(clean).sort(stableCompare) : [],
+        scenario: inferred.scenario,
+        scope: options.scope ?? null,
+        paths: normalizedPaths,
+        contextId: options.contextId ?? (orientation.status === 'ready' ? orientation.context.id : null),
+        anchor: anchorFromSources(sources),
+        signals,
+        requestedSections: ['summary', 'pending', 'decision', 'risk', 'note', 'knowledge', 'deadend', 'activity'],
+        budget: { unit: 'chars', total: Math.max(0, options.maxChars ?? 4000), reservedForRenderer: 0 },
+        adapter: options.adapter ?? 'generic',
+        sessionId: options.sessionId ?? null,
+        eventId: options.eventId ?? null,
+    };
+}
+export async function compileContext(startPath, options = {}) {
+    const sources = await loadCompilerSources(startPath, options);
+    const normalizedPaths = options.paths ? await filterPaths(sources.anchor.projectRoot, options.paths) : [];
+    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: 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);
+    const all = createCandidates(sources, intent, notes, knowledge, deadends, activities);
+    const excluded = [];
+    const eligible = all.filter((candidate) => {
+        const check = applicable(candidate, intent);
+        if (!check.ok)
+            excluded.push({ candidateId: candidate.candidateId, source: candidate.source, reason: check.reason ?? 'query_no_match' });
+        return check.ok;
+    }).sort(sortCandidates);
+    const selected = [];
+    const truncation = emptyTruncation();
+    const sectionStats = {};
+    let usedChars = 0;
+    for (const candidate of eligible) {
+        const separator = selected.length > 0 ? 1 : 0;
+        const available = maxChars - usedChars - separator;
+        if (available <= 0) {
+            excluded.push({ candidateId: candidate.candidateId, source: candidate.source, reason: 'budget' });
+            truncation.candidatesOmittedByBudget += 1;
+            truncation.truncated = true;
+            continue;
+        }
+        const limited = truncateText(candidate.text, available);
+        if (!limited.text) {
+            excluded.push({ candidateId: candidate.candidateId, source: candidate.source, reason: 'budget' });
+            truncation.candidatesOmittedByBudget += 1;
+            truncation.truncated = true;
+            continue;
+        }
+        const item = { ...candidate, text: limited.text, selectedChars: limited.text.length, selected: true, truncated: limited.truncated };
+        selected.push(item);
+        usedChars += separator + item.selectedChars;
+        const prior = sectionStats[item.section] ?? { allocated: maxChars, consumed: 0, truncated: false };
+        sectionStats[item.section] = { ...prior, consumed: prior.consumed + item.selectedChars + separator, truncated: prior.truncated || limited.truncated };
+        if (limited.truncated) {
+            truncation.candidatesPartiallyTruncated += 1;
+            truncation.truncated = true;
+            if (item.section === 'summary')
+                truncation.summary = true;
+            if (item.section === 'pending')
+                truncation.pending = true;
+            if (item.section === 'decision')
+                truncation.decisions = true;
+            if (item.section === 'risk')
+                truncation.risks = true;
+            if (item.section === 'note')
+                truncation.notes = true;
+            if (item.section === 'knowledge')
+                truncation.knowledge = true;
+            if (item.section === 'deadend')
+                truncation.deadends = true;
+            if (item.section === 'activity')
+                truncation.activity = true;
+        }
+    }
+    const sections = {
+        summary: selected.filter((item) => item.section === 'summary'),
+        pending: selected.filter((item) => item.section === 'pending'),
+        decision: selected.filter((item) => item.section === 'decision'),
+        risk: selected.filter((item) => item.section === 'risk'),
+        notes: selected.filter((item) => item.section === 'note'),
+        knowledge: selected.filter((item) => item.section === 'knowledge'),
+        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.6',
+        rankingVersion: 'compiler-ranking-v2',
+        status: orientation.status,
+        projectRoot: sources.anchor.projectRoot,
+        mode: orientation.explanation.mode,
+        anchor: sources.anchor,
+        intent,
+        context: orientation.context,
+        snapshot: orientation.snapshot,
+        resumeSummary: orientation.resumeSummary,
+        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: {
+            journalRead: sources.events.length > 0,
+            journalEventCount: sources.events.length,
+            selectedSourceIds: [...new Set(selected.map((item) => item.source.sourceId))].sort(stableCompare),
+            selectedEventIds: [...new Set(selected.flatMap((item) => item.source.provenance.eventId ? [item.source.provenance.eventId] : []))].sort(stableCompare),
+            fallbackReason: sources.fallbackReason,
+        },
+        text: manifestText(selected),
+    };
+}

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;