fluffy-context 0.7.7 → 1.0.0-beta.1

package/dist/src/cognition/projections.js

@@ -2,9 +2,10 @@ import crypto from 'node:crypto';
 import { readdir, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { atomicWriteJson } from '../storage/atomic-write.js';
-import { cognitionBranchesDirectory, cognitionContextsProjectionPath, cognitionDeadendsProjectionPath, cognitionKnowledgeProjectionPath, cognitionNotesProjectionPath, cognitionProjectionCursorPath, cognitionRetrievalProjectionPath, } from '../storage/layout.js';
+import { cognitionBranchesDirectory, cognitionContextsProjectionPath, cognitionDeadendsProjectionPath, cognitionExperiencesProjectionPath, cognitionEvidenceGraphProjectionPath, cognitionKnowledgeProjectionPath, cognitionNotesProjectionPath, cognitionProjectionCursorPath, cognitionProposalsProjectionPath, cognitionRetrievalProjectionPath, cognitionSkillsProjectionPath, cognitionRecipesProjectionPath, } from '../storage/layout.js';
 import { readJournal } from './journal.js';
 import { buildRetrievalProjection } from './retrieval.js';
+import { buildEvidenceGraph } from './evidence-graph.js';
 export function workspaceKey(anchor) {
     return crypto.createHash('sha256')
         .update(`${anchor.worktreeId ?? 'default'}\0${anchor.ref ?? anchor.branch ?? 'detached'}`)
@@ -48,6 +49,55 @@ function pathFocusFrom(event) {
         .sort()
         .slice(-100);
 }
+function evolutionRecord(event) {
+    const payload = event.payload;
+    return isRecord(payload.record) ? payload.record : null;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function lifecycleEntry(event) {
+    const payload = event.payload;
+    const transition = payload.transition;
+    if (!isRecord(transition) || transition.entity !== 'proposal' || typeof transition.entityId !== 'string' || typeof transition.from !== 'string' || typeof transition.to !== 'string' || typeof transition.reason !== 'string')
+        return null;
+    return {
+        eventId: event.eventId,
+        occurredAt: event.occurredAt,
+        from: transition.from,
+        to: transition.to,
+        reason: transition.reason,
+        ...(isRecord(transition.supersedes) ? { supersedes: transition.supersedes } : {}),
+    };
+}
+function skillLifecycleEntry(event) {
+    const payload = event.payload;
+    const transition = payload.transition;
+    if (!isRecord(transition) || transition.entity !== 'skill' || typeof transition.entityId !== 'string' || typeof transition.from !== 'string' || typeof transition.to !== 'string' || typeof transition.reason !== 'string')
+        return null;
+    return {
+        eventId: event.eventId,
+        occurredAt: event.occurredAt,
+        from: transition.from,
+        to: transition.to,
+        reason: transition.reason,
+        ...(isRecord(transition.supersedes) ? { supersedes: transition.supersedes } : {}),
+    };
+}
+function recipeLifecycleEntry(event) {
+    const payload = event.payload;
+    const transition = payload.transition;
+    if (!isRecord(transition) || transition.entity !== 'compiler-recipe' || typeof transition.entityId !== 'string' || typeof transition.from !== 'string' || typeof transition.to !== 'string' || typeof transition.reason !== 'string')
+        return null;
+    return {
+        eventId: event.eventId,
+        occurredAt: event.occurredAt,
+        from: transition.from,
+        to: transition.to,
+        reason: transition.reason,
+        ...(isRecord(transition.supersedes) ? { supersedes: transition.supersedes } : {}),
+    };
+}
 function latestOpenObservationIds(events, notes) {
     const latest = new Map();
     for (const event of events) {
@@ -66,7 +116,7 @@ function latestOpenObservationIds(events, notes) {
     return new Set([...latest.values()].flatMap(({ eventId, record }) => record.status === 'open' && record.absorbedBySnapshotId === null ? [eventId] : []));
 }
 export function projectEvents(events) {
-    const projection = { schemaVersion: 2, contexts: {}, notes: {}, knowledge: {}, deadends: {}, workspaces: {} };
+    const projection = { schemaVersion: 2, contexts: {}, notes: {}, knowledge: {}, deadends: {}, experiences: {}, proposals: {}, skills: {}, recipes: {}, evidenceGraph: { schemaVersion: 1, derivationVersion: 'evidence-graph-v1', nodes: [], edges: [] }, workspaces: {} };
     const openObservationIds = latestOpenObservationIds(events, projection.notes);
     for (const event of events) {
         const key = workspaceKey(event.git);
@@ -96,6 +146,72 @@ export function projectEvents(events) {
             if (deadendId)
                 projection.deadends[deadendId] = payload;
         }
+        if (event.type === 'experience.recorded') {
+            const experience = evolutionRecord(event);
+            if (experience && typeof experience.experienceId === 'string')
+                projection.experiences[experience.experienceId] = experience;
+        }
+        if (event.type === 'evolution.proposed') {
+            const proposal = evolutionRecord(event);
+            if (proposal && typeof proposal.proposalId === 'string') {
+                projection.proposals[proposal.proposalId] = { proposal, status: proposal.status, lifecycle: [], acceptedArtifact: null };
+            }
+        }
+        if (event.type === 'evolution.candidate.accepted') {
+            const artifact = evolutionRecord(event);
+            if (artifact && projection.proposals[artifact.proposalId])
+                projection.proposals[artifact.proposalId].acceptedArtifact = artifact;
+        }
+        if (['evolution.verified', 'evolution.published', 'evolution.rejected', 'evolution.deprecated', 'evolution.superseded'].includes(event.type)) {
+            const entry = lifecycleEntry(event);
+            const state = entry ? projection.proposals[event.payload.transition.entityId] : null;
+            if (entry && state && state.status === entry.from) {
+                state.status = entry.to;
+                state.lifecycle.push(entry);
+            }
+        }
+        if (event.type === 'skill.materialized') {
+            const skill = evolutionRecord(event);
+            if (skill && typeof skill.skillId === 'string' && !projection.skills[skill.skillId]) {
+                projection.skills[skill.skillId] = { skill, status: skill.status, lifecycle: [], invocations: [], outcomes: [] };
+            }
+        }
+        if (['evolution.verified', 'evolution.published', 'evolution.rejected', 'evolution.deprecated', 'evolution.superseded'].includes(event.type)) {
+            const skillEntry = skillLifecycleEntry(event);
+            const skillState = skillEntry ? projection.skills[event.payload.transition.entityId] : null;
+            if (skillEntry && skillState && skillState.status === skillEntry.from) {
+                skillState.status = skillEntry.to;
+                skillState.lifecycle.push(skillEntry);
+            }
+        }
+        if (event.type === 'recipe.materialized') {
+            const recipe = evolutionRecord(event);
+            if (recipe && typeof recipe.recipeId === 'string' && !projection.recipes[recipe.recipeId]) {
+                projection.recipes[recipe.recipeId] = { recipe, status: recipe.status, lifecycle: [] };
+            }
+        }
+        if (['evolution.verified', 'evolution.published', 'evolution.rejected', 'evolution.deprecated', 'evolution.superseded'].includes(event.type)) {
+            const recipeEntry = recipeLifecycleEntry(event);
+            const recipeState = recipeEntry ? projection.recipes[event.payload.transition.entityId] : null;
+            if (recipeEntry && recipeState && recipeState.status === recipeEntry.from) {
+                recipeState.status = recipeEntry.to;
+                recipeState.lifecycle.push(recipeEntry);
+            }
+        }
+        if (event.type === 'skill.invoked') {
+            const invocation = evolutionRecord(event);
+            const skillState = invocation ? projection.skills[invocation.skillId] : null;
+            if (invocation && skillState && skillState.status === 'published' && !skillState.invocations.some((item) => item.invocationId === invocation.invocationId))
+                skillState.invocations.push(invocation);
+        }
+        if (event.type === 'skill.outcome.recorded') {
+            const outcome = evolutionRecord(event);
+            if (outcome) {
+                const skillState = Object.values(projection.skills).find((state) => state.invocations.some((invocation) => invocation.invocationId === outcome.invocationId));
+                if (skillState && !skillState.outcomes.some((item) => item.invocationId === outcome.invocationId))
+                    skillState.outcomes.push(outcome);
+            }
+        }
         if (event.type === 'note.recorded' && openObservationIds.has(event.eventId)) {
             workspace.openObservationEventIds = [...workspace.openObservationEventIds, event.eventId].slice(-50);
         }
@@ -104,6 +220,7 @@ export function projectEvents(events) {
         }
         projection.workspaces[key] = workspace;
     }
+    projection.evidenceGraph = buildEvidenceGraph(events);
     return projection;
 }
 async function removeObsoleteWorkspaceFiles(projectRoot, workspaceKeys) {
@@ -136,6 +253,11 @@ export async function rebuildProjections(projectRoot) {
         atomicWriteJson(cognitionNotesProjectionPath(projectRoot), projection.notes),
         atomicWriteJson(cognitionKnowledgeProjectionPath(projectRoot), projection.knowledge),
         atomicWriteJson(cognitionDeadendsProjectionPath(projectRoot), projection.deadends),
+        atomicWriteJson(cognitionExperiencesProjectionPath(projectRoot), projection.experiences),
+        atomicWriteJson(cognitionProposalsProjectionPath(projectRoot), projection.proposals),
+        atomicWriteJson(cognitionSkillsProjectionPath(projectRoot), projection.skills),
+        atomicWriteJson(cognitionRecipesProjectionPath(projectRoot), projection.recipes),
+        atomicWriteJson(cognitionEvidenceGraphProjectionPath(projectRoot), projection.evidenceGraph),
         atomicWriteJson(cognitionRetrievalProjectionPath(projectRoot), retrieval),
         ...Object.values(projection.workspaces).map((workspace) => atomicWriteJson(`${cognitionBranchesDirectory(projectRoot)}/${workspace.workspaceKey}.json`, workspace)),
     ]);

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

@@ -0,0 +1,25 @@
+import type { CompilerRecipeSection, CompilerRecipeSource, CompilerRecipeState, EvolutionArtifactStatus, EvolutionLineageReference } from './types.js';
+export interface MaterializeRecipeInput {
+    proposalId: string;
+    title: string;
+    preferredSources?: CompilerRecipeSource[];
+    preferredSections?: CompilerRecipeSection[];
+    sectionBudgets?: Partial<Record<CompilerRecipeSection, number>>;
+}
+export interface TransitionRecipeInput {
+    recipeId: string;
+    to: Extract<EvolutionArtifactStatus, 'verified' | 'published' | 'deprecated' | 'superseded'>;
+    rationale: string;
+    supersedes?: EvolutionLineageReference;
+}
+export declare function listRecipes(startPath?: string): Promise<CompilerRecipeState[]>;
+export declare function inspectRecipe(startPath: string | undefined, recipeId: string): Promise<CompilerRecipeState>;
+export declare function materializeRecipe(startPath: string | undefined, input: MaterializeRecipeInput): Promise<{
+    materialized: boolean;
+    recipeId: string;
+    eventId: string;
+}>;
+export declare function transitionRecipe(startPath: string | undefined, input: TransitionRecipeInput): Promise<{
+    transitioned: boolean;
+    eventId: string;
+}>;

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/runtime.js

@@ -249,6 +249,10 @@ export async function serveRuntime(startPath, options = {}) {
         return closing;
     };
     const touch = () => {
+        // Draining observations during shutdown can still notify activity. Never
+        // recreate an inactivity timer after closeServer has cleared the timers.
+        if (closing)
+            return;
         if (inactivity)
             clearTimeout(inactivity);
         inactivity = setTimeout(() => { void close('inactivity').catch(() => undefined); }, inactivityTimeoutMs);

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 };
+}