onto-mcp 0.3.0

package/dist/core-runtime/learning/shared/specs/promote-decisions-spec.js

@@ -0,0 +1,43 @@
+/**
+ * PromoteDecisions spec — Phase B input.
+ *
+ * Persisted JSON at {sessionRoot}/promote-decisions.json. The user (or
+ * --approve-all flag) writes this between Phase A and Phase B to express
+ * which candidates to promote, retire, etc.
+ */
+import { parseRaw, serializeRaw, rejectPreV7, checkSchemaVersion, checkString, checkArray, } from "./spec-helpers.js";
+const KIND = "promote_decisions";
+const CURRENT_VERSION = "1";
+const SUPPORTED = ["1"];
+export const PromoteDecisionsSpec = {
+    kind: KIND,
+    current_schema_version: CURRENT_VERSION,
+    supported_schema_versions: SUPPORTED,
+    supported_formats: ["json"],
+    parse(content, format) {
+        const raw = parseRaw(content, format);
+        return rejectPreV7(raw, KIND, SUPPORTED);
+    },
+    serialize(data, format) {
+        return serializeRaw(data, format);
+    },
+    validate(data) {
+        const errors = [];
+        if (typeof data !== "object" || data === null) {
+            return { valid: false, errors: ["data is not an object"] };
+        }
+        const obj = data;
+        checkSchemaVersion(obj, CURRENT_VERSION, errors);
+        checkString(obj, "session_id", errors);
+        checkString(obj, "prepared_at", errors);
+        checkArray(obj, "promotions", errors);
+        checkArray(obj, "contradiction_replacements", errors);
+        checkArray(obj, "cross_agent_dedup_approvals", errors);
+        checkArray(obj, "axis_tag_changes", errors);
+        checkArray(obj, "retirements", errors);
+        checkArray(obj, "domain_doc_updates", errors);
+        checkArray(obj, "audit_outcomes", errors);
+        checkArray(obj, "audit_obligations_waived", errors);
+        return { valid: errors.length === 0, errors };
+    },
+};

package/dist/core-runtime/learning/shared/specs/promote-report-spec.js

