@yanlinglabs/winter-conformance 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yanlingLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# `@yanlinglabs/winter-conformance`
+
+Winter's SDK compatibility corpus: a trace normalizer, a set of committed golden traces, and the
+pinned-upstream ("official SDK") mechanics that back Winter's compatibility claim against
+`@anthropic-ai/claude-agent-sdk@0.3.250` (see [WS-02](../../../docs/superpowers/specs/winter/WS-02-repo-and-packaging.md)
+in the `winter-agent-sdk` repository for the full spec, if you have it checked out).
+
+This package is published to GitHub Packages under restricted access (`@yanlinglabs` scope). The
+registry is chosen by the release workflow, not by a committed pin — see
+[RELEASING.md](https://github.com/yanlingLabs/winter-agent-sdk/blob/main/RELEASING.md).
+
+## Install
+
+Published to **both** registries. This is one of the org's own test harnesses rather than something a
+consumer of the wrapper installs — and it is on public npm deliberately: the router package
+`@yanlinglabs/winter-runtime-sdk` lives in its own repository and needs these golden traces and this trace normalizer as a dev dependency, and
+reaching GitHub Packages from that repository's CI would mean a cross-repo `read:packages` token
+whose only purpose is fetching test fixtures.
+
+### From public npm (anyone)
+
+```sh
+npm install @yanlinglabs/winter-conformance
+```
+
+Nothing else is needed: the `@yanlinglabs` scope is public on npm.
+
+### From GitHub Packages (the `yanlingLabs` org)
+
+GitHub Packages needs the scope pointed at it and an authenticated read, even for a public package.
+In your project's `.npmrc`:
+
+```
+@yanlinglabs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+…with `GITHUB_TOKEN` in the environment — a personal access token carrying `read:packages`, never a
+literal in the file. Then `npm install @yanlinglabs/winter-conformance` as usual.
+
+**The published packages contain COMPILED OUTPUT ONLY.** Each tarball ships `dist/` — the bundled
+JavaScript a consumer imports and the `.d.ts` declarations their type-checker reads — plus its data
+files, `README.md` and `LICENSE`. It does **not** ship `src/`: the TypeScript sources live at
+<https://github.com/yanlingLabs/winter-agent-sdk>, which is where to read them, file an issue, or send
+a patch.
+
+## What it ships
+
+| Import | What it is |
+| --- | --- |
+| `@yanlinglabs/winter-conformance` | The full barrel: everything below, in one import. |
+| `@yanlinglabs/winter-conformance/trace` | `normalizeTrace`, `compareTraces`, and the `ConformanceTraceEntry` type — strips volatile fields (session ids, timestamps, durations, costs) from a captured SDK message trace and diffs two normalized traces. |
+| `@yanlinglabs/winter-conformance/official` | The pinned-upstream mechanics: `fetchAndVerifyUpstream` (checksum-verified ephemeral fetch of the pinned official wrapper tarball) and `runCapture` (the `RUN_OFFICIAL_CAPTURE=1`-gated differential-signal harness). |
+
+## Bun-only surface
+
+This package declares `engines.node` and every entry point **imports** cleanly under Node 18+ (the
+compiled emit under `dist/` is what a non-Bun runtime resolves, via each export's `default`
+condition; Bun resolves the `bun` condition and gets the TypeScript source unchanged). Importable is
+not the same as runnable on every path — one exported function needs the Bun runtime:
+
+| Function | Import | Needs | Why |
+| --- | --- | --- | --- |
+| `runCapture()` | `@yanlinglabs/winter-conformance`, `@yanlinglabs/winter-conformance/official` | `Bun.spawn`, `Bun.serve` | It installs the pinned official SDK into a throwaway npm prefix and drives it against loopback HTTP fakes. |
+
+Called anywhere else it throws `BunRequiredError` (exported from both of those barrels) as its FIRST
+action — before the pinned tarball is fetched and before any listener is bound — naming the function,
+the Bun API and what to do instead. Catch it by identity:
+
+```ts
+import { runCapture, BunRequiredError } from "@yanlinglabs/winter-conformance";
+
+try {
+  await runCapture();
+} catch (err) {
+  if (err instanceof BunRequiredError) { /* run the capture under Bun instead */ }
+  throw err;
+}
+```
+
+### `BunRequiredError` is THIS package's own class
+
+`@yanlinglabs/winter-provider-runtime` exports a class with the same name and shape, and the two are
+deliberately **not** the same type — the packages share no dependency, so there is no module either
+could import it from. **Catch the one you imported.** Within this package it is one type across every
+subpath: an error thrown by `./official`'s `runCapture` satisfies `instanceof BunRequiredError`
+imported from the main barrel, and vice versa, under Node as well as Bun. The same holds for
+`ChecksumMismatchError` and `OfficialCompatUnavailableError`, which are also exported from both
+entries (the compiled emit gives each export entry its own bundle, so each class carries a
+package-scoped `Symbol.for` brand to make that hold).
+
+Everything else here — the trace normalizer, the goldens and their loaders, `fetchAndVerifyUpstream`
+and the checksum helpers — is plain Node-compatible code. The goldens `runCapture` produces are
+ordinary JSON and are readable from Node whoever produced them.
+
+Goldens (`goldens/*.trace.json`) ship as data alongside the compiled `dist/` — load them with `loadGolden`,
+`listGoldens`, and `goldenPath` from the main barrel rather than reaching into the installed
+package's directory layout by hand.
+
+```ts
+import { normalizeTrace, compareTraces, loadGolden } from "@yanlinglabs/winter-conformance";
+
+const golden = loadGolden("plain-query.trace.json");
+const fresh = normalizeTrace(await traceMySession());
+const diffs = compareTraces(fresh, golden);
+```
+
+## What it does NOT ship
+
+Per WS-02 §6 and §9: no Anthropic-derived artifact of any kind (no upstream `.d.ts`, no `sdk.mjs`,
+no native binary, no extracted prompt text). `compat/anthropic/0.3.250/` — the derived declaration
+digests and independently-authored consumer fixtures this repository uses to prove compatibility —
+is excluded from every published tarball; only `dist/` and `goldens/` ship (see this package's
+`package.json` `files` field). The `runCapture()` harness under `./official` never writes a golden
+file or persists anything from a live capture run; it prints a report for a human to read.
+
+## Runtime notes
+
+`./trace` is plain, dependency-free TypeScript and is the one subpath this repository's own CI
+proves importable under both Node 18 and Bun (the `pack-smoke` job, WS-02 §9 Step 3). The top-level
+barrel and `./official` additionally pull in `./official/capture.ts`, which calls `Bun.spawn` (to
+install the pinned official SDK into a throwaway npm prefix) — only inside `runCapture()`'s own
+function body, never at module load, so importing the barrel itself never requires Bun; actually
+*calling* `runCapture()` does.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.

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/goldens.d.ts

@@ -0,0 +1,11 @@
+import type { ConformanceTraceEntry } from "./trace.js";
+/** Every committed golden's file name (e.g. "plain-query.trace.json"), sorted for a stable order. */
+export declare function listGoldens(): string[];
+/** Absolute path to a named golden file. Does not check existence -- loadGolden's own read does that. */
+export declare function goldenPath(name: string): string;
+/**
+ * Reads and parses a committed golden trace by file name (e.g. "plain-query.trace.json", one of
+ * `listGoldens()`'s entries). The returned array is already `normalizeTrace()`-shaped -- every
+ * committed golden is, by `differential.ts`'s own convention (trace.ts's header comment).
+ */
+export declare function loadGolden(name: string): ConformanceTraceEntry[];