@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/sdk.d.ts

@@ -0,0 +1,214 @@
+import type { BrandProfile, Options, Query, SessionKey } from "@yanlinglabs/winter-agent-sdk";
+import { type RouterOfficialInput, type RouterOfficialPolicy, type RouterQuery } from "./door.js";
+import type { SeamContextWithDirectory } from "./seams/context.js";
+import type { OfficialSdkModule } from "./seams/official-sdk-shapes.js";
+import type { GlobalMessagingHandle } from "./messaging/router.js";
+import type { HandoffBarrier, HandoffOutcome } from "./seams/handoff.js";
+import type { KeychainSeam } from "./seams/keychain.js";
+import type { MaterializedResumeDecorator } from "./seams/materialized-resume.js";
+import type { OfficialAdapter } from "./seams/official-adapter.js";
+import type { RuntimeDirectory } from "./seams/directory.js";
+import type { RuntimeDirectoryStore } from "./seams/directory-store.js";
+import type { GlobalMessagingOptions, RuntimeDirectoryOptions } from "./messaging/index.js";
+import type { HandoffBarrierDeps } from "./store/index.js";
+import type { RuntimeKind, RuntimeSelection, SelectionInput } from "./selection/runtime-selection.js";
+import { type VersionMatrixReport } from "./version-matrix.js";
+/**
+ * The injected peers.
+ *
+ * INSTANCES, not names. The router never imports the official SDK as a value — a host that only ever
+ * creates Winter sessions never loads it — and taking the Winter peer by injection too means a host
+ * that vendors all three packages (WS-02's own model) can be certain no SDK is instantiated twice.
+ */
+export interface RuntimeSdkPeers {
+    winter: typeof import("@yanlinglabs/winter-agent-sdk");
+    /**
+     * The official runtime's module instance, when the host has one.
+     *
+     * TYPED STRUCTURALLY (`OfficialSdkModule`), not as `typeof import("@anthropic-ai/claude-agent-sdk")`
+     * as the plan pins — a fourth documented departure, and forced by the plan's own decision to make
+     * this peer OPTIONAL. A `typeof import(…)` in a published `.d.ts` makes every consumer's
+     * type-checker resolve the module, so a Winter-only host that (correctly) did not install it would
+     * see `Cannot find module` coming out of this package. See `seams/official-sdk-shapes.ts` for the
+     * full reasoning, the conformance test that keeps the structural shape honest against the real
+     * 0.3.250 declarations, and the packing gate that keeps the specifier out of the reachable
+     * declaration graph.
+     */
+    claude?: OfficialSdkModule;
+}
+export interface RuntimeSdkOptions {
+    peers: RuntimeSdkPeers;
+    /** R-7b-2's seam; default = in-memory (which is also what every hermetic test uses). */
+    directoryStore?: RuntimeDirectoryStore;
+    /** Host-provided credential reads (WS-14 §12) — never disk, never this package's own keychain. */
+    keychain: KeychainSeam;
+    /** `pathToClaudeCodeExecutable` for the official branch: the host vendors it; tests use node_modules. */
+    vendoredOfficialRuntime?: string;
+    /**
+     * Flows through to both branches unchanged (D19 clause a).
+     *
+     * RESOLVED ONCE, at construction, through the INJECTED peer's own `resolveBrand` — so an invalid
+     * profile is a typed construction refusal (`InvalidBrandError`, the Winter SDK's own class) beside
+     * the version matrix's, rather than a surprise at the first query. `RuntimeSdk.brand` is the
+     * result, and it is what the official branch and the router's own name derivations use.
+     *
+     * PRECEDENCE, in one sentence: a per-query `Options.brand` wins on the Winter leg and is never
+     * rewritten; this constructor profile fills in when a query supplies none; Winter's own defaults
+     * fill in when neither does.
+     */
+    brand?: Partial<BrandProfile>;
+    /**
+     * The handoff barrier's collaborators (whole-branch review, F-3).
+     *
+     * WITHOUT THIS FIELD THE HANDLE'S `handoff()` COULD NEVER RETURN `resumed`. `HandoffBarrierDeps`
+     * carries `participants` — the source owner to drain and the destination to confirm — and the
+     * factory was called with no options at all, so `markersFor` set step 8 "no destination runtime was
+     * supplied" and every `sdk.handoff()` ended in a lossy fork. The spine's promise was one wiring
+     * line per seam; keeping it meant the lane factories were CONSTRUCTED but never CONFIGURABLE.
+     *
+     * `shared` AND `decorator` ARE NOT OFFERED, on purpose: the barrier builds both so that one store,
+     * one decoration registry and one door are structural (see `createHandoffBarrier`'s own F2 note).
+     * A host that injected a second store would get the wash-back that check exists to refuse.
+     *
+     * `winterHome` here is what fills `SeamContext.winterHome`, so the barrier, its decorator and any
+     * later seam that reads the context all resolve under the same home.
+     */
+    handoff?: Omit<HandoffBarrierDeps, "shared" | "decorator">;
+    /**
+     * The official adapter's own policy (Task 6b).
+     *
+     * WITHOUT IT THE OFFICIAL LEG IS UNCONFIGURABLE, in the same way F-3 found the other two seams to
+     * be: `createOfficialAdapter(context)` was called with no options at all, so a host could not name
+     * its `configuredExtras`, its containment dispositions, its crash hook or its reconciler — and the
+     * door builds this branch's options and child environment from exactly those. `env.remoteConfig` is
+     * the deployment-wide default for R-7b-11; a per-query `runtime.official.remoteConfig` wins over it.
+     */
+    official?: RouterOfficialPolicy;
+    /**
+     * The directory's and the router's own options (whole-branch review, F-3).
+     *
+     * WITHOUT THIS FIELD EVERY OFFICIAL RECEIVER WAS HELD FOREVER. `official.permissionClass` is the
+     * ONLY way an official session's permission class can be known — there is no facet to ask — and
+     * since D2 an unknown class fails closed, so a host that could not pass it had a `messaging` that
+     * held every message to every official session and never released it. The README sentence item 19
+     * owes ("fail-closed until `official.permissionClass` is wired") had no field to name.
+     */
+    messaging?: {
+        directory?: RuntimeDirectoryOptions;
+        messaging?: GlobalMessagingOptions;
+    };
+}
+/** Options members this package OWNS. Never forwarded to either SDK — see `query()`. */
+export declare const ROUTER_ONLY_OPTION_KEYS: readonly ["runtime"];
+export type RouterOnlyOptionKey = (typeof ROUTER_ONLY_OPTION_KEYS)[number];
+/**
+ * The runtime-selection inputs the door accepts ALONGSIDE the pinned `Options` — "additive and
+ * typed" (the plan's Global Constraints), and stripped before either SDK sees them.
+ */
+export interface RouterRuntimeInput {
+    /** A selection already persisted for this session. It WINS: a change is a handoff or a visible fork. */
+    selection?: RuntimeSelection;
+    /** Everything needed to decide one when there is no persisted selection yet. */
+    select?: SelectionInput;
+    /**
+     * This session's own id, on EITHER leg.
+     *
+     * WHAT IT BUYS: the door can hold a caller to the session's persisted choice. `selection` is
+     * documented as "already persisted for this session", so a `selection` that disagrees with the
+     * session's record is a REQUEST TO CHANGE RUNTIME, and D13 answers that with a certified handoff or
+     * a visible fork — never by serving the new runtime on the old transcript. With an id, the door
+     * refuses that in-process on both legs; the official leg additionally reads the durable directory
+     * row before it launches anything. Without one, the host is the only party holding the record.
+     *
+     * The official leg takes its id from `official.sessionId` (which it requires anyway); this field is
+     * for the Winter leg and for a host that prefers to say it once.
+     */
+    sessionId?: string;
+    /**
+     * What the OFFICIAL leg needs and only the host knows (Task 6b) — the session id its directory row
+     * is addressed by, its credential plan for families whose variables are the host's, the vendored
+     * runtime's neighbours. Ignored entirely on the Winter leg, where the pinned `Options` already say
+     * everything.
+     */
+    official?: RouterOfficialInput;
+}
+/** `Options` plus the router's own additive input. Nothing is removed and nothing is renamed. */
+export interface RouterOptions extends Options {
+    runtime?: RouterRuntimeInput;
+}
+export interface RuntimeSdk {
+    /** The resolved brand profile every Winter-owned name in this session derives from (I2). */
+    readonly brand: BrandProfile;
+    /**
+     * The one door, over BOTH runtimes (Task 6b). See this module's header for the deviations from the
+     * plan's pinned line, and `src/door.ts` for the official leg's own composition.
+     *
+     * TWO OVERLOADS, AND THE SPLIT IS A FACT RATHER THAN A CONVENIENCE. The official leg is reachable
+     * ONLY through `options.runtime`, so a call that passes none can only ever produce the Winter peer's
+     * `Query` — and says so. A call that DOES pass one is decided at run time, and its type is the union
+     * of the two runtimes' own handles, because neither of them is the other and this package will not
+     * flatten them into a facade (see `RouterQuery`).
+     */
+    query(args: {
+        prompt: string | AsyncIterable<string>;
+        options?: Options & {
+            runtime?: never;
+        };
+    }): Query;
+    query(args: {
+        prompt: string | AsyncIterable<string>;
+        options: RouterOptions;
+    }): RouterQuery;
+    /** D13/D28, pure. Throws `SelectionRefusedError` on a typed refusal (see that class's own note). */
+    selectRuntime(input: SelectionInput): RuntimeSelection;
+    /** WS-15 §6.1. */
+    directory: RuntimeDirectory;
+    /**
+     * WS-15 §6.2–6.4 — the HANDLE, which is the seam plus the two doors a host cannot work without.
+     *
+     * WIDENED, NEVER NARROWED (F-3). The plan pins `GlobalMessaging`, and `GlobalMessagingHandle`
+     * extends it: every pinned member is present with its pinned signature, and what is added is
+     * `attachWinterSession`/`attachOfficialSession` — without which a host can configure a receiver's
+     * permission class and still have nothing live to deliver to. Typing the field as the seam meant
+     * the one door the package exists for could be reached only through a cast.
+     */
+    messaging: GlobalMessagingHandle;
+    /** WS-05 §12's mechanics; the host renders the outcome (R-7b-3). */
+    handoff(session: SessionKey, to: RuntimeKind): Promise<HandoffOutcome>;
+    readonly versions: VersionMatrixReport;
+    dispose(): Promise<void>;
+}
+/**
+ * The collaborators a lane swaps its real implementation into.
+ *
+ * Not part of `RuntimeSdk` (the plan pins that surface) and not a constructor option (the plan pins
+ * those too) — it is this package's own internal wiring, exported for `test/spine/*` and for the
+ * lanes' own tests to reach a single seam without standing up the whole handle.
+ */
+export interface RuntimeSdkInternals {
+    official: OfficialAdapter;
+    barrier: HandoffBarrier;
+    decorator: MaterializedResumeDecorator;
+    /** The exact object every seam factory was handed — what a lane's real factory will receive. */
+    context: SeamContextWithDirectory;
+}
+/** Reaches the internals of a handle this package built. Returns undefined for anything else. */
+export declare function runtimeSdkInternals(sdk: RuntimeSdk): RuntimeSdkInternals | undefined;
+/**
+ * Builds the object forwarded to a peer's `query()`.
+ *
+ * THE COMMON CASE FORWARDS THE CALLER'S OWN OBJECT, by reference. "Passes through verbatim" is a
+ * property a test can only really check by identity, and a router that copied unconditionally would
+ * be quietly deciding which of `Options`' members it knows about — the exact drift D19b's "never a
+ * translation layer" rules out. A copy is made ONLY when a router-owned key is present, because that
+ * key must not reach an SDK that would not recognise it; every other member keeps its own value
+ * identity through the copy.
+ */
+export declare function forwardableOptions(options: RouterOptions, brand?: Partial<BrandProfile>): Options;
+/**
+ * Constructs the router. Throws `RuntimeSdkVersionError` on a version-matrix miss (D19a).
+ *
+ * THE MATRIX IS ASSERTED FIRST, before a single seam is built, so a refusal costs nothing and says
+ * only what it is about.
+ */
+export declare function createRuntimeSdk(opts: RuntimeSdkOptions): RuntimeSdk;

