@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/selection/runtime-selection.d.ts

@@ -0,0 +1,217 @@
+import type { CredentialRef, ModelFamilyListing } from "@yanlinglabs/winter-agent-sdk";
+import { RuntimeSdkError } from "../errors.js";
+/**
+ * The two runtimes, spelled exactly as the Winter runtime's own messaging layer spells them
+ * (`packages/runtime/src/messaging/adapter.ts`, which Task 0 moves to
+ * `@yanlinglabs/winter-agent-sdk/messaging`).
+ *
+ * ONE DECLARATION, and this is it while Task 0 is in flight: when the messaging subpath lands, this
+ * line becomes a re-export of the SDK's own `RuntimeKind` (see `src/seams/messaging-contract.ts`,
+ * which carries the same note for the messaging shapes). The two unions are character-identical, so
+ * the swap is type-identical and no lane's code moves.
+ */
+export type RuntimeKind = "winter-agent" | "claude-agent";
+/**
+ * WS-15 §1's persisted-choice contract, populated by the D13 selector at session creation.
+ *
+ * `sdkVersion` vs `engineVersion` are WS-02 §3's two separate identities: the wrapper's and the
+ * runtime engine's. `reason` is a human-readable sentence naming the rule that fired — it is what a
+ * host renders when a user asks "why is this session on that runtime", and what a support log needs
+ * when a persisted selection looks surprising a month later. `decidedAt` is ISO-8601.
+ */
+export interface RuntimeSelection {
+    runtimeKind: RuntimeKind;
+    providerId: string;
+    /**
+     * The provider-qualified catalog **row key** (`anthropic/claude-opus-5`) — this session's model
+     * IDENTITY, never the raw model id.
+     *
+     * READ IT AS AN IDENTITY, NOT AS A WIRE VALUE. The id a runtime actually sends is derived from the
+     * row, never from this field: handing `modelRef` straight to a runtime's `model` option sends the
+     * provider prefix with it, and that fails at the endpoint rather than at compile time. WS-17 row 17
+     * is why the field is qualified at all — `claude-opus-5` is six catalog rows behind six providers,
+     * and two sessions on two of them must not persist byte-identical records.
+     */
+    modelRef: string;
+    family: string;
+    authFamily: "api-key" | "cloud-credential-chain" | "claude-oauth" | "console-oauth" | "local-none" | "custom";
+    sdkVersion: string;
+    engineVersion?: string;
+    reason: string;
+    decidedAt: string;
+}
+/** The auth families a `RuntimeSelection` can record, as a name (the union is pinned inline above). */
+export type SelectionAuthFamily = RuntimeSelection["authFamily"];
+/**
+ * What the host knows about one provider BEYOND "a credential ref exists" — the two facts the D13
+ * branch is actually taken on.
+ *
+ * WHY THIS EXISTS. `CredentialPresence.byProvider` carries a `CredentialRef["kind"]`, which says
+ * WHERE a credential is stored (`keychain` | `env` | `file` | `inline` | `aws-default-chain` |
+ * `none`). D13 branches on something else entirely: WS-13 §9's own words are "routing decisions use
+ * the persisted runtime profile/AUTH SOURCE — never a raw model-ID substring", and R-7b-1 spells the
+ * official branch's served set as "API key, cloud credential chain, or an approved Claude OAuth". A
+ * storage location cannot express any of those three, and it certainly cannot express the difference
+ * between an Anthropic API key and a Claude OAuth credential, which is the difference between D13's
+ * row 2 and its row 1. So the host — which has the provider descriptor — declares them.
+ *
+ * `protocols` is WS-13 §5's wire-dialect list (`ProviderProtocol` in the catalog: `anthropic-messages`,
+ * `openai-chat-completions`, `bedrock-converse`, …), copied verbatim from the provider descriptor.
+ * The selector reads exactly one bit out of it: does this backend speak the Anthropic dialect —
+ * which is WS-13 §9's "Anthropic-protocol backend" test, and the thing that separates a Claude model
+ * served by its vendor from the same Claude model resold through an OpenAI-shaped gateway.
+ *
+ * KEPT A BARE `string[]`, deliberately: the dialect vocabulary belongs to the catalog package, and
+ * this package must not grow a dependency on it to spell one comparison.
+ */
+export interface ProviderAuthView {
+    /** The auth family this provider's CONFIGURED credential belongs to (WS-14 §12's own table). */
+    authFamily: SelectionAuthFamily;
+    /** The wire dialects the provider speaks, verbatim from its catalog descriptor. */
+    protocols?: readonly string[];
+}
+/**
+ * Which providers have a credential REF configured — never any credential material.
+ *
+ * WS-13c §4's filter step ("filter by configured credential ref") and WS-14 Execution amendments'
+ * "a pinned alias resolves to the `anthropic` provider ONLY when a credential ref for it is
+ * configured, and never by ambient environment scan" are both decided from this map. The value is the
+ * ref's KIND (the SDK's own `CredentialRef["kind"]`), because the auth family follows from it and
+ * nothing else here needs more.
+ *
+ * LANE D AMENDMENT — `byProvider` REMAINS THE FILTER, `authByProvider` REFINES IT. Presence of a
+ * provider's key in `byProvider` is what admits its rows (unchanged, and it is the only admission
+ * test: an absent key means "no configured credential ref", never "probe the environment"). What the
+ * kind cannot do is name the auth FAMILY, so `authByProvider` carries it where the host knows it. A
+ * provider with no entry there falls back to `authFamilyFromRefKind` in `./select-runtime.ts`, whose
+ * one rule is that an OAuth family is NEVER inferred — `claude-oauth` and `console-oauth` are
+ * reachable only by declaration, so the D14 ship gate can never be tripped by a guess.
+ */
+export interface CredentialPresence {
+    readonly byProvider: Readonly<Record<string, CredentialRef["kind"]>>;
+    /** Per-provider auth family + wire dialects, where the host knows them. See `ProviderAuthView`. */
+    readonly authByProvider?: Readonly<Record<string, ProviderAuthView>>;
+}
+/**
+ * The version identities stamped into a selection (WS-02 §3: "the runtime engine and wrapper carry
+ * separate version identities — `sdkVersion` vs `engineVersion`").
+ *
+ * A PURE FUNCTION CANNOT READ THEM. `RuntimeSelection.sdkVersion` is required and its value depends
+ * on which runtime the table picked, so the caller supplies both candidates and the selector stamps
+ * the one it chose. Absent → `UNKNOWN_VERSION`, which is an honest record rather than a plausible
+ * lie; `selectionVersionsFrom(sdk.versions)` in `./select-runtime.ts` builds this from the
+ * constructor's own matrix report, which is where a host already has the answer.
+ */
+export interface SelectionVersions {
+    /** The Winter SDK's own version — stamped when the table picks `winter-agent`. */
+    winterSdkVersion?: string;
+    /** The official SDK's version — stamped when the table picks `claude-agent`. */
+    claudeSdkVersion?: string;
+    /** The runtime ENGINE's version, when the host knows it (WS-02 §3's second identity). */
+    engineVersion?: string;
+}
+/** The D13 decision's inputs. See this file's header for why no raw model id decides the branch. */
+export interface SelectionInput {
+    mode: "code" | "dispatch" | "chat";
+    requested: {
+        slot?: string;
+        model?: string;
+        provider?: string;
+    };
+    families: ModelFamilyListing;
+    credentials: CredentialPresence;
+    hasClaudePeer: boolean;
+    /**
+     * D14's ship gate. `false` IS THE SHIPPED DEFAULT (`D14_CLAUDE_OAUTH_APPROVED_DEFAULT` in
+     * `./select-runtime.ts`): WS-14 §12 — "built but publicly ship-gated pending written Anthropic
+     * approval… until approval exists, the shippable branch uses API-key/cloud/gateway auth only".
+     * Required rather than optional on purpose — a host must say it, and saying nothing is not consent.
+     */
+    claudeOauthApproved: boolean;
+    persisted?: RuntimeSelection;
+    /** Stamped into the produced record. Absent → `UNKNOWN_VERSION`. */
+    versions?: SelectionVersions;
+    /** The ISO-8601 instant to record as `decidedAt`. Absent → now. Present makes a decision reproducible. */
+    now?: string;
+}
+/**
+ * A typed refusal — never a substitution and never a different family (WS-13c §4's own words).
+ *
+ * `slot-unservable`: no candidate survived slot resolution (no configured credential ref, or the
+ * slot names a family this catalog cannot serve). `claude-oauth-not-approved`: the D14 ship gate is
+ * closed and the only route to this selection was Claude OAuth. `runtime-unavailable`: the runtime
+ * the rule selected is not present (e.g. a `claude` slot that must run official, with no official
+ * peer injected). `mode-forbids-runtime`: the mode×runtime matrix has no cell for this pair —
+ * WS-15 §2's "Claude OAuth is Code-only even after D14 approval. Unsupported combinations are
+ * explicit capabilities in the matrix, never silent fallbacks."
+ *
+ * THE FOURTH MEMBER IS LANE D'S ADDITION and it is the one that keeps a rule from becoming a
+ * fallback: without it, Claude OAuth in Dispatch or Chat has exactly two expressible answers, and
+ * both are wrong — route to the official runtime (violating D4's "Dispatch and Chat → Winter-only,
+ * in-daemon") or route to Winter (violating D28's "Claude oAuth never routes to winter").
+ */
+export interface SelectionRefusal {
+    refused: true;
+    reason: "slot-unservable" | "claude-oauth-not-approved" | "runtime-unavailable" | "mode-forbids-runtime";
+    /** One sentence naming what was missing, for the host to surface verbatim. */
+    detail: string;
+}
+/**
+ * Narrows the union without a `"refused" in x` incantation at every call site.
+ *
+ * GENERIC IN THE NON-REFUSAL HALF, because every door in `src/selection/` returns "the answer OR the
+ * same refusal": `RuntimeSelection | SelectionRefusal` from the two selectors, `ChildRuntimePairing |
+ * SelectionRefusal` from the pairing door. One guard for all of them is the point — a second guard
+ * per return type is a second place for the discriminant to be spelled, and the discriminant is the
+ * whole contract.
+ */
+export declare function isSelectionRefusal<T extends object>(value: T | SelectionRefusal): value is SelectionRefusal;
+/**
+ * The refusal, thrown — how `RuntimeSdk.selectRuntime` reports one.
+ *
+ * THE PLAN PINS TWO SIGNATURES THAT DISAGREE, and this class is the reconciliation. The pure module
+ * function above returns `RuntimeSelection | SelectionRefusal` (a refusal is data — the D13 table has
+ * an answer for every input, and a caller doing capability discovery wants it as a value). The
+ * `RuntimeSdk.selectRuntime` METHOD is pinned as returning `RuntimeSelection` alone, so on that door
+ * a refusal has to leave some other way: it is thrown, carrying the refusal verbatim. A host that
+ * wants the value calls the exported function; a host that wants the method catches this.
+ */
+export declare class SelectionRefusedError extends RuntimeSdkError {
+    readonly refusal: SelectionRefusal;
+    constructor(refusal: SelectionRefusal);
+}
+/**
+ * A child's own request, resolved independently of the parent's runtime (R-7b-1).
+ *
+ * ONE OBJECT WHERE THE PLAN WRITES TWO ARGUMENTS. The plan's Task 5 line is
+ * `selectChildRuntime(parent, child: { slot?; model?; provider? }, input)`; the spine pinned the
+ * two-argument form the barrel and the seams already import. They describe the same information, so
+ * this shape carries both halves: the `slot`/`model`/`provider` the spawn requested, and the context
+ * the D13 table needs. `slot` is optional here for the same reason it is optional in
+ * `SelectionInput.requested` — a spawn may name a model or a provider instead, and a child that names
+ * nothing takes its session's active slot set, exactly like a top-level session.
+ *
+ * WHAT IS DELIBERATELY ABSENT: anything from the parent. `selectChildRuntime` reads its `parent`
+ * argument for ONE purpose only — reporting whether the resulting pair is cross-runtime (Lane B's
+ * routing bit) — and never as an input to the decision. That is R-7b-1's whole content, and making
+ * the parent structurally absent from this type is what makes it true rather than merely intended.
+ */
+export interface ChildSelectionInput {
+    /** The child's slot name (WS-13c §4 resolves it to a canonical model id). */
+    slot?: string;
+    /** A canonical model id or a catalog row key, when the spawn names a model instead of a slot. */
+    model?: string;
+    /** A pinned provider id (WS-13c §4's "a pinned `provider`"). */
+    provider?: string;
+    mode: "code" | "dispatch" | "chat";
+    families: ModelFamilyListing;
+    credentials: CredentialPresence;
+    hasClaudePeer: boolean;
+    claudeOauthApproved: boolean;
+    /** Stamped into the child's own record. */
+    versions?: SelectionVersions;
+    /** The ISO-8601 instant to record as the child's `decidedAt`. */
+    now?: string;
+}
+export { selectRuntime } from "./select-runtime.js";
+export { selectChildRuntime } from "./child-runtime.js";

