onto-mcp 0.3.0

package/dist/core-runtime/learning/shared/artifact-registry.js

@@ -0,0 +1,254 @@
+/**
+ * Artifact Registry — DD-20 (central spec management).
+ *
+ * Design authority:
+ *   - learn-phase3-design-v9.md DD-20 (lazy init + RegistryInitError + schema reject)
+ *   - learn-phase3-design-v8.md DD-20 (lazy init + write enforcement + pre-v7 reject)
+ *   - learn-phase3-design-v7.md DD-20 (introduction + spec contract)
+ *
+ * Why this exists:
+ *   1. Every persisted control artifact in Phase 3 must declare a spec
+ *      describing its kind, supported schema versions, formats, and validators.
+ *   2. Without central registration, each artifact would re-implement parsing
+ *      and version gates ad hoc — v6 review traced multiple drift bugs back to
+ *      this pattern.
+ *   3. Lazy init means runtime entry points do not need to call initArtifactRegistry()
+ *      explicitly. The first REGISTRY.loadFromFile / saveToFile call performs
+ *      registration and caches success/failure.
+ *
+ * CLI-process-scoped runtime assumption (§12.7): Phase 3 commands run in
+ * short-lived processes. Init failure caching is per-process and recovery is
+ * "restart and re-run" by design. Phase 4 daemon work must revisit this.
+ *
+ * Write-side enforcement (SYN-CC1):
+ *   - validate() runs on every save
+ *   - format binding is derived from the file extension and checked against
+ *     spec.supported_formats
+ *   - schema_version on the data object MUST match spec.current_schema_version;
+ *     undefined is rejected (SYN-CONS-03 v9 fix)
+ */
+import fs from "node:fs";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class RegistryInitError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(`Artifact registry initialization failed: ${message}`);
+        this.name = "RegistryInitError";
+        if (cause)
+            this.cause = cause;
+    }
+}
+export class IncompatibleVersionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IncompatibleVersionError";
+    }
+}
+export class InvalidArtifactError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidArtifactError";
+    }
+}
+export class UnregisteredArtifactKindError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnregisteredArtifactKindError";
+    }
+}
+export class ArtifactNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArtifactNotFoundError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+class ArtifactRegistry {
+    specs = new Map();
+    initialized = false;
+    cachedInitError = null;
+    builtinRegistrar = null;
+    /**
+     * Inject the built-in spec registrar from artifact-registry-init.ts.
+     *
+     * The init module is imported lazily (inside ensureInitialized) to break
+     * the import cycle: specs need errors from this module, init imports specs,
+     * registry needs init. Calling this from artifact-registry-init.ts after
+     * spec imports complete keeps the registrar separate from registry core.
+     */
+    setBuiltinRegistrar(registrar) {
+        this.builtinRegistrar = registrar;
+    }
+    /**
+     * Lazy initialization. Idempotent.
+     *
+     * Contract (NQ-19 v9):
+     *   - First call: invoke builtinRegistrar
+     *   - Subsequent calls: no-op
+     *   - On failure: wrap as RegistryInitError, cache, throw on every subsequent
+     *     call (CLI-process-scoped recovery is process restart only)
+     */
+    ensureInitialized() {
+        if (this.initialized)
+            return;
+        if (this.cachedInitError)
+            throw this.cachedInitError;
+        if (!this.builtinRegistrar) {
+            // The registrar is wired by artifact-registry-init.ts side-effect import.
+            // If callers reach here without that side effect, something invoked the
+            // registry before init module loaded — fail loudly.
+            this.cachedInitError = new RegistryInitError("no builtin registrar wired. Import 'artifact-registry-init.js' " +
+                "from the entry point before using REGISTRY.");
+            throw this.cachedInitError;
+        }
+        try {
+            this.builtinRegistrar();
+            this.initialized = true;
+        }
+        catch (error) {
+            this.cachedInitError = new RegistryInitError(error instanceof Error ? error.message : String(error), error instanceof Error ? error : undefined);
+            throw this.cachedInitError;
+        }
+    }
+    /**
+     * Register a spec at init time. Performs structural sanity checks so a
+     * mis-declared spec fails at registration rather than at first read/write
+     * (SYN-C2 v8 register-time consistency check).
+     */
+    register(spec) {
+        if (spec.supported_schema_versions.length === 0) {
+            throw new Error(`${spec.kind}: supported_schema_versions cannot be empty`);
+        }
+        if (!spec.supported_schema_versions.includes(spec.current_schema_version)) {
+            throw new Error(`${spec.kind}: current_schema_version "${spec.current_schema_version}" ` +
+                `not in supported_schema_versions [${spec.supported_schema_versions.join(", ")}]`);
+        }
+        if (spec.supported_schema_versions.length > 1 && !spec.migrate) {
+            throw new Error(`${spec.kind}: supports ${spec.supported_schema_versions.length} schema versions ` +
+                `but no migrate function provided`);
+        }
+        if (spec.supported_formats.length === 0) {
+            throw new Error(`${spec.kind}: supported_formats cannot be empty`);
+        }
+        if (this.specs.has(spec.kind)) {
+            throw new Error(`Duplicate artifact kind: ${spec.kind}`);
+        }
+        this.specs.set(spec.kind, spec);
+    }
+    get(kind) {
+        this.ensureInitialized();
+        const spec = this.specs.get(kind);
+        if (!spec) {
+            throw new UnregisteredArtifactKindError(`Artifact kind '${kind}' not registered. ` +
+                `Available: ${[...this.specs.keys()].sort().join(", ")}`);
+        }
+        return spec;
+    }
+    loadFromFile(kind, filePath) {
+        this.ensureInitialized();
+        const spec = this.get(kind);
+        if (!fs.existsSync(filePath)) {
+            throw new ArtifactNotFoundError(`Artifact file not found: ${filePath}`);
+        }
+        const format = formatFromPath(filePath, kind, spec);
+        const content = fs.readFileSync(filePath, "utf8");
+        const parsed = spec.parse(content, format);
+        const validation = spec.validate(parsed);
+        if (!validation.valid) {
+            throw new InvalidArtifactError(`${kind}: ${validation.errors.join(", ")}`);
+        }
+        return parsed;
+    }
+    saveToFile(kind, filePath, data) {
+        this.ensureInitialized();
+        const spec = this.get(kind);
+        // SYN-CC1 part 1: structural validation before write
+        const validation = spec.validate(data);
+        if (!validation.valid) {
+            throw new InvalidArtifactError(`${kind} validation failed: ${validation.errors.join(", ")}`);
+        }
+        // SYN-CC1 part 2: format binding from extension
+        const format = formatFromPath(filePath, kind, spec);
+        // SYN-CC1 part 3 + SYN-CONS-03 (v9): schema_version is required and must
+        // match spec.current_schema_version. undefined is rejected.
+        const dataObj = data;
+        if (dataObj.schema_version === undefined) {
+            throw new InvalidArtifactError(`${kind}: data missing required schema_version field. ` +
+                `Expected "${spec.current_schema_version}".`);
+        }
+        if (dataObj.schema_version !== spec.current_schema_version) {
+            throw new InvalidArtifactError(`${kind}: data has schema_version "${dataObj.schema_version}" ` +
+                `but spec current is "${spec.current_schema_version}".`);
+        }
+        const content = spec.serialize(data, format);
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, content, "utf8");
+    }
+    /**
+     * Append-only logs (e.g. emergency-log.jsonl, prune-log.jsonl) need a
+     * separate write entry point because they bypass the "single-data-object
+     * with schema_version" pattern. Spec.serialize is invoked per-entry; the
+     * caller is responsible for newline framing.
+     */
+    appendToFile(kind, filePath, entry) {
+        this.ensureInitialized();
+        const spec = this.get(kind);
+        const validation = spec.validate(entry);
+        if (!validation.valid) {
+            throw new InvalidArtifactError(`${kind} validation failed: ${validation.errors.join(", ")}`);
+        }
+        const dataObj = entry;
+        if (dataObj.schema_version === undefined) {
+            throw new InvalidArtifactError(`${kind}: entry missing required schema_version field.`);
+        }
+        if (dataObj.schema_version !== spec.current_schema_version) {
+            throw new InvalidArtifactError(`${kind}: entry has schema_version "${dataObj.schema_version}" ` +
+                `but spec current is "${spec.current_schema_version}".`);
+        }
+        const format = formatFromPath(filePath, kind, spec);
+        const line = spec.serialize(entry, format) + "\n";
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.appendFileSync(filePath, line, "utf8");
+    }
+    listRegistered() {
+        this.ensureInitialized();
+        return [...this.specs.keys()].sort();
+    }
+    /** Test-only reset. Not used in production code paths. */
+    __resetForTest() {
+        this.specs.clear();
+        this.initialized = false;
+        this.cachedInitError = null;
+    }
+}
+function formatFromPath(filePath, kind, spec) {
+    const ext = path.extname(filePath).slice(1).toLowerCase();
+    let format;
+    if (ext === "json" || ext === "jsonl") {
+        format = "json";
+    }
+    else if (ext === "yaml" || ext === "yml") {
+        format = "yaml";
+    }
+    else {
+        throw new Error(`${kind}: unsupported file extension ".${ext}" (path=${filePath})`);
+    }
+    if (!spec.supported_formats.includes(format)) {
+        throw new Error(`${kind}: format ${format} (from ${filePath}) not in supported_formats ` +
+            `[${spec.supported_formats.join(", ")}]`);
+    }
+    return format;
+}
+/** Singleton instance. */
+export const REGISTRY = new ArtifactRegistry();

