onto-mcp 0.3.0

package/dist/core-runtime/review/review-config-legacy-translate.js

@@ -0,0 +1,244 @@
+/**
+ * Review UX Redesign P1 — legacy → v3 axis translation (pure functions).
+ *
+ * # What this module is
+ *
+ * Two pure translators that convert **legacy** config representations
+ * (`execution_topology_priority` entries, or legacy provider-profile YAML)
+ * into the new `OntoReviewConfig` axis form:
+ *
+ *   - `legacyTopologyIdToAxes(id)` — single topology id → partial axes.
+ *   - `legacyFieldsToReviewConfig(raw)` — top-level YAML (possibly holding
+ *     `execution_topology_priority`) → partial `OntoReviewConfig`.
+ *
+ * # Why it exists
+ *
+ * P4 (onboard) and P5 (`onto config`) migrate existing configs to the new
+ * schema. Doing the translation in a pure, side-effect-free module means
+ * both flows share identical semantics and P1 can ship coverage tests
+ * without any runtime wiring. P1 does NOT call these functions from
+ * runtime — they are library-only.
+ *
+ * # How it relates
+ *
+ * - Input: legacy identifier(s) from the existing sketch-v3 schema.
+ * - Output: `Partial<OntoReviewConfig>` — caller overlays remaining
+ *   user preferences (effort, concurrency) on top.
+ * - Mapping table: see design doc §7.2 (authoritative).
+ *
+ * # Scope note (post-P9.2, 2026-04-21)
+ *
+ * P9.2 removed `execution_topology_priority` from the `OntoConfig` type.
+ * In-process code can no longer carry this field, so this translator's
+ * only remaining caller is **disk-based legacy YAML migration** (onboard
+ * re-detect reading an old `.onto/config.yml` before any typing pass).
+ * The `raw` parameter stays typed as `Record<string, unknown>` precisely
+ * to support that pre-type reading — the input shape is what YAML
+ * produced, not a current OntoConfig.
+ */
+// ---------------------------------------------------------------------------
+// Legacy topology id → axes
+// ---------------------------------------------------------------------------
+/**
+ * Translate a single legacy topology id (from `execution_topology_priority`)
+ * to partial axis config.
+ *
+ * Returns `null` for:
+ *   - Unknown ids.
+ *   - `generic-*` ids (explicitly marked "unimplemented / invalid" in
+ *     design doc §7.2, dropped from the v3 catalog).
+ *
+ * Mapping table is the authoritative design doc §7.2.
+ */
+export function legacyTopologyIdToAxes(id) {
+    switch (id) {
+        case "cc-main-agent-subagent":
+            return {
+                teamlead: { model: "main" },
+                subagent: { provider: "main-native" },
+                runtime_preconditions: {},
+            };
+        case "cc-main-codex-subprocess":
+            return {
+                teamlead: { model: "main" },
+                subagent: {
+                    provider: "codex",
+                    // model_id is required by the discriminated union. Legacy configs
+                    // did not carry it at this level (codex.* block held it). Caller
+                    // overlays from `config.codex.model` if available; absent that,
+                    // the validator will later flag this partial translation.
+                    model_id: "",
+                },
+                runtime_preconditions: {},
+            };
+        case "cc-teams-agent-subagent":
+            return {
+                teamlead: { model: "main" },
+                subagent: { provider: "main-native" },
+                runtime_preconditions: {
+                    requires_agent_teams_env: true,
+                },
+            };
+        case "cc-teams-codex-subprocess":
+            return {
+                teamlead: { model: "main" },
+                subagent: {
+                    provider: "codex",
+                    model_id: "",
+                },
+                runtime_preconditions: {
+                    requires_agent_teams_env: true,
+                },
+            };
+        case "cc-teams-litellm-sessions":
+            return {
+                teamlead: { model: "main" },
+                subagent: {
+                    provider: "litellm",
+                    model_id: "",
+                },
+                runtime_preconditions: {
+                    requires_agent_teams_env: true,
+                },
+            };
+        case "cc-teams-lens-agent-deliberation":
+            return {
+                teamlead: { model: "main" },
+                subagent: { provider: "main-native" },
+                lens_deliberation: "sendmessage-a2a",
+                runtime_preconditions: {
+                    requires_agent_teams_env: true,
+                },
+            };
+        case "codex-main-subprocess":
+            return {
+                teamlead: { model: "main" },
+                subagent: { provider: "main-native" },
+                runtime_preconditions: {
+                    implies_host_codex: true,
+                },
+            };
+        case "codex-nested-subprocess":
+            return {
+                teamlead: {
+                    model: {
+                        provider: "codex",
+                        model_id: "",
+                    },
+                },
+                subagent: {
+                    provider: "codex",
+                    model_id: "",
+                },
+                runtime_preconditions: {
+                    implies_host_plain_terminal: true,
+                },
+            };
+        // generic-nested-subagent / generic-main-subagent: dropped per §7.2.
+        default:
+            return null;
+    }
+}
+/**
+ * Translate a legacy-shaped YAML object (top-level, post-cast) to partial
+ * OntoReviewConfig. Consults `execution_topology_priority` first entry and
+ * overlays model/effort from per-provider blocks (codex.*, litellm.*, etc.)
+ * when available.
+ *
+ * Returns `null` when no legacy signal is present (no
+ * `execution_topology_priority` entry and no recognized provider block).
+ */
+export function legacyFieldsToReviewConfig(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const obj = raw;
+    const priority = obj.execution_topology_priority;
+    if (!Array.isArray(priority) || priority.length === 0) {
+        return null;
+    }
+    const firstId = priority[0];
+    if (typeof firstId !== "string") {
+        return null;
+    }
+    const axes = legacyTopologyIdToAxes(firstId);
+    if (!axes) {
+        return null;
+    }
+    const warnings = [];
+    const out = {};
+    if (axes.teamlead) {
+        out.teamlead = overlayTeamleadModelFields(axes.teamlead, obj, warnings);
+    }
+    if (axes.subagent) {
+        out.subagent = overlaySubagentModelFields(axes.subagent, obj, warnings);
+    }
+    if (axes.lens_deliberation) {
+        out.lens_deliberation = axes.lens_deliberation;
+    }
+    return {
+        config: out,
+        source_topology_id: firstId,
+        runtime_preconditions: axes.runtime_preconditions,
+        warnings,
+    };
+}
+function overlayTeamleadModelFields(teamlead, raw, warnings) {
+    if (teamlead.model === "main") {
+        return teamlead;
+    }
+    // External teamlead — overlay model_id / effort from legacy per-provider
+    // block (only codex is reachable via current legacy topology ids).
+    const provider = teamlead.model.provider;
+    const block = readProviderBlock(raw, provider);
+    const modelId = teamlead.model.model_id || readModelIdFromBlock(block) || "";
+    const effort = teamlead.model.effort || readEffortFromBlock(block);
+    if (!modelId) {
+        warnings.push(`teamlead.model.model_id 미지정 — 기존 config 의 ${provider}.model 이 없습니다. ` +
+            "새 config 의 teamlead.model.model_id 를 직접 채워주세요.");
+    }
+    return {
+        model: {
+            provider,
+            model_id: modelId,
+            ...(effort ? { effort } : {}),
+        },
+    };
+}
+function overlaySubagentModelFields(subagent, raw, warnings) {
+    if (subagent.provider === "main-native") {
+        return subagent;
+    }
+    const provider = subagent.provider;
+    const block = readProviderBlock(raw, provider);
+    const modelId = subagent.model_id || readModelIdFromBlock(block) || "";
+    const effort = subagent.effort || readEffortFromBlock(block);
+    if (!modelId) {
+        warnings.push(`subagent.model_id 미지정 — 기존 config 의 ${provider}.model 이 없습니다. ` +
+            "새 config 의 subagent.model_id 를 직접 채워주세요.");
+    }
+    return {
+        provider,
+        model_id: modelId,
+        ...(effort ? { effort } : {}),
+    };
+}
+function readProviderBlock(raw, provider) {
+    const block = raw[provider];
+    if (typeof block === "object" && block !== null && !Array.isArray(block)) {
+        return block;
+    }
+    return null;
+}
+function readModelIdFromBlock(block) {
+    if (!block)
+        return null;
+    const model = block.model;
+    return typeof model === "string" && model.length > 0 ? model : null;
+}
+function readEffortFromBlock(block) {
+    if (!block)
+        return null;
+    const effort = block.effort;
+    return typeof effort === "string" && effort.length > 0 ? effort : null;
+}

