@dcyfr/ai 3.0.1 → 3.0.2

package/dist/ai/metacognition/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../../packages/ai/metacognition/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAMnE,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,EAAG,KAAc,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,MAAM,EAAE,OAAO,4BAA4B,CAAC;IAC5C,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,KAAK,EAAE,WAAW,CAAC;CACpB;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAO/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA4BvE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAanE;AAED,0DAA0D;AAC1D,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAMD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,EAAE,MAAM;IAStB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAezC,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKjE,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;YAKvD,cAAc;CAW7B;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,EAAE,MAAM;IAQ5B,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAKhC,OAAO,IAAI,WAAW,EAAE;CAKzB;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,aAAa,EAAE,yBAAyB,CAAC;IACzC,WAAW,EAAE,OAAO,CAAC;CACtB;AAQD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,EAAE,GACrB,eAAe,CA4CjB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG;IAC9D,OAAO,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;CAC9B,GAAG,IAAI,CAeP;AAED,sEAAsE;AACtE,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM,EAClC,OAAO,EAAE,MAAM;CAKlB"}

package/dist/ai/metacognition/ledger.js

@@ -0,0 +1,268 @@
+/**
+ * Improvement Ledger — Append-Only Schema and Serializers
+ * TLP:AMBER - Internal Use Only
+ *
+ * Implements the append-only improvement ledger with:
+ *   - Typed schema for all lifecycle event entries
+ *   - JSON serializers / deserializers with schema version stamping
+ *   - File-backed persistent ledger (newline-delimited JSON, one entry per line)
+ *   - Lineage helpers (task 2.2) for audit reconstruction
+ *
+ * The file-backed ledger appends atomically per entry; it never rewrites
+ * existing lines, ensuring immutability of prior entries.
+ *
+ * @module ai/metacognition/ledger
+ */
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFile, appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+// ---------------------------------------------------------------------------
+// Serialized record format (on-disk / over-wire schema)
+// ---------------------------------------------------------------------------
+/** Schema version for the serialized ledger record format. */
+export const LEDGER_RECORD_SCHEMA_VERSION = '1.0';
+// ---------------------------------------------------------------------------
+// Serializers
+// ---------------------------------------------------------------------------
+/**
+ * Serialize a LedgerEntry to a newline-delimited JSON record.
+ * Each record is a single line; the newline is included in the output.
+ */
+export function serializeLedgerEntry(entry) {
+    const envelope = {
+        schema: LEDGER_RECORD_SCHEMA_VERSION,
+        written_at: new Date().toISOString(),
+        entry,
+    };
+    return JSON.stringify(envelope) + '\n';
+}
+/**
+ * Deserialize a single newline-delimited JSON line to a LedgerEntry.
+ * Returns null if the line is empty or cannot be parsed.
+ *
+ * @throws {LedgerDeserializationError} if the line parses but the schema is unrecognized.
+ */
+export function deserializeLedgerEntry(line) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return null;
+    let envelope;
+    try {
+        envelope = JSON.parse(trimmed);
+    }
+    catch {
+        throw new LedgerDeserializationError(`Invalid JSON in ledger line: ${trimmed.slice(0, 80)}`);
+    }
+    if (typeof envelope !== 'object' || envelope === null) {
+        throw new LedgerDeserializationError('Ledger record must be a JSON object');
+    }
+    const rec = envelope;
+    if (rec['schema'] !== LEDGER_RECORD_SCHEMA_VERSION) {
+        throw new LedgerDeserializationError(`Unsupported ledger record schema version: ${String(rec['schema'])}`);
+    }
+    if (typeof rec['entry'] !== 'object' || rec['entry'] === null) {
+        throw new LedgerDeserializationError('Ledger record missing "entry" field');
+    }
+    return rec['entry'];
+}
+/**
+ * Deserialize all entries from a newline-delimited JSON string.
+ * Skips blank lines; throws on malformed non-blank lines.
+ */
+export function deserializeAllEntries(ndjson) {
+    return ndjson
+        .split('\n')
+        .map((line, i) => {
+        try {
+            return deserializeLedgerEntry(line);
+        }
+        catch (err) {
+            throw new LedgerDeserializationError(`Error at line ${i + 1}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    })
+        .filter((e) => e !== null);
+}
+/** Thrown when a ledger record cannot be deserialized. */
+export class LedgerDeserializationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LedgerDeserializationError';
+    }
+}
+// ---------------------------------------------------------------------------
+// File-backed persistent ledger
+// ---------------------------------------------------------------------------
+/**
+ * File-backed append-only ledger.
+ *
+ * Storage format: newline-delimited JSON (NDJSON), one LedgerRecordEnvelope per line.
+ * Each `append()` call writes exactly one line; prior lines are never modified.
+ *
+ * The file is read fully on each query (suitable for low-volume policy improvement
+ * workloads; not designed for high-throughput streaming use cases).
+ *
+ * @example
+ * ```typescript
+ * const ledger = new FileLedger('/var/lib/dcyfr/metacog-ledger.ndjson');
+ * await ledger.append(entry);
+ * const entries = await ledger.getEntriesForProposal('proposal-id');
+ * ```
+ */
+export class FileLedger {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        // Ensure parent directory exists
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    async append(entry) {
+        // Idempotent: check if entry_id already present before writing
+        const existing = await this.getLatestEntry(entry.proposal_id);
+        if (existing) {
+            // Scan all entries for exact entry_id match
+            const all = await this.readAllEntries();
+            if (all.some((e) => e.entry_id === entry.entry_id))
+                return;
+        }
+        const line = serializeLedgerEntry(entry);
+        const dir = dirname(this.filePath);
+        await mkdir(dir, { recursive: true });
+        await appendFile(this.filePath, line, { encoding: 'utf8' });
+    }
+    async getEntriesForProposal(proposalId) {
+        const all = await this.readAllEntries();
+        return all.filter((e) => e.proposal_id === proposalId);
+    }
+    async getLatestEntry(proposalId) {
+        const entries = await this.getEntriesForProposal(proposalId);
+        return entries[entries.length - 1] ?? null;
+    }
+    async readAllEntries() {
+        const dir = dirname(this.filePath);
+        await mkdir(dir, { recursive: true });
+        try {
+            const content = await readFile(this.filePath, { encoding: 'utf8' });
+            return deserializeAllEntries(content);
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+}
+/**
+ * Synchronous file-backed ledger.
+ * For use in environments where async is not available (e.g. process exit hooks).
+ */
+export class SyncFileLedger {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    append(entry) {
+        const line = serializeLedgerEntry(entry);
+        appendFileSync(this.filePath, line, { encoding: 'utf8' });
+    }
+    readAll() {
+        if (!existsSync(this.filePath))
+            return [];
+        const content = readFileSync(this.filePath, { encoding: 'utf8' });
+        return deserializeAllEntries(content);
+    }
+}
+const TERMINAL_STATES = new Set([
+    'applied',
+    'rolled_back',
+    'rejected',
+]);
+/**
+ * Reconstruct the full ordered lifecycle for a proposal from a set of entries.
+ *
+ * Entries are ordered by following the `previous_entry_id` chain from the
+ * root (where `previous_entry_id === null`) to the latest entry.
+ * Falls back to insertion order if the chain cannot be fully resolved.
+ *
+ * @throws {LedgerLineageError} if the chain is broken (gap in previous_entry_id).
+ */
+export function reconstructLineage(proposalId, entries) {
+    if (entries.length === 0) {
+        throw new LedgerLineageError(proposalId, 'No entries found for proposal');
+    }
+    // Build id → entry map
+    const byId = new Map();
+    for (const e of entries)
+        byId.set(e.entry_id, e);
+    // Find the root (previous_entry_id === null)
+    const roots = entries.filter((e) => e.previous_entry_id === null);
+    if (roots.length === 0) {
+        throw new LedgerLineageError(proposalId, 'No root entry found (no entry with previous_entry_id=null)');
+    }
+    if (roots.length > 1) {
+        throw new LedgerLineageError(proposalId, `Multiple root entries found: ${roots.map((r) => r.entry_id).join(', ')}`);
+    }
+    // Walk the chain
+    const ordered = [];
+    let current = roots[0];
+    const visited = new Set();
+    while (current) {
+        if (visited.has(current.entry_id)) {
+            throw new LedgerLineageError(proposalId, `Cycle detected at entry ${current.entry_id}`);
+        }
+        visited.add(current.entry_id);
+        ordered.push(current);
+        // Find the next entry that points back to this one
+        const next = entries.find((e) => e.previous_entry_id === current.entry_id && !visited.has(e.entry_id));
+        current = next;
+    }
+    const latest = ordered[ordered.length - 1];
+    return {
+        proposal_id: proposalId,
+        entries: ordered,
+        current_state: latest.state,
+        is_terminal: TERMINAL_STATES.has(latest.state),
+    };
+}
+/**
+ * Reconstruct the rollback trail for a proposal.
+ * Returns the applied entry and the rolled_back entry, or null if no rollback occurred.
+ */
+export function extractRollbackTrail(lineage) {
+    const rolledBack = lineage.entries.find((e) => e.state === 'rolled_back');
+    if (!rolledBack)
+        return null;
+    const applied = lineage.entries.find((e) => e.state === 'applied');
+    if (!applied)
+        return null;
+    const payload = rolledBack.payload;
+    if (payload.kind !== 'rolled_back')
+        return null;
+    return {
+        applied,
+        rolled_back: rolledBack,
+        restored_snapshot_id: payload.restored_snapshot_id,
+    };
+}
+/** Thrown when lineage reconstruction fails due to a broken chain. */
+export class LedgerLineageError extends Error {
+    proposalId;
+    constructor(proposalId, message) {
+        super(`Lineage error for proposal ${proposalId}: ${message}`);
+        this.proposalId = proposalId;
+        this.name = 'LedgerLineageError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isNodeError(err) {
+    return typeof err === 'object' && err !== null && 'code' in err;
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ai/metacognition/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../packages/ai/metacognition/ledger.ts"],"names":[],"mappings":"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"}

package/dist/ai/metacognition/runtime.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Metacognitive Improvement Runtime — Lifecycle State Machine
+ * TLP:AMBER - Internal Use Only
+ *
+ * Implements the governed lifecycle state machine for improvement proposals:
+ *   propose → evaluate → approve → apply → (rollback)
+ *
+ * Enforcement rules:
+ *   - Schema version must be compatible before any proposal is processed.
+ *   - `production_direct` scope requires at least `third_party_audit`.
+ *   - TLP:RED context requires `human_required`.
+ *   - State transitions are validated; invalid transitions throw.
+ *   - All lifecycle events are written to the injected ImprovementLedger.
+ *
+ * Feature flag: controlled by `MetacognitiveRuntimeConfig.enabled`.
+ * When disabled the runtime is a structural no-op (see task 1.3 for env wiring).
+ *
+ * @module ai/metacognition/runtime
+ * @version 1.0.0
+ */
+import type { VerificationPolicy, VerificationResult } from '../types/delegation-contracts.js';
+import type { ImprovementLifecycleState, ImprovementProposal, ImprovementEvaluationResult, MetacognitiveRuntimeConfig, PolicySnapshot } from './types.js';
+/** A single entry in the improvement ledger. */
+export interface LedgerEntry {
+    readonly entry_id: string;
+    readonly proposal_id: string;
+    readonly state: ImprovementLifecycleState;
+    readonly actor: string;
+    readonly timestamp: string;
+    /** ID of the previous ledger entry for this proposal (null for first). */
+    readonly previous_entry_id: string | null;
+    readonly payload: LedgerEntryPayload;
+}
+/** Discriminated union payload per lifecycle state. */
+export type LedgerEntryPayload = {
+    kind: 'proposed';
+    proposal: ImprovementProposal;
+    source_snapshot: PolicySnapshot;
+} | {
+    kind: 'evaluated';
+    result: ImprovementEvaluationResult;
+} | {
+    kind: 'approved';
+    verification_result: VerificationResult;
+    approved_by: string;
+} | {
+    kind: 'rejected';
+    reason: string;
+    at_state: ImprovementLifecycleState;
+} | {
+    kind: 'applied';
+    result_snapshot: PolicySnapshot;
+} | {
+    kind: 'rolled_back';
+    reason: string;
+    restored_snapshot_id: string;
+};
+/**
+ * Minimal ledger interface consumed by the runtime.
+ * Full implementation (append-only persistence, lineage queries) is in task 2.1.
+ */
+export interface ImprovementLedger {
+    /** Append a new entry. Must be idempotent on duplicate entry_ids. */
+    append(entry: LedgerEntry): Promise<void>;
+    /** Return all entries for a proposal in insertion order. */
+    getEntriesForProposal(proposal_id: string): Promise<LedgerEntry[]>;
+    /** Return the latest entry for a proposal, or null. */
+    getLatestEntry(proposal_id: string): Promise<LedgerEntry | null>;
+}
+/** Thrown when an invalid lifecycle transition is attempted. */
+export declare class InvalidLifecycleTransitionError extends Error {
+    readonly proposal_id: string;
+    readonly from: ImprovementLifecycleState;
+    readonly to: ImprovementLifecycleState;
+    constructor(proposal_id: string, from: ImprovementLifecycleState, to: ImprovementLifecycleState);
+}
+/** Thrown when a policy snapshot fails schema version compatibility check. */
+export declare class SchemaIncompatibleError extends Error {
+    readonly snapshot_id: string;
+    readonly snapshot_version: string;
+    readonly runtime_version: string;
+    constructor(snapshot_id: string, snapshot_version: string, runtime_version: string);
+}
+/** Thrown when an approve request fails governance threshold checks. */
+export declare class GovernanceViolationError extends Error {
+    readonly proposal_id: string;
+    readonly provided: VerificationPolicy;
+    readonly required: VerificationPolicy;
+    readonly reason: string;
+    constructor(proposal_id: string, provided: VerificationPolicy, required: VerificationPolicy, reason: string);
+}
+/** Thrown when the runtime is disabled and a proposal is submitted. */
+export declare class RuntimeDisabledError extends Error {
+    constructor();
+}
+export type IdGenerator = () => string;
+/**
+ * Governed runtime for the improvement lifecycle state machine.
+ *
+ * Usage:
+ * ```typescript
+ * const runtime = new MetacognitiveImprovementRuntime(config, ledger);
+ * await runtime.propose(snapshot, proposal);
+ * await runtime.evaluate(proposal_id, evaluationResult);
+ * await runtime.approve(proposal_id, verificationResult, 'human-reviewer-1');
+ * await runtime.apply(proposal_id, resultSnapshot);
+ * ```
+ */
+export declare class MetacognitiveImprovementRuntime {
+    private readonly config;
+    private readonly ledger;
+    private readonly generateId;
+    constructor(config: MetacognitiveRuntimeConfig, ledger: ImprovementLedger, generateId?: IdGenerator);
+    /**
+     * Submit an improvement proposal.
+     *
+     * Validates:
+     * 1. Runtime is enabled.
+     * 2. Source snapshot schema version is compatible with this runtime.
+     *
+     * On success appends a `proposed` ledger entry.
+     *
+     * @throws {RuntimeDisabledError} if the runtime is disabled.
+     * @throws {SchemaIncompatibleError} if the snapshot schema is incompatible.
+     */
+    propose(sourceSnapshot: PolicySnapshot, proposal: ImprovementProposal): Promise<LedgerEntry>;
+    /**
+     * Record the evaluation result for a proposal.
+     *
+     * Transitions `proposed → evaluated` (pass) or `proposed → rejected` (fail).
+     * Rejection occurs when the evaluation did not pass.
+     *
+     * @throws {InvalidLifecycleTransitionError} if proposal is not in `proposed` state.
+     */
+    evaluate(proposalId: string, result: ImprovementEvaluationResult, evaluatedBy: string): Promise<LedgerEntry>;
+    /**
+     * Approve an evaluated proposal.
+     *
+     * Transitions `evaluated → approved`.
+     *
+     * Governance enforcement:
+     * - Resolves the required verification policy from the proposal's context.
+     * - Rejects if `verificationResult.verification_method` does not meet the
+     *   required policy strength.
+     * - TLP:RED always requires `human_required`.
+     * - `production_direct` scope requires at minimum `third_party_audit`.
+     *
+     * @throws {InvalidLifecycleTransitionError} if proposal is not in `evaluated` state.
+     * @throws {GovernanceViolationError} if the verification policy is insufficient.
+     */
+    approve(proposalId: string, verificationResult: VerificationResult, approvedBy: string): Promise<LedgerEntry>;
+    /**
+     * Apply an approved proposal, recording the resulting policy snapshot.
+     *
+     * Transitions `approved → applied`.
+     *
+     * @throws {InvalidLifecycleTransitionError} if proposal is not in `approved` state.
+     */
+    apply(proposalId: string, resultSnapshot: PolicySnapshot, appliedBy: string): Promise<LedgerEntry>;
+    /**
+     * Roll back an applied proposal to a prior snapshot.
+     *
+     * Transitions `applied → rolled_back`.
+     *
+     * @throws {InvalidLifecycleTransitionError} if proposal is not in `applied` state.
+     */
+    rollback(proposalId: string, reason: string, restoredSnapshotId: string, rolledBackBy: string): Promise<LedgerEntry>;
+    /**
+     * Return the current lifecycle state of a proposal, or null if unknown.
+     */
+    getState(proposalId: string): Promise<ImprovementLifecycleState | null>;
+    private assertEnabled;
+    private assertSchemaCompatible;
+    private assertValidTransition;
+    private requireLatestEntry;
+    private requireProposedEntry;
+    private buildGovernanceViolationReason;
+    /**
+     * Assert governance config invariants at construction time.
+     * Prevents misconfiguration that would weaken production safety gates.
+     */
+    private assertGovernanceInvariants;
+}
+/**
+ * Simple in-memory ImprovementLedger.
+ * Used in tests and non-production shadow mode.
+ * Not suitable for production (no persistence, no durability guarantees).
+ */
+export declare class InMemoryImprovementLedger implements ImprovementLedger {
+    private entries;
+    append(entry: LedgerEntry): Promise<void>;
+    getEntriesForProposal(proposalId: string): Promise<LedgerEntry[]>;
+    getLatestEntry(proposalId: string): Promise<LedgerEntry | null>;
+    /** Test helper: clear all entries. */
+    clear(): void;
+}
+/**
+ * Create a MetacognitiveImprovementRuntime with the default governance config.
+ */
+export declare function createMetacognitiveRuntime(options?: {
+    enabled?: boolean;
+    ledger?: ImprovementLedger;
+    generateId?: IdGenerator;
+}): MetacognitiveImprovementRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/ai/metacognition/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../packages/ai/metacognition/runtime.ts"],"names":[],"mappings":"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"}