@@ -0,0 +1,113 @@
+/**
+ * PromoteReport spec — DD-20 + SYN-U1.
+ *
+ * Phase A output, persisted as JSON. Snapshot of all collection/audit/panel
+ * data needed for Phase B to apply user decisions.
+ *
+ * SYN-U1: schema_version bumped from "1" → "2" when CrossAgentDedupCluster
+ * gained the required `primary_member_index` field. Reports produced before
+ * the bump (no primary_member_index OR a schema_version="1" header) are
+ * refused at load time with a clear regenerate-via-Phase-A message.
+ *
+ * The nested validation also traverses cross_agent_dedup_clusters to verify
+ * primary_member_index is present and structurally sound, so a schema v2
+ * report with a malformed cluster entry fails loudly rather than silently
+ * falling through to the apply-time structural guard.
+ */
+import { IncompatibleVersionError, } from "../artifact-registry.js";
+import { parseRaw, serializeRaw, rejectPreV7, checkSchemaVersion, checkString, checkArray, } from "./spec-helpers.js";
+const KIND = "promote_report";
+const CURRENT_VERSION = "2";
+const SUPPORTED = ["2"];
+export const PromoteReportSpec = {
+    kind: KIND,
+    current_schema_version: CURRENT_VERSION,
+    supported_schema_versions: SUPPORTED,
+    supported_formats: ["json"],
+    parse(content, format) {
+        const raw = parseRaw(content, format);
+        // 4-C1 fix: schema_version="1" reports from before the index-based
+        // primary_member bump get a dedicated migration message naming the
+        // specific action operator needs to take. rejectPreV7 handles the
+        // no-schema_version and wrong-version cases with a generic message;
+        // this explicit branch runs FIRST so the v1→v2 path is operator-legible.
+        if (typeof raw === "object" &&
+            raw !== null &&
+            raw.schema_version === "1") {
+            throw new IncompatibleVersionError(`${KIND}: legacy schema_version="1" detected. ` +
+                `This report was generated before the index-based primary_member identity ` +
+                `bump (v1→v2). The new Phase B apply path requires ` +
+                `cross_agent_dedup_clusters[].primary_member_index which the legacy format ` +
+                `does not carry. ` +
+                `Action: discard the legacy report, regenerate a new report, then re-run apply on the fresh session.`);
+        }
+        return rejectPreV7(raw, KIND, SUPPORTED);
+    },
+    serialize(data, format) {
+        return serializeRaw(data, format);
+    },
+    validate(data) {
+        const errors = [];
+        if (typeof data !== "object" || data === null) {
+            return { valid: false, errors: ["data is not an object"] };
+        }
+        const obj = data;
+        checkSchemaVersion(obj, CURRENT_VERSION, errors);
+        checkString(obj, "session_id", errors);
+        checkString(obj, "generated_at", errors);
+        checkString(obj, "mode", errors);
+        if (obj.collection === undefined || obj.collection === null) {
+            errors.push("collection must be present");
+        }
+        checkArray(obj, "pre_analysis", errors);
+        checkArray(obj, "panel_verdicts", errors);
+        checkArray(obj, "cross_agent_dedup_clusters", errors);
+        if (obj.audit_summary === undefined || obj.audit_summary === null) {
+            errors.push("audit_summary must be present");
+        }
+        checkArray(obj, "retirement_candidates", errors);
+        checkArray(obj, "conflict_proposals", errors);
+        checkArray(obj, "domain_doc_candidates", errors);
+        if (obj.health_snapshot === undefined || obj.health_snapshot === null) {
+            errors.push("health_snapshot must be present");
+        }
+        checkArray(obj, "degraded_states", errors);
+        checkArray(obj, "warnings", errors);
+        // SYN-U1: nested validation for cross_agent_dedup_clusters. Each cluster
+        // MUST carry primary_member_index as an integer within member_items
+        // bounds. Reports from the schema-v1 era (or mid-migration reports that
+        // forgot to populate the field) are rejected here instead of at apply
+        // time where the failure is harder to triage.
+        if (Array.isArray(obj.cross_agent_dedup_clusters)) {
+            obj.cross_agent_dedup_clusters.forEach((raw, i) => {
+                if (typeof raw !== "object" || raw === null) {
+                    errors.push(`cross_agent_dedup_clusters[${i}] is not an object`);
+                    return;
+                }
+                const c = raw;
+                if (typeof c.cluster_id !== "string") {
+                    errors.push(`cross_agent_dedup_clusters[${i}].cluster_id must be a string`);
+                }
+                if (typeof c.primary_owner_agent !== "string") {
+                    errors.push(`cross_agent_dedup_clusters[${i}].primary_owner_agent must be a string`);
+                }
+                if (typeof c.primary_member_index !== "number" ||
+                    !Number.isInteger(c.primary_member_index) ||
+                    c.primary_member_index < 0) {
+                    errors.push(`cross_agent_dedup_clusters[${i}].primary_member_index must be a non-negative integer ` +
+                        `(schema v2 required; regenerate Phase A if the report predates the bump)`);
+                }
+                if (!Array.isArray(c.member_items)) {
+                    errors.push(`cross_agent_dedup_clusters[${i}].member_items must be an array`);
+                    return;
+                }
+                if (typeof c.primary_member_index === "number" &&
+                    c.primary_member_index >= c.member_items.length) {
+                    errors.push(`cross_agent_dedup_clusters[${i}].primary_member_index (${c.primary_member_index}) ` +
+                        `out of member_items bounds (length=${c.member_items.length})`);
+                }
+            });
+        }
+        return { valid: errors.length === 0, errors };
+    },
+};

package/dist/core-runtime/learning/shared/specs/prune-log-spec.js

