@yanlinglabs/winter-provider-runtime 0.0.2

package/dist/adapters/privileged-headers.d.ts

@@ -0,0 +1,51 @@
+import { type EndpointPolicy } from "../endpoint-policy.js";
+/**
+ * Header names that carry an ORGANISATION / PROJECT / ACCOUNT identity.
+ *
+ * Lowercase, because a raw record's keys are compared case-insensitively here (a `Headers` object
+ * would do it for us; a plain object will not).
+ */
+export declare const PRIVILEGED_IDENTITY_HEADERS: readonly string[];
+/**
+ * WINTER'S OWN IDENTITY NAMES — dropped from a host's map on a GENERATED endpoint (whole-branch
+ * review M-1).
+ *
+ * The INVERSE of the privileged rule above, and deliberately so. `identity.ts` says the User-Agent
+ * is "deliberately NOT configurable" and names exactly one sanctioned override: "the operator
+ * speaking about their own proxy" — that is a USER endpoint. What the code did was let the same
+ * `ConnectionProfile.headers['user-agent']` replace Winter's identity on the VENDOR'S OWN reviewed
+ * endpoint too, which is the one place the admission rule cares about: a host could present Winter
+ * to a vendor as an editor or a first-party CLI, through a field nothing else guards.
+ *
+ * `client-agent` is here for the same reason and by the same reading (fix-wave R-FW-2): it is the
+ * second half of the same identity, so one rule governs both rather than two that can drift.
+ *
+ * NOT ON THE PRIVILEGED LIST, because the two rules point opposite ways: a privileged name is
+ * dropped on a USER endpoint and kept on a generated one; an identity name is kept on a user
+ * endpoint (the operator's proxy is theirs to describe) and dropped on a generated one.
+ */
+export declare const WINTER_IDENTITY_HEADERS: readonly string[];
+/**
+ * The host's own connection headers, filtered for the endpoint they are about to be sent to.
+ *
+ * TWO RULES, with deliberately different reach:
+ *
+ *   CREDENTIALS — every name on `CREDENTIAL_HEADER_NAMES` is dropped ALWAYS, generated endpoint or
+ *     not. A profile is non-secret connection metadata by contract; a credential in it is a
+ *     misconfiguration, and a reviewed endpoint does not make it less of one.
+ *
+ *   PRIVILEGED — the privileged names are dropped on a USER endpoint only; on a generated one a
+ *     reviewed descriptor endpoint vouches for the identity headers that belong to it. (Three of the
+ *     four privileged names are on the credential list too, so `x-goog-quota-project` is the only
+ *     header where the two rules actually differ.)
+ *
+ *   WINTER'S IDENTITY — `user-agent`/`client-agent` are dropped on a GENERATED endpoint, the exact
+ *     inverse (M-1). The sanctioned override is the operator describing THEIR OWN proxy; letting the
+ *     same field replace Winter's name at the vendor's own endpoint is how a host would present
+ *     Winter as an editor or a first-party CLI, which is the thing the admission rule forbids.
+ *
+ * Everything else is kept on both — a host's proxy token, a tracing header — as its own business.
+ *
+ * Returns a COPY either way, so a `ConnectionProfile` reused across requests is never mutated.
+ */
+export declare function hostHeaders(policy: EndpointPolicy, headers: Record<string, string> | undefined, extraPrivileged?: readonly string[]): Record<string, string>;

package/dist/adapters/refusals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `thinking: { type: "enabled" }` with no `budgetTokens`, on a family whose reasoning is
+ * BUDGET-controlled (Anthropic Messages, Bedrock Converse, Google GenerateContent).
+ *
+ * The OpenAI family does NOT use this sentence: it has no budget field at all, so the same config
+ * resolves against the row's `defaultEffort` and is refused only when there is none — a different
+ * situation with a different way out (`THINKING_ENABLED_NEEDS_EFFORT`, in the family's own
+ * `shared.ts`, which is where the effort vocabulary lives).
+ */
+export declare const THINKING_ENABLED_NEEDS_BUDGET = "thinking `{ type: \"enabled\" }` carries no budgetTokens, which this endpoint requires. Pass `budgetTokens`, or ask for `{ type: \"adaptive\" }` if the model should decide.";

