fluffy-context 0.7.6 → 0.8.0

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

@@ -0,0 +1,36 @@
+import type { EvolutionArtifactKind, EvolutionArtifactStatus, EvolutionLineageReference, EvolutionProposalState } from './types.js';
+type ProposalTargetKind = Extract<EvolutionArtifactKind, 'skill' | 'compiler-recipe'>;
+export interface ProposeEvolutionInput {
+    eventIds?: string[];
+    recentLimit?: number;
+    targetKind?: ProposalTargetKind;
+}
+export interface ProposeEvolutionResult {
+    experienceId: string;
+    experienceEventId: string;
+    proposalId: string | null;
+    proposalEventId: string | null;
+    recorded: boolean;
+}
+export interface AcceptEvolutionCandidateInput {
+    proposalId: string;
+    rationale: string;
+}
+export interface TransitionEvolutionProposalInput {
+    proposalId: string;
+    to: Extract<EvolutionArtifactStatus, 'verified' | 'rejected' | 'deprecated' | 'superseded'>;
+    rationale: string;
+    supersedes?: EvolutionLineageReference;
+}
+export declare function proposeEvolution(startPath: string | undefined, input?: ProposeEvolutionInput): Promise<ProposeEvolutionResult>;
+export declare function listEvolutionProposals(startPath?: string): Promise<EvolutionProposalState[]>;
+export declare function inspectEvolutionProposal(startPath: string | undefined, proposalId: string): Promise<EvolutionProposalState>;
+export declare function acceptEvolutionCandidate(startPath: string | undefined, input: AcceptEvolutionCandidateInput): Promise<{
+    accepted: boolean;
+    eventId: string;
+}>;
+export declare function transitionEvolutionProposal(startPath: string | undefined, input: TransitionEvolutionProposalInput): Promise<{
+    transitioned: boolean;
+    eventId: string;
+}>;
+export {};

package/dist/src/cognition/evolution.js