@@ -0,0 +1,36 @@
+/**
+ * PruneLogEntry spec — DD-16 (SYN-D-02 part 2).
+ *
+ * Append-only JSONL at ~/.onto/backups/.prune-log.jsonl. Records every
+ * checkpoint pruning event with reason and freed bytes.
+ */
+import { rejectPreV7, checkSchemaVersion, checkString, checkNumber, } from "./spec-helpers.js";
+const KIND = "prune_log_entry";
+const CURRENT_VERSION = "1";
+const SUPPORTED = ["1"];
+export const PruneLogSpec = {
+    kind: KIND,
+    current_schema_version: CURRENT_VERSION,
+    supported_schema_versions: SUPPORTED,
+    supported_formats: ["json"],
+    parse(content, _format) {
+        const raw = JSON.parse(content);
+        return rejectPreV7(raw, KIND, SUPPORTED);
+    },
+    serialize(data, _format) {
+        return JSON.stringify(data);
+    },
+    validate(data) {
+        const errors = [];
+        if (typeof data !== "object" || data === null) {
+            return { valid: false, errors: ["data is not an object"] };
+        }
+        const obj = data;
+        checkSchemaVersion(obj, CURRENT_VERSION, errors);
+        checkString(obj, "session_id", errors);
+        checkString(obj, "pruned_at", errors);
+        checkString(obj, "reason", errors);
+        checkNumber(obj, "bytes_freed", errors);
+        return { valid: errors.length === 0, errors };
+    },
+};

package/dist/core-runtime/learning/shared/specs/recovery-resolution-spec.js

@@ -0,0 +1,48 @@
+/**
+ * RecoveryResolution spec — DD-23 (NEW in v9).
+ *
+ * Persisted YAML at {projectRoot}/.onto/sessions/promote/{session-id}/recovery-resolution.yaml.
+ *
+ * Canonical operator-decision seat for cross-attempt manual escalation. When
+ * resolveRecoveryTruth() detects multiple attempt_ids, it surfaces a
+ * manual_escalation_required result. The operator records their selection in
+ * this artifact. Subsequent resume runs read it first.
+ */
+import { parseRaw, serializeRaw, rejectPreV7, checkSchemaVersion, checkString, checkArray, } from "./spec-helpers.js";
+const KIND = "recovery_resolution";
+const CURRENT_VERSION = "1";
+const SUPPORTED = ["1"];
+export const RecoveryResolutionSpec = {
+    kind: KIND,
+    current_schema_version: CURRENT_VERSION,
+    supported_schema_versions: SUPPORTED,
+    supported_formats: ["yaml"],
+    parse(content, format) {
+        const raw = parseRaw(content, format);
+        return rejectPreV7(raw, KIND, SUPPORTED);
+    },
+    serialize(data, format) {
+        return serializeRaw(data, format);
+    },
+    validate(data) {
+        const errors = [];
+        if (typeof data !== "object" || data === null) {
+            return { valid: false, errors: ["data is not an object"] };
+        }
+        const obj = data;
+        checkSchemaVersion(obj, CURRENT_VERSION, errors);
+        checkString(obj, "session_id", errors);
+        checkString(obj, "resolved_at", errors);
+        checkString(obj, "resolved_by", errors);
+        checkString(obj, "resolution_method", errors);
+        checkString(obj, "selected_attempt_id", errors);
+        checkString(obj, "selected_attempt_reason", errors);
+        checkArray(obj, "all_attempts_at_resolution_time", errors);
+        // NQ-21: append-only history. Must be non-empty when artifact exists.
+        checkArray(obj, "resolution_history", errors);
+        if (Array.isArray(obj.resolution_history) && obj.resolution_history.length === 0) {
+            errors.push("resolution_history cannot be empty");
+        }
+        return { valid: errors.length === 0, errors };
+    },
+};

package/dist/core-runtime/learning/shared/specs/restore-manifest-spec.js