package/dist/core-runtime/learning/shared/audit-obligation-kernel.js

@@ -0,0 +1,73 @@
+/**
+ * AuditObligation kernel — pure types and constants (DD-21 SYN-D1).
+ *
+ * Design authority: learn-phase3-design-v9.md DD-21, learn-phase3-design-v8.md DD-21.
+ *
+ * This module is intentionally dependency-free (no I/O, no class, no other
+ * modules from learning/). Other modules import enums/types from here so the
+ * dependency graph stays low and AuditObligation class can sit above this.
+ *
+ * Why kernel separation:
+ *   1. Lowers import coupling — modules that need only the type/enum (e.g., a
+ *      reporter that prints a status) do not transitively depend on the class.
+ *   2. Construction invariants in AuditObligation can reuse these constants
+ *      without circular import risk.
+ *   3. v6 review's dependency-03 finding: obligation kernel was seated too high.
+ */
+/**
+ * Legal transition matrix (DD-17 + EXPIRED-UNATTENDED-01 fix in v6 review).
+ *
+ * Rationale:
+ *   - pending: initial active state. Can move into in_progress, be waived, or
+ *     expire unattended (carry-forward exhausted before P-14 picked it up).
+ *   - in_progress: P-14 is currently processing. Terminates as fulfilled,
+ *     transient blocked, or no_eligible_agents (irrecoverable).
+ *   - blocked: transient failure (LLM timeout, etc.). Re-enters pending on the
+ *     next promote, may also be waived or expire.
+ *   - no_eligible_agents / fulfilled / waived: terminal.
+ *   - expired_unattended: ledger-visible but not strictly terminal — operator
+ *     may waive it after manual review.
+ *
+ * v6 review found that pending/blocked → expired_unattended ingress was missing
+ * from the legal transition matrix; v9 makes it explicit so the carry-forward
+ * exhaustion path is enforceable.
+ */
+export const LEGAL_TRANSITIONS = {
+    pending: ["in_progress", "waived", "expired_unattended"],
+    in_progress: ["fulfilled", "blocked", "no_eligible_agents"],
+    blocked: ["pending", "fulfilled", "waived", "expired_unattended"],
+    no_eligible_agents: [],
+    fulfilled: [],
+    waived: [],
+    expired_unattended: ["waived"],
+};
+export function isLegalTransition(from, to) {
+    return LEGAL_TRANSITIONS[from].includes(to);
+}
+/**
+ * Strictly terminal statuses — no outgoing legal transitions.
+ *
+ * Note: expired_unattended is intentionally NOT included here because the
+ * operator can waive it. Use isStrictlyTerminal() if you need the strict set,
+ * or check `isActive()` on the AuditObligation class for active/inactive.
+ */
+export const TERMINAL_STATUSES = new Set([
+    "fulfilled",
+    "no_eligible_agents",
+    "waived",
+]);
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+export class IllegalTransitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IllegalTransitionError";
+    }
+}
+export class InvariantViolatedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvariantViolatedError";
+    }
+}

