@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/judgment-dag-composition.js

@@ -0,0 +1,731 @@
+/**
+ * Contract for composing versioned Judgment DAGs into one parent judgment.
+ *
+ * This module intentionally has no persistence or host adapter dependency.
+ * It validates the composition, freezes the evaluation boundary, and records
+ * the result of each child without changing the J0 single-DAG run artifact.
+ */
+import { JUDGMENT_DAG_SCOPE_TYPES } from './judgment-dag-core.js';
+export const JUDGMENT_DAG_COMPOSITION_VERSION = 'judgment-dag-composition.v1';
+export const JUDGMENT_DAG_COMPOSITION_STATUSES = Object.freeze([
+    'completed',
+    'failed',
+    'held'
+]);
+export const JUDGMENT_DAG_SUBDAG_STATUSES = Object.freeze([
+    'completed',
+    'failed',
+    'held'
+]);
+export class JudgmentDAGCompositionError extends Error {
+    code;
+    invocation_id;
+    dependency_id;
+    cycle;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'JudgmentDAGCompositionError';
+        this.code = code;
+        this.invocation_id = details.invocation_id;
+        this.dependency_id = details.dependency_id;
+        this.cycle = details.cycle;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isPlainRecord(value) {
+    return (isRecord(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+function isSafeString(value) {
+    return typeof value === 'string' && value.trim().length > 0 && !/[\u0000-\u001F\u007F]/u.test(value);
+}
+function invalidContract(message) {
+    throw new JudgmentDAGCompositionError('invalid_contract', message);
+}
+function requireRecord(value, path) {
+    if (!isPlainRecord(value)) {
+        invalidContract(`${path} must be a plain object`);
+    }
+    return value;
+}
+function requireExactKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            invalidContract(`${path}.${key} is not an allowed contract field`);
+        }
+    }
+}
+function requireString(value, path) {
+    if (!isSafeString(value)) {
+        invalidContract(`${path} must be a non-empty string without control characters`);
+    }
+    return value;
+}
+function requireArray(value, path) {
+    if (!Array.isArray(value)) {
+        invalidContract(`${path} must be an array`);
+    }
+    return value;
+}
+function snapshotJSON(value, path, active = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (Number.isFinite(value)) {
+            return value;
+        }
+        invalidContract(`${path} must contain only finite JSON numbers`);
+    }
+    if (typeof value !== 'object') {
+        invalidContract(`${path} must be a JSON value`);
+    }
+    const objectValue = value;
+    if (active.has(objectValue)) {
+        invalidContract(`${path} must not contain cyclic values`);
+    }
+    active.add(objectValue);
+    try {
+        if (Array.isArray(value)) {
+            const result = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value)) {
+                    invalidContract(`${path}[${index}] must be defined`);
+                }
+                result.push(snapshotJSON(value[index], `${path}[${index}]`, active));
+            }
+            return result;
+        }
+        if (!isPlainRecord(value)) {
+            invalidContract(`${path} must contain only plain objects`);
+        }
+        const result = {};
+        for (const key of Object.keys(value)) {
+            result[key] = snapshotJSON(value[key], `${path}.${key}`, active);
+        }
+        return result;
+    }
+    catch (error) {
+        if (error instanceof JudgmentDAGCompositionError) {
+            throw error;
+        }
+        invalidContract(`${path} must be readable`);
+    }
+    finally {
+        active.delete(objectValue);
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+    }
+    return value;
+}
+function parseScope(value, path) {
+    const scope = requireRecord(value, path);
+    requireExactKeys(scope, ['type', 'id'], path);
+    if (!JUDGMENT_DAG_SCOPE_TYPES.includes(scope.type)) {
+        invalidContract(`${path}.type must be a supported scope type`);
+    }
+    return {
+        type: scope.type,
+        id: requireString(scope.id, `${path}.id`)
+    };
+}
+function parseVersionReference(value, path) {
+    const reference = requireRecord(value, path);
+    requireExactKeys(reference, ['id', 'version'], path);
+    return {
+        id: requireString(reference.id, `${path}.id`),
+        version: requireString(reference.version, `${path}.version`)
+    };
+}
+const SNAPSHOT_ID_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+function parseProblemSnapshotReference(value, path) {
+    const reference = requireRecord(value, path);
+    requireExactKeys(reference, ['snapshot_id', 'problem_id', 'revision'], path);
+    const snapshotId = requireString(reference.snapshot_id, `${path}.snapshot_id`);
+    if (!SNAPSHOT_ID_PATTERN.test(snapshotId)) {
+        invalidContract(`${path}.snapshot_id must be sha256:<64 lowercase hex>`);
+    }
+    const problemId = requireString(reference.problem_id, `${path}.problem_id`);
+    const revision = requireString(reference.revision, `${path}.revision`);
+    if (!/^[1-9]\d*$/u.test(revision)) {
+        invalidContract(`${path}.revision must be a positive decimal revision`);
+    }
+    return deepFreeze({
+        snapshot_id: snapshotId,
+        problem_id: problemId,
+        revision
+    });
+}
+function parseStringList(value, path) {
+    const values = requireArray(value, path).map((entry, index) => requireString(entry, `${path}[${index}]`));
+    if (new Set(values).size !== values.length) {
+        invalidContract(`${path} must not contain duplicates`);
+    }
+    return [...values].sort();
+}
+function parseChild(value, index) {
+    const path = `children[${index}]`;
+    const child = requireRecord(value, path);
+    requireExactKeys(child, [
+        'invocation_id',
+        'dag',
+        'question',
+        'input_contract',
+        'output_contract',
+        'required_capabilities',
+        'depends_on'
+    ], path);
+    return {
+        invocation_id: requireString(child.invocation_id, `${path}.invocation_id`),
+        dag: parseVersionReference(child.dag, `${path}.dag`),
+        question: requireString(child.question, `${path}.question`),
+        input_contract: requireString(child.input_contract, `${path}.input_contract`),
+        output_contract: requireString(child.output_contract, `${path}.output_contract`),
+        required_capabilities: parseStringList(child.required_capabilities, `${path}.required_capabilities`),
+        depends_on: parseStringList(child.depends_on, `${path}.depends_on`)
+    };
+}
+function parseComposition(value) {
+    const composition = requireRecord(value, 'composition');
+    requireExactKeys(composition, ['composition_id', 'composition_version', 'scope', 'parent_dag', 'children'], 'composition');
+    const children = requireArray(composition.children, 'composition.children')
+        .map((child, index) => parseChild(child, index))
+        .sort((left, right) => left.invocation_id.localeCompare(right.invocation_id));
+    return {
+        composition_id: requireString(composition.composition_id, 'composition.composition_id'),
+        composition_version: requireString(composition.composition_version, 'composition.composition_version'),
+        scope: parseScope(composition.scope, 'composition.scope'),
+        parent_dag: parseVersionReference(composition.parent_dag, 'composition.parent_dag'),
+        children
+    };
+}
+function equalScope(left, right) {
+    return left.type === right.type && left.id === right.id;
+}
+function equalVersionReference(left, right) {
+    return left.id === right.id && left.version === right.version;
+}
+function equalProblemSnapshotReference(left, right) {
+    return left.snapshot_id === right.snapshot_id &&
+        left.problem_id === right.problem_id &&
+        left.revision === right.revision;
+}
+function validateTopology(composition) {
+    const childById = new Map();
+    for (const child of composition.children) {
+        if (childById.has(child.invocation_id)) {
+            throw new JudgmentDAGCompositionError('duplicate_invocation', `composition contains duplicate invocation ${child.invocation_id}`, { invocation_id: child.invocation_id });
+        }
+        childById.set(child.invocation_id, child);
+    }
+    const remaining = new Map();
+    const dependents = new Map();
+    for (const child of composition.children) {
+        remaining.set(child.invocation_id, child.depends_on.length);
+        dependents.set(child.invocation_id, []);
+    }
+    for (const child of composition.children) {
+        for (const dependencyId of child.depends_on) {
+            if (!childById.has(dependencyId)) {
+                throw new JudgmentDAGCompositionError('missing_dependency', `invocation ${child.invocation_id} depends on missing invocation ${dependencyId}`, { invocation_id: child.invocation_id, dependency_id: dependencyId });
+            }
+            dependents.get(dependencyId)?.push(child.invocation_id);
+        }
+    }
+    const ready = composition.children
+        .filter((child) => remaining.get(child.invocation_id) === 0)
+        .map((child) => child.invocation_id)
+        .sort();
+    const executionOrder = [];
+    while (ready.length > 0) {
+        const invocationId = ready.shift();
+        if (invocationId === undefined) {
+            break;
+        }
+        executionOrder.push(invocationId);
+        for (const dependentId of [...(dependents.get(invocationId) ?? [])].sort()) {
+            const next = (remaining.get(dependentId) ?? 0) - 1;
+            remaining.set(dependentId, next);
+            if (next === 0) {
+                ready.push(dependentId);
+                ready.sort();
+            }
+        }
+    }
+    if (executionOrder.length !== composition.children.length) {
+        const cycle = composition.children
+            .filter((child) => (remaining.get(child.invocation_id) ?? 0) > 0)
+            .map((child) => child.invocation_id)
+            .sort();
+        throw new JudgmentDAGCompositionError('cycle', `composition contains an execution dependency cycle: ${cycle.join(' -> ')}`, { cycle });
+    }
+    return {
+        valid: true,
+        composition_id: composition.composition_id,
+        composition_version: composition.composition_version,
+        execution_order: executionOrder
+    };
+}
+export function validateJudgmentDAGComposition(value) {
+    return validateTopology(parseComposition(value));
+}
+export function assertValidJudgmentDAGComposition(value) {
+    validateJudgmentDAGComposition(value);
+}
+export function createJudgmentDAGCompositionDefinition(value) {
+    const composition = parseComposition(value);
+    validateTopology(composition);
+    return deepFreeze(composition);
+}
+function parseDelegation(value, expectedScope) {
+    const delegation = requireRecord(value, 'request.delegation');
+    requireExactKeys(delegation, ['scope', 'capabilities'], 'request.delegation');
+    const scope = parseScope(delegation.scope, 'request.delegation.scope');
+    if (!equalScope(scope, expectedScope)) {
+        throw new JudgmentDAGCompositionError('scope_mismatch', 'request delegation scope must match the composition scope');
+    }
+    return {
+        scope,
+        capabilities: parseStringList(delegation.capabilities, 'request.delegation.capabilities')
+    };
+}
+function hasCapabilities(available, required) {
+    const availableSet = new Set(available);
+    return required.every((capability) => availableSet.has(capability));
+}
+function parseRunReference(value, child) {
+    if (value === null) {
+        return null;
+    }
+    const reference = requireRecord(value, 'child.result.run_reference');
+    requireExactKeys(reference, ['run_id', 'dag', 'artifact_id'], 'child.result.run_reference');
+    const dag = parseVersionReference(reference.dag, 'child.result.run_reference.dag');
+    if (dag.id !== child.dag.id || dag.version !== child.dag.version) {
+        throw new JudgmentDAGCompositionError('dag_mismatch', `child ${child.invocation_id} returned a run for a different DAG`, { invocation_id: child.invocation_id });
+    }
+    const runId = requireString(reference.run_id, 'child.result.run_reference.run_id');
+    const artifactId = reference.artifact_id === undefined
+        ? undefined
+        : requireString(reference.artifact_id, 'child.result.run_reference.artifact_id');
+    if (artifactId !== undefined && !/^sha256:[0-9a-f]{64}$/u.test(artifactId)) {
+        invalidContract('child.result.run_reference.artifact_id must be sha256:<64 lowercase hex>');
+    }
+    return {
+        run_id: runId,
+        dag,
+        ...(artifactId === undefined
+            ? {}
+            : { artifact_id: artifactId })
+    };
+}
+function parseEvidence(value) {
+    return requireArray(value, 'child.result.evidence').map((entry, index) => {
+        const path = `child.result.evidence[${index}]`;
+        const evidence = requireRecord(entry, path);
+        requireExactKeys(evidence, ['kind', 'id', 'revision'], path);
+        const baseResult = {
+            kind: requireString(evidence.kind, `${path}.kind`),
+            id: requireString(evidence.id, `${path}.id`)
+        };
+        const revision = evidence.revision === undefined
+            ? undefined
+            : requireString(evidence.revision, `${path}.revision`);
+        return revision === undefined ? baseResult : { ...baseResult, revision };
+    });
+}
+function normalizeChildResult(value, child) {
+    const result = requireRecord(value, `child ${child.invocation_id} result`);
+    requireExactKeys(result, [
+        'status',
+        'input_contract',
+        'output_contract',
+        'run_reference',
+        'conclusion',
+        'evidence',
+        'applicability',
+        'uncertainty',
+        'reason'
+    ], `child ${child.invocation_id} result`);
+    if (!JUDGMENT_DAG_SUBDAG_STATUSES.includes(result.status)) {
+        throw new JudgmentDAGCompositionError('invalid_child_result', `child ${child.invocation_id} returned an unsupported status`, { invocation_id: child.invocation_id });
+    }
+    if (result.input_contract !== child.input_contract || result.output_contract !== child.output_contract) {
+        throw new JudgmentDAGCompositionError('contract_mismatch', `child ${child.invocation_id} returned a different input or output contract`, { invocation_id: child.invocation_id });
+    }
+    const runReference = parseRunReference(result.run_reference, child);
+    if (result.status === 'completed' && runReference === null) {
+        throw new JudgmentDAGCompositionError('invalid_child_result', `completed child ${child.invocation_id} must include a run reference`, { invocation_id: child.invocation_id });
+    }
+    const normalized = {
+        status: result.status,
+        input_contract: child.input_contract,
+        output_contract: child.output_contract,
+        run_reference: runReference,
+        conclusion: snapshotJSON(result.conclusion, `child ${child.invocation_id} result.conclusion`),
+        evidence: parseEvidence(result.evidence),
+        applicability: snapshotJSON(result.applicability, `child ${child.invocation_id} result.applicability`),
+        uncertainty: snapshotJSON(result.uncertainty, `child ${child.invocation_id} result.uncertainty`)
+    };
+    if (result.reason === undefined) {
+        return deepFreeze(normalized);
+    }
+    return deepFreeze({
+        ...normalized,
+        reason: requireString(result.reason, `child ${child.invocation_id} result.reason`)
+    });
+}
+function incompleteResult(status, child, reason) {
+    return deepFreeze({
+        status,
+        input_contract: child.input_contract,
+        output_contract: child.output_contract,
+        run_reference: null,
+        conclusion: null,
+        evidence: [],
+        applicability: { status: 'not_run' },
+        uncertainty: { status: 'blocked' },
+        reason
+    });
+}
+function parsePort(value) {
+    const port = requireRecord(value, 'request.port');
+    requireExactKeys(port, ['execute'], 'request.port');
+    if (typeof port.execute !== 'function') {
+        invalidContract('request.port.execute must be a function');
+    }
+    return port;
+}
+function parseSnapshotReader(value) {
+    const reader = requireRecord(value, 'request.snapshot_reader');
+    requireExactKeys(reader, ['read'], 'request.snapshot_reader');
+    if (typeof reader.read !== 'function') {
+        invalidContract('request.snapshot_reader.read must be a function');
+    }
+    return reader;
+}
+function parseDAGResolver(value) {
+    const resolver = requireRecord(value, 'request.dag_resolver');
+    requireExactKeys(resolver, ['resolve'], 'request.dag_resolver');
+    if (typeof resolver.resolve !== 'function') {
+        invalidContract('request.dag_resolver.resolve must be a function');
+    }
+    return resolver;
+}
+function parseContractValidator(value) {
+    const validator = requireRecord(value, 'request.contract_validator');
+    requireExactKeys(validator, ['validate'], 'request.contract_validator');
+    if (typeof validator.validate !== 'function') {
+        invalidContract('request.contract_validator.validate must be a function');
+    }
+    return validator;
+}
+function parseArtifactReader(value) {
+    const reader = requireRecord(value, 'request.artifact_reader');
+    requireExactKeys(reader, ['read'], 'request.artifact_reader');
+    if (typeof reader.read !== 'function') {
+        invalidContract('request.artifact_reader.read must be a function');
+    }
+    return reader;
+}
+function parseRequest(value) {
+    const request = requireRecord(value, 'request');
+    requireExactKeys(request, [
+        'run_id',
+        'composition',
+        'question',
+        'input',
+        'problem_snapshot',
+        'fixed_conditions',
+        'delegation',
+        'snapshot_reader',
+        'dag_resolver',
+        'contract_validator',
+        'artifact_reader',
+        'port'
+    ], 'request');
+    const composition = createJudgmentDAGCompositionDefinition(request.composition);
+    const validation = validateTopology(composition);
+    const artifactReader = request.artifact_reader === undefined
+        ? undefined
+        : parseArtifactReader(request.artifact_reader);
+    return {
+        run_id: requireString(request.run_id, 'request.run_id'),
+        composition,
+        question: requireString(request.question, 'request.question'),
+        input: snapshotJSON(request.input, 'request.input'),
+        problem_snapshot: parseProblemSnapshotReference(request.problem_snapshot, 'request.problem_snapshot'),
+        fixed_conditions: snapshotJSON(request.fixed_conditions, 'request.fixed_conditions'),
+        delegation: parseDelegation(request.delegation, composition.scope),
+        snapshot_reader: parseSnapshotReader(request.snapshot_reader),
+        dag_resolver: parseDAGResolver(request.dag_resolver),
+        contract_validator: parseContractValidator(request.contract_validator),
+        ...(artifactReader === undefined ? {} : { artifact_reader: artifactReader }),
+        port: parsePort(request.port),
+        validation
+    };
+}
+function parseVersionResolution(value, path) {
+    const resolution = requireRecord(value, path);
+    requireExactKeys(resolution, ['dag', 'input_contract', 'output_contract'], path);
+    return deepFreeze({
+        dag: parseVersionReference(resolution.dag, `${path}.dag`),
+        input_contract: requireString(resolution.input_contract, `${path}.input_contract`),
+        output_contract: requireString(resolution.output_contract, `${path}.output_contract`)
+    });
+}
+async function resolveDAGReferences(parsed) {
+    const resolve = async (role, dag, invocationId) => {
+        let rawResolution;
+        try {
+            rawResolution = await parsed.dag_resolver.resolve({
+                role,
+                ...(invocationId === undefined ? {} : { invocation_id: invocationId }),
+                dag
+            });
+        }
+        catch {
+            throw new JudgmentDAGCompositionError('dag_unavailable', `${role} DAG ${dag.id}@${dag.version} could not be resolved`, invocationId === undefined ? {} : { invocation_id: invocationId });
+        }
+        try {
+            return parseVersionResolution(rawResolution, `${role} DAG resolution`);
+        }
+        catch {
+            throw new JudgmentDAGCompositionError('dag_unavailable', `${role} DAG ${dag.id}@${dag.version} returned an invalid resolution`, invocationId === undefined ? {} : { invocation_id: invocationId });
+        }
+    };
+    const parentResolution = await resolve('parent', parsed.composition.parent_dag);
+    if (!equalVersionReference(parentResolution.dag, parsed.composition.parent_dag)) {
+        throw new JudgmentDAGCompositionError('dag_mismatch', 'parent DAG resolver returned a different version');
+    }
+    for (const child of parsed.composition.children) {
+        const resolution = await resolve('child', child.dag, child.invocation_id);
+        if (!equalVersionReference(resolution.dag, child.dag)) {
+            throw new JudgmentDAGCompositionError('dag_mismatch', `child ${child.invocation_id} DAG resolver returned a different version`, { invocation_id: child.invocation_id });
+        }
+        if (resolution.input_contract !== child.input_contract ||
+            resolution.output_contract !== child.output_contract) {
+            throw new JudgmentDAGCompositionError('contract_mismatch', `child ${child.invocation_id} DAG version has a different input or output contract`, { invocation_id: child.invocation_id });
+        }
+        try {
+            await parsed.contract_validator.validate({
+                role: 'child',
+                invocation_id: child.invocation_id,
+                dag: child.dag,
+                input_contract: resolution.input_contract,
+                output_contract: resolution.output_contract
+            });
+        }
+        catch {
+            throw new JudgmentDAGCompositionError('contract_mismatch', `child ${child.invocation_id} input/output contract was rejected`, { invocation_id: child.invocation_id });
+        }
+    }
+}
+async function readProblemSnapshot(parsed) {
+    let rawResult;
+    try {
+        rawResult = await parsed.snapshot_reader.read({
+            mode: 'read',
+            reference_resolution: 'current',
+            reference: parsed.problem_snapshot
+        });
+    }
+    catch {
+        throw new JudgmentDAGCompositionError('snapshot_unavailable', 'the selected JudgmentProblem snapshot could not be read');
+    }
+    try {
+        const result = requireRecord(rawResult, 'snapshot_reader result');
+        requireExactKeys(result, ['reference_resolution', 'status', 'reference', 'snapshot'], 'snapshot_reader result');
+        if (result.status !== 'resolved' || result.reference_resolution !== 'current') {
+            throw new Error('snapshot is not resolved');
+        }
+        const reference = parseProblemSnapshotReference(result.reference, 'snapshot_reader result.reference');
+        if (!equalProblemSnapshotReference(reference, parsed.problem_snapshot)) {
+            throw new Error('snapshot reference does not match the requested snapshot');
+        }
+        const snapshot = snapshotJSON(result.snapshot, 'snapshot_reader result.snapshot');
+        const snapshotRecord = requireRecord(snapshot, 'snapshot_reader result.snapshot');
+        if (snapshotRecord.snapshot_version !== 'judgment-problem-snapshot.v1' ||
+            snapshotRecord.problem_id !== parsed.problem_snapshot.problem_id ||
+            snapshotRecord.revision !== parsed.problem_snapshot.revision) {
+            throw new Error('snapshot identity does not match the requested snapshot');
+        }
+        return deepFreeze(snapshot);
+    }
+    catch {
+        throw new JudgmentDAGCompositionError('snapshot_unavailable', 'the snapshot reader returned an invalid or mismatched JudgmentProblem snapshot');
+    }
+}
+async function verifyArtifactReadback(result, child, reader) {
+    const runReference = result.run_reference;
+    if (runReference?.artifact_id === undefined)
+        return;
+    if (reader === undefined) {
+        throw new JudgmentDAGCompositionError('artifact_readback_failed', `child ${child.invocation_id} returned an artifact without a readback adapter`, { invocation_id: child.invocation_id });
+    }
+    let rawArtifact;
+    try {
+        rawArtifact = await reader.read({
+            artifact_id: runReference.artifact_id,
+            expected_run_id: runReference.run_id,
+            expected_dag: child.dag
+        });
+    }
+    catch {
+        throw new JudgmentDAGCompositionError('artifact_readback_failed', `child ${child.invocation_id} artifact could not be read back`, { invocation_id: child.invocation_id });
+    }
+    try {
+        const artifact = requireRecord(rawArtifact, `child ${child.invocation_id} artifact`);
+        if (requireString(artifact.run_id, `child ${child.invocation_id} artifact.run_id`) !== runReference.run_id) {
+            throw new Error('artifact run identity does not match the child result');
+        }
+        const artifactDAG = requireRecord(artifact.dag, `child ${child.invocation_id} artifact.dag`);
+        const artifactDAGReference = {
+            id: requireString(artifactDAG.id, `child ${child.invocation_id} artifact.dag.id`),
+            version: requireString(artifactDAG.version, `child ${child.invocation_id} artifact.dag.version`)
+        };
+        if (!equalVersionReference(artifactDAGReference, child.dag)) {
+            throw new Error('artifact DAG identity does not match the child result');
+        }
+    }
+    catch {
+        throw new JudgmentDAGCompositionError('artifact_readback_failed', `child ${child.invocation_id} artifact readback did not match the child run`, { invocation_id: child.invocation_id });
+    }
+}
+function childByInvocation(composition) {
+    return new Map(composition.children.map((child) => [child.invocation_id, child]));
+}
+/**
+ * Execute only the explicitly declared evaluation port for each child.
+ * Resource reservation, deploys, external sends, and arbitrary host-code
+ * isolation remain outside this OSS boundary.
+ */
+export async function executeJudgmentDAGComposition(request) {
+    const parsed = parseRequest(request);
+    const childrenById = childByInvocation(parsed.composition);
+    // Preflight every child before the first port call. A later capability
+    // violation therefore cannot leave an earlier child partially evaluated.
+    for (const child of parsed.composition.children) {
+        if (!hasCapabilities(parsed.delegation.capabilities, child.required_capabilities)) {
+            const missing = child.required_capabilities.filter((capability) => !parsed.delegation.capabilities.includes(capability));
+            throw new JudgmentDAGCompositionError('capability_violation', `child ${child.invocation_id} requires undelegated capabilities: ${missing.join(', ')}`, { invocation_id: child.invocation_id });
+        }
+    }
+    // Resolve the selected problem snapshot and every declared DAG version before
+    // the first evaluation port call. The snapshot adapter owns current lookup
+    // and authorization; the coordinator only accepts the exact locator and
+    // identity it was given.
+    await readProblemSnapshot(parsed);
+    await resolveDAGReferences(parsed);
+    const childRecords = new Map();
+    for (const invocationId of parsed.validation.execution_order) {
+        const child = childrenById.get(invocationId);
+        if (child === undefined) {
+            throw new JudgmentDAGCompositionError('invalid_contract', `execution order references unknown invocation ${invocationId}`, { invocation_id: invocationId });
+        }
+        const dependencyResults = child.depends_on.map((dependencyId) => {
+            const dependency = childRecords.get(dependencyId);
+            if (dependency === undefined) {
+                throw new JudgmentDAGCompositionError('invalid_contract', `dependency ${dependencyId} has not been recorded before ${invocationId}`, { invocation_id: invocationId, dependency_id: dependencyId });
+            }
+            return {
+                invocation_id: dependency.invocation_id,
+                result: dependency.result
+            };
+        });
+        const delegation = {
+            scope: parsed.delegation.scope,
+            capabilities: child.required_capabilities
+        };
+        const blockedDependency = dependencyResults.find((dependency) => dependency.result.status !== 'completed');
+        let result;
+        if (blockedDependency !== undefined) {
+            result = incompleteResult('held', child, `dependency ${blockedDependency.invocation_id} is ${blockedDependency.result.status}`);
+        }
+        else {
+            const childRequest = deepFreeze({
+                mode: 'evaluation',
+                parent_run_id: parsed.run_id,
+                composition: {
+                    id: parsed.composition.composition_id,
+                    version: parsed.composition.composition_version
+                },
+                invocation_id: child.invocation_id,
+                dag: child.dag,
+                question: child.question,
+                input: parsed.input,
+                problem_snapshot: parsed.problem_snapshot,
+                fixed_conditions: parsed.fixed_conditions,
+                delegation,
+                dependency_results: dependencyResults
+            });
+            let rawResult;
+            let executorFailed = false;
+            try {
+                rawResult = await parsed.port.execute(childRequest);
+            }
+            catch {
+                executorFailed = true;
+            }
+            if (executorFailed) {
+                result = incompleteResult('failed', child, 'evaluation port failed');
+            }
+            else {
+                // Keep result validation outside the executor catch. A malformed or
+                // mismatched result is a contract error, not a successful child.
+                result = normalizeChildResult(rawResult, child);
+                await verifyArtifactReadback(result, child, parsed.artifact_reader);
+            }
+        }
+        const childRecord = {
+            invocation_id: child.invocation_id,
+            dag: child.dag,
+            question: child.question,
+            input_contract: child.input_contract,
+            output_contract: child.output_contract,
+            input: parsed.input,
+            problem_snapshot: parsed.problem_snapshot,
+            fixed_conditions: parsed.fixed_conditions,
+            delegation,
+            dependency_invocation_ids: child.depends_on,
+            dependency_results: dependencyResults,
+            result
+        };
+        childRecords.set(invocationId, deepFreeze(childRecord));
+    }
+    const children = parsed.validation.execution_order.map((invocationId) => {
+        const child = childRecords.get(invocationId);
+        if (child === undefined) {
+            throw new JudgmentDAGCompositionError('invalid_contract', `child ${invocationId} was not recorded`, { invocation_id: invocationId });
+        }
+        return child;
+    });
+    const status = children.some((child) => child.result.status === 'failed')
+        ? 'failed'
+        : children.some((child) => child.result.status === 'held')
+            ? 'held'
+            : 'completed';
+    return deepFreeze({
+        run_id: parsed.run_id,
+        composition: {
+            id: parsed.composition.composition_id,
+            version: parsed.composition.composition_version
+        },
+        parent_dag: parsed.composition.parent_dag,
+        question: parsed.question,
+        input: parsed.input,
+        problem_snapshot: parsed.problem_snapshot,
+        fixed_conditions: parsed.fixed_conditions,
+        delegation: parsed.delegation,
+        execution_order: parsed.validation.execution_order,
+        status,
+        children
+    });
+}