eval-quality 0.1.0

package/dist/core/seal/derived-reference.js

@@ -0,0 +1,383 @@
+import { parseEvidenceTarget, resolveOperation, resolveStep, } from './plan-index.js';
+function resolveEvidenceTarget(pointer, index) {
+    const target = parseEvidenceTarget(pointer);
+    const step = resolveStep(index, target.stepId);
+    const operation = resolveOperation(index, step.operationId);
+    return { target, step, operation };
+}
+// ---- joining ---------------------------------------------------------
+function joinWithAnd(items) {
+    const [first, ...rest] = items;
+    if (first === undefined)
+        return '';
+    if (rest.length === 0)
+        return first;
+    const last = rest[rest.length - 1];
+    if (rest.length === 1)
+        return `${first} and ${last}`;
+    const middle = rest.slice(0, -1);
+    return `${[first, ...middle].join(', ')}, and ${last}`;
+}
+// ---- operation identity -----------------------------------------------
+// Humanizing a kebab-case operationId is injective on distinct ids, and
+// `buildPlanIndex` already rejects a duplicate `operationId` across
+// interfaces, so two resolved operations never share this phrase. `method`
+// and `pathTemplate` are never printed here: AD-16 withholds the operation
+// inventory from the brief.
+function operationReference(operation) {
+    return `the ${operation.operationId.split('-').join(' ')} endpoint`;
+}
+const ESCALATION_LEVELS = [
+    'generic',
+    'kind',
+    'literal',
+];
+const TRANSPORT_ORDER = [
+    'path',
+    'query',
+    'header',
+    'body',
+];
+// Sorted by transport channel in fixed order, then by key name, so this
+// never depends on a binding map's insertion order and the rendered prose
+// stays permutation-invariant.
+function bindingEntries(step) {
+    const entries = [];
+    for (const transportChannel of TRANSPORT_ORDER) {
+        const map = step.inputBinding[transportChannel];
+        if (map === null)
+            continue;
+        for (const key of Object.keys(map).sort()) {
+            const value = map[key];
+            if (value !== undefined)
+                entries.push({ transportChannel, key, value });
+        }
+    }
+    return entries;
+}
+// The transport channel is part of the rendered name as well as the sort
+// key: two bindings can share a parameter name across channels (path.id and
+// query.id), and without the qualifier both would render as "the supplied
+// id", hiding two different bindings behind identical text.
+function entryName(entry) {
+    return `${entry.transportChannel} ${entry.key}`;
+}
+function isTypeViolating(value) {
+    return 'matcher' in value && value.matcher === 'type-violating';
+}
+// Matches `canonicalize.ts`'s key-sorting rule (AD-27) so two contracts
+// differing only in one literal binding's declared key order still render
+// identical prose from that one canonical digest.
+function canonicalizeForDisplay(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeForDisplay);
+    if (value !== null && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = canonicalizeForDisplay(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function formatLiteral(literal) {
+    return JSON.stringify(canonicalizeForDisplay(literal));
+}
+// Base rendering: `type-violating` always names the input malformed.
+// `any` and, at the 'generic' level, `literal` share the same generic wording
+// on purpose; the escalation ladder below tells them apart once two steps
+// would otherwise collide.
+function renderBindingValue(entry, level) {
+    const name = entryName(entry);
+    if (isTypeViolating(entry.value)) {
+        return `a malformed ${name} value`;
+    }
+    if (level === 'generic' || 'matcher' in entry.value) {
+        return `the supplied ${name}`;
+    }
+    if (level === 'kind') {
+        return `the stated ${name}`;
+    }
+    return `the ${name} ${formatLiteral(entry.value.literal)}`;
+}
+// Every declared binding key escalates together: narrowing to only the
+// discriminating key would make one step's shown detail depend on which
+// other steps happen to collide with it elsewhere. Naming a step's own
+// bound keys is not the operation inventory AD-16 withholds; that scope is
+// which other calls exist, not this call's own fields.
+//
+// When a type-violating binding is present, the clause names only that one:
+// it is the semantically salient binding, matching AD-16's worked example.
+function bindingClause(step, level) {
+    const entries = bindingEntries(step);
+    if (entries.length === 0)
+        return null;
+    const malformed = entries.filter((entry) => isTypeViolating(entry.value));
+    const chosen = malformed.length > 0 ? malformed : entries;
+    return `with ${joinWithAnd(chosen.map((entry) => renderBindingValue(entry, level)))}`;
+}
+// Parenthesized rather than comma-joined onto the operation reference: a
+// step reference can itself be joined with other phrases at a higher level
+// (`joinWithAnd`, or a temporal pair's "compared with"), and `bindingClause`
+// already carries its own internal ", and" separators. A second comma layer
+// on top would produce indistinguishable comma soup once two or more
+// phrases are joined.
+function stepReferenceAtLevel(step, operation, level) {
+    const base = operationReference(operation);
+    const clause = bindingClause(step, level);
+    return clause === null ? base : `${base} (${clause})`;
+}
+/**
+ * Escalates through `ESCALATION_LEVELS` in order until every step in
+ * `siblings` renders distinctly.
+ *
+ * `siblings` is direction-scoped: the caller passes only the steps the
+ * current direction's own resolved evidence targets share this operation
+ * with, not every step in the plan (AD-16), so an unrelated collision
+ * elsewhere never blocks an otherwise renderable direction.
+ *
+ * Throws the same precondition-violation `TypeError` as `buildPlanIndex`'s
+ * duplicate `stepId` check if two siblings still collide after full
+ * escalation.
+ */
+export function renderStepReference(step, operation, siblings) {
+    for (const level of ESCALATION_LEVELS) {
+        const phrases = siblings.map((sibling) => stepReferenceAtLevel(sibling, operation, level));
+        if (new Set(phrases).size === phrases.length) {
+            return stepReferenceAtLevel(step, operation, level);
+        }
+    }
+    throw new TypeError(`two or more steps invoking operation "${operation.operationId}" that this direction references render to the same derived reference even fully escalated; the declared structure does not distinguish them`);
+}
+function siblingsByOperation(resolved) {
+    const map = new Map();
+    const seenSteps = new Set();
+    for (const entry of resolved) {
+        if (seenSteps.has(entry.step.stepId))
+            continue;
+        seenSteps.add(entry.step.stepId);
+        const list = map.get(entry.operation.operationId);
+        if (list === undefined)
+            map.set(entry.operation.operationId, [entry.step]);
+        else
+            list.push(entry.step);
+    }
+    return map;
+}
+// ---- the channel framing ----------------------------------------------
+// An empty token is RFC 6901's legal spelling for a zero-length key but
+// names no field worth naming, so it is filtered out rather than spliced in
+// verbatim (which would produce a blank "its  field" or a stray "."). The
+// remaining segments join by "." rather than keeping only the last, so two
+// nested pointers sharing one leaf field name (`.../a/id` and `.../b/id`)
+// never collapse to the same phrase.
+function fieldPath(tail) {
+    const named = tail.filter((token) => token !== '');
+    return named.length === 0 ? null : named.join('.');
+}
+function localTargetPhrase(target) {
+    const field = fieldPath(target.tail);
+    switch (target.channel) {
+        case 'response-status':
+            return 'its transport status';
+        case 'exit-code':
+            return 'its exit code';
+        case 'call-inputs': {
+            if (target.transportChannel === null) {
+                // Unreachable: `parseEvidenceTarget` sets this exactly when the
+                // channel is 'call-inputs'.
+                throw new TypeError('call-inputs evidence target carries no transport channel');
+            }
+            // The transport channel is named here too, not only in the no-tail
+            // fallback below: same path.id / query.id collision `entryName`
+            // above guards against.
+            return field !== null
+                ? `the ${target.transportChannel} ${field} value you sent`
+                : `the ${target.transportChannel} you sent`;
+        }
+        case 'response-body':
+            return field !== null
+                ? `its ${field} field`
+                : 'the response body you obtained';
+        case 'response-headers':
+            return field !== null
+                ? `its ${field} header`
+                : 'the response headers you obtained';
+        case 'stdout':
+            // Distinguished from response-body's "field" wording and from
+            // stderr below, so two channels naming the same field never render
+            // identical text.
+            return field !== null
+                ? `the ${field} field of its standard output`
+                : 'the standard output you obtained';
+        case 'stderr':
+            return field !== null
+                ? `the ${field} field of its standard error`
+                : 'the standard error you obtained';
+    }
+}
+function fullTargetPhrase(resolved, siblingsOf) {
+    const local = localTargetPhrase(resolved.target);
+    const stepRef = renderStepReference(resolved.step, resolved.operation, siblingsOf(resolved.operation.operationId));
+    const preposition = resolved.target.channel === 'call-inputs' ? 'to' : 'from';
+    return `${local} ${preposition} ${stepRef}`;
+}
+// Encoded as a JSON array rather than a `/`-joined string: a `/`-join would
+// conflate a tail token containing a literal `/` (reachable via the RFC 6901
+// `~1` escape, e.g. `['a/b']`) with an equivalent multi-segment tail (`['a',
+// 'b']`). Both would join to the same `".../a/b"` string, producing a false
+// tie in `sentFirstOrder` below.
+function channelSignature(target) {
+    return JSON.stringify([target.channel, target.transportChannel, target.tail]);
+}
+// A total order over one pair, independent of argument order. The final
+// reference-comparison rung fires only on a genuine tie, such as the same
+// field read from two different `after`-linked steps' response bodies; it
+// never degenerates to argument order, since colliding same-operation
+// siblings already throw in `renderStepReference`, and different operations
+// always humanize to different names.
+function sentFirstOrder(a, b, siblingsOf) {
+    const rank = (r) => r.target.channel === 'call-inputs' ? 0 : 1;
+    const rankA = rank(a);
+    const rankB = rank(b);
+    if (rankA !== rankB)
+        return rankA < rankB ? [a, b] : [b, a];
+    const signatureA = channelSignature(a.target);
+    const signatureB = channelSignature(b.target);
+    if (signatureA !== signatureB)
+        return signatureA < signatureB ? [a, b] : [b, a];
+    const referenceA = renderStepReference(a.step, a.operation, siblingsOf(a.operation.operationId));
+    const referenceB = renderStepReference(b.step, b.operation, siblingsOf(b.operation.operationId));
+    return referenceA <= referenceB ? [a, b] : [b, a];
+}
+// Two evidence targets whose steps are declared in an `after` relationship
+// render as one relational phrase, so concatenation never discloses which
+// step came first. A same-step multi-target group stays `single` regardless
+// of `after`; forcing a pair there would guess at which target on each side
+// pairs with which.
+//
+// Pairing is resolved from sorted step ids, never from discovery order over
+// `resolved`, so it stays permutation-invariant: when a predecessor is named
+// by more than one successor (AD-39 admits this), the winner is the successor
+// whose own stepId sorts first, and the losing successor renders as its own
+// `single` group.
+function groupResolvedTargets(resolved) {
+    const byStep = new Map();
+    for (const entry of resolved) {
+        const list = byStep.get(entry.step.stepId);
+        if (list === undefined)
+            byStep.set(entry.step.stepId, [entry]);
+        else
+            list.push(entry);
+    }
+    const stepIds = [...byStep.keys()].sort();
+    const singleTargetStepIds = new Set(stepIds.filter((id) => byStep.get(id)?.length === 1));
+    // Every eligible successor, grouped by the predecessor its `after` names.
+    const successorsOf = new Map();
+    for (const stepId of singleTargetStepIds) {
+        const step = byStep.get(stepId)?.[0]?.step;
+        const after = step?.after ?? null;
+        if (after === null || !singleTargetStepIds.has(after))
+            continue;
+        const successors = successorsOf.get(after);
+        if (successors === undefined)
+            successorsOf.set(after, [stepId]);
+        else
+            successors.push(stepId);
+    }
+    // One winner per predecessor: the successor whose own stepId sorts first.
+    const chosenSuccessorOf = new Map();
+    for (const predecessorId of stepIds) {
+        const successors = successorsOf.get(predecessorId);
+        const winner = successors === undefined ? undefined : [...successors].sort()[0];
+        if (winner !== undefined)
+            chosenSuccessorOf.set(predecessorId, winner);
+    }
+    // `chosenSuccessorOf` maps each predecessor to at most one successor, and
+    // each successor wins at most one predecessor, so it forms a disjoint
+    // union of simple chains (or cycles, on a malformed `after` graph).
+    // Walking only from steps absent from `chosenAsSuccessor` starts at true
+    // chain roots and can never enter a cycle, since every cycle node is by
+    // construction someone's chosen successor.
+    //
+    // Each root is walked and paired every other link: (1st, 2nd), (3rd,
+    // 4th), with a leftover final step left to render alone. This replaced an
+    // earlier single-link collapse that silently dropped a chain's trailing
+    // links. `pairedAway` marks each pair's second half so the final loop
+    // below skips rendering it standalone.
+    const chosenAsSuccessor = new Set(chosenSuccessorOf.values());
+    const pairPartnerOf = new Map();
+    const pairedAway = new Set();
+    for (const stepId of stepIds) {
+        if (chosenAsSuccessor.has(stepId))
+            continue; // reached by walking its root below
+        let predecessorId = stepId;
+        while (predecessorId !== undefined) {
+            const successorId = chosenSuccessorOf.get(predecessorId);
+            if (successorId === undefined)
+                break;
+            pairPartnerOf.set(predecessorId, successorId);
+            pairedAway.add(successorId);
+            predecessorId = chosenSuccessorOf.get(successorId);
+        }
+    }
+    const groups = [];
+    for (const stepId of stepIds) {
+        // Rendered as part of its predecessor's pair elsewhere in this loop.
+        if (pairedAway.has(stepId))
+            continue;
+        const list = byStep.get(stepId);
+        if (list === undefined)
+            continue;
+        const successorId = pairPartnerOf.get(stepId);
+        const first = list[0];
+        const partnerFirst = successorId === undefined ? undefined : byStep.get(successorId)?.[0];
+        if (first !== undefined && partnerFirst !== undefined) {
+            groups.push({ kind: 'temporal-pair', a: first, b: partnerFirst });
+            continue;
+        }
+        groups.push({ kind: 'single', resolved: list });
+    }
+    return groups;
+}
+function renderPhraseGroup(group, siblingsOf) {
+    if (group.kind === 'temporal-pair') {
+        const [first, second] = sentFirstOrder(group.a, group.b, siblingsOf);
+        return `${fullTargetPhrase(first, siblingsOf)}, compared with ${fullTargetPhrase(second, siblingsOf)}`;
+    }
+    const first = group.resolved[0];
+    if (first === undefined) {
+        throw new TypeError('evidence-target group is empty');
+    }
+    if (group.resolved.length === 1) {
+        return fullTargetPhrase(first, siblingsOf);
+    }
+    const stepRef = renderStepReference(first.step, first.operation, siblingsOf(first.operation.operationId));
+    // Sorted, so a same-step group's field order is permutation-invariant like
+    // the top-level join below; in declaration order, permuting
+    // `evidenceTargets` would change which field is named first here.
+    const locals = group.resolved
+        .map((entry) => localTargetPhrase(entry.target))
+        .sort();
+    return `${stepRef}: ${joinWithAnd(locals)}`;
+}
+/**
+ * Renders every evidence target a direction declares as one canonically
+ * ordered, order-independent clause: byte-identical under any permutation of
+ * `evidenceTargets`, `interactionPlan`, or `permittedInterfaces`, since every
+ * phrase comes from Map-keyed lookups and structural properties, never array
+ * position.
+ *
+ * A repeated pointer is deduplicated first: left in place it would push its
+ * step out of the "exactly one target" shape temporal pairing requires,
+ * silently disabling the relational phrase for an otherwise-valid pair.
+ */
+export function renderEvidenceReferences(pointers, index) {
+    const uniquePointers = [...new Set(pointers)];
+    const resolved = uniquePointers.map((pointer) => resolveEvidenceTarget(pointer, index));
+    const siblings = siblingsByOperation(resolved);
+    const siblingsOf = (operationId) => siblings.get(operationId) ?? [];
+    const groups = groupResolvedTargets(resolved);
+    const phrases = groups.map((group) => renderPhraseGroup(group, siblingsOf));
+    return joinWithAnd([...phrases].sort());
+}

package/dist/core/seal/direction-prose.d.ts

@@ -0,0 +1,13 @@
+import type { Direction } from '../schemas/oracle.ts';
+import type { PlanIndex } from './plan-index.ts';
+/**
+ * An empty `evidenceTargets` array reaches here on a contract that compiles
+ * clean: `core/schemas/oracle.ts` puts no `.min(1)` on the array, and AD-3's
+ * alignment predicate (`core/compile/oracle-alignment.ts`) is a universal
+ * over it, so an empty list is contained in any `check` vacuously. Rendering
+ * has nothing to name, so this throws the same precondition-violation
+ * `TypeError` as the other should-never-happen shapes in `core/seal/`, and
+ * `application/seal.ts` converts it to `RuntimeFault('schema-parse-failure')`
+ * at the boundary.
+ */
+export declare function renderDirectionText(direction: Direction, index: PlanIndex): string;

package/dist/core/seal/direction-prose.js

@@ -0,0 +1,120 @@
+import { renderEvidenceReferences } from './derived-reference.js';
+// Uppercases only the first letter found, so an author-written `scope` or
+// `negativeDomain` string that starts lowercase still reads as its own
+// sentence once joined after another.
+function capitalizeFirst(text) {
+    const match = /[a-zA-Z]/.exec(text);
+    if (match === null)
+        return text;
+    const index = match.index;
+    const char = text[index];
+    if (char === undefined)
+        return text;
+    return `${text.slice(0, index)}${char.toUpperCase()}${text.slice(index + 1)}`;
+}
+const ensureSentence = (text) => {
+    const capitalized = capitalizeFirst(text.trim());
+    return /[.!?]$/.test(capitalized) ? capitalized : `${capitalized}.`;
+};
+// `for-all`/`for-any` carry no nested predicate on `Direction`; that lives on
+// `check`, which this module does not read. So the claim names the
+// quantification itself, saying nothing about a condition it cannot see.
+function quantifierClaim(relation, evidence) {
+    return relation === 'for-all'
+        ? `Every element reachable through ${evidence} is asserted to meet the declared condition.`
+        : `At least one element reachable through ${evidence} is asserted to meet the declared condition.`;
+}
+// A shared affirmative skeleton over `not` would tell the sealed evaluator
+// the opposite of the declared claim.
+function connectiveClaim(relation, evidence) {
+    switch (relation) {
+        case 'all':
+            return `${evidence} is asserted to satisfy every declared condition together.`;
+        case 'any':
+            return `${evidence} is asserted to satisfy at least one declared condition.`;
+        case 'not':
+            return `${evidence} is asserted to fail the declared condition, not to satisfy it.`;
+    }
+}
+function presenceClaim(relation, evidence) {
+    return relation === 'existence'
+        ? `${evidence} is asserted to be present.`
+        : `${evidence} is asserted to be absent.`;
+}
+function comparisonClaim(relation, evidence) {
+    switch (relation) {
+        case 'equality':
+            return `${evidence} is asserted to be equal.`;
+        case 'deep-equality':
+            return `${evidence} is asserted to be deeply, structurally equal.`;
+        case 'containment':
+            return `${evidence} is asserted to contain the declared member.`;
+    }
+}
+function structuralClaim(relation, evidence) {
+    return `${evidence} is asserted to satisfy the declared "${relation}" condition.`;
+}
+function renderRelationClaim(relation, evidence) {
+    if (relation === 'for-all' || relation === 'for-any') {
+        return quantifierClaim(relation, evidence);
+    }
+    if (relation === 'all' || relation === 'any' || relation === 'not') {
+        return connectiveClaim(relation, evidence);
+    }
+    if (relation === 'existence' || relation === 'absence') {
+        return presenceClaim(relation, evidence);
+    }
+    if (relation === 'equality' ||
+        relation === 'deep-equality' ||
+        relation === 'containment') {
+        return comparisonClaim(relation, evidence);
+    }
+    return structuralClaim(relation, evidence);
+}
+function renderPolarityClause(polarity) {
+    return polarity === 'expects-hold'
+        ? 'The declared polarity expects this relation to hold.'
+        : 'The declared polarity expects this relation to be a violation.';
+}
+// `negativeDomain` is author-written, evaluator-facing free text.
+// Any trailing terminator the author already wrote is stripped first, since
+// the text becomes the subject of a larger sentence rather than standing
+// alone: an author-terminated string would otherwise read "...did not
+// return. is treated as a defect." (a mid-sentence period followed by a
+// lowercase clause).
+function renderNegativeDomainClause(negativeDomain) {
+    const trimmed = negativeDomain.trim().replace(/[.!?]+$/, '');
+    return `${trimmed} is treated as a defect.`;
+}
+/**
+ * An empty `evidenceTargets` array reaches here on a contract that compiles
+ * clean: `core/schemas/oracle.ts` puts no `.min(1)` on the array, and AD-3's
+ * alignment predicate (`core/compile/oracle-alignment.ts`) is a universal
+ * over it, so an empty list is contained in any `check` vacuously. Rendering
+ * has nothing to name, so this throws the same precondition-violation
+ * `TypeError` as the other should-never-happen shapes in `core/seal/`, and
+ * `application/seal.ts` converts it to `RuntimeFault('schema-parse-failure')`
+ * at the boundary.
+ */
+export function renderDirectionText(direction, index) {
+    if (direction.evidenceTargets.length === 0) {
+        throw new TypeError('direction carries no evidenceTargets; there is no observation for the generated prose to name');
+    }
+    const evidence = renderEvidenceReferences(direction.evidenceTargets, index);
+    const parts = [
+        ensureSentence(renderRelationClaim(direction.relation, evidence)),
+        ensureSentence(renderPolarityClause(direction.polarity)),
+    ];
+    // `null` and `''` both drop the clause: the schema allows `''` as distinct
+    // from `null` with no minimum length, and an absent clause is omitted
+    // rather than rendered as an empty sentence. Checking `!== null` alone
+    // would still render that empty sentence for `''`.
+    if (direction.scope !== null && direction.scope.trim() !== '') {
+        parts.push(ensureSentence(direction.scope));
+    }
+    if (direction.negativeDomain !== null &&
+        direction.negativeDomain.trim() !== '') {
+        parts.push(ensureSentence(renderNegativeDomainClause(direction.negativeDomain)));
+    }
+    return parts.join(' ');
+}

package/dist/core/seal/plan-index.d.ts

@@ -0,0 +1,63 @@
+/** resolves a pointer to its step and operation; nothing about reachability. */
+import type { Operation, PermittedInterface } from '../schemas/interface.ts';
+import type { InteractionStep } from '../schemas/plan.ts';
+import { type EvidenceChannelName, type TransportChannelName } from '../schemas/pointer.ts';
+/**
+ * Exported so `core/evaluate/evidence-resolution.ts` decodes pointer tails
+ * with these same two functions, avoiding a second private copy (the drift
+ * `IDENTIFIER_CHARSET_SOURCE`'s own precedent warns against).
+ */
+export declare const decodeToken: (token: string) => string;
+export declare const decodeTail: (tailSource: string) => readonly string[];
+/**
+ * One evidence target, resolved locally to its step id and channel. The
+ * channel decides whether the rendered phrase says "the response you
+ * obtained" or "the value you sent".
+ */
+export type EvidenceTarget = {
+    stepId: string;
+    channel: EvidenceChannelName;
+    transportChannel: TransportChannelName | null;
+    tail: readonly string[];
+};
+/**
+ * Parses one `InteractionPointer` string (`INTERACTION_POINTER_PATTERN` in
+ * `pointer.ts`) into its step id, channel, transport channel, and tail, using
+ * the schema's own channel partition so this accepts exactly what
+ * `InteractionPointer.safeParse` accepts. A should-never-happen precondition
+ * violation throws `TypeError`, per `digest.ts`'s precedent.
+ */
+export declare function parseEvidenceTarget(pointer: string): EvidenceTarget;
+/**
+ * What a pointer names: step, operation, and every step naming a given
+ * operation, which `derived-reference.ts`'s escalation needs. Says nothing
+ * about reachability or channel typing; the general addressing-grammar
+ * resolver lives in `core/evaluate/evidence-resolution.ts` and reachability
+ * in `core/compile/reachability.ts`.
+ */
+export type PlanIndex = {
+    stepOf: (stepId: string) => InteractionStep | undefined;
+    operationOf: (operationId: string) => Operation | undefined;
+    stepsUsing: (operationId: string) => readonly InteractionStep[];
+};
+export type PlanIndexOptions = {
+    duplicateIds?: 'throw' | 'unresolved';
+};
+/**
+ * Builds the index once over the whole plan and interface set. Neither
+ * schema enforces `stepId`/`operationId` uniqueness. Strict callers keep the
+ * default throw instead of resolving by array order. Standalone structural
+ * checks can select `unresolved`, which removes every ambiguous identifier
+ * from lookup while preserving all unambiguous entries.
+ */
+export declare function buildPlanIndex(interactionPlan: readonly InteractionStep[], permittedInterfaces: readonly PermittedInterface[], options?: PlanIndexOptions): PlanIndex;
+/**
+ * Resolves a step id through the index or throws. Split from `stepOf` so the
+ * index itself stays a plain lookup (`| undefined`, per
+ * `noUncheckedIndexedAccess`) while callers get one function instead of
+ * repeating the `undefined` check. A precondition violation, not a
+ * `RuntimeFault`.
+ */
+export declare function resolveStep(index: PlanIndex, stepId: string): InteractionStep;
+/** Resolves an operation id through the index or throws. See `resolveStep`. */
+export declare function resolveOperation(index: PlanIndex, operationId: string): Operation;