package/dist/core-runtime/learning/shared/audit-state.js

@@ -0,0 +1,99 @@
+/**
+ * Audit state ledger — DD-17.
+ *
+ * Design authority:
+ *   - learn-phase3-design-v9.md DD-17
+ *   - learn-phase3-design-v6.md DD-17 (lifecycle definitions)
+ *   - learn-phase3-design-v8.md DD-21 (class boundary, no transition helper)
+ *
+ * Responsibility:
+ *   - Load/save the obligation ledger via REGISTRY
+ *   - Carry-forward processing (DD-17 lifecycle)
+ *   - Detect new obligations from PromoteReport thresholds
+ *
+ * Class boundary:
+ *   - On disk we use AuditStateJSON (plain). In memory we hold AuditObligation
+ *     class instances so DD-21 invariants are enforced.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { REGISTRY } from "./artifact-registry.js";
+import { AuditObligation } from "../promote/audit-obligation.js";
+export const DEFAULT_AUDIT_STATE_PATH = path.join(os.homedir(), ".onto", "audit-state.yaml");
+export const DEFAULT_MAX_CARRY_FORWARD = 3;
+export function getAuditStatePath(ontoHome) {
+    if (ontoHome) {
+        return path.join(ontoHome, "audit-state.yaml");
+    }
+    return DEFAULT_AUDIT_STATE_PATH;
+}
+/**
+ * Load audit state. If the file does not exist returns an empty ledger so
+ * fresh users do not need to bootstrap manually.
+ */
+export function loadAuditState(filePath) {
+    const target = filePath ?? DEFAULT_AUDIT_STATE_PATH;
+    if (!fs.existsSync(target)) {
+        return { schema_version: "1", obligations: [] };
+    }
+    const json = REGISTRY.loadFromFile("audit_state", target);
+    return {
+        schema_version: "1",
+        obligations: json.obligations.map((j) => AuditObligation.fromJSON(j)),
+    };
+}
+export function saveAuditState(state, filePath) {
+    const target = filePath ?? DEFAULT_AUDIT_STATE_PATH;
+    const json = {
+        schema_version: "1",
+        obligations: state.obligations.map((o) => o.toJSON()),
+    };
+    REGISTRY.saveToFile("audit_state", target, json);
+}
+// ---------------------------------------------------------------------------
+// Carry-forward processing
+// ---------------------------------------------------------------------------
+/**
+ * Advance the carry-forward count for all active (pending/blocked) obligations.
+ *
+ * Lifecycle (DD-17):
+ *   - blocked → pending automatically (re-entry on next promote)
+ *   - pending obligations whose count exceeds max_carry_forward → expired_unattended
+ *
+ * `expired_unattended` is intentionally NOT a terminal state — the operator
+ * can waive it. This visibility is the v6 SYN-D-01 fix: silent cleanup was
+ * a governance defect, so the obligation stays on the ledger until explicitly
+ * resolved.
+ */
+export function processCarryForward(state, sessionId) {
+    for (const ob of state.obligations) {
+        if (ob.status !== "pending" && ob.status !== "blocked")
+            continue;
+        ob.incrementCarryForward();
+        if (ob.hasExceededCarryForward()) {
+            ob.transition("expired_unattended", `carry_forward_count (${ob.carry_forward_count}) exceeded max ` +
+                `(${ob.max_carry_forward})`, { session_id: sessionId });
+            continue;
+        }
+        if (ob.status === "blocked") {
+            ob.transition("pending", `Re-entry from blocked (carry_forward ${ob.carry_forward_count})`, { session_id: sessionId });
+        }
+    }
+    return state;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+export function findObligation(state, obligationId) {
+    return state.obligations.find((o) => o.obligation_id === obligationId);
+}
+export function getExpiredUnattended(state) {
+    return state.obligations.filter((o) => o.status === "expired_unattended");
+}
+export function getActiveObligations(state) {
+    return state.obligations.filter((o) => o.isActive());
+}
+export function countCarriedForward(state) {
+    return state.obligations.filter((o) => o.carry_forward_count > 0).length;
+}

package/dist/core-runtime/learning/shared/duplicate-check.js

@@ -0,0 +1,28 @@
+/**
+ * Content-level dedup — A-10, P-3 (Phase 2/3 공용).
+ *
+ * CC2 반영: content 부분만 추출 → trim 후 exact match.
+ * 태그/소스/임팩트 차이는 A-11(semantic classifier)이 처리.
+ */
+import { CONTENT_CAPTURE } from "./patterns.js";
+/**
+ * Extract content portion from a fully assembled learning line.
+ * Returns null if the line doesn't match the expected format.
+ */
+export function extractContent(line) {
+    const match = line.match(CONTENT_CAPTURE);
+    return match?.[1]?.trim() ?? null;
+}
+/**
+ * Check if new content is an exact duplicate of any existing line's content.
+ * A-10: content-level dedup (not full-line match).
+ */
+export function isContentDuplicate(newContent, existingLines) {
+    const normalized = newContent.trim();
+    for (const line of existingLines) {
+        const existing = extractContent(line);
+        if (existing && existing === normalized)
+            return true;
+    }
+    return false;
+}