package/dist/seams/context.d.ts

@@ -0,0 +1,26 @@
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import type { RuntimeSdkPeers } from "../sdk.js";
+import type { RuntimeDirectory } from "./directory.js";
+import type { RuntimeDirectoryStore } from "./directory-store.js";
+import type { KeychainSeam } from "./keychain.js";
+/** Everything the directory itself needs. */
+export interface SeamContext {
+    peers: RuntimeSdkPeers;
+    /** WS-14 §12: the host's credential reads. Nothing in this package caches what it returns. */
+    keychain: KeychainSeam;
+    /**
+     * The RESOLVED profile (I2) — never `Partial`, never a literal, resolved exactly once at
+     * construction through the INJECTED peer's own `resolveBrand`. Every Winter-owned name any seam
+     * spells derives from this.
+     */
+    brand: BrandProfile;
+    directoryStore: RuntimeDirectoryStore;
+    /** WS-14 §5.1: `pathToClaudeCodeExecutable` — the host vendors it; tests point at node_modules. */
+    vendoredOfficialRuntime?: string;
+    /** Lane C: an explicit home for the shared store's lazy resolver (defaults to the peer's own resolution under `brand`). */
+    winterHome?: string;
+}
+/** What every OTHER seam needs: the same, plus the directory, which is built first. */
+export interface SeamContextWithDirectory extends SeamContext {
+    directory: RuntimeDirectory;
+}

