@exellix/graph-composer 2.0.0

package/dist/graphComposerOutputValidation.js

@@ -0,0 +1,709 @@
+import { reportTaskNodeProtocolGaps } from "./aiTaskProfile.js";
+import { collectCanonicalGraphWarnings } from "./canonicalGraphWarnings.js";
+import { canonicalizeGraphModel, reportTaskNodeInputsLayoutIssues, taskNodeInputsLayoutWarningMessage, } from "./taskNodeTaskVariable.js";
+const PRIMARY_INTENT_TYPES = new Set([
+    "question",
+    "decision",
+    "action",
+    "objective",
+]);
+const CONCEPT_STATUSES = new Set([
+    "not-started",
+    "generated-draft",
+    "user-refined",
+    "complete",
+]);
+const GRAPH_CONCEPT_PATCH_KEYS = [
+    "primaryIntentType",
+    "primaryIntentStatement",
+    "businessObjective",
+    "primaryOutcome",
+];
+export function validateExplainOutput(out, _ctx) {
+    if ("graph" in out && out.graph !== undefined) {
+        throw new Error("explain action must not return a graph object");
+    }
+}
+function validatePresentGraphConceptPatchKeys(p, ctxPrefix) {
+    for (const key of GRAPH_CONCEPT_PATCH_KEYS) {
+        if (!(key in p))
+            continue;
+        const v = p[key];
+        if (key === "primaryIntentType") {
+            if (typeof v !== "string" || !PRIMARY_INTENT_TYPES.has(v)) {
+                throw new Error(`${ctxPrefix}.primaryIntentType must be one of: question, decision, action, objective`);
+            }
+            continue;
+        }
+        if (typeof v !== "string") {
+            throw new Error(`${ctxPrefix}.${key} must be a string`);
+        }
+        if (key === "primaryIntentStatement" && v.trim() === "") {
+            throw new Error(`${ctxPrefix}.primaryIntentStatement must be non-empty when present`);
+        }
+    }
+}
+const REVIEW_EXTRA_STRING_PATCH_KEYS = [
+    "graphType",
+    "expectedInput",
+    "outputDescription",
+    "persistenceNotes",
+    "notes",
+    "targetEntityType",
+    "decisionType",
+];
+function validatePresentReviewConceptPatchStringExtras(p, ctxPrefix) {
+    for (const key of REVIEW_EXTRA_STRING_PATCH_KEYS) {
+        if (!(key in p))
+            continue;
+        const v = p[key];
+        if (typeof v !== "string") {
+            throw new Error(`${ctxPrefix}.${key} must be a string when present`);
+        }
+    }
+}
+function validateOptionalConceptStatus(v, ctxPrefix) {
+    if (v === undefined)
+        return;
+    if (typeof v !== "string" || !CONCEPT_STATUSES.has(v)) {
+        throw new Error(`${ctxPrefix}.conceptStatus must be one of: not-started, generated-draft, user-refined, complete`);
+    }
+}
+function validateOptionalEntityBindings(eb, ctxPrefix) {
+    if (eb === undefined)
+        return;
+    if (eb === null || typeof eb !== "object" || Array.isArray(eb)) {
+        throw new Error(`${ctxPrefix}.entityBindings must be a plain object when present`);
+    }
+    const o = eb;
+    if ("coreEntityCollectionId" in o &&
+        o.coreEntityCollectionId !== undefined &&
+        typeof o.coreEntityCollectionId !== "string") {
+        throw new Error(`${ctxPrefix}.entityBindings.coreEntityCollectionId must be a string when present`);
+    }
+    if ("supportingEntityCollectionIds" in o && o.supportingEntityCollectionIds !== undefined) {
+        const arr = o.supportingEntityCollectionIds;
+        if (!Array.isArray(arr)) {
+            throw new Error(`${ctxPrefix}.entityBindings.supportingEntityCollectionIds must be an array when present`);
+        }
+        for (let j = 0; j < arr.length; j++) {
+            if (typeof arr[j] !== "string") {
+                throw new Error(`${ctxPrefix}.entityBindings.supportingEntityCollectionIds[${j}] must be a string`);
+            }
+        }
+    }
+    if ("targetEntityCollectionId" in o &&
+        o.targetEntityCollectionId !== undefined &&
+        typeof o.targetEntityCollectionId !== "string") {
+        throw new Error(`${ctxPrefix}.entityBindings.targetEntityCollectionId must be a string when present`);
+    }
+}
+function validateReviewConceptRequirements(req, ctx) {
+    if (req === undefined)
+        return;
+    if (req === null || typeof req !== "object" || Array.isArray(req)) {
+        throw new Error(`${ctx} must be a plain object when present`);
+    }
+    const r = req;
+    if ("skill" in r && r.skill !== undefined) {
+        const sk = r.skill;
+        if (sk === null || typeof sk !== "object" || Array.isArray(sk)) {
+            throw new Error(`${ctx}.skill must be an object when present`);
+        }
+        const s = sk;
+        if (typeof s.skillKey !== "string") {
+            throw new Error(`${ctx}.skill.skillKey must be a string when skill is present`);
+        }
+        if ("isLocal" in s && s.isLocal !== undefined && typeof s.isLocal !== "boolean") {
+            throw new Error(`${ctx}.skill.isLocal must be a boolean when present`);
+        }
+    }
+    if ("memoryIO" in r && r.memoryIO !== undefined) {
+        const m = r.memoryIO;
+        if (m === null || typeof m !== "object" || Array.isArray(m)) {
+            throw new Error(`${ctx}.memoryIO must be an object when present`);
+        }
+        const mem = m;
+        if ("reads" in mem && mem.reads !== undefined) {
+            if (!Array.isArray(mem.reads)) {
+                throw new Error(`${ctx}.memoryIO.reads must be an array when present`);
+            }
+            for (let k = 0; k < mem.reads.length; k++) {
+                if (typeof mem.reads[k] !== "string") {
+                    throw new Error(`${ctx}.memoryIO.reads[${k}] must be a string`);
+                }
+            }
+        }
+        if ("writes" in mem && mem.writes !== undefined && typeof mem.writes !== "string") {
+            throw new Error(`${ctx}.memoryIO.writes must be a string when present`);
+        }
+        if ("jobContextMappings" in mem &&
+            mem.jobContextMappings !== undefined) {
+            const j = mem.jobContextMappings;
+            if (j === null || typeof j !== "object" || Array.isArray(j)) {
+                throw new Error(`${ctx}.memoryIO.jobContextMappings must be an object when present`);
+            }
+        }
+    }
+    if ("strategies" in r && r.strategies !== undefined) {
+        const strat = r.strategies;
+        if (strat === null || typeof strat !== "object" || Array.isArray(strat)) {
+            throw new Error(`${ctx}.strategies must be an object when present`);
+        }
+        const st = strat;
+        for (const key of ["pre", "post"]) {
+            if (!(key in st) || st[key] === undefined)
+                continue;
+            const arr = st[key];
+            if (!Array.isArray(arr)) {
+                throw new Error(`${ctx}.strategies.${key} must be an array when present`);
+            }
+            for (let j = 0; j < arr.length; j++) {
+                if (typeof arr[j] !== "string") {
+                    throw new Error(`${ctx}.strategies.${key}[${j}] must be a string`);
+                }
+            }
+        }
+    }
+    for (const sub of ["catalogBinding", "narrix"]) {
+        if (!(sub in r) || r[sub] === undefined)
+            continue;
+        const v = r[sub];
+        if (v === null || typeof v !== "object" || Array.isArray(v)) {
+            throw new Error(`${ctx}.${sub} must be an object when present`);
+        }
+    }
+}
+function validateReviewConceptCoreTaskPatchItem(t, ctxPrefix) {
+    if ("taskType" in t && t.taskType !== undefined) {
+        if (typeof t.taskType !== "string" || !PRIMARY_INTENT_TYPES.has(t.taskType)) {
+            throw new Error(`${ctxPrefix}.taskType must be one of: question, decision, action, objective when present`);
+        }
+    }
+    for (const key of ["statement", "details"]) {
+        if (!(key in t) || t[key] === undefined)
+            continue;
+        if (typeof t[key] !== "string") {
+            throw new Error(`${ctxPrefix}.${key} must be a string when present`);
+        }
+    }
+    if ("sourceFamilyHints" in t && t.sourceFamilyHints !== undefined) {
+        const hints = t.sourceFamilyHints;
+        if (!Array.isArray(hints)) {
+            throw new Error(`${ctxPrefix}.sourceFamilyHints must be an array when present`);
+        }
+        for (let j = 0; j < hints.length; j++) {
+            if (typeof hints[j] !== "string") {
+                throw new Error(`${ctxPrefix}.sourceFamilyHints[${j}] must be a string`);
+            }
+        }
+    }
+    if ("planningRunsAfterTaskIndex" in t && t.planningRunsAfterTaskIndex !== undefined) {
+        const p = t.planningRunsAfterTaskIndex;
+        if (typeof p !== "number" || !Number.isInteger(p) || p < -1) {
+            throw new Error(`${ctxPrefix}.planningRunsAfterTaskIndex must be an integer >= -1 when present`);
+        }
+    }
+    if ("stepInputs" in t && t.stepInputs !== undefined) {
+        const si = t.stepInputs;
+        if (typeof si === "string") {
+            /* v3 path hint */
+        }
+        else if (si === null || typeof si !== "object" || Array.isArray(si)) {
+            throw new Error(`${ctxPrefix}.stepInputs must be a string or plain object when present`);
+        }
+    }
+    if ("subTasks" in t && t.subTasks !== undefined) {
+        const st = t.subTasks;
+        if (!Array.isArray(st)) {
+            throw new Error(`${ctxPrefix}.subTasks must be an array when present`);
+        }
+        for (let j = 0; j < st.length; j++) {
+            const row = st[j];
+            if (row === null || typeof row !== "object" || Array.isArray(row)) {
+                throw new Error(`${ctxPrefix}.subTasks[${j}] must be an object`);
+            }
+        }
+    }
+    if ("webScoping" in t && t.webScoping !== undefined) {
+        const w = t.webScoping;
+        if (w === null || typeof w !== "object" || Array.isArray(w)) {
+            throw new Error(`${ctxPrefix}.webScoping must be an object when present`);
+        }
+    }
+    if ("synthesis" in t && t.synthesis !== undefined) {
+        const syn = t.synthesis;
+        if (syn === null || typeof syn !== "object" || Array.isArray(syn)) {
+            throw new Error(`${ctxPrefix}.synthesis must be an object when present`);
+        }
+    }
+    if ("requirements" in t && t.requirements !== undefined) {
+        validateReviewConceptRequirements(t.requirements, `${ctxPrefix}.requirements`);
+    }
+}
+function validateReviewConceptPatchObject(patch, ctxPrefix) {
+    validatePresentGraphConceptPatchKeys(patch, ctxPrefix);
+    validatePresentReviewConceptPatchStringExtras(patch, ctxPrefix);
+    if ("conceptStatus" in patch) {
+        validateOptionalConceptStatus(patch.conceptStatus, ctxPrefix);
+    }
+    if ("entityBindings" in patch) {
+        validateOptionalEntityBindings(patch.entityBindings, ctxPrefix);
+    }
+    const ct = patch.coreTasks;
+    if (ct === undefined)
+        return;
+    if (!Array.isArray(ct)) {
+        throw new Error(`${ctxPrefix}.coreTasks must be an array when present`);
+    }
+    for (let i = 0; i < ct.length; i++) {
+        const item = ct[i];
+        if (item === null || item === undefined)
+            continue;
+        if (typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(`${ctxPrefix}.coreTasks[${i}] must be an object or null`);
+        }
+        const t = item;
+        validateReviewConceptCoreTaskPatchItem(t, `${ctxPrefix}.coreTasks[${i}]`);
+    }
+}
+function validateOptionalReviewConceptPatch(patch, fieldName) {
+    if (patch === undefined || patch === null)
+        return;
+    if (typeof patch !== "object" || Array.isArray(patch)) {
+        throw new Error(`${fieldName} must be an object when present`);
+    }
+    validateReviewConceptPatchObject(patch, fieldName);
+}
+function requirementOptionCandidateHasContent(o) {
+    if (typeof o.value === "string" && o.value.length > 0)
+        return true;
+    if (typeof o.rationale === "string" &&
+        o.rationale.trim() !== "") {
+        return true;
+    }
+    return false;
+}
+function validateRequirementOptionsArray(arr, ctx) {
+    if (!Array.isArray(arr)) {
+        throw new Error(`${ctx} must be an array when present`);
+    }
+    for (let i = 0; i < arr.length; i++) {
+        const row = arr[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`${ctx}[${i}] must be an object`);
+        }
+        const o = row;
+        if (typeof o.taskIndex !== "number" ||
+            !Number.isInteger(o.taskIndex) ||
+            o.taskIndex < 0) {
+            throw new Error(`${ctx}[${i}].taskIndex must be a non-negative integer`);
+        }
+        if (typeof o.field !== "string" || o.field.trim() === "") {
+            throw new Error(`${ctx}[${i}].field must be a non-empty string`);
+        }
+        if (typeof o.needsNewArtifact !== "boolean") {
+            throw new Error(`${ctx}[${i}].needsNewArtifact must be a boolean`);
+        }
+        const cand = o.candidates;
+        if (!Array.isArray(cand) || cand.length === 0) {
+            throw new Error(`${ctx}[${i}].candidates must be a non-empty array`);
+        }
+        for (let j = 0; j < cand.length; j++) {
+            const c = cand[j];
+            if (c === null || typeof c !== "object" || Array.isArray(c)) {
+                throw new Error(`${ctx}[${i}].candidates[${j}] must be an object`);
+            }
+            const co = c;
+            if (!requirementOptionCandidateHasContent(co)) {
+                throw new Error(`${ctx}[${i}].candidates[${j}] must include a non-empty string value or non-empty rationale`);
+            }
+            if ("value" in co && co.value !== undefined && typeof co.value !== "string") {
+                throw new Error(`${ctx}[${i}].candidates[${j}].value must be a string when present`);
+            }
+            if ("rationale" in co &&
+                co.rationale !== undefined &&
+                typeof co.rationale !== "string") {
+                throw new Error(`${ctx}[${i}].candidates[${j}].rationale must be a string when present`);
+            }
+            if ("source" in co && co.source !== undefined && typeof co.source !== "string") {
+                throw new Error(`${ctx}[${i}].candidates[${j}].source must be a string when present`);
+            }
+        }
+    }
+}
+export function validateReviewConceptOutput(out, _ctx) {
+    assertNoGraph(out, "reviewConcept");
+    if ("changelog" in out && out.changelog !== undefined) {
+        throw new Error("reviewConcept action must not return a changelog");
+    }
+    const verdict = out.verdict;
+    if (verdict === null ||
+        verdict === undefined ||
+        typeof verdict !== "object" ||
+        Array.isArray(verdict)) {
+        throw new Error("reviewConcept output must include verdict object");
+    }
+    const v = verdict;
+    if (typeof v.coherent !== "boolean") {
+        throw new Error("reviewConcept.verdict.coherent must be a boolean");
+    }
+    if (typeof v.summary !== "string" || v.summary.trim() === "") {
+        throw new Error("reviewConcept.verdict.summary must be a non-empty string");
+    }
+    if (!Array.isArray(out.findings)) {
+        throw new Error("reviewConcept output must include findings array");
+    }
+    const findings = out.findings;
+    for (let i = 0; i < findings.length; i++) {
+        const row = findings[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`findings[${i}] must be an object`);
+        }
+        const f = row;
+        assertStringField(f, "category", `findings[${i}]`);
+        assertStringField(f, "severity", `findings[${i}]`);
+        assertStringField(f, "summary", `findings[${i}]`);
+        if (f.nodeIds !== undefined) {
+            if (!Array.isArray(f.nodeIds)) {
+                throw new Error(`findings[${i}].nodeIds must be an array when present`);
+            }
+            for (let j = 0; j < f.nodeIds.length; j++) {
+                const id = f.nodeIds[j];
+                if (typeof id !== "string") {
+                    throw new Error(`findings[${i}].nodeIds[${j}] must be a string`);
+                }
+            }
+        }
+        if (f.suggestedChange !== undefined &&
+            typeof f.suggestedChange !== "string") {
+            throw new Error(`findings[${i}].suggestedChange must be a string when present`);
+        }
+        if (f.taskIndex !== undefined) {
+            if (typeof f.taskIndex !== "number" ||
+                !Number.isInteger(f.taskIndex) ||
+                f.taskIndex < 0) {
+                throw new Error(`findings[${i}].taskIndex must be a non-negative integer when present`);
+            }
+        }
+        if (f.proposal !== undefined) {
+            if (f.proposal === null ||
+                typeof f.proposal !== "object" ||
+                Array.isArray(f.proposal)) {
+                throw new Error(`findings[${i}].proposal must be a plain object when present`);
+            }
+        }
+    }
+    validateOptionalReviewConceptPatch(out.graphConceptPatch, "graphConceptPatch");
+    validateOptionalReviewConceptPatch(out.suggestedConceptPatch, "suggestedConceptPatch");
+    if (out.catalogProposals !== undefined) {
+        if (!Array.isArray(out.catalogProposals)) {
+            throw new Error("catalogProposals must be an array when present");
+        }
+        const props = out.catalogProposals;
+        for (let i = 0; i < props.length; i++) {
+            const row = props[i];
+            if (row === null || typeof row !== "object" || Array.isArray(row)) {
+                throw new Error(`catalogProposals[${i}] must be an object`);
+            }
+        }
+    }
+    if (out.requirementOptions !== undefined) {
+        validateRequirementOptionsArray(out.requirementOptions, "requirementOptions");
+    }
+}
+/**
+ * When `existingGraph.metadata.graphConcept.coreTasks` has length N > 0, any
+ * `graphConceptPatch` / `suggestedConceptPatch` must include `coreTasks` with
+ * the same length (index-aligned). Call after `validateReviewConceptOutput`.
+ */
+export function validateReviewConceptOutputAgainstInput(out, input) {
+    const n = coreTasksLengthFromExistingGraph(input.existingGraph);
+    if (n === undefined || n <= 0)
+        return;
+    const gcp = out.graphConceptPatch;
+    const scp = out.suggestedConceptPatch;
+    const hasGcp = gcp !== null &&
+        gcp !== undefined &&
+        typeof gcp === "object" &&
+        !Array.isArray(gcp);
+    const hasScp = scp !== null &&
+        scp !== undefined &&
+        typeof scp === "object" &&
+        !Array.isArray(scp);
+    if (!hasGcp && !hasScp)
+        return;
+    function checkPatch(patch, fieldName) {
+        const ct = patch.coreTasks;
+        if (!Array.isArray(ct)) {
+            throw new Error(`reviewConcept: when existingGraph.metadata.graphConcept.coreTasks has length ${n}, ${fieldName} must include coreTasks as an array of length ${n}`);
+        }
+        if (ct.length !== n) {
+            throw new Error(`reviewConcept: ${fieldName}.coreTasks must have length ${n} to match existing concept (got ${ct.length})`);
+        }
+    }
+    if (hasGcp)
+        checkPatch(gcp, "graphConceptPatch");
+    if (hasScp)
+        checkPatch(scp, "suggestedConceptPatch");
+}
+function coreTasksLengthFromExistingGraph(existingGraph) {
+    if (existingGraph === null ||
+        typeof existingGraph !== "object" ||
+        Array.isArray(existingGraph)) {
+        return undefined;
+    }
+    const meta = existingGraph.metadata;
+    if (meta === null || typeof meta !== "object" || Array.isArray(meta)) {
+        return undefined;
+    }
+    const gc = meta.graphConcept;
+    if (gc === null || typeof gc !== "object" || Array.isArray(gc)) {
+        return undefined;
+    }
+    const ct = gc.coreTasks;
+    if (!Array.isArray(ct))
+        return undefined;
+    return ct.length;
+}
+export function validateSuggestConceptOutput(out, _ctx) {
+    if ("graph" in out && out.graph !== undefined) {
+        throw new Error("suggestConceptObjective action must not return a graph object");
+    }
+    const patch = out.graphConceptPatch;
+    if (patch === undefined ||
+        patch === null ||
+        typeof patch !== "object" ||
+        Array.isArray(patch)) {
+        throw new Error("suggestConceptObjective output must include graphConceptPatch object");
+    }
+    const p = patch;
+    validatePresentGraphConceptPatchKeys(p, "graphConceptPatch");
+}
+function appendWarnings(out, messages) {
+    if (messages.length === 0)
+        return;
+    const existing = out.warnings;
+    if (Array.isArray(existing)) {
+        out.warnings = [...existing, ...messages];
+    }
+    else {
+        out.warnings = messages;
+    }
+}
+function appendCreateModifyLayoutWarnings(out, graph) {
+    const issues = reportTaskNodeInputsLayoutIssues(graph);
+    if (issues.length === 0)
+        return;
+    const msg = taskNodeInputsLayoutWarningMessage(issues);
+    appendWarnings(out, [msg]);
+}
+export function validateCreateModifyOutput(out, ctx) {
+    if (!Array.isArray(out.changelog)) {
+        throw new Error("create/modify output must include changelog array");
+    }
+    const graph = out.graph;
+    if (graph !== null &&
+        graph !== undefined &&
+        typeof graph === "object" &&
+        !Array.isArray(graph)) {
+        appendCreateModifyLayoutWarnings(out, graph);
+        const canonicalized = canonicalizeGraphModel(graph);
+        const gaps = reportTaskNodeProtocolGaps(canonicalized, {
+            utilitySkills: ctx?.input?.utilitySkills,
+        });
+        if (gaps.length > 0) {
+            throw new Error(`create/modify graph violates task node protocol (taskConfiguration.aiTaskProfile / webScoping / inputSynthesis): ${JSON.stringify(gaps)}`);
+        }
+        appendWarnings(out, collectCanonicalGraphWarnings(canonicalized));
+        out.graph = canonicalized;
+    }
+}
+function assertNoGraph(out, action) {
+    if ("graph" in out && out.graph !== undefined) {
+        throw new Error(`${action} action must not return a graph object`);
+    }
+}
+function assertStringField(row, field, ctx) {
+    const v = row[field];
+    if (typeof v !== "string" || v.trim() === "") {
+        throw new Error(`${ctx}: ${field} must be a non-empty string`);
+    }
+}
+export function validateSuggestCatalogResolutionOutput(out, _ctx) {
+    assertNoGraph(out, "suggestCatalogResolution");
+    for (const key of ["skillResolution", "scopingResolution", "narrixResolution", "gaps"]) {
+        if (!Array.isArray(out[key])) {
+            throw new Error(`suggestCatalogResolution output must include ${key} array`);
+        }
+    }
+    const skills = out.skillResolution;
+    for (let i = 0; i < skills.length; i++) {
+        const row = skills[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`skillResolution[${i}] must be an object`);
+        }
+        const o = row;
+        assertStringField(o, "nodeId", `skillResolution[${i}]`);
+        assertStringField(o, "skillKey", `skillResolution[${i}]`);
+        if ("isLocal" in o && typeof o.isLocal !== "boolean") {
+            throw new Error(`skillResolution[${i}].isLocal must be boolean when present`);
+        }
+    }
+    const scoping = out.scopingResolution;
+    for (let i = 0; i < scoping.length; i++) {
+        const row = scoping[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`scopingResolution[${i}] must be an object`);
+        }
+    }
+    const narrix = out.narrixResolution;
+    for (let i = 0; i < narrix.length; i++) {
+        const row = narrix[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`narrixResolution[${i}] must be an object`);
+        }
+    }
+    const gaps = out.gaps;
+    for (let i = 0; i < gaps.length; i++) {
+        const row = gaps[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`gaps[${i}] must be an object`);
+        }
+        const o = row;
+        assertStringField(o, "kind", `gaps[${i}]`);
+        assertStringField(o, "summary", `gaps[${i}]`);
+    }
+}
+export function validateSuggestCatalogCreationsOutput(out, _ctx) {
+    assertNoGraph(out, "suggestCatalogCreations");
+    if (!Array.isArray(out.catalogRequestProposals)) {
+        throw new Error("suggestCatalogCreations output must include catalogRequestProposals array");
+    }
+    const proposals = out.catalogRequestProposals;
+    for (let i = 0; i < proposals.length; i++) {
+        const row = proposals[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`catalogRequestProposals[${i}] must be an object`);
+        }
+        const o = row;
+        assertStringField(o, "catalogType", `catalogRequestProposals[${i}]`);
+        assertStringField(o, "requestedId", `catalogRequestProposals[${i}]`);
+    }
+    if (out.newSkillDescriptors !== undefined) {
+        if (!Array.isArray(out.newSkillDescriptors)) {
+            throw new Error("newSkillDescriptors must be an array when present");
+        }
+        const nd = out.newSkillDescriptors;
+        for (let i = 0; i < nd.length; i++) {
+            const row = nd[i];
+            if (row === null || typeof row !== "object" || Array.isArray(row)) {
+                throw new Error(`newSkillDescriptors[${i}] must be an object`);
+            }
+            const o = row;
+            assertStringField(o, "skillKey", `newSkillDescriptors[${i}]`);
+            assertStringField(o, "description", `newSkillDescriptors[${i}]`);
+        }
+    }
+}
+function recommendedScopingHasId(o) {
+    const sid = o.scopingMapId;
+    const qid = o.questionId;
+    const hasSid = typeof sid === "string" && sid.trim() !== "";
+    const hasQid = typeof qid === "string" && qid.trim() !== "";
+    return hasSid || hasQid;
+}
+export function validateSuggestScopingNeedMatchOutput(out, _ctx) {
+    assertNoGraph(out, "suggestScopingNeedMatch");
+    if (typeof out.hasSuitableMatch !== "boolean") {
+        throw new Error("suggestScopingNeedMatch output must include boolean hasSuitableMatch");
+    }
+    if (!Array.isArray(out.gaps)) {
+        throw new Error("suggestScopingNeedMatch output must include gaps array");
+    }
+    const gaps = out.gaps;
+    for (let i = 0; i < gaps.length; i++) {
+        const row = gaps[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`gaps[${i}] must be an object`);
+        }
+        const g = row;
+        assertStringField(g, "kind", `gaps[${i}]`);
+        assertStringField(g, "summary", `gaps[${i}]`);
+    }
+    if (!("recommended" in out)) {
+        throw new Error("suggestScopingNeedMatch output must include recommended key");
+    }
+    const rec = out.recommended;
+    if (out.hasSuitableMatch) {
+        if (rec === null || typeof rec !== "object" || Array.isArray(rec)) {
+            throw new Error("when hasSuitableMatch is true, recommended must be a non-null object");
+        }
+        if (!recommendedScopingHasId(rec)) {
+            throw new Error("when hasSuitableMatch is true, recommended must include non-empty scopingMapId and/or questionId");
+        }
+    }
+    else {
+        if (rec !== null) {
+            throw new Error("when hasSuitableMatch is false, recommended must be null");
+        }
+    }
+    if (out.alternatives !== undefined) {
+        if (!Array.isArray(out.alternatives)) {
+            throw new Error("alternatives must be an array when present");
+        }
+        const alts = out.alternatives;
+        for (let i = 0; i < alts.length; i++) {
+            const row = alts[i];
+            if (row === null || typeof row !== "object" || Array.isArray(row)) {
+                throw new Error(`alternatives[${i}] must be an object`);
+            }
+        }
+    }
+}
+export function validateSuggestScopingMapCreationOutput(out, _ctx) {
+    assertNoGraph(out, "suggestScopingMapCreation");
+    const prop = out.scopingMapProposal;
+    if (prop === null ||
+        prop === undefined ||
+        typeof prop !== "object" ||
+        Array.isArray(prop)) {
+        throw new Error("suggestScopingMapCreation output must include scopingMapProposal object");
+    }
+    const p = prop;
+    assertStringField(p, "suggestedScopingMapId", "scopingMapProposal");
+    assertStringField(p, "title", "scopingMapProposal");
+    assertStringField(p, "purpose", "scopingMapProposal");
+    if ("entityIdPath" in p && p.entityIdPath !== undefined) {
+        if (typeof p.entityIdPath !== "string") {
+            throw new Error("scopingMapProposal.entityIdPath must be a string when present");
+        }
+    }
+    if ("expectedFieldPaths" in p && p.expectedFieldPaths !== undefined) {
+        if (!Array.isArray(p.expectedFieldPaths)) {
+            throw new Error("scopingMapProposal.expectedFieldPaths must be an array when present");
+        }
+        for (let i = 0; i < p.expectedFieldPaths.length; i++) {
+            const v = p.expectedFieldPaths[i];
+            if (typeof v !== "string") {
+                throw new Error(`scopingMapProposal.expectedFieldPaths[${i}] must be a string`);
+            }
+        }
+    }
+    if (!Array.isArray(out.catalogRequestProposals)) {
+        throw new Error("suggestScopingMapCreation output must include catalogRequestProposals array");
+    }
+    const proposals = out.catalogRequestProposals;
+    if (proposals.length < 1) {
+        throw new Error("catalogRequestProposals must be non-empty");
+    }
+    for (let i = 0; i < proposals.length; i++) {
+        const row = proposals[i];
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`catalogRequestProposals[${i}] must be an object`);
+        }
+        const o = row;
+        assertStringField(o, "catalogType", `catalogRequestProposals[${i}]`);
+        assertStringField(o, "requestedId", `catalogRequestProposals[${i}]`);
+    }
+}