onto-mcp 0.3.2 → 0.4.0

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

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

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

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

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

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

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

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