package/dist/seams/directory-store.d.ts

@@ -0,0 +1,274 @@
+import type { RuntimeSelection } from "../selection/runtime-selection.js";
+import type { RemoteConfigPolicy } from "./official-adapter.js";
+import type { DeliveryOutcome, GlobalAgentMessage, ListedRuntimeObject, RuntimeAddress, RuntimeKind, RuntimeObjectKind, SerializedRuntimeAddress } from "./messaging-contract.js";
+/**
+ * WS-15 §6.1's `transport`, which `runtimeKind × objectKind` CANNOT recover (review r1, M1).
+ *
+ * An in-daemon Dispatch/Chat session (`winter-thread`) and a spawned Code session (`winter-session`)
+ * are both `winter-agent`/`session`, and that is precisely the split the Winter messaging adapter
+ * routes on: a direct in-process push versus the spawned session's `Query.messaging` wire facet.
+ */
+export type RuntimeTransport = "winter-thread" | "winter-session" | "claude-handle" | "claude-child";
+/**
+ * WS-15 §6.1's directory record: one addressable runtime object (a session or one of its children).
+ *
+ * `selection` is the object's OWN persisted runtime, never its parent's — R-7b-1's whole point, and
+ * what makes WS-13c §8 ("the child's own record is authoritative on resume") enforceable rather than
+ * aspirational. `generation` is WS-10 §12's monotonic counter, the thing a `toGeneration` on an
+ * envelope is checked against so a message addressed to a previous incarnation is refused rather
+ * than delivered to its successor.
+ */
+export interface RuntimeDirectoryEntry {
+    /** The canonical serialization — the key every other method takes. */
+    address: SerializedRuntimeAddress;
+    /** The structured form of `address`. Stored alongside so a reader never re-parses. */
+    parsed: RuntimeAddress;
+    runtimeKind: RuntimeKind;
+    objectKind: RuntimeObjectKind;
+    /** WS-15 §6.1's own field — see `RuntimeTransport`; NOT derivable from the two above. */
+    transport: RuntimeTransport;
+    /** The display name a `ListAgents` listing shows; absent when the object has never been named. */
+    displayName?: string;
+    /** WS-15 §6.1's `title` — the session's own title, when it has one. */
+    title?: string;
+    status: ListedRuntimeObject["status"];
+    /** `code` | `dispatch` | `chat` — an open string here because the mode vocabulary is the host's (WS-15 §2). */
+    mode: string;
+    cwd?: string;
+    /** WS-10 §12's incarnation counter. */
+    generation: number;
+    /** This object's own persisted runtime choice (R-7b-1 / WS-13c §8). */
+    selection: RuntimeSelection;
+    /** Present for a child; the canonical address of its parent session. */
+    parentAddress?: SerializedRuntimeAddress;
+    /** The backend (runtime-side) session id, absent while "starting". */
+    backendSessionId?: string;
+    /**
+     * WS-14 §6 rule 2: the `CLAUDE_CONFIG_DIR` OBSERVED in `SpawnOptions.env` — never the value that was
+     * configured — recorded before the process is returned, because "this is the only supported way to
+     * know the `claude-resume-<uuid>` staging root, since the default spawner exposes no post-cleanup
+     * lookup". Rule 5: cleared (set back to absent) only after verified cleanup, which is why it is a
+     * field with a lifecycle rather than a write-once one.
+     *
+     * WRITTEN BY Lane A's supervised spawn proxy, before it hands the process back. READ BY Lane B's
+     * `RuntimeDirectory.recover()` (WS-15 §6.4) and by Lane A's own cleanup reconciliation. Absent for
+     * every `winter-agent` object — it is the official branch's staging root, nobody else's.
+     */
+    configDir?: string;
+    /**
+     * WS-14 §9 / WS-15 §6.4 step 2: PID **plus process start identity**, never a bare PID — an OS
+     * recycles pids, so a bare one turns "is my child still alive?" into a coin flip that occasionally
+     * answers about somebody else's process.
+     *
+     * WRITTEN BY Lane A's spawn proxy alongside `configDir`. READ BY Lane B's `recover()` step 2, which
+     * marks previously live handles `"unavailable"` until process identity revalidates. Absent for
+     * in-daemon (`winter-thread`) objects, which have no child at all.
+     */
+    processIdentity?: {
+        pid: number;
+        startedAt: string;
+    };
+    /**
+     * R-7b-11: whether this session's child was allowed to fetch the runtime's REMOTE FEATURE
+     * CONFIGURATION. Absent (and for every `winter-agent` row) means the shipped default, `"deny"`.
+     *
+     * IT IS ON THE ROW BECAUSE THE SURFACE IS NOT DERIVABLE FROM THE VERSION. Two sessions on the same
+     * pinned artifact advertise different tool sets depending on this one answer, so a reader asking
+     * "what could this session do?" cannot answer it from `selection.engineVersion` alone. Written by
+     * the official adapter's record sink at launch, from `OfficialLaunchPlan.remoteConfig`.
+     */
+    remoteConfig?: RemoteConfigPolicy;
+    capabilities: ListedRuntimeObject["capabilities"];
+    /**
+     * ISO-8601. A DELIBERATE DEPARTURE from WS-15 §6.1's `updatedAt: number`: every other timestamp on
+     * this seam that a human ever reads is ISO (`RuntimeSelection.decidedAt`, the lease records below),
+     * and one record carrying epoch milliseconds while its neighbours carry ISO is the kind of
+     * inconsistency that produces a `new Date(isoString)` bug in a host months later. The epoch-ms
+     * spelling is kept where it is load-bearing for arithmetic — `HeldMessageRecord.heldAt/expiresAt`,
+     * which the mailbox's own expiry compares numerically, matching the runtime's mailbox exactly.
+     */
+    updatedAt: string;
+}
+/**
+ * Per-address delivery cursors (WS-15 §6.4's recovery, WS-17 row 11's "index.db rebuild preserves
+ * runtime mappings, backend IDs, cursors").
+ *
+ * A cursor is an OPAQUE string to this seam: what it points at is the adapter's business.
+ */
+export interface CursorStore {
+    get(address: SerializedRuntimeAddress): Promise<string | undefined>;
+    set(address: SerializedRuntimeAddress, cursor: string): Promise<void>;
+    remove(address: SerializedRuntimeAddress): Promise<void>;
+    /** Every cursor, for the restart sweep. */
+    all(): Promise<Record<SerializedRuntimeAddress, string>>;
+}
+/**
+ * One held message, as the store keeps it.
+ *
+ * The FULL envelope is stored, not a reference: WS-15 §6.4's restart recovery has to be able to
+ * deliver a message the process was holding when it died, and a record that only remembered an id
+ * would need the message to have been persisted somewhere else as well.
+ */
+export interface HeldMessageRecord {
+    messageId: string;
+    /** The canonical address the message is held FOR. */
+    receiver: SerializedRuntimeAddress;
+    reason: string;
+    /** WS-10 §13: an explicit hold persists; a default-class hold expires (5-minute dialog expiry). */
+    kind: "default" | "explicit";
+    /** Epoch milliseconds, matching the runtime's own mailbox. */
+    heldAt: number;
+    /** Present only for `kind: "default"`. */
+    expiresAt?: number;
+    message: GlobalAgentMessage;
+}
+/** The held-mailbox sink. Caps and expiry are the ROUTER's (see this file's header). */
+export interface MailboxStore {
+    listHeld(receiver: SerializedRuntimeAddress): Promise<HeldMessageRecord[]>;
+    hold(record: HeldMessageRecord): Promise<void>;
+    takeHeld(receiver: SerializedRuntimeAddress, messageId: string): Promise<HeldMessageRecord | undefined>;
+    clear(receiver: SerializedRuntimeAddress): Promise<void>;
+    /** Every receiver holding at least one message — the entry point of the restart sweep. */
+    receivers(): Promise<SerializedRuntimeAddress[]>;
+}
+/**
+ * ONE DELIVERY, from the moment its id exists to the moment its receipt does (WS-15 §6.2).
+ *
+ * The pipeline the router runs is explicit about what must be durable, and in which order: "allocate
+ * and **persist** the request/message ID **before address resolution** (so ambiguous/missing/
+ * unavailable outcomes are idempotent too) → **persist the envelope** and resolved target generation
+ * → … → **persist the adapter receipt**", so that "a retry returns the stored outcome instead of
+ * starting a second turn".
+ *
+ * `claimedBy` set with no `outcome` is the crash window: WS-15 §6.4 step 5 reconciles exactly those
+ * as `delivery_uncertain`, which is why they are two fields and not one status enum — the pair is the
+ * evidence, and a single "status" would let a writer describe a state it had not actually reached.
+ */
+export interface DeliveryRecord {
+    /** WS-10 §12: derived from (sender session, tool-call id), so a retry allocates the SAME id. */
+    messageId: string;
+    /** The envelope, persisted before resolution — a restart must be able to finish what it started. */
+    message: GlobalAgentMessage;
+    /** The target generation resolution picked. A later generation is a different incarnation. */
+    toGeneration: number;
+    /** Set at the atomic claim, before the adapter is invoked; a claim with no receipt is "uncertain". */
+    claimedBy?: RuntimeKind;
+    /** THE RECEIPT. A retry with the same `messageId` returns this instead of delivering again. */
+    outcome?: DeliveryOutcome;
+    /** ISO-8601. */
+    updatedAt: string;
+}
+/** The idempotency sink. Policy (dedupe windows, retry limits, loop guards) stays with the router. */
+export interface DeliveryRecordStore {
+    get(messageId: string): Promise<DeliveryRecord | undefined>;
+    put(record: DeliveryRecord): Promise<void>;
+    /** WS-15 §6.4 step 5's entry point: claimed, never receipted — every one is `delivery_uncertain`. */
+    claimedWithoutReceipt(): Promise<DeliveryRecord[]>;
+    /**
+     * Drop every RECEIPTED record older than this ISO stamp; returns how many went (Lane B fix r1, n3).
+     *
+     * WHY A DURABLE SINK NEEDS A REMOVAL DOOR AT ALL. This store is the only unbounded thing in the
+     * delivery path — the SDK subpath's own in-memory equivalents are explicitly capped
+     * (`rememberBounded`, `MAX_TRACKED_MESSAGE_IDS`) — and on the OFFICIAL branch the growth is worst,
+     * because a send with no tool-call id to derive from writes a record under `no-tool-call:<now>:
+     * <random>` that can never be looked up again. Without this door a long-lived host's directory
+     * store grows forever with rows that answer no question.
+     *
+     * A CLAIMED-BUT-UNRECEIPTED RECORD IS NEVER PRUNED, at any age. It is WS-15 §6.4 step 5's whole
+     * evidence: the pair (claimed, no receipt) is what makes a crashed delivery `delivery_uncertain`
+     * rather than invisible, and an "old enough" heuristic would silently convert the one state
+     * recovery must report into no state at all.
+     */
+    prune(receiptedBefore: string): Promise<number>;
+}
+/**
+ * A pending `notify_when_idle` (WS-10 §14, WS-15 §6.3).
+ *
+ * §6.3 is explicit that this one "survives restart only when durably stored with valid target
+ * identity/generation" — hence `targetGeneration`, without which a notice could fire for a different
+ * incarnation of the same address.
+ */
+export interface IdleSubscriptionRecord {
+    messageId: string;
+    /** Who gets the notice. */
+    subscriber: SerializedRuntimeAddress;
+    /** What is being watched. */
+    target: SerializedRuntimeAddress;
+    targetGeneration: number;
+    /** Epoch milliseconds — compared numerically against WS-10 §14's 12-hour expiry. */
+    createdAt: number;
+    expiresAt: number;
+}
+export interface IdleSubscriptionStore {
+    list(): Promise<IdleSubscriptionRecord[]>;
+    add(record: IdleSubscriptionRecord): Promise<void>;
+    remove(messageId: string): Promise<void>;
+}
+/**
+ * A display-name lease, live or released (WS-10 §11 rule 5, WS-15 §6.4 step 6).
+ *
+ * WHY THE HISTORY OUTLIVES THE ENTRY. Rule 5 says a STALE name is refused — not "not found". Telling
+ * those two apart after the object is gone requires remembering that the name once meant something,
+ * which `RuntimeDirectoryEntry.displayName` cannot do (it disappears with `remove()`). A released
+ * lease is that memory, and it is the only thing that lets the router answer "that name referred to a
+ * session that has since exited" instead of "no such agent".
+ */
+export interface NameLeaseRecord {
+    /** The display name, exactly as a model or user would write it. */
+    name: string;
+    address: SerializedRuntimeAddress;
+    /** The holder's generation at the time of the claim. */
+    generation: number;
+    /** ISO-8601. */
+    claimedAt: string;
+    /** ISO-8601; absent while the lease is held. */
+    releasedAt?: string;
+}
+export interface NameLeaseStore {
+    /** Every record for a name — a held one (at most one) plus released ones. Order is the caller's business. */
+    lookup(name: string): Promise<NameLeaseRecord[]>;
+    claim(record: NameLeaseRecord): Promise<void>;
+    release(name: string, address: SerializedRuntimeAddress, releasedAt: string): Promise<void>;
+    /** Every currently-held lease — WS-15 §6.4 step 6 sweeps these by generation. */
+    held(): Promise<NameLeaseRecord[]>;
+    /**
+     * Drop every RELEASED lease released before this ISO stamp; returns how many went (Lane B fix r1, n3).
+     *
+     * A HELD LEASE IS NEVER PRUNED, at any age — it is the live answer to "who owns this name".
+     *
+     * THE RETENTION IS A PRODUCT DECISION, not a cleanup interval: it is exactly how long a stale name
+     * keeps answering "that referred to something that has gone" instead of "no such agent" (WS-10 §11
+     * rule 5). Prune too eagerly and a model that addresses a session that exited an hour ago gets the
+     * refusal rule 5 exists to avoid; never prune and the memory of every name ever used is permanent.
+     */
+    prune(releasedBefore: string): Promise<number>;
+}
+/**
+ * R-7b-2's seam.
+ *
+ * The plan pins the first five members; `deliveries`, `subscriptions` and `names` were added in fix
+ * round 1 (review r1, I1) because three obligations the plan assigns Lane B — WS-15 §6.2's persisted
+ * id/envelope/claim/receipt, §6.3's restart-surviving idle subscriptions, and §6.4 step 6 / WS-10 §11
+ * rule 5's name leases — had no durable sink at all, here or in the SDK-side router core (whose
+ * outcome map and notification queue are bounded, explicitly non-durable, in-memory `Map`s). The
+ * router's store is the only durable place they can live.
+ */
+export interface RuntimeDirectoryStore {
+    load(): Promise<RuntimeDirectoryEntry[]>;
+    upsert(e: RuntimeDirectoryEntry): Promise<void>;
+    remove(address: SerializedRuntimeAddress): Promise<void>;
+    cursors: CursorStore;
+    mailboxes: MailboxStore;
+    deliveries: DeliveryRecordStore;
+    subscriptions: IdleSubscriptionStore;
+    names: NameLeaseStore;
+}
+/**
+ * The in-memory `RuntimeDirectoryStore` — the default when a host injects none, and the store every
+ * hermetic test uses.
+ *
+ * FULLY IMPLEMENTED, not a stub: it is the test default, so "the directory works" must be provable
+ * without a host. It touches no filesystem, no `~/.winter`, no keychain, and holds nothing across a
+ * process — which is also the honest statement of what a host gets if it never supplies one.
+ */
+export declare function createInMemoryRuntimeDirectoryStore(): RuntimeDirectoryStore;

