agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/dist/registries/capabilityContract.js

@@ -106,16 +106,11 @@ export function buildCapabilitySchemaContract(data, contractPath) {
 }
 function buildTriggerEnrichmentRules(data) {
     const enrichment = data.TRIGGER_ENRICHMENT;
-    const defaults = enrichment.contract_defaults;
     const fields = enrichment.fields;
     const primaryAliases = data.ROUTE_ALIASES.primary_aliases;
     const allowedCapabilityIds = primaryAliases.map((entry) => entry.capability);
     return {
         spec: enrichment.spec,
-        contractDefaults: {
-            confidenceThreshold: defaults.confidence_threshold,
-            borderlineBand: defaults.borderline_band,
-        },
         fields: Object.fromEntries(Object.entries(fields).map(([name, raw]) => [name, buildEnrichmentFieldRule(raw)])),
         allowedCapabilityIds,
     };
@@ -355,9 +350,7 @@ function checkSelfGroups(data, sourceLabel, requiredGroups, errors) {
     }
 }
 /**
- * Required integer range field inside TRIGGER_ENRICHMENT (defaults and
- * per-field min/max). Used by both the contract_defaults and field-level
- * constraint checks below.
+ * Required integer range field inside TRIGGER_ENRICHMENT compatibility rules.
  */
 function checkEnrichmentIntegerField(value, label, sourceLabel, errors) {
     if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 100) {
@@ -373,22 +366,15 @@ function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
     if (typeof enrichment.spec !== "string" || !enrichment.spec) {
         errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.spec in ${sourceLabel} must be a non-empty string`);
     }
-    const defaults = enrichment.contract_defaults;
-    if (!isMapping(defaults)) {
-        errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.contract_defaults in ${sourceLabel} must be a mapping`);
-    }
-    else {
-        checkEnrichmentIntegerField(defaults.confidence_threshold, "TRIGGER_ENRICHMENT.contract_defaults.confidence_threshold", sourceLabel, errors);
-        checkEnrichmentIntegerField(defaults.borderline_band, "TRIGGER_ENRICHMENT.contract_defaults.borderline_band", sourceLabel, errors);
-    }
     const fields = enrichment.fields;
     if (!isMapping(fields)) {
         errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields in ${sourceLabel} must be a mapping`);
         return;
     }
-    // The four canonical enrichment field names. Each must exist as a mapping
-    // with the documented shape; the loader reads them faithfully.
+    // Legacy fields remain shape-validated for compatibility, but are not
+    // carried into the active semantic trigger model.
     const expected = {
+        patterns: "list_of_strings",
         confidence_threshold: "integer",
         borderline_band: "integer",
         patterns_regex: "list_of_strings",
@@ -414,9 +400,8 @@ function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
             if (typeof max !== "number" || max !== 100) {
                 errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.max in ${sourceLabel} must be 100`);
             }
-            checkEnrichmentIntegerField(fields[fieldName].default, `TRIGGER_ENRICHMENT.fields.${fieldName}.default`, sourceLabel, errors);
         }
-        if (expectedType === "list_of_strings" && fields[fieldName].each_must_be_valid_regex !== true) {
+        if (fieldName === "patterns_regex" && fields[fieldName].each_must_be_valid_regex !== true) {
             errors.push(`bootstrap [error]: TRIGGER_ENRICHMENT.fields.${fieldName}.each_must_be_valid_regex in ${sourceLabel} must be true`);
         }
     }
@@ -451,4 +436,3 @@ function checkTriggerEnrichmentRules(data, sourceLabel, errors) {
         }
     }
 }
-//# sourceMappingURL=capabilityContract.js.map

package/dist/registries/evaluatorHandoffContract.js

@@ -168,4 +168,3 @@ export function evaluatorHandoffOutputRequirements(contract) {
         schema_authority: "references/cli/capability-instruction-contract.yaml#evaluator_handoff",
     };
 }
-//# sourceMappingURL=evaluatorHandoffContract.js.map

package/dist/registries/evidenceTierContract.js

