@yanlinglabs/winter-runtime-sdk 0.0.1

package/dist/store/wiring.d.ts

@@ -0,0 +1,250 @@
+import type { BrandProfile, SessionKey, SessionStore, SessionStoreEntry, SessionSummaryEntry } from "@yanlinglabs/winter-agent-sdk";
+import { RuntimeSdkError } from "../errors.js";
+import type { RuntimeSdkPeers } from "../sdk.js";
+/**
+ * The concrete store's surface, as the router uses it.
+ *
+ * STRUCTURAL, not `InstanceType<typeof peers.winter.WinterCompatibilitySessionStore>`, for the same
+ * reason `seams/official-sdk-shapes.ts` types the official module structurally: the peer is INJECTED,
+ * so the router must describe what it needs rather than name a class it never imports. The four
+ * Winter-only members below are on the concrete class and deliberately NOT on the pinned
+ * `SessionStore` type (WS-03 §10 pins that at exactly six members) — the store's own comments say so.
+ */
+export interface CanonicalSessionStore extends SessionStore {
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    listSessions(projectKey: string): Promise<Array<{
+        sessionId: string;
+        mtime: number;
+    }>>;
+    listSessionSummaries(projectKey: string): Promise<SessionSummaryEntry[]>;
+    delete(key: SessionKey): Promise<void>;
+    listSubkeys(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<string[]>;
+    listProjectKeys(): Promise<string[]>;
+    readSessionSummary(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<SessionSummaryEntry | null>;
+    acquireSessionLease(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<void>;
+}
+/** The constructor the injected peer exports. */
+export type CanonicalSessionStoreConstructor = new (opts: {
+    winterHome: string;
+}) => CanonicalSessionStore;
+/** WS-14 §5.1: an options combination the shared store cannot be used with. */
+export declare class SharedStoreOptionsError extends RuntimeSdkError {
+    readonly option: "persistSession" | "enableFileCheckpointing" | "sessionStore";
+    constructor(args: {
+        option: "persistSession" | "enableFileCheckpointing" | "sessionStore";
+        reason: string;
+    });
+}
+/**
+ * WS-14 §5: "Blind `importSessionToStore()` after partial mirror failure is forbidden."
+ *
+ * A THROW AND NOT A WARNING. The import transports a whole local transcript into the canonical store;
+ * run after a PARTIAL mirror it re-imports entries that already landed and re-orders around the ones
+ * that did not, which is the one failure the canonical file cannot recover from by itself. The safe
+ * door is `reconcile.ts`'s suffix-only reconciliation, and this class names it.
+ */
+export declare class BlindStoreImportError extends RuntimeSdkError {
+    readonly key: Readonly<SessionKey>;
+    constructor(key: SessionKey, detail: string);
+}
+/** The injected Winter peer does not carry the concrete store (a peer built for a different purpose). */
+export declare class SharedStoreUnavailableError extends RuntimeSdkError {
+    constructor();
+}
+export interface MirrorPolicy {
+    /** §5's "~100 ms batches". Appends inside one window become ONE canonical append. */
+    batchWindowMs: number;
+    /** §5's "≤3 append attempts". */
+    maxAttempts: number;
+    /** §5's "short backoff" between attempts. */
+    backoffMs: number;
+    /**
+     * How long ONE attempt may take before it is abandoned.
+     *
+     * §5: "a timed-out append is **not** retried". The reason is not politeness — a timed-out append may
+     * still land, so a retry is the one action that can duplicate entries in an append-only file.
+     */
+    attemptTimeoutMs: number;
+}
+export declare const DEFAULT_MIRROR_POLICY: MirrorPolicy;
+export type TranscriptHealth = "ok" | "repair-required";
+/** What a failed mirror records. COUNTS AND A CAUSE — never entry content (WS-05 §13). */
+export interface MirrorErrorRecord {
+    projectKey: string;
+    sessionId: string;
+    subpath?: string;
+    /** How many entries were in the batch that failed. Never what they were. */
+    entryCount: number;
+    attempts: number;
+    cause: "append-failed" | "timed-out";
+    /** The failure's own message, from the store's typed error — never an entry. */
+    detail: string;
+    at: string;
+}
+export interface SessionMirrorHealth {
+    transcriptHealth: TranscriptHealth;
+    errors: readonly MirrorErrorRecord[];
+    /** Canonical appends this session has completed — the "~100 ms batches" observation. */
+    batchesCommitted: number;
+    /** `append()` calls received from a branch. Two inside one window commit as one batch. */
+    appendsReceived: number;
+}
+export interface SettleReport {
+    /** True when every pending batch reached a terminal state (committed or recorded as a mirror error). */
+    settled: boolean;
+    batchesCommitted: number;
+    errors: readonly MirrorErrorRecord[];
+    transcriptHealth: TranscriptHealth;
+}
+/** The identity that makes "one instance, one version" checkable rather than asserted. */
+export interface SharedStoreIdentity {
+    packageName: string;
+    /** The injected peer's own version identity — the version BOTH branches are therefore using. */
+    packageVersion: string;
+    /** Unique per `createSharedSessionStore` call, so "the same store" is provable by value. */
+    instanceId: string;
+    winterHome: string;
+}
+/** Options members WS-14 §5.1 rules on. Structural, so both branches' option objects fit. */
+export interface StoreBearingOptions {
+    sessionStore?: unknown;
+    persistSession?: boolean;
+    enableFileCheckpointing?: boolean;
+}
+export interface SharedSessionStore {
+    /** THE object handed to both branches as `Options.sessionStore`. */
+    readonly store: SessionStore;
+    /** The underlying concrete store, for the barrier's lease/summary doors. Never handed to a branch. */
+    readonly canonical: CanonicalSessionStore;
+    readonly identity: SharedStoreIdentity;
+    readonly policy: MirrorPolicy;
+    /** WS-05 §12 step 3's host-side pending barrier. No key = every session. */
+    settle(key?: SessionKey): Promise<SettleReport>;
+    health(key: SessionKey): SessionMirrorHealth;
+    /**
+     * Clears a session's `repair-required` flag. THE ONLY CALLER IS A COMPLETED RECONCILIATION
+     * (`reconcile.ts`) — the flag exists to block a handoff until the canonical store is reconciled, so
+     * anything else clearing it would be clearing the evidence rather than the cause.
+     */
+    markReconciled(key: SessionKey, detail: string): void;
+    /** Attaches the shared store to an options object, refusing §5.1's two combinations. */
+    attach<T extends StoreBearingOptions>(options: T): T & {
+        sessionStore: SessionStore;
+    };
+    /** WS-14 §5's blind-import ban, as a guard a host calls before `importSessionToStore()`. */
+    assertImportAllowed(key: SessionKey): void;
+    /** WS-13 §8.2's no-wash-back mechanism. Shared with the decorator and the reconciler. */
+    readonly decorations: DecorationRegistry;
+}
+/**
+ * The uuids of entries that exist ONLY in a materialized resume copy.
+ *
+ * WHY THIS EXISTS AT ALL. WS-13 §8.2's PREFERRED door bakes decorations into the copy the destination
+ * runtime reads, "the canonical file stays byte-pure". But the destination then WRITES its next turn
+ * with `parentUuid` pointing at whatever it read last — including a decoration — and mirrors that turn
+ * back through this store. Without a registry, the byte-pure canonical file would acquire either the
+ * decoration itself (via reconciliation's suffix append) or an entry whose parent is unreachable in it
+ * (WS-05 §12 step 5's own validation would then fail the NEXT handoff). Both are the wash-back the
+ * probe is about; this is the mechanism that makes the probe pass rather than a hope that it does.
+ *
+ * IN-MEMORY BY DESIGN. §8.2: "decorations are recomputed fresh at every leg spawn (never stale)". A
+ * copy outlives neither the generation that staged it nor the process that decorated it, so a durable
+ * ledger would only ever hold entries about copies that no longer exist.
+ */
+export interface DecorationRegistry {
+    /** Records an entry that lives only in the copy, with the parent the canonical chain should keep. */
+    record(key: SessionKey, decoration: {
+        uuid: string;
+        parentUuid: string | null;
+    }): void;
+    has(key: SessionKey, uuid: string): boolean;
+    list(key: SessionKey): readonly string[];
+    /** The parent a decoration stands in front of, resolving a chain of them. */
+    canonicalParentOf(key: SessionKey, uuid: string): string | null;
+    forget(key: SessionKey): void;
+}
+export declare function createDecorationRegistry(): DecorationRegistry;
+export interface StripDecorationsResult {
+    entries: SessionStoreEntry[];
+    dropped: number;
+    reparented: number;
+}
+/**
+ * Removes copy-only entries from a batch on its way into the canonical store, and re-links the chain.
+ *
+ * RE-PARENTING IS NOT OPTIONAL. Dropping a decoration whose child points at it would leave the child
+ * with an unreachable `parentUuid` — exactly what WS-05 §12 step 5 validates and refuses. The child's
+ * `parentUuid` becomes the decoration's own parent, which is the link the canonical file would have had
+ * if the decoration had never been staged. Nothing else about the entry is touched, and an entry with
+ * no decorated parent is returned by IDENTITY (never a copy), so a batch with no decorations in it is
+ * byte-identical to the one the branch handed us.
+ */
+export declare function stripDecorations(key: SessionKey, entries: readonly SessionStoreEntry[], registry: DecorationRegistry): StripDecorationsResult;
+/**
+ * WS-14 §5.1's two refusals, over any options object carrying a store.
+ *
+ * BOTH BRANCHES, ONE RULE. The Winter SDK's own `query()` refuses the same two combinations at
+ * construction (`packages/sdk/src/query.ts`), and Lane A's `assertOptionsInvariants` refuses them on
+ * the official template. This is the third site on purpose: it is the one that runs when the ROUTER
+ * attaches the store, i.e. before either branch exists, and it throws a TYPED class rather than the
+ * bare `Error` the SDK's constructor-time check throws.
+ */
+export declare function assertStoreCompatibleOptions(options: StoreBearingOptions): void;
+/**
+ * Asserts that every options object listed carries the SAME store object (WS-05 §6).
+ *
+ * BY IDENTITY, because that is the only check that means anything: two stores over one home are
+ * type-identical, version-identical, and still two writers.
+ */
+export declare function assertOneSharedStore(shared: SharedSessionStore, ...options: ReadonlyArray<{
+    sessionStore?: unknown;
+}>): void;
+export interface SharedSessionStoreInput {
+    peers: RuntimeSdkPeers;
+    winterHome: string;
+    policy?: Partial<MirrorPolicy>;
+    /** Injectable clock for the records' timestamps. */
+    now?: () => Date;
+    /** WS-13 §8.2's decoration registry. A fresh one per store unless a host shares one deliberately. */
+    decorations?: DecorationRegistry;
+}
+/**
+ * Builds the one store both branches share.
+ *
+ * THE CLASS COMES FROM THE INJECTED PEER, never from an import of this package's own: a host that
+ * vendored its own copy of the Winter SDK gets ITS store, ITS lease semantics and ITS typed errors —
+ * the same argument `createRuntimeSdk` already makes for `resolveBrand`/`InvalidBrandError`.
+ */
+export declare function createSharedSessionStore(input: SharedSessionStoreInput): SharedSessionStore;
+/**
+ * A shared store resolved on FIRST USE, from the injected peer's own `resolveWinterHome()`.
+ *
+ * WHY LAZY MATTERS, and it is not a micro-optimisation. The spine's wiring line is
+ * `stubHandoffBarrier(context)` becoming `createHandoffBarrier(context)`, called for EVERY
+ * `createRuntimeSdk` — including the ones in `test/spine/*`, whose fake peer exports five members and
+ * neither a store class nor `resolveWinterHome`. A factory that built its store eagerly would throw at
+ * construction for every host that never hands a session off, and would break every spine test the day
+ * it was wired in. Resolved on the first `plan()`/`execute()`, it costs nothing until a handoff exists,
+ * and a host that already has a store passes it and never reaches this at all.
+ */
+export declare function lazySharedSessionStore(input: {
+    peers: RuntimeSdkPeers;
+    winterHome?: string;
+    /**
+     * The RESOLVED profile. NOT optional in practice: `resolveWinterHome()` defaults to `WINTER_BRAND`,
+     * so a call without it would send a rebranded host's sessions to Winter's own home directory — the
+     * exact failure the brand sweep gate exists to catch, and did catch, on this line.
+     */
+    brand: Pick<BrandProfile, "envPrefix" | "homeDirName">;
+    policy?: Partial<MirrorPolicy>;
+}): () => SharedSessionStore;

package/dist/vendor-paths.d.ts

@@ -0,0 +1,21 @@
+/** The vendor's fixed staging prefix (WS-05 §9, WS-14 §1: disclosed, never faked, never rebranded). */
+export declare const RESUME_STAGING_PREFIX = "claude-resume-";
+/**
+ * `<base>/claude-resume-<uuid>` — the root a store-backed resume stages under.
+ *
+ * WS-05 §9: "Store-backed resume still stages under SDK-parent `os.tmpdir()/claude-resume-<uuid>`."
+ *
+ * EXPORTED FOR RECOGNITION AND FOR STAGING, NEVER FOR CONFIGURATION on the official branch: the
+ * vendor's wrapper builds its own path there and we never set it ("`Options.env`/spawn hook are too
+ * late" — WS-14 §2's controls table), so the only base a host can move is the SDK PARENT's process
+ * `TMPDIR`. Lane C's decorator, by contrast, stages a copy at a root it owns and passes `base`.
+ */
+export declare function resumeStagingRoot(uuid: string, base?: string): string;
+/**
+ * True when a path is a `claude-resume-<uuid>` staging root.
+ *
+ * BY BASENAME, NEVER BY SUBSTRING: `<tmp>/claude-resume-9/projects/key` is a file INSIDE a staging
+ * root, not the root, and a reconciler that confused the two would delete or import the wrong thing.
+ * The bare prefix with no uuid is not one either.
+ */
+export declare function isResumeStagingRoot(path: string): boolean;

package/dist/version-matrix.d.ts

@@ -0,0 +1,84 @@
+import type { RuntimeSdkPeers } from "./sdk.js";
+/**
+ * THE MATRIX. The plan pins this object verbatim.
+ *
+ * `winterAgentSdk` is a RANGE because the Winter SDK is this repository's sibling and moves with it;
+ * `claudeAgentSdk` is an EXACT pin because WS-02 §6.1 says declaration identity alone must not
+ * approve an upgrade — a new official version is a reviewed compatibility event (WS-17's drift gate),
+ * not a range that quietly widens.
+ */
+export declare const SUPPORTED: {
+    readonly winterAgentSdk: ">=0.0.2 <0.1.0";
+    readonly claudeAgentSdk: "0.3.250";
+};
+/**
+ * The Winter wire protocol versions this router is tested against (`PROTOCOL_VERSION` in the SDK's
+ * own `protocol/frames.ts`). Separate from `SUPPORTED` because the plan pins that object's shape and
+ * because these are two independent identities: a wrapper can be re-released without moving its wire.
+ */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["1.0"];
+/** Where a peer's package version came from. See this module's header. */
+export type PeerVersionSource = "peer-export" | "resolved-manifest";
+export interface PeerVersionIdentity {
+    /** The package name the identity was read for. */
+    packageName: string;
+    /** The version string that was matched against the matrix. */
+    packageVersion: string;
+    source: PeerVersionSource;
+    /** The matrix entry this peer satisfied. */
+    supported: string;
+}
+export interface VersionMatrixReport {
+    winterAgentSdk: PeerVersionIdentity & {
+        protocolVersion: string;
+    };
+    /** Absent when no official peer was injected — which is allowed (a Winter-only host). */
+    claudeAgentSdk?: PeerVersionIdentity;
+    /** The matrix the report was produced against, so a diagnostic never has to guess. */
+    supported: typeof SUPPORTED;
+    supportedProtocolVersions: readonly string[];
+    /** ISO-8601, so a persisted report says when it was taken. */
+    checkedAt: string;
+}
+interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    /** The `-alpha.1` tail, or "" for a release. */
+    prerelease: string;
+}
+/** Parses `X.Y.Z`, `vX.Y.Z`, `X.Y.Z-tag`, `X.Y.Z+build`. Returns undefined for anything else. */
+export declare function parseVersion(raw: string): ParsedVersion | undefined;
+/**
+ * Whether `version` satisfies `range`.
+ *
+ * Supported forms, and deliberately only these: a space-separated conjunction of `>=`/`>`/`<=`/`<`
+ * comparators, a caret (`^X.Y.Z`), and a bare or `=`-prefixed exact version. An UNRECOGNISED range
+ * throws rather than returning false — a matrix entry nobody can parse is a bug in the matrix, and
+ * silently refusing every peer would look like a peer problem.
+ */
+export declare function satisfiesRange(version: string, range: string): boolean;
+/** The export names a peer may use to publish its own package version, in probe order. */
+export declare const VERSION_EXPORT_NAMES: readonly ["SDK_VERSION", "VERSION", "PACKAGE_VERSION", "version"];
+/** Step 1: a version identity exported by the injected module namespace itself. */
+export declare function readExportedVersion(namespace: unknown): string | undefined;
+/**
+ * Step 2: the `version` of the copy of `packageName` THIS module can resolve.
+ *
+ * Walks up from the resolved entry file rather than resolving `<name>/package.json` directly,
+ * because a package whose `exports` map is closed to `"."` (the Winter SDK's is) does not expose its
+ * own manifest as a subpath. Every failure mode — no such package, a manifest that will not parse, a
+ * manifest with no `version` — returns `undefined`, which the caller turns into the loud refusal.
+ * Never throws: a missing OPTIONAL peer must not crash the matrix on its way to reporting itself.
+ */
+export declare function readResolvedManifestVersion(packageName: string): string | undefined;
+/**
+ * Reads each injected peer's version identity and refuses loudly on a miss.
+ *
+ * Three outcomes, and the third is the one worth naming: an ABSENT official peer is allowed. A
+ * Winter-only host injects `{ winter }` and never loads the official runtime (that is the whole
+ * point of the optional peer), so "no claude peer" is a valid, fully-supported configuration and the
+ * report simply omits the row.
+ */
+export declare function assertVersionMatrix(peers: RuntimeSdkPeers): VersionMatrixReport;
+export {};

package/docs/conformance-rows.md

@@ -0,0 +1,195 @@
+# `@yanlinglabs/winter-runtime-sdk` — conformance rows
+
+> GENERATED from `test/conformance/rows.test.ts`. Do not edit by hand — change the table there and
+> re-run `WINTER_ROWS_WRITE=1 bun test test/conformance/rows.test.ts`. Every citation below is
+> machine-verified by that test: the cited file is read and the cited test title searched for, so a
+> renamed test fails the suite rather than leaving this page claiming a proof that no longer exists.
+
+WS-17 §8's closing line is why this page exists: **no release may claim drop-in compatibility while a
+router-owned row is unproven.** Rows 6, 9, 10, 16 and 18 are excluded by WS-17 §8 itself.
+
+## WS-17 §8 — the router's proof rows
+
+| Row | Status | Owner | Obligation | Scope / note |
+| --- | --- | --- | --- | --- |
+| WS17-1 | **proven** | Lane B (the handlers the official branch's aliases reach), with Lane A's `toolAliases` | Real model-emitted `SendMessage` through the TS alias reaches `mcp__winter__send_message` with native args and returns the visible result. | PROVEN WHOLE-ROW IN THE FIX WAVE (item 14). Each lane's half was already green against a DOUBLE of the other — Lane A's alias test used a recording handler, Lane B's router tests used a scripted caller — and the row is the join. `test/joint/` drives one real 0.3.250 process through its own `toolAliases` into Lane B's real handler and router, and the delivered frame, the class, the summary and the typed outcome are read at the far end. The joint run also established what no report knew: the WS-10 §12 retry key survives the whole path, because the caller is bound with NO tool-use id and the message id still carries the model's own (item 15). |
+| WS17-2 | **proven** | Lane B (handlers), with Lane A's alias table | `ListAgents` aliasing; canonical MCP duplicate deferred/hidden visibility; behavior without Tool Search. | The visibility half is RECORDED, not asserted-as-wished: with no Tool Search active the pinned runtime advertises the native name AND the canonical twin, so `deferred` is this package's intent and the runtime's own decision is what the test writes down. Re-measured under the hermetic child env (F-1), where the advertised set is the artifact's own 21 names rather than 25 including three remotely-flagged tools. |
+| WS17-3 | **proven** | Lane A (aliases + deny floor, WS-14 §7) | `disallowedTools` + permission floor cover harness-internal/direct paths aliases miss. | The measurement behind it: denying only the built-in leaves the alias resolving and the handler RUNNING, because the deny check happens after alias resolution. `aliasDenyNames` is the door that stops a host tripping over it, and row 3 is why it exists. |
+| WS17-4 | **proven** | Lane A (spool isolation, WS-14 §1) with Lane B (delivery, hold/refuse, idle wake) | Two official sessions under the spool: isolated discovery, delivery, hold/refuse, idle wake, zero visibility into `~/.claude`. | Both halves are now measured against two REAL 0.3.250 processes over one shared directory (item 14) — run SEQUENTIALLY, each with its own spool, which is what the isolation assertion compares; not one lane's real runtime beside the other lane's double. The `idle wake` clause resolves to WS-10 §14's WHOLE-CALL REFUSAL on this branch — the pinned SDK's `Query` exposes no session-status surface, so an adapter without a reliable idle signal must refuse rather than subscribe. That is a measurement about the artifact, not a gap in the row. |
+| WS17-5 | **proven** | Lane A (parent-restart child restoration, WS-14 §15) with Lane B (the resume route) | Official parent resume after restart restores completed children for native SendMessage resume. | The joint half is a REAL `resume()` (round 2, NEW-B): generation one's `system/init` session id and its own spool are handed to `adapter.resume()`, the second generation reports the SAME backend session id and the same observed root, and a native SendMessage to a completed child is asserted `delivered`/`queued` with the frame arriving in the resumed parent's stream. The earlier version launched two fresh sessions and closed on `not.toBe("not_found")`, which `unavailable` and `held` also satisfy. |
+| WS17-7 | **proven** | Lane B (the messaging router, WS-15 §6.2–6.3 / WS-10 §11–§13) | Messaging: addressing, ambiguity/staleness, dedupe, queue bounds, TTL, retries, crash windows, loop prevention, reply routing, `notify_when_idle`. | Ten clauses, ten named proofs. The crash-window clause is the one worth reading twice: the envelope and the CLAIM are persisted before the adapter is invoked, so a crash between them is recoverable as `delivery_uncertain` rather than as silence. |
+| WS17-8 | **proven** (router-scoped — see the note) | Lane C (store wiring, WS-05 §6/§7) | Shared filesystem `SessionStore` + pinned dialect: Claude→Winter, Winter→Claude, and both round-trips at every advertised level. | SCOPED, and the scope is what this row's own tests cover: both legs are produced by the SHARED STORE over the pinned dialect, at every advertised level, over real `mkdtemp` homes. A Claude leg written by the PINNED RUNTIME is covered next door rather than here — `docs/probes/materialized-resume.md`'s probe (c) drives both round-trip orders with the real artifact producing every Claude leg, and as of round 2 it PASSES (its round-1 failure was two probe-side defects: a seed that never reached the canonical store, and a line-adjacency rule stricter than the dialect and than the barrier's own step 5). All four probes now pass measured, so `probe()` reports `preferred`; the SHIPPED default is still `fallback`, because the door follows a measurement a host takes on its own pin. No `agent-state` or `full-filesystem` compatibility claim rests on this row. |
+| WS17-11 | **proven** | Lane C (store wiring) | Delete/rebuild of the disposable `sessions/index.db` preserves runtime mappings, backend IDs, cursors. | Proven the strong way and the structural way: the data survives a delete/rebuild BECAUSE none of it lives in the index, and a source scan pins that the router never reads the index at all. |
+| WS17-12 | **proven** | Lane B (the inbound policy and the mailbox, WS-10 §13) | Documented message-size, 50-accepted/100-held queues, 5-minute dialog expiry, 12-hour idle subscription, permission-class behavior; inert `@` mentions retained. | The expiry clause carries one interim behaviour a host must know and the README states: the sweep is LAZY — a held message's receipt is rewritten to `refused` when something next addresses that receiver, not on a timer of its own. |
+| WS17-13 | **proven** (router-scoped — see the note) | the spine (the packing and source gates), with this file's lockfile-integrity check | No verbatim all-rights-reserved artifacts in the Winter distribution; ephemeral CI fetch only. | Scoped to the ROUTER's own distribution: the artifact exists only in gitignored `node_modules`, is pinned by lockfile integrity (the plan's Global Constraints), and is rejected by the pack scan if it ever reaches a tarball. WS-02 §6's checksum-verified ephemeral FETCH is the SDK repository's own harness gate and stays there. |
+| WS17-14 | **proven** | Lane A (builtin-path containment, WS-14 §8) | Native + aliased Agent/worktree, durable Cron, workflow, saved-approval, plan-mode, and arbitrary file/shell paths cannot create `CLAUDE.md`, `.claude/`, or `~/.claude/plans` under strict policy. | Two layers, and the scope is exact. PRE-HOC: the permission floor refuses any call whose arguments name a forbidden target — path fields (case-folded, NFKC), command text (un-normalized, quote-stripped), and the §8 writers with no path argument at all — installed by `launch()` itself on EVERY launch — merged ahead of the caller's own hooks and never replaced by one of them (the floor is recognised by IDENTITY: a hook merely stamped with the exported floor mark is not the floor, and a genuine floor built under a looser template policy does not stand in for the adapter's own) — and required by `assertOptionsInvariants` by that same identity, not merely offered by the options builder. POST-HOC: a sweep registered on PostToolUse, PostToolUseFailure and PostToolBatch snapshots the forbidden names under the session's cwd AND the child's HOME, to a bounded depth (6 by default), around every filesystem-touching call; it removes what APPEARED under its roots during the call, records a typed containment breach, and ends the turn. SCOPE, stated rather than implied: shell-escape and constructed-name spellings are caught POST-HOC by the sweep, never pre-hoc; the sweep sees the SYNCHRONOUSLY-VISIBLE effects of the call it brackets (a background write that lands later is caught opportunistically by the next swept call), and its diff is TIME-BASED rather than causal — under the child's HOME that means a vendor home created by something else during a long call is removed and attributed to that call, which is narrow (an existing one is in every baseline and is never touched) but is what the wording says; it does not look outside cwd and HOME, nor below its depth bound; and the TURN ends only for a call that SUCCEEDS — for a failing call the guarantee is that the artifact does not survive it. |
+| WS17-15 | **proven** (router-scoped — see the note) | Lane C (temp continuity and the barrier) with Lane A (the supervised proxy) | Canonical memory + the D18 temp layout, cross-engine temp continuity, vendor temp roots reported honestly, supervised pre-cleanup reconciliation, default-spawn `mirror_error` handoff refusal, entire-adapter projection, `$bunfs` extraction avoided or tested. | SCOPED: six of the row's seven clauses are proven, four of them against the pinned runtime. The seventh — `$bunfs` extraction avoided or tested — is NOT claimed here: it is a property of how a HOST packages this package (a single-file Bun executable extracting its own embedded runtime), and nothing in this repository builds one. A row that counted it would be counting somebody else's build. The `entire-adapter projection` clause is likewise the projector's (Phase 8, WS-15 §4), and what this row proves for it is the durable half — the roots and records a projector reads. |
+| WS17-17 | **proven** | Lane D | Two identical raw model IDs behind different providers keep distinct provider-qualified identity/credentials/continuation/resume routes. | The fixture mirrors the generated catalog, where `claude-opus-5` really is six rows behind six providers. |
+
+## Phase 7b rulings discharged (not WS-17 rows)
+
+| Ruling | Status | Owner | Obligation | Scope / note |
+| --- | --- | --- | --- | --- |
+| D13/D28 | **proven** | Lane D | The runtime-selection table: Claude OAuth → official always (D14-gated); a Claude-family model on a backend the official branch serves in Code mode → official; Claude through other endpoints and all Dispatch/Chat → Winter; never a raw model-ID substring; the persisted selection wins. | — |
+| D14 gate | **proven** | Lane D | The Claude OAuth ship gate is closed by default, and a closed gate refuses rather than falling back to the Winter runtime. | — |
+| R-7b-1 | **proven** | Lane D (the selection half; the delivery half is Lane B's) | A child runs on the runtime its OWN slot's family selects, independent of the parent's; the child's selection is persisted with the child, resume follows the child's record, and a cross-runtime pair talks only through the RuntimeDirectory. | — |
+| WS13c-SM1/2/3 | **proven** | Lane D (selection level; the `DeliveryOutcome` half is Lane B's) | A parent switching family leaves its child's record untouched (both directions), and a child whose provider credential is gone refuses with `child-provider-unavailable` while the parent's turn continues. | — |
+| R-7b-8 | **proven** | Lane D | The D29 probe: whether the pinned official runtime exposes an advisor server tool in an SDK session, and under which condition, measured against the pinned artifact through the loopback capture and recorded. | REWRITTEN IN THE FIX WAVE (whole-branch F-1). The first version's citations pointed at tests asserting that `settings.advisorModel` put an advisor on the wire; that was the pinned artifact PLUS its remote feature configuration, and it went red whenever the CDN fetch timed out. With the runtime's four traffic opt-outs set, no condition puts an advisor anywhere — it is a remotely-flagged capability, not a property of the pin. D29's split is unaffected either way (nothing client-side to alias under either condition). One labelled non-hermetic leg survives behind `WINTER_D29_ALLOW_REMOTE_CONFIG=1` and is evidence for nothing. The probe skips with a printed reason where the pinned runtime cannot start, so the citation is to the tests AND to the record they produce. |
+
+## Citations
+
+### WS17-1
+
+- `test/joint/rows-1-2.test.ts` — `row 1 — a model-emitted SendMessage is delivered by the REAL router, and the router's typed outcome is what the model sees`
+- `test/joint/rows-1-2.test.ts` — `row 1 — a refusal is rendered as a classified failure the model can act on, not as a crash`
+- `test/joint/rows-1-2.test.ts` — `the REVERSE direction — a peer's message reaches the live official session's own row, through the router`
+- `test/official/runtime-aliases.test.ts` — `row 1: a model-emitted `SendMessage` reaches the canonical handler with NATIVE args, and its result is what the model sees`
+- `test/messaging/handlers.test.ts` — `a retry with the SAME vendor tool-use id returns the stored outcome, not a second delivery`
+
+### WS17-2
+
+- `test/joint/rows-1-2.test.ts` — `row 2 — a model-emitted ListAgents renders the REAL directory, and both canonical twins are advertised`
+- `test/official/runtime-aliases.test.ts` — `row 2: `ListAgents` aliases the same way, and the advertised set records what 0.3.250 actually does`
+- `test/official/aliases-containment.test.ts` — `the canonical duplicates are DEFERRED rather than hidden — they stay addressable by name`
+
+### WS17-3
+
+- `test/official/runtime-aliases.test.ts` — `row 3: the paths the alias does not cover — the canonical name direct, and where a deny rule must be spelled`
+- `test/official/aliases-containment.test.ts` — `the floor is a PATH rule, so it covers tools no disposition anticipated`
+
+### WS17-4
+
+- `test/official/runtime-spool.test.ts` — `row 4: two sessions under ONE spool stay isolated, and neither can see the vendor home`
+- `test/messaging/official-pair.test.ts` — `DISCOVERY is isolated: each sees the other session and its OWN children, never the other's`
+- `test/messaging/official-pair.test.ts` — `DELIVERY between the two lands in the receiver's own handle, attributed to the sender`
+- `test/messaging/official-pair.test.ts` — `HOLD and REFUSE are the receiver's, and neither delivers anything`
+- `test/messaging/official-pair.test.ts` — `IDLE WAKE: an idle official session starts one turn (`delivered`), a running one queues`
+- `test/joint/rows-4-5.test.ts` — `two live official sessions get DIFFERENT config dirs, each under its own spool`
+- `test/joint/rows-4-5.test.ts` — `a model in one official session DISCOVERS and ADDRESSES the other, and the delivery lands in it`
+- `test/joint/rows-4-5.test.ts` — `a receiver whose permission class cannot be known is HELD, not delivered — fail-closed, with the real runtime as the sender`
+- `test/joint/rows-4-5.test.ts` — `notify_when_idle against an OFFICIAL target refuses the whole call — measured, because this branch has no idle signal`
+
+### WS17-5
+
+- `test/messaging/official-pair.test.ts` — `recovery keeps the completed children, and a native SendMessage to one routes through the resumed parent`
+- `test/messaging/official-pair.test.ts` — `before the parent is resumed, the same send is retryably unavailable rather than not-found`
+- `test/joint/rows-4-5.test.ts` — `generation two is a real `resume()` of generation one's backend session, and the completed children are addressable through it`
+
+### WS17-7
+
+- `test/messaging/directory.test.ts` — `rule 4 — ambiguity RETURNS CANDIDATES rather than choosing, and the candidates are directory rows`
+- `test/messaging/directory.test.ts` — `rule 5 — a name whose only holder is gone is STALE, not not-found (the lease outlives the row)`
+- `test/messaging/router.test.ts` — `a retry of the same (sender, tool-call) pair returns the STORED outcome and starts no second turn`
+- `test/messaging/router.test.ts` — `the dedupe survives a RESTART, because the id is derived rather than counted`
+- `test/messaging/router.test.ts` — `the envelope and its resolved generation are persisted, and the delivery is CLAIMED, before the adapter runs`
+- `test/messaging/router.test.ts` — `an adapter that THROWS is delivery_uncertain, and the record keeps the claim`
+- `test/messaging/router.test.ts` — `an identical rapid repeat is suppressed with a VISIBLE outcome, and allowed again after the window`
+- `test/messaging/router.test.ts` — `a reply chain is stopped at MAX_HOP_COUNT — the bound is machinery, not documentation`
+- `test/messaging/router.test.ts` — `the subscription SURVIVES A RESTART — a new router over the same store still fires it`
+- `test/messaging/recovery.test.ts` — `step 5 turns every claimed-but-unreceipted delivery into delivery_uncertain, and redelivers nothing`
+
+### WS17-8
+
+- `test/store/rows.test.ts` — `Claude -> Winter, Winter -> Claude and both round trips at level`
+- `test/store/rows.test.ts` — `the subagent level round-trips too: a subkey survives both directions`
+
+### WS17-11
+
+- `test/store/rows.test.ts` — `runtime mappings, backend ids and cursors all survive, because none of them live there`
+- `test/store/rows.test.ts` — `the router never reads the product index: its name appears nowhere in this lane's source`
+
+### WS17-12
+
+- `test/messaging/router.test.ts` — `a body over MAX_GLOBAL_MESSAGE_SIZE is refused before anything is resolved`
+- `test/messaging/policy.test.ts` — `a DELIVERED message (an idle receiver, one turn started) frees its slot; a QUEUED one does not`
+- `test/messaging/policy.test.ts` — `the held cap survives a RESTART — the in-memory box is rehydrated from the durable store`
+- `test/messaging/policy.test.ts` — `a DEFAULT-class hold expires after five minutes; an EXPLICIT hold never does`
+- `test/messaging/router.test.ts` — `a subscription past its 12-hour expiry fires nothing and is swept`
+- `test/messaging/policy.test.ts` — `prompts receiver x BYPASSES sender holds, visibly, with the envelope kept durably`
+- `test/messaging/policy.test.ts` — ``@` mentions and slash-command text survive the router's own rendering byte-identically`
+
+### WS17-13
+
+- `test/gates/release-gates.test.ts` — `nothing tracked is the pinned package, its bundle, or a vendored copy`
+- `test/gates/scripts.test.ts` — `an embedded Anthropic artifact is rejected, by directory name and by file name`
+- `test/gates/scripts.test.ts` — `rule 7: the OPTIONAL peer named in a REACHABLE declaration is rejected -- and only there`
+- `test/conformance/rows.test.ts` — `row 13's other half — the pinned artifact is fetched by integrity hash into a gitignored tree`
+
+### WS17-14
+
+- `test/official/runtime-containment.test.ts` — `the native writers: every §8 row is EXERCISED, and the tally says which containment stopped it`
+- `test/official/runtime-containment.test.ts` — `arbitrary file and shell paths: an approving broker does not lift the floor`
+- `test/official/runtime-containment.test.ts` — `review r2, NEW-3: a command that BUILDS the name is caught post-hoc — swept, reported, and the call blocked`
+- `test/official/runtime-containment.test.ts` — `review r3, NEW-9: a command whose side effect precedes a FAILURE is swept too`
+- `test/official/runtime-containment.test.ts` — `review r3, NEW-11: the saved-approval path, for real — the durable update is stripped and no vendor settings file appears`
+- `test/official/runtime-containment.test.ts` — `review r4, NEW-18 (a): a host hook stamped with the exported floor mark does not REPLACE the floor — the floor is recognised by identity`
+- `test/official/runtime-containment.test.ts` — `the whole session's writes stay inside the spool, the cwd and the product home`
+
+### WS17-15
+
+- `test/store/rows.test.ts` — `the temp home stabilizes in the vendor engine dir across a full round trip`
+- `test/store/rows.test.ts` — `the vendor temp roots are reported honestly, including the one a copy left behind`
+- `test/store/rows.test.ts` — `supervised PRE-CLEANUP reconciliation: the entries are in the store before the staging root is deleted`
+- `test/store/rows.test.ts` — `a DEFAULT-SPAWN session with a mirror error is refused, never reconciled by guesswork`
+- `test/official/runtime-spool.test.ts` — `row 15: the vendor temp root is what we configured PLUS the engine's own segment, reported honestly`
+- `test/official/runtime-spool.test.ts` — `§1 profile 2 + §6 rules 2/3: a store-backed resume is observed as a staging root, and reconciliation runs BEFORE cleanup`
+
+### WS17-17
+
+- `test/selection/row-17.test.ts` — `row 17 — the fixture really is one raw model id behind several providers`
+- `test/selection/row-17.test.ts` — `row 17 identity — two selections of the same raw id keep distinct provider-qualified identities`
+- `test/selection/row-17.test.ts` — `row 17 credentials — each row is admitted by ITS OWN provider's credential ref, never a sibling's`
+- `test/selection/row-17.test.ts` — `row 17 continuation — the same raw id routes to DIFFERENT runtimes depending on the provider`
+- `test/selection/row-17.test.ts` — `row 17 resume — a record on one provider never resumes onto its twin behind another provider`
+- `test/selection/row-17.test.ts` — `row 17 — two children on the same raw id under one parent stay two distinct records`
+
+### D13/D28
+
+- `test/selection/select-runtime.test.ts` — `D13 row 1 — a Claude OAuth credential routes to the official runtime, always`
+- `test/selection/select-runtime.test.ts` — `D13 row 2 — a Claude-family model on an Anthropic-protocol backend in Code mode routes to the official runtime`
+- `test/selection/select-runtime.test.ts` — `D13 row 2 — a Console OAuth bearer on the Anthropic-dialect backend routes to the official runtime`
+- `test/selection/select-runtime.test.ts` — `D13 row 2 — a cloud credential chain is a backend the official branch serves, dialect notwithstanding`
+- `test/selection/select-runtime.test.ts` — `officialServesBackend agrees with OFFICIAL_SERVED_AUTH_FAMILIES for every auth family`
+- `test/selection/select-runtime.test.ts` — `D13 row 3 — the same Claude model through a non-Anthropic-protocol endpoint routes to Winter`
+- `test/selection/select-runtime.test.ts` — `D13 row 3 — Dispatch and Chat run on Winter even on the Anthropic-protocol backend`
+- `test/selection/select-runtime.test.ts` — `D28 — a gpt-family slot routes to Winter even with an official peer present`
+- `test/selection/select-runtime.test.ts` — `no branch reads a raw model id — renaming every model id leaves the decision unchanged`
+- `test/selection/select-runtime.test.ts` — `the persisted selection wins and is returned by identity, never re-decided`
+- `test/selection/select-runtime.test.ts` — `a persisted selection that no longer matches a fresh decision is reported as handoff-required, not rewritten`
+
+### D14 gate
+
+- `test/selection/select-runtime.test.ts` — `the D14 ship gate ships closed — the shipped default flag refuses a Claude OAuth session`
+- `test/selection/select-runtime.test.ts` — `D13 row 1 — Claude OAuth with the D14 ship gate closed is refused, never downgraded to Winter`
+- `test/selection/select-runtime.test.ts` — `D13 row 1 — Claude OAuth outside Code mode is refused: Code-only even after D14 approval`
+- `test/selection/select-runtime.test.ts` — `D13 row 1 — Claude OAuth with no official peer is refused, because it never routes to Winter`
+
+### R-7b-1
+
+- `test/selection/child-runtime.test.ts` — `R-7b-1 — the same child under two different parents produces the identical record`
+- `test/selection/child-runtime.test.ts` — `R-7b-1 — a Claude-family child of a Winter parent runs on the official runtime`
+- `test/selection/child-runtime.test.ts` — `R-7b-1 — a gpt-family child of an official parent runs on the Winter runtime`
+- `test/selection/child-runtime.test.ts` — `R-7b-1 — a cross-runtime parent/child pair is flagged for the directory channel`
+- `test/selection/child-runtime.test.ts` — `WS-13c §8 — a resume never re-decides the runtime, even when the table would now differ`
+- `test/selection/child-runtime.test.ts` — `WS-13c §8 — a resume succeeds on a recorded row that is not its provider's first row`
+- `test/selection/child-runtime.test.ts` — `WS-13c §8 — a resume refuses when the recorded ROW is unservable though its provider still serves the model`
+- `test/selection/child-runtime.test.ts` — `WS-13c §8 — a resume refuses when the recorded row has moved into another family`
+
+### WS13c-SM1/2/3
+
+- `test/selection/child-runtime.test.ts` — `WS13c-SM1 — a gpt parent's sonnet child is unchanged when the parent switches to claude`
+- `test/selection/child-runtime.test.ts` — `WS13c-SM2 — a claude parent's gpt child is unchanged when the parent switches to gpt`
+- `test/selection/child-runtime.test.ts` — `WS13c-SM3 — a child whose credential is gone refuses with child-provider-unavailable and is not retryable`
+
+### R-7b-8
+
+- `test/selection/d29-advisor-probe.test.ts` — `the probe drove the PINNED artifact, over loopback only, and printed its inventories`
+- `test/selection/d29-advisor-probe.test.ts` — `D29 — no condition puts an advisor tool in the session's advertised tool inventory`
+- `test/selection/d29-advisor-probe.test.ts` — `D29 — configuring an advisor model puts NOTHING advisor-shaped on the wire (the pinned artifact, alone)`
+- `test/selection/d29-advisor-probe.test.ts` — `D29 — no advisor appears in ANY hermetic condition, on the wire or in the inventory`
+- `test/selection/d29-advisor-probe.test.ts` — `the remote-configuration leg, when it is explicitly enabled, shows what the CDN adds`
+- `docs/probes/d29-advisor.md` — `## 3. Verdict`
+
+## Still unproven
+
+None — every row above carries at least one machine-verified citation.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@yanlinglabs/winter-runtime-sdk",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "description": "One door over the Winter Agent SDK and the official Claude Agent SDK: runtime selection, the official-SDK adapter, the shared session store, the handoff barrier and the cross-runtime messaging router.",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanlingLabs/winter-runtime-sdk.git"
+  },
+  "homepage": "https://github.com/yanlingLabs/winter-runtime-sdk",
+  "bugs": {
+    "url": "https://github.com/yanlingLabs/winter-runtime-sdk/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs/conformance-rows.md"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "winter": {
+    "publish": {
+      "npm": true
+    }
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.250",
+    "@yanlinglabs/winter-agent-sdk": ">=0.0.2 <0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.250",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^26.4.0",
+    "@yanlinglabs/winter-agent-sdk": "^0.0.2",
+    "@yanlinglabs/winter-conformance": "^0.0.2",
+    "@yanlinglabs/winter-provider-conformance": "^0.0.2",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "build:packages": "bun run scripts/build-packages.ts",
+    "release:pack": "bun run scripts/release-pack.ts",
+    "smoke:installed": "bun run scripts/smoke-installed.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "test": "bun test"
+  }
+}