package/dist/core-runtime/review/review-config-legacy-translate.test.js

@@ -0,0 +1,161 @@
+import { describe, it, expect } from "vitest";
+import { legacyFieldsToReviewConfig, legacyTopologyIdToAxes, } from "./review-config-legacy-translate.js";
+// ---------------------------------------------------------------------------
+// legacy translation — Review UX Redesign P1 (2026-04-20)
+// ---------------------------------------------------------------------------
+//
+// Authoritative mapping table: design doc §7.2.
+// - 8 known legacy topology ids → partial axes (each with specific runtime
+//   preconditions where applicable).
+// - 2 generic-* ids → null (dropped from v3 catalog).
+// - unknown ids → null.
+//
+// legacyFieldsToReviewConfig also overlays model_id / effort from legacy
+// per-provider blocks (codex.* / litellm.* / etc.) into the translated axes.
+// ---------------------------------------------------------------------------
+describe("legacyTopologyIdToAxes — §7.2 mapping table", () => {
+    it("cc-main-agent-subagent → teamlead=main, subagent=main-native", () => {
+        const a = legacyTopologyIdToAxes("cc-main-agent-subagent");
+        expect(a).not.toBeNull();
+        expect(a?.teamlead).toEqual({ model: "main" });
+        expect(a?.subagent).toEqual({ provider: "main-native" });
+        expect(a?.runtime_preconditions).toEqual({});
+    });
+    it("cc-main-codex-subprocess → teamlead=main, subagent=codex", () => {
+        const a = legacyTopologyIdToAxes("cc-main-codex-subprocess");
+        expect(a?.subagent).toMatchObject({ provider: "codex" });
+        expect(a?.runtime_preconditions).toEqual({});
+    });
+    it("cc-teams-agent-subagent → requires_agent_teams_env=true", () => {
+        const a = legacyTopologyIdToAxes("cc-teams-agent-subagent");
+        expect(a?.subagent).toEqual({ provider: "main-native" });
+        expect(a?.runtime_preconditions.requires_agent_teams_env).toBe(true);
+    });
+    it("cc-teams-codex-subprocess → requires_agent_teams_env=true + codex", () => {
+        const a = legacyTopologyIdToAxes("cc-teams-codex-subprocess");
+        expect(a?.subagent).toMatchObject({ provider: "codex" });
+        expect(a?.runtime_preconditions.requires_agent_teams_env).toBe(true);
+    });
+    it("cc-teams-litellm-sessions → requires_agent_teams_env=true + litellm", () => {
+        const a = legacyTopologyIdToAxes("cc-teams-litellm-sessions");
+        expect(a?.subagent).toMatchObject({ provider: "litellm" });
+        expect(a?.runtime_preconditions.requires_agent_teams_env).toBe(true);
+    });
+    it("cc-teams-lens-agent-deliberation → lens_deliberation=sendmessage-a2a", () => {
+        const a = legacyTopologyIdToAxes("cc-teams-lens-agent-deliberation");
+        expect(a?.subagent).toEqual({ provider: "main-native" });
+        expect(a?.lens_deliberation).toBe("sendmessage-a2a");
+        expect(a?.runtime_preconditions.requires_agent_teams_env).toBe(true);
+    });
+    it("codex-main-subprocess → implies_host_codex=true", () => {
+        const a = legacyTopologyIdToAxes("codex-main-subprocess");
+        expect(a?.subagent).toEqual({ provider: "main-native" });
+        expect(a?.runtime_preconditions.implies_host_codex).toBe(true);
+    });
+    it("codex-nested-subprocess → external teamlead=codex + plain-terminal host", () => {
+        const a = legacyTopologyIdToAxes("codex-nested-subprocess");
+        expect(a?.teamlead?.model).toMatchObject({ provider: "codex" });
+        expect(a?.subagent).toMatchObject({ provider: "codex" });
+        expect(a?.runtime_preconditions.implies_host_plain_terminal).toBe(true);
+    });
+    it("generic-nested-subagent → null (dropped from v3 catalog)", () => {
+        expect(legacyTopologyIdToAxes("generic-nested-subagent")).toBeNull();
+    });
+    it("generic-main-subagent → null (dropped from v3 catalog)", () => {
+        expect(legacyTopologyIdToAxes("generic-main-subagent")).toBeNull();
+    });
+    it("unknown id → null", () => {
+        expect(legacyTopologyIdToAxes("not-a-real-topology")).toBeNull();
+        expect(legacyTopologyIdToAxes("")).toBeNull();
+    });
+});
+describe("legacyFieldsToReviewConfig — overlay provider blocks", () => {
+    it("returns null when no execution_topology_priority", () => {
+        expect(legacyFieldsToReviewConfig({})).toBeNull();
+        expect(legacyFieldsToReviewConfig({ codex: { model: "gpt-5.4" } })).toBeNull();
+    });
+    it("returns null for empty priority array", () => {
+        expect(legacyFieldsToReviewConfig({ execution_topology_priority: [] })).toBeNull();
+    });
+    it("uses first entry of priority array", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: [
+                "cc-main-codex-subprocess",
+                "codex-main-subprocess",
+            ],
+            codex: { model: "gpt-5.4", effort: "high" },
+        });
+        expect(r).not.toBeNull();
+        expect(r?.source_topology_id).toBe("cc-main-codex-subprocess");
+        expect(r?.config.subagent).toEqual({
+            provider: "codex",
+            model_id: "gpt-5.4",
+            effort: "high",
+        });
+    });
+    it("overlays codex.model + codex.effort into subagent axes", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: ["cc-teams-codex-subprocess"],
+            codex: { model: "gpt-5.4-preview", effort: "xhigh" },
+        });
+        expect(r?.config.subagent).toEqual({
+            provider: "codex",
+            model_id: "gpt-5.4-preview",
+            effort: "xhigh",
+        });
+        expect(r?.runtime_preconditions.requires_agent_teams_env).toBe(true);
+    });
+    it("overlays litellm.model into litellm subagent", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: ["cc-teams-litellm-sessions"],
+            litellm: { model: "llama-8b" },
+        });
+        expect(r?.config.subagent).toMatchObject({
+            provider: "litellm",
+            model_id: "llama-8b",
+        });
+    });
+    it("warns when foreign provider block has no model", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: ["cc-main-codex-subprocess"],
+            // codex block absent — no model to overlay
+        });
+        expect(r).not.toBeNull();
+        expect(r?.warnings.some((w) => w.includes("model_id"))).toBe(true);
+    });
+    it("preserves lens_deliberation for deliberation topology", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: ["cc-teams-lens-agent-deliberation"],
+        });
+        expect(r?.config.lens_deliberation).toBe("sendmessage-a2a");
+    });
+    it("codex-nested overlays codex.model into both teamlead and subagent", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: ["codex-nested-subprocess"],
+            codex: { model: "gpt-5.4", effort: "high" },
+        });
+        expect(r?.config.teamlead?.model).toEqual({
+            provider: "codex",
+            model_id: "gpt-5.4",
+            effort: "high",
+        });
+        expect(r?.config.subagent).toEqual({
+            provider: "codex",
+            model_id: "gpt-5.4",
+            effort: "high",
+        });
+        expect(r?.runtime_preconditions.implies_host_plain_terminal).toBe(true);
+    });
+    it("returns null when first priority entry is generic-*", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: ["generic-main-subagent"],
+        });
+        expect(r).toBeNull();
+    });
+    it("rejects non-string first entry gracefully", () => {
+        const r = legacyFieldsToReviewConfig({
+            execution_topology_priority: [42, "cc-main-agent-subagent"],
+        });
+        expect(r).toBeNull();
+    });
+});

