onto-mcp 0.3.0

package/dist/core-runtime/learning/promote/apply-state.js

@@ -0,0 +1,240 @@
+/**
+ * Phase 3 Promote — Apply Execution State helper (Step 9c).
+ *
+ * Design authority:
+ *   - learn-phase3-design-v9.md DD-22 (attempt_id lifecycle, generation
+ *     monotonic within an attempt)
+ *   - learn-phase3-design-v8.md DD-15 (Phase B atomicity, dual failure modes)
+ *   - learn-phase3-design-v5.md DD-15 (initial atomic apply contract)
+ *
+ * Responsibility:
+ *   - Generate ULID-shaped attempt_ids for fresh Phase B attempts so cross-
+ *     attempt resolution (DD-22) can rely on lexicographic == chronological
+ *     ordering.
+ *   - Provide builder helpers for the ApplyExecutionState lifecycle:
+ *     init → applied / failed / pending updates → status transitions →
+ *     persist.
+ *   - Wrap REGISTRY.saveToFile so the canonical JSON path is computed once
+ *     and the generation counter is enforced to be monotonic.
+ *
+ * Scope:
+ *   - Phase B helper. promoter.ts (Phase A) does not call this.
+ *   - This module does NOT decide which decisions to apply; it only mutates
+ *     the ApplyExecutionState struct in memory and persists it to disk.
+ *   - Atomic write: REGISTRY.saveToFile writes through a temp + rename
+ *     dance via the spec-helpers module, so partial-write recovery is
+ *     handled at the registry layer.
+ *
+ * Failure model split (DD-15):
+ *   - apply_verification_failed and state_persistence_failed are distinct
+ *     terminal states. The latter never reaches a persisted ApplyExecutionState
+ *     because, by definition, persistence itself failed — it goes to the
+ *     emergency log instead. The discriminator stays in the type so recovery
+ *     code can pattern-match exhaustively.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { REGISTRY } from "../shared/artifact-registry.js";
+// ---------------------------------------------------------------------------
+// ULID generation — DD-22 attempt_id
+// ---------------------------------------------------------------------------
+/**
+ * Crockford base32 alphabet — RFC ULID spec.
+ *
+ * I = 1-like; L = 1-like; O = 0-like; U = excluded for profanity reasons.
+ * These exclusions yield a 32-character set: 0-9 + A-Z minus {I,L,O,U}.
+ */
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function encodeBase32(value, length) {
+    let v = value;
+    const chars = new Array(length);
+    for (let i = length - 1; i >= 0; i--) {
+        chars[i] = CROCKFORD_BASE32.charAt(Number(v % 32n));
+        v /= 32n;
+    }
+    return chars.join("");
+}
+/**
+ * Generate a ULID (26-character Crockford base32 string).
+ *
+ * Format:
+ *   - Chars 0..9: 48-bit timestamp (ms since epoch) — 10 base32 chars
+ *   - Chars 10..25: 80-bit randomness — 16 base32 chars
+ *
+ * Lexicographic ordering matches chronological ordering by construction.
+ * That property is what DD-22 canonical attempt selection relies on.
+ *
+ * Note: this is a minimal in-tree implementation to avoid pulling in a
+ * runtime dependency. If we need monotonic ULIDs (millisecond collisions
+ * within a single process), upgrade to the `ulid` npm package.
+ */
+export function generateUlid() {
+    const timestampMs = Date.now();
+    const timestampBig = BigInt(timestampMs);
+    const tsPart = encodeBase32(timestampBig, 10);
+    const randBytes = crypto.randomBytes(10);
+    let randBig = 0n;
+    for (const byte of randBytes) {
+        randBig = (randBig << 8n) | BigInt(byte);
+    }
+    const randPart = encodeBase32(randBig, 16);
+    return tsPart + randPart;
+}
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Canonical path for ApplyExecutionState persistence.
+ *
+ * sessionRoot is `{projectRoot}/.onto/sessions/promote/{session-id}/`. The
+ * filename is fixed so recovery can always discover it without needing
+ * extra metadata.
+ */
+export function getApplyStatePath(sessionRoot) {
+    return path.join(sessionRoot, "promote-execution-result.json");
+}
+/**
+ * Construct a fresh ApplyExecutionState for a new attempt.
+ *
+ * DD-22 lifecycle rule 1: a fresh apply (no --resume) generates a NEW
+ * attempt_id. The caller passes one explicitly (when running a deterministic
+ * test) or omits it to get a fresh ULID.
+ *
+ * The state starts in `in_progress` with generation=0 and an empty
+ * applied/failed list. The pending list snapshots the decisions the caller
+ * is about to apply so recovery can identify which slots were promised.
+ */
+export function initApplyState(config) {
+    const now = new Date().toISOString();
+    return {
+        schema_version: "1",
+        session_id: config.sessionId,
+        attempt_id: config.attemptId ?? generateUlid(),
+        attempt_started_at: now,
+        generation: 0,
+        last_updated_at: now,
+        status: "in_progress",
+        applied_decisions: [],
+        failed_decisions: [],
+        pending_decisions: [...config.pendingDecisions],
+        recoverability_checkpoint_path: config.recoverabilityCheckpointPath ?? null,
+    };
+}
+// ---------------------------------------------------------------------------
+// Mutation helpers — pure transforms over the in-memory state
+// ---------------------------------------------------------------------------
+/**
+ * Mark a pending decision as applied. Removes it from `pending_decisions`
+ * and appends to `applied_decisions`. Bumps generation + last_updated_at.
+ *
+ * Throws when the decision_id is not in the pending list — that would mean
+ * the caller double-applied or applied an unexpected decision, which is a
+ * symptom of a higher-layer bug we want to catch loudly.
+ */
+export function markApplied(state, applied) {
+    const stillPending = state.pending_decisions.filter((p) => !(p.decision_id === applied.decision_id && p.decision_kind === applied.decision_kind));
+    if (stillPending.length === state.pending_decisions.length) {
+        throw new Error(`apply-state.markApplied: decision ${applied.decision_kind}/${applied.decision_id} ` +
+            `not found in pending_decisions (already applied or never declared)`);
+    }
+    return bump({
+        ...state,
+        applied_decisions: [...state.applied_decisions, applied],
+        pending_decisions: stillPending,
+    });
+}
+/**
+ * Mark a pending decision as failed. Same removal/move semantics as
+ * markApplied, but the destination is `failed_decisions`.
+ *
+ * `resumable` records whether the failure can be retried in a `--resume`
+ * flow. The caller decides; this helper does not classify.
+ */
+export function markFailed(state, failed) {
+    const stillPending = state.pending_decisions.filter((p) => !(p.decision_id === failed.decision_id && p.decision_kind === failed.decision_kind));
+    if (stillPending.length === state.pending_decisions.length) {
+        throw new Error(`apply-state.markFailed: decision ${failed.decision_kind}/${failed.decision_id} ` +
+            `not found in pending_decisions`);
+    }
+    return bump({
+        ...state,
+        failed_decisions: [...state.failed_decisions, failed],
+        pending_decisions: stillPending,
+    });
+}
+/**
+ * Record verification failures discovered after apply (DD-15
+ * apply_verification_failed path).
+ */
+export function recordVerificationFailures(state, failures) {
+    if (failures.length === 0)
+        return state;
+    return bump({
+        ...state,
+        verification_failures: [
+            ...(state.verification_failures ?? []),
+            ...failures,
+        ],
+    });
+}
+/**
+ * Transition the state's status field. Phase B's terminal transitions are:
+ *   in_progress → completed
+ *   in_progress → failed_resumable  (one or more applied + recoverable failure)
+ *   in_progress → apply_verification_failed (post-apply check failed)
+ *
+ * `state_persistence_failed` is intentionally rejected here because, by
+ * definition, that state never gets persisted — the caller writes an
+ * emergency log entry instead.
+ */
+export function transitionStatus(state, to) {
+    if (to === "state_persistence_failed") {
+        throw new Error(`apply-state.transitionStatus: state_persistence_failed cannot be ` +
+            `persisted into ApplyExecutionState — write to the emergency log instead`);
+    }
+    return bump({ ...state, status: to });
+}
+/**
+ * Generation + timestamp bump. Every mutation goes through this helper so the
+ * monotonic invariant (DD-22) is enforced in one place.
+ */
+function bump(state) {
+    return {
+        ...state,
+        generation: state.generation + 1,
+        last_updated_at: new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+/**
+ * Persist the state to disk via REGISTRY.saveToFile.
+ *
+ * The registry's saveToFile helper handles atomic write semantics (write to
+ * a sibling temp file then rename). On disk failure the caller catches the
+ * thrown error and routes it to the emergency log path.
+ *
+ * Returns the resolved path so callers can record it for audit.
+ */
+export function persistApplyState(sessionRoot, state) {
+    const target = getApplyStatePath(sessionRoot);
+    REGISTRY.saveToFile("apply_execution_state", target, state);
+    return target;
+}
+/**
+ * Load a previously persisted ApplyExecutionState (for `--resume`).
+ *
+ * Returns null when the file does not exist (fresh attempt). Throws when
+ * the file exists but is structurally invalid — the caller routes that to
+ * the recovery path (gatherRecoveryContext + RecoveryResolution).
+ */
+export function loadApplyState(sessionRoot) {
+    const target = getApplyStatePath(sessionRoot);
+    // Distinguish "no prior attempt" from "corrupted prior state" — fs probe
+    // returns null for the former, REGISTRY.loadFromFile throws for the latter.
+    if (!fs.existsSync(target))
+        return null;
+    return REGISTRY.loadFromFile("apply_execution_state", target);
+}

package/dist/core-runtime/learning/promote/audit-obligation.js

@@ -0,0 +1,195 @@
+/**
+ * AuditObligation — encapsulated class (DD-21).
+ *
+ * Design authority:
+ *   - learn-phase3-design-v9.md DD-21 (status documented as cache)
+ *   - learn-phase3-design-v8.md DD-21 (construction invariants + kernel separation)
+ *   - learn-phase3-design-v7.md DD-21 (introduction)
+ *
+ * Why encapsulation:
+ *   - v6 review found that `obligation.status = X` direct assignment was a
+ *     latent bug surface. The mandatory transitionObligation() helper relied
+ *     on grep-based code review for enforcement.
+ *   - DD-21 moves enforcement into the type system: status / status_history /
+ *     carry_forward_count are private fields. The TypeScript compiler catches
+ *     any mutation attempt as an error.
+ *   - v8 added construction invariants so AuditObligation.fromJSON() also
+ *     verifies status ↔ status_history consistency. Bad serialized data fails
+ *     loudly at deserialization, not at the next transition.
+ *
+ * Cache documentation (v9 SYN-UF-CONC-01):
+ *   #status mirrors #status_history[last].to. This is an intentional cache,
+ *   not a duplicate. The constructor enforces the invariant; transition()
+ *   updates both atomically; the field is private so external mutation is
+ *   impossible. Consumers can use `obligation.status` directly without
+ *   re-deriving from history.
+ */
+import { isLegalTransition, isTerminalStatus, IllegalTransitionError, InvariantViolatedError, } from "../shared/audit-obligation-kernel.js";
+export class AuditObligation {
+    // Immutable public identity
+    obligation_id;
+    trigger_kind;
+    detected_at;
+    detected_after_session;
+    affected_agents;
+    reason;
+    max_carry_forward;
+    // Encapsulated mutable state — only mutable through methods on this class
+    #status;
+    #status_history;
+    #carry_forward_count;
+    constructor(init) {
+        this.obligation_id = init.obligation_id;
+        this.trigger_kind = init.trigger_kind;
+        this.detected_at = init.detected_at;
+        this.detected_after_session = init.detected_after_session;
+        this.affected_agents = init.affected_agents;
+        this.reason = init.reason;
+        this.max_carry_forward = init.max_carry_forward;
+        // Initialize status_history (default = single initial transition)
+        this.#status_history = init.status_history
+            ? [...init.status_history]
+            : [
+                {
+                    from: null,
+                    to: "pending",
+                    at: init.detected_at,
+                    reason: "initial detection",
+                    session_id: init.detected_after_session,
+                },
+            ];
+        // Construction invariant 1: status_history must be non-empty
+        if (this.#status_history.length === 0) {
+            throw new InvariantViolatedError(`AuditObligation ${init.obligation_id}: status_history cannot be empty`);
+        }
+        // Construction invariant 2: declared status must match the last history entry
+        const lastTransition = this.#status_history[this.#status_history.length - 1];
+        const declaredStatus = init.status ?? lastTransition.to;
+        if (declaredStatus !== lastTransition.to) {
+            throw new InvariantViolatedError(`AuditObligation ${init.obligation_id}: declared status (${declaredStatus}) ` +
+                `does not match last status_history.to (${lastTransition.to})`);
+        }
+        this.#status = declaredStatus;
+        // Construction invariant 3: carry_forward_count must be non-negative
+        this.#carry_forward_count = init.carry_forward_count ?? 0;
+        if (this.#carry_forward_count < 0) {
+            throw new InvariantViolatedError(`AuditObligation ${init.obligation_id}: carry_forward_count must be >= 0`);
+        }
+        if (this.max_carry_forward < 0) {
+            throw new InvariantViolatedError(`AuditObligation ${init.obligation_id}: max_carry_forward must be >= 0`);
+        }
+    }
+    // Read-only accessors. No setters by design.
+    get status() {
+        return this.#status;
+    }
+    get status_history() {
+        return this.#status_history;
+    }
+    get carry_forward_count() {
+        return this.#carry_forward_count;
+    }
+    /**
+     * Apply a state transition. Only legal way to change status.
+     *
+     * Captures `from` BEFORE mutation so the recorded transition reflects the
+     * pre-state, not the post-state (avoids the SYN-CONS-01 bug from v5 where a
+     * waive transition recorded `from: waived`).
+     */
+    transition(to, reason, context = {}) {
+        const fromStatus = this.#status;
+        if (!isLegalTransition(fromStatus, to)) {
+            throw new IllegalTransitionError(`Illegal transition: ${fromStatus} → ${to} for obligation ${this.obligation_id}`);
+        }
+        // Atomic in the sense that both updates happen together.
+        this.#status = to;
+        const transition = {
+            from: fromStatus,
+            to,
+            at: context.at ?? new Date().toISOString(),
+            reason,
+        };
+        if (context.session_id !== undefined) {
+            transition.session_id = context.session_id;
+        }
+        this.#status_history.push(transition);
+    }
+    /**
+     * Increment carry-forward count. Only legal mutation for this field.
+     * Use processCarryForward() in audit-state.ts for the carry-forward DAG;
+     * this method exists so other modules can replay the same operation.
+     */
+    incrementCarryForward() {
+        this.#carry_forward_count += 1;
+    }
+    isTerminal() {
+        return isTerminalStatus(this.#status);
+    }
+    isActive() {
+        return !this.isTerminal() && this.#status !== "expired_unattended";
+    }
+    hasExceededCarryForward() {
+        return this.#carry_forward_count > this.max_carry_forward;
+    }
+    /**
+     * Serialize to plain object for persistence.
+     * Returns a fresh copy of arrays so the caller cannot mutate internal state.
+     */
+    toJSON() {
+        return {
+            obligation_id: this.obligation_id,
+            trigger_kind: this.trigger_kind,
+            detected_at: this.detected_at,
+            detected_after_session: this.detected_after_session,
+            affected_agents: [...this.affected_agents],
+            reason: this.reason,
+            max_carry_forward: this.max_carry_forward,
+            status: this.#status,
+            status_history: this.#status_history.map((t) => ({ ...t })),
+            carry_forward_count: this.#carry_forward_count,
+        };
+    }
+    /**
+     * Deserialize from plain object. Constructor invariants enforce structural
+     * consistency, so corrupted ledger entries fail loudly here rather than at
+     * the next transition.
+     */
+    static fromJSON(data) {
+        if (data === null || typeof data !== "object") {
+            throw new InvariantViolatedError(`AuditObligation.fromJSON: data is not an object`);
+        }
+        // Check required fields explicitly so deserialization mismatches throw
+        // (NQ-21 / v9 §14.3 recommendation: explicit throw, no defaults).
+        const required = [
+            "obligation_id",
+            "trigger_kind",
+            "detected_at",
+            "detected_after_session",
+            "affected_agents",
+            "reason",
+            "max_carry_forward",
+            "status",
+            "status_history",
+            "carry_forward_count",
+        ];
+        const dataRecord = data;
+        for (const field of required) {
+            if (dataRecord[field] === undefined) {
+                throw new InvariantViolatedError(`AuditObligation.fromJSON: missing required field "${field}" ` +
+                    `(obligation_id=${data.obligation_id ?? "<unknown>"})`);
+            }
+        }
+        return new AuditObligation({
+            obligation_id: data.obligation_id,
+            trigger_kind: data.trigger_kind,
+            detected_at: data.detected_at,
+            detected_after_session: data.detected_after_session,
+            affected_agents: data.affected_agents,
+            reason: data.reason,
+            max_carry_forward: data.max_carry_forward,
+            status: data.status,
+            status_history: data.status_history,
+            carry_forward_count: data.carry_forward_count,
+        });
+    }
+}