@@ -0,0 +1,221 @@
+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 { v2Enabled } from './orient.js';
+import { projectEvents, rebuildProjections } from './projections.js';
+const extractor = { id: 'deterministic-maintainer', version: '1' };
+const maxEvidenceEvents = 32;
+const allowedEvidenceTypes = new Set([
+    'host.prompt.submitted',
+    'context.checkpoint.imported', 'context.state.recorded',
+    'note.recorded', 'note.resolved', 'note.absorbed',
+    'git.state.observed', 'git.branch.changed', 'git.head.changed',
+    'workspace.paths.changed', 'record.used', 'usage.operation.completed',
+]);
+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 anchor(event) {
+    return { worktreeId: event.git.worktreeId, branch: event.git.branch, ref: event.git.ref, head: event.git.head };
+}
+function currentAnchor(state) {
+    return { worktreeId: state.worktreeId, branch: state.branch, ref: state.ref, head: state.commit };
+}
+function requireReason(reason) {
+    const value = reason.trim();
+    if (!value)
+        throw new Error('evolution rationale must not be empty');
+    return value;
+}
+function selectEvidence(events, input) {
+    const selected = input.eventIds
+        ? input.eventIds.map((eventId) => {
+            if (!eventId.trim())
+                throw new Error('evidence event ID must not be empty');
+            return eventId;
+        })
+        : events.filter((event) => allowedEvidenceTypes.has(event.type)).slice(-(input.recentLimit ?? maxEvidenceEvents)).map((event) => event.eventId);
+    if (selected.length === 0)
+        throw new Error('evolution extraction requires evidence events');
+    if (selected.length > maxEvidenceEvents)
+        throw new Error(`evolution extraction supports at most ${maxEvidenceEvents} evidence events`);
+    if (new Set(selected).size !== selected.length)
+        throw new Error('evolution evidence event IDs must be unique');
+    const byId = new Map(events.map((event) => [event.eventId, event]));
+    const evidence = selected.map((eventId) => byId.get(eventId));
+    if (evidence.some((event) => !event))
+        throw new Error('evolution evidence event was not found');
+    if (evidence.some((event) => !allowedEvidenceTypes.has(event.type)))
+        throw new Error('evolution evidence event type is not allowed');
+    return evidence;
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim().length > 0) : [];
+}
+function sourceReferences(events) {
+    const contextIds = new Set();
+    const snapshotIds = new Set();
+    const paths = new Set();
+    for (const event of events) {
+        const payload = event.payload;
+        const record = payload.record;
+        if (record && typeof record === 'object' && !Array.isArray(record)) {
+            const item = record;
+            const snapshot = item.snapshot;
+            if (snapshot && typeof snapshot === 'object' && !Array.isArray(snapshot)) {
+                const value = snapshot;
+                if (typeof value.contextId === 'string')
+                    contextIds.add(value.contextId);
+                if (typeof value.snapshotId === 'string')
+                    snapshotIds.add(value.snapshotId);
+            }
+            if (typeof item.contextId === 'string')
+                contextIds.add(item.contextId);
+            if (typeof item.snapshotId === 'string')
+                snapshotIds.add(item.snapshotId);
+        }
+        for (const value of stringArray(payload.paths))
+            paths.add(value.replaceAll('\\', '/'));
+    }
+    return { contextIds: [...contextIds].sort(), snapshotIds: [...snapshotIds].sort(), paths: [...paths].sort() };
+}
+function privacy(events) {
+    const redactionCount = events.reduce((total, event) => total + event.privacy.redactionCount, 0);
+    return { classification: events.some((event) => event.privacy.classification === 'redacted-text') ? 'redacted-text' : 'metadata', redactionCount };
+}
+function applicability(event) {
+    if (event.git.ref === null && event.git.branch === null)
+        return { project: true, branchMode: 'global' };
+    return { project: true, branchMode: 'exact', branches: [event.git.ref ?? event.git.branch ?? 'detached'], sourceCommit: event.git.head };
+}
+function candidateEligible(events) {
+    const hasContext = events.some((event) => event.type === 'context.checkpoint.imported' || event.type === 'context.state.recorded');
+    const hasActivity = events.some((event) => event.type.startsWith('git.') || event.type === 'workspace.paths.changed');
+    const hasUse = events.some((event) => event.type === 'record.used');
+    return hasContext && hasActivity && hasUse;
+}
+async function enabledProject(startPath) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!await v2Enabled(projectRoot))
+        throw new Error('evolution requires an enabled v2 runtime');
+    return projectRoot;
+}
+export async function proposeEvolution(startPath, input = {}) {
+    const projectRoot = await enabledProject(startPath);
+    const events = await readJournal(projectRoot);
+    const evidence = selectEvidence(events, input);
+    const references = sourceReferences(evidence);
+    const sourceEventIds = evidence.map((event) => event.eventId);
+    const last = evidence.at(-1);
+    const experienceBasis = { sourceEventIds, sourceContextIds: references.contextIds, sourceSnapshotIds: references.snapshotIds, paths: references.paths, git: anchor(last), privacy: privacy(evidence), extractor, createdAt: last.occurredAt };
+    const experience = {
+        experienceId: `exp-${hash(experienceBasis).slice(0, 20)}`,
+        schemaVersion: 1,
+        ...experienceBasis,
+        contentHash: hash(experienceBasis),
+        summary: `Metadata-only experience from ${sourceEventIds.length} journal events.`,
+    };
+    const experienceResult = await appendEvent(projectRoot, {
+        type: 'experience.recorded', source: { kind: 'agent' }, occurredAt: experience.createdAt,
+        idempotencyKey: `experience:${experience.experienceId}`, git: experience.git,
+        privacy: experience.privacy, payload: { record: experience },
+    });
+    let proposalResult = null;
+    let proposal = null;
+    if (candidateEligible(evidence)) {
+        const targetKind = input.targetKind ?? 'skill';
+        const proposalBasis = { sourceExperienceIds: [experience.experienceId], evidence: sourceEventIds.map((eventId) => ({ eventId, relation: 'derived_from' })), applicability: applicability(last), targetKind, extractor, createdAt: experience.createdAt };
+        const contentHash = hash(proposalBasis);
+        proposal = {
+            proposalId: `proposal-${contentHash.slice(0, 20)}`,
+            schemaVersion: 1,
+            targetKind,
+            targetId: `${targetKind}-${contentHash.slice(0, 20)}`,
+            status: 'candidate',
+            sourceExperienceIds: proposalBasis.sourceExperienceIds,
+            evidence: proposalBasis.evidence,
+            lineage: [],
+            applicability: proposalBasis.applicability,
+            contentHash,
+            summary: `Candidate ${targetKind} derived from metadata-only experience ${experience.experienceId}.`,
+            extractor,
+            createdAt: experience.createdAt,
+        };
+        proposalResult = await appendEvent(projectRoot, {
+            type: 'evolution.proposed', source: { kind: 'agent' }, occurredAt: proposal.createdAt,
+            idempotencyKey: `evolution-proposal:${proposal.proposalId}`, git: experience.git,
+            privacy: experience.privacy, payload: { record: proposal },
+        });
+    }
+    if (experienceResult.appended || proposalResult?.appended)
+        await rebuildProjections(projectRoot);
+    return { experienceId: experience.experienceId, experienceEventId: experienceResult.event.eventId, proposalId: proposal?.proposalId ?? null, proposalEventId: proposalResult?.event.eventId ?? null, recorded: experienceResult.appended || Boolean(proposalResult?.appended) };
+}
+export async function listEvolutionProposals(startPath) {
+    const projectRoot = await enabledProject(startPath);
+    return Object.values(projectEvents(await readJournal(projectRoot)).proposals).sort((left, right) => left.proposal.proposalId.localeCompare(right.proposal.proposalId));
+}
+export async function inspectEvolutionProposal(startPath, proposalId) {
+    const proposal = (await listEvolutionProposals(startPath)).find((item) => item.proposal.proposalId === proposalId);
+    if (!proposal)
+        throw new Error(`evolution proposal not found: ${proposalId}`);
+    return proposal;
+}
+export async function acceptEvolutionCandidate(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const rationale = requireReason(input.rationale);
+    const state = await inspectEvolutionProposal(projectRoot, input.proposalId);
+    if (state.proposal.targetKind !== 'skill' && state.proposal.targetKind !== 'compiler-recipe')
+        throw new Error('only skill and compiler-recipe proposals can be accepted in Phase 1');
+    if (state.status !== 'candidate')
+        throw new Error(`candidate acceptance requires a candidate proposal: ${input.proposalId}`);
+    if (state.acceptedArtifact)
+        throw new Error(`candidate artifact already accepted: ${input.proposalId}`);
+    const git = await readGitWorktreeState(projectRoot);
+    const artifact = {
+        artifactId: state.proposal.targetId,
+        schemaVersion: 1,
+        proposalId: state.proposal.proposalId,
+        kind: state.proposal.targetKind,
+        status: 'candidate',
+        applicability: state.proposal.applicability,
+        contentHash: state.proposal.contentHash,
+        lineage: state.proposal.lineage,
+        rationale,
+        createdAt: new Date().toISOString(),
+    };
+    const result = await appendEvent(projectRoot, {
+        type: 'evolution.candidate.accepted', source: { kind: 'cli' }, idempotencyKey: `evolution-accept:${artifact.artifactId}:${hash(rationale).slice(0, 16)}`,
+        git: currentAnchor(git), payload: { record: artifact },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { accepted: result.appended, eventId: result.event.eventId };
+}
+export async function transitionEvolutionProposal(startPath, input) {
+    const projectRoot = await enabledProject(startPath);
+    const rationale = requireReason(input.rationale);
+    const state = await inspectEvolutionProposal(projectRoot, input.proposalId);
+    if (input.to === 'superseded' && !input.supersedes)
+        throw new Error('superseding an evolution proposal requires lineage');
+    const git = await readGitWorktreeState(projectRoot);
+    const result = await appendEvent(projectRoot, {
+        type: `evolution.${input.to}`,
+        source: { kind: 'cli' },
+        idempotencyKey: `evolution-transition:${input.proposalId}:${state.status}:${input.to}:${hash({ rationale, supersedes: input.supersedes }).slice(0, 16)}`,
+        git: currentAnchor(git),
+        payload: { transition: { entity: 'proposal', entityId: input.proposalId, from: state.status, to: input.to, reason: rationale, ...(input.supersedes ? { supersedes: input.supersedes } : {}) } },
+    });
+    if (result.appended)
+        await rebuildProjections(projectRoot);
+    return { transitioned: result.appended, eventId: result.event.eventId };
+}

package/dist/src/cognition/journal.js

@@ -10,10 +10,14 @@ const eventTypes = new Set([
     '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',
+    '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',
 ]);
-const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'git-observer', 'fs-observer', 'migration']);
+const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'agent', 'git-observer', 'fs-observer', 'migration']);
 const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