package/dist/core-runtime/review/review-config-validator.js

@@ -0,0 +1,289 @@
+/**
+ * Review UX Redesign P1 — pure validator for the `review:` config block.
+ *
+ * # What this module is
+ *
+ * A pure function suite that accepts an `unknown` (the shape YAML casting
+ * produces under `OntoConfig.review`) and returns either a typed
+ * `OntoReviewConfig` or a list of structured validation errors. The
+ * validator enforces the **discriminated union semantics** that YAML
+ * cast-reads cannot verify — e.g. `subagent.provider = "main-native"` must
+ * not carry `model_id` / `effort`, and `subagent.provider` of a foreign
+ * provider must carry `model_id`.
+ *
+ * # Why it exists
+ *
+ * `readConfigAt` in `config-chain.ts` casts raw YAML into `OntoConfig`
+ * without runtime structure checks. Downstream consumers (P2 topology
+ * derivation, P4 onboard, P5 config CLI) need a single seat that both
+ * (a) surfaces config errors with precise `review.*.path` location and
+ * (b) narrows the discriminated union so compile-time type guards hold
+ * for the rest of the pipeline.
+ *
+ * # How it relates
+ *
+ * - Input:  raw `review` block (from YAML cast). Permissively typed.
+ * - Output: `{ ok: true, config: OntoReviewConfig }` or
+ *           `{ ok: false, errors: ValidationError[] }`.
+ * - P1 does NOT call this validator from runtime — it is pure/library.
+ *   P2 wires the call inside the review-invoke path.
+ */
+// Domain tables kept next to the validator — same file changes together with
+// schema changes, so drift between type and validator is impossible.
+const FOREIGN_PROVIDERS = ["codex"];
+const SUBAGENT_PROVIDERS = ["main-native", ...FOREIGN_PROVIDERS];
+const LENS_DELIBERATIONS = [
+    "controlled-lens-deliberation",
+];
+/**
+ * Validate a raw `review` block (as cast from YAML) and return either the
+ * narrowed OntoReviewConfig or a structured error list.
+ *
+ * `undefined` / missing block → `{ ok: true, config: {}, errors: [] }`.
+ * Consumers should treat `{}` as the review defaults.
+ */
+export function validateReviewConfig(raw) {
+    const errors = [];
+    if (raw === undefined || raw === null) {
+        return { ok: true, config: {}, errors: [] };
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        errors.push({
+            path: "review",
+            message: "review block must be a YAML mapping (object), not scalar/array.",
+        });
+        return { ok: false, errors };
+    }
+    const obj = raw;
+    const out = {};
+    rejectUnknownKeys(obj, ["teamlead", "subagent", "max_concurrent_lenses", "lens_deliberation"], "review", errors);
+    if ("teamlead" in obj) {
+        const teamlead = validateTeamlead(obj.teamlead, errors);
+        if (teamlead)
+            out.teamlead = teamlead;
+    }
+    if ("subagent" in obj) {
+        const subagent = validateSubagent(obj.subagent, errors);
+        if (subagent)
+            out.subagent = subagent;
+    }
+    if ("max_concurrent_lenses" in obj) {
+        const concurrency = validateConcurrency(obj.max_concurrent_lenses, errors);
+        if (concurrency !== null)
+            out.max_concurrent_lenses = concurrency;
+    }
+    if ("lens_deliberation" in obj) {
+        const deliberation = validateDeliberation(obj.lens_deliberation, errors);
+        if (deliberation)
+            out.lens_deliberation = deliberation;
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return { ok: true, config: out, errors: [] };
+}
+// ---------------------------------------------------------------------------
+// Teamlead
+// ---------------------------------------------------------------------------
+function validateTeamlead(raw, errors) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        errors.push({
+            path: "review.teamlead",
+            message: "teamlead must be a mapping with a `model` field.",
+        });
+        return null;
+    }
+    const obj = raw;
+    rejectUnknownKeys(obj, ["model"], "review.teamlead", errors);
+    if (!("model" in obj)) {
+        errors.push({
+            path: "review.teamlead.model",
+            message: "teamlead.model is required when teamlead block is declared.",
+        });
+        return null;
+    }
+    const model = obj.model;
+    if (model === "main") {
+        return { model: "main" };
+    }
+    const explicit = validateExplicitModel(model, "review.teamlead.model", errors);
+    if (!explicit)
+        return null;
+    return { model: explicit };
+}
+function validateExplicitModel(raw, pathPrefix, errors) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        errors.push({
+            path: pathPrefix,
+            message: 'model must be either "main" (string) or a mapping ' +
+                "{provider, model_id, effort?}.",
+        });
+        return null;
+    }
+    const obj = raw;
+    rejectUnknownKeys(obj, ["provider", "model_id", "effort"], pathPrefix, errors);
+    const provider = obj.provider;
+    if (typeof provider !== "string") {
+        errors.push({
+            path: `${pathPrefix}.provider`,
+            message: "provider must be a string.",
+        });
+        return null;
+    }
+    if (!FOREIGN_PROVIDERS.includes(provider)) {
+        errors.push({
+            path: `${pathPrefix}.provider`,
+            message: `provider must be one of: ${FOREIGN_PROVIDERS.join(", ")} (got "${provider}"). "main-native" is only valid under subagent, not under an explicit model spec.`,
+        });
+        return null;
+    }
+    const modelId = obj.model_id;
+    if (typeof modelId !== "string" || modelId.length === 0) {
+        errors.push({
+            path: `${pathPrefix}.model_id`,
+            message: "model_id is required (non-empty string) for foreign providers.",
+        });
+        return null;
+    }
+    const spec = {
+        provider: provider,
+        model_id: modelId,
+    };
+    if ("effort" in obj) {
+        if (typeof obj.effort !== "string" || obj.effort.length === 0) {
+            errors.push({
+                path: `${pathPrefix}.effort`,
+                message: "effort must be a non-empty string when present.",
+            });
+            return null;
+        }
+        spec.effort = obj.effort;
+    }
+    return spec;
+}
+// ---------------------------------------------------------------------------
+// Subagent
+// ---------------------------------------------------------------------------
+function validateSubagent(raw, errors) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        errors.push({
+            path: "review.subagent",
+            message: "subagent must be a mapping with a `provider` field.",
+        });
+        return null;
+    }
+    const obj = raw;
+    rejectUnknownKeys(obj, ["provider", "model_id", "effort"], "review.subagent", errors);
+    const provider = obj.provider;
+    if (typeof provider !== "string") {
+        errors.push({
+            path: "review.subagent.provider",
+            message: "subagent.provider is required and must be a string.",
+        });
+        return null;
+    }
+    if (!SUBAGENT_PROVIDERS.includes(provider)) {
+        errors.push({
+            path: "review.subagent.provider",
+            message: `subagent.provider must be one of: ${SUBAGENT_PROVIDERS.join(", ")} (got "${provider}").`,
+        });
+        return null;
+    }
+    if (provider === "main-native") {
+        // Discriminated-union enforcement: main-native branch must not carry
+        // model_id / effort (those are foreign-provider-only).
+        if ("model_id" in obj) {
+            errors.push({
+                path: "review.subagent.model_id",
+                message: "model_id is not allowed when subagent.provider=main-native. " +
+                    "main-native resolves via the host's native subagent mechanism.",
+            });
+        }
+        if ("effort" in obj) {
+            errors.push({
+                path: "review.subagent.effort",
+                message: "effort is not allowed when subagent.provider=main-native. " +
+                    "Effort configuration for main-native is host-managed (e.g. Claude Code Agent tool).",
+            });
+        }
+        if (errors.some((e) => e.path.startsWith("review.subagent"))) {
+            return null;
+        }
+        return { provider: "main-native" };
+    }
+    // Foreign branch
+    const modelId = obj.model_id;
+    if (typeof modelId !== "string" || modelId.length === 0) {
+        errors.push({
+            path: "review.subagent.model_id",
+            message: `model_id is required (non-empty string) when subagent.provider=${provider}.`,
+        });
+        return null;
+    }
+    const spec = {
+        provider: provider,
+        model_id: modelId,
+    };
+    if ("effort" in obj) {
+        if (typeof obj.effort !== "string" || obj.effort.length === 0) {
+            errors.push({
+                path: "review.subagent.effort",
+                message: "effort must be a non-empty string when present.",
+            });
+            return null;
+        }
+        spec.effort = obj.effort;
+    }
+    return spec;
+}
+// ---------------------------------------------------------------------------
+// Scalar axes
+// ---------------------------------------------------------------------------
+function validateConcurrency(raw, errors) {
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+        errors.push({
+            path: "review.max_concurrent_lenses",
+            message: "max_concurrent_lenses must be a finite number.",
+        });
+        return null;
+    }
+    if (!Number.isInteger(raw) || raw < 1) {
+        errors.push({
+            path: "review.max_concurrent_lenses",
+            message: "max_concurrent_lenses must be a positive integer (>= 1).",
+        });
+        return null;
+    }
+    return raw;
+}
+function validateDeliberation(raw, errors) {
+    if (typeof raw !== "string") {
+        errors.push({
+            path: "review.lens_deliberation",
+            message: "lens_deliberation must be a string.",
+        });
+        return null;
+    }
+    if (!LENS_DELIBERATIONS.includes(raw)) {
+        errors.push({
+            path: "review.lens_deliberation",
+            message: `lens_deliberation must be one of: ${LENS_DELIBERATIONS.join(", ")} (got "${raw}").`,
+        });
+        return null;
+    }
+    return raw;
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function rejectUnknownKeys(obj, allowed, pathPrefix, errors) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(obj)) {
+        if (!allowedSet.has(key)) {
+            errors.push({
+                path: `${pathPrefix}.${key}`,
+                message: `Unknown field. Allowed: ${allowed.join(", ")}.`,
+            });
+        }
+    }
+}