@pcguest/atb-sdk 0.1.2

package/README.md

@@ -0,0 +1,40 @@
+# @atb-dev/sdk — ATB TypeScript SDK
+
+The official TypeScript/JavaScript SDK for [ATB (Agent Trace Bundle)](https://github.com/pcguest/atb).
+
+## Installation
+
+```bash
+npm install @atb-dev/sdk
+# or
+pnpm add @atb-dev/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Bundle } from "@atb-dev/sdk";
+
+const bundle = new Bundle();
+
+bundle.append("dev.session", {
+  date: "2025-01-15",
+  featuresBuilt: ["hash chaining", "CLI init"],
+});
+
+bundle.append("decision", {
+  choice: "Go over Rust for CLI",
+  reason: "Solo founder velocity",
+});
+
+bundle.save(); // Writes to run.atb/bundle.atb
+
+// Later — reload and verify
+const loaded = Bundle.load();
+loaded.verify(); // Throws ATBVerificationError if tampered
+console.log(`Verified ${loaded.length} events — chain intact.`);
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,95 @@
+/**
+ * Core type definitions for the ATB TypeScript SDK.
+ */
+/** A single auditable event in an ATB bundle. */
+interface ATBEvent {
+    /** 1-based sequence number within the bundle. */
+    seq: number;
+    /** Hex-encoded SHA-256 hash of the preceding event (or GENESIS_HASH). */
+    prevHash: string;
+    /** Dot-namespaced event type identifier. */
+    type: string;
+    /** Arbitrary JSON-serialisable payload. */
+    data: unknown;
+}
+/** A single record in an ATB bundle file (event + its hash). */
+interface ATBRecord {
+    event: ATBEvent;
+    hash: string;
+}
+/** Options for creating a Bundle. */
+interface BundleOptions {
+    /** Path to the bundle file. Defaults to `run.atb/bundle.atb`. */
+    path?: string;
+}
+
+/**
+ * ATB Bundle — the primary interface for creating and managing ATB trace bundles.
+ */
+
+declare class ATBVerificationError extends Error {
+    readonly eventIndex: number;
+    readonly expectedHash: string;
+    readonly computedHash: string;
+    constructor(message: string, eventIndex: number, expectedHash: string, computedHash: string);
+}
+/**
+ * An in-memory ATB bundle.
+ *
+ * @example
+ * ```ts
+ * import { Bundle } from "@atb-dev/sdk";
+ *
+ * const bundle = new Bundle();
+ * bundle.append("dev.session", { date: "2025-01-15" });
+ * bundle.save();
+ *
+ * const loaded = Bundle.load();
+ * loaded.verify();
+ * ```
+ */
+declare class Bundle {
+    readonly records: ATBRecord[];
+    private readonly path;
+    constructor(options?: BundleOptions);
+    /** Append a new event to the bundle. */
+    append(type: string, data: unknown): ATBRecord;
+    /** Verify the integrity of the entire bundle. Throws on tampering. */
+    verify(): void;
+    /** Save the bundle to disk in NDJSON format. */
+    save(path?: string): void;
+    /** Load a bundle from disk. */
+    static load(path?: string): Bundle;
+    get length(): number;
+}
+
+/**
+ * ATB hash-chaining implementation for TypeScript/Node.js.
+ *
+ * Each event hash is computed as:
+ *   SHA256(prevHash + canonicalJSON(event))
+ */
+
+/** The sentinel previous-hash used for the first event in a bundle. */
+declare const GENESIS_HASH: string;
+/**
+ * Compute the SHA-256 hash for an event given the previous hash.
+ */
+declare function computeHash(event: ATBEvent, prevHash: string): string;
+/**
+ * Compute and assign hashes for a sequence of events.
+ * Mutates each event's `seq` and `prevHash` fields in-place.
+ *
+ * @returns Array of hex-encoded SHA-256 hashes, one per event.
+ */
+declare function chainEvents(events: ATBEvent[]): string[];
+
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS) implementation.
+ *
+ * Produces a deterministic, canonical UTF-8 string for any JSON value,
+ * suitable for use in cryptographic hash computation.
+ */
+declare function canonicalize(value: unknown): string;
+
+export { type ATBEvent, type ATBRecord, ATBVerificationError, Bundle, type BundleOptions, GENESIS_HASH, canonicalize, chainEvents, computeHash };

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Core type definitions for the ATB TypeScript SDK.
+ */
+/** A single auditable event in an ATB bundle. */
+interface ATBEvent {
+    /** 1-based sequence number within the bundle. */
+    seq: number;
+    /** Hex-encoded SHA-256 hash of the preceding event (or GENESIS_HASH). */
+    prevHash: string;
+    /** Dot-namespaced event type identifier. */
+    type: string;
+    /** Arbitrary JSON-serialisable payload. */
+    data: unknown;
+}
+/** A single record in an ATB bundle file (event + its hash). */
+interface ATBRecord {
+    event: ATBEvent;
+    hash: string;
+}
+/** Options for creating a Bundle. */
+interface BundleOptions {
+    /** Path to the bundle file. Defaults to `run.atb/bundle.atb`. */
+    path?: string;
+}
+
+/**
+ * ATB Bundle — the primary interface for creating and managing ATB trace bundles.
+ */
+
+declare class ATBVerificationError extends Error {
+    readonly eventIndex: number;
+    readonly expectedHash: string;
+    readonly computedHash: string;
+    constructor(message: string, eventIndex: number, expectedHash: string, computedHash: string);
+}
+/**
+ * An in-memory ATB bundle.
+ *
+ * @example
+ * ```ts
+ * import { Bundle } from "@atb-dev/sdk";
+ *
+ * const bundle = new Bundle();
+ * bundle.append("dev.session", { date: "2025-01-15" });
+ * bundle.save();
+ *
+ * const loaded = Bundle.load();
+ * loaded.verify();
+ * ```
+ */
+declare class Bundle {
+    readonly records: ATBRecord[];
+    private readonly path;
+    constructor(options?: BundleOptions);
+    /** Append a new event to the bundle. */
+    append(type: string, data: unknown): ATBRecord;
+    /** Verify the integrity of the entire bundle. Throws on tampering. */
+    verify(): void;
+    /** Save the bundle to disk in NDJSON format. */
+    save(path?: string): void;
+    /** Load a bundle from disk. */
+    static load(path?: string): Bundle;
+    get length(): number;
+}
+
+/**
+ * ATB hash-chaining implementation for TypeScript/Node.js.
+ *
+ * Each event hash is computed as:
+ *   SHA256(prevHash + canonicalJSON(event))
+ */
+
+/** The sentinel previous-hash used for the first event in a bundle. */
+declare const GENESIS_HASH: string;
+/**
+ * Compute the SHA-256 hash for an event given the previous hash.
+ */
+declare function computeHash(event: ATBEvent, prevHash: string): string;
+/**
+ * Compute and assign hashes for a sequence of events.
+ * Mutates each event's `seq` and `prevHash` fields in-place.
+ *
+ * @returns Array of hex-encoded SHA-256 hashes, one per event.
+ */
+declare function chainEvents(events: ATBEvent[]): string[];
+
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS) implementation.
+ *
+ * Produces a deterministic, canonical UTF-8 string for any JSON value,
+ * suitable for use in cryptographic hash computation.
+ */
+declare function canonicalize(value: unknown): string;
+
+export { type ATBEvent, type ATBRecord, ATBVerificationError, Bundle, type BundleOptions, GENESIS_HASH, canonicalize, chainEvents, computeHash };

package/dist/index.js

@@ -0,0 +1,194 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ATBVerificationError: () => ATBVerificationError,
+  Bundle: () => Bundle,
+  GENESIS_HASH: () => GENESIS_HASH,
+  canonicalize: () => canonicalize,
+  chainEvents: () => chainEvents,
+  computeHash: () => computeHash
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/bundle.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+
+// src/hash.ts
+var import_node_crypto = require("crypto");
+
+// src/canonicalize.ts
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return serializeNumber(value);
+  if (typeof value === "string") return serializeString(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const sortedKeys = Object.keys(obj).sort(utf16Compare);
+    const pairs = sortedKeys.map(
+      (k) => `${serializeString(k)}:${canonicalize(obj[k])}`
+    );
+    return "{" + pairs.join(",") + "}";
+  }
+  throw new TypeError(`canonicalize: unsupported type ${typeof value}`);
+}
+function serializeNumber(n) {
+  if (!isFinite(n)) throw new RangeError(`canonicalize: non-finite number ${n}`);
+  return String(n);
+}
+var ESCAPE_MAP = {
+  '"': '\\"',
+  "\\": "\\\\",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "	": "\\t"
+};
+function serializeString(s) {
+  let result = '"';
+  for (const ch of s) {
+    const code = ch.charCodeAt(0);
+    if (ch in ESCAPE_MAP) {
+      result += ESCAPE_MAP[ch];
+    } else if (code < 32) {
+      result += `\\u${code.toString(16).padStart(4, "0")}`;
+    } else {
+      result += ch;
+    }
+  }
+  return result + '"';
+}
+function utf16Compare(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const ca = a.charCodeAt(i) || -1;
+    const cb = b.charCodeAt(i) || -1;
+    if (ca !== cb) return ca - cb;
+  }
+  return 0;
+}
+
+// src/hash.ts
+var GENESIS_HASH = "0".repeat(64);
+function computeHash(event, prevHash) {
+  const canonical = canonicalize(event);
+  return (0, import_node_crypto.createHash)("sha256").update(prevHash, "utf8").update(canonical, "utf8").digest("hex");
+}
+function chainEvents(events) {
+  const hashes = [];
+  let prev = GENESIS_HASH;
+  for (let i = 0; i < events.length; i++) {
+    events[i].seq = i + 1;
+    events[i].prevHash = prev;
+    const h = computeHash(events[i], prev);
+    hashes.push(h);
+    prev = h;
+  }
+  return hashes;
+}
+
+// src/bundle.ts
+var DEFAULT_PATH = "run.atb/bundle.atb";
+var ATBVerificationError = class extends Error {
+  constructor(message, eventIndex, expectedHash, computedHash) {
+    super(message);
+    this.eventIndex = eventIndex;
+    this.expectedHash = expectedHash;
+    this.computedHash = computedHash;
+    this.name = "ATBVerificationError";
+  }
+};
+var Bundle = class _Bundle {
+  records = [];
+  path;
+  constructor(options = {}) {
+    this.path = options.path ?? DEFAULT_PATH;
+  }
+  /** Append a new event to the bundle. */
+  append(type, data) {
+    const prevHash = this.records.length > 0 ? this.records[this.records.length - 1].hash : GENESIS_HASH;
+    const event = {
+      seq: this.records.length + 1,
+      prevHash,
+      type,
+      data
+    };
+    const hash = computeHash(event, prevHash);
+    const record = { event, hash };
+    this.records.push(record);
+    return record;
+  }
+  /** Verify the integrity of the entire bundle. Throws on tampering. */
+  verify() {
+    let prev = GENESIS_HASH;
+    for (let i = 0; i < this.records.length; i++) {
+      const record = this.records[i];
+      const event = { ...record.event, seq: i + 1, prevHash: prev };
+      const computed = computeHash(event, prev);
+      if (computed !== record.hash) {
+        throw new ATBVerificationError(
+          `Tamper detected at event ${i + 1}: expected ${record.hash}, computed ${computed}`,
+          i,
+          record.hash,
+          computed
+        );
+      }
+      prev = computed;
+    }
+  }
+  /** Save the bundle to disk in NDJSON format. */
+  save(path) {
+    const target = path ?? this.path;
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(target), { recursive: true });
+    const lines = this.records.map((r) => JSON.stringify(r));
+    (0, import_node_fs.writeFileSync)(target, lines.join("\n") + "\n", "utf8");
+  }
+  /** Load a bundle from disk. */
+  static load(path) {
+    const target = path ?? DEFAULT_PATH;
+    const bundle = new _Bundle({ path: target });
+    const content = (0, import_node_fs.readFileSync)(target, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const record = JSON.parse(trimmed);
+      bundle.records.push(record);
+    }
+    return bundle;
+  }
+  get length() {
+    return this.records.length;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ATBVerificationError,
+  Bundle,
+  GENESIS_HASH,
+  canonicalize,
+  chainEvents,
+  computeHash
+});

package/dist/index.mjs

@@ -0,0 +1,162 @@
+// src/bundle.ts
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+// src/hash.ts
+import { createHash } from "crypto";
+
+// src/canonicalize.ts
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return serializeNumber(value);
+  if (typeof value === "string") return serializeString(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const sortedKeys = Object.keys(obj).sort(utf16Compare);
+    const pairs = sortedKeys.map(
+      (k) => `${serializeString(k)}:${canonicalize(obj[k])}`
+    );
+    return "{" + pairs.join(",") + "}";
+  }
+  throw new TypeError(`canonicalize: unsupported type ${typeof value}`);
+}
+function serializeNumber(n) {
+  if (!isFinite(n)) throw new RangeError(`canonicalize: non-finite number ${n}`);
+  return String(n);
+}
+var ESCAPE_MAP = {
+  '"': '\\"',
+  "\\": "\\\\",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "	": "\\t"
+};
+function serializeString(s) {
+  let result = '"';
+  for (const ch of s) {
+    const code = ch.charCodeAt(0);
+    if (ch in ESCAPE_MAP) {
+      result += ESCAPE_MAP[ch];
+    } else if (code < 32) {
+      result += `\\u${code.toString(16).padStart(4, "0")}`;
+    } else {
+      result += ch;
+    }
+  }
+  return result + '"';
+}
+function utf16Compare(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const ca = a.charCodeAt(i) || -1;
+    const cb = b.charCodeAt(i) || -1;
+    if (ca !== cb) return ca - cb;
+  }
+  return 0;
+}
+
+// src/hash.ts
+var GENESIS_HASH = "0".repeat(64);
+function computeHash(event, prevHash) {
+  const canonical = canonicalize(event);
+  return createHash("sha256").update(prevHash, "utf8").update(canonical, "utf8").digest("hex");
+}
+function chainEvents(events) {
+  const hashes = [];
+  let prev = GENESIS_HASH;
+  for (let i = 0; i < events.length; i++) {
+    events[i].seq = i + 1;
+    events[i].prevHash = prev;
+    const h = computeHash(events[i], prev);
+    hashes.push(h);
+    prev = h;
+  }
+  return hashes;
+}
+
+// src/bundle.ts
+var DEFAULT_PATH = "run.atb/bundle.atb";
+var ATBVerificationError = class extends Error {
+  constructor(message, eventIndex, expectedHash, computedHash) {
+    super(message);
+    this.eventIndex = eventIndex;
+    this.expectedHash = expectedHash;
+    this.computedHash = computedHash;
+    this.name = "ATBVerificationError";
+  }
+};
+var Bundle = class _Bundle {
+  records = [];
+  path;
+  constructor(options = {}) {
+    this.path = options.path ?? DEFAULT_PATH;
+  }
+  /** Append a new event to the bundle. */
+  append(type, data) {
+    const prevHash = this.records.length > 0 ? this.records[this.records.length - 1].hash : GENESIS_HASH;
+    const event = {
+      seq: this.records.length + 1,
+      prevHash,
+      type,
+      data
+    };
+    const hash = computeHash(event, prevHash);
+    const record = { event, hash };
+    this.records.push(record);
+    return record;
+  }
+  /** Verify the integrity of the entire bundle. Throws on tampering. */
+  verify() {
+    let prev = GENESIS_HASH;
+    for (let i = 0; i < this.records.length; i++) {
+      const record = this.records[i];
+      const event = { ...record.event, seq: i + 1, prevHash: prev };
+      const computed = computeHash(event, prev);
+      if (computed !== record.hash) {
+        throw new ATBVerificationError(
+          `Tamper detected at event ${i + 1}: expected ${record.hash}, computed ${computed}`,
+          i,
+          record.hash,
+          computed
+        );
+      }
+      prev = computed;
+    }
+  }
+  /** Save the bundle to disk in NDJSON format. */
+  save(path) {
+    const target = path ?? this.path;
+    mkdirSync(dirname(target), { recursive: true });
+    const lines = this.records.map((r) => JSON.stringify(r));
+    writeFileSync(target, lines.join("\n") + "\n", "utf8");
+  }
+  /** Load a bundle from disk. */
+  static load(path) {
+    const target = path ?? DEFAULT_PATH;
+    const bundle = new _Bundle({ path: target });
+    const content = readFileSync(target, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const record = JSON.parse(trimmed);
+      bundle.records.push(record);
+    }
+    return bundle;
+  }
+  get length() {
+    return this.records.length;
+  }
+};
+export {
+  ATBVerificationError,
+  Bundle,
+  GENESIS_HASH,
+  canonicalize,
+  chainEvents,
+  computeHash
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pcguest/atb-sdk",
+  "version": "0.1.2",
+  "description": "ATB (Agent Trace Bundle) TypeScript SDK — tamper-evident audit trails for AI agent workflows",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "audit",
+    "ai",
+    "agents",
+    "tracing",
+    "observability",
+    "atb"
+  ],
+  "author": "Paddy Guest <patrickcguest@proton.me>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pcguest/atb.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://atb.dev",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,111 @@
+/**
+ * ATB Bundle — the primary interface for creating and managing ATB trace bundles.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { GENESIS_HASH, computeHash } from "./hash.js";
+import type { ATBEvent, ATBRecord, BundleOptions } from "./types.js";
+
+const DEFAULT_PATH = "run.atb/bundle.atb";
+
+export class ATBVerificationError extends Error {
+  constructor(
+    message: string,
+    public readonly eventIndex: number,
+    public readonly expectedHash: string,
+    public readonly computedHash: string
+  ) {
+    super(message);
+    this.name = "ATBVerificationError";
+  }
+}
+
+/**
+ * An in-memory ATB bundle.
+ *
+ * @example
+ * ```ts
+ * import { Bundle } from "@atb-dev/sdk";
+ *
+ * const bundle = new Bundle();
+ * bundle.append("dev.session", { date: "2025-01-15" });
+ * bundle.save();
+ *
+ * const loaded = Bundle.load();
+ * loaded.verify();
+ * ```
+ */
+export class Bundle {
+  readonly records: ATBRecord[] = [];
+  private readonly path: string;
+
+  constructor(options: BundleOptions = {}) {
+    this.path = options.path ?? DEFAULT_PATH;
+  }
+
+  /** Append a new event to the bundle. */
+  append(type: string, data: unknown): ATBRecord {
+    const prevHash =
+      this.records.length > 0
+        ? this.records[this.records.length - 1].hash
+        : GENESIS_HASH;
+
+    const event: ATBEvent = {
+      seq: this.records.length + 1,
+      prevHash,
+      type,
+      data,
+    };
+
+    const hash = computeHash(event, prevHash);
+    const record: ATBRecord = { event, hash };
+    this.records.push(record);
+    return record;
+  }
+
+  /** Verify the integrity of the entire bundle. Throws on tampering. */
+  verify(): void {
+    let prev = GENESIS_HASH;
+    for (let i = 0; i < this.records.length; i++) {
+      const record = this.records[i];
+      const event = { ...record.event, seq: i + 1, prevHash: prev };
+      const computed = computeHash(event, prev);
+      if (computed !== record.hash) {
+        throw new ATBVerificationError(
+          `Tamper detected at event ${i + 1}: expected ${record.hash}, computed ${computed}`,
+          i,
+          record.hash,
+          computed
+        );
+      }
+      prev = computed;
+    }
+  }
+
+  /** Save the bundle to disk in NDJSON format. */
+  save(path?: string): void {
+    const target = path ?? this.path;
+    mkdirSync(dirname(target), { recursive: true });
+    const lines = this.records.map((r) => JSON.stringify(r));
+    writeFileSync(target, lines.join("\n") + "\n", "utf8");
+  }
+
+  /** Load a bundle from disk. */
+  static load(path?: string): Bundle {
+    const target = path ?? DEFAULT_PATH;
+    const bundle = new Bundle({ path: target });
+    const content = readFileSync(target, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const record = JSON.parse(trimmed) as ATBRecord;
+      bundle.records.push(record);
+    }
+    return bundle;
+  }
+
+  get length(): number {
+    return this.records.length;
+  }
+}

package/src/canonicalize.ts

@@ -0,0 +1,66 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS) implementation.
+ *
+ * Produces a deterministic, canonical UTF-8 string for any JSON value,
+ * suitable for use in cryptographic hash computation.
+ */
+
+export function canonicalize(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return serializeNumber(value);
+  if (typeof value === "string") return serializeString(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    // RFC 8785 §3.2.3 — sort keys by UTF-16 code unit sequence.
+    const sortedKeys = Object.keys(obj).sort(utf16Compare);
+    const pairs = sortedKeys.map(
+      (k) => `${serializeString(k)}:${canonicalize(obj[k])}`
+    );
+    return "{" + pairs.join(",") + "}";
+  }
+  throw new TypeError(`canonicalize: unsupported type ${typeof value}`);
+}
+
+function serializeNumber(n: number): string {
+  if (!isFinite(n)) throw new RangeError(`canonicalize: non-finite number ${n}`);
+  // Use JavaScript's default number serialisation, which matches ES6.
+  return String(n);
+}
+
+const ESCAPE_MAP: Record<string, string> = {
+  '"': '\\"',
+  "\\": "\\\\",
+  "\b": "\\b",
+  "\f": "\\f",
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+};
+
+function serializeString(s: string): string {
+  let result = '"';
+  for (const ch of s) {
+    const code = ch.charCodeAt(0);
+    if (ch in ESCAPE_MAP) {
+      result += ESCAPE_MAP[ch];
+    } else if (code < 0x20) {
+      result += `\\u${code.toString(16).padStart(4, "0")}`;
+    } else {
+      result += ch;
+    }
+  }
+  return result + '"';
+}
+
+function utf16Compare(a: string, b: string): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const ca = a.charCodeAt(i) || -1;
+    const cb = b.charCodeAt(i) || -1;
+    if (ca !== cb) return ca - cb;
+  }
+  return 0;
+}

package/src/hash.ts

@@ -0,0 +1,43 @@
+/**
+ * ATB hash-chaining implementation for TypeScript/Node.js.
+ *
+ * Each event hash is computed as:
+ *   SHA256(prevHash + canonicalJSON(event))
+ */
+
+import { createHash } from "node:crypto";
+import { canonicalize } from "./canonicalize.js";
+import type { ATBEvent } from "./types.js";
+
+/** The sentinel previous-hash used for the first event in a bundle. */
+export const GENESIS_HASH = "0".repeat(64);
+
+/**
+ * Compute the SHA-256 hash for an event given the previous hash.
+ */
+export function computeHash(event: ATBEvent, prevHash: string): string {
+  const canonical = canonicalize(event);
+  return createHash("sha256")
+    .update(prevHash, "utf8")
+    .update(canonical, "utf8")
+    .digest("hex");
+}
+
+/**
+ * Compute and assign hashes for a sequence of events.
+ * Mutates each event's `seq` and `prevHash` fields in-place.
+ *
+ * @returns Array of hex-encoded SHA-256 hashes, one per event.
+ */
+export function chainEvents(events: ATBEvent[]): string[] {
+  const hashes: string[] = [];
+  let prev = GENESIS_HASH;
+  for (let i = 0; i < events.length; i++) {
+    events[i].seq = i + 1;
+    events[i].prevHash = prev;
+    const h = computeHash(events[i], prev);
+    hashes.push(h);
+    prev = h;
+  }
+  return hashes;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @atb-dev/sdk — ATB (Agent Trace Bundle) TypeScript SDK
+ *
+ * Tamper-evident, replayable audit trails for AI agent workflows.
+ *
+ * @example
+ * ```ts
+ * import { Bundle } from "@atb-dev/sdk";
+ *
+ * const bundle = new Bundle();
+ * bundle.append("dev.session", { date: "2025-01-15" });
+ * bundle.save();
+ * ```
+ */
+
+export { Bundle, ATBVerificationError } from "./bundle.js";
+export { computeHash, chainEvents, GENESIS_HASH } from "./hash.js";
+export { canonicalize } from "./canonicalize.js";
+export type { ATBEvent, ATBRecord, BundleOptions } from "./types.js";

package/src/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Core type definitions for the ATB TypeScript SDK.
+ */
+
+/** A single auditable event in an ATB bundle. */
+export interface ATBEvent {
+  /** 1-based sequence number within the bundle. */
+  seq: number;
+  /** Hex-encoded SHA-256 hash of the preceding event (or GENESIS_HASH). */
+  prevHash: string;
+  /** Dot-namespaced event type identifier. */
+  type: string;
+  /** Arbitrary JSON-serialisable payload. */
+  data: unknown;
+}
+
+/** A single record in an ATB bundle file (event + its hash). */
+export interface ATBRecord {
+  event: ATBEvent;
+  hash: string;
+}
+
+/** Options for creating a Bundle. */
+export interface BundleOptions {
+  /** Path to the bundle file. Defaults to `run.atb/bundle.atb`. */
+  path?: string;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}