fluffy-context 0.7.6 → 0.8.0

package/dist/src/cognition/recipes.js

@@ -0,0 +1,149 @@
+import crypto from 'node:crypto';
+import { readGitWorktreeState } from '../git/git-adapter.js';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { inspectEvolutionProposal } from './evolution.js';
+import { appendEvent, readJournal } from './journal.js';
+import { v2Enabled } from './orient.js';
+import { projectEvents, rebuildProjections } from './projections.js';
+const sources = new Set(['context', 'knowledge', 'deadend', 'note']);
+const sections = new Set(['summary', 'pending', 'decision', 'risk', 'note', 'knowledge', 'deadend', 'activity']);
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(',')}}`;
+}
+function hash(value) {
+    return crypto.createHash('sha256').update(canonical(value)).digest('hex');
+}
+function requireText(value, label) {
+    const text = value.trim();
+    if (!text)
+        throw new Error(`${label} must not be empty`);
+    return text;
+}
+function preferences(value, allowed, label) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > allowed.size || value.some((item) => !allowed.has(item)) || new Set(value).size !== value.length)
+        throw new Error(`invalid recipe ${label}`);
+    return [...value];
+}
+function budgets(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.entries(value).some(([section, budget]) => !sections.has(section) || !Number.isSafeInteger(budget) || budget < 0 || budget > 100_000))
+        throw new Error('invalid recipe section budgets');
+    return Object.fromEntries(Object.entries(value).sort());
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function eventRecord(event) {
+    const payload = event.payload;
+    return isRecord(payload.record) ? payload.record : null;
+}
+function matchingRecord(record, expected, ignored = []) {
+    const actual = { ...record };
+    for (const field of ignored)
+        delete actual[field];
+    return canonical(actual) === canonical(expected);
+}
+function anchor(git) {
+    return { worktreeId: git.worktreeId, branch: git.branch, ref: git.ref, head: git.commit };
+}
+async function enabledProject(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!await v2Enabled(projectRoot))
+        throw new Error('recipes require an enabled v2 runtime');
+    return projectRoot;
+}
+export async function listRecipes(startPath) {
+    const projectRoot = await enabledProject(startPath);
+    return Object.values(projectEvents(await readJournal(projectRoot)).recipes).sort((left, right) => left.recipe.recipeId.localeCompare(right.recipe.recipeId));
+}
+export async function inspectRecipe(startPath, recipeId) {
+    const id = requireText(recipeId, 'recipe ID');
+    const recipe = (await listRecipes(startPath)).find((item) => item.recipe.recipeId === id);
+    if (!recipe)
+        throw new Error(`recipe not found: ${id}`);
+    return recipe;
+}
+export async function materializeRecipe(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const proposalId = requireText(input.proposalId, 'proposal ID');
+    const proposalState = await inspectEvolutionProposal(projectRoot, proposalId);
+    if (proposalState.proposal.targetKind !== 'compiler-recipe' || proposalState.status !== 'candidate')
+        throw new Error(`recipe materialization requires a candidate compiler-recipe proposal: ${proposalId}`);
+    const artifact = proposalState.acceptedArtifact;
+    if (!artifact || artifact.kind !== 'compiler-recipe' || artifact.proposalId !== proposalId)
+        throw new Error(`recipe materialization requires an accepted compiler-recipe candidate: ${proposalId}`);
+    const title = requireText(input.title, 'recipe title');
+    const preferredSources = preferences(input.preferredSources, sources, 'source preferences');
+    const preferredSections = preferences(input.preferredSections, sections, 'section preferences');
+    const sectionBudgets = budgets(input.sectionBudgets);
+    const basis = { proposalId, title, applicability: artifact.applicability, preferredSources, preferredSections, sectionBudgets, lineage: artifact.lineage, proposalContentHash: artifact.contentHash };
+    const expected = {
+        recipeId: artifact.artifactId,
+        schemaVersion: 1,
+        proposalId,
+        title,
+        applicability: artifact.applicability,
+        ...(preferredSources ? { preferredSources } : {}),
+        ...(preferredSections ? { preferredSections } : {}),
+        ...(sectionBudgets ? { sectionBudgets } : {}),
+        status: 'candidate',
+        contentHash: hash(basis),
+        lineage: artifact.lineage,
+    };
+    const existing = (await readJournal(projectRoot)).find((event) => event.type === 'recipe.materialized' && eventRecord(event)?.recipeId === expected.recipeId);
+    if (existing) {
+        const record = eventRecord(existing);
+        if (!matchingRecord(record, expected, ['createdAt']))
+            throw new Error(`Recipe already materialized with conflicting content: ${expected.recipeId}`);
+        return { materialized: false, recipeId: expected.recipeId, eventId: existing.eventId };
+    }
+    const recipe = { ...expected, createdAt: new Date().toISOString() };
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, {
+        type: 'recipe.materialized', source: { kind: 'cli' }, idempotencyKey: `recipe-materialized:${recipe.recipeId}:${recipe.contentHash}`,
+        git: anchor(git), payload: { record: recipe },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { materialized: result.appended, recipeId: recipe.recipeId, eventId: result.event.eventId };
+}
+export async function transitionRecipe(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const recipe = await inspectRecipe(projectRoot, input.recipeId);
+    const rationale = requireText(input.rationale, 'recipe rationale');
+    if (input.to === 'superseded' && !input.supersedes)
+        throw new Error('superseding a Recipe requires lineage');
+    const request = { entity: 'compiler-recipe', entityId: recipe.recipe.recipeId, to: input.to, reason: rationale, ...(input.supersedes ? { supersedes: input.supersedes } : {}) };
+    const existing = (await readJournal(projectRoot)).find((event) => {
+        if (!event.type.startsWith('evolution.'))
+            return false;
+        const transition = event.payload.transition;
+        return isRecord(transition) && matchingRecord(transition, request, ['from']);
+    });
+    if (existing)
+        return { transitioned: false, eventId: existing.eventId };
+    if (!((recipe.status === 'candidate' && (input.to === 'verified' || input.to === 'deprecated'))
+        || (recipe.status === 'verified' && (input.to === 'published' || input.to === 'deprecated' || input.to === 'superseded'))
+        || (recipe.status === 'published' && (input.to === 'deprecated' || input.to === 'superseded')))) {
+        throw new Error(`invalid Recipe transition: ${recipe.status} to ${input.to}`);
+    }
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, {
+        type: `evolution.${input.to}`,
+        source: { kind: 'cli' },
+        idempotencyKey: `recipe-transition:${recipe.recipe.recipeId}:${input.to}:${hash({ rationale, supersedes: input.supersedes }).slice(0, 16)}`,
+        git: anchor(git),
+        payload: { transition: { ...request, from: recipe.status } },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { transitioned: result.appended, eventId: result.event.eventId };
+}

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

@@ -0,0 +1,45 @@
+import type { EvolutionArtifactStatus, EvolutionLineageReference, SkillOutcome, SkillState } from './types.js';
+export interface MaterializeSkillInput {
+    proposalId: string;
+    title: string;
+    procedure: string[];
+}
+export interface TransitionSkillInput {
+    skillId: string;
+    to: Extract<EvolutionArtifactStatus, 'verified' | 'published' | 'deprecated' | 'superseded'>;
+    rationale: string;
+    supersedes?: EvolutionLineageReference;
+}
+export interface RecordSkillInvocationInput {
+    skillId: string;
+    invocationId: string;
+    callerEventId: string;
+    inputHash: string;
+}
+export interface RecordSkillOutcomeInput {
+    skillId: string;
+    invocationId: string;
+    outcomeId: string;
+    callerEventId: string;
+    outcome: SkillOutcome['outcome'];
+    summary: string;
+}
+export declare function listSkills(startPath?: string): Promise<SkillState[]>;
+export declare function inspectSkill(startPath: string | undefined, skillId: string): Promise<SkillState>;
+export declare function materializeSkill(startPath: string | undefined, input: MaterializeSkillInput): Promise<{
+    materialized: boolean;
+    skillId: string;
+    eventId: string;
+}>;
+export declare function transitionSkill(startPath: string | undefined, input: TransitionSkillInput): Promise<{
+    transitioned: boolean;
+    eventId: string;
+}>;
+export declare function recordSkillInvocation(startPath: string | undefined, input: RecordSkillInvocationInput): Promise<{
+    recorded: boolean;
+    eventId: string;
+}>;
+export declare function recordSkillOutcome(startPath: string | undefined, input: RecordSkillOutcomeInput): Promise<{
+    recorded: boolean;
+    eventId: string;
+}>;

package/dist/src/cognition/skills.js

@@ -0,0 +1,184 @@
+import crypto from 'node:crypto';
+import { readGitWorktreeState } from '../git/git-adapter.js';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { appendEvent, readJournal } from './journal.js';
+import { inspectEvolutionProposal } from './evolution.js';
+import { v2Enabled } from './orient.js';
+import { projectEvents, rebuildProjections } from './projections.js';
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(',')}}`;
+}
+function hash(value) {
+    return crypto.createHash('sha256').update(canonical(value)).digest('hex');
+}
+function requireText(value, label) {
+    const text = value.trim();
+    if (!text)
+        throw new Error(`${label} must not be empty`);
+    return text;
+}
+function requireProcedure(procedure) {
+    if (!Array.isArray(procedure) || procedure.length === 0 || procedure.length > 32)
+        throw new Error('skill procedure must contain 1 to 32 steps');
+    return procedure.map((step) => requireText(step, 'skill procedure step'));
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function eventRecord(event) {
+    const payload = event.payload;
+    return isRecord(payload.record) ? payload.record : null;
+}
+function matchingRecord(record, expected, ignored = []) {
+    const actual = { ...record };
+    for (const field of ignored)
+        delete actual[field];
+    return canonical(actual) === canonical(expected);
+}
+function anchor(git) {
+    return { worktreeId: git.worktreeId, branch: git.branch, ref: git.ref, head: git.commit };
+}
+async function enabledProject(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!await v2Enabled(projectRoot))
+        throw new Error('skills require an enabled v2 runtime');
+    return projectRoot;
+}
+export async function listSkills(startPath) {
+    const projectRoot = await enabledProject(startPath);
+    return Object.values(projectEvents(await readJournal(projectRoot)).skills).sort((left, right) => left.skill.skillId.localeCompare(right.skill.skillId));
+}
+export async function inspectSkill(startPath, skillId) {
+    const id = requireText(skillId, 'skill ID');
+    const skill = (await listSkills(startPath)).find((item) => item.skill.skillId === id);
+    if (!skill)
+        throw new Error(`skill not found: ${id}`);
+    return skill;
+}
+export async function materializeSkill(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const proposalId = requireText(input.proposalId, 'proposal ID');
+    const proposalState = await inspectEvolutionProposal(projectRoot, proposalId);
+    if (proposalState.proposal.targetKind !== 'skill' || proposalState.status !== 'candidate')
+        throw new Error(`skill materialization requires a candidate Skill proposal: ${proposalId}`);
+    const artifact = proposalState.acceptedArtifact;
+    if (!artifact || artifact.kind !== 'skill' || artifact.proposalId !== proposalId)
+        throw new Error(`skill materialization requires an accepted Skill candidate: ${proposalId}`);
+    const title = requireText(input.title, 'skill title');
+    const procedure = requireProcedure(input.procedure);
+    const basis = { proposalId, title, procedure, applicability: artifact.applicability, lineage: artifact.lineage, proposalContentHash: artifact.contentHash };
+    const expected = {
+        skillId: artifact.artifactId,
+        schemaVersion: 1,
+        proposalId,
+        title,
+        procedure,
+        applicability: artifact.applicability,
+        status: 'candidate',
+        contentHash: hash(basis),
+        lineage: artifact.lineage,
+    };
+    const existing = (await readJournal(projectRoot)).find((event) => event.type === 'skill.materialized' && eventRecord(event)?.skillId === expected.skillId);
+    if (existing) {
+        const record = eventRecord(existing);
+        if (!matchingRecord(record, expected, ['createdAt']))
+            throw new Error(`Skill already materialized with conflicting content: ${expected.skillId}`);
+        return { materialized: false, skillId: expected.skillId, eventId: existing.eventId };
+    }
+    const skill = { ...expected, createdAt: new Date().toISOString() };
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, {
+        type: 'skill.materialized', source: { kind: 'cli' }, idempotencyKey: `skill-materialized:${skill.skillId}:${skill.contentHash}`,
+        git: anchor(git), payload: { record: skill },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { materialized: result.appended, skillId: skill.skillId, eventId: result.event.eventId };
+}
+export async function transitionSkill(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const skill = await inspectSkill(projectRoot, input.skillId);
+    const rationale = requireText(input.rationale, 'skill rationale');
+    if (input.to === 'superseded' && !input.supersedes)
+        throw new Error('superseding a Skill requires lineage');
+    const request = { entity: 'skill', entityId: skill.skill.skillId, to: input.to, reason: rationale, ...(input.supersedes ? { supersedes: input.supersedes } : {}) };
+    const existing = (await readJournal(projectRoot)).find((event) => {
+        if (!event.type.startsWith('evolution.'))
+            return false;
+        const transition = event.payload.transition;
+        return isRecord(transition) && matchingRecord(transition, request, ['from']);
+    });
+    if (existing)
+        return { transitioned: false, eventId: existing.eventId };
+    if (!((skill.status === 'candidate' && (input.to === 'verified' || input.to === 'deprecated'))
+        || (skill.status === 'verified' && (input.to === 'published' || input.to === 'deprecated' || input.to === 'superseded'))
+        || (skill.status === 'published' && (input.to === 'deprecated' || input.to === 'superseded')))) {
+        throw new Error(`invalid Skill transition: ${skill.status} to ${input.to}`);
+    }
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, {
+        type: `evolution.${input.to}`,
+        source: { kind: 'cli' },
+        idempotencyKey: `skill-transition:${skill.skill.skillId}:${input.to}:${hash({ rationale, supersedes: input.supersedes }).slice(0, 16)}`,
+        git: anchor(git),
+        payload: { transition: { ...request, from: skill.status } },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { transitioned: result.appended, eventId: result.event.eventId };
+}
+export async function recordSkillInvocation(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const skill = await inspectSkill(projectRoot, input.skillId);
+    const invocation = {
+        invocationId: requireText(input.invocationId, 'invocation ID'),
+        skillId: skill.skill.skillId,
+        callerEventId: requireText(input.callerEventId, 'caller event ID'),
+        inputHash: requireText(input.inputHash, 'skill input hash'),
+    };
+    const existing = (await readJournal(projectRoot)).find((event) => event.type === 'skill.invoked' && eventRecord(event)?.invocationId === invocation.invocationId);
+    if (existing) {
+        if (!matchingRecord(eventRecord(existing), invocation, ['occurredAt']))
+            throw new Error(`Skill invocation ID already exists: ${invocation.invocationId}`);
+        return { recorded: false, eventId: existing.eventId };
+    }
+    if (skill.status !== 'published')
+        throw new Error(`Skill invocation requires a published Skill: ${skill.skill.skillId}`);
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, { type: 'skill.invoked', source: { kind: 'cli' }, idempotencyKey: `skill-invocation:${invocation.invocationId}`, git: anchor(git), payload: { record: { ...invocation, occurredAt: new Date().toISOString() } } });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { recorded: result.appended, eventId: result.event.eventId };
+}
+export async function recordSkillOutcome(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const skill = await inspectSkill(projectRoot, input.skillId);
+    const invocationId = requireText(input.invocationId, 'invocation ID');
+    const outcome = {
+        outcomeId: requireText(input.outcomeId, 'outcome ID'),
+        invocationId,
+        callerEventId: requireText(input.callerEventId, 'caller event ID'),
+        outcome: input.outcome,
+        summary: requireText(input.summary, 'skill outcome summary'),
+    };
+    const existing = (await readJournal(projectRoot)).find((event) => event.type === 'skill.outcome.recorded' && eventRecord(event)?.outcomeId === outcome.outcomeId);
+    if (existing) {
+        if (!matchingRecord(eventRecord(existing), outcome, ['occurredAt']))
+            throw new Error(`Skill outcome ID already exists: ${outcome.outcomeId}`);
+        return { recorded: false, eventId: existing.eventId };
+    }
+    if (!skill.invocations.some((item) => item.invocationId === invocationId))
+        throw new Error(`Skill invocation not found: ${invocationId}`);
+    if (skill.outcomes.some((item) => item.invocationId === invocationId))
+        throw new Error(`Skill outcome already recorded: ${invocationId}`);
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, { type: 'skill.outcome.recorded', source: { kind: 'cli' }, idempotencyKey: `skill-outcome:${outcome.outcomeId}`, git: anchor(git), payload: { record: { ...outcome, occurredAt: new Date().toISOString() } } });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { recorded: result.appended, eventId: result.event.eventId };
+}

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' | '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' | 'projection.advanced' | 'projection.failed';
+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' | '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,12 +61,201 @@ 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';
     entityId: string;
     outcome: 'used';
 }
+export interface UsageOperationCompletedPayload {
+    operation: 'orient' | 'compile' | 'expand' | 'resume';
+    interface: 'cli' | 'mcp' | 'agent' | 'hook';
+    success: boolean;
+    durationMs: number;
+    inputChars: number;
+    outputChars: number;
+    inputBytes: number;
+    outputBytes: number;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedMethod: 'chars-div-four';
+    errorClass?: string;
+}
 export interface CognitionRetrievalEntry {
     entity: 'knowledge' | 'deadend';
     entityId: string;
@@ -163,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.d.ts

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