package/dist/selection/select-runtime.d.ts

@@ -0,0 +1,213 @@
+import type { CredentialRef, ModelFamilyListing } from "@yanlinglabs/winter-agent-sdk";
+import type { VersionMatrixReport } from "../version-matrix.js";
+import type { CredentialPresence, ProviderAuthView, RuntimeSelection, SelectionAuthFamily, SelectionInput, SelectionRefusal, SelectionVersions } from "./runtime-selection.js";
+/** The family id the D13 table names. The catalog's own id (WS-13c §1, `CLAUDE_FAMILY_ID`). */
+export declare const CLAUDE_FAMILY_ID = "claude";
+/** WS-13 §5's Anthropic wire dialect, as the catalog's provider descriptors spell it. */
+export declare const ANTHROPIC_PROTOCOL = "anthropic-messages";
+/**
+ * The provider ids treated as Anthropic-protocol backends when the host declares no `protocols`.
+ *
+ * A FALLBACK, NOT A POLICY. When `CredentialPresence.authByProvider[id].protocols` is present it is
+ * authoritative and this list is not consulted. It exists because the alternative — treating an
+ * undeclared backend as Anthropic-protocol — would route a Claude model resold through an
+ * OpenAI-shaped gateway to the official runtime, which is precisely WS-13 §9's third row inverted.
+ * The conservative direction is the safe one: an undeclared, unlisted backend goes to Winter, which
+ * serves every family, rather than to a runtime that speaks one wire protocol.
+ *
+ * ONE ENTRY, and that is not an oversight: Bedrock and Vertex reach the official branch through their
+ * AUTH FAMILY (`cloud-credential-chain`, WS-14 §12's own table rows), not through this list — their
+ * catalog dialects are `bedrock-converse` and `google-generate-content`, and claiming otherwise here
+ * would be a false statement about the catalog.
+ */
+export declare const ANTHROPIC_PROTOCOL_PROVIDER_FALLBACK: readonly string[];
+/**
+ * D25's reserved slot names, which resolve into the `claude` family from any active set (WS-13c §3's
+ * acceptance order, mirrored from the catalog's `CLAUDE_RESERVED_SLOT_NAMES`).
+ */
+export declare const CLAUDE_RESERVED_SLOT_NAMES: readonly string[];
+/**
+ * D14's ship gate, as the shipped default.
+ *
+ * WS-14 §12: Claude OAuth is "built but publicly ship-gated pending written Anthropic approval…
+ * Until approval exists, the shippable branch uses API-key/cloud/gateway auth only." A host that has
+ * approval passes `claudeOauthApproved: true` deliberately; everything that does not say so gets this.
+ */
+export declare const D14_CLAUDE_OAUTH_APPROVED_DEFAULT = false;
+/** What a `RuntimeSelection` records when the caller supplied no version identity for that runtime. */
+export declare const UNKNOWN_VERSION = "unknown";
+/**
+ * The auth families the official branch serves (R-7b-1 as clarified 2026-09-08), before any per-rule
+ * gate.
+ *
+ * THE ONE HOME FOR THE SET. `officialServesBackend` DERIVES from this list rather than restating it —
+ * the alternative was two places to edit, and review r1's I1 was the first time that cost something
+ * real (a family was added to the rule and the constant said otherwise, with nothing failing).
+ */
+export declare const OFFICIAL_SERVED_AUTH_FAMILIES: readonly SelectionAuthFamily[];
+/**
+ * Every branch this selector can take, with the sentence a host renders.
+ *
+ * IDS RATHER THAN PROSE MATCHING. `RuntimeSelection.reason` is `"<id>: <text>"`, so a test asserts on
+ * `D13-1` while a user reads the sentence, and rewording the sentence never breaks a test (nor does
+ * a test pin prose a product person should be free to improve).
+ */
+export declare const SELECTION_RULES: {
+    readonly "D13-1": "a Claude OAuth credential always routes to the official runtime (WS-13 §9, D13 row 1)";
+    readonly "D13-2": "a Claude-family model on an Anthropic-protocol backend in Code mode routes to the official runtime (WS-13 §9, D13 row 2)";
+    readonly "D13-3-endpoint": "a Claude-family model reached through a backend the official branch does not serve routes to the Winter runtime (WS-13 §9, D13 row 3)";
+    readonly "D13-3-mode": "Dispatch and Chat run in-daemon on the Winter runtime (WS-13 §9 row 3, D4)";
+    readonly D28: "a non-Claude family routes to the Winter runtime (WS-13c §0, D28)";
+    readonly "R-7b-1-no-peer": "this router holds no official runtime, so the Claude-family slot resolves through WS-13c §4's order onto the Winter runtime (R-7b-1)";
+    readonly persisted: "the selection persisted at session creation wins; a change is the certified handoff or a visible fork, never a silent rewrite (WS-00 §2, D13)";
+};
+export type SelectionRuleId = keyof typeof SELECTION_RULES;
+/** `"<id>: <sentence>"` — the exact string a produced record carries in `reason`. */
+export declare function reasonFor(rule: SelectionRuleId): string;
+/**
+ * The rule id a produced record was decided by, recovered from its `reason`.
+ *
+ * `Object.hasOwn`, NOT `in` — `in` walks the prototype chain, so a persisted record whose `reason`
+ * began `toString:` would have come back as a `SelectionRuleId` and `SELECTION_RULES[id]` would have
+ * handed the caller a `Function` where it expects a sentence. A `RuntimeSelection` arrives off a
+ * host's durable store, so it is exactly the kind of input that must not be trusted to be one of ours.
+ */
+export declare function ruleIdOf(selection: RuntimeSelection): SelectionRuleId | undefined;
+type FamilyEntry = ModelFamilyListing["families"][number];
+type ModelEntry = FamilyEntry["models"][number];
+/** One catalog row as the listing publishes it: the provider-qualified `key` is the identity (row 17). */
+export type ModelRow = ModelEntry["rows"][number];
+/** A row that survived WS-13c §4's filter, with the family it belongs to. */
+export interface SelectionCandidate {
+    family: string;
+    canonicalModelId: string;
+    row: ModelRow;
+    auth: ProviderAuthView;
+}
+/**
+ * The auth family implied by a credential ref's STORAGE KIND, for a provider the host did not describe.
+ *
+ * THE ONE RULE THAT MATTERS HERE: an OAuth family is never inferred. `keychain`, `env` and `inline`
+ * are where an API key lives and are also where a subscription credential could live, and guessing
+ * `claude-oauth` from a keychain entry would let an ambient credential trip D14's ship gate — the
+ * exact shape WS-14's Phase 6 amendment forbids ("never by ambient environment scan"). `file` is
+ * genuinely undeterminable (the ref's `format` distinguishes an AWS credentials file from a raw key,
+ * and the kind alone does not carry it), so it reports `custom`, which no rule routes to the official
+ * runtime. Everything unknown therefore lands on Winter, which serves every family.
+ */
+export declare function authFamilyFromRefKind(kind: CredentialRef["kind"]): SelectionAuthFamily;
+/** The host's view of a provider, or the conservative one derived from its ref kind. */
+export declare function providerAuthView(providerId: string, credentials: CredentialPresence): ProviderAuthView | undefined;
+/** WS-13 §9's "Anthropic-protocol backend" test: the declared dialects, else the fallback list. */
+export declare function speaksAnthropicProtocol(providerId: string, auth: ProviderAuthView): boolean;
+/**
+ * Can the OFFICIAL branch serve this backend at all? (R-7b-1's served set, WS-14 §12's table.)
+ *
+ * MEMBERSHIP FIRST, THEN THE PROTOCOL GATE. A family outside `OFFICIAL_SERVED_AUTH_FAMILIES` is not
+ * served, full stop; a family inside it is served either unconditionally or only on a backend that
+ * speaks the Anthropic dialect, and which of the two it is follows from what the family means:
+ *
+ *   `claude-oauth`             — served (and gated separately, because it is D13's own row 1).
+ *   `cloud-credential-chain`   — served. These are WS-14 §12's Bedrock and Vertex rows: their catalog
+ *                                dialects are NOT `anthropic-messages`, and the official runtime
+ *                                speaks them itself, so the auth family is the honest test there.
+ *   `api-key`, `console-oauth` — served ONLY on an Anthropic-dialect backend. Both are token-priced
+ *                                bearer credentials the official runtime accepts through its bearer
+ *                                variable (R-7b-1 as clarified 2026-09-08), so neither is a reason to
+ *                                route away from the official branch — but a Claude model resold over
+ *                                an OpenAI-shaped endpoint still is, which is WS-13 §9's row 3 and the
+ *                                one place the protocol test does the work.
+ *
+ * `console-oauth` was excluded here until review r1's I1. The reasoning had been WS-13c §6's "the
+ * `anthropic` provider first (api-key or Console OAuth credential)" — but that sentence sits inside
+ * §6's WINTER-ALONE paragraph, and the router leg is the next sentence ("With the runtime SDK present:
+ * `claude` slots prefer the official SDK per D13"). The exclusion was never required by the spec, and
+ * it contradicted D28's "anthropic models always prefer claude agent sdk".
+ */
+export declare function officialServesBackend(providerId: string, auth: ProviderAuthView): boolean;
+/**
+ * WS-13c §4, end to end: what the session asked for → the one row it will run on.
+ *
+ * ORDER OF PRECEDENCE: an explicit slot, else an explicit model, else the session's active slot set —
+ * whose slots are tried in the order the listing publishes them, because that order IS §4's
+ * deterministic order (vendorProviders, subscription before token, `settings.preferredProviders`, then
+ * `admission.tier`). This package re-sorts nothing: the listing is produced by the code that owns
+ * those rules, and a second ordering here would be a second answer.
+ */
+/** A candidate list that is non-empty BY TYPE, so a caller never has to guard an impossible empty. */
+export type NonEmptyCandidates = [SelectionCandidate, ...SelectionCandidate[]];
+/**
+ * EVERY candidate row for an explicitly named model or catalog row key, in the listing's own order.
+ *
+ * `resolveCandidate` below takes the first of these and is what a fresh decision uses. A RESUME needs
+ * the whole list instead (`resumeChildSelection`): its question is not "which row would we pick now"
+ * but "is the row this child is RECORDED on still servable", and those differ the moment one provider
+ * serves two rows for one canonical model. Review r1's M1 is exactly that difference — the old code
+ * compared against the first row and called it a provider check, which the provider pin had already
+ * guaranteed.
+ */
+export declare function resolveCandidateRows(input: SelectionInput & {
+    requested: {
+        model: string;
+    };
+}): NonEmptyCandidates | SelectionRefusal;
+export declare function resolveCandidate(input: SelectionInput): SelectionCandidate | SelectionRefusal;
+/**
+ * The D13/D28 table itself, over an already-resolved candidate.
+ *
+ * Exported because both entry points evaluate the SAME table — R-7b-1's "a child runs on the runtime
+ * its OWN slot's family selects under D13/D28" is implemented by calling this with the child's own
+ * candidate, not by a second table that would drift from this one.
+ */
+export declare function decideRuntime(candidate: SelectionCandidate, input: SelectionInput): RuntimeSelection | SelectionRefusal;
+/**
+ * D13/D28, pure — the router's runtime selection.
+ *
+ * Returns the PERSISTED record untouched when there is one, otherwise the row this session resolves
+ * to plus the runtime the table picks, otherwise a typed refusal.
+ */
+export declare function selectRuntime(input: SelectionInput): RuntimeSelection | SelectionRefusal;
+/**
+ * What a fresh decision would say about a session that already has a persisted selection.
+ *
+ * `unchanged` — the table still picks the same runtime, provider and model. `handoff-required` — it
+ * would pick something else: WS-00 §2's D13 says that change "is the certified handoff or a visible
+ * fork, never a silent rewrite", so this is reported to the host (which renders the choice, R-7b-3)
+ * and the persisted record is returned untouched either way. `fresh-refused` — the session's
+ * persisted selection is no longer servable at all (a credential removed, a row withdrawn); the
+ * record still stands, and the refusal says why a fresh decision could not be made.
+ */
+export type SelectionReview = {
+    kind: "unchanged";
+    selection: RuntimeSelection;
+    fresh: RuntimeSelection;
+} | {
+    kind: "handoff-required";
+    persisted: RuntimeSelection;
+    fresh: RuntimeSelection;
+    changed: Array<"runtimeKind" | "providerId" | "modelRef" | "family" | "authFamily">;
+    detail: string;
+} | {
+    kind: "fresh-refused";
+    persisted: RuntimeSelection;
+    refusal: SelectionRefusal;
+};
+/**
+ * Compares a session's persisted selection against what the table would decide today.
+ *
+ * NEVER RETURNS A REWRITTEN RECORD. Every branch carries the persisted object itself; `fresh` is
+ * offered beside it as the *proposal* a handoff (WS-05 §12) or a visible fork would realise. The
+ * host, not this function, decides what to do with a `handoff-required`.
+ */
+export declare function reviewPersistedSelection(input: SelectionInput & {
+    persisted: RuntimeSelection;
+}): SelectionReview;
+/**
+ * The version identities the constructor already measured, in the shape a selection stamps.
+ *
+ * `RuntimeSdk.versions` is a `VersionMatrixReport`; `SelectionInput.versions` is what the record
+ * needs. This is the one-line bridge, so a host does not hand-copy two fields and get the second one
+ * wrong for the runtime it did not test.
+ */
+export declare function selectionVersionsFrom(report: VersionMatrixReport): SelectionVersions;
+export {};