package/dist/seams/directory.d.ts

@@ -0,0 +1,46 @@
+import type { RuntimeDirectoryEntry } from "./directory-store.js";
+import type { ListedRuntimeObject, RuntimeAddress, SerializedRuntimeAddress } from "./messaging-contract.js";
+export interface DirectoryResolutionContext {
+    /** Who is asking. Scopes "a stable child id beats a name" to the asker's own children. */
+    from: RuntimeAddress;
+}
+export type DirectoryResolution = {
+    kind: "resolved";
+    entry: RuntimeDirectoryEntry;
+} | {
+    kind: "ambiguous";
+    candidates: ListedRuntimeObject[];
+} | {
+    kind: "stale-name";
+    reason: string;
+    candidates: ListedRuntimeObject[];
+} | {
+    kind: "not-found";
+    reason: string;
+};
+/** WS-15 §6.4's seven-step restart recovery, reported step by step. */
+export interface RuntimeDirectoryRecoveryStep {
+    step: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    name: string;
+    outcome: string;
+}
+export interface RuntimeDirectoryRecovery {
+    steps: RuntimeDirectoryRecoveryStep[];
+    entriesLoaded: number;
+    /** Entries whose runtime object no longer exists and were marked accordingly (never deleted silently). */
+    staleMarked: number;
+    cursorsRestored: number;
+    heldMessagesFound: number;
+}
+/** WS-15 §6.1. Lane B implements; the spine pins the signature. */
+export interface RuntimeDirectory {
+    list(scope?: {
+        parent?: SerializedRuntimeAddress;
+    }): Promise<RuntimeDirectoryEntry[]>;
+    get(address: SerializedRuntimeAddress): Promise<RuntimeDirectoryEntry | undefined>;
+    record(entry: RuntimeDirectoryEntry): Promise<void>;
+    forget(address: SerializedRuntimeAddress): Promise<void>;
+    /** `to` is the raw model- or user-supplied target string (WS-10 §10.1 caps it at 300 chars, no newline, no `*`). */
+    resolve(to: string, context: DirectoryResolutionContext): Promise<DirectoryResolution>;
+    recover(): Promise<RuntimeDirectoryRecovery>;
+}

