@hop-top/xrr 0.1.0-alpha.4

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of Conduct
+
+xrr follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Summary
+
+- Be respectful and inclusive.
+- No harassment, discrimination, or personal attacks.
+- Critique ideas, not people.
+- Report issues: me@jadb.io
+
+Full text: https://www.contributor-covenant.org/version/2/1/code_of_conduct/

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to xrr
+
+## Quick start
+
+```
+git clone ...
+task test     # all 5 languages
+task lint     # all 5 linters
+```
+
+## Adding an adapter
+
+1. Implement `Adapter` interface in target language (4 methods: `id`, `fingerprint`,
+   `serialize`, `deserialize`) — use `go/adapters/exec/` as reference.
+2. Add conformance fixture: `spec/fixtures/<adapter>-happy/` with `manifest.yaml`,
+   `<adapter>-<fp>.req.yaml`, `<adapter>-<fp>.resp.yaml`.
+3. Run conformance in all ports — every port must pass new fixture without code change.
+4. Open PR; link to `spec/cassette-format-v1.md` and the relevant interface docs.
+
+## Porting to a new language
+
+See the [Porting Guide](README.md#porting-guide) in the root README.
+
+## Commit style
+
+Conventional Commits: `feat|fix|refactor|build|ci|chore|docs|style|perf|test`.
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IdeaCrafters Labs
+
+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,22 @@
+# xrr — TypeScript SDK
+
+> Auto-published from [poly-xrr](https://github.com/hop-top/poly-xrr).
+> Do not open issues or PRs here — contribute to poly-xrr instead.
+
+## Install
+
+```bash
+npm install @hop-top/xrr
+```
+
+## Usage
+
+```ts
+const sess = new Session({ cassette: "fixtures/my-test" });
+const resp = await sess.record("http-get-users", adapter);
+sess.close();
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| latest  | ✓         |
+
+## Reporting a vulnerability
+
+Email me@jadb.io. Do not open a public issue for security bugs.
+
+Response within 48 hours. Fix target: 14 days for critical, 90 days for others.

package/dist/src/adapters/exec.d.ts

@@ -0,0 +1,21 @@
+import type { Adapter } from "../xrr.js";
+export interface ExecRequest {
+    argv: string[];
+    stdin?: string;
+    env?: Record<string, string>;
+}
+export interface ExecResponse {
+    stdout: string;
+    stderr?: string;
+    exit_code: number;
+    duration_ms?: number;
+}
+export declare class ExecAdapter implements Adapter<ExecRequest, ExecResponse> {
+    readonly id = "exec";
+    fingerprint(req: ExecRequest): Promise<string>;
+    serializeReq(req: ExecRequest): unknown;
+    serializeResp(resp: ExecResponse): unknown;
+    deserializeReq(data: unknown): ExecRequest;
+    deserializeResp(data: unknown): ExecResponse;
+}
+//# sourceMappingURL=exec.d.ts.map

package/dist/src/adapters/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../../src/adapters/exec.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAUD,qBAAa,WAAY,YAAW,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC;IACpE,QAAQ,CAAC,EAAE,UAAU;IAEf,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAOpD,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO;IAIvC,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO;IAI1C,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW;IAI1C,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY;CAG7C"}

package/dist/src/adapters/exec.js

@@ -0,0 +1,29 @@
+/**
+ * exec adapter — fingerprints on argv + stdin.
+ */
+import { createHash } from "node:crypto";
+function sortedKeys(obj) {
+    return Object.fromEntries(Object.keys(obj)
+        .sort()
+        .map((k) => [k, obj[k]]));
+}
+export class ExecAdapter {
+    id = "exec";
+    async fingerprint(req) {
+        const canonical = JSON.stringify(sortedKeys({ argv: req.argv, stdin: req.stdin ?? "" }));
+        return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+    }
+    serializeReq(req) {
+        return req;
+    }
+    serializeResp(resp) {
+        return resp;
+    }
+    deserializeReq(data) {
+        return data;
+    }
+    deserializeResp(data) {
+        return data;
+    }
+}
+//# sourceMappingURL=exec.js.map

package/dist/src/adapters/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../../src/adapters/exec.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBzC,SAAS,UAAU,CAAC,GAA4B;IAC9C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SACb,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,WAAW;IACb,EAAE,GAAG,MAAM,CAAC;IAErB,KAAK,CAAC,WAAW,CAAC,GAAgB;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAC9B,UAAU,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CACvD,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,YAAY,CAAC,GAAgB;QAC3B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,aAAa,CAAC,IAAkB;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,IAAa;QAC1B,OAAO,IAAmB,CAAC;IAC7B,CAAC;IAED,eAAe,CAAC,IAAa;QAC3B,OAAO,IAAoB,CAAC;IAC9B,CAAC;CACF"}

package/dist/src/adapters/fs.d.ts

@@ -0,0 +1,28 @@
+import type { Adapter } from "../xrr.js";
+export type FsOp = "write" | "mkdir" | "remove" | "rename" | "chmod" | "chown" | "symlink" | "hardlink" | "truncate";
+export interface FsRequest {
+    op: FsOp;
+    path: string;
+    /** UTF-8 string per spec. Binary callers MUST base64-encode beforehand. */
+    data?: string;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    dest?: string;
+    size?: number;
+    flags?: number;
+    recursive?: boolean;
+}
+export interface FsResponse {
+    duration_ms?: number;
+    bytes_written?: number;
+}
+export declare class FsAdapter implements Adapter<FsRequest, FsResponse> {
+    readonly id = "fs";
+    fingerprint(req: FsRequest): Promise<string>;
+    serializeReq(req: FsRequest): unknown;
+    serializeResp(resp: FsResponse): unknown;
+    deserializeReq(data: unknown): FsRequest;
+    deserializeResp(data: unknown): FsResponse;
+}
+//# sourceMappingURL=fs.d.ts.map

package/dist/src/adapters/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/adapters/fs.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,MAAM,IAAI,GACZ,OAAO,GACP,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,OAAO,GACP,SAAS,GACT,UAAU,GACV,UAAU,CAAC;AAEf,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAUD,qBAAa,SAAU,YAAW,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,QAAQ;IAEb,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAmClD,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO;IAIrC,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAIxC,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS;IAIxC,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU;CAG3C"}

package/dist/src/adapters/fs.js

@@ -0,0 +1,76 @@
+/**
+ * fs adapter — fingerprints on op + path + presence-gated optional fields.
+ *
+ * Mirrors go/adapters/fs/fs.go. The fingerprint algorithm hashes a
+ * canonical JSON object (sorted keys) containing `op`, `path`, and
+ * each optional field only when "set" per the omit-on-zero rules
+ * documented in spec/cassette-format-v1.md.
+ *
+ * Field naming uses snake_case in the TS interface to match the
+ * YAML wire form used by every other port — js-yaml round-trips
+ * the field names verbatim, so what you see in code is what you
+ * see in the cassette.
+ *
+ * Path normalization: the TS adapter accepts paths verbatim. The
+ * Go adapter ships a PathNormalizer hook because Go is the typical
+ * record-side runtime; on replay-side (where TS is most useful),
+ * paths arrive already-normalized from the cassette. Adopters that
+ * need TS-side recording with normalization can pre-normalize at
+ * the caller layer before constructing the request.
+ */
+import { createHash } from "node:crypto";
+function sortedKeys(obj) {
+    return Object.fromEntries(Object.keys(obj)
+        .sort()
+        .map((k) => [k, obj[k]]));
+}
+export class FsAdapter {
+    id = "fs";
+    async fingerprint(req) {
+        const fields = {
+            op: req.op,
+            path: req.path,
+        };
+        if (req.data !== undefined && req.data !== "") {
+            fields.data_sha256 = createHash("sha256")
+                .update(req.data, "utf8")
+                .digest("hex");
+        }
+        if (req.mode !== undefined) {
+            fields.mode = req.mode;
+        }
+        if (req.uid !== undefined) {
+            fields.uid = req.uid;
+        }
+        if (req.gid !== undefined) {
+            fields.gid = req.gid;
+        }
+        if (req.dest !== undefined && req.dest !== "") {
+            fields.dest = req.dest;
+        }
+        if (req.size !== undefined) {
+            fields.size = req.size;
+        }
+        if (req.flags !== undefined && req.flags !== 0) {
+            fields.flags = req.flags;
+        }
+        if (req.recursive === true) {
+            fields.recursive = true;
+        }
+        const canonical = JSON.stringify(sortedKeys(fields));
+        return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+    }
+    serializeReq(req) {
+        return req;
+    }
+    serializeResp(resp) {
+        return resp;
+    }
+    deserializeReq(data) {
+        return data;
+    }
+    deserializeResp(data) {
+        return data;
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/src/adapters/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../src/adapters/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiCzC,SAAS,UAAU,CAAC,GAA4B;IAC9C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SACb,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,SAAS;IACX,EAAE,GAAG,IAAI,CAAC;IAEnB,KAAK,CAAC,WAAW,CAAC,GAAc;QAC9B,MAAM,MAAM,GAA4B;YACtC,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,IAAI,EAAE,GAAG,CAAC,IAAI;SACf,CAAC;QACF,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;YAC9C,MAAM,CAAC,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC;iBACtC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC;iBACxB,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;QACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;QACvB,CAAC;QACD,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;QACvB,CAAC;QACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;YAC9C,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACzB,CAAC;QACD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QAC3B,CAAC;QACD,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;QAC1B,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,YAAY,CAAC,GAAc;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,aAAa,CAAC,IAAgB;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,IAAa;QAC1B,OAAO,IAAiB,CAAC;IAC3B,CAAC;IAED,eAAe,CAAC,IAAa;QAC3B,OAAO,IAAkB,CAAC;IAC5B,CAAC;CACF"}

package/dist/src/adapters/http.d.ts

@@ -0,0 +1,21 @@
+import type { Adapter } from "../xrr.js";
+export interface HttpRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface HttpResponse {
+    status: number;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export declare class HttpAdapter implements Adapter<HttpRequest, HttpResponse> {
+    readonly id = "http";
+    fingerprint(req: HttpRequest): Promise<string>;
+    serializeReq(req: HttpRequest): unknown;
+    serializeResp(resp: HttpResponse): unknown;
+    deserializeReq(data: unknown): HttpRequest;
+    deserializeResp(data: unknown): HttpResponse;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/src/adapters/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/adapters/http.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAUD,qBAAa,WAAY,YAAW,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC;IACpE,QAAQ,CAAC,EAAE,UAAU;IAEf,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAapD,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO;IAIvC,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO;IAI1C,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW;IAI1C,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY;CAG7C"}

package/dist/src/adapters/http.js

@@ -0,0 +1,35 @@
+/**
+ * http adapter — fingerprints on method + path+query + sha256(body)[:8].
+ */
+import { createHash } from "node:crypto";
+function sortedKeys(obj) {
+    return Object.fromEntries(Object.keys(obj)
+        .sort()
+        .map((k) => [k, obj[k]]));
+}
+export class HttpAdapter {
+    id = "http";
+    async fingerprint(req) {
+        const u = new URL(req.url);
+        const pathQuery = u.search ? `${u.pathname}${u.search}` : u.pathname;
+        const bodyHash = createHash("sha256")
+            .update(req.body ?? "")
+            .digest("hex")
+            .slice(0, 8);
+        const canonical = JSON.stringify(sortedKeys({ body_hash: bodyHash, method: req.method, path: pathQuery }));
+        return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+    }
+    serializeReq(req) {
+        return req;
+    }
+    serializeResp(resp) {
+        return resp;
+    }
+    deserializeReq(data) {
+        return data;
+    }
+    deserializeResp(data) {
+        return data;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/adapters/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/adapters/http.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBzC,SAAS,UAAU,CAAC,GAA4B;IAC9C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SACb,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,WAAW;IACb,EAAE,GAAG,MAAM,CAAC;IAErB,KAAK,CAAC,WAAW,CAAC,GAAgB;QAChC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrE,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;aAClC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;aACtB,MAAM,CAAC,KAAK,CAAC;aACb,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACf,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAC9B,UAAU,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CACzE,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,YAAY,CAAC,GAAgB;QAC3B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,aAAa,CAAC,IAAkB;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,IAAa;QAC1B,OAAO,IAAmB,CAAC;IAC7B,CAAC;IAED,eAAe,CAAC,IAAa;QAC3B,OAAO,IAAoB,CAAC;IAC9B,CAAC;CACF"}

package/dist/src/adapters/redis.d.ts

@@ -0,0 +1,17 @@
+import type { Adapter } from "../xrr.js";
+export interface RedisRequest {
+    command: string;
+    args?: string[];
+}
+export interface RedisResponse {
+    result: unknown;
+}
+export declare class RedisAdapter implements Adapter<RedisRequest, RedisResponse> {
+    readonly id = "redis";
+    fingerprint(req: RedisRequest): Promise<string>;
+    serializeReq(req: RedisRequest): unknown;
+    serializeResp(resp: RedisResponse): unknown;
+    deserializeReq(data: unknown): RedisRequest;
+    deserializeResp(data: unknown): RedisResponse;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/src/adapters/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/adapters/redis.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,YAAa,YAAW,OAAO,CAAC,YAAY,EAAE,aAAa,CAAC;IACvE,QAAQ,CAAC,EAAE,WAAW;IAEhB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAMrD,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO;IAIxC,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAI3C,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY;IAI3C,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa;CAG9C"}

package/dist/src/adapters/redis.js

@@ -0,0 +1,25 @@
+/**
+ * redis adapter — fingerprints on command + args joined.
+ */
+import { createHash } from "node:crypto";
+export class RedisAdapter {
+    id = "redis";
+    async fingerprint(req) {
+        const parts = [req.command.toUpperCase(), ...(req.args ?? [])];
+        const canonical = JSON.stringify(parts.join(" "));
+        return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+    }
+    serializeReq(req) {
+        return req;
+    }
+    serializeResp(resp) {
+        return resp;
+    }
+    deserializeReq(data) {
+        return data;
+    }
+    deserializeResp(data) {
+        return data;
+    }
+}
+//# sourceMappingURL=redis.js.map

package/dist/src/adapters/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../../src/adapters/redis.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAYzC,MAAM,OAAO,YAAY;IACd,EAAE,GAAG,OAAO,CAAC;IAEtB,KAAK,CAAC,WAAW,CAAC,GAAiB;QACjC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,YAAY,CAAC,GAAiB;QAC5B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,aAAa,CAAC,IAAmB;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,IAAa;QAC1B,OAAO,IAAoB,CAAC;IAC9B,CAAC;IAED,eAAe,CAAC,IAAa;QAC3B,OAAO,IAAqB,CAAC;IAC/B,CAAC;CACF"}

package/dist/src/adapters/sql.d.ts

@@ -0,0 +1,18 @@
+import type { Adapter } from "../xrr.js";
+export interface SqlRequest {
+    query: string;
+    args?: unknown[];
+}
+export interface SqlResponse {
+    rows?: Record<string, unknown>[];
+    affected?: number;
+}
+export declare class SqlAdapter implements Adapter<SqlRequest, SqlResponse> {
+    readonly id = "sql";
+    fingerprint(req: SqlRequest): Promise<string>;
+    serializeReq(req: SqlRequest): unknown;
+    serializeResp(resp: SqlResponse): unknown;
+    deserializeReq(data: unknown): SqlRequest;
+    deserializeResp(data: unknown): SqlResponse;
+}
+//# sourceMappingURL=sql.d.ts.map

package/dist/src/adapters/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../../src/adapters/sql.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAcD,qBAAa,UAAW,YAAW,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC;IACjE,QAAQ,CAAC,EAAE,SAAS;IAEd,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAOnD,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IAItC,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO;IAIzC,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU;IAIzC,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW;CAG5C"}

package/dist/src/adapters/sql.js

@@ -0,0 +1,32 @@
+/**
+ * sql adapter — fingerprints on normalized query + args.
+ */
+import { createHash } from "node:crypto";
+function normalizeQuery(q) {
+    return q.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function sortedKeys(obj) {
+    return Object.fromEntries(Object.keys(obj)
+        .sort()
+        .map((k) => [k, obj[k]]));
+}
+export class SqlAdapter {
+    id = "sql";
+    async fingerprint(req) {
+        const canonical = JSON.stringify(sortedKeys({ args: req.args ?? null, query: normalizeQuery(req.query) }));
+        return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+    }
+    serializeReq(req) {
+        return req;
+    }
+    serializeResp(resp) {
+        return resp;
+    }
+    deserializeReq(data) {
+        return data;
+    }
+    deserializeResp(data) {
+        return data;
+    }
+}
+//# sourceMappingURL=sql.js.map

package/dist/src/adapters/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../../../src/adapters/sql.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC,SAAS,cAAc,CAAC,CAAS;IAC/B,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,UAAU,CAAC,GAA4B;IAC9C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SACb,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,UAAU;IACZ,EAAE,GAAG,KAAK,CAAC;IAEpB,KAAK,CAAC,WAAW,CAAC,GAAe;QAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAC9B,UAAU,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CACzE,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,YAAY,CAAC,GAAe;QAC1B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,aAAa,CAAC,IAAiB;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,IAAa;QAC1B,OAAO,IAAkB,CAAC;IAC5B,CAAC;IAED,eAAe,CAAC,IAAa;QAC3B,OAAO,IAAmB,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/cassette.d.ts

@@ -0,0 +1,13 @@
+import { type Cassette } from "./xrr.js";
+export declare class FileCassette implements Cassette {
+    private readonly dir;
+    constructor(dir: string);
+    save(adapterID: string, fingerprint: string, req: unknown, resp: unknown): Promise<void>;
+    private write;
+    load(adapterID: string, fingerprint: string): Promise<{
+        req: unknown;
+        resp: unknown;
+    }>;
+    private read;
+}
+//# sourceMappingURL=cassette.d.ts.map

package/dist/src/cassette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cassette.d.ts","sourceRoot":"","sources":["../../src/cassette.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAU1D,qBAAa,YAAa,YAAW,QAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,MAAM;IAElC,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC;YAMF,KAAK;IAmBb,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;YAM7B,IAAI;CAqBnB"}

package/dist/src/cassette.js

@@ -0,0 +1,54 @@
+/**
+ * FileCassette — reads/writes YAML envelope files.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { ErrCassetteMiss } from "./xrr.js";
+export class FileCassette {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async save(adapterID, fingerprint, req, resp) {
+        const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+        await this.write(adapterID, fingerprint, "req", now, req);
+        await this.write(adapterID, fingerprint, "resp", now, resp);
+    }
+    async write(adapterID, fingerprint, kind, recordedAt, payload) {
+        const env = {
+            xrr: "1",
+            adapter: adapterID,
+            fingerprint,
+            recorded_at: recordedAt,
+            payload,
+        };
+        const data = yaml.dump(env, { lineWidth: -1 });
+        const filePath = path.join(this.dir, `${adapterID}-${fingerprint}.${kind}.yaml`);
+        await fs.writeFile(filePath, data, "utf8");
+    }
+    async load(adapterID, fingerprint) {
+        const req = await this.read(adapterID, fingerprint, "req");
+        const resp = await this.read(adapterID, fingerprint, "resp");
+        return { req, resp };
+    }
+    async read(adapterID, fingerprint, kind) {
+        const filePath = path.join(this.dir, `${adapterID}-${fingerprint}.${kind}.yaml`);
+        let data;
+        try {
+            data = await fs.readFile(filePath, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw ErrCassetteMiss;
+            }
+            throw err;
+        }
+        const env = yaml.load(data);
+        if (!env || typeof env !== "object" || !("payload" in env)) {
+            throw new Error(`xrr: missing payload in ${kind}`);
+        }
+        return env.payload;
+    }
+}
+//# sourceMappingURL=cassette.js.map

package/dist/src/cassette.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cassette.js","sourceRoot":"","sources":["../../src/cassette.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAiB,MAAM,UAAU,CAAC;AAU1D,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C,KAAK,CAAC,IAAI,CACR,SAAiB,EACjB,WAAmB,EACnB,GAAY,EACZ,IAAa;QAEb,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QAC/D,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC1D,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAEO,KAAK,CAAC,KAAK,CACjB,SAAiB,EACjB,WAAmB,EACnB,IAAoB,EACpB,UAAkB,EAClB,OAAgB;QAEhB,MAAM,GAAG,GAAa;YACpB,GAAG,EAAE,GAAG;YACR,OAAO,EAAE,SAAS;YAClB,WAAW;YACX,WAAW,EAAE,UAAU;YACvB,OAAO;SACR,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,WAAW,IAAI,IAAI,OAAO,CAAC,CAAC;QACjF,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,IAAI,CACR,SAAiB,EACjB,WAAmB;QAEnB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QAC7D,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,IAAI,CAChB,SAAiB,EACjB,WAAmB,EACnB,IAAoB;QAEpB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,WAAW,IAAI,IAAI,OAAO,CAAC,CAAC;QACjF,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,MAAM,eAAe,CAAC;YACxB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAa,CAAC;QACxC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;CACF"}

package/dist/src/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Barrel export for @hop-top/xrr.
+ */
+export { ErrCassetteMiss } from "./xrr.js";
+export type { Adapter, Cassette, Mode, Session } from "./xrr.js";
+export { FileCassette } from "./cassette.js";
+export { FileSession } from "./session.js";
+export { ExecAdapter } from "./adapters/exec.js";
+export type { ExecRequest, ExecResponse } from "./adapters/exec.js";
+export { HttpAdapter } from "./adapters/http.js";
+export type { HttpRequest, HttpResponse } from "./adapters/http.js";
+export { RedisAdapter } from "./adapters/redis.js";
+export type { RedisRequest, RedisResponse } from "./adapters/redis.js";
+export { SqlAdapter } from "./adapters/sql.js";
+export type { SqlRequest, SqlResponse } from "./adapters/sql.js";
+export { FsAdapter } from "./adapters/fs.js";
+export type { FsOp, FsRequest, FsResponse } from "./adapters/fs.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * Barrel export for @hop-top/xrr.
+ */
+export { ErrCassetteMiss } from "./xrr.js";
+export { FileCassette } from "./cassette.js";
+export { FileSession } from "./session.js";
+export { ExecAdapter } from "./adapters/exec.js";
+export { HttpAdapter } from "./adapters/http.js";
+export { RedisAdapter } from "./adapters/redis.js";
+export { SqlAdapter } from "./adapters/sql.js";
+export { FsAdapter } from "./adapters/fs.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/session.d.ts

@@ -0,0 +1,13 @@
+/**
+ * FileSession — record/replay/passthrough session.
+ */
+import { type Adapter, type Cassette, type Mode, type Session } from "./xrr.js";
+export declare class FileSession implements Session {
+    private readonly mode;
+    private readonly cassette;
+    constructor(mode: Mode, cassette: Cassette);
+    record<Req, Resp>(adapter: Adapter<Req, Resp>, req: Req, do_: () => Promise<Resp>): Promise<Resp>;
+    private doRecord;
+    private doReplay;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/src/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAmB,KAAK,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAEjG,qBAAa,WAAY,YAAW,OAAO;IAEvC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,QAAQ;IAG/B,MAAM,CAAC,GAAG,EAAE,IAAI,EACpB,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,EAC3B,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC;YAeF,QAAQ;YAgBR,QAAQ;CAcvB"}

package/dist/src/session.js

@@ -0,0 +1,46 @@
+/**
+ * FileSession — record/replay/passthrough session.
+ */
+import { ErrCassetteMiss } from "./xrr.js";
+export class FileSession {
+    mode;
+    cassette;
+    constructor(mode, cassette) {
+        this.mode = mode;
+        this.cassette = cassette;
+    }
+    async record(adapter, req, do_) {
+        switch (this.mode) {
+            case "record":
+                return this.doRecord(adapter, req, do_);
+            case "replay":
+                return this.doReplay(adapter, req);
+            case "passthrough":
+                return do_();
+            default: {
+                const exhaustive = this.mode;
+                throw new Error(`xrr: unknown mode "${exhaustive}"`);
+            }
+        }
+    }
+    async doRecord(adapter, req, do_) {
+        const resp = await do_();
+        const fp = await adapter.fingerprint(req);
+        await this.cassette.save(adapter.id, fp, adapter.serializeReq(req), adapter.serializeResp(resp));
+        return resp;
+    }
+    async doReplay(adapter, req) {
+        const fp = await adapter.fingerprint(req);
+        let loaded;
+        try {
+            loaded = await this.cassette.load(adapter.id, fp);
+        }
+        catch (err) {
+            if (err === ErrCassetteMiss)
+                throw ErrCassetteMiss;
+            throw err;
+        }
+        return adapter.deserializeResp(loaded.resp);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/src/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAA+B,eAAe,EAA2B,MAAM,UAAU,CAAC;AAEjG,MAAM,OAAO,WAAW;IAEH;IACA;IAFnB,YACmB,IAAU,EACV,QAAkB;QADlB,SAAI,GAAJ,IAAI,CAAM;QACV,aAAQ,GAAR,QAAQ,CAAU;IAClC,CAAC;IAEJ,KAAK,CAAC,MAAM,CACV,OAA2B,EAC3B,GAAQ,EACR,GAAwB;QAExB,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;YAC1C,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACrC,KAAK,aAAa;gBAChB,OAAO,GAAG,EAAE,CAAC;YACf,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,IAAI,CAAC,IAAI,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,sBAAsB,UAAU,GAAG,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,QAAQ,CACpB,OAA2B,EAC3B,GAAQ,EACR,GAAwB;QAExB,MAAM,IAAI,GAAG,MAAM,GAAG,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CACtB,OAAO,CAAC,EAAE,EACV,EAAE,EACF,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,EACzB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAC5B,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,KAAK,CAAC,QAAQ,CACpB,OAA2B,EAC3B,GAAQ;QAER,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,MAAuC,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,KAAK,eAAe;gBAAE,MAAM,eAAe,CAAC;YACnD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC;CACF"}

package/dist/src/xrr.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Core xrr interfaces — mirrors Go reference implementation.
+ */
+export type Mode = "record" | "replay" | "passthrough";
+export declare const ErrCassetteMiss: Error;
+export interface Adapter<Req, Resp> {
+    id: string;
+    fingerprint(req: Req): Promise<string>;
+    serializeReq(req: Req): unknown;
+    serializeResp(resp: Resp): unknown;
+    deserializeReq(data: unknown): Req;
+    deserializeResp(data: unknown): Resp;
+}
+export interface Cassette {
+    save(adapterID: string, fingerprint: string, req: unknown, resp: unknown): Promise<void>;
+    load(adapterID: string, fingerprint: string): Promise<{
+        req: unknown;
+        resp: unknown;
+    }>;
+}
+export interface Session {
+    record<Req, Resp>(adapter: Adapter<Req, Resp>, req: Req, do_: () => Promise<Resp>): Promise<Resp>;
+}
+//# sourceMappingURL=xrr.d.ts.map

package/dist/src/xrr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrr.d.ts","sourceRoot":"","sources":["../../src/xrr.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEvD,eAAO,MAAM,eAAe,OAAkC,CAAC;AAE/D,MAAM,WAAW,OAAO,CAAC,GAAG,EAAE,IAAI;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC;IAChC,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IACnC,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC;IACnC,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxF;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,GAAG,EAAE,IAAI,EACd,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,EAC3B,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/src/xrr.js

@@ -0,0 +1,5 @@
+/**
+ * Core xrr interfaces — mirrors Go reference implementation.
+ */
+export const ErrCassetteMiss = new Error("xrr: cassette miss");
+//# sourceMappingURL=xrr.js.map

package/dist/src/xrr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrr.js","sourceRoot":"","sources":["../../src/xrr.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@hop-top/xrr",
+  "version": "0.1.0-alpha.4",
+  "type": "module",
+  "description": "Multi-channel interaction recorder/replayer",
+  "main": "./src/index.ts",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.1.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "LICENSE",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "README.md"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint src tests",
+    "ci:build": "tsc -p tsconfig.build.json"
+  }
+}

package/src/adapters/exec.ts

@@ -0,0 +1,53 @@
+/**
+ * exec adapter — fingerprints on argv + stdin.
+ */
+import { createHash } from "node:crypto";
+import type { Adapter } from "../xrr.js";
+
+export interface ExecRequest {
+  argv: string[];
+  stdin?: string;
+  env?: Record<string, string>;
+}
+
+export interface ExecResponse {
+  stdout: string;
+  stderr?: string;
+  exit_code: number;
+  duration_ms?: number;
+}
+
+function sortedKeys(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k]])
+  );
+}
+
+export class ExecAdapter implements Adapter<ExecRequest, ExecResponse> {
+  readonly id = "exec";
+
+  async fingerprint(req: ExecRequest): Promise<string> {
+    const canonical = JSON.stringify(
+      sortedKeys({ argv: req.argv, stdin: req.stdin ?? "" })
+    );
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+  }
+
+  serializeReq(req: ExecRequest): unknown {
+    return req;
+  }
+
+  serializeResp(resp: ExecResponse): unknown {
+    return resp;
+  }
+
+  deserializeReq(data: unknown): ExecRequest {
+    return data as ExecRequest;
+  }
+
+  deserializeResp(data: unknown): ExecResponse {
+    return data as ExecResponse;
+  }
+}

package/src/adapters/fs.ts

@@ -0,0 +1,115 @@
+/**
+ * fs adapter — fingerprints on op + path + presence-gated optional fields.
+ *
+ * Mirrors go/adapters/fs/fs.go. The fingerprint algorithm hashes a
+ * canonical JSON object (sorted keys) containing `op`, `path`, and
+ * each optional field only when "set" per the omit-on-zero rules
+ * documented in spec/cassette-format-v1.md.
+ *
+ * Field naming uses snake_case in the TS interface to match the
+ * YAML wire form used by every other port — js-yaml round-trips
+ * the field names verbatim, so what you see in code is what you
+ * see in the cassette.
+ *
+ * Path normalization: the TS adapter accepts paths verbatim. The
+ * Go adapter ships a PathNormalizer hook because Go is the typical
+ * record-side runtime; on replay-side (where TS is most useful),
+ * paths arrive already-normalized from the cassette. Adopters that
+ * need TS-side recording with normalization can pre-normalize at
+ * the caller layer before constructing the request.
+ */
+import { createHash } from "node:crypto";
+import type { Adapter } from "../xrr.js";
+
+export type FsOp =
+  | "write"
+  | "mkdir"
+  | "remove"
+  | "rename"
+  | "chmod"
+  | "chown"
+  | "symlink"
+  | "hardlink"
+  | "truncate";
+
+export interface FsRequest {
+  op: FsOp;
+  path: string;
+  /** UTF-8 string per spec. Binary callers MUST base64-encode beforehand. */
+  data?: string;
+  mode?: number;
+  uid?: number;
+  gid?: number;
+  dest?: string;
+  size?: number;
+  flags?: number;
+  recursive?: boolean;
+}
+
+export interface FsResponse {
+  duration_ms?: number;
+  bytes_written?: number;
+}
+
+function sortedKeys(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k]])
+  );
+}
+
+export class FsAdapter implements Adapter<FsRequest, FsResponse> {
+  readonly id = "fs";
+
+  async fingerprint(req: FsRequest): Promise<string> {
+    const fields: Record<string, unknown> = {
+      op: req.op,
+      path: req.path,
+    };
+    if (req.data !== undefined && req.data !== "") {
+      fields.data_sha256 = createHash("sha256")
+        .update(req.data, "utf8")
+        .digest("hex");
+    }
+    if (req.mode !== undefined) {
+      fields.mode = req.mode;
+    }
+    if (req.uid !== undefined) {
+      fields.uid = req.uid;
+    }
+    if (req.gid !== undefined) {
+      fields.gid = req.gid;
+    }
+    if (req.dest !== undefined && req.dest !== "") {
+      fields.dest = req.dest;
+    }
+    if (req.size !== undefined) {
+      fields.size = req.size;
+    }
+    if (req.flags !== undefined && req.flags !== 0) {
+      fields.flags = req.flags;
+    }
+    if (req.recursive === true) {
+      fields.recursive = true;
+    }
+    const canonical = JSON.stringify(sortedKeys(fields));
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+  }
+
+  serializeReq(req: FsRequest): unknown {
+    return req;
+  }
+
+  serializeResp(resp: FsResponse): unknown {
+    return resp;
+  }
+
+  deserializeReq(data: unknown): FsRequest {
+    return data as FsRequest;
+  }
+
+  deserializeResp(data: unknown): FsResponse {
+    return data as FsResponse;
+  }
+}

package/src/adapters/http.ts

@@ -0,0 +1,59 @@
+/**
+ * http adapter — fingerprints on method + path+query + sha256(body)[:8].
+ */
+import { createHash } from "node:crypto";
+import type { Adapter } from "../xrr.js";
+
+export interface HttpRequest {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+export interface HttpResponse {
+  status: number;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+function sortedKeys(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k]])
+  );
+}
+
+export class HttpAdapter implements Adapter<HttpRequest, HttpResponse> {
+  readonly id = "http";
+
+  async fingerprint(req: HttpRequest): Promise<string> {
+    const u = new URL(req.url);
+    const pathQuery = u.search ? `${u.pathname}${u.search}` : u.pathname;
+    const bodyHash = createHash("sha256")
+      .update(req.body ?? "")
+      .digest("hex")
+      .slice(0, 8);
+    const canonical = JSON.stringify(
+      sortedKeys({ body_hash: bodyHash, method: req.method, path: pathQuery })
+    );
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+  }
+
+  serializeReq(req: HttpRequest): unknown {
+    return req;
+  }
+
+  serializeResp(resp: HttpResponse): unknown {
+    return resp;
+  }
+
+  deserializeReq(data: unknown): HttpRequest {
+    return data as HttpRequest;
+  }
+
+  deserializeResp(data: unknown): HttpResponse {
+    return data as HttpResponse;
+  }
+}

package/src/adapters/redis.ts

@@ -0,0 +1,40 @@
+/**
+ * redis adapter — fingerprints on command + args joined.
+ */
+import { createHash } from "node:crypto";
+import type { Adapter } from "../xrr.js";
+
+export interface RedisRequest {
+  command: string;
+  args?: string[];
+}
+
+export interface RedisResponse {
+  result: unknown;
+}
+
+export class RedisAdapter implements Adapter<RedisRequest, RedisResponse> {
+  readonly id = "redis";
+
+  async fingerprint(req: RedisRequest): Promise<string> {
+    const parts = [req.command.toUpperCase(), ...(req.args ?? [])];
+    const canonical = JSON.stringify(parts.join(" "));
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+  }
+
+  serializeReq(req: RedisRequest): unknown {
+    return req;
+  }
+
+  serializeResp(resp: RedisResponse): unknown {
+    return resp;
+  }
+
+  deserializeReq(data: unknown): RedisRequest {
+    return data as RedisRequest;
+  }
+
+  deserializeResp(data: unknown): RedisResponse {
+    return data as RedisResponse;
+  }
+}

package/src/adapters/sql.ts

@@ -0,0 +1,54 @@
+/**
+ * sql adapter — fingerprints on normalized query + args.
+ */
+import { createHash } from "node:crypto";
+import type { Adapter } from "../xrr.js";
+
+export interface SqlRequest {
+  query: string;
+  args?: unknown[];
+}
+
+export interface SqlResponse {
+  rows?: Record<string, unknown>[];
+  affected?: number;
+}
+
+function normalizeQuery(q: string): string {
+  return q.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function sortedKeys(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.keys(obj)
+      .sort()
+      .map((k) => [k, obj[k]])
+  );
+}
+
+export class SqlAdapter implements Adapter<SqlRequest, SqlResponse> {
+  readonly id = "sql";
+
+  async fingerprint(req: SqlRequest): Promise<string> {
+    const canonical = JSON.stringify(
+      sortedKeys({ args: req.args ?? null, query: normalizeQuery(req.query) })
+    );
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+  }
+
+  serializeReq(req: SqlRequest): unknown {
+    return req;
+  }
+
+  serializeResp(resp: SqlResponse): unknown {
+    return resp;
+  }
+
+  deserializeReq(data: unknown): SqlRequest {
+    return data as SqlRequest;
+  }
+
+  deserializeResp(data: unknown): SqlResponse {
+    return data as SqlResponse;
+  }
+}

package/src/cassette.ts

@@ -0,0 +1,80 @@
+/**
+ * FileCassette — reads/writes YAML envelope files.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { ErrCassetteMiss, type Cassette } from "./xrr.js";
+
+interface Envelope {
+  xrr: string;
+  adapter: string;
+  fingerprint: string;
+  recorded_at: string;
+  payload: unknown;
+}
+
+export class FileCassette implements Cassette {
+  constructor(private readonly dir: string) {}
+
+  async save(
+    adapterID: string,
+    fingerprint: string,
+    req: unknown,
+    resp: unknown
+  ): Promise<void> {
+    const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    await this.write(adapterID, fingerprint, "req", now, req);
+    await this.write(adapterID, fingerprint, "resp", now, resp);
+  }
+
+  private async write(
+    adapterID: string,
+    fingerprint: string,
+    kind: "req" | "resp",
+    recordedAt: string,
+    payload: unknown
+  ): Promise<void> {
+    const env: Envelope = {
+      xrr: "1",
+      adapter: adapterID,
+      fingerprint,
+      recorded_at: recordedAt,
+      payload,
+    };
+    const data = yaml.dump(env, { lineWidth: -1 });
+    const filePath = path.join(this.dir, `${adapterID}-${fingerprint}.${kind}.yaml`);
+    await fs.writeFile(filePath, data, "utf8");
+  }
+
+  async load(
+    adapterID: string,
+    fingerprint: string
+  ): Promise<{ req: unknown; resp: unknown }> {
+    const req = await this.read(adapterID, fingerprint, "req");
+    const resp = await this.read(adapterID, fingerprint, "resp");
+    return { req, resp };
+  }
+
+  private async read(
+    adapterID: string,
+    fingerprint: string,
+    kind: "req" | "resp"
+  ): Promise<unknown> {
+    const filePath = path.join(this.dir, `${adapterID}-${fingerprint}.${kind}.yaml`);
+    let data: string;
+    try {
+      data = await fs.readFile(filePath, "utf8");
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw ErrCassetteMiss;
+      }
+      throw err;
+    }
+    const env = yaml.load(data) as Envelope;
+    if (!env || typeof env !== "object" || !("payload" in env)) {
+      throw new Error(`xrr: missing payload in ${kind}`);
+    }
+    return env.payload;
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Barrel export for @hop-top/xrr.
+ */
+export { ErrCassetteMiss } from "./xrr.js";
+export type { Adapter, Cassette, Mode, Session } from "./xrr.js";
+export { FileCassette } from "./cassette.js";
+export { FileSession } from "./session.js";
+export { ExecAdapter } from "./adapters/exec.js";
+export type { ExecRequest, ExecResponse } from "./adapters/exec.js";
+export { HttpAdapter } from "./adapters/http.js";
+export type { HttpRequest, HttpResponse } from "./adapters/http.js";
+export { RedisAdapter } from "./adapters/redis.js";
+export type { RedisRequest, RedisResponse } from "./adapters/redis.js";
+export { SqlAdapter } from "./adapters/sql.js";
+export type { SqlRequest, SqlResponse } from "./adapters/sql.js";
+export { FsAdapter } from "./adapters/fs.js";
+export type { FsOp, FsRequest, FsResponse } from "./adapters/fs.js";

package/src/session.ts

@@ -0,0 +1,61 @@
+/**
+ * FileSession — record/replay/passthrough session.
+ */
+import { type Adapter, type Cassette, ErrCassetteMiss, type Mode, type Session } from "./xrr.js";
+
+export class FileSession implements Session {
+  constructor(
+    private readonly mode: Mode,
+    private readonly cassette: Cassette
+  ) {}
+
+  async record<Req, Resp>(
+    adapter: Adapter<Req, Resp>,
+    req: Req,
+    do_: () => Promise<Resp>
+  ): Promise<Resp> {
+    switch (this.mode) {
+      case "record":
+        return this.doRecord(adapter, req, do_);
+      case "replay":
+        return this.doReplay(adapter, req);
+      case "passthrough":
+        return do_();
+      default: {
+        const exhaustive: never = this.mode;
+        throw new Error(`xrr: unknown mode "${exhaustive}"`);
+      }
+    }
+  }
+
+  private async doRecord<Req, Resp>(
+    adapter: Adapter<Req, Resp>,
+    req: Req,
+    do_: () => Promise<Resp>
+  ): Promise<Resp> {
+    const resp = await do_();
+    const fp = await adapter.fingerprint(req);
+    await this.cassette.save(
+      adapter.id,
+      fp,
+      adapter.serializeReq(req),
+      adapter.serializeResp(resp)
+    );
+    return resp;
+  }
+
+  private async doReplay<Req, Resp>(
+    adapter: Adapter<Req, Resp>,
+    req: Req
+  ): Promise<Resp> {
+    const fp = await adapter.fingerprint(req);
+    let loaded: { req: unknown; resp: unknown };
+    try {
+      loaded = await this.cassette.load(adapter.id, fp);
+    } catch (err) {
+      if (err === ErrCassetteMiss) throw ErrCassetteMiss;
+      throw err;
+    }
+    return adapter.deserializeResp(loaded.resp);
+  }
+}

package/src/xrr.ts

@@ -0,0 +1,29 @@
+/**
+ * Core xrr interfaces — mirrors Go reference implementation.
+ */
+
+export type Mode = "record" | "replay" | "passthrough";
+
+export const ErrCassetteMiss = new Error("xrr: cassette miss");
+
+export interface Adapter<Req, Resp> {
+  id: string;
+  fingerprint(req: Req): Promise<string>;
+  serializeReq(req: Req): unknown;
+  serializeResp(resp: Resp): unknown;
+  deserializeReq(data: unknown): Req;
+  deserializeResp(data: unknown): Resp;
+}
+
+export interface Cassette {
+  save(adapterID: string, fingerprint: string, req: unknown, resp: unknown): Promise<void>;
+  load(adapterID: string, fingerprint: string): Promise<{ req: unknown; resp: unknown }>;
+}
+
+export interface Session {
+  record<Req, Resp>(
+    adapter: Adapter<Req, Resp>,
+    req: Req,
+    do_: () => Promise<Resp>
+  ): Promise<Resp>;
+}