@@ -55,6 +59,79 @@ function validGitAnchor(value) {
 function validIsoDate(value) {
     return typeof value === 'string' && Number.isFinite(Date.parse(value));
 }
+function validEvolutionId(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error(`${label} must not be empty`);
+}
+function validNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function validLineage(value) {
+    return isRecord(value)
+        && (value.entity === 'knowledge' || value.entity === 'deadend' || value.entity === 'skill' || value.entity === 'compiler-recipe' || value.entity === 'experience' || value.entity === 'proposal')
+        && typeof value.entityId === 'string' && value.entityId.trim().length > 0
+        && (value.relation === 'supports' || value.relation === 'contradicts' || value.relation === 'supersedes' || value.relation === 'used_for');
+}
+function validEvolutionEvidence(value) {
+    return isRecord(value)
+        && typeof value.eventId === 'string' && value.eventId.trim().length > 0
+        && (value.relation === 'derived_from' || value.relation === 'supports' || value.relation === 'contradicts' || value.relation === 'validated_by');
+}
+function validApplicability(value) {
+    return isRecord(value)
+        && value.project === true
+        && (value.branchMode === 'global' || value.branchMode === 'exact' || value.branchMode === 'ancestor-of-source' || value.branchMode === 'descendant-of-source')
+        && (value.branches === undefined || Array.isArray(value.branches) && value.branches.every((item) => typeof item === 'string' && item.trim().length > 0))
+        && (value.paths === undefined || Array.isArray(value.paths) && value.paths.every((item) => typeof item === 'string' && item.trim().length > 0))
+        && (value.sourceCommit === undefined || typeof value.sourceCommit === 'string' || value.sourceCommit === null)
+        && (value.dependencyConstraints === undefined || Array.isArray(value.dependencyConstraints) && value.dependencyConstraints.every((item) => typeof item === 'string' && item.trim().length > 0));
+}
+function validEvolutionTransition(from, to) {
+    if ((from !== 'candidate' && from !== 'verified' && from !== 'published' && from !== 'rejected' && from !== 'deprecated' && from !== 'superseded' && from !== 'obsolete') || (to !== 'verified' && to !== 'published' && to !== 'rejected' && to !== 'deprecated' && to !== 'superseded' && to !== 'obsolete'))
+        return false;
+    return (from === 'candidate' && (to === 'verified' || to === 'rejected' || to === 'deprecated'))
+        || (from === 'verified' && (to === 'published' || to === 'deprecated' || to === 'superseded' || to === 'obsolete'))
+        || (from === 'published' && (to === 'deprecated' || to === 'superseded' || to === 'obsolete'));
+}
+function validSkill(value) {
+    return isRecord(value)
+        && typeof value.skillId === 'string' && value.skillId.trim().length > 0
+        && value.schemaVersion === 1
+        && typeof value.proposalId === 'string' && value.proposalId.trim().length > 0
+        && typeof value.title === 'string' && value.title.trim().length > 0
+        && Array.isArray(value.procedure) && value.procedure.length > 0 && value.procedure.length <= 32 && value.procedure.every((step) => typeof step === 'string' && step.trim().length > 0)
+        && validApplicability(value.applicability)
+        && value.status === 'candidate'
+        && typeof value.contentHash === 'string' && value.contentHash.trim().length > 0
+        && Array.isArray(value.lineage) && value.lineage.every(validLineage)
+        && validIsoDate(value.createdAt);
+}
+const recipeSources = new Set(['context', 'knowledge', 'deadend', 'note']);
+const recipeSections = new Set(['summary', 'pending', 'decision', 'risk', 'note', 'knowledge', 'deadend', 'activity']);
+function validRecipe(value) {
+    if (!isRecord(value))
+        return false;
+    const allowed = new Set(['recipeId', 'schemaVersion', 'proposalId', 'title', 'applicability', 'preferredSources', 'preferredSections', 'sectionBudgets', 'status', 'contentHash', 'lineage', 'createdAt']);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return false;
+    const validPreferences = (items, allowedItems) => items === undefined
+        || (Array.isArray(items) && items.length <= allowedItems.size && items.every((item) => typeof item === 'string' && allowedItems.has(item)) && new Set(items).size === items.length);
+    const sectionBudgets = isRecord(value.sectionBudgets) ? value.sectionBudgets : null;
+    const validBudgets = value.sectionBudgets === undefined || (sectionBudgets !== null
+        && Object.keys(sectionBudgets).every((key) => recipeSections.has(key) && validNonNegativeInteger(sectionBudgets[key]) && sectionBudgets[key] <= 100_000));
+    return typeof value.recipeId === 'string' && value.recipeId.trim().length > 0
+        && value.schemaVersion === 1
+        && typeof value.proposalId === 'string' && value.proposalId.trim().length > 0
+        && typeof value.title === 'string' && value.title.trim().length > 0
+        && validApplicability(value.applicability)
+        && validPreferences(value.preferredSources, recipeSources)
+        && validPreferences(value.preferredSections, recipeSections)
+        && validBudgets
+        && value.status === 'candidate'
+        && typeof value.contentHash === 'string' && value.contentHash.trim().length > 0
+        && Array.isArray(value.lineage) && value.lineage.every(validLineage)
+        && validIsoDate(value.createdAt);
+}
 function validatePayloadBoundary(input) {
     const payload = input.payload;
     if (input.type === 'host.prompt.submitted' && (typeof payload.intent !== 'string' || payload.intent.trim().length === 0)) {
@@ -65,11 +142,74 @@ function validatePayloadBoundary(input) {
         if (!isRecord(record) || typeof record.message !== 'string' || record.message.trim().length === 0)
             throw new Error('note message must not be empty');
     }
+    if (input.type === 'usage.operation.completed') {
+        const requiredNumbers = ['durationMs', 'inputChars', 'outputChars', 'inputBytes', 'outputBytes', 'estimatedInputTokens', 'estimatedOutputTokens'];
+        if (payload.operation !== 'orient' && payload.operation !== 'compile' && payload.operation !== 'expand' && payload.operation !== 'resume')
+            throw new Error('invalid usage operation');
+        if (payload.interface !== 'cli' && payload.interface !== 'mcp' && payload.interface !== 'agent' && payload.interface !== 'hook')
+            throw new Error('invalid usage interface');
+        if (typeof payload.success !== 'boolean' || payload.estimatedMethod !== 'chars-div-four' || requiredNumbers.some((key) => typeof payload[key] !== 'number' || !Number.isFinite(payload[key]) || payload[key] < 0))
+            throw new Error('invalid usage telemetry payload');
+        if (!payload.success && typeof payload.errorClass !== 'string')
+            throw new Error('usage errors require an error class');
+    }
     if (input.type === 'workspace.paths.changed') {
         const changes = payload.changes;
         if (!Array.isArray(changes) || changes.length === 0)
             throw new Error('workspace activity must contain changes');
     }
+    if (input.type === 'experience.recorded') {
+        const experience = payload.record;
+        if (!isRecord(experience))
+            throw new Error('experience record is required');
+        validEvolutionId(experience.experienceId, 'experience id');
+        if (experience.schemaVersion !== 1 || !Array.isArray(experience.sourceEventIds) || experience.sourceEventIds.length === 0 || !experience.sourceEventIds.every((value) => typeof value === 'string' && value.trim().length > 0) || !Array.isArray(experience.sourceContextIds) || !experience.sourceContextIds.every((value) => typeof value === 'string') || !Array.isArray(experience.sourceSnapshotIds) || !experience.sourceSnapshotIds.every((value) => typeof value === 'string') || !Array.isArray(experience.paths) || !experience.paths.every((value) => typeof value === 'string') || !validGitAnchor(experience.git) || !isRecord(experience.privacy) || (experience.privacy.classification !== 'metadata' && experience.privacy.classification !== 'redacted-text') || !validNonNegativeInteger(experience.privacy.redactionCount) || !isRecord(experience.extractor) || typeof experience.extractor.id !== 'string' || experience.extractor.id.trim().length === 0 || typeof experience.extractor.version !== 'string' || experience.extractor.version.trim().length === 0 || typeof experience.contentHash !== 'string' || experience.contentHash.trim().length === 0 || typeof experience.summary !== 'string' || experience.summary.trim().length === 0 || !validIsoDate(experience.createdAt))
+            throw new Error('invalid experience record');
+    }
+    if (input.type === 'evolution.proposed') {
+        const proposal = payload.record;
+        if (!isRecord(proposal))
+            throw new Error('evolution proposal record is required');
+        validEvolutionId(proposal.proposalId, 'proposal id');
+        if (proposal.schemaVersion !== 1 || (proposal.targetKind !== 'knowledge' && proposal.targetKind !== 'deadend' && proposal.targetKind !== 'skill' && proposal.targetKind !== 'compiler-recipe') || typeof proposal.targetId !== 'string' || proposal.targetId.trim().length === 0 || proposal.status !== 'candidate' || !Array.isArray(proposal.sourceExperienceIds) || proposal.sourceExperienceIds.length === 0 || !proposal.sourceExperienceIds.every((value) => typeof value === 'string' && value.trim().length > 0) || !Array.isArray(proposal.evidence) || proposal.evidence.length === 0 || !proposal.evidence.every(validEvolutionEvidence) || !Array.isArray(proposal.lineage) || !proposal.lineage.every(validLineage) || !validApplicability(proposal.applicability) || typeof proposal.contentHash !== 'string' || proposal.contentHash.trim().length === 0 || typeof proposal.summary !== 'string' || proposal.summary.trim().length === 0 || !isRecord(proposal.extractor) || typeof proposal.extractor.id !== 'string' || proposal.extractor.id.trim().length === 0 || typeof proposal.extractor.version !== 'string' || proposal.extractor.version.trim().length === 0 || !validIsoDate(proposal.createdAt))
+            throw new Error('invalid evolution proposal record');
+    }
+    if (input.type === 'evolution.candidate.accepted') {
+        const artifact = payload.record;
+        if (!isRecord(artifact) || typeof artifact.artifactId !== 'string' || artifact.artifactId.trim().length === 0 || artifact.schemaVersion !== 1 || typeof artifact.proposalId !== 'string' || artifact.proposalId.trim().length === 0 || (artifact.kind !== 'skill' && artifact.kind !== 'compiler-recipe') || artifact.status !== 'candidate' || !validApplicability(artifact.applicability) || typeof artifact.contentHash !== 'string' || artifact.contentHash.trim().length === 0 || !Array.isArray(artifact.lineage) || !artifact.lineage.every(validLineage) || typeof artifact.rationale !== 'string' || artifact.rationale.trim().length === 0 || !validIsoDate(artifact.createdAt))
+            throw new Error('invalid evolution candidate artifact');
+    }
+    if (['evolution.verified', 'evolution.published', 'evolution.rejected', 'evolution.deprecated', 'evolution.superseded'].includes(input.type)) {
+        const transition = payload.transition;
+        if (!isRecord(transition) || (transition.entity !== 'knowledge' && transition.entity !== 'deadend' && transition.entity !== 'skill' && transition.entity !== 'compiler-recipe' && transition.entity !== 'proposal') || typeof transition.entityId !== 'string' || transition.entityId.trim().length === 0 || !validEvolutionTransition(transition.from, transition.to) || typeof transition.reason !== 'string' || transition.reason.trim().length === 0 || (transition.supersedes !== undefined && !validLineage(transition.supersedes)))
+            throw new Error('invalid evolution lifecycle transition');
+        if ((input.type === 'evolution.verified' && transition.to !== 'verified') || (input.type === 'evolution.published' && transition.to !== 'published') || (input.type === 'evolution.rejected' && transition.to !== 'rejected') || (input.type === 'evolution.deprecated' && transition.to !== 'deprecated') || (input.type === 'evolution.superseded' && (transition.to !== 'superseded' || !validLineage(transition.supersedes))))
+            throw new Error('evolution lifecycle event does not match transition');
+    }
+    if (input.type === 'skill.materialized') {
+        if (!validSkill(payload.record))
+            throw new Error('invalid skill record');
+    }
+    if (input.type === 'recipe.materialized') {
+        if (!validRecipe(payload.record))
+            throw new Error('invalid compiler recipe record');
+    }
+    if (input.type === 'skill.invoked') {
+        const invocation = payload.record;
+        if (!isRecord(invocation))
+            throw new Error('skill invocation record is required');
+        validEvolutionId(invocation.invocationId, 'invocation id');
+        if (typeof invocation.skillId !== 'string' || invocation.skillId.trim().length === 0 || typeof invocation.callerEventId !== 'string' || invocation.callerEventId.trim().length === 0 || typeof invocation.inputHash !== 'string' || invocation.inputHash.trim().length === 0 || !validIsoDate(invocation.occurredAt))
+            throw new Error('invalid skill invocation record');
+    }
+    if (input.type === 'skill.outcome.recorded') {
+        const outcome = payload.record;
+        if (!isRecord(outcome))
+            throw new Error('skill outcome record is required');
+        validEvolutionId(outcome.outcomeId, 'outcome id');
+        if (typeof outcome.invocationId !== 'string' || outcome.invocationId.trim().length === 0 || typeof outcome.callerEventId !== 'string' || outcome.callerEventId.trim().length === 0 || (outcome.outcome !== 'success' && outcome.outcome !== 'failure' && outcome.outcome !== 'partial' && outcome.outcome !== 'irrelevant' && outcome.outcome !== 'unknown') || typeof outcome.summary !== 'string' || outcome.summary.trim().length === 0 || !validIsoDate(outcome.occurredAt))
+            throw new Error('invalid skill outcome record');
+    }
 }
 function validateEventShape(event, projectId, file, line) {
     if (!isRecord(event)
@@ -142,6 +282,7 @@ export async function readJournal(startPath, options = {}) {
                 throw new Error(`invalid journal record ${file}:${index + 1}: ${error instanceof Error ? error.message : 'invalid JSON'}`);
             }
             validateEventShape(event, projectId, file, index + 1);
+            validatePayloadBoundary(event);
             const { hash, ...withoutHash } = event;
             if (event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
                 throw new Error(`invalid journal hash chain at ${file}:${index + 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;
+}>;