@@ -0,0 +1,43 @@
+/**
+ * RestoreManifest spec — DD-16 (RESTORE-MANIFEST-01 + SYN-UF-02).
+ *
+ * Auto-generated alongside each backup directory at
+ * ~/.onto/backups/{session-id}/restore-manifest.yaml.
+ *
+ * Single canonical seat for restore commands. Recovery builders must read
+ * from manifest_path on the RecoverabilityCheckpoint, not derive paths from
+ * the backup file names.
+ */
+import { parseRaw, serializeRaw, rejectPreV7, checkSchemaVersion, checkString, checkNumber, checkArray, } from "./spec-helpers.js";
+const KIND = "restore_manifest";
+const CURRENT_VERSION = "1";
+const SUPPORTED = ["1"];
+export const RestoreManifestSpec = {
+    kind: KIND,
+    current_schema_version: CURRENT_VERSION,
+    supported_schema_versions: SUPPORTED,
+    supported_formats: ["yaml"],
+    parse(content, format) {
+        const raw = parseRaw(content, format);
+        return rejectPreV7(raw, KIND, SUPPORTED);
+    },
+    serialize(data, format) {
+        return serializeRaw(data, format);
+    },
+    validate(data) {
+        const errors = [];
+        if (typeof data !== "object" || data === null) {
+            return { valid: false, errors: ["data is not an object"] };
+        }
+        const obj = data;
+        checkSchemaVersion(obj, CURRENT_VERSION, errors);
+        checkString(obj, "session_id", errors);
+        checkString(obj, "attempt_id", errors);
+        checkNumber(obj, "generation", errors);
+        checkString(obj, "created_at", errors);
+        checkArray(obj, "backups", errors);
+        checkArray(obj, "restore_order", errors);
+        checkArray(obj, "verification_after_restore", errors);
+        return { valid: errors.length === 0, errors };
+    },
+};

package/dist/core-runtime/learning/shared/specs/spec-helpers.js

@@ -0,0 +1,64 @@
+/**
+ * Shared helpers for ArtifactSpec implementations.
+ *
+ * Why: every spec parses/serializes JSON or YAML, performs the pre-v7 detection
+ * (UF-COV-01), and validates schema_version. Centralizing the boilerplate keeps
+ * each per-artifact spec to its structural validators only.
+ */
+import * as yaml from "yaml";
+import { IncompatibleVersionError, } from "../artifact-registry.js";
+export function parseRaw(content, format) {
+    if (format === "yaml")
+        return yaml.parse(content);
+    return JSON.parse(content);
+}
+export function serializeRaw(data, format) {
+    if (format === "yaml")
+        return yaml.stringify(data);
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Detect pre-v7 artifacts (no schema_version field) and reject with a clear
+ * action message. UF-COV-01 v8.
+ */
+export function rejectPreV7(raw, kind, supportedVersions) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new IncompatibleVersionError(`${kind}: parsed content is not an object`);
+    }
+    const obj = raw;
+    if (obj.schema_version === undefined) {
+        throw new IncompatibleVersionError(`${kind}: pre-v7 artifact detected (no schema_version field). ` +
+            `Phase 3 requires schema_version. Action: discard the legacy file ` +
+            `and re-run the producing command to regenerate.`);
+    }
+    if (!supportedVersions.includes(obj.schema_version)) {
+        throw new IncompatibleVersionError(`${kind}: schema_version "${obj.schema_version}" not in supported set ` +
+            `[${supportedVersions.join(", ")}]`);
+    }
+    return obj;
+}
+export function checkString(obj, field, errors) {
+    if (typeof obj[field] !== "string") {
+        errors.push(`${field} must be a string`);
+    }
+}
+export function checkOptionalString(obj, field, errors) {
+    if (obj[field] !== undefined && typeof obj[field] !== "string") {
+        errors.push(`${field} must be a string when present`);
+    }
+}
+export function checkNumber(obj, field, errors) {
+    if (typeof obj[field] !== "number") {
+        errors.push(`${field} must be a number`);
+    }
+}
+export function checkArray(obj, field, errors) {
+    if (!Array.isArray(obj[field])) {
+        errors.push(`${field} must be an array`);
+    }
+}
+export function checkSchemaVersion(obj, expected, errors) {
+    if (obj.schema_version !== expected) {
+        errors.push(`schema_version must be "${expected}"`);
+    }
+}

