onto-mcp 0.3.0

package/dist/core-runtime/learning/promote/promoter.js

@@ -0,0 +1,307 @@
+/**
+ * Phase 3 Promote — Phase A Orchestrator (Step 10a).
+ *
+ * Design authority:
+ *   - learn-phase3-design-v9.md DD-1 (2-Phase + strict source-read-only Phase A)
+ *   - learn-phase3-design-v5.md §1.3 Phase A canonical sequence
+ *   - learn-phase3-design-v5.md DD-13/DD-19 (P-14 audit ordering + lineage)
+ *   - .onto/processes/learn/promote.md Step 1~9
+ *
+ * Responsibility:
+ *   - Strict source-read-only orchestration of Phase A:
+ *       1. Collect (collector.ts) — produces CollectionResult per DD-18 §SST
+ *       2. Pre-analysis (placeholder for P-3 exact / P-4 semantic dedup —
+ *          structural no-op; the panel evaluates criterion 5 inline)
+ *       3. Panel review (panel-reviewer.ts) — DD-2 + DD-7 + DD-12 hard gate
+ *       4. Cross-agent dedup discovery (criterion 6, LLM-driven with
+ *          Jaccard pre-filter + union-find + same-principle test)
+ *       5. Carry-forward processing on AuditState (DD-17)
+ *       6. Judgment audit P-14 (judgment-auditor.ts) — DD-13 + DD-17
+ *       7. Retirement analysis (retirement.ts) — DD-6
+ *       8. Domain doc candidate identification (domain-doc-proposer.ts) —
+ *          DD-19 Phase A part
+ *       9. Health snapshot (health-snapshot.ts) — promote.md §9
+ *      10. Persist PromoteReport via REGISTRY
+ *      11. Persist mutated AuditState (carry-forward + transitions)
+ *
+ *   - Returns the assembled PromoteReport so the CLI can present it.
+ *
+ * Scope boundary:
+ *   - NO mutation to learning files. The only persisted writes are:
+ *       - promote-report.json (PromoteReport)
+ *       - audit-state.yaml (AuditObligation transitions from carry-forward
+ *         and P-14 lifecycle)
+ *     Both are control artifacts, not user-facing learning content.
+ *
+ * Failure model:
+ *   - Collector never throws; parse_errors are surfaced in
+ *     PromoteReport.warnings.
+ *   - Panel review can produce degraded states (member_unreachable,
+ *     panel_contract_invalid, panel_minimum_unmet) — collected but Phase A
+ *     does NOT abort on them. Phase B's gate is the hard gate.
+ *   - Audit failures route through obligation lifecycle transitions.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { REGISTRY } from "../shared/artifact-registry.js";
+import { loadAuditState, saveAuditState, processCarryForward, } from "../shared/audit-state.js";
+import { collect } from "./collector.js";
+import { reviewPanel, discoverCrossAgentDedupClusters, candidateIdOf, } from "./panel-reviewer.js";
+import { runJudgmentAudit, DEFAULT_AUDIT_POLICY, } from "./judgment-auditor.js";
+import { identifyRetirementCandidates } from "./retirement.js";
+import { identifyDomainDocCandidates } from "./domain-doc-proposer.js";
+import { buildHealthSnapshot } from "./health-snapshot.js";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+function resolveSessionRoot(config) {
+    if (config.sessionRoot)
+        return config.sessionRoot;
+    return path.join(config.projectRoot, ".onto", "sessions", "promote", config.sessionId);
+}
+function resolveAuditStatePath(config) {
+    if (config.auditStatePath)
+        return config.auditStatePath;
+    const home = config.ontoHome ?? path.join(os.homedir(), ".onto");
+    return path.join(home, "audit-state.yaml");
+}
+// ---------------------------------------------------------------------------
+// Pre-analysis (P-3 exact dedup, P-4 semantic dedup) — intentionally empty
+// ---------------------------------------------------------------------------
+/**
+ * Pre-analysis pass — intentionally returns no results.
+ *
+ * The full design included P-3 (exact dedup) and P-4 (semantic dedup) before
+ * panel review, but measurement showed that the panel's criterion 5 already
+ * catches the same cases. Running a separate pre-analysis layer would create
+ * two LLM call paths for the same axis with no coverage gain. Keeping the
+ * function as an empty-result adapter rather than deleting it preserves the
+ * §1~§9 step numbering documented in .onto/processes/learn/promote.md and leaves a named
+ * extension point for a future cheap-dedup pass if measurement ever proves
+ * the panel is too expensive for this axis.
+ */
+function runPreAnalysis() {
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Phase A entry point
+// ---------------------------------------------------------------------------
+export async function runPromoter(config) {
+    const sessionRoot = resolveSessionRoot(config);
+    const auditStatePath = resolveAuditStatePath(config);
+    fs.mkdirSync(sessionRoot, { recursive: true });
+    // -------------------------------------------------------------------------
+    // Step 1: Collect — DD-18 §SST canonical seats
+    // -------------------------------------------------------------------------
+    const collection = collect({
+        mode: config.mode,
+        projectRoot: config.projectRoot,
+    });
+    const warnings = [];
+    if (collection.parse_errors.length > 0) {
+        warnings.push(`${collection.parse_errors.length} learning lines failed to parse — ` +
+            `see parse_errors. These items are excluded from this session.`);
+    }
+    // -------------------------------------------------------------------------
+    // Step 2: Pre-analysis (stub)
+    // -------------------------------------------------------------------------
+    const pre_analysis = runPreAnalysis();
+    // -------------------------------------------------------------------------
+    // Step 3: Panel review — DD-2 + DD-7 + DD-12
+    // -------------------------------------------------------------------------
+    let panelVerdicts = [];
+    let degradedFromPanel = [];
+    if (!config.skipPanel && collection.candidate_items.length > 0) {
+        const panelResult = await reviewPanel({
+            candidates: collection.candidate_items,
+            globalItems: collection.global_items,
+            ...(config.ontoHome !== undefined ? { ontoHome: config.ontoHome } : {}),
+            ...(config.modelId !== undefined ? { modelId: config.modelId } : {}),
+        });
+        panelVerdicts = panelResult.verdicts;
+        degradedFromPanel = panelResult.degraded_states;
+    }
+    else if (config.skipPanel) {
+        warnings.push("Panel review skipped (skipPanel=true). " +
+            "PromoteReport contains zero panel_verdicts.");
+    }
+    // -------------------------------------------------------------------------
+    // Step 4: Cross-agent dedup (criterion 6) — LLM-driven
+    // -------------------------------------------------------------------------
+    // Discovery runs only when the panel also ran AND there are candidate
+    // items (U1 fix: criterion 6 inspects candidate-vs-global + cross-candidate
+    // principle duplication. With zero candidates there is nothing to evaluate,
+    // even if global_items is populated — running the LLM on a global-only pool
+    // would burn cost without producing actionable clusters.)
+    //
+    // Bounded loss metrics (C4) are captured regardless of whether clusters
+    // were emitted and surfaced as warnings so the report never looks more
+    // complete than the actual work performed.
+    let cross_agent_dedup_clusters = [];
+    if (!config.skipPanel && collection.candidate_items.length > 0) {
+        const discovery = await discoverCrossAgentDedupClusters(collection.candidate_items, collection.global_items, config.modelId !== undefined ? { modelId: config.modelId } : {});
+        cross_agent_dedup_clusters = discovery.clusters;
+        // C4: surface bounded-loss signals as warnings. Each channel surfaces
+        // a human-readable line so report consumers see what was dropped.
+        const m = discovery.metrics;
+        if (m.shortlists_cap_dropped_count > 0) {
+            warnings.push(`cross_agent_dedup: ${m.shortlists_cap_dropped_count} valid shortlist(s) ` +
+                `dropped because total exceeded MAX_SHORTLISTS_PER_RUN cap.`);
+        }
+        if (m.shortlists_truncated_count > 0) {
+            warnings.push(`cross_agent_dedup: ${m.shortlists_truncated_count} shortlist(s) truncated ` +
+                `(${m.members_truncated_total} total member(s) removed) by MAX_ITEMS_PER_SHORTLIST cap.`);
+        }
+        const totalLlmFailures = m.llm_failures.provider_error +
+            m.llm_failures.malformed_json +
+            m.llm_failures.missing_field +
+            m.llm_failures.primary_owner_not_in_shortlist;
+        if (totalLlmFailures > 0) {
+            warnings.push(`cross_agent_dedup: ${totalLlmFailures} shortlist(s) dropped due to LLM failures ` +
+                `(provider_error=${m.llm_failures.provider_error}, malformed_json=${m.llm_failures.malformed_json}, ` +
+                `missing_field=${m.llm_failures.missing_field}, primary_owner_not_in_shortlist=${m.llm_failures.primary_owner_not_in_shortlist}).`);
+        }
+        // UF2: same_principle_rejected is not a failure but operators may still
+        // want to see the count for calibration — surface it as an info-tier
+        // warning when non-zero.
+        if (m.same_principle_rejected > 0) {
+            warnings.push(`cross_agent_dedup: ${m.same_principle_rejected} shortlist(s) returned ` +
+                `same_principle=false (not the same principle — valid negative classification).`);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Step 5: Audit-state carry-forward + Step 6: P-14 judgment audit
+    // -------------------------------------------------------------------------
+    let auditState = loadAuditState(auditStatePath);
+    auditState = processCarryForward(auditState, config.sessionId);
+    let auditOutcomes = {
+        policy: config.auditPolicy ?? DEFAULT_AUDIT_POLICY,
+        obligations_processed: [],
+        eligibility: [],
+        execution: { audited_agents: [], audited_items_count: 0, llm_calls: 0 },
+        outcomes: { retain: 0, modify: 0, delete: 0, audit_to_conflict_proposal: 0 },
+        failed_agents: [],
+    };
+    const auditConflictProposals = [];
+    if (!config.skipAudit) {
+        const auditResult = await runJudgmentAudit({
+            globalItems: collection.global_items,
+            state: auditState,
+            sessionId: config.sessionId,
+            ...(config.auditPolicy !== undefined
+                ? { policy: config.auditPolicy }
+                : {}),
+            ...(config.modelId !== undefined ? { modelId: config.modelId } : {}),
+        });
+        auditOutcomes = auditResult.summary;
+        // DD-19 lineage: audit_to_conflict_proposal outcomes flow into
+        // ConflictProposal[] with origin="judgment_audit" + obligation linkage.
+        for (const outcome of auditResult.outcomes) {
+            if (outcome.decision !== "audit_to_conflict_proposal")
+                continue;
+            auditConflictProposals.push({
+                source_session_id: config.sessionId,
+                lens_id: outcome.agent_id,
+                new_item_line: outcome.item.raw_line,
+                matched_existing_line: outcome.item.raw_line,
+                decision: "conflict_propose_keep",
+                conflict_kind: "contradiction",
+                reason: outcome.reason,
+            });
+        }
+    }
+    else {
+        warnings.push("Judgment audit skipped (skipAudit=true).");
+    }
+    // -------------------------------------------------------------------------
+    // Step 7: Retirement analysis — DD-6
+    // -------------------------------------------------------------------------
+    // W-C-06 scope 명시: retirement 는 GLOBAL scope 대상 (promoted items).
+    // panel_verdicts (Step 3~6) 는 PROJECT scope 대상. 두 signal 의 scope 가 다름은 의도적.
+    const retirement_candidates = identifyRetirementCandidates(collection.global_items);
+    // -------------------------------------------------------------------------
+    // Step 8: Domain doc candidates — DD-19 Phase A part
+    // -------------------------------------------------------------------------
+    const domain_doc_candidates = identifyDomainDocCandidates(panelVerdicts);
+    // -------------------------------------------------------------------------
+    // Step 9: Health snapshot — promote.md §9
+    // -------------------------------------------------------------------------
+    const health_snapshot = buildHealthSnapshot({
+        globalItems: collection.global_items,
+        panelVerdicts,
+        retirementCandidates: retirement_candidates,
+        crossAgentDedupClusters: cross_agent_dedup_clusters,
+        extras: {
+            axis_tag_re_evaluation_changes_this_session: countAxisTagChanges(panelVerdicts),
+            creation_gate_failures: collection.global_items.filter((item) => item.raw_line.includes("tag-incomplete")).length,
+            applied_learnings_aggregate: { yes: 0, no: 0 },
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Step 10: Build PromoteReport
+    // -------------------------------------------------------------------------
+    const generated_at = new Date().toISOString();
+    // ConflictProposal[] is audit-derived only. The collector does not produce
+    // conflict proposals on its own — Phase 2 ConflictProposal merging lives in
+    // the extraction pipeline, not the Phase 3 collector. All entries here come
+    // from the judgment-auditor's audit_to_conflict_proposal outcomes.
+    const conflict_proposals = auditConflictProposals;
+    const report = {
+        schema_version: "2",
+        session_id: config.sessionId,
+        generated_at,
+        mode: config.mode,
+        collection,
+        pre_analysis,
+        panel_verdicts: panelVerdicts,
+        cross_agent_dedup_clusters,
+        audit_summary: auditOutcomes,
+        retirement_candidates,
+        conflict_proposals,
+        domain_doc_candidates,
+        health_snapshot,
+        degraded_states: degradedFromPanel,
+        warnings,
+    };
+    // -------------------------------------------------------------------------
+    // Step 11: Persist via REGISTRY
+    // -------------------------------------------------------------------------
+    const reportPath = path.join(sessionRoot, "promote-report.json");
+    REGISTRY.saveToFile("promote_report", reportPath, report);
+    // Persist the mutated audit state (carry-forward + P-14 transitions). The
+    // ledger lives outside the session root because it's the canonical
+    // cross-session truth (DD-17 SYN-UF-03).
+    saveAuditState(auditState, auditStatePath);
+    return {
+        report,
+        reportPath,
+        auditStatePath,
+        sessionRoot,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Count panel verdicts whose axis_tag_recommendation differs from "retain".
+ *
+ * This is the per-session axis tag re-evaluation churn — promote.md §9
+ * exposes it so operators can spot taxonomies that are still settling.
+ */
+function countAxisTagChanges(verdicts) {
+    let count = 0;
+    for (const v of verdicts) {
+        for (const r of v.member_reviews) {
+            if (r.axis_tag_recommendation !== "retain" &&
+                r.axis_tag_recommendation !== "no_recommendation") {
+                count += 1;
+                break; // count once per candidate
+            }
+        }
+    }
+    return count;
+}
+// Re-export for CLI consumers needing to compute candidate ids over a
+// loaded report (e.g., to match a user's "promote 1,3" selection).
+export { candidateIdOf };

package/dist/core-runtime/learning/promote/retirement.js

@@ -0,0 +1,122 @@
+/**
+ * Phase 3 Promote — Retirement analyzer (Step 9a).
+ *
+ * Design authority:
+ *   - learn-phase3-design-v2.md DD-6 (event marker 기반 퇴역)
+ *   - .onto/processes/learn/promote.md Step 4a (event marker review)
+ *
+ * Responsibility:
+ *   - Identify global learnings carrying 2+ event markers (`applied-then-found-invalid`)
+ *     since the most recent `retention-confirmed` checkpoint, surface them as
+ *     retirement candidates for the operator's Step 5 review.
+ *
+ * Scope:
+ *   - Phase A only. No mutation. The actual retirement (file edits) happens
+ *     in Phase B promote-executor with explicit decisions.
+ *
+ * Marker grammar (collector.ts emits the full comment text):
+ *   <!-- applied-then-found-invalid: YYYY-MM-DD, <excerpt>, target:<learning_id> -->
+ *   <!-- retention-confirmed: YYYY-MM-DD -->
+ *
+ * Cutoff rule (promote.md §4a):
+ *   When `retention_confirmed_at` is set, only event markers with a date
+ *   STRICTLY AFTER that timestamp are counted toward the 2+ threshold.
+ *   Markers attached before retention-confirmed are considered already
+ *   reviewed and explicitly retained.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** DD-6 minimum threshold. The design fixes this at 2 — see promote.md §4a. */
+export const RETIREMENT_MARKER_THRESHOLD = 2;
+const EVENT_MARKER_DATE_RE = /<!--\s*(?:applied-then-found-invalid|observed-obsolete):\s*(\d{4}-\d{2}-\d{2})/;
+// ---------------------------------------------------------------------------
+// Marker date parsing
+// ---------------------------------------------------------------------------
+/**
+ * Extract the YYYY-MM-DD prefix from an event marker comment string.
+ *
+ * Returns null when the marker text is malformed (no date prefix). The
+ * collector currently writes well-formed markers, but legacy items written by
+ * humans before Phase 2 may have looser shapes — those are dropped from the
+ * count rather than triggering an error.
+ */
+function parseMarkerDate(markerText) {
+    const m = markerText.match(EVENT_MARKER_DATE_RE);
+    return m ? m[1] : null;
+}
+/**
+ * Compare two ISO date strings (YYYY-MM-DD). Lexicographic == chronological.
+ */
+function isStrictlyAfter(date, cutoff) {
+    return date > cutoff;
+}
+function analyzeItemMarkers(item) {
+    const countable = [];
+    const excluded = [];
+    const undated = [];
+    for (const marker of item.event_markers) {
+        const date = parseMarkerDate(marker);
+        if (date === null) {
+            undated.push(marker);
+            continue;
+        }
+        if (item.retention_confirmed_at !== null &&
+            !isStrictlyAfter(date, item.retention_confirmed_at)) {
+            excluded.push(marker);
+            continue;
+        }
+        countable.push(marker);
+    }
+    return {
+        countable,
+        excluded_by_retention: excluded,
+        undated,
+    };
+}
+/**
+ * Identify retirement candidates from a global item pool.
+ *
+ * Input is the global slice of CollectionResult (`global_items`). Project
+ * items are excluded because retirement targets already-promoted learnings.
+ * The promote.md §4a wording explicitly limits this to global learnings.
+ *
+ * Returns one candidate per item that crossed the threshold. The reason
+ * string is human-readable so the operator can decide without re-running
+ * analysis. Marker counts are exposed in `marker_count` so a downstream
+ * UI can sort by severity.
+ */
+export function identifyRetirementCandidates(globalItems, config = {}) {
+    const threshold = config.threshold ?? RETIREMENT_MARKER_THRESHOLD;
+    const candidates = [];
+    for (const item of globalItems) {
+        if (item.event_markers.length === 0)
+            continue;
+        const analysis = analyzeItemMarkers(item);
+        if (analysis.countable.length < threshold)
+            continue;
+        const reasonParts = [
+            `${analysis.countable.length} event marker(s) since` +
+                (item.retention_confirmed_at
+                    ? ` retention-confirmed (${item.retention_confirmed_at})`
+                    : " creation"),
+        ];
+        if (analysis.excluded_by_retention.length > 0) {
+            reasonParts.push(`${analysis.excluded_by_retention.length} marker(s) excluded by retention-confirmed cutoff`);
+        }
+        if (analysis.undated.length > 0) {
+            reasonParts.push(`${analysis.undated.length} undated marker(s) ignored`);
+        }
+        candidates.push({
+            item,
+            marker_count: analysis.countable.length,
+            markers: analysis.countable,
+            retention_confirmed_at: item.retention_confirmed_at,
+            reason: reasonParts.join("; "),
+        });
+    }
+    // Sort by severity (highest marker_count first) so reviewers see hot spots
+    // at the top of the report.
+    candidates.sort((a, b) => b.marker_count - a.marker_count);
+    return candidates;
+}

package/dist/core-runtime/learning/promote/types.js

@@ -0,0 +1,23 @@
+/**
+ * Phase 3 Promote — Type definitions.
+ *
+ * Design authority:
+ *   - learn-phase3-design-v9.md (final)
+ *   - learn-phase3-design-v8.md (DD-1~DD-22 base)
+ *   - learn-phase3-design-v7.md (DD-20/21/22 introduction)
+ *   - learn-phase3-design-v6.md (DD-1~DD-19 body)
+ *
+ * This module is the canonical type seat for promote pipeline. Modules under
+ * src/core-runtime/learning/promote/ import their interfaces from here.
+ *
+ * Layering:
+ *   - Phase A (source-read-only): collection → audit → panel review → report
+ *   - Phase B (mutation): decisions → checkpoint → apply → state persist
+ *
+ * Naming convention:
+ *   - kind: discriminator on union types (e.g., "promote" | "reclassify-insights")
+ *   - schema_version: persisted artifact version (DD-20)
+ *   - attempt_id: ULID, unique per Phase B attempt (DD-22)
+ *   - generation: monotonic within an attempt (DD-22)
+ */
+export {};

package/dist/core-runtime/learning/prompt-sections.js

@@ -0,0 +1,51 @@
+/**
+ * Prompt section renderers for Phase 2 — §1.6 Newly Learned + §1.7 Event Markers.
+ *
+ * Injected into lens prompt packets when extract mode is shadow or active.
+ * CON-4 해소: Phase 2 배포 시 주입 시작.
+ */
+/**
+ * §1.6: Newly Learned prompt instructions.
+ * Tells the LLM how to output new learnings in structured format.
+ */
+export function renderNewlyLearnedInstructions(sessionDomain) {
+    const domainExample = sessionDomain && sessionDomain !== "none" && sessionDomain !== "@-"
+        ? `domain/${sessionDomain}`
+        : "domain/{name}";
+    return `
+## Learning Extraction
+
+After completing your review, include a "### Newly Learned" section at the end of your output.
+
+### Newly Learned
+- [{fact|judgment}] [methodology|${domainExample}]+ [{guardrail|foundation|convention}]? {content} [impact:{high|normal}]
+
+Rules:
+- type is required: fact (objective) or judgment (subjective assessment)
+- applicability: at least one tag. Use [methodology] for cross-domain learnings, [${domainExample}] for domain-specific
+- role is optional: [guardrail] for safety/correctness rules, [foundation] for core principles, [convention] for style/naming
+- For guardrail items, include: **Situation**: ... **Result**: ... **Corrective action**: ...
+- impact: [impact:high] for critical learnings, [impact:normal] for standard
+- source metadata is automatically added by the system. Do NOT write (source: ...) yourself
+- If you have no new learnings: write "- none"
+
+PROHIBITION: Do NOT write to learning files directly.
+Write learnings ONLY in the ### Newly Learned section of your output.
+The extraction pipeline will process and store them.
+Do NOT use the Write tool on any file under .onto/learnings/.`;
+}
+/**
+ * §1.7: Event Marker prompt instructions.
+ * Tells the LLM how to report problematic applied learnings.
+ */
+export function renderEventMarkerInstructions() {
+    return `
+### Applied Learnings — Event Markers
+
+If during your review you applied a prior learning and found it to be harmful or incorrect, report it here:
+- marker: applied-then-found-invalid
+- learning_excerpt: <identifiable excerpt from the learning>
+- reason: <why the learning was harmful or incorrect>
+
+If no markers to report, omit this section entirely.`;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Built-in artifact spec registration — DD-20.
+ *
+ * Importing this module wires the registrar into REGISTRY. The registrar runs
+ * lazily on first REGISTRY use. Other modules import this once at process
+ * entry to ensure REGISTRY can resolve canonical kinds.
+ *
+ * Why a separate module:
+ *   - Breaks the import cycle (registry needs init, init imports specs,
+ *     specs need registry types).
+ *   - Allows tests to swap in alternative spec sets via __resetForTest +
+ *     manual register() calls without re-running this module.
+ */
+import { REGISTRY } from "./artifact-registry.js";
+import { PromoteReportSpec } from "./specs/promote-report-spec.js";
+import { AuditStateSpec } from "./specs/audit-state-spec.js";
+import { EmergencyLogSpec } from "./specs/emergency-log-spec.js";
+import { LayoutVersionSpec } from "./specs/layout-version-spec.js";
+import { RestoreManifestSpec } from "./specs/restore-manifest-spec.js";
+import { PruneLogSpec } from "./specs/prune-log-spec.js";
+import { ApplyExecutionStateSpec } from "./specs/apply-execution-state-spec.js";
+import { BackupMetadataSpec } from "./specs/backup-metadata-spec.js";
+import { PromoteDecisionsSpec } from "./specs/promote-decisions-spec.js";
+import { RecoveryResolutionSpec } from "./specs/recovery-resolution-spec.js";
+REGISTRY.setBuiltinRegistrar(() => {
+    REGISTRY.register(PromoteReportSpec);
+    REGISTRY.register(AuditStateSpec);
+    REGISTRY.register(EmergencyLogSpec);
+    REGISTRY.register(LayoutVersionSpec);
+    REGISTRY.register(RestoreManifestSpec);
+    REGISTRY.register(PruneLogSpec);
+    REGISTRY.register(ApplyExecutionStateSpec);
+    REGISTRY.register(BackupMetadataSpec);
+    REGISTRY.register(PromoteDecisionsSpec);
+    REGISTRY.register(RecoveryResolutionSpec);
+});
+/**
+ * Convenience for tests and explicit init paths. Idempotent: the registrar
+ * itself is idempotent inside the registry.
+ */
+export function ensureRegistryReady() {
+    // Touching REGISTRY.listRegistered() forces ensureInitialized() without
+    // requiring a real artifact load.
+    REGISTRY.listRegistered();
+}