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

package/dist/registries/glossaryTermIdentity.js

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Locale-independent Unicode caseless-exact equality with no normalization.
+ *
+ * ECMAScript's `iu` matching supplies Unicode simple case folding. Escaping
+ * makes the bounded term literal, while the anchors and terminal lookahead
+ * prevent regex syntax and final-line-terminator behavior from widening exact
+ * matching. NFC/NFD, accent, and compatibility normalization are intentionally
+ * absent, so differently encoded strings remain distinct unless Unicode case
+ * folding itself relates them.
+ */
+export function unicodeCaselessExact(left, right) {
+    const literal = escapeRegExp(left);
+    return new RegExp(`^(?:${literal})$(?![\\s\\S])`, "iu").test(right);
+}
+function compareCodePoints(left, right) {
+    const leftCodePoint = left.codePointAt(0) ?? 0;
+    const rightCodePoint = right.codePointAt(0) ?? 0;
+    return leftCodePoint - rightCodePoint;
+}
+export function compareGlossaryUnicodeStrings(left, right) {
+    const leftScalars = [...left];
+    const rightScalars = [...right];
+    for (let index = 0; index < Math.min(leftScalars.length, rightScalars.length); index += 1) {
+        const comparison = compareCodePoints(leftScalars[index], rightScalars[index]);
+        if (comparison !== 0)
+            return comparison;
+    }
+    return leftScalars.length - rightScalars.length;
+}
+function singleScalar(value) {
+    return [...value].length === 1 ? value : null;
+}
+/**
+ * Build the same simple-case equivalence key used by the stable identity.
+ * Lowercase mapping is the primary Unicode simple-fold projection. A
+ * lowercased uppercase mapping is admitted only when the existing equality
+ * matcher confirms it, which avoids transitive casing mistakes such as
+ * treating ASCII `I` and dotless `ı` as equal.
+ */
+function unicodeSimpleCaseFoldKey(value) {
+    return [...value]
+        .map((character) => {
+        const lower = singleScalar(character.toLowerCase()) ?? character;
+        const upper = singleScalar(character.toUpperCase());
+        const upperLower = upper === null ? null : singleScalar(upper.toLowerCase());
+        if (upperLower !== null && unicodeCaselessExact(character, upperLower)) {
+            return upperLower;
+        }
+        return lower;
+    })
+        .join("");
+}
+function sha256Utf8(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function requireNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${field} must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Return a content-addressed identity for one Unicode caseless-exact term.
+ * The original spelling is not changed or stored in the identity key.
+ */
+export function stableGlossaryTermIdentity(term) {
+    const value = requireNonEmpty(term, "term");
+    const key = unicodeSimpleCaseFoldKey(value);
+    return sha256Utf8(JSON.stringify({
+        schema_version: "agentera.personalGlossaryTermIdentity.v1",
+        key,
+    }));
+}
+export const GLOSSARY_CANDIDATE_SCOPES = ["personal", "project", "ambiguous"];
+export function isGlossaryCandidateScope(value) {
+    return GLOSSARY_CANDIDATE_SCOPES.includes(value);
+}
+export function canonicalGlossaryJson(value) {
+    if (value === undefined)
+        throw new TypeError("canonical JSON cannot contain undefined");
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalGlossaryJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort(compareGlossaryUnicodeStrings)
+        .map((key) => `${JSON.stringify(key)}:${canonicalGlossaryJson(record[key])}`)
+        .join(",")}}`;
+}
+export function glossaryCanonicalSha256(value) {
+    return sha256Utf8(canonicalGlossaryJson(value));
+}
+/**
+ * Return a content-addressed candidate revision without mining or publishing.
+ * Evidence order is not semantic, but every evidence identity remains bound.
+ */
+export function glossaryCandidateRevision(input) {
+    const stableTermIdentity = requireNonEmpty(input.stable_term_identity, "stable_term_identity");
+    const meaning = requireNonEmpty(input.meaning, "meaning");
+    const policyVersion = requireNonEmpty(input.policy_version, "policy_version");
+    const generation = requireNonEmpty(input.generation, "generation");
+    if (!Array.isArray(input.evidence))
+        throw new TypeError("evidence must be a list");
+    if (!isGlossaryCandidateScope(input.scope)) {
+        throw new TypeError("scope must be personal, project, or ambiguous");
+    }
+    const evidence = input.evidence.map((item) => {
+        requireNonEmpty(item.source_id, "evidence.source_id");
+        requireNonEmpty(item.evidence_anchor, "evidence.evidence_anchor");
+        return item;
+    });
+    const canonicalEvidence = new Set();
+    for (const item of evidence) {
+        const canonical = canonicalGlossaryJson(item);
+        if (canonicalEvidence.has(canonical)) {
+            throw new TypeError("evidence must not contain duplicate canonical evidence records");
+        }
+        canonicalEvidence.add(canonical);
+    }
+    evidence.sort((left, right) => {
+        const leftCanonical = canonicalGlossaryJson(left);
+        const rightCanonical = canonicalGlossaryJson(right);
+        return compareGlossaryUnicodeStrings(leftCanonical, rightCanonical);
+    });
+    return sha256Utf8(canonicalGlossaryJson({
+        schema_version: "agentera.personalGlossaryCandidateRevision.v1",
+        stable_term_identity: stableTermIdentity,
+        meaning,
+        scope: input.scope,
+        evidence,
+        policy_version: policyVersion,
+        generation,
+    }));
+}

package/dist/registries/glossaryTermOccurrence.js

@@ -0,0 +1,20 @@
+const IDENTIFIER_CONTINUATION = "[\\p{ID_Continue}$\\u200C\\u200D]";
+const identifierContinuation = new RegExp(`^${IDENTIFIER_CONTINUATION}$`, "u");
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Find one exact-case, non-normalizing glossary term occurrence on a source line.
+ * Boundaries follow ECMAScript identifier continuation: Unicode ID_Continue,
+ * `$`, ZWNJ (U+200C), and ZWJ (U+200D).
+ */
+export function containsGlossaryTerm(line, term) {
+    const characters = [...term];
+    const prefix = identifierContinuation.test(characters[0] ?? "")
+        ? `(?<!${IDENTIFIER_CONTINUATION})`
+        : "";
+    const suffix = identifierContinuation.test(characters.at(-1) ?? "")
+        ? `(?!${IDENTIFIER_CONTINUATION})`
+        : "";
+    return new RegExp(`${prefix}${escapeRegExp(term)}${suffix}`, "u").test(line);
+}

package/dist/registries/hybridRoute.js

@@ -0,0 +1,274 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+import { canonicalRecordJson } from "../state/archiveDiscovery.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadCapabilitySchemaContract } from "./capabilityContract.js";
+import { loadTriggerModel } from "./triggerLoader.js";
+export class HybridRouteRegistryError extends Error {
+    errors;
+    constructor(errors) {
+        super(errors.join("; "));
+        this.errors = errors;
+    }
+}
+function normalized(value) {
+    return value.normalize("NFKC").toLowerCase().trim().replace(/\s+/gu, " ");
+}
+function byteOffset(value, utf16Offset) {
+    return Buffer.byteLength(value.slice(0, utf16Offset), "utf8");
+}
+function sourceSeparatorOffset(value) {
+    let offset = 0;
+    for (const character of value) {
+        if ([":", "-", "—"].includes(character.normalize("NFKC")))
+            return offset;
+        offset += character.length;
+    }
+    return undefined;
+}
+function sourcePath(root, relativePath) {
+    return path.join(root, ...relativePath.split("/"));
+}
+function readMapping(root, relativePath) {
+    try {
+        return loadYamlMapping(fs.readFileSync(sourcePath(root, relativePath), "utf8"));
+    }
+    catch (error) {
+        throw new HybridRouteRegistryError([`${relativePath} is not readable or valid: ${error.message}`]);
+    }
+}
+function contractMapping(value, field) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new HybridRouteRegistryError([`hybrid route contract ${field} must be a mapping`]);
+    }
+    return value;
+}
+function contractString(value, field) {
+    if (typeof value !== "string" || !value) {
+        throw new HybridRouteRegistryError([`hybrid route contract ${field} must be a non-empty string`]);
+    }
+    return value;
+}
+function contractStrings(value, field) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new HybridRouteRegistryError([`hybrid route contract ${field} must be a string list`]);
+    }
+    return value;
+}
+function routeReceiptContract(contract, semanticCapsuleSha) {
+    const protocol = contractMapping(contract.protocol, "protocol");
+    const receipt = contractMapping(protocol.receipt, "protocol.receipt");
+    const cliSeam = contractMapping(receipt.cli_seam, "protocol.receipt.cli_seam");
+    const authority = contractMapping(receipt.validation_authority, "protocol.receipt.validation_authority");
+    const hostOutput = contractMapping(authority.host_output_shape, "protocol.receipt.validation_authority.host_output_shape");
+    const normalization = contractMapping(authority.host_to_cli_normalization, "protocol.receipt.validation_authority.host_to_cli_normalization");
+    const projection = contractMapping(normalization.projection, "protocol.receipt.validation_authority.host_to_cli_normalization.projection");
+    const requestBoundFields = contractMapping(authority.request_bound_fields, "protocol.receipt.validation_authority.request_bound_fields");
+    const discovery = contractMapping(contractMapping(protocol.response, "protocol.response").semantic_required, "protocol.response.semantic_required");
+    const receiptDiscovery = contractMapping(discovery.receipt_contract, "protocol.response.semantic_required.receipt_contract");
+    const example = contractMapping(receiptDiscovery.stdin_example, "protocol.response.semantic_required.receipt_contract.stdin_example");
+    const exampleReceipt = contractMapping(example.receipt, "protocol.response.semantic_required.receipt_contract.stdin_example.receipt");
+    const compound = contractMapping(contractMapping(contract.compound_intent, "compound_intent").semantic, "compound_intent.semantic");
+    const exampleRequest = contractString(example.request, "protocol.response.semantic_required.receipt_contract.stdin_example.request");
+    const version = contractString(receipt.version, "protocol.receipt.version");
+    const schemaVersion = contractString(receiptDiscovery.schema_version, "protocol.response.semantic_required.receipt_contract.schema_version");
+    if (version !== "agentera.route_receipt.v1" || schemaVersion !== "agentera.route_receipt_contract.v1") {
+        throw new HybridRouteRegistryError(["hybrid route receipt discovery declares an unsupported version"]);
+    }
+    return {
+        schemaVersion: "agentera.route_receipt_contract.v1",
+        version: "agentera.route_receipt.v1",
+        command: contractString(cliSeam.command, "protocol.receipt.cli_seam.command"),
+        stdin_command: contractString(receiptDiscovery.stdin_command, "protocol.response.semantic_required.receipt_contract.stdin_command"),
+        input_schema: contractMapping(receiptDiscovery.input_schema, "protocol.response.semantic_required.receipt_contract.input_schema"),
+        nullable_schema: contractMapping(hostOutput.schema, "protocol.receipt.validation_authority.host_output_shape.schema"),
+        outcomes: contractStrings(receipt.outcomes, "protocol.receipt.outcomes"),
+        outcome_rules: contractMapping(projection.outcome_rules, "protocol.receipt.validation_authority.host_to_cli_normalization.projection.outcome_rules"),
+        compound,
+        remainder_span: contractMapping(requestBoundFields.remainder_span, "protocol.receipt.validation_authority.request_bound_fields.remainder_span"),
+        stdin_example: {
+            input: {
+                request: exampleRequest,
+                receipt: {
+                    version,
+                    request_sha256: crypto.createHash("sha256").update(exampleRequest, "utf8").digest("hex"),
+                    semantic_capsule_sha256: semanticCapsuleSha,
+                    ...exampleReceipt,
+                },
+            },
+        },
+    };
+}
+function phrasesFrom(root, contract) {
+    const raw = readMapping(root, "skills/agentera/route-phrases.yaml");
+    const entries = raw.phrases;
+    if (!Array.isArray(entries))
+        throw new HybridRouteRegistryError(["route phrase registry phrases must be a list"]);
+    const capabilities = new Set(contract.routeAliases.primaryAliases.map(({ capability }) => capability));
+    const errors = [];
+    const seen = new Set();
+    const directNames = new Set([
+        ...capabilities,
+        ...contract.routeAliases.primaryAliases.map(({ alias }) => alias),
+    ].map(normalized));
+    const phrases = [];
+    for (const [index, value] of entries.entries()) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            errors.push(`phrases[${index}] must be a mapping`);
+            continue;
+        }
+        const entry = value;
+        const { id, capability, phrase, status } = entry;
+        if (![id, capability, phrase, status].every((field) => typeof field === "string" && field)) {
+            errors.push(`phrases[${index}] requires non-empty id, capability, phrase, and status`);
+            continue;
+        }
+        const normalizedPhrase = normalized(phrase);
+        if (!normalizedPhrase) {
+            errors.push(`phrases[${index}] phrase must contain text`);
+            continue;
+        }
+        if (seen.has(normalizedPhrase))
+            errors.push(`phrase collision: ${id}`);
+        seen.add(normalizedPhrase);
+        if (!capabilities.has(capability))
+            errors.push(`phrases[${index}] capability does not resolve`);
+        if (directNames.has(normalizedPhrase) || directNames.has(normalizedPhrase.split(" ")[0])) {
+            errors.push(`phrases[${index}] conflicts with direct-route grammar`);
+        }
+        phrases.push({ id: id, capability: capability, phrase: phrase, status: status });
+    }
+    if (errors.length > 0)
+        throw new HybridRouteRegistryError(errors);
+    return phrases;
+}
+function phraseMatch(request, phrase) {
+    const phraseTokens = normalized(phrase.phrase).split(" ");
+    const sourceTokens = [...request.matchAll(/\S+/gu)];
+    if (sourceTokens.length < phraseTokens.length)
+        return undefined;
+    for (let index = 0; index < phraseTokens.length - 1; index += 1) {
+        if (normalized(sourceTokens[index][0]) !== phraseTokens[index])
+            return undefined;
+    }
+    const finalToken = sourceTokens[phraseTokens.length - 1];
+    const separator = sourceSeparatorOffset(finalToken[0]);
+    const finalEnd = separator ?? finalToken[0].length;
+    if (normalized(finalToken[0].slice(0, finalEnd)) !== phraseTokens.at(-1))
+        return undefined;
+    return {
+        start: byteOffset(request, sourceTokens[0].index),
+        end: byteOffset(request, finalToken.index + finalEnd),
+    };
+}
+function deterministic(capability, tier, recognizedSpan, request, provenance) {
+    return {
+        schemaVersion: "agentera.route_response.v1",
+        outcome: "deterministic_selection",
+        capability,
+        tier,
+        recognized_span: recognizedSpan,
+        topic_span: { start: recognizedSpan.end, end: Buffer.byteLength(request, "utf8") },
+        provenance,
+    };
+}
+function directRoute(request, contract) {
+    const match = /^(\s*\/agentera)(?:\s+([^\s]+))?/u.exec(request);
+    if (!match)
+        return undefined;
+    const prefixEnd = match[1].length;
+    const name = match[2];
+    if (!name) {
+        if (request.slice(prefixEnd).trim())
+            return undefined;
+        const start = request.search(/\S/u);
+        return deterministic("status", "bare", { start: byteOffset(request, start), end: byteOffset(request, prefixEnd) }, request, { tier: "bare" });
+    }
+    const normalizedName = normalized(name);
+    const alias = contract.routeAliases.primaryAliases.find(({ alias: value, capability }) => normalized(value) === normalizedName || normalized(capability) === normalizedName);
+    if (!alias)
+        return undefined;
+    const nameStart = request.indexOf(name, prefixEnd);
+    return deterministic(alias.capability, "direct", {
+        start: byteOffset(request, request.search(/\S/u)),
+        end: byteOffset(request, nameStart + name.length),
+    }, request, { tier: "direct", route_alias: alias.alias });
+}
+function semanticCapsule(model, contractVersion) {
+    return {
+        contract_version: contractVersion,
+        capabilities: [...model.capabilities.values()].map(({ capability, triggers }) => ({
+            capability,
+            triggers: triggers.map((trigger) => ({
+                id: trigger.id,
+                description: trigger.description,
+                priority: trigger.priority,
+                disambiguates_against: trigger.disambiguatesAgainst.map(({ capability: target, hint }) => ({ capability: target, hint })),
+            })),
+        })),
+    };
+}
+/** Hash the exact bounded semantic classification capsule presented to the host. */
+export function semanticCapsuleSha256(capsule) {
+    return crypto.createHash("sha256").update(canonicalRecordJson(capsule), "utf8").digest("hex");
+}
+/** Returns the complete receipt guide that semantic abstention exposes to hosts. */
+export function describeRouteReceipt(sourceRoot = resolveSourceRoot()) {
+    const response = resolveRouteRequest("make implementation plan", sourceRoot);
+    if (response.outcome !== "semantic_required") {
+        throw new HybridRouteRegistryError(["route receipt example must remain deterministically abstained"]);
+    }
+    return response.receipt_contract;
+}
+/** Resolve only the contract's deterministic request phase; semantic selection remains host-owned. */
+export function resolveRouteRequest(request, sourceRoot = resolveSourceRoot()) {
+    if (typeof request !== "string")
+        throw new TypeError("request must be a string");
+    const contractRaw = readMapping(sourceRoot, "references/cli/hybrid-route-contract.yaml");
+    const contractVersion = contractRaw.schema_version;
+    if (typeof contractVersion !== "string" || !contractVersion) {
+        throw new HybridRouteRegistryError(["hybrid route contract schema_version must be a non-empty string"]);
+    }
+    let capabilityContract;
+    try {
+        capabilityContract = loadCapabilitySchemaContract(sourcePath(sourceRoot, "skills/agentera/capability_schema_contract.yaml"));
+    }
+    catch (error) {
+        throw new HybridRouteRegistryError([`capability route authority is invalid: ${error.message}`]);
+    }
+    const phrases = phrasesFrom(sourceRoot, capabilityContract);
+    const direct = directRoute(request, capabilityContract);
+    if (direct)
+        return direct;
+    for (const phrase of phrases) {
+        if (phrase.status !== "active")
+            continue;
+        const recognizedSpan = phraseMatch(request, phrase);
+        if (recognizedSpan) {
+            return deterministic(phrase.capability, "phrase", recognizedSpan, request, {
+                tier: "phrase",
+                phrase_id: phrase.id,
+            });
+        }
+    }
+    let triggerModel;
+    try {
+        triggerModel = loadTriggerModel(capabilityContract, { sourceRoot });
+    }
+    catch (error) {
+        throw new HybridRouteRegistryError([`semantic intent authority is invalid: ${error.message}`]);
+    }
+    const semantic_capsule = semanticCapsule(triggerModel, contractVersion);
+    const semantic_capsule_sha256 = semanticCapsuleSha256(semantic_capsule);
+    return {
+        schemaVersion: "agentera.route_response.v1",
+        outcome: "semantic_required",
+        request_sha256: crypto.createHash("sha256").update(request, "utf8").digest("hex"),
+        semantic_capsule,
+        semantic_capsule_sha256,
+        receipt_contract: routeReceiptContract(contractRaw, semantic_capsule_sha256),
+        provenance: { tier: "deterministic_abstention", contract: contractVersion },
+    };
+}

package/dist/registries/hybridRouteReceipt.js

@@ -0,0 +1,221 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { preCutoverCommand } from "../cli/preCutoverCommand.js";
+import { loadCapabilitySchemaContract } from "./capabilityContract.js";
+import { resolveRouteRequest } from "./hybridRoute.js";
+export class RouteReceiptValidationError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.field = field;
+    }
+}
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOnlyKeys(value, keys, field) {
+    for (const key of Object.keys(value)) {
+        if (!keys.includes(key))
+            throw new RouteReceiptValidationError(`${field}.${key}`, "contains an unsupported field");
+    }
+}
+function requires(value, key, field) {
+    if (!(key in value))
+        throw new RouteReceiptValidationError(`${field}.${key}`, "is required");
+    return value[key];
+}
+function validUtf8String(value, field) {
+    if (typeof value !== "string" || Buffer.from(value, "utf8").toString("utf8") !== value) {
+        throw new RouteReceiptValidationError(field, "must be a valid UTF-8 string");
+    }
+    return value;
+}
+function codePointLength(value) {
+    return [...value].length;
+}
+function nullableHostShape(receipt, capabilities) {
+    if (!isMapping(receipt))
+        throw new RouteReceiptValidationError("receipt", "must be a nullable host receipt mapping");
+    const keys = ["version", "request_sha256", "semantic_capsule_sha256", "outcome", "capability", "compound", "question", "remainder_span"];
+    hasOnlyKeys(receipt, keys, "receipt");
+    for (const key of keys)
+        requires(receipt, key, "receipt");
+    if (receipt.version !== "agentera.route_receipt.v1")
+        throw new RouteReceiptValidationError("receipt.version", "must be agentera.route_receipt.v1");
+    validUtf8String(receipt.request_sha256, "receipt.request_sha256");
+    validUtf8String(receipt.semantic_capsule_sha256, "receipt.semantic_capsule_sha256");
+    if (!["select", "clarify", "no_match"].includes(receipt.outcome)) {
+        throw new RouteReceiptValidationError("receipt.outcome", "must be select, clarify, or no_match");
+    }
+    if (receipt.capability !== null && (typeof receipt.capability !== "string" || !capabilities.has(receipt.capability))) {
+        throw new RouteReceiptValidationError("receipt.capability", "must be a canonical capability or null");
+    }
+    if (receipt.compound !== null && receipt.compound !== "none" && receipt.compound !== "preserve") {
+        throw new RouteReceiptValidationError("receipt.compound", "must be none, preserve, or null");
+    }
+    if (receipt.question !== null) {
+        const question = validUtf8String(receipt.question, "receipt.question");
+        if (codePointLength(question) > 280)
+            throw new RouteReceiptValidationError("receipt.question", "must be at most 280 characters");
+    }
+    if (receipt.remainder_span !== null) {
+        if (!isMapping(receipt.remainder_span))
+            throw new RouteReceiptValidationError("receipt.remainder_span", "must be a span mapping or null");
+        hasOnlyKeys(receipt.remainder_span, ["start", "end"], "receipt.remainder_span");
+        for (const key of ["start", "end"]) {
+            if (!Number.isInteger(receipt.remainder_span[key]))
+                throw new RouteReceiptValidationError(`receipt.remainder_span.${key}`, "must be an integer");
+        }
+    }
+    return receipt;
+}
+/** Projects the required nullable host shape without changing any non-null value. */
+function normalizeHostReceipt(hostReceipt) {
+    const outcome = hostReceipt.outcome;
+    const requireNonNull = (keys) => {
+        for (const key of keys)
+            if (hostReceipt[key] === null)
+                throw new RouteReceiptValidationError(`receipt.${key}`, "must not be null for this outcome");
+    };
+    const requireNull = (keys) => {
+        for (const key of keys)
+            if (hostReceipt[key] !== null)
+                throw new RouteReceiptValidationError(`receipt.${key}`, "must be null for this outcome");
+    };
+    if (outcome === "select") {
+        requireNonNull(["version", "request_sha256", "semantic_capsule_sha256", "outcome", "capability", "compound"]);
+        requireNull(["question"]);
+        if (hostReceipt.compound === "none")
+            requireNull(["remainder_span"]);
+        else
+            requireNonNull(["remainder_span"]);
+    }
+    else if (outcome === "clarify") {
+        requireNonNull(["version", "request_sha256", "semantic_capsule_sha256", "outcome", "question"]);
+        requireNull(["capability", "compound", "remainder_span"]);
+    }
+    else {
+        requireNonNull(["version", "request_sha256", "semantic_capsule_sha256", "outcome"]);
+        requireNull(["capability", "compound", "question", "remainder_span"]);
+    }
+    return Object.fromEntries(Object.entries(hostReceipt).filter(([, value]) => value !== null));
+}
+function exactUtf8Suffix(request, span) {
+    const bytes = Buffer.from(request, "utf8");
+    if (span.start < 0 || span.end <= span.start || span.end !== bytes.length) {
+        throw new RouteReceiptValidationError("receipt.remainder_span", "must be a non-empty suffix ending at the original request byte length");
+    }
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(span.start, span.end));
+        if (!Buffer.from(text, "utf8").equals(bytes.subarray(span.start, span.end))) {
+            throw new RouteReceiptValidationError("receipt.remainder_span", "must preserve exact UTF-8 request bytes");
+        }
+        return text;
+    }
+    catch (error) {
+        if (error instanceof RouteReceiptValidationError)
+            throw error;
+        throw new RouteReceiptValidationError("receipt.remainder_span", "must start and end on UTF-8 code-point boundaries");
+    }
+}
+function authoritativeReceipt(receipt, request, capabilities) {
+    hasOnlyKeys(receipt, ["version", "request_sha256", "semantic_capsule_sha256", "outcome", "capability", "compound", "question", "remainder_span"], "receipt");
+    if (receipt.version !== "agentera.route_receipt.v1")
+        throw new RouteReceiptValidationError("receipt.version", "is unsupported");
+    if (typeof receipt.request_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.request_sha256)) {
+        throw new RouteReceiptValidationError("receipt.request_sha256", "must be a lowercase SHA-256 digest");
+    }
+    if (typeof receipt.semantic_capsule_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.semantic_capsule_sha256)) {
+        throw new RouteReceiptValidationError("receipt.semantic_capsule_sha256", "must be a lowercase SHA-256 digest");
+    }
+    const digest = crypto.createHash("sha256").update(request, "utf8").digest("hex");
+    if (receipt.request_sha256 !== digest)
+        throw new RouteReceiptValidationError("receipt.request_sha256", "does not match the supplied request");
+    if (receipt.outcome === "select") {
+        if (typeof receipt.capability !== "string" || !capabilities.has(receipt.capability))
+            throw new RouteReceiptValidationError("receipt.capability", "must name a canonical capability");
+        if (receipt.compound !== "none" && receipt.compound !== "preserve")
+            throw new RouteReceiptValidationError("receipt.compound", "must be none or preserve");
+        if ("question" in receipt)
+            throw new RouteReceiptValidationError("receipt.question", "is forbidden for select");
+        if (receipt.compound === "none" && "remainder_span" in receipt)
+            throw new RouteReceiptValidationError("receipt.remainder_span", "is forbidden when compound is none");
+        if (receipt.compound === "preserve" && !("remainder_span" in receipt))
+            throw new RouteReceiptValidationError("receipt.remainder_span", "is required when compound is preserve");
+    }
+    else if (receipt.outcome === "clarify") {
+        const question = validUtf8String(receipt.question, "receipt.question");
+        if (!question || codePointLength(question) > 280)
+            throw new RouteReceiptValidationError("receipt.question", "must be a non-empty question of at most 280 characters");
+        for (const key of ["capability", "compound", "remainder_span"])
+            if (key in receipt)
+                throw new RouteReceiptValidationError(`receipt.${key}`, "is forbidden for clarify");
+    }
+    else if (receipt.outcome === "no_match") {
+        for (const key of ["capability", "compound", "question", "remainder_span"])
+            if (key in receipt)
+                throw new RouteReceiptValidationError(`receipt.${key}`, "is forbidden for no_match");
+    }
+    else {
+        throw new RouteReceiptValidationError("receipt.outcome", "must be select, clarify, or no_match");
+    }
+    if (receipt.remainder_span !== undefined) {
+        if (!isMapping(receipt.remainder_span) || !Number.isInteger(receipt.remainder_span.start) || !Number.isInteger(receipt.remainder_span.end)) {
+            throw new RouteReceiptValidationError("receipt.remainder_span", "must contain integer start and end values");
+        }
+        return exactUtf8Suffix(request, receipt.remainder_span);
+    }
+    return undefined;
+}
+function requireSemanticAuthorization(request, receipt, sourceRoot) {
+    try {
+        const phaseOne = resolveRouteRequest(request, sourceRoot);
+        if (phaseOne.outcome !== "semantic_required" || phaseOne.request_sha256 !== receipt.request_sha256) {
+            throw new RouteReceiptValidationError("receipt.request_sha256", "is not bound to a semantic_required route response");
+        }
+        if (phaseOne.semantic_capsule_sha256 !== receipt.semantic_capsule_sha256) {
+            throw new RouteReceiptValidationError("receipt.semantic_capsule_sha256", "does not match the current semantic capsule");
+        }
+    }
+    catch (error) {
+        if (error instanceof RouteReceiptValidationError)
+            throw error;
+        throw new RouteReceiptValidationError("receipt", "could not be authorized by the deterministic route authority");
+    }
+}
+export function validateRouteReceiptSubmission(input, sourceRoot = resolveSourceRoot()) {
+    if (!isMapping(input))
+        throw new RouteReceiptValidationError("input", "must be a mapping with request and receipt");
+    hasOnlyKeys(input, ["request", "receipt"], "input");
+    const request = validUtf8String(requires(input, "request", "input"), "input.request");
+    const hostReceipt = requires(input, "receipt", "input");
+    const contract = loadCapabilitySchemaContract(path.join(sourceRoot, "skills/agentera/capability_schema_contract.yaml"));
+    const capabilities = new Set(contract.routeAliases.primaryAliases.map(({ capability }) => capability));
+    const receipt = normalizeHostReceipt(nullableHostShape(hostReceipt, capabilities));
+    const deferredText = authoritativeReceipt(receipt, request, capabilities);
+    requireSemanticAuthorization(request, receipt, sourceRoot);
+    if (receipt.outcome === "clarify") {
+        return {
+            schemaVersion: "agentera.route_receipt_result.v1",
+            outcome: "clarification",
+            question: receipt.question,
+            route_provenance: { source: "semantic_receipt", receipt_version: "agentera.route_receipt.v1" },
+        };
+    }
+    const capability = receipt.outcome === "no_match" ? "status" : receipt.capability;
+    const startupCommand = preCutoverCommand(`prime --context ${capability} --format json`);
+    const span = receipt.remainder_span;
+    return {
+        schemaVersion: "agentera.route_receipt_result.v1",
+        outcome: receipt.outcome === "no_match" ? "status_fallback" : "selected",
+        capability,
+        ...(span ? { deferred_intent: { remainder_span: span, text: deferredText } } : {}),
+        route_provenance: {
+            source: "semantic_receipt",
+            receipt_version: "agentera.route_receipt.v1",
+            startup_command: startupCommand,
+            ...(receipt.outcome === "no_match" ? { status_reason: "no_match" } : {}),
+        },
+    };
+}