agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/registries/todoReadinessContract.js

@@ -0,0 +1,448 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMapping } from "../core/yaml.js";
+const SCHEMA_VERSION = "agentera.todoReadiness.v1";
+const PHASE_AUTHORITY = "protocol.yaml#PHASES[*].capabilities";
+const REQUIRED_FIELDS = [
+    "capability",
+    "reason",
+    "dependencies",
+    "blocked",
+    "gate",
+    "queue_rank",
+    "order_reason",
+];
+const EVALUATION_PRECEDENCE = [
+    "todo_resolved",
+    "readiness_absent",
+    "blocked",
+    "gate_pending",
+    "dependency_cross_artifact",
+    "dependency_missing",
+    "dependency_cycle",
+    "dependency_open",
+    "ordering_conflict",
+    "actionable",
+];
+const PROHIBITED_TIEBREAKERS = [
+    "entity_id",
+    "file_order",
+    "filesystem_time",
+    "created_or_modified_time",
+    "description_text",
+];
+const OUTCOME_EXPECTATIONS = {
+    todo_resolved: { result: "resolved", eligible: false, attention: "none", recovery: "null" },
+    readiness_absent: { result: "needs-triage", eligible: false, attention: "item", recovery: "required" },
+    blocked: { result: "blocked", eligible: false, attention: "item", recovery: "required" },
+    gate_pending: { result: "gated", eligible: false, attention: "none", recovery: "required" },
+    dependency_cross_artifact: { result: "needs-triage", eligible: false, attention: "item", recovery: "required" },
+    dependency_missing: { result: "needs-triage", eligible: false, attention: "item", recovery: "required" },
+    dependency_cycle: { result: "needs-triage", eligible: false, attention: "item", recovery: "required" },
+    dependency_open: { result: "waiting", eligible: false, attention: "none", recovery: "required" },
+    dependency_resolved: { result: "satisfied", eligible: null, attention: "none", recovery: "null" },
+    ordering_conflict: { result: "needs-triage", eligible: false, attention: "item", recovery: "required" },
+    actionable: { result: "actionable", eligible: true, attention: "none", recovery: "null" },
+};
+const QUEUE_EXPECTATIONS = {
+    mixed_actionable_and_triage: {
+        selection: "highest_ordered_actionable",
+        attention: "bounded_triage_summary",
+    },
+    all_non_actionable: {
+        selection: "abstain",
+        attention: "bounded_highest_severity_summary",
+    },
+};
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringList(value) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))
+        return null;
+    return value;
+}
+function sameList(actual, expected) {
+    const list = stringList(actual);
+    return list !== null && list.length === expected.length && list.every((value, index) => value === expected[index]);
+}
+function canonicalCapabilities(capabilityContract, errors, sourceLabel) {
+    const aliases = isMapping(capabilityContract.ROUTE_ALIASES)
+        ? capabilityContract.ROUTE_ALIASES.primary_aliases
+        : null;
+    if (!Array.isArray(aliases)) {
+        errors.push(`${sourceLabel}: ROUTE_ALIASES.primary_aliases must be a list`);
+        return [];
+    }
+    const capabilities = [];
+    for (const alias of aliases) {
+        if (!isMapping(alias) || typeof alias.capability !== "string" || !alias.capability.trim()) {
+            errors.push(`${sourceLabel}: each ROUTE_ALIASES.primary_aliases entry must declare capability`);
+            continue;
+        }
+        capabilities.push(alias.capability);
+    }
+    return capabilities;
+}
+function derivePhaseMapping(protocol, canonical, errors, sourceLabel) {
+    const mapping = new Map();
+    if (!isMapping(protocol.PHASES)) {
+        errors.push(`${sourceLabel}: protocol PHASES must be a mapping`);
+        return mapping;
+    }
+    for (const entry of Object.values(protocol.PHASES)) {
+        if (!isMapping(entry))
+            continue;
+        const phase = typeof entry.value === "string" ? entry.value : "";
+        const capabilities = stringList(entry.capabilities);
+        if (!phase || capabilities === null) {
+            errors.push(`${sourceLabel}: each PHASES entry must declare a value and capabilities list`);
+            continue;
+        }
+        for (const capability of capabilities) {
+            if (!canonical.has(capability)) {
+                errors.push(`${sourceLabel}: PHASES capability '${capability}' is not canonical`);
+            }
+            if (mapping.has(capability)) {
+                errors.push(`${sourceLabel}: capability '${capability}' appears in multiple PHASES entries`);
+            }
+            else {
+                mapping.set(capability, phase);
+            }
+        }
+    }
+    return mapping;
+}
+function validateFields(readiness, errors, sourceLabel) {
+    const fields = readiness.fields;
+    if (!isMapping(fields)) {
+        errors.push(`${sourceLabel}: READINESS.fields must be a mapping`);
+        return;
+    }
+    for (const name of REQUIRED_FIELDS) {
+        const field = fields[name];
+        if (!isMapping(field)) {
+            errors.push(`${sourceLabel}: READINESS.fields.${name} must be a mapping`);
+            continue;
+        }
+        if (field.required !== true) {
+            errors.push(`${sourceLabel}: READINESS.fields.${name}.required must be true`);
+        }
+    }
+    const capability = fields.capability;
+    if (isMapping(capability) && capability.enum_source !== PHASE_AUTHORITY) {
+        errors.push(`${sourceLabel}: READINESS.fields.capability.enum_source must be ${PHASE_AUTHORITY}`);
+    }
+    const dependencies = fields.dependencies;
+    const dependencyEntries = isMapping(dependencies) && isMapping(dependencies.entries)
+        ? dependencies.entries
+        : null;
+    const dependencyArtifact = dependencyEntries && isMapping(dependencyEntries.artifact)
+        ? dependencyEntries.artifact
+        : null;
+    if (dependencyArtifact?.const !== "todo") {
+        errors.push(`${sourceLabel}: dependency artifact const must be todo`);
+    }
+}
+function validateOutcomes(readiness, errors, sourceLabel) {
+    const outcomes = readiness.outcomes;
+    if (!isMapping(outcomes)) {
+        errors.push(`${sourceLabel}: READINESS.outcomes must be a mapping`);
+        return;
+    }
+    for (const [name, expected] of Object.entries(OUTCOME_EXPECTATIONS)) {
+        const outcome = outcomes[name];
+        if (!isMapping(outcome)) {
+            errors.push(`${sourceLabel}: READINESS.outcomes.${name} must be a mapping`);
+            continue;
+        }
+        if (outcome.result !== expected.result) {
+            errors.push(`${sourceLabel}: READINESS.outcomes.${name}.result must be ${expected.result}`);
+        }
+        if (outcome.eligible !== expected.eligible) {
+            errors.push(`${sourceLabel}: READINESS.outcomes.${name}.eligible must be ${String(expected.eligible)}`);
+        }
+        if (outcome.attention !== expected.attention) {
+            errors.push(`${sourceLabel}: READINESS.outcomes.${name}.attention must be one of: none, item`);
+        }
+        const validRecovery = expected.recovery === "null"
+            ? outcome.recovery === null
+            : typeof outcome.recovery === "string" && outcome.recovery.trim().length > 0;
+        if (!validRecovery) {
+            errors.push(`${sourceLabel}: READINESS.outcomes.${name}.recovery must be ${expected.recovery === "null" ? "null" : "a non-empty string"}`);
+        }
+    }
+}
+function validateQueueOutcomes(readiness, errors, sourceLabel) {
+    const outcomes = readiness.queue_outcomes;
+    if (!isMapping(outcomes)) {
+        errors.push(`${sourceLabel}: READINESS.queue_outcomes must be a mapping`);
+        return;
+    }
+    for (const [name, expected] of Object.entries(QUEUE_EXPECTATIONS)) {
+        const outcome = outcomes[name];
+        if (!isMapping(outcome)) {
+            errors.push(`${sourceLabel}: READINESS.queue_outcomes.${name} must be a mapping`);
+            continue;
+        }
+        if (outcome.selection !== expected.selection || outcome.attention !== expected.attention) {
+            errors.push(`${sourceLabel}: READINESS.queue_outcomes.${name} must use selection=${expected.selection} and attention=${expected.attention}`);
+        }
+        if (typeof outcome.recovery !== "string" || !outcome.recovery.trim()) {
+            errors.push(`${sourceLabel}: READINESS.queue_outcomes.${name}.recovery must be a non-empty string`);
+        }
+    }
+}
+function validateOrdering(readiness, errors, sourceLabel) {
+    const ordering = readiness.ordering;
+    if (!isMapping(ordering)) {
+        errors.push(`${sourceLabel}: READINESS.ordering must be a mapping`);
+        return;
+    }
+    if (ordering.primary !== "protocol.yaml#SEVERITY_ISSUE") {
+        errors.push(`${sourceLabel}: READINESS.ordering.primary must be protocol.yaml#SEVERITY_ISSUE`);
+    }
+    for (const legacy of ["within_severity", "duplicate_rank", "prohibited_tiebreakers"]) {
+        if (legacy in ordering)
+            errors.push(`${sourceLabel}: READINESS.ordering.${legacy} must be declared under one ordering mode`);
+    }
+    const modes = ordering.modes;
+    if (!isMapping(modes)) {
+        errors.push(`${sourceLabel}: READINESS.ordering.modes must be a mapping`);
+        return;
+    }
+    if (Object.keys(modes).sort().join(",") !== "nonprojected,projected_startup") {
+        errors.push(`${sourceLabel}: READINESS.ordering.modes must contain only nonprojected and projected_startup`);
+    }
+    const nonprojected = modes.nonprojected;
+    if (!isMapping(nonprojected)) {
+        errors.push(`${sourceLabel}: READINESS.ordering.modes.nonprojected must be a mapping`);
+    }
+    else {
+        if (Object.keys(nonprojected).sort().join(",") !== "duplicate_rank,prohibited_tiebreakers,within_severity") {
+            errors.push(`${sourceLabel}: READINESS.ordering.modes.nonprojected has unsupported fields`);
+        }
+        if (nonprojected.within_severity !== "queue_rank_ascending") {
+            errors.push(`${sourceLabel}: READINESS.ordering.modes.nonprojected.within_severity must be queue_rank_ascending`);
+        }
+        if (nonprojected.duplicate_rank !== "ordering_conflict") {
+            errors.push(`${sourceLabel}: READINESS.ordering.modes.nonprojected.duplicate_rank must be ordering_conflict`);
+        }
+        if (!sameList(nonprojected.prohibited_tiebreakers, PROHIBITED_TIEBREAKERS)) {
+            errors.push(`${sourceLabel}: READINESS.ordering.modes.nonprojected.prohibited_tiebreakers must equal ${PROHIBITED_TIEBREAKERS.join(", ")}`);
+        }
+    }
+    const projected = modes.projected_startup;
+    const projectedRules = {
+        entity_annotation: "required_for_every_entity",
+        eligibility: "before_order",
+        managed_before_absent: true,
+        managed_within_severity: "markdown_order_ascending",
+        managed_duplicate_rank: "ignored",
+        absent_within_severity: "queue_rank_then_id",
+        absent_duplicate_rank: "entity_id_ascending",
+    };
+    if (!isMapping(projected)) {
+        errors.push(`${sourceLabel}: READINESS.ordering.modes.projected_startup must be a mapping`);
+    }
+    else {
+        if (Object.keys(projected).sort().join(",") !== Object.keys(projectedRules).sort().join(",")) {
+            errors.push(`${sourceLabel}: READINESS.ordering.modes.projected_startup has unsupported fields`);
+        }
+        for (const [field, expected] of Object.entries(projectedRules)) {
+            if (projected[field] !== expected)
+                errors.push(`${sourceLabel}: READINESS.ordering.modes.projected_startup.${field} must be ${String(expected)}`);
+        }
+    }
+}
+export function validateTodoReadinessContract(todoSchema, protocol, capabilityContract, sourceLabel = "TODO readiness contract") {
+    const errors = [];
+    const readiness = todoSchema.READINESS;
+    if (!isMapping(readiness))
+        return [`${sourceLabel}: READINESS must be a mapping`];
+    if (readiness.schema_version !== SCHEMA_VERSION) {
+        errors.push(`${sourceLabel}: READINESS.schema_version must be ${SCHEMA_VERSION}`);
+    }
+    const canonicalList = canonicalCapabilities(capabilityContract, errors, sourceLabel);
+    const canonical = new Set(canonicalList);
+    const phaseByCapability = derivePhaseMapping(protocol, canonical, errors, sourceLabel);
+    const destination = readiness.destination;
+    if (!isMapping(destination)) {
+        errors.push(`${sourceLabel}: READINESS.destination must be a mapping`);
+    }
+    else {
+        if (destination.phase_authority !== PHASE_AUTHORITY) {
+            errors.push(`${sourceLabel}: READINESS.destination.phase_authority must be ${PHASE_AUTHORITY}`);
+        }
+        for (const duplicate of ["allowed_destinations", "phase_mapping"]) {
+            if (duplicate in destination) {
+                errors.push(`${sourceLabel}: READINESS.destination.${duplicate} duplicates the canonical PHASES authority`);
+            }
+        }
+        const excluded = destination.excluded_capabilities;
+        if (!isMapping(excluded)) {
+            errors.push(`${sourceLabel}: READINESS.destination.excluded_capabilities must be a mapping`);
+        }
+        else {
+            for (const capability of canonicalList) {
+                const mapped = phaseByCapability.has(capability);
+                const exclusion = excluded[capability];
+                if (mapped && exclusion !== undefined) {
+                    errors.push(`${sourceLabel}: mapped capability '${capability}' must not also be excluded`);
+                }
+                else if (!mapped && (typeof exclusion !== "string" || !exclusion.trim())) {
+                    errors.push(`${sourceLabel}: canonical capability '${capability}' must be mapped to one phase or explicitly excluded`);
+                }
+            }
+            for (const [capability, reason] of Object.entries(excluded)) {
+                if (!canonical.has(capability)) {
+                    errors.push(`${sourceLabel}: excluded capability '${capability}' is not canonical`);
+                }
+                if (typeof reason !== "string" || !reason.trim()) {
+                    errors.push(`${sourceLabel}: excluded capability '${capability}' must have a non-empty reason`);
+                }
+            }
+        }
+    }
+    validateFields(readiness, errors, sourceLabel);
+    const evaluation = readiness.evaluation;
+    if (!isMapping(evaluation) || !sameList(evaluation.precedence, EVALUATION_PRECEDENCE)) {
+        errors.push(`${sourceLabel}: READINESS.evaluation.precedence must equal ${EVALUATION_PRECEDENCE.join(", ")}`);
+    }
+    validateOutcomes(readiness, errors, sourceLabel);
+    validateQueueOutcomes(readiness, errors, sourceLabel);
+    validateOrdering(readiness, errors, sourceLabel);
+    return errors;
+}
+function requiredMappingFields(label, value, names) {
+    if (!isMapping(value))
+        return [`${label} must be a mapping or null`];
+    const errors = [];
+    for (const name of names) {
+        if (!(name in value))
+            errors.push(`${label}.${name} is required`);
+        else if (typeof value[name] !== "string" || !String(value[name]).trim())
+            errors.push(`${label}.${name} must be a non-empty string`);
+    }
+    for (const name of Object.keys(value)) {
+        if (!names.includes(name))
+            errors.push(`${label} has unsupported field '${name}'`);
+    }
+    return errors;
+}
+export function todoReadinessRecordViolations(readiness, contract = loadTodoReadinessContract()) {
+    if (!isMapping(readiness))
+        return ["readiness must be a mapping"];
+    const errors = [];
+    for (const field of REQUIRED_FIELDS) {
+        if (!(field in readiness))
+            errors.push(`${field} is required when readiness is declared`);
+    }
+    for (const field of Object.keys(readiness)) {
+        if (!REQUIRED_FIELDS.includes(field))
+            errors.push(`readiness has unsupported field '${field}'`);
+    }
+    if (typeof readiness.capability !== "string" || !contract.allowedDestinations.includes(readiness.capability)) {
+        errors.push(`capability must be one of: ${contract.allowedDestinations.join(", ")}`);
+    }
+    if (typeof readiness.reason !== "string" || !readiness.reason.trim())
+        errors.push("reason must be a non-empty string");
+    if (!Array.isArray(readiness.dependencies))
+        errors.push("dependencies must be a list");
+    else
+        for (const [index, dependency] of readiness.dependencies.entries()) {
+            if (!isMapping(dependency)) {
+                errors.push(`dependencies[${index}] must be a mapping`);
+                continue;
+            }
+            for (const field of Object.keys(dependency)) {
+                if (field !== "artifact" && field !== "id")
+                    errors.push(`dependencies[${index}] has unsupported field '${field}'`);
+            }
+            if (dependency.artifact !== "todo")
+                errors.push(`dependencies[${index}] dependency artifact must be 'todo'`);
+            if (!/^[a-z]{10}$/.test(String(dependency.id ?? "")))
+                errors.push(`dependencies[${index}] dependency ID must be ten lowercase letters`);
+        }
+    if (readiness.blocked !== null)
+        errors.push(...requiredMappingFields("blocked", readiness.blocked, ["reason", "recovery"]));
+    if (readiness.gate !== null) {
+        errors.push(...requiredMappingFields("gate", readiness.gate, ["state", "reason", "recovery"]));
+        const gate = isMapping(readiness.gate) ? readiness.gate : {};
+        const gateFields = isMapping(contract.fields.gate) && isMapping(contract.fields.gate.fields) ? contract.fields.gate.fields : {};
+        const stateField = isMapping(gateFields.state) ? gateFields.state : {};
+        const allowed = stringList(stateField.enum) ?? [];
+        if (typeof gate.state === "string" && !allowed.includes(gate.state))
+            errors.push(`gate.state must be one of: ${allowed.join(", ")}`);
+    }
+    const queueField = isMapping(contract.fields.queue_rank) ? contract.fields.queue_rank : {};
+    const minimum = typeof queueField.minimum === "number" ? queueField.minimum : 1;
+    if (!Number.isInteger(readiness.queue_rank) || Number(readiness.queue_rank) < minimum)
+        errors.push(`queue_rank must be an integer greater than or equal to ${minimum}`);
+    if (typeof readiness.order_reason !== "string" || !readiness.order_reason.trim())
+        errors.push("order_reason must be a non-empty string");
+    return [...new Set(errors)];
+}
+export function todoReadinessReferenceViolations(itemId, readiness, todos) {
+    if (!isMapping(readiness) || !Array.isArray(readiness.dependencies))
+        return [];
+    const dependencies = readiness.dependencies
+        .filter(isMapping)
+        .map((dependency) => String(dependency.id ?? ""))
+        .filter((id) => /^[a-z]{10}$/.test(id));
+    const byId = new Map(todos.map((todo) => [todo.id, todo.record]));
+    const errors = [];
+    for (const dependency of dependencies) {
+        if (dependency === itemId)
+            errors.push(`TODO '${itemId}' cannot depend on itself`);
+        else if (!byId.has(dependency))
+            errors.push(`TODO dependency '${dependency}' does not exist`);
+    }
+    const reachesItem = (id, seen) => {
+        if (id === itemId)
+            return true;
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        const record = byId.get(id);
+        const nested = isMapping(record?.readiness) && Array.isArray(record.readiness.dependencies)
+            ? record.readiness.dependencies.filter(isMapping).map((dependency) => String(dependency.id ?? ""))
+            : [];
+        return nested.some((dependency) => reachesItem(dependency, seen));
+    };
+    if (!errors.length && dependencies.some((dependency) => reachesItem(dependency, new Set()))) {
+        errors.push(`TODO '${itemId}' would create a dependency cycle`);
+    }
+    return errors;
+}
+export class TodoReadinessContractError extends Error {
+    errors;
+    constructor(errors) {
+        super(errors.join("; "));
+        this.errors = errors;
+        this.name = "TodoReadinessContractError";
+    }
+}
+export function loadTodoReadinessContract(todoSchemaPath = path.join(resolveSourceRoot(), "skills", "agentera", "schemas", "artifacts", "todo.yaml"), protocolPath = path.join(resolveSourceRoot(), "skills", "agentera", "protocol.yaml"), capabilityContractPath = path.join(resolveSourceRoot(), "skills", "agentera", "capability_schema_contract.yaml")) {
+    const todoSchema = loadYamlMapping(fs.readFileSync(todoSchemaPath, "utf8"));
+    const protocol = loadYamlMapping(fs.readFileSync(protocolPath, "utf8"));
+    const capabilityContract = loadYamlMapping(fs.readFileSync(capabilityContractPath, "utf8"));
+    const errors = validateTodoReadinessContract(todoSchema, protocol, capabilityContract, todoSchemaPath);
+    if (errors.length)
+        throw new TodoReadinessContractError(errors);
+    const readiness = todoSchema.READINESS;
+    const destination = readiness.destination;
+    const phaseByCapability = derivePhaseMapping(protocol, new Set(canonicalCapabilities(capabilityContract, [], capabilityContractPath)), [], protocolPath);
+    return {
+        schemaVersion: readiness.schema_version,
+        allowedDestinations: [...phaseByCapability.keys()],
+        phaseByCapability,
+        excludedCapabilities: destination.excluded_capabilities,
+        fields: readiness.fields,
+        precedence: readiness.evaluation.precedence,
+        outcomes: readiness.outcomes,
+        queueOutcomes: readiness.queue_outcomes,
+        ordering: readiness.ordering,
+    };
+}

