onto-mcp 0.3.2 → 0.4.1

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

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

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

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

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