package/dist/core-runtime/learning/usage-tracker.js

@@ -0,0 +1,190 @@
+/**
+ * usage-tracker.ts — Learning 활용 히트율 계측 seat
+ *
+ * W-A-72: DL-017 기제 seat (learn).
+ * 세션별 learning-manifest.yaml 에서 공급량(loaded)을 수집하고,
+ * extraction manifest 에서 추출량(saved)을, event marker 에서
+ * 무효화 건수를 종합하여 learning 기제 신뢰도 proxy 를 산출한다.
+ *
+ * 측정 대상 (§1.4 측면 3):
+ *   - 공급률: parsed → loaded 비율 (필터링 효율)
+ *   - 추출률: 세션당 새 learning 추출 건수 (학습 생산성)
+ *   - 무효화율: event marker 발생 비율 (기제 신뢰도 역지표)
+ *   - 토큰 효율: tokens_used / loaded items (학습 항목당 토큰 비용)
+ *
+ * 소비자: onto:health (W-A-59), refresh protocol (§4)
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parse as yamlParse } from "yaml";
+import { getLogger } from "../logger.js";
+// ─── Helpers ───
+function parseYamlFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        return yamlParse(raw);
+    }
+    catch {
+        getLogger().debug("usage-tracker: failed to parse YAML", { path: filePath });
+        return null;
+    }
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function emptyTier() {
+    return { t1: 0, t2: 0, t3: 0, t4: 0 };
+}
+function emptyRole() {
+    return { guardrail: 0, foundation: 0, convention: 0, unclassified: 0 };
+}
+function sumTier(a, b) {
+    return { t1: a.t1 + b.t1, t2: a.t2 + b.t2, t3: a.t3 + b.t3, t4: a.t4 + b.t4 };
+}
+function sumRole(a, b) {
+    return {
+        guardrail: a.guardrail + b.guardrail,
+        foundation: a.foundation + b.foundation,
+        convention: a.convention + b.convention,
+        unclassified: a.unclassified + b.unclassified,
+    };
+}
+function parseTierDist(raw) {
+    if (!raw)
+        return emptyTier();
+    return {
+        t1: raw["1"] ?? 0,
+        t2: raw["2"] ?? 0,
+        t3: raw["3"] ?? 0,
+        t4: raw["4"] ?? 0,
+    };
+}
+function parseRoleDist(raw) {
+    if (!raw)
+        return emptyRole();
+    return {
+        guardrail: raw["guardrail"] ?? 0,
+        foundation: raw["foundation"] ?? 0,
+        convention: raw["convention"] ?? 0,
+        unclassified: raw["unclassified"] ?? 0,
+    };
+}
+// ─── Core API ───
+/**
+ * .onto/review/ 이하 모든 세션의 learning 공급 데이터를 수집한다.
+ *
+ * @param reviewRoot - .onto/review 디렉터리 경로
+ * @returns LearningUsageSummary — 세션별 공급 요약 + 집계 metric
+ */
+export function collectLearningUsage(reviewRoot) {
+    const absRoot = resolve(reviewRoot);
+    let sessionDirs;
+    try {
+        sessionDirs = readdirSync(absRoot).filter((name) => /^\d{8}-[0-9a-f]+$/.test(name) && isDirectory(join(absRoot, name)));
+    }
+    catch {
+        getLogger().warn("usage-tracker: review root not found", { path: absRoot });
+        return emptySummary(absRoot);
+    }
+    const entries = [];
+    for (const dirName of sessionDirs) {
+        const manifestPath = join(absRoot, dirName, "execution-preparation", "learning-manifest.yaml");
+        const manifest = parseYamlFile(manifestPath);
+        if (!manifest)
+            continue;
+        const entry = parseManifest(dirName, manifest);
+        if (entry)
+            entries.push(entry);
+    }
+    // session_id 알파벳순 (= 시간순)
+    entries.sort((a, b) => a.session_id.localeCompare(b.session_id));
+    return {
+        collected_at: new Date().toISOString(),
+        review_root: absRoot,
+        total_sessions: entries.length,
+        entries,
+        aggregate: computeAggregate(entries),
+    };
+}
+function parseManifest(sessionId, raw) {
+    const loaded = raw.total_items_loaded ?? 0;
+    const parsed = raw.total_items_parsed ?? 0;
+    let totalTokens = 0;
+    let totalTruncated = 0;
+    let tierDist = emptyTier();
+    let roleDist = emptyRole();
+    for (const agent of raw.per_agent ?? []) {
+        totalTokens += agent.tokens_used ?? 0;
+        totalTruncated += agent.budget_truncated_count ?? 0;
+        tierDist = sumTier(tierDist, parseTierDist(agent.tier_distribution));
+        roleDist = sumRole(roleDist, parseRoleDist(agent.role_distribution));
+    }
+    return {
+        session_id: sessionId,
+        session_domain: raw.session_domain ?? "none",
+        agents_loaded: raw.agents_loaded ?? 0,
+        total_items_loaded: loaded,
+        total_items_parsed: parsed,
+        total_items_skipped: raw.total_items_skipped ?? 0,
+        total_tokens_used: totalTokens,
+        total_budget_truncated: totalTruncated,
+        degraded: raw.degraded ?? false,
+        tier_distribution: tierDist,
+        role_distribution: roleDist,
+    };
+}
+/**
+ * 세션 목록에서 집계 metric 을 산출한다.
+ */
+export function computeAggregate(entries) {
+    if (entries.length === 0)
+        return emptyAggregate();
+    const n = entries.length;
+    const totalLoaded = entries.reduce((s, e) => s + e.total_items_loaded, 0);
+    const totalParsed = entries.reduce((s, e) => s + e.total_items_parsed, 0);
+    const totalTokens = entries.reduce((s, e) => s + e.total_tokens_used, 0);
+    const totalTruncated = entries.reduce((s, e) => s + e.total_budget_truncated, 0);
+    const degradedCount = entries.filter((e) => e.degraded).length;
+    let tierTotal = emptyTier();
+    let roleTotal = emptyRole();
+    for (const e of entries) {
+        tierTotal = sumTier(tierTotal, e.tier_distribution);
+        roleTotal = sumRole(roleTotal, e.role_distribution);
+    }
+    return {
+        avg_items_loaded: Math.round(totalLoaded / n),
+        avg_items_parsed: Math.round(totalParsed / n),
+        supply_ratio: totalParsed > 0 ? Math.round((totalLoaded / totalParsed) * 1000) / 1000 : 0,
+        avg_tokens_used: Math.round(totalTokens / n),
+        avg_budget_truncated: Math.round(totalTruncated / n),
+        degradation_ratio: Math.round((degradedCount / n) * 1000) / 1000,
+        total_tier_distribution: tierTotal,
+        total_role_distribution: roleTotal,
+    };
+}
+function emptySummary(root) {
+    return {
+        collected_at: new Date().toISOString(),
+        review_root: root,
+        total_sessions: 0,
+        entries: [],
+        aggregate: emptyAggregate(),
+    };
+}
+function emptyAggregate() {
+    return {
+        avg_items_loaded: 0,
+        avg_items_parsed: 0,
+        supply_ratio: 0,
+        avg_tokens_used: 0,
+        avg_budget_truncated: 0,
+        degradation_ratio: 0,
+        total_tier_distribution: emptyTier(),
+        total_role_distribution: emptyRole(),
+    };
+}