package/dist/registries/triggerLoader.js

@@ -0,0 +1,174 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+export class TriggerLoaderError extends Error {
+    errors;
+    constructor(errors) {
+        super(errors.join("; "));
+        this.name = "TriggerLoaderError";
+        this.errors = errors;
+    }
+}
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isNumericKey(key) {
+    return /^\d+$/.test(key) && Number(key) >= 1;
+}
+/** Absolute directory holding the Agentera capability schemas. */
+export function capabilitiesBaseDir(sourceRoot = resolveSourceRoot()) {
+    return path.join(sourceRoot, "skills", "agentera", "capabilities");
+}
+/** Absolute path to a capability's triggers.yaml. */
+export function triggersYamlPath(capability, sourceRoot = resolveSourceRoot()) {
+    return path.join(capabilitiesBaseDir(sourceRoot), capability, "schemas", "triggers.yaml");
+}
+function readTriggersYaml(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new TriggerLoaderError([`triggers.yaml not found at ${filePath}`]);
+    }
+    return loadYamlMapping(fs.readFileSync(filePath, "utf8")); // cast: YAML parse IO boundary
+}
+function resolveDisambiguation(value, location, allowedCapabilityIds) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new TriggerLoaderError([
+            `${location} disambiguates_against must be a list of mappings`,
+        ]);
+    }
+    const entries = [];
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (!isMapping(item)) {
+            throw new TriggerLoaderError([
+                `${location} disambiguates_against[${i}] must be a mapping with 'capability' and 'hint'`,
+            ]);
+        }
+        const capability = item.capability;
+        if (typeof capability !== "string" || !capability) {
+            throw new TriggerLoaderError([
+                `${location} disambiguates_against[${i}] missing 'capability' (must be one of: ${allowedCapabilityIds.join(", ")})`,
+            ]);
+        }
+        if (!allowedCapabilityIds.includes(capability)) {
+            throw new TriggerLoaderError([
+                `${location} disambiguates_against[${i}].capability=${JSON.stringify(capability)} is not a canonical capability ID (must be one of: ${allowedCapabilityIds.join(", ")})`,
+            ]);
+        }
+        const hint = item.hint;
+        if (typeof hint !== "string" || hint.trim() === "") {
+            throw new TriggerLoaderError([
+                `${location} disambiguates_against[${i}] missing or empty 'hint' (must be a non-empty string)`,
+            ]);
+        }
+        entries.push({ capability, hint });
+    }
+    return entries;
+}
+function buildTriggerEntry(key, raw, capability, contract) {
+    const location = `TRIGGERS entry ${key} in ${capability}/schemas/triggers.yaml`;
+    const id = raw.id;
+    if (typeof id !== "string" || !id) {
+        throw new TriggerLoaderError([`${location} missing 'id'`]);
+    }
+    const description = raw.description;
+    if (typeof description !== "string" || description.trim() === "") {
+        throw new TriggerLoaderError([`${location} missing 'description'`]);
+    }
+    const priorityRaw = raw.priority;
+    if (typeof priorityRaw !== "string" ||
+        !contract.triggerPriorityRules.allowedValues.includes(priorityRaw)) {
+        throw new TriggerLoaderError([
+            `${location} has invalid priority=${JSON.stringify(priorityRaw)} (must be one of: ${contract.triggerPriorityRules.allowedValues.join(", ")})`,
+        ]);
+    }
+    const priority = priorityRaw;
+    const disambiguatesAgainst = resolveDisambiguation(raw.disambiguates_against, location, contract.triggerEnrichment.allowedCapabilityIds);
+    const fallback = raw.fallback === true;
+    return {
+        id,
+        description,
+        priority,
+        disambiguatesAgainst,
+        fallback,
+    };
+}
+function buildCapabilityTriggers(capability, contract, sourceRoot) {
+    const filePath = triggersYamlPath(capability, sourceRoot);
+    const data = readTriggersYaml(filePath);
+    const triggersGroup = data.TRIGGERS;
+    if (!isMapping(triggersGroup)) {
+        throw new TriggerLoaderError([
+            `${capability}/schemas/triggers.yaml is missing the TRIGGERS group`,
+        ]);
+    }
+    const triggers = [];
+    for (const key of Object.keys(triggersGroup)) {
+        if (!isNumericKey(key)) {
+            throw new TriggerLoaderError([
+                `${capability}/schemas/triggers.yaml has non-numeric key ${JSON.stringify(key)} in TRIGGERS`,
+            ]);
+        }
+        const entry = triggersGroup[key];
+        if (!isMapping(entry)) {
+            throw new TriggerLoaderError([
+                `TRIGGERS entry ${key} in ${capability}/schemas/triggers.yaml is not a mapping`,
+            ]);
+        }
+        triggers.push(buildTriggerEntry(key, entry, capability, contract));
+    }
+    return { capability, triggers };
+}
+/**
+ * Load all twelve capability triggers.yaml files into a typed active
+ * TriggerModel.
+ * The capability set is the ROUTE_ALIASES.primary_aliases list owned by the
+ * capability schema contract. Absent `disambiguates_against` defaults to an
+ * empty list; its capability references are validated against the canonical
+ * capability IDs and each must resolve to a capability present in the returned
+ * model.
+ */
+export function loadTriggerModel(contract, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const capabilities = contract.routeAliases.primaryAliases.map((alias) => alias.capability);
+    const errors = [];
+    const model = new Map();
+    for (const capability of capabilities) {
+        try {
+            model.set(capability, buildCapabilityTriggers(capability, contract, sourceRoot));
+        }
+        catch (exc) {
+            if (exc instanceof TriggerLoaderError) {
+                errors.push(...exc.errors);
+            }
+            else {
+                throw exc;
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new TriggerLoaderError(errors);
+    }
+    // Resolve disambiguates_against references: each capability referenced must
+    // resolve to a capability present in the model with at least one trigger.
+    const resolutionErrors = [];
+    for (const { capability, triggers } of model.values()) {
+        for (const entry of triggers) {
+            for (const ref of entry.disambiguatesAgainst) {
+                const referenced = model.get(ref.capability);
+                if (!referenced) {
+                    resolutionErrors.push(`TRIGGERS entry ${entry.id} in ${capability}/schemas/triggers.yaml disambiguates_against.capability=${JSON.stringify(ref.capability)} does not resolve to a loaded capability`);
+                }
+                else if (referenced.triggers.length === 0) {
+                    resolutionErrors.push(`TRIGGERS entry ${entry.id} in ${capability}/schemas/triggers.yaml disambiguates_against.capability=${JSON.stringify(ref.capability)} resolves to a capability with no trigger entries`);
+                }
+            }
+        }
+    }
+    if (resolutionErrors.length > 0) {
+        throw new TriggerLoaderError(resolutionErrors);
+    }
+    return { capabilities: model };
+}