@sema-agent/core/dist/brain/route-conformance.d.ts

Stateless, task-oriented AI agent core

import type { RouteAdjudication, RouteCredential, RoutePairingConfig } from "../internal/llm.js";
/**
 * The PUBLISHED golden conformance corpus for the key↔URL pairing adjudicator
 * ({@link import("./route-adjudicator.js").adjudicateModelRoute}).
 *
 * THE SEAM. The pairing law has exactly ONE implementation — core's `adjudicateModelRoute` — and
 * every consumer that surfaces routing verdicts (a server annotating its model roster, a brain
 * degradation leg replacing a hand-rolled check) MUST delegate to it rather than re-derive
 * "does this key belong to this URL". This corpus is the anti-drift anchor between codebases
 * (the gold-corpus discipline):
 *  - CORE runs it as a regression test (`test/route-adjudication.test.ts`): every vector's `expect`
 *    MUST equal `adjudicateModelRoute(model, credential, config)` on the `ok`/`posture`/`code`
 *    axes, so a change to the law fails the test and updates the corpus in lockstep — the published
 *    contract cannot silently drift from the implementation.
 *  - A CONSUMER imports this corpus from `@sema-agent/core` and runs it as a CONTRACT test against
 *    whatever face it wired the adjudicator into: for each vector, its surface's
 *    allow/annotate/refuse of the described route MUST match `expect.ok` (and forward
 *    `expect.code` verbatim on refusals). That proves the surface actually routes through core's
 *    predicate.
 *
 * ⚠️ CONSUMER CONTRACT: depend on `expect.ok` + `expect.code` (+ `expect.posture` if the surface
 * annotates postures). `fixHint` wording is core-internal and may be reworded without notice.
 *
 * `leg` is ADVISORY: how the refusal is DISPOSED of in the engine's two-leg discipline — a
 * `"named"` (caller-explicit) model surfaces the refusal loudly at the request gate; a `"derived"`
 * (role/tier/system-default) model falls back to the primary model with a
 * `route.fallback_to_primary` notice. The verdict itself is leg-independent (same law both legs).
 */
export interface RouteAdjudicationVector {
    /** Stable case id (appears in test output + the published contract). */
    name: string;
    /** What this vector proves. */
    intent: string;
    model: {
        id: string;
        baseUrl: string;
    };
    credential: RouteCredential;
    config: RoutePairingConfig;
    /** The `ok` / `posture` / `code` axes of the expected {@link RouteAdjudication}. */
    expect: {
        ok: true;
        posture: Extract<RouteAdjudication, {
            ok: true;
        }>["posture"];
    } | {
        ok: false;
        code: Extract<RouteAdjudication, {
            ok: false;
        }>["code"];
    };
    /** Advisory: how the engine's two-leg discipline disposes of this shape (see module note). */
    leg?: "named" | "derived";
}
export declare const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS: readonly RouteAdjudicationVector[];