package/dist/seams/global-messaging.d.ts

@@ -0,0 +1,30 @@
+import type { DeliveryOutcome, GlobalAgentMessage, ListedRuntimeObject, PermissionClassLabel, RuntimeAddress, RuntimeKind, RuntimeMessagingAdapter } from "./messaging-contract.js";
+/** WS-10 §10.1's model-facing send, after the tool layer has validated `to` (≤300 chars, no newline, `"*"` forbidden). */
+export interface SendMessageRequest {
+    from: RuntimeAddress;
+    /** The raw target string as the model wrote it. Resolution is the directory's job, never the caller's. */
+    to: string;
+    body: string;
+    summary?: string;
+    notifyWhenIdle?: boolean;
+    /** The tool call this send came from — WS-10 §12 derives the message id from (sender, tool call). */
+    originToolCallId?: string;
+}
+/** WS-15 §6.2. Lane B implements; the spine pins the signature. */
+export interface GlobalMessaging {
+    /** WS-10 §10.2: what this sender can reach right now. Never enumerates exited transcripts on disk. */
+    listReachable(scope: {
+        from: RuntimeAddress;
+    }): Promise<ListedRuntimeObject[]>;
+    send(request: SendMessageRequest): Promise<DeliveryOutcome>;
+    deliver(message: GlobalAgentMessage): Promise<DeliveryOutcome>;
+    /** WS-10 §14's 12-hour idle subscription. */
+    notifyWhenIdle(target: RuntimeAddress, request: {
+        from: RuntimeAddress;
+        messageId: string;
+    }): Promise<DeliveryOutcome>;
+    /** WS-10 §13's inbound class for a given object, as the policy matrix reads it. */
+    senderPermissionClass(address: RuntimeAddress): Promise<PermissionClassLabel>;
+    /** One adapter per runtime kind; registering the same kind twice replaces it. */
+    registerAdapter(kind: RuntimeKind, adapter: RuntimeMessagingAdapter): void;
+}