agentera 3.0.0-dev.72 → 3.0.0-dev.74

package/dist/registries/explicitSegmentGrammarContract.js

@@ -0,0 +1,619 @@
+import path from "node:path";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+export const EXPLICIT_SEGMENT_GRAMMAR_SCHEMA_VERSION = "agentera.personalGlossarySegmentGrammar.v1";
+export const EXPLICIT_SEGMENT_FORM_IDS = [
+    "quoted_means",
+    "definition_list_colon",
+    "acronym_stands_for",
+    "acronym_parenthetical",
+    "by_i_mean",
+    "use_for",
+    "use_to_mean",
+    "refers_to",
+    "clarification_prefer_to_mean",
+    "correction_means",
+];
+export const EXPLICIT_SEGMENT_STATES = [
+    "outside",
+    "cue",
+    "inline_meaning",
+    "continuation",
+    "structural_config",
+    "terminated",
+    "rejected",
+];
+export const EXPLICIT_SEGMENT_INPUTS = [
+    "approved_cue",
+    "non_empty_inline_meaning",
+    "continuation_line",
+    "blank_line",
+    "next_cue",
+    "structural_fragment",
+    "comment",
+    "list_boundary",
+    "indentation",
+    "nested_marker",
+    "block_scalar",
+    "prose",
+    "unsupported",
+    "eof",
+];
+export const EXPLICIT_SEGMENT_REASONS = {
+    unsupportedTransition: "unsupported_transition",
+    structuralFragment: "structural_fragment",
+    emptyMeaning: "empty_meaning",
+    meaningBoundExceeded: "meaning_bound_exceeded",
+    ambiguousReference: "ambiguous_reference",
+    conflictingMeaning: "conflicting_meaning",
+    invalidExitBoundary: "invalid_exit_boundary",
+};
+function transition(from, input, to, action, reason) {
+    return { from, input, to, action, ...(reason === undefined ? {} : { reason }) };
+}
+const REQUIRED_TRANSITIONS = [
+    transition("outside", "approved_cue", "cue", "enter_cue_segment"),
+    transition("outside", "structural_fragment", "structural_config", "enter_structural_config", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("outside", "list_boundary", "structural_config", "enter_structural_config", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("outside", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+    transition("cue", "non_empty_inline_meaning", "inline_meaning", "capture_inline_meaning"),
+    transition("cue", "blank_line", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.emptyMeaning),
+    transition("cue", "next_cue", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.emptyMeaning),
+    transition("cue", "structural_fragment", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.emptyMeaning),
+    transition("cue", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+    transition("inline_meaning", "continuation_line", "continuation", "append_original_newline"),
+    transition("inline_meaning", "blank_line", "terminated", "finish_before_boundary"),
+    transition("inline_meaning", "next_cue", "terminated", "finish_before_boundary"),
+    transition("inline_meaning", "structural_fragment", "terminated", "finish_before_boundary"),
+    transition("inline_meaning", "comment", "terminated", "finish_before_boundary"),
+    transition("inline_meaning", "list_boundary", "terminated", "finish_before_boundary"),
+    transition("inline_meaning", "prose", "continuation", "append_original_newline"),
+    transition("inline_meaning", "eof", "terminated", "finish_at_eof"),
+    transition("inline_meaning", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+    transition("continuation", "continuation_line", "continuation", "append_original_newline"),
+    transition("continuation", "prose", "continuation", "append_original_newline"),
+    transition("continuation", "blank_line", "terminated", "finish_before_boundary"),
+    transition("continuation", "next_cue", "terminated", "finish_before_boundary"),
+    transition("continuation", "structural_fragment", "terminated", "finish_before_boundary"),
+    transition("continuation", "comment", "terminated", "finish_before_boundary"),
+    transition("continuation", "list_boundary", "terminated", "finish_before_boundary"),
+    transition("continuation", "eof", "terminated", "finish_at_eof"),
+    transition("continuation", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+    transition("structural_config", "approved_cue", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "structural_fragment", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "comment", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "blank_line", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "indentation", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "nested_marker", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "block_scalar", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "list_boundary", "structural_config", "reject_structural_fragment", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "prose", "outside", "reject_fragment_then_exit", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("structural_config", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+    transition("structural_config", "eof", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.structuralFragment),
+    transition("terminated", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+    transition("rejected", "unsupported", "rejected", "reject", EXPLICIT_SEGMENT_REASONS.unsupportedTransition),
+];
+export class ExplicitSegmentGrammarContractError extends Error {
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? [...value]
+        : [];
+}
+function sameStrings(value, expected) {
+    return JSON.stringify(strings(value)) === JSON.stringify(expected);
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isState(value) {
+    return EXPLICIT_SEGMENT_STATES.includes(value);
+}
+function isInput(value) {
+    return EXPLICIT_SEGMENT_INPUTS.includes(value);
+}
+function isReason(value) {
+    return Object.values(EXPLICIT_SEGMENT_REASONS).includes(value);
+}
+function transitionKey(from, input) {
+    return `${from}:${input}`;
+}
+function formMappings(value) {
+    return Array.isArray(value)
+        ? value.map(mapping).filter((item) => item !== null)
+        : [];
+}
+function validateTransition(value, label, fallback, errors) {
+    const transition = mapping(value);
+    if (!transition) {
+        errors.push(`${label} must be a mapping`);
+        return;
+    }
+    if (!isState(transition.from))
+        errors.push(`${label}.from is not a declared state`);
+    if (fallback) {
+        if (transition.input !== "unsupported") {
+            errors.push(`${label}.input must be unsupported`);
+        }
+    }
+    else if (!isInput(transition.input)) {
+        errors.push(`${label}.input is not a declared input class`);
+    }
+    if (!isState(transition.to))
+        errors.push(`${label}.to is not a declared state`);
+    if (!nonEmpty(transition.action))
+        errors.push(`${label}.action is required`);
+    if (transition.reason !== undefined && !isReason(transition.reason)) {
+        errors.push(`${label}.reason is not a stable grammar reason`);
+    }
+}
+function validateExactObjectFields(value, fields, label, errors) {
+    const result = mapping(value);
+    if (!result) {
+        errors.push(`${label} must be a mapping`);
+        return null;
+    }
+    for (const field of fields) {
+        if (result[field] === undefined)
+            errors.push(`${label}.${field} is required`);
+    }
+    return result;
+}
+/** Validate the finite grammar projection nested under explicit_discovery.grammar. */
+export function validateExplicitSegmentGrammar(value) {
+    const errors = [];
+    const grammar = mapping(value);
+    const segment = mapping(grammar?.segment_grammar);
+    if (!segment) {
+        errors.push("explicit segment grammar must declare segment_grammar");
+        return errors;
+    }
+    if (segment.schema_version !== EXPLICIT_SEGMENT_GRAMMAR_SCHEMA_VERSION) {
+        errors.push("explicit segment grammar schema_version is unsupported");
+    }
+    if (segment.segment_class !== "explicit_cue_segment") {
+        errors.push("explicit segment grammar must declare explicit_cue_segment");
+    }
+    if (!sameStrings(segment.states, EXPLICIT_SEGMENT_STATES)) {
+        errors.push("explicit segment grammar states must remain finite and ordered");
+    }
+    if (!sameStrings(segment.input_classes, EXPLICIT_SEGMENT_INPUTS)) {
+        errors.push("explicit segment grammar input_classes must remain finite and ordered");
+    }
+    if (segment.initial_state !== "outside") {
+        errors.push("explicit segment grammar initial_state must be outside");
+    }
+    if (!sameStrings(segment.terminal_states, ["terminated", "rejected"])) {
+        errors.push("explicit segment grammar terminal_states must be terminated and rejected");
+    }
+    const forms = formMappings(grammar?.forms);
+    if (!sameStrings(forms.map((form) => String(form.id)), EXPLICIT_SEGMENT_FORM_IDS)) {
+        errors.push("explicit segment grammar must cover the approved ten cue forms in order");
+    }
+    for (const [index, form] of forms.entries()) {
+        if (!EXPLICIT_SEGMENT_FORM_IDS.includes(form.id)) {
+            errors.push(`explicit segment grammar form[${index}].id is not approved`);
+        }
+        if (form.segment_class !== "explicit_cue_segment") {
+            errors.push(`explicit segment grammar form[${index}] must map to explicit_cue_segment`);
+        }
+        if (!nonEmpty(form.syntax))
+            errors.push(`explicit segment grammar form[${index}].syntax is required`);
+        if (form.entry !== "outside_approved_cue") {
+            errors.push(`explicit segment grammar form[${index}].entry is invalid`);
+        }
+        if (form.termination !== "shared_bounded_termination") {
+            errors.push(`explicit segment grammar form[${index}].termination is invalid`);
+        }
+        if (form.output !== "shared_cue_segment_output") {
+            errors.push(`explicit segment grammar form[${index}].output is invalid`);
+        }
+    }
+    const entry = validateExactObjectFields(segment.entry, ["from", "input", "to", "accepted_forms", "unsupported_reason"], "explicit segment grammar entry", errors);
+    if (entry) {
+        if (entry.from !== "outside" || entry.input !== "approved_cue" || entry.to !== "cue") {
+            errors.push("explicit segment grammar entry must transition outside approved_cue to cue");
+        }
+        if (!sameStrings(entry.accepted_forms, EXPLICIT_SEGMENT_FORM_IDS)) {
+            errors.push("explicit segment grammar entry must accept every approved cue form");
+        }
+        if (entry.unsupported_reason !== EXPLICIT_SEGMENT_REASONS.unsupportedTransition) {
+            errors.push("explicit segment grammar entry must fail closed with unsupported_transition");
+        }
+    }
+    const termination = validateExactObjectFields(segment.termination, [
+        "start_state",
+        "continuation_state",
+        "terminal_state",
+        "required",
+        "boundary_inputs",
+        "maximum_meaning_utf8_bytes",
+        "limit",
+        "over_limit_reason",
+    ], "explicit segment grammar termination", errors);
+    if (termination) {
+        if (termination.start_state !== "inline_meaning" ||
+            termination.continuation_state !== "continuation" ||
+            termination.terminal_state !== "terminated" ||
+            termination.required !== "non_empty_inline_meaning") {
+            errors.push("explicit segment grammar termination states are invalid");
+        }
+        if (!sameStrings(termination.boundary_inputs, [
+            "blank_line",
+            "next_cue",
+            "structural_fragment",
+            "comment",
+            "list_boundary",
+        ])) {
+            errors.push("explicit segment grammar termination boundary_inputs are invalid");
+        }
+        if (termination.maximum_meaning_utf8_bytes !== 4096 || termination.limit !== "inclusive") {
+            errors.push("explicit segment grammar termination must accept exactly 4096 UTF-8 bytes");
+        }
+        if (termination.over_limit_reason !== EXPLICIT_SEGMENT_REASONS.meaningBoundExceeded) {
+            errors.push("explicit segment grammar termination over_limit_reason is invalid");
+        }
+    }
+    const output = validateExactObjectFields(segment.output, ["fields", "span_encoding", "source_semantics"], "explicit segment grammar output", errors);
+    if (output) {
+        if (!sameStrings(output.fields, ["term", "meaning", "term_span", "meaning_span"])) {
+            errors.push("explicit segment grammar output fields are invalid");
+        }
+        if (output.span_encoding !== "utf8_byte_offsets") {
+            errors.push("explicit segment grammar output must use UTF-8 byte offsets");
+        }
+        if (output.source_semantics !== "exact_source_bytes_without_unicode_normalization") {
+            errors.push("explicit segment grammar output must preserve exact source bytes");
+        }
+    }
+    const continuation = validateExactObjectFields(segment.continuation, [
+        "starts_after",
+        "preserves",
+        "stops_on",
+        "maximum_utf8_bytes",
+        "limit",
+        "over_limit",
+        "over_limit_reason",
+    ], "explicit segment grammar continuation", errors);
+    if (continuation) {
+        if (continuation.starts_after !== "non_empty_inline_meaning") {
+            errors.push("explicit segment grammar continuation must start after non-empty inline meaning");
+        }
+        if (continuation.preserves !== "exact_source_newlines_and_utf8_bytes") {
+            errors.push("explicit segment grammar continuation must preserve original newlines and bytes");
+        }
+        if (!sameStrings(continuation.stops_on, [
+            "blank_line",
+            "next_cue",
+            "structural_fragment",
+            "comment",
+            "list_boundary",
+        ])) {
+            errors.push("explicit segment grammar continuation stops_on is invalid");
+        }
+        if (continuation.maximum_utf8_bytes !== 4096 || continuation.limit !== "inclusive") {
+            errors.push("explicit segment grammar continuation must accept exactly 4096 UTF-8 bytes");
+        }
+        if (continuation.over_limit !== "reject" ||
+            continuation.over_limit_reason !== EXPLICIT_SEGMENT_REASONS.meaningBoundExceeded) {
+            errors.push("explicit segment grammar continuation must reject one byte over the bound");
+        }
+    }
+    const structural = validateExactObjectFields(segment.structural_configuration, ["state", "entry_inputs", "persist_inputs", "reject_inputs", "exit"], "explicit segment grammar structural_configuration", errors);
+    if (structural) {
+        if (structural.state !== "structural_config") {
+            errors.push("explicit segment grammar structural_configuration state is invalid");
+        }
+        if (!sameStrings(structural.entry_inputs, ["structural_fragment", "list_boundary"])) {
+            errors.push("explicit segment grammar structural_configuration entry_inputs are invalid");
+        }
+        if (!sameStrings(structural.persist_inputs, [
+            "comment",
+            "blank_line",
+            "indentation",
+            "nested_marker",
+            "block_scalar",
+            "structural_fragment",
+            "list_boundary",
+        ])) {
+            errors.push("explicit segment grammar structural_configuration persist_inputs are invalid");
+        }
+        if (!sameStrings(structural.reject_inputs, [
+            "comment",
+            "blank_line",
+            "indentation",
+            "nested_marker",
+            "block_scalar",
+            "structural_fragment",
+            "list_boundary",
+            "approved_cue",
+        ])) {
+            errors.push("explicit segment grammar structural_configuration reject_inputs are invalid");
+        }
+        const exit = mapping(structural.exit);
+        if (!exit) {
+            errors.push("explicit segment grammar structural_configuration.exit must be a mapping");
+        }
+        else if (exit.input !== "prose" ||
+            !nonEmpty(exit.condition) ||
+            !nonEmpty(exit.action) ||
+            exit.next_state !== "outside" ||
+            exit.definition_allowed !== "next_physical_line_only") {
+            errors.push("explicit segment grammar structural_configuration must have one finite prose exit");
+        }
+    }
+    const references = validateExactObjectFields(segment.reference_binding, [
+        "following",
+        "this",
+        "exact_term",
+        "matching",
+        "duplicate_target_reason",
+        "missing_target_reason",
+        "duplicate_target_outcome",
+        "missing_target_outcome",
+        "unrelated_cue_outcome",
+    ], "explicit segment grammar reference_binding", errors);
+    if (references) {
+        if (references.following !== "nearest_next_cue" ||
+            references.this !== "nearest_previous_cue" ||
+            references.exact_term !== "nearest_matching_cue" ||
+            references.matching !== "unicode_caseless_exact_no_normalization" ||
+            references.duplicate_target_reason !== EXPLICIT_SEGMENT_REASONS.ambiguousReference ||
+            references.missing_target_reason !== EXPLICIT_SEGMENT_REASONS.ambiguousReference ||
+            references.duplicate_target_outcome !== "exclude_bound_cue_only" ||
+            references.missing_target_outcome !== "exclude_bound_cue_only" ||
+            references.unrelated_cue_outcome !== "retain") {
+            errors.push("explicit segment grammar reference_binding direction and ambiguity rules are invalid");
+        }
+    }
+    const deduplication = validateExactObjectFields(segment.deduplication, [
+        "identity",
+        "same_identity_same_meaning",
+        "same_identity_different_meaning",
+        "unrelated_cue_outcome",
+    ], "explicit segment grammar deduplication", errors);
+    if (deduplication) {
+        if (deduplication.identity !== "personal_mining_authority.term_identity.stable_term_identity" ||
+            deduplication.same_identity_same_meaning !== "retain_one_earliest_source_span" ||
+            deduplication.same_identity_different_meaning !== "reject_all_conflicting_meaning" ||
+            deduplication.unrelated_cue_outcome !== "retain") {
+            errors.push("explicit segment grammar deduplication must preserve identity and conflict semantics");
+        }
+    }
+    const order = validateExactObjectFields(segment.canonical_order, ["fields", "comparator", "direction"], "explicit segment grammar canonical_order", errors);
+    if (order) {
+        if (!sameStrings(order.fields, ["term", "meaning", "term_span.start", "meaning_span.start"]) ||
+            order.comparator !== "unicode_scalar_code_point_ascending" ||
+            order.direction !== "ascending") {
+            errors.push("explicit segment grammar canonical_order must remain lexical and ascending");
+        }
+    }
+    const transitions = Array.isArray(segment.transitions) ? segment.transitions : [];
+    const canonicalTransitionKeys = new Set(REQUIRED_TRANSITIONS.map((transition) => transitionKey(transition.from, transition.input)));
+    const transitionKeys = new Set();
+    for (const [index, value] of transitions.entries()) {
+        validateTransition(value, `explicit segment grammar transitions[${index}]`, false, errors);
+        const transition = mapping(value);
+        if (transition && isState(transition.from) && isInput(transition.input)) {
+            const key = transitionKey(transition.from, transition.input);
+            if (transitionKeys.has(key))
+                errors.push(`explicit segment grammar transition ${key} is duplicated`);
+            transitionKeys.add(key);
+            if (!canonicalTransitionKeys.has(key))
+                errors.push(`explicit segment grammar transition ${key} is not declared by its finite rule`);
+        }
+    }
+    for (const expected of REQUIRED_TRANSITIONS) {
+        const key = transitionKey(expected.from, expected.input);
+        const actual = transitions
+            .map(mapping)
+            .find((transition) => transition?.from === expected.from && transition.input === expected.input);
+        if (!actual) {
+            errors.push(`explicit segment grammar transition ${key} is required`);
+            continue;
+        }
+        if (actual.to !== expected.to ||
+            actual.action !== expected.action ||
+            (expected.reason === undefined
+                ? actual.reason !== undefined
+                : actual.reason !== expected.reason)) {
+            errors.push(`explicit segment grammar transition ${key} does not match its finite rule`);
+        }
+    }
+    const fallbacks = mapping(segment.fallback_transitions);
+    if (!fallbacks) {
+        errors.push("explicit segment grammar fallback_transitions must declare every state");
+    }
+    else {
+        for (const state of EXPLICIT_SEGMENT_STATES) {
+            const fallback = mapping(fallbacks[state]);
+            if (!fallback) {
+                errors.push(`explicit segment grammar fallback_transitions.${state} is required`);
+                continue;
+            }
+            validateTransition(fallback, `explicit segment grammar fallback_transitions.${state}`, true, errors);
+            if (fallback.from !== state || fallback.to !== "rejected") {
+                errors.push(`explicit segment grammar fallback_transitions.${state} must reject from its state`);
+            }
+            if (fallback.reason !== EXPLICIT_SEGMENT_REASONS.unsupportedTransition) {
+                errors.push(`explicit segment grammar fallback_transitions.${state} must use unsupported_transition`);
+            }
+        }
+    }
+    const reasonMap = mapping(segment.reasons);
+    if (!reasonMap) {
+        errors.push("explicit segment grammar reasons must be declared");
+    }
+    else {
+        for (const [key, reason] of Object.entries(EXPLICIT_SEGMENT_REASONS)) {
+            const yamlKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+            if (reasonMap[yamlKey] !== reason) {
+                errors.push(`explicit segment grammar reasons.${yamlKey} must be ${reason}`);
+            }
+        }
+    }
+    return errors;
+}
+export function explicitSegmentGrammarAuthorityPath(root = resolveSourceRoot()) {
+    return path.join(root, "references", "artifacts", "glossary-entry-contract.yaml");
+}
+function requiredString(value, label) {
+    if (!nonEmpty(value))
+        throw new ExplicitSegmentGrammarContractError(`${label} must be non-empty`);
+    return value;
+}
+/** Load the validated finite contract that a future explicit parser consumes. */
+export function loadExplicitSegmentGrammarContract(pathname = explicitSegmentGrammarAuthorityPath()) {
+    let authority;
+    try {
+        authority = loadYamlMappingFile(pathname);
+    }
+    catch (error) {
+        throw new ExplicitSegmentGrammarContractError(`glossary entry authority ${pathname} is unreadable or malformed: ${error.message}`);
+    }
+    const mining = mapping(authority.personal_mining_authority);
+    const explicitDiscovery = mapping(mining?.explicit_discovery);
+    const grammar = mapping(explicitDiscovery?.grammar);
+    const errors = validateExplicitSegmentGrammar(grammar);
+    if (errors.length > 0)
+        throw new ExplicitSegmentGrammarContractError(errors.join("; "));
+    const segment = mapping(grammar?.segment_grammar);
+    const forms = new Map();
+    for (const value of formMappings(grammar?.forms)) {
+        const id = value.id;
+        forms.set(id, {
+            id,
+            segmentClass: requiredString(value.segment_class, `form ${id}.segment_class`),
+            syntax: requiredString(value.syntax, `form ${id}.syntax`),
+            entry: "outside_approved_cue",
+            termination: "shared_bounded_termination",
+            output: "shared_cue_segment_output",
+        });
+    }
+    const transitions = new Map();
+    for (const value of Array.isArray(segment.transitions) ? segment.transitions : []) {
+        const transition = mapping(value);
+        const from = transition.from;
+        const input = transition.input;
+        transitions.set(transitionKey(from, input), {
+            from,
+            input,
+            to: transition.to,
+            action: requiredString(transition.action, `${from}:${input}.action`),
+            ...(transition.reason === undefined
+                ? {}
+                : { reason: transition.reason }),
+        });
+    }
+    const fallbackMap = new Map();
+    const fallbackMappings = mapping(segment.fallback_transitions);
+    for (const state of EXPLICIT_SEGMENT_STATES) {
+        const value = mapping(fallbackMappings[state]);
+        fallbackMap.set(state, {
+            from: state,
+            input: "unsupported",
+            to: "rejected",
+            action: requiredString(value.action, `fallback ${state}.action`),
+            reason: value.reason,
+        });
+    }
+    const entry = mapping(segment.entry);
+    const termination = mapping(segment.termination);
+    const continuation = mapping(segment.continuation);
+    const structural = mapping(segment.structural_configuration);
+    const structuralExit = mapping(structural.exit);
+    const references = mapping(segment.reference_binding);
+    return {
+        schemaVersion: segment.schema_version,
+        segmentClass: segment.segment_class,
+        states: [...strings(segment.states)],
+        inputClasses: [...strings(segment.input_classes)],
+        initialState: "outside",
+        terminalStates: ["terminated", "rejected"],
+        forms,
+        entry: {
+            from: "outside",
+            input: "approved_cue",
+            to: "cue",
+            acceptedForms: strings(entry.accepted_forms),
+            unsupportedReason: entry.unsupported_reason,
+        },
+        termination: {
+            startState: "inline_meaning",
+            continuationState: "continuation",
+            terminalState: "terminated",
+            required: "non_empty_inline_meaning",
+            boundaryInputs: strings(termination.boundary_inputs),
+            maximumMeaningUtf8Bytes: 4096,
+            limit: "inclusive",
+            overLimitReason: termination.over_limit_reason,
+        },
+        output: {
+            fields: ["term", "meaning", "term_span", "meaning_span"],
+            spanEncoding: "utf8_byte_offsets",
+            sourceSemantics: "exact_source_bytes_without_unicode_normalization",
+        },
+        continuation: {
+            startsAfter: "non_empty_inline_meaning",
+            preserves: "exact_source_newlines_and_utf8_bytes",
+            stopsOn: strings(continuation.stops_on),
+            maximumUtf8Bytes: 4096,
+            limit: "inclusive",
+            overLimit: "reject",
+            overLimitReason: continuation.over_limit_reason,
+        },
+        structuralConfiguration: {
+            state: "structural_config",
+            entryInputs: strings(structural.entry_inputs),
+            persistInputs: strings(structural.persist_inputs),
+            rejectInputs: strings(structural.reject_inputs),
+            exit: {
+                input: "prose",
+                condition: requiredString(structuralExit.condition, "structural exit.condition"),
+                action: requiredString(structuralExit.action, "structural exit.action"),
+                nextState: "outside",
+                definitionAllowed: "next_physical_line_only",
+            },
+        },
+        referenceBinding: {
+            following: "nearest_next_cue",
+            this: "nearest_previous_cue",
+            exactTerm: "nearest_matching_cue",
+            matching: "unicode_caseless_exact_no_normalization",
+            duplicateTargetReason: references.duplicate_target_reason,
+            missingTargetReason: references.missing_target_reason,
+            duplicateTargetOutcome: "exclude_bound_cue_only",
+            missingTargetOutcome: "exclude_bound_cue_only",
+            unrelatedCueOutcome: "retain",
+        },
+        deduplication: {
+            identity: "personal_mining_authority.term_identity.stable_term_identity",
+            sameIdentitySameMeaning: "retain_one_earliest_source_span",
+            sameIdentityDifferentMeaning: "reject_all_conflicting_meaning",
+            unrelatedCueOutcome: "retain",
+        },
+        canonicalOrder: {
+            fields: ["term", "meaning", "term_span.start", "meaning_span.start"],
+            comparator: "unicode_scalar_code_point_ascending",
+            direction: "ascending",
+        },
+        transitions,
+        fallbacks: fallbackMap,
+    };
+}
+/** Resolve one transition, falling back to the declared stable rejection. */
+export function explicitSegmentTransition(contract, state, input) {
+    return (contract.transitions.get(transitionKey(state, input)) ??
+        contract.fallbacks.get(state) ?? {
+        from: state,
+        input,
+        to: "rejected",
+        action: "reject",
+        reason: EXPLICIT_SEGMENT_REASONS.unsupportedTransition,
+    });
+}

package/dist/registries/glossaryCandidateContractPaths.js

@@ -0,0 +1,6 @@
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+/** Resolve the authority shared by the candidate-layer contract readers. */
+export function glossaryCandidateContractsAuthorityPath(root = resolveSourceRoot()) {
+    return path.join(root, "references", "artifacts", "glossary-entry-contract.yaml");
+}