fluffy-context 0.7.7 → 1.0.0-beta.1

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

@@ -1,6 +1,6 @@
 export declare const COGNITION_LAYOUT_VERSION: "event-journal-v2";
 export type CognitionEventSource = 'cli' | 'claude-hook' | 'mcp' | 'agent' | 'git-observer' | 'fs-observer' | 'migration';
-export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'record.used' | 'usage.operation.completed' | 'projection.advanced' | 'projection.failed';
+export type CognitionEventType = 'runtime.enabled' | 'runtime.started' | 'runtime.stopped' | 'host.session.started' | 'host.prompt.submitted' | 'git.state.observed' | 'git.branch.changed' | 'git.head.changed' | 'workspace.paths.changed' | 'context.checkpoint.imported' | 'context.state.recorded' | 'note.recorded' | 'note.resolved' | 'note.absorbed' | 'knowledge.proposed' | 'knowledge.verified' | 'knowledge.deprecated' | 'knowledge.rejected' | 'deadend.proposed' | 'deadend.verified' | 'deadend.obsoleted' | 'deadend.rejected' | 'experience.recorded' | 'evolution.proposed' | 'evolution.candidate.accepted' | 'evolution.verified' | 'evolution.published' | 'evolution.rejected' | 'evolution.deprecated' | 'evolution.superseded' | 'skill.materialized' | 'recipe.materialized' | 'skill.invoked' | 'skill.outcome.recorded' | 'record.used' | 'usage.operation.completed' | 'projection.advanced' | 'projection.failed';
 export interface CognitionGitAnchor {
     worktreeId: string | null;
     branch: string | null;
@@ -61,6 +61,181 @@ export interface CognitionLifecycleTransition {
     to: 'verified' | 'deprecated' | 'rejected' | 'obsolete';
     reason?: string;
 }
+export type EvolutionArtifactKind = 'knowledge' | 'deadend' | 'skill' | 'compiler-recipe';
+export type EvolutionArtifactStatus = 'candidate' | 'verified' | 'published' | 'rejected' | 'deprecated' | 'superseded' | 'obsolete';
+export type EvolutionLineageRelation = 'derived_from' | 'supports' | 'contradicts' | 'supersedes' | 'validated_by' | 'used_for';
+export interface EvolutionEvidenceReference {
+    eventId: string;
+    relation: Extract<EvolutionLineageRelation, 'derived_from' | 'supports' | 'contradicts' | 'validated_by'>;
+}
+export interface EvolutionLineageReference {
+    entity: EvolutionArtifactKind | 'experience' | 'proposal';
+    entityId: string;
+    relation: Extract<EvolutionLineageRelation, 'supports' | 'contradicts' | 'supersedes' | 'used_for'>;
+}
+export interface Experience {
+    experienceId: string;
+    schemaVersion: 1;
+    sourceEventIds: string[];
+    sourceContextIds: string[];
+    sourceSnapshotIds: string[];
+    paths: string[];
+    git: CognitionGitAnchor;
+    privacy: {
+        classification: 'metadata' | 'redacted-text';
+        redactionCount: number;
+    };
+    extractor: {
+        id: string;
+        version: string;
+    };
+    contentHash: string;
+    summary: string;
+    createdAt: string;
+}
+export interface EvolutionProposal {
+    proposalId: string;
+    schemaVersion: 1;
+    targetKind: EvolutionArtifactKind;
+    targetId: string;
+    status: 'candidate';
+    sourceExperienceIds: string[];
+    evidence: EvolutionEvidenceReference[];
+    lineage: EvolutionLineageReference[];
+    applicability: Applicability;
+    contentHash: string;
+    summary: string;
+    extractor: {
+        id: string;
+        version: string;
+    };
+    createdAt: string;
+}
+export interface EvolutionCandidateArtifact {
+    artifactId: string;
+    schemaVersion: 1;
+    proposalId: string;
+    kind: Extract<EvolutionArtifactKind, 'skill' | 'compiler-recipe'>;
+    status: 'candidate';
+    applicability: Applicability;
+    contentHash: string;
+    lineage: EvolutionLineageReference[];
+    rationale: string;
+    createdAt: string;
+}
+export interface EvolutionProposalLifecycleEntry {
+    eventId: string;
+    occurredAt: string;
+    from: EvolutionArtifactStatus;
+    to: EvolutionArtifactStatus;
+    reason: string;
+    supersedes?: EvolutionLineageReference;
+}
+export interface EvolutionProposalState {
+    proposal: EvolutionProposal;
+    status: EvolutionArtifactStatus;
+    lifecycle: EvolutionProposalLifecycleEntry[];
+    acceptedArtifact: EvolutionCandidateArtifact | null;
+}
+export interface Skill {
+    skillId: string;
+    schemaVersion: 1;
+    proposalId: string;
+    title: string;
+    procedure: string[];
+    applicability: Applicability;
+    status: 'candidate';
+    contentHash: string;
+    lineage: EvolutionLineageReference[];
+    createdAt: string;
+}
+export interface SkillLifecycleEntry {
+    eventId: string;
+    occurredAt: string;
+    from: EvolutionArtifactStatus;
+    to: EvolutionArtifactStatus;
+    reason: string;
+    supersedes?: EvolutionLineageReference;
+}
+export interface SkillState {
+    skill: Skill;
+    status: EvolutionArtifactStatus;
+    lifecycle: SkillLifecycleEntry[];
+    invocations: SkillInvocation[];
+    outcomes: SkillOutcome[];
+}
+export type CompilerRecipeSource = 'context' | 'knowledge' | 'deadend' | 'note';
+export type CompilerRecipeSection = 'summary' | 'pending' | 'decision' | 'risk' | 'note' | 'knowledge' | 'deadend' | 'activity';
+export interface CompilerRecipe {
+    recipeId: string;
+    schemaVersion: 1;
+    proposalId: string;
+    title: string;
+    applicability: Applicability;
+    preferredSources?: CompilerRecipeSource[];
+    preferredSections?: CompilerRecipeSection[];
+    sectionBudgets?: Partial<Record<CompilerRecipeSection, number>>;
+    status: 'candidate';
+    contentHash: string;
+    lineage: EvolutionLineageReference[];
+    createdAt: string;
+}
+export interface CompilerRecipeLifecycleEntry {
+    eventId: string;
+    occurredAt: string;
+    from: EvolutionArtifactStatus;
+    to: EvolutionArtifactStatus;
+    reason: string;
+    supersedes?: EvolutionLineageReference;
+}
+export interface CompilerRecipeState {
+    recipe: CompilerRecipe;
+    status: EvolutionArtifactStatus;
+    lifecycle: CompilerRecipeLifecycleEntry[];
+}
+export interface EvolutionLifecycleTransition {
+    entity: EvolutionArtifactKind | 'proposal';
+    entityId: string;
+    from: EvolutionArtifactStatus;
+    to: EvolutionArtifactStatus;
+    reason: string;
+    supersedes?: EvolutionLineageReference;
+}
+export interface SkillInvocation {
+    invocationId: string;
+    skillId: string;
+    callerEventId: string;
+    inputHash: string;
+    occurredAt: string;
+}
+export interface SkillOutcome {
+    outcomeId: string;
+    invocationId: string;
+    callerEventId: string;
+    outcome: 'success' | 'failure' | 'partial' | 'irrelevant' | 'unknown';
+    summary: string;
+    occurredAt: string;
+}
+export interface EvidenceGraphNode {
+    nodeId: string;
+    kind: 'context' | 'snapshot' | 'experience' | 'proposal' | 'knowledge' | 'deadend' | 'skill' | 'recipe' | 'path' | 'test' | 'commit' | 'branch-worktree';
+}
+export interface EvidenceGraphEdge {
+    edgeId: string;
+    from: string;
+    to: string;
+    type: 'derived_from' | 'supports' | 'contradicts' | 'supersedes' | 'used_for' | 'observed_in' | 'changed_in' | 'co_changed_with' | 'tests';
+    sourceEventIds: string[];
+    derivationVersion: string;
+    occurredAt: string;
+    confidence?: number;
+}
+export interface EvidenceGraphProjection {
+    schemaVersion: 1;
+    derivationVersion: 'evidence-graph-v1';
+    nodes: EvidenceGraphNode[];
+    edges: EvidenceGraphEdge[];
+}
 export interface CognitionUseFeedback {
     feedbackId: string;
     entity: 'knowledge' | 'deadend';
@@ -177,6 +352,11 @@ export interface CognitionProjection {
     notes: Record<string, CognitionRecordPayload>;
     knowledge: Record<string, CognitionRecordPayload>;
     deadends: Record<string, CognitionRecordPayload>;
+    experiences: Record<string, Experience>;
+    proposals: Record<string, EvolutionProposalState>;
+    skills: Record<string, SkillState>;
+    recipes: Record<string, CompilerRecipeState>;
+    evidenceGraph: EvidenceGraphProjection;
     workspaces: Record<string, BranchWorkspace>;
 }
 export interface RuntimeLease {

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

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

package/dist/src/compiler/compile.js

@@ -4,6 +4,7 @@ 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 { graphOrdering } from './graph.js';
 import { latestHostIntent, loadCompilerSources, sourceDescriptor } from './sources.js';
 const scenarioKeywords = [
     { scenario: 'debugging', words: ['bug', 'error', 'fail', 'failure', 'exception', 'regression', 'debug', '失败', '报错', '异常', '修复'] },
@@ -137,6 +138,50 @@ function sortCandidates(left, right) {
         || right.matchedTerms.length - left.matchedTerms.length
         || stableCompare(left.candidateId, right.candidateId);
 }
+function recipeParticipation(sources) {
+    const recipe = sources.recipe?.recipe;
+    if (!recipe)
+        return undefined;
+    return {
+        recipeId: recipe.recipeId,
+        contentHash: recipe.contentHash,
+        interpreterVersion: 'recipe-interpreter-v1',
+        preferredSources: [...(recipe.preferredSources ?? [])],
+        preferredSections: [...(recipe.preferredSections ?? [])],
+        sectionBudgets: { ...(recipe.sectionBudgets ?? {}) },
+    };
+}
+function sourcePreference(candidate, recipe) {
+    const source = candidate.source.kind === 'current-context' ? 'context' : candidate.source.kind;
+    const index = recipe.preferredSources.indexOf(source);
+    return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+}
+function sectionPreference(candidate, recipe) {
+    const index = recipe.preferredSections.indexOf(candidate.section);
+    return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+}
+function recipeApplicable(recipe, sources, paths) {
+    const applicability = sources.recipe.recipe.applicability;
+    if (applicability.branchMode === 'global')
+        return true;
+    if (applicability.branchMode !== 'exact')
+        return false;
+    const branch = sources.anchor.ref ?? sources.anchor.branch ?? 'detached';
+    if (applicability.branches?.length && !applicability.branches.includes(branch) && !applicability.branches.includes(sources.anchor.branch ?? ''))
+        return false;
+    if (applicability.sourceCommit && applicability.sourceCommit !== sources.anchor.head)
+        return false;
+    if (paths.length > 0 && applicability.paths?.length && !applicability.paths.some((path) => paths.includes(path.replaceAll('\\', '/'))))
+        return false;
+    return recipe.recipeId === sources.recipe.recipe.recipeId;
+}
+function sortWithRecipe(recipe) {
+    if (!recipe)
+        return sortCandidates;
+    return (left, right) => sourcePreference(left, recipe) - sourcePreference(right, recipe)
+        || sectionPreference(left, recipe) - sectionPreference(right, recipe)
+        || sortCandidates(left, right);
+}
 function truncateText(value, maxChars) {
     if (value.length <= maxChars)
         return { text: value, truncated: false };
@@ -152,32 +197,32 @@ function activityText(record) {
     return `activity: ${changes}`;
 }
 function createCandidates(sources, intent, notes, knowledge, deadends, activities) {
-    if (sources.orientation.status !== 'ready')
-        return [];
-    const { context, snapshot, resumeSummary } = sources.orientation;
     const terms = intent.normalizedTerms;
     const candidates = [];
-    const contextSource = sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'current-context', context.id, context.id, snapshot.snapshotId, context.status, null, resumeSummary.relatedFiles);
-    const summaryFields = [
-        ['title', context.title, 'summary'],
-        ['progressSummary', resumeSummary.progressSummary, 'summary'],
-        ['lastError', resumeSummary.lastError, 'risk'],
-    ];
-    for (const [field, value, section] of summaryFields) {
-        const text = textForSummary(field, value);
-        if (text)
-            candidates.push(makeCandidate(section, contextSource, { field, value }, text, terms, [field], field));
-    }
-    const listFields = [
-        ['pendingTasks', resumeSummary.pendingTasks, 'pending'],
-        ['completed', resumeSummary.completed, 'summary'],
-        ['decisions', resumeSummary.decisions, 'decision'],
-        ['risks', resumeSummary.risks, 'risk'],
-        ['relatedFiles', resumeSummary.relatedFiles, 'summary'],
-    ];
-    for (const [field, values, section] of listFields) {
-        for (const [index, value] of values.entries()) {
-            candidates.push(makeCandidate(section, contextSource, { field, value }, `${field}: ${value}`, terms, [field], `${field}:${index}`));
+    if (sources.orientation.status === 'ready') {
+        const { context, snapshot, resumeSummary } = sources.orientation;
+        const contextSource = sourceDescriptor(sources.anchor.projectRoot, sources.anchor, sources.events, 'current-context', context.id, context.id, snapshot.snapshotId, context.status, null, resumeSummary.relatedFiles);
+        const summaryFields = [
+            ['title', context.title, 'summary'],
+            ['progressSummary', resumeSummary.progressSummary, 'summary'],
+            ['lastError', resumeSummary.lastError, 'risk'],
+        ];
+        for (const [field, value, section] of summaryFields) {
+            const text = textForSummary(field, value);
+            if (text)
+                candidates.push(makeCandidate(section, contextSource, { field, value }, text, terms, [field], field));
+        }
+        const listFields = [
+            ['pendingTasks', resumeSummary.pendingTasks, 'pending'],
+            ['completed', resumeSummary.completed, 'summary'],
+            ['decisions', resumeSummary.decisions, 'decision'],
+            ['risks', resumeSummary.risks, 'risk'],
+            ['relatedFiles', resumeSummary.relatedFiles, 'summary'],
+        ];
+        for (const [field, values, section] of listFields) {
+            for (const [index, value] of values.entries()) {
+                candidates.push(makeCandidate(section, contextSource, { field, value }, `${field}: ${value}`, terms, [field], `${field}:${index}`));
+            }
         }
     }
     for (const note of notes) {
@@ -237,11 +282,14 @@ 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 recipe = recipeParticipation(sources);
+    if (recipe && !recipeApplicable(recipe, sources, normalizedPaths))
+        throw new Error(`compiler recipe is not applicable: ${recipe.recipeId}`);
     const orientation = sources.orientation;
     const maxChars = intent.budget.total;
     const notes = orientation.status === 'ready' ? (await listNotes(sources.anchor.projectRoot, { contextId: orientation.context.id, openOnly: true, limit: options.noteLimit ?? 50, maxChars: Number.MAX_SAFE_INTEGER })).filter((note) => orientation.notes.some((selected) => selected.noteId === note.noteId)) : [];
-    const knowledge = orientation.status === 'ready' && intent.query ? await listKnowledge(sources.anchor.projectRoot, true) : [];
-    const deadends = orientation.status === 'ready' && intent.query ? await listDeadends(sources.anchor.projectRoot, true) : [];
+    const knowledge = intent.query ? await listKnowledge(sources.anchor.projectRoot, true) : [];
+    const deadends = intent.query ? await listDeadends(sources.anchor.projectRoot, true) : [];
     const activities = await extractActivity(sources.anchor.projectRoot, sources.events, sources.anchor, sources.workspace, options.activityLimit ?? 20);
     const all = createCandidates(sources, intent, notes, knowledge, deadends, activities);
     const excluded = [];
@@ -250,14 +298,31 @@ export async function compileContext(startPath, options = {}) {
         if (!check.ok)
             excluded.push({ candidateId: candidate.candidateId, source: candidate.source, reason: check.reason ?? 'query_no_match' });
         return check.ok;
-    }).sort(sortCandidates);
+    }).sort(sortWithRecipe(recipe));
+    const graph = options.graphHops === undefined ? undefined : graphOrdering(sources.evidenceGraph, options.graphHops, sources.anchor, eligible);
+    if (graph) {
+        eligible.sort((left, right) => {
+            if (recipe) {
+                const sourceOrder = sourcePreference(left, recipe) - sourcePreference(right, recipe);
+                if (sourceOrder)
+                    return sourceOrder;
+                const sectionOrder = sectionPreference(left, recipe) - sectionPreference(right, recipe);
+                if (sectionOrder)
+                    return sectionOrder;
+            }
+            return (graph.distanceFor(left) ?? Number.MAX_SAFE_INTEGER) - (graph.distanceFor(right) ?? Number.MAX_SAFE_INTEGER)
+                || sortCandidates(left, right);
+        });
+    }
     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;
+        const sectionBudget = recipe?.sectionBudgets[candidate.section] ?? maxChars;
+        const consumedInSection = sectionStats[candidate.section]?.consumed ?? 0;
+        const available = Math.min(maxChars - usedChars - separator, sectionBudget - consumedInSection - separator);
         if (available <= 0) {
             excluded.push({ candidateId: candidate.candidateId, source: candidate.source, reason: 'budget' });
             truncation.candidatesOmittedByBudget += 1;
@@ -274,7 +339,7 @@ export async function compileContext(startPath, options = {}) {
         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 };
+        const prior = sectionStats[item.section] ?? { allocated: recipe?.sectionBudgets[item.section] ?? 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;
@@ -309,8 +374,9 @@ export async function compileContext(startPath, options = {}) {
     };
     const tokenEstimate = estimateTokens(manifestText(selected));
     const selectedItemHashes = selected.map((item) => item.itemHash);
+    const status = orientation.status === 'ready' || selected.length > 0 ? 'ready' : 'no_context';
     const manifestHash = rebuildManifestHash({
-        status: orientation.status,
+        status,
         projectRoot: sources.anchor.projectRoot,
         mode: orientation.explanation.mode,
         anchor: sources.anchor,
@@ -318,12 +384,14 @@ export async function compileContext(startPath, options = {}) {
         selected,
         budget: { requested: intent.budget, usedChars, remainingChars: Math.max(0, maxChars - usedChars), sections: sectionStats },
         truncation,
+        ...(recipe ? { recipe } : {}),
+        ...(graph ? { graph: graph.participation } : {}),
     });
     return {
         schemaVersion: 1,
         compilerVersion: '0.7.7',
         rankingVersion: 'compiler-ranking-v2',
-        status: orientation.status,
+        status,
         projectRoot: sources.anchor.projectRoot,
         mode: orientation.explanation.mode,
         anchor: sources.anchor,
@@ -348,6 +416,8 @@ export async function compileContext(startPath, options = {}) {
             selectedEventIds: [...new Set(selected.flatMap((item) => item.source.provenance.eventId ? [item.source.provenance.eventId] : []))].sort(stableCompare),
             fallbackReason: sources.fallbackReason,
         },
+        ...(recipe ? { recipe } : {}),
+        ...(graph ? { graph: graph.participation } : {}),
         text: manifestText(selected),
     };
 }

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

@@ -0,0 +1,7 @@
+import type { EvidenceGraphProjection } from '../cognition/types.js';
+import type { ContextAnchor, ContextCandidate, ContextGraphParticipation } from './types.js';
+export interface GraphOrdering {
+    participation: ContextGraphParticipation;
+    distanceFor(candidate: ContextCandidate): number | null;
+}
+export declare function graphOrdering(graph: EvidenceGraphProjection | null, hops: 0 | 1 | 2, anchor: ContextAnchor, eligible: ContextCandidate[]): GraphOrdering;

package/dist/src/compiler/graph.js

@@ -0,0 +1,117 @@
+import { EVIDENCE_GRAPH_DERIVATION_VERSION, workspaceNodeId } from '../cognition/evidence-graph.js';
+import { contentHash } from './identity.js';
+const MAX_VISITED_NODES = 256;
+const MAX_TRAVERSED_EDGES = 512;
+const MAX_FAN_OUT = 32;
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function candidateNodeId(candidate) {
+    if (candidate.section === 'knowledge')
+        return `knowledge:${candidate.source.entityId}`;
+    if (candidate.section === 'deadend')
+        return `deadend:${candidate.source.entityId}`;
+    if (candidate.source.kind === 'current-context')
+        return `context:${candidate.source.contextId ?? candidate.source.entityId}`;
+    return null;
+}
+function validGraph(graph) {
+    if (graph.schemaVersion !== 1 || graph.derivationVersion !== EVIDENCE_GRAPH_DERIVATION_VERSION || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges))
+        return false;
+    const nodeKinds = new Set(['context', 'snapshot', 'experience', 'proposal', 'knowledge', 'deadend', 'skill', 'recipe', 'path', 'test', 'commit', 'branch-worktree']);
+    const edgeTypes = new Set(['derived_from', 'supports', 'contradicts', 'supersedes', 'used_for', 'observed_in', 'changed_in', 'co_changed_with', 'tests']);
+    const nodes = new Set();
+    for (const node of graph.nodes) {
+        if (!node || typeof node.nodeId !== 'string' || node.nodeId.length === 0 || !nodeKinds.has(node.kind) || nodes.has(node.nodeId))
+            return false;
+        nodes.add(node.nodeId);
+    }
+    const edges = new Set();
+    for (const edge of graph.edges) {
+        if (!edge || typeof edge.edgeId !== 'string' || edge.edgeId.length === 0 || edges.has(edge.edgeId) || !nodes.has(edge.from) || !nodes.has(edge.to) || !edgeTypes.has(edge.type) || edge.derivationVersion !== EVIDENCE_GRAPH_DERIVATION_VERSION || typeof edge.occurredAt !== 'string' || edge.occurredAt.length === 0 || !Array.isArray(edge.sourceEventIds) || edge.sourceEventIds.some((id) => typeof id !== 'string' || !id) || (edge.confidence !== undefined && (typeof edge.confidence !== 'number' || !Number.isFinite(edge.confidence) || edge.confidence < 0 || edge.confidence > 1)))
+            return false;
+        edges.add(edge.edgeId);
+    }
+    return true;
+}
+function graphProjectionHash(graph) {
+    return contentHash(graph);
+}
+export function graphOrdering(graph, hops, anchor, eligible) {
+    const empty = (fallbackReason, seedNodeIds = []) => ({
+        participation: {
+            derivationVersion: EVIDENCE_GRAPH_DERIVATION_VERSION,
+            projectionHash: null,
+            hops,
+            seedNodeIds,
+            selectedNodeIds: [],
+            selectedEdgeIds: [],
+            fallbackReason,
+        },
+        distanceFor: () => null,
+    });
+    if (!graph)
+        return empty('graph-unavailable');
+    if (!validGraph(graph))
+        return empty('graph-invalid');
+    const projectionHash = graphProjectionHash(graph);
+    const nodes = new Set(graph.nodes.map((node) => node.nodeId));
+    const candidateNodes = new Map(eligible.map((candidate) => [candidate.candidateId, candidateNodeId(candidate)]));
+    const seedNodeIds = [...new Set([
+            workspaceNodeId(anchor),
+            ...eligible.filter((candidate) => candidate.source.kind === 'current-context').map(candidateNodeId).filter((node) => node !== null),
+        ].filter((node) => nodes.has(node)))].sort(compare);
+    if (seedNodeIds.length === 0)
+        return empty('graph-no-seeds');
+    if (hops === 0) {
+        const distances = new Map(seedNodeIds.map((node) => [node, 0]));
+        return {
+            participation: { derivationVersion: EVIDENCE_GRAPH_DERIVATION_VERSION, projectionHash, hops, seedNodeIds, selectedNodeIds: seedNodeIds, selectedEdgeIds: [], fallbackReason: null },
+            distanceFor: (candidate) => {
+                const node = candidateNodes.get(candidate.candidateId);
+                return node ? distances.get(node) ?? null : null;
+            },
+        };
+    }
+    const adjacency = new Map();
+    for (const edge of graph.edges) {
+        adjacency.set(edge.from, [...(adjacency.get(edge.from) ?? []), edge]);
+        adjacency.set(edge.to, [...(adjacency.get(edge.to) ?? []), edge]);
+    }
+    for (const edges of adjacency.values())
+        edges.sort((left, right) => compare(left.edgeId, right.edgeId));
+    const distances = new Map(seedNodeIds.map((node) => [node, 0]));
+    const queue = [...seedNodeIds];
+    const selectedEdgeIds = new Set();
+    while (queue.length > 0 && distances.size < MAX_VISITED_NODES && selectedEdgeIds.size < MAX_TRAVERSED_EDGES) {
+        const node = queue.shift();
+        const distance = distances.get(node);
+        if (distance >= hops)
+            continue;
+        for (const edge of (adjacency.get(node) ?? []).slice(0, MAX_FAN_OUT)) {
+            if (selectedEdgeIds.size >= MAX_TRAVERSED_EDGES)
+                break;
+            const adjacent = edge.from === node ? edge.to : edge.from;
+            selectedEdgeIds.add(edge.edgeId);
+            if (!distances.has(adjacent) && distances.size < MAX_VISITED_NODES) {
+                distances.set(adjacent, distance + 1);
+                queue.push(adjacent);
+            }
+        }
+    }
+    return {
+        participation: {
+            derivationVersion: EVIDENCE_GRAPH_DERIVATION_VERSION,
+            projectionHash,
+            hops,
+            seedNodeIds,
+            selectedNodeIds: [...distances.keys()].sort(compare),
+            selectedEdgeIds: [...selectedEdgeIds].sort(compare),
+            fallbackReason: null,
+        },
+        distanceFor: (candidate) => {
+            const node = candidateNodes.get(candidate.candidateId);
+            return node ? distances.get(node) ?? null : null;
+        },
+    };
+}