@@ -0,0 +1,375 @@
+import path from "node:path";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+export class EvidenceTierContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EvidenceTierContractError";
+    }
+}
+/** Supported source families the contract must never silently omit. */
+export const REQUIRED_SOURCE_FAMILIES = [
+    "codex",
+    "cursor",
+    "opencode",
+    "copilot",
+    "claude-code",
+];
+/** Signal semantics whose required meaning must remain available. */
+export const REQUIRED_SIGNAL_KINDS = [
+    "correction",
+    "decision",
+    "question",
+    "instruction",
+    "configuration",
+    "record_identity",
+    "date",
+    "evidence_anchor",
+    "session_id",
+    "origin_id",
+    "content_fingerprint",
+    "author_class",
+];
+/** Compatibility states that must have deterministic, actionable outcomes. */
+export const REQUIRED_COMPATIBILITY_STATES = [
+    "oversized",
+    "legacy",
+    "missing",
+    "corrupt",
+    "incomplete",
+];
+/** Latent startup-analysis reader that must appear in the consumer map. */
+export const STARTUP_ANALYSIS_CONSUMER = "startup_analysis";
+/** Profile-synthesis consumer that must appear in the consumer map. */
+export const PROFILE_SYNTHESIS_CONSUMER = "profile_synthesis";
+/** Signal types the profile_synthesis consumer reads for bounded synthesis. */
+export const PROFILE_SIGNAL_TYPES = [
+    "decision",
+    "question",
+    "correction",
+    "instruction",
+    "configuration",
+];
+export function evidenceTierAuthorityPath(root = resolveSourceRoot()) {
+    return path.join(root, "references", "analysis", "evidence-tier-authority.yaml");
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asRecord(value, label) {
+    const m = mapping(value);
+    if (m === null) {
+        throw new EvidenceTierContractError(`${label} must be a mapping`);
+    }
+    return m;
+}
+function asMappingMap(value, label) {
+    const m = mapping(value);
+    const out = new Map();
+    if (m === null) {
+        throw new EvidenceTierContractError(`${label} must be a mapping`);
+    }
+    for (const [key, entry] of Object.entries(m)) {
+        const em = mapping(entry);
+        if (em === null) {
+            throw new EvidenceTierContractError(`${label}.${key} must be a mapping`);
+        }
+        out.set(key, em);
+    }
+    return out;
+}
+function asString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new EvidenceTierContractError(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+function asStringArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new EvidenceTierContractError(`${label} must be an array`);
+    }
+    return value.map((entry, i) => asString(entry, `${label}[${i}]`));
+}
+function asPositiveInt(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+        throw new EvidenceTierContractError(`${label} must be a positive integer`);
+    }
+    return value;
+}
+function asPositiveNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) {
+        throw new EvidenceTierContractError(`${label} must be a positive number in (0, 1]`);
+    }
+    return value;
+}
+/**
+ * A family declares either `source_product` (single string) or `source_products`
+ * (list, e.g. cursor covers both Cursor and Cursor Agent). Normalize to a list
+ * for uniform coverage checks. At least one product is required.
+ */
+function resolveSourceProduct(entry, label) {
+    const products = entry.source_products ?? entry.source_product;
+    if (products === undefined) {
+        throw new EvidenceTierContractError(`${label} must declare source_product or source_products`);
+    }
+    return Array.isArray(products) ? asStringArray(products, `${label}.source_products`) : [asString(products, `${label}.source_product`)];
+}
+/** Load and structurally validate the evidence-tier authority YAML. */
+export function loadEvidenceTierContract(contractPath = evidenceTierAuthorityPath()) {
+    let raw;
+    try {
+        raw = loadYamlMappingFile(contractPath);
+    }
+    catch (error) {
+        throw new EvidenceTierContractError(`evidence tier authority ${contractPath} is unreadable or malformed: ${error.message}`);
+    }
+    const schemaVersion = asString(raw.schema_version, "schema_version");
+    if (schemaVersion !== "agentera.evidenceTierAuthority.v1") {
+        throw new EvidenceTierContractError(`evidence tier authority ${contractPath} has unsupported schema_version: ${schemaVersion}`);
+    }
+    const tiersMap = asMappingMap(raw.tiers, "tiers");
+    const tierIds = [];
+    for (const [key, entry] of tiersMap) {
+        if (key !== "full_evidence" && key !== "signal") {
+            throw new EvidenceTierContractError(`tiers.${key} is not a recognized tier id`);
+        }
+        tierIds.push(key);
+        const stored = asRecord(entry.stored_fields, `tiers.${key}.stored_fields`);
+        asStringArray(stored.required, `tiers.${key}.stored_fields.required`);
+    }
+    const familiesMap = asMappingMap(asRecord(raw.source_families, "source_families").families, "source_families.families");
+    const families = new Map();
+    for (const [familyId, entry] of familiesMap) {
+        const sourceClass = asString(entry.source_class, `source_families.families.${familyId}.source_class`);
+        if (sourceClass !== "active_runtime" && sourceClass !== "historical_import") {
+            throw new EvidenceTierContractError(`source_families.families.${familyId}.source_class must be active_runtime or historical_import`);
+        }
+        families.set(familyId, {
+            family_id: familyId,
+            source_class: sourceClass,
+            source_product: resolveSourceProduct(entry, `source_families.families.${familyId}`),
+            active_runtime: Boolean(entry.active_runtime),
+            inclusion_rule: typeof entry.inclusion_rule === "string" ? entry.inclusion_rule : undefined,
+        });
+    }
+    const consumerMapRoot = asRecord(raw.consumer_map, "consumer_map");
+    const consumersMap = asMappingMap(consumerMapRoot.consumers, "consumer_map.consumers");
+    const consumers = new Map();
+    for (const [consumerId, entry] of consumersMap) {
+        const tier = asString(entry.tier, `consumer_map.consumers.${consumerId}.tier`);
+        if (tier !== "full_evidence" && tier !== "signal") {
+            throw new EvidenceTierContractError(`consumer_map.consumers.${consumerId}.tier must be full_evidence or signal`);
+        }
+        consumers.set(consumerId, {
+            consumer_id: consumerId,
+            tier,
+            purpose: asString(entry.purpose, `consumer_map.consumers.${consumerId}.purpose`),
+            required_fields: asStringArray(entry.required_fields, `consumer_map.consumers.${consumerId}.required_fields`),
+            source_identity: asString(entry.source_identity, `consumer_map.consumers.${consumerId}.source_identity`),
+            input_contract: asString(entry.input_contract, `consumer_map.consumers.${consumerId}.input_contract`),
+        });
+    }
+    const semanticMap = asMappingMap(consumerMapRoot.semantic_consumers, "consumer_map.semantic_consumers");
+    const semanticConsumers = new Map();
+    for (const [consumerId, entry] of semanticMap) {
+        semanticConsumers.set(consumerId, {
+            consumer_id: consumerId,
+            tier: asString(entry.tier, `consumer_map.semantic_consumers.${consumerId}.tier`),
+            status: asString(entry.status, `consumer_map.semantic_consumers.${consumerId}.status`),
+            input_scope: typeof entry.input_scope === "string" ? entry.input_scope : undefined,
+            excluded_evidence_classes: Array.isArray(entry.excluded_evidence_classes)
+                ? asStringArray(entry.excluded_evidence_classes, `consumer_map.semantic_consumers.${consumerId}.excluded_evidence_classes`)
+                : [],
+            required_semantics: asStringArray(entry.required_semantics, `consumer_map.semantic_consumers.${consumerId}.required_semantics`),
+        });
+    }
+    const semanticsMap = asMappingMap(asRecord(raw.signal_semantics, "signal_semantics").kinds, "signal_semantics.kinds");
+    const signalSemantics = new Map();
+    for (const [kind, entry] of semanticsMap) {
+        signalSemantics.set(kind, {
+            kind,
+            meaning: asString(entry.meaning, `signal_semantics.kinds.${kind}.meaning`),
+            derivable_from: asString(entry.derivable_from, `signal_semantics.kinds.${kind}.derivable_from`),
+            consumer: asString(entry.consumer, `signal_semantics.kinds.${kind}.consumer`),
+            current_consumer: typeof entry.current_consumer === "string" ? entry.current_consumer : undefined,
+        });
+    }
+    const statesMap = asMappingMap(asRecord(raw.compatibility_states, "compatibility_states").states, "compatibility_states.states");
+    const compatibilityStates = new Map();
+    for (const [key, entry] of statesMap) {
+        if (!REQUIRED_COMPATIBILITY_STATES.includes(key)) {
+            throw new EvidenceTierContractError(`compatibility_states.states.${key} is not a recognized state`);
+        }
+        const stateId = key;
+        const outcome = asString(entry.outcome, `compatibility_states.states.${key}.outcome`);
+        if (outcome !== "recover" && outcome !== "degrade") {
+            throw new EvidenceTierContractError(`compatibility_states.states.${key}.outcome must be recover or degrade`);
+        }
+        compatibilityStates.set(stateId, {
+            state_id: stateId,
+            trigger: asString(entry.trigger, `compatibility_states.states.${key}.trigger`),
+            status: asString(entry.status, `compatibility_states.states.${key}.status`),
+            reason: asString(entry.reason, `compatibility_states.states.${key}.reason`),
+            outcome,
+            recovery: asString(entry.recovery, `compatibility_states.states.${key}.recovery`),
+        });
+    }
+    const reconciliation = asRecord(raw.decision_55_reconciliation, "decision_55_reconciliation");
+    const boundsRoot = asRecord(raw.bounds, "bounds");
+    const bounds = {
+        readerByteCap: asPositiveInt(boundsRoot.reader_byte_cap, "bounds.reader_byte_cap"),
+        shardByteCap: asPositiveInt(boundsRoot.shard_byte_cap, "bounds.shard_byte_cap"),
+        signalByteCap: asPositiveInt(boundsRoot.signal_byte_cap, "bounds.signal_byte_cap"),
+    };
+    const suffRoot = asRecord(raw.profile_sufficiency, "profile_sufficiency");
+    const profileSufficiency = {
+        profileSignalTypes: asStringArray(suffRoot.profile_signal_types, "profile_sufficiency.profile_signal_types"),
+        minimumFamilyRetention: asPositiveNumber(suffRoot.minimum_family_retention, "profile_sufficiency.minimum_family_retention"),
+    };
+    return {
+        schemaVersion,
+        status: asString(raw.status, "status"),
+        tierIds,
+        families,
+        consumers,
+        semanticConsumers,
+        signalSemantics,
+        compatibilityStates,
+        bounds,
+        profileSufficiency,
+        decisionNumber: typeof reconciliation.decision_number === "number"
+            ? reconciliation.decision_number
+            : 0,
+    };
+}
+/** All declared source family ids (no family is silently omitted). */
+export function supportedSourceFamilies(contractPath = evidenceTierAuthorityPath()) {
+    return [...loadEvidenceTierContract(contractPath).families.keys()];
+}
+/** All declared consumers with their bounded input contract and required fields. */
+export function consumerMap(contractPath = evidenceTierAuthorityPath()) {
+    return [...loadEvidenceTierContract(contractPath).consumers.values()];
+}
+/** All declared signal semantics available to current consumers. */
+export function signalSemantics(contractPath = evidenceTierAuthorityPath()) {
+    return [...loadEvidenceTierContract(contractPath).signalSemantics.values()];
+}
+/** All declared compatibility states with deterministic, actionable outcomes. */
+export function compatibilityStates(contractPath = evidenceTierAuthorityPath()) {
+    return [...loadEvidenceTierContract(contractPath).compatibilityStates.values()];
+}
+/**
+ * Projected byte caps for full-evidence shards and the signal tier. These are
+ * the bounds the publication writer and direct retriever enforce; they are read
+ * from the authority rather than duplicated in callers.
+ */
+export function evidenceTierBounds(contractPath = evidenceTierAuthorityPath()) {
+    return loadEvidenceTierContract(contractPath).bounds;
+}
+/**
+ * Profile-synthesis sufficiency threshold (resolves planning Unknown 2). The
+ * profile_signal_types and minimum_family_retention are the authority a bounded
+ * profile reader projects when comparing the retained signal distribution
+ * against the intended distribution. Callers must not re-declare these.
+ */
+export function profileSufficiency(contractPath = evidenceTierAuthorityPath()) {
+    return loadEvidenceTierContract(contractPath).profileSufficiency;
+}
+/**
+ * Validate the contract against its invariants. Returns a list of human-readable
+ * errors; an empty list means the contract satisfies every Task 1 acceptance
+ * invariant. Used by tests for both passing (production contract) and failing
+ * (mutated fixture) checks.
+ */
+export function validateEvidenceTierContract(contractPath = evidenceTierAuthorityPath()) {
+    const errors = [];
+    let model;
+    try {
+        model = loadEvidenceTierContract(contractPath);
+    }
+    catch (error) {
+        return [error.message];
+    }
+    // AC1: every consumer has one bounded input contract supplying required fields
+    // with source identity.
+    for (const consumer of model.consumers.values()) {
+        if (consumer.required_fields.length === 0) {
+            errors.push(`consumer ${consumer.consumer_id} declares no required fields`);
+        }
+        if (!consumer.source_identity) {
+            errors.push(`consumer ${consumer.consumer_id} has no source identity`);
+        }
+        if (!consumer.input_contract) {
+            errors.push(`consumer ${consumer.consumer_id} has no input contract`);
+        }
+    }
+    if (!model.consumers.has(STARTUP_ANALYSIS_CONSUMER)) {
+        errors.push(`consumer map omits latent ${STARTUP_ANALYSIS_CONSUMER} reader`);
+    }
+    // AC2: no supported source family is silently omitted.
+    for (const family of REQUIRED_SOURCE_FAMILIES) {
+        if (!model.families.has(family)) {
+            errors.push(`source family ${family} is omitted`);
+        }
+    }
+    // AC3: signal semantics required meaning remains available to current and
+    // declared semantic consumers.
+    for (const kind of REQUIRED_SIGNAL_KINDS) {
+        const semantic = model.signalSemantics.get(kind);
+        if (!semantic) {
+            errors.push(`signal semantic ${kind} is omitted`);
+            continue;
+        }
+        if (!semantic.consumer) {
+            errors.push(`signal semantic ${kind} has no declared consumer`);
+        }
+    }
+    for (const [name, consumer] of model.semanticConsumers) {
+        for (const kind of consumer.required_semantics) {
+            if (!model.signalSemantics.has(kind)) {
+                errors.push(`semantic consumer ${name} requires unknown semantic ${kind}`);
+            }
+        }
+    }
+    const glossary = model.semanticConsumers.get("glossary");
+    if (glossary?.status !== "active" ||
+        glossary.input_scope !== "bounded_personal_history" ||
+        !glossary.excluded_evidence_classes.includes("project_file")) {
+        errors.push("active glossary evidence must use bounded personal history and exclude project files");
+    }
+    // AC4: every compatibility state is deterministic and actionable.
+    for (const state of REQUIRED_COMPATIBILITY_STATES) {
+        const def = model.compatibilityStates.get(state);
+        if (!def) {
+            errors.push(`compatibility state ${state} is omitted`);
+            continue;
+        }
+        if (def.outcome !== "recover" && def.outcome !== "degrade") {
+            errors.push(`compatibility state ${state} has non-deterministic outcome`);
+        }
+        if (!def.recovery) {
+            errors.push(`compatibility state ${state} has no actionable recovery`);
+        }
+    }
+    // Profile-synthesis sufficiency (Unknown 2): the consumer must appear, the
+    // sufficiency model must declare profile signal types, and each declared
+    // type must be a recognized signal semantic so the comparison is meaningful.
+    if (!model.consumers.has(PROFILE_SYNTHESIS_CONSUMER)) {
+        errors.push(`consumer map omits ${PROFILE_SYNTHESIS_CONSUMER} consumer`);
+    }
+    if (model.profileSufficiency.profileSignalTypes.length === 0) {
+        errors.push("profile_sufficiency declares no profile_signal_types");
+    }
+    for (const kind of model.profileSufficiency.profileSignalTypes) {
+        if (!model.signalSemantics.has(kind)) {
+            errors.push(`profile_sufficiency references unknown signal semantic ${kind}`);
+        }
+    }
+    // Decision 55 reconciliation: the decision is referenced, not rewritten.
+    if (model.decisionNumber !== 55) {
+        errors.push(`decision_55_reconciliation.decision_number is ${model.decisionNumber}, expected 55`);
+    }
+    return errors;
+}