onto-mcp 0.3.2 → 0.4.1

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

@@ -1,240 +0,0 @@
-/**
- * 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

@@ -1,195 +0,0 @@
-/**
- * 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,
-        });
-    }
-}