package/dist/address-classifier.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What an IP address IS, rather than merely whether some particular caller should refuse it. The
+ * two consumers want opposite answers from the same facts — Monitor refuses every non-public
+ * address, while the provider endpoint policy ACCEPTS a loopback/private one when a host declares
+ * the endpoint local — so the shared primitive has to be the classification, not the verdict.
+ */
+export type AddressClass = "public" | "loopback" | "private" | "link-local" | "unique-local" | "cgnat" | "multicast" | "unspecified" | "invalid";
+/** True for the classes an endpoint may serve over plain `http` — loopback, RFC 1918, link-local, unique-local (R6-11). */
+export declare function isLocalAddressClass(cls: AddressClass): boolean;
+/** Classifies a literal IP address. `family` is 4 or 6, exactly as `dns.lookup`'s own results report it. */
+export declare function classifyAddress(address: string, family: number): AddressClass;
+/**
+ * Monitor's verdict, unchanged from P3: everything that is not a routable public address is refused,
+ * unparseable IPv4 included (fail closed). Re-exported by `monitor.ts` so that file's own callers
+ * and its existing fixture set are untouched by this module's existence.
+ */
+export declare function isDisallowedAddress(address: string, family: number): boolean;

package/dist/bun-required.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A function that needs the Bun runtime was called somewhere else.
+ *
+ * `name` is the exported function the caller actually invoked (never the internal helper that
+ * reaches for Bun), because that is the name in their code.
+ */
+/**
+ * P7a fix wave round 3 (F2): CROSS-BUNDLE `instanceof`.
+ *
+ * THE PROBLEM, measured on the compiled emit under Node. `build-packages.ts` runs `bun build` ONCE
+ * PER EXPORT ENTRY, so every entry bundle carries its own copy of every internal module: the class
+ * declared in one source file exists as TWO DISTINCT CLASSES at runtime, one in `dist/index.js` and
+ * one in `dist/<subpath>/index.js`. A consumer who imports the function from one subpath and the
+ * class from the other -- the pattern both new READMEs teach -- gets a silent `false` from
+ * `instanceof` and rethrows the very error the guard exists to make catchable. Under Bun the `bun`
+ * condition resolves both entries to the same `src/*.ts`, so the classes ARE identical, which is why
+ * no Bun-side test could see it.
+ *
+ * THE FIX, applied to the CLASS of the problem rather than to one error: every error class exported
+ * from more than one subpath of a package carries a PACKAGE-SCOPED `Symbol.for(...)` brand and a
+ * `static [Symbol.hasInstance]` that tests for it. `Symbol.for` is cross-realm and cross-copy, so
+ * every duplicated bundle of ONE package agrees -- while a DIFFERENT package's class, whose key
+ * names a different package, still does not match. The two packages stay deliberately distinct
+ * (they share no dependency and cannot share a module), and the existing distinctness test passes
+ * unchanged.
+ *
+ * Considered and recorded as a carry rather than done here: `bun build --splitting`, so shared
+ * internals emit once per package. It is the more fundamental answer and it changes the emit shape
+ * for every package and every `.d.ts` -- not a round-3-sized change.
+ */
+export declare function brandedInstanceOf(brand: symbol): (candidate: unknown) => boolean;
+/** The cross-bundle identity of THIS package's `BunRequiredError`. Package-scoped on purpose. */
+declare const BUN_REQUIRED_BRAND: unique symbol;
+export declare class BunRequiredError extends Error {
+    readonly name = "BunRequiredError";
+    /** F2: the brand `Symbol.hasInstance` below tests for. Present on every instance, in every bundle. */
+    readonly [BUN_REQUIRED_BRAND] = true;
+    /** F2: `instanceof` holds across this package's duplicated entry bundles, and only this package's. */
+    static [Symbol.hasInstance]: (candidate: unknown) => boolean;
+    /** The exported function the caller invoked. */
+    readonly functionName: string;
+    /** The Bun API that has no Node equivalent this package implements, e.g. `Bun.serve`. */
+    readonly bunApi: string;
+    constructor(functionName: string, bunApi: string, detail: string);
+}
+/** True when this process is Bun. Separated so a test can assert the guard without a subprocess. */
+export declare function hasBunRuntime(): boolean;
+/**
+ * Throws `BunRequiredError` unless this process is Bun. Called FIRST in each guarded function, before
+ * any network call, any file write and any credential read — a guard that fired after a side effect
+ * would be a worse failure than the `ReferenceError` it replaces.
+ */
+export declare function requireBunRuntime(functionName: string, bunApi: string, detail: string): void;
+export {};

package/dist/continuity/decoration.d.ts

@@ -0,0 +1,89 @@
+/** Which door a decoration goes through. Mirrors `ProviderMessageLike.decoration.door`. */
+export type DecorationDoor = "tag" | "thinking-channel";
+/** The tag name of the text door, in ONE place: the renderer, the corpus and the escaping all name it from here. */
+export declare const RECOVERED_REASONING_TAG = "recovered_reasoning_summary";
+/** Who produced the reasoning being carried. Ids only -- never a credential, never opaque state. */
+export interface DecorationSource {
+    providerId: string;
+    modelKey: string;
+}
+export interface DecorationInput {
+    /** The readable material: a provider-produced SUMMARY or complete exposed reasoning. Never opaque state -- there is deliberately no parameter for one. */
+    text: string;
+    source: DecorationSource;
+    door: DecorationDoor;
+    /**
+     * §9.6's context budget for this one decoration, counted on the FINISHED text -- wrapper included.
+     *
+     * Counting only the body would let a caller's budget be quietly overspent by the delimiter and the
+     * origin labels, which is most of a short decoration; a budget that does not bound what actually
+     * reaches the target is not a budget. Absent means unbounded.
+     */
+    maxChars?: number;
+}
+export interface Decoration {
+    text: string;
+    door: DecorationDoor;
+    /** §9.6: ANY truncation flips the transfer to warned-lossy. The flag is what makes that flip observable rather than a silent claim of losslessness. */
+    truncated: boolean;
+}
+/**
+ * Which door a target's own reasoning transport admits.
+ *
+ * `full-exposed` targets read plain reasoning text, so their own channel is available. `summary` and
+ * `none` targets either validate their reasoning channel (Anthropic signatures) or have none at all;
+ * for both, the text tag is the only door.
+ */
+export declare function doorFor(target: {
+    readableState: "none" | "summary" | "full-exposed";
+}): DecorationDoor;
+/**
+ * Builds ONE decoration.
+ *
+ * The escaping below is not cosmetic. `providerId`/`modelKey` are catalog strings and a summary is
+ * MODEL-GENERATED text: both are untrusted (WS-13 §7 says as much about model ids), and either could
+ * contain a forged closing delimiter. A body that could terminate its own wrapper would let quoted
+ * prior-model text escape the delimiter and read as first-class instruction to the target -- the one
+ * failure the injection floor exists to prevent -- so a forged delimiter is neutralised into inert
+ * text and the wrapper's own closing tag remains the only one.
+ */
+export declare function buildDecoration(input: DecorationInput): Decoration;
+/**
+ * How many characters a decoration spends on its wrapper alone, for THIS source and door.
+ *
+ * Exported because the renderer has to decide whether a remaining budget can hold a decoration at all
+ * BEFORE building one: a wrapper with an empty body is not a decoration, it is noise with a delimiter
+ * around it, and the honest response to "no room" is to drop the material and say so.
+ */
+export declare function decorationOverhead(source: DecorationSource, door: DecorationDoor): number;
+/** The minimum body a decoration must be able to carry to be worth sending at all. */
+export declare const MIN_DECORATION_BODY_CHARS = 32;
+/**
+ * §9.6's trimming, mechanically.
+ *
+ * KEEPS THE HEAD AND THE TAIL with an explicit elision between them. §9.6 orders what to retain by
+ * MEANING (concrete decisions, evidence, exact identifiers and pending work before redundant
+ * speculation), and Winter cannot rank text semantically without another model call -- so this is an
+ * approximation, chosen because objective and evidence cluster at the start of a reasoning trace and
+ * decisions and pending work at the end, while restatement accumulates in the middle. The
+ * approximation is only defensible because it is NEVER silent: `truncated` flips the whole transfer
+ * to warned-lossy, which is §9.6's closing rule ("never silently truncate reasoning while still
+ * classifying the handoff as lossless").
+ */
+export declare function trimToBudget(text: string, maxChars: number | undefined): {
+    text: string;
+    truncated: boolean;
+};
+/** Escapes an XML-ish attribute value. `&` first, or the escapes escape each other. */
+export declare function escapeAttribute(value: string): string;
+/** Strips angle brackets from an id rendered inline in prose, so a crafted model id cannot open a tag of its own. */
+export declare function escapeInline(value: string): string;
+/**
+ * Neutralises any sequence that would look like this module's own delimiter.
+ *
+ * Only the delimiter is touched -- the body is otherwise carried VERBATIM, because the whole value of
+ * forwarding complete exposed reasoning (the DeepSeek→OpenAI no-warning case, §8.4 condition 2) is
+ * that it is passed unmodified. Escaping every `<` would modify it, and would then have to be
+ * declared lossy.
+ */
+export declare function neutralizeDelimiters(text: string): string;

package/dist/continuity/domains.d.ts

@@ -0,0 +1,92 @@
+import type { EvidenceConfidence, ReasoningCapabilities, WinterModelDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import { type ProviderRegistry } from "../registry.js";
+import type { MessageOrigin } from "../types.js";
+/** What a readable-reasoning capability can be. Mirrors `ProviderAdapter.capabilities().readableState` and the descriptor's own evidence. */
+export type ReadableState = "none" | "summary" | "full-exposed";
+/**
+ * One side of a transfer: who produced (or will consume) a message, and what its reasoning transport
+ * can do. Built from a stamped `MessageOrigin` plus whatever the catalog knows about that model.
+ */
+export interface ContinuityEndpoint {
+    providerId: string;
+    modelKey: string;
+    family: string;
+    /** The STAMPED continuation-domain id. Absent means "this model's native state is not documented to be replayable anywhere" -- never "any domain". */
+    continuationDomain?: string;
+    /**
+     * The model's reasoning TRANSPORT, straight from its descriptor. `"none"` is the fact that matters
+     * here: a model with no reasoning at all has no hidden state to lose, so a switch away from it must
+     * not warn about reasoning (review I1 -- `readableState: "none"` alone conflates "no readable
+     * summary" with "no reasoning", and a chat model warned about losing state it never had).
+     *
+     * ABSENT MEANS UNKNOWN, and unknown warns: the fallback endpoint (no catalog row) cannot prove the
+     * source was reasoning-free, and silence about a reasoning model is the expensive mistake.
+     */
+    continuation?: ReasoningCapabilities["continuation"];
+    readableState: ReadableState;
+    /** Whether this model documents a way to ASK for a readable summary (§9.1's proactive-summary policy). */
+    summaryRequest?: {
+        field: string;
+        values: string[];
+    };
+}
+/** The subset of an endpoint the domain test reads. Deliberately tiny: a `nativeState` and a render target are both valid arguments. */
+export interface DomainFacts {
+    continuationDomain?: string;
+}
+/**
+ * Do these two sides share a continuation domain?
+ *
+ * TRUE requires BOTH sides to carry a stamped id AND the ids to be equal. Every other shape is false,
+ * including the one that looks safest: two sides that both have NO domain id are NOT the same domain,
+ * because absence means "undocumented", and two undocumented transports are not thereby the same
+ * transport. Reading absence as a wildcard is how an OpenAI reasoning item would be replayed into
+ * Anthropic on a session where neither model happened to carry evidence.
+ *
+ * There is deliberately no `providerId`/`family` argument. Adding one would make it possible to write
+ * the forbidden test.
+ */
+export declare function sameDomain(a: DomainFacts | undefined, b: DomainFacts | undefined): boolean;
+/** The evidence confidences that CERTIFY a shared continuation domain (§8.4's own word). Anything weaker is a guess, and a guess must not buy a suppressed warning. */
+export declare const CERTIFIED_DOMAIN_CONFIDENCES: ReadonlySet<EvidenceConfidence>;
+/** Whether two sides belong to the same wire family. NEVER a substitute for `sameDomain` -- two Claude models are one family and (absent evidence) two domains. */
+export declare function sameFamily(a: {
+    family: string;
+} | undefined, b: {
+    family: string;
+} | undefined): boolean;
+/** The descriptor's readable-reasoning evidence, or `"none"` when it declares none. Reading a bare `supported: true` as "has a summary" would be exactly the timeless boolean WS-13 §4 forbids. */
+export declare function readableStateOf(descriptor: WinterModelDescriptor | undefined): ReadableState;
+/** The provider's own documented summary-request field and its accepted values (Anthropic `display`, OpenAI `reasoning.summary`, Gemini `includeThoughts`). */
+export declare function summaryRequestOf(descriptor: WinterModelDescriptor | undefined): {
+    field: string;
+    values: string[];
+} | undefined;
+/**
+ * §9.1's proactive-summary policy: ask for a summary from session start whenever the model documents
+ * HOW to ask.
+ *
+ * THE TEST IS `summaryRequest`, NOT `readableState`, and the difference is a live provider rather
+ * than a nicety: DeepSeek's readable state is `full-exposed` (it returns `reasoning_content`) while
+ * its Responses compatibility does not generate REQUESTED summaries at all -- so a policy keyed on
+ * readable state asks DeepSeek for something it will never produce, on every request of the session.
+ * A model with no `summaryRequest` evidence is one Winter does not know how to ask, and asking anyway
+ * is the silent assumption §9.1 closes with ("do not silently assume summaries are free or
+ * universally available").
+ */
+export declare function shouldRequestSummary(descriptor: WinterModelDescriptor | undefined): boolean;
+/**
+ * Turns a stamped `MessageOrigin` into the full endpoint facts, through the REGISTRY.
+ *
+ * The registry is the only capability authority (R6-12: Lane C reads capability facts through T2's
+ * registry). `resolve()` returns an ERROR OBJECT rather than throwing, and the fallback for one is
+ * the stamped origin itself: a message produced by a model that has since left the catalog still
+ * knows its own provider, model and domain, and degrading it to "unknown" would drop a valid native
+ * replay because a catalog row was renamed.
+ *
+ * Cached per `modelKey` for the lifetime of the returned function: one render pass asks about the
+ * same handful of models once per message, and `resolve` walks the catalog indexes each time.
+ */
+export declare function createEndpointResolver(registry: ProviderRegistry): (origin: MessageOrigin) => ContinuityEndpoint;
+/** The registry-free fallback: everything the stamp itself carries, and `readableState: "none"` because absence of evidence is not evidence of a summary. */
+export declare function endpointFromOrigin(origin: MessageOrigin): ContinuityEndpoint;

package/dist/continuity/fixtures.d.ts

@@ -0,0 +1,44 @@
+import type { CapabilityEvidence, EvidenceConfidence, ReasoningCapabilities, ToolCalling, WinterCatalog, WinterModelDescriptor, WinterProviderDescriptor } from "@yanlinglabs/winter-provider-catalog";
+import type { ProviderAdapter, ProviderEvent, ProviderFamily } from "../types.js";
+export declare const evidence: <T>(value: T, confidence?: EvidenceConfidence) => CapabilityEvidence<T>;
+export interface FixtureModelInit {
+    key: string;
+    providerId: string;
+    upstreamId?: string;
+    aliases?: string[];
+    reasoning?: ReasoningCapabilities;
+    toolCalling?: ToolCalling;
+    contextWindow?: number;
+}
+export declare function fixtureModel(init: FixtureModelInit): WinterModelDescriptor;
+/**
+ * The reasoning evidence a reasoning-capable row carries. `domain` is the MEMBER LIST the registry
+ * derives a domain id from -- passing two models the same list is how a fixture certifies a shared
+ * domain, and passing different lists is how it certifies two domains that share an HTTP shape.
+ */
+export declare function fixtureReasoning(init: {
+    readableState: "none" | "summary" | "full-exposed";
+    continuation?: ReasoningCapabilities["continuation"];
+    domain?: string[];
+    summaryRequest?: {
+        field: string;
+        values: string[];
+    };
+    efforts?: string[];
+    confidence?: EvidenceConfidence;
+}): ReasoningCapabilities;
+export declare function fixtureProvider(init: {
+    id: string;
+    adapterId?: string;
+    family?: string;
+    baseUrl?: string;
+}): WinterProviderDescriptor;
+export declare function fixtureCatalog(providers: WinterProviderDescriptor[], models: WinterModelDescriptor[]): WinterCatalog;
+/** A scripted `ProviderAdapter`: no HTTP, no credentials. `events` is what `streamTurn` yields, and every request it is handed is recorded for assertions. */
+export declare function scriptedAdapter(init: {
+    id: string;
+    family?: ProviderFamily;
+    events?: ProviderEvent[];
+}): ProviderAdapter & {
+    requests: unknown[];
+};

package/dist/continuity/handoff.d.ts

@@ -0,0 +1,94 @@
+import type { ContinuityEndpoint } from "./domains.js";
+import type { ContinuationChainLike, MaterialKind } from "./renderer.js";
+import type { ProviderMessageLike } from "../types.js";
+/** The delimiter of the handoff block. Its own tag, distinct from a reasoning decoration's: the two carry different classes of content and a reader must not have to guess which. */
+export declare const PRIOR_MODEL_HANDOFF_TAG = "prior_model_handoff";
+/**
+ * Instruction-file basenames a tool fact is never allowed to carry (§2.8). Matched case-insensitively
+ * on the basename.
+ *
+ * P7a (D19): the first entry is `brand.instructionsFile`. This is a SAFETY list, so a branded session
+ * gets its own name ADDED to this set rather than swapped into it (`PortableHandoffOptions.
+ * instructionsFile`) -- a repository can perfectly well contain Winter's own instructions file and a
+ * reuser's beside it, and neither belongs in a handoff.
+ */
+export declare const INSTRUCTION_FILE_BASENAMES: readonly string[];
+export interface HandoffToolFact {
+    name: string;
+    ok: boolean;
+    /** A BOUNDED excerpt of the factual result. Absent when the call produced nothing quotable. */
+    detail?: string;
+}
+export interface PortableHandoffSections {
+    source: {
+        providerId: string;
+        modelKey: string;
+    };
+    /** The current user objective: the most recent user message's own visible text. Winter does not infer an objective -- it quotes the one the user stated. */
+    objective?: string;
+    /**
+     * The source's readable reasoning, labelled by KIND so a summary is never mistaken for a complete
+     * trace (§9.5) -- and by `truncated`, so a 400-character remnant is never labelled "complete".
+     */
+    reasoning?: {
+        kind: MaterialKind;
+        text: string;
+        truncated: boolean;
+    };
+    /** The source's visible assistant text, oldest first: the decisions and the rationale it actually stated. */
+    visibleRationale: string[];
+    toolFacts: HandoffToolFact[];
+    artifacts: string[];
+    /** Failures, denials and interruptions -- the work that is demonstrably not finished. */
+    unresolved: string[];
+    finalResponse?: string;
+    /** §9.4's optional source-produced continuation brief. Supplied by the caller; never requested from here. */
+    brief?: string;
+}
+export interface PortableHandoff {
+    sections: PortableHandoffSections;
+    /** The rendered block, already delimited and labelled -- drop it into `ProviderMessage.decoration` (door `"tag"`). */
+    text: string;
+    /** ANY quoted value was bounded -- including a tool-result excerpt, which is not reasoning loss. */
+    truncated: boolean;
+    /**
+     * The REASONING specifically was trimmed. Tracked apart from `truncated` because they mean
+     * different things to §9.6: a clipped tool excerpt is a display bound, while a clipped reasoning
+     * trace is state the target will not receive -- and the second one, and only the second one, must
+     * flip a would-be-lossless transfer to warned-lossy. The engine's switch point folds THIS flag
+     * into its `SwitchFacts`, never `truncated`.
+     */
+    reasoningTruncated: boolean;
+}
+export interface PortableHandoffOptions {
+    /** §9.4's brief, when the harness asked the source for one before switching. */
+    brief?: string;
+    /** How many of the source's most recent visible assistant messages to carry. Default 4. */
+    maxVisibleMessages?: number;
+    /** How many completed tool facts to carry, most recent first. Default 12. */
+    maxToolFacts?: number;
+    /** The per-value character bound on any quoted text. Default 400. */
+    maxValueChars?: number;
+    /** Path fragments whose tool facts are dropped -- pass the session's memory directory here (§2.8). Instruction-file basenames are refused unconditionally. */
+    excludedPathFragments?: readonly string[];
+    /** P7a (D19): the running brand's `instructionsFile`, ADDED to `INSTRUCTION_FILE_BASENAMES` (never swapped for it). */
+    instructionsFile?: string;
+    /** Whether the source's exposed reasoning may be forwarded at all (§12.4: only when policy permits). A summary is unaffected. */
+    allowExposedForwarding?: boolean;
+}
+/**
+ * Builds the handoff.
+ *
+ * `messages` is the conversation AS THE ENGINE HOLDS IT -- the same array the renderer sees -- and
+ * `chain` supplies the source's captured reasoning. Everything is derived MECHANICALLY: the objective
+ * is the user's own last message, the rationale is the assistant's own visible text, the tool facts
+ * are real completed calls. Nothing here summarises or infers, because a summary Winter invents is a
+ * claim about the source's reasoning that the source never made -- that is what §9.4's optional brief
+ * is for, and it comes from the source model itself.
+ */
+export declare function buildPortableHandoff(messages: readonly ProviderMessageLike[], chain: ContinuationChainLike, from: ContinuityEndpoint, options?: PortableHandoffOptions): PortableHandoff;
+/** The handoff as a `ProviderMessage.decoration`. The TAG door always: a handoff is text, and it must be readable by a family whose reasoning channel validates its input. */
+export declare function handoffDecoration(handoff: PortableHandoff): {
+    text: string;
+    door: "tag";
+};

package/dist/continuity/index.d.ts

@@ -0,0 +1,10 @@
+export { RECOVERED_REASONING_TAG, MIN_DECORATION_BODY_CHARS, buildDecoration, decorationOverhead, doorFor, escapeAttribute, escapeInline, neutralizeDelimiters, trimToBudget } from "./decoration.js";
+export type { Decoration, DecorationDoor, DecorationInput, DecorationSource } from "./decoration.js";
+export { createEndpointResolver, endpointFromOrigin, readableStateOf, sameDomain, sameFamily, shouldRequestSummary, summaryRequestOf } from "./domains.js";
+export type { ContinuityEndpoint, DomainFacts, ReadableState } from "./domains.js";
+export { applyDecorationToContent, createHistoryRenderer } from "./renderer.js";
+export type { ContinuationChainLike, ContinuationLinkLike, HistoryRendererOptions, HistoryTarget, MaterialKind, RenderReport, RenderedDecoration, WinterHistoryRenderer } from "./renderer.js";
+export { classifySwitch } from "./warnings.js";
+export type { LossClass, SwitchClassification, SwitchFacts } from "./warnings.js";
+export { INSTRUCTION_FILE_BASENAMES, PRIOR_MODEL_HANDOFF_TAG, buildPortableHandoff, handoffDecoration } from "./handoff.js";
+export type { HandoffToolFact, PortableHandoff, PortableHandoffOptions, PortableHandoffSections } from "./handoff.js";

package/dist/continuity/renderer.d.ts

@@ -0,0 +1,111 @@
+import type { ProviderRegistry } from "../registry.js";
+import type { ContentBlockLike, MessageOrigin, ProviderMessageLike, ProviderNativeState } from "../types.js";
+import { type DecorationDoor } from "./decoration.js";
+import { type ReadableState } from "./domains.js";
+/** The target of THIS request. Structurally the `target` argument of the runtime's frozen `HistoryRenderer` seam. */
+export interface HistoryTarget {
+    family: string;
+    continuationDomain?: string;
+    readableState: ReadableState;
+}
+/** One assistant entry's folded sidecar records. Structurally `ContinuationLink` from the runtime's `store/provider-state.ts`. */
+export interface ContinuationLinkLike {
+    origin?: MessageOrigin;
+    nativeState?: ProviderNativeState;
+    summary?: string;
+}
+/** What the renderer needs of a chain: a lookup by anchor uuid. `Map<string, ContinuationLink>` -- the runtime's `ContinuationChain` -- satisfies it exactly. */
+export interface ContinuationChainLike {
+    get(anchorUuid: string): ContinuationLinkLike | undefined;
+}
+/** Whether a message's readable material is a provider SUMMARY or its own complete exposed reasoning. §9.5: the two are never merged, and never merged with opaque state. */
+export type MaterialKind = "summary" | "exposed";
+export interface RenderedDecoration {
+    /** The decorated message's anchor uuid, when it had one. Identity only -- this record never carries the decoration's text, let alone any payload. */
+    anchorUuid?: string;
+    source: {
+        providerId: string;
+        modelKey: string;
+    };
+    kind: MaterialKind;
+    door: DecorationDoor;
+    truncated: boolean;
+}
+/**
+ * What one render did. The seam returns only messages, so this is how a caller learns that a transfer
+ * became lossy -- §9.6's "never silently truncate reasoning while still classifying the handoff as
+ * lossless" needs somewhere for the truncation to be reported, and this is it.
+ */
+export interface RenderReport {
+    /** Messages replayed with their native state intact (same domain). */
+    replayedNatively: number;
+    /** Messages whose native state was dropped because the target is a different domain. */
+    droppedNativeState: number;
+    /** In-dialect thinking / redacted_thinking blocks stripped from content on a cross-domain leg. */
+    strippedInDialectBlocks: number;
+    decorations: RenderedDecoration[];
+    /** Cross-domain messages that had NO readable material to carry (no summary captured, or forwarding was policy-blocked). */
+    withoutMaterial: number;
+    /** Material dropped ENTIRELY because the render's total decoration budget was exhausted. */
+    budgetDropped: number;
+    /** ANY truncation or budget drop. The engine's switch point reads this to flip a would-be-lossless transfer to warned-lossy. */
+    truncated: boolean;
+    /**
+     * Decorations placed on the THINKING-CHANNEL door, which only the target family's own adapter can
+     * address. Surfaced so a caller can see that this render depends on adapter-side placement --
+     * `applyDecorationToContent` deliberately cannot do it, and a count of zero means every decoration
+     * this render produced is placeable as ordinary text.
+     */
+    thinkingChannelDecorations: number;
+}
+export interface HistoryRendererOptions {
+    /** §9.6: the per-decoration character budget. Absent = unbounded. */
+    maxDecorationChars?: number;
+    /** §9.6: the budget for ALL decorations in one render, spent NEWEST FIRST so the material closest to the current work survives. Absent = unbounded. */
+    decorationCharBudget?: number;
+    /**
+     * §12.4 / §8.4: whether raw exposed reasoning may be forwarded at all. `false` suppresses
+     * `exposed` material (a provider or user policy that forbids forwarding) while leaving
+     * provider-produced summaries alone; `classifySwitch` turns it into the policy-blocked warning.
+     */
+    allowExposedForwarding?: boolean;
+    /** Called with every render's report. The frozen seam returns only messages; this is the side channel that keeps truncation observable through it. */
+    onReport?: (report: RenderReport) => void;
+}
+/**
+ * The renderer.
+ *
+ * `render` is deliberately GENERIC over the message type rather than typed against the engine's
+ * `ProviderMessage`: this package must never import the runtime (R6-4's cycle rule), and a generic
+ * whose constraint is `ProviderMessageLike` is instantiated at `M = ProviderMessage` when this object
+ * is assigned to the runtime's frozen `HistoryRenderer` seam. `corpus/continuity.test.ts` proves that
+ * assignment against the REAL `adapterAsProvider` rather than against a hand-copied shape.
+ */
+export interface WinterHistoryRenderer {
+    render<M extends ProviderMessageLike>(messages: M[], chain: ContinuationChainLike, target: HistoryTarget): M[];
+    renderWithReport<M extends ProviderMessageLike>(messages: M[], chain: ContinuationChainLike, target: HistoryTarget): {
+        messages: M[];
+        report: RenderReport;
+    };
+}
+export declare function createHistoryRenderer(registry: ProviderRegistry, options?: HistoryRendererOptions): WinterHistoryRenderer;
+/** What `applyDecorationToContent` did. `applied: false` always says WHY, and always returns the untouched content. */
+export type DecorationPlacement = {
+    applied: true;
+    content: string | ContentBlockLike[];
+} | {
+    applied: false;
+    reason: "no-decoration" | "thinking-channel-door";
+    content: string | ContentBlockLike[];
+};
+/**
+ * Places a TAG-door decoration into a message's own content, as ordinary text.
+ *
+ * OFFERED TO ADAPTERS, and it is what makes the door real: the renderer annotates, and the adapter
+ * that owns a family's wire mapping decides where the annotation goes. For the tag door that is a
+ * plain text block appended to the message the reasoning belongs to (text is the ONLY door into a
+ * validating family); for the thinking-channel door it is the family's own plain reasoning field,
+ * which only that adapter can address, so this helper deliberately refuses that case rather than
+ * quietly turning it into text.
+ */
+export declare function applyDecorationToContent(message: ProviderMessageLike): DecorationPlacement;

package/dist/continuity/warnings.d.ts

@@ -0,0 +1,46 @@
+import { type ContinuityEndpoint } from "./domains.js";
+/**
+ * How much of the source's continuation survives.
+ *
+ * `lossless-native` -- the target accepts the source's own native continuation object (§8.4's first
+ * suppressing condition: a certified shared domain).
+ * `lossless-portable` -- the source's COMPLETE readable reasoning crosses unmodified as text (§8.4's
+ * second condition; the DeepSeek→OpenAI class).
+ * `warned-lossy` -- everything else. Truncation flips either lossless class into this one.
+ */
+export type LossClass = "lossless-native" | "lossless-portable" | "warned-lossy";
+/**
+ * The per-switch observations. BOOLEANS AND COUNTS ONLY -- there is deliberately no field that could
+ * carry reasoning text, a payload, or a credential, which is what makes "warnings never print
+ * payloads" a property of the type rather than a rule someone has to remember.
+ */
+export interface SwitchFacts {
+    /** A provider-produced summary for the source's work exists (captured into the sidecar). */
+    summaryAvailable?: boolean;
+    /** For a `full-exposed` source: is the readable reasoning COMPLETE? `false` means some of it is missing (§8.4's third trigger). */
+    exposedComplete?: boolean;
+    /** Reasoning had to be trimmed to fit the target's context (§9.6). Flips a lossless class to lossy, always. */
+    truncated?: boolean;
+    /** A provider or user policy forbids forwarding the reasoning text (§8.4's fifth trigger, §12.4's "only when policy permits"). */
+    policyBlocksForwarding?: boolean;
+    /** The switch aborts a RUNNING turn before its final summary/state exists (§8.3's immediate switch). */
+    midTurnAbort?: boolean;
+    /** How many tool calls completed and are therefore carried as portable FACTS. Zero is a fact about the turn, not a missing input. */
+    completedToolResults?: number;
+}
+export interface SwitchClassification {
+    lossClass: LossClass;
+    /** User-facing prose. Empty for a lossless transfer -- that is what "warn iff lossy" means. */
+    warnings: string[];
+    /** What survives the switch, named exactly. Never empty: the visible conversation always crosses. */
+    portable: string[];
+}
+/**
+ * Classifies one requested transition.
+ *
+ * `from`/`to` carry the CAPABILITY facts (readable state, stamped continuation domain) and `facts`
+ * carries what is true of this particular switch. Nothing here reads a provider id to decide
+ * portability -- `sameDomain` is the only continuation test, so "same vendor" never buys a suppressed
+ * warning and "different vendor" never forces one.
+ */
+export declare function classifySwitch(from: ContinuityEndpoint, to: ContinuityEndpoint, facts?: SwitchFacts): SwitchClassification;

package/dist/credentials/env.d.ts

@@ -0,0 +1,6 @@
+import type { CredentialStore } from "../types.js";
+export interface EnvCredentialStoreOptions {
+    /** The environment this store may read. A host passes `process.env` explicitly at the composition root if that is what it wants — never here. */
+    env: Record<string, string | undefined>;
+}
+export declare function createEnvCredentialStore(opts: EnvCredentialStoreOptions): CredentialStore;