@rubric-protocol/attest-decision 1.0.0

package/src/attestor.ts

@@ -0,0 +1,249 @@
+/**
+ * Attestor — the fire-and-forget façade (tasks/P1.md).
+ *
+ * `attest()` builds a DAR, appends it durably to the spool, enqueues it, and
+ * returns immediately (adds <1 ms to the caller). It NEVER throws into app code;
+ * any failure is reported to the optional `onError` sink and swallowed.
+ *
+ * The batcher flushes when the queue reaches `maxBatch` (64) or `maxWaitMs`
+ * (5000 ms) elapses, whichever comes first — one POST per flush. A delivered
+ * batch is acked in the spool; a failed batch is returned to the front of the
+ * queue and retried, so it is never lost. On construction the spool is drained:
+ * anything left by a previous run is re-queued and per-agent chain heads reseeded.
+ */
+import type { DarCore, PayloadRecord, TransmitMode } from "./constants.js";
+import { DarBuilder, toPayload, type DarBuildInput } from "./dar.js";
+import { Spool } from "./spool.js";
+import type { Transport } from "./transport.js";
+
+export interface AttestorOptions {
+  transport: Transport;
+  spoolPath: string;
+  maxBatch?: number;
+  maxWaitMs?: number;
+  maxSpoolBytes?: number;
+  retryMs?: number;
+  /** Max re-send attempts per batch during close() before leaving it spooled. */
+  closeRetries?: number;
+  /** Cap on in-memory queued (un-acked) records; oldest are dropped past it. Default 100000. */
+  maxQueue?: number;
+  /** Reject a decision whose canonical form exceeds this many bytes. Default 256 KiB. */
+  maxDecisionBytes?: number;
+  /** `hash-only` (default) sends DAR cores only; `payload` also carries raw content in the envelope. */
+  mode?: TransmitMode;
+  now?: () => number;
+  newDecisionId?: () => string;
+  onError?: (err: unknown) => void;
+  /** Replay leftover spool records on construction. Default true. */
+  autoRecover?: boolean;
+}
+
+interface QueueItem {
+  seq: number;
+  dar: DarCore;
+  payload?: PayloadRecord;
+}
+
+const sleep0 = (): Promise<void> => new Promise((r) => setImmediate(r));
+const delay = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+export class Attestor {
+  private readonly builder: DarBuilder;
+  private readonly spool: Spool;
+  private readonly transport: Transport;
+  private readonly maxBatch: number;
+  private readonly maxWaitMs: number;
+  private readonly retryMs: number;
+  private readonly closeRetries: number;
+  private readonly maxQueue: number;
+  private readonly mode: TransmitMode;
+  private readonly onError?: (err: unknown) => void;
+
+  private queue: QueueItem[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private flushing = false;
+  private closed = false;
+
+  constructor(options: AttestorOptions) {
+    this.transport = options.transport;
+    this.onError = options.onError;
+    this.spool = new Spool(options.spoolPath, {
+      maxBytes: options.maxSpoolBytes,
+      onDrop: (n) => this.reportError(new Error(`spool dropped ${n} oldest record(s) at the size cap`)),
+    });
+    this.builder = new DarBuilder({
+      newDecisionId: options.newDecisionId,
+      now: options.now,
+      maxDecisionBytes: options.maxDecisionBytes,
+    });
+    this.maxBatch = options.maxBatch ?? 64;
+    this.maxWaitMs = options.maxWaitMs ?? 5000;
+    this.retryMs = options.retryMs ?? 1000;
+    this.closeRetries = options.closeRetries ?? 3;
+    this.maxQueue = options.maxQueue ?? 100_000;
+    this.mode = options.mode ?? "hash-only";
+
+    if (options.autoRecover !== false) this.recover();
+  }
+
+  /**
+   * Fire-and-forget. Returns the minted `decisionId`, or `null` if the record
+   * could not be built/spooled (never throws). Adds <1 ms to the caller.
+   */
+  attest(input: DarBuildInput): string | null {
+    if (this.closed) return null;
+    try {
+      const dar = this.builder.build(input);
+      const payload = this.mode === "payload" ? toPayload(dar.decisionId, input) : undefined;
+      const seq = this.spool.append(dar, payload);
+      this.queue.push({ seq, dar, payload });
+      // Bound in-memory growth under sustained transport failure: drop oldest
+      // queued records past the cap (they are surfaced, not silently lost).
+      while (this.queue.length > this.maxQueue) {
+        this.queue.shift();
+        this.reportError(new Error("attest queue cap exceeded; dropped oldest queued record"));
+      }
+      if (this.queue.length >= this.maxBatch) this.scheduleFlush();
+      else this.armTimer();
+      return dar.decisionId;
+    } catch (err) {
+      this.reportError(err);
+      return null;
+    }
+  }
+
+  /** Flush at most one batch. Safe to call directly; concurrency-guarded. */
+  async flush(): Promise<void> {
+    if (this.flushing || this.closed) return;
+    if (this.queue.length === 0) return;
+    this.flushing = true;
+    this.clearTimer();
+    const batch = this.queue.splice(0, this.maxBatch);
+    try {
+      this.spool.compactIfNeeded(); // enforce the 50 MB cap off the caller path
+      this.spool.fsync();
+      await this.transport.send(batch.map((b) => b.dar), this.payloadsOf(batch));
+      this.spool.ack(batch[batch.length - 1]!.seq);
+      this.flushing = false;
+      this.scheduleNext();
+    } catch (err) {
+      // Retain: return the batch to the front (order preserved) and retry.
+      this.queue.unshift(...batch);
+      this.flushing = false;
+      this.reportError(err);
+      this.scheduleRetry();
+    }
+  }
+
+  /** Flush repeatedly until the queue is empty (used by tests and shutdown). */
+  async drain(): Promise<void> {
+    for (;;) {
+      while (this.flushing) await sleep0();
+      if (this.queue.length === 0 || this.closed) return;
+      await this.flush();
+    }
+  }
+
+  /** Number of records still queued (not yet acknowledged). */
+  pendingCount(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Stop accepting records, drain the queue (retrying each batch up to
+   * `closeRetries` times), and close the spool. Anything still undelivered after
+   * the retries remains durably spooled for the next run's recovery.
+   */
+  async close(): Promise<void> {
+    this.closed = true;
+    this.clearTimer();
+    while (this.flushing) await sleep0();
+    this.spool.compactIfNeeded();
+    while (this.queue.length > 0) {
+      const batch = this.queue.splice(0, this.maxBatch);
+      let delivered = false;
+      for (let attempt = 0; attempt <= this.closeRetries; attempt++) {
+        try {
+          this.spool.fsync();
+          await this.transport.send(batch.map((b) => b.dar), this.payloadsOf(batch));
+          this.spool.ack(batch[batch.length - 1]!.seq);
+          delivered = true;
+          break;
+        } catch (err) {
+          this.reportError(err);
+          if (attempt < this.closeRetries) await delay(this.retryMs);
+        }
+      }
+      if (!delivered) {
+        // Give up: leave this batch (and the rest) durably spooled for recovery.
+        this.queue.unshift(...batch);
+        break;
+      }
+    }
+    this.spool.close();
+  }
+
+  // --- internals ---
+
+  /** Raw payloads for a batch — only in `payload` mode; ride in the envelope. */
+  private payloadsOf(batch: QueueItem[]): PayloadRecord[] | undefined {
+    if (this.mode !== "payload") return undefined;
+    const payloads = batch
+      .map((b) => b.payload)
+      .filter((p): p is PayloadRecord => p !== undefined);
+    return payloads.length > 0 ? payloads : undefined;
+  }
+
+  private recover(): void {
+    const pending = this.spool.pending();
+    for (const { dar } of pending) this.builder.seedHead(dar.agentId, dar.decisionId);
+    for (const item of pending) this.queue.push(item);
+    if (this.queue.length > 0) this.scheduleFlush();
+  }
+
+  private scheduleNext(): void {
+    if (this.queue.length >= this.maxBatch) this.scheduleFlush();
+    else if (this.queue.length > 0) this.armTimer();
+  }
+
+  private armTimer(): void {
+    if (this.timer || this.flushing || this.closed) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.scheduleFlush();
+    }, this.maxWaitMs);
+    this.timer.unref?.();
+  }
+
+  private scheduleRetry(): void {
+    if (this.timer || this.flushing || this.closed) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.scheduleFlush();
+    }, this.retryMs);
+    this.timer.unref?.();
+  }
+
+  private scheduleFlush(): void {
+    this.clearTimer();
+    if (this.flushing || this.closed) return;
+    setImmediate(() => {
+      void this.flush();
+    });
+  }
+
+  private clearTimer(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private reportError(err: unknown): void {
+    try {
+      this.onError?.(err);
+    } catch {
+      // An onError that throws must not escape attest().
+    }
+  }
+}

package/src/constants.ts

@@ -0,0 +1,64 @@
+/**
+ * Frozen DAR/0.1 constants and types (spec/dar-0.1.md §2, §4).
+ */
+
+/** Record format tag for the frozen DAR/0.1 field set. */
+export const DAR_VERSION = "DAR/0.1" as const;
+
+/** Hash algorithm invariant (spec §4.1). SHA3-256 everywhere. */
+export const HASH_ALGORITHM = "sha3-256" as const;
+
+/** Prefix on hash-valued fields (spec §4.2), i.e. `sha3-256:`. */
+export const HASH_PREFIX = `${HASH_ALGORITHM}:` as const;
+
+/** Attestation endpoint. Test + standard traffic both flush here (CLAUDE.md). */
+export const TIERED_ATTEST_PATH = "/v1/tiered-attest" as const;
+
+/** The single credential env var the SDK reads (CLAUDE.md invariant). */
+export const API_KEY_ENV = "RUBRIC_API_KEY" as const;
+
+/** Leaf discriminant values (spec §2, `leafType`). */
+export type LeafType = "decision" | "schema-change" | "checkpoint";
+
+/** A `sha3-256:<hex>` encoded hash string. */
+export type HashString = `${typeof HASH_ALGORITHM}:${string}`;
+
+/** Identifies the adapter that produced a decision's inputs (spec §2). */
+export interface AdapterInfo {
+  readonly name: string;
+  readonly version: string;
+}
+
+/** Transmit mode: `hash-only` (default) sends DAR cores; `payload` also carries raw content in the envelope. */
+export type TransmitMode = "hash-only" | "payload";
+
+/** Raw content transmitted ONLY in `payload` mode, in the transport envelope — never in the DAR core. */
+export interface PayloadRecord {
+  decisionId: string;
+  schema?: unknown;
+  input: unknown;
+  output: unknown;
+  meta?: unknown;
+}
+
+/**
+ * The DAR core: the frozen, HASHES-ONLY field set (spec §2). It never carries
+ * raw content — only commitments. The Merkle leaf hash is computed over the JCS
+ * canonicalization of this object.
+ */
+export interface DarCore {
+  readonly v: typeof DAR_VERSION;
+  readonly decisionId: string;
+  readonly agentId: string;
+  /** Client-claimed decision time; trusted time is the HCS consensus timestamp. */
+  readonly ts: string;
+  readonly prev: string | null;
+  readonly leafType: LeafType;
+  readonly schemaHash: HashString;
+  readonly inputHash: HashString;
+  readonly outputHash: HashString;
+  /** SHA3-256 over JCS of { schemaHash, inputHash, outputHash }. */
+  readonly decisionHash: HashString;
+  readonly schemaRef?: string;
+  readonly adapter?: AdapterInfo;
+}

package/src/dar.ts

@@ -0,0 +1,168 @@
+/**
+ * DAR builder (spec/dar-0.1.md §2). Assembles a HASHES-ONLY DAR core from
+ * adapter inputs: hashes the schema, input, and output (JCS+SHA3-256), derives
+ * `decisionHash` over those three commitments, mints a ULID `decisionId`, and
+ * maintains the per-agent `prev` chain. The core never carries raw content.
+ */
+import {
+  DAR_VERSION,
+  type AdapterInfo,
+  type DarCore,
+  type HashString,
+  type LeafType,
+  type PayloadRecord,
+} from "./constants.js";
+import { hashJson, sha3_256 } from "./hash.js";
+import { canonicalize, canonicalizeToBytes } from "./jcs.js";
+import { ulid as defaultUlid } from "./ulid.js";
+
+const LEAF_TYPES: ReadonlySet<string> = new Set(["decision", "schema-change", "checkpoint"]);
+const HASH_STRING = /^sha3-256:[0-9a-f]{64}$/;
+const DEFAULT_MAX_DECISION_BYTES = 256 * 1024; // bounds attest() latency + payload size
+
+/** Non-content metadata an adapter may attach to a decision. */
+export interface DarMeta {
+  schemaRef?: string;
+  adapter?: AdapterInfo;
+  leafType?: LeafType;
+}
+
+export interface DarBuildInput {
+  agentId: string;
+  /** Adapter-supplied decision input; hashed to `inputHash`. */
+  input: unknown;
+  /** Adapter-supplied decision output; hashed to `outputHash`. */
+  output: unknown;
+  /** Schema descriptor to hash, or a precomputed `schemaHash`. One is required. */
+  schema?: unknown;
+  schemaHash?: HashString;
+  meta?: DarMeta;
+}
+
+export interface DarBuilderDeps {
+  /** Injectable id generator (default: monotonic ULID). */
+  newDecisionId?: () => string;
+  /** Injectable clock in epoch ms (default: Date.now). */
+  now?: () => number;
+  /** Reject a decision whose canonical input+output exceeds this many bytes. Default 256 KiB. */
+  maxDecisionBytes?: number;
+}
+
+/** Derive `decisionHash` from the three content commitments (spec §4.2). */
+export function decisionHashOf(schemaHash: HashString, inputHash: HashString, outputHash: HashString): HashString {
+  return hashJson({ schemaHash, inputHash, outputHash });
+}
+
+export class DarBuilder {
+  private readonly newDecisionId: () => string;
+  private readonly now: () => number;
+  private readonly maxDecisionBytes: number;
+  private readonly heads = new Map<string, string>();
+  // Keyed by object identity: reusing the same schema object across build()
+  // calls skips re-hashing. CONTRACT: schema objects must be treated as
+  // immutable — mutating one in place after its first build() would return the
+  // stale cached hash. Distinct objects with identical contents are re-hashed.
+  private readonly schemaCache = new WeakMap<object, HashString>();
+
+  constructor(deps: DarBuilderDeps = {}) {
+    this.newDecisionId = deps.newDecisionId ?? defaultUlid;
+    this.now = deps.now ?? Date.now;
+    this.maxDecisionBytes = deps.maxDecisionBytes ?? DEFAULT_MAX_DECISION_BYTES;
+  }
+
+  build(input: DarBuildInput): DarCore {
+    const { agentId } = input;
+    if (typeof agentId !== "string" || agentId.length === 0) {
+      throw new Error("DAR: agentId must be a non-empty string");
+    }
+    const leafType: LeafType = input.meta?.leafType ?? "decision";
+    if (!LEAF_TYPES.has(leafType)) {
+      throw new Error(`DAR: unknown leafType '${leafType}'`);
+    }
+
+    const schemaHash = this.resolveSchemaHash(input);
+
+    // Canonicalize input/output once, cap the combined size, then hash.
+    const inputBytes = canonicalizeToBytes(input.input);
+    const outputBytes = canonicalizeToBytes(input.output);
+    if (inputBytes.length + outputBytes.length > this.maxDecisionBytes) {
+      throw new Error(
+        `DAR: input+output is ${inputBytes.length + outputBytes.length} bytes; exceeds maxDecisionBytes (${this.maxDecisionBytes})`,
+      );
+    }
+    const inputHash = sha3_256(inputBytes);
+    const outputHash = sha3_256(outputBytes);
+    const decisionHash = decisionHashOf(schemaHash, inputHash, outputHash);
+
+    const decisionId = this.newDecisionId();
+    const prev = this.heads.get(agentId) ?? null;
+    const ts = new Date(this.now()).toISOString();
+
+    const dar: DarCore = {
+      v: DAR_VERSION,
+      decisionId,
+      agentId,
+      ts,
+      prev,
+      leafType,
+      schemaHash,
+      inputHash,
+      outputHash,
+      decisionHash,
+      ...(input.meta?.schemaRef !== undefined ? { schemaRef: input.meta.schemaRef } : {}),
+      ...(input.meta?.adapter !== undefined ? { adapter: input.meta.adapter } : {}),
+    };
+
+    this.heads.set(agentId, decisionId);
+    return dar;
+  }
+
+  private resolveSchemaHash(input: DarBuildInput): HashString {
+    if (input.schemaHash) {
+      if (!HASH_STRING.test(input.schemaHash)) {
+        throw new Error(`DAR: schemaHash must be 'sha3-256:<64 hex>', got '${input.schemaHash}'`);
+      }
+      return input.schemaHash;
+    }
+    if (input.schema === undefined) throw new Error("DAR: schema or schemaHash is required");
+    if (typeof input.schema === "object" && input.schema !== null) {
+      const cached = this.schemaCache.get(input.schema);
+      if (cached) return cached;
+      const h = hashJson(input.schema);
+      this.schemaCache.set(input.schema, h);
+      return h;
+    }
+    return hashJson(input.schema);
+  }
+
+  /** Current chain head (last minted decisionId) for an agent, if any. */
+  getHead(agentId: string): string | undefined {
+    return this.heads.get(agentId);
+  }
+
+  /** Seed a chain head — used to continue chains after spool recovery. */
+  seedHead(agentId: string, decisionId: string): void {
+    this.heads.set(agentId, decisionId);
+  }
+}
+
+/** Build the raw payload record for `payload`-mode transmission (never in the core). */
+export function toPayload(decisionId: string, input: DarBuildInput): PayloadRecord {
+  return {
+    decisionId,
+    ...(input.schema !== undefined ? { schema: input.schema } : {}),
+    input: input.input,
+    output: input.output,
+    ...(input.meta !== undefined ? { meta: input.meta } : {}),
+  };
+}
+
+/** The Merkle leaf hash of a DAR core: SHA3-256 over its JCS bytes (spec §4.3). */
+export function leafHash(dar: DarCore): HashString {
+  return hashJson(dar);
+}
+
+/** JCS canonicalization of a DAR core — the exact leaf-hash preimage. */
+export function canonicalDar(dar: DarCore): string {
+  return canonicalize(dar);
+}

package/src/hash.ts

@@ -0,0 +1,27 @@
+/**
+ * SHA3-256 hashing (spec/dar-0.1.md §4). SHA3-256 everywhere — an invariant,
+ * not a per-call choice. Hash strings are `sha3-256:<64 lowercase hex>`.
+ */
+import { createHash } from "node:crypto";
+import { HASH_ALGORITHM, HASH_PREFIX, type HashString } from "./constants.js";
+import { canonicalizeToBytes } from "./jcs.js";
+
+/** Raw SHA3-256 as lowercase hex (no prefix). */
+export function sha3_256Hex(input: string | Uint8Array): string {
+  const h = createHash(HASH_ALGORITHM);
+  h.update(typeof input === "string" ? Buffer.from(input, "utf8") : input);
+  return h.digest("hex");
+}
+
+/** SHA3-256 as a prefixed `sha3-256:<hex>` HashString. */
+export function sha3_256(input: string | Uint8Array): HashString {
+  return `${HASH_PREFIX}${sha3_256Hex(input)}` as HashString;
+}
+
+/**
+ * Canonicalize (JCS) then hash — the one hashing path (spec §3.1).
+ * Returns a prefixed HashString over the RFC 8785 bytes of `value`.
+ */
+export function hashJson(value: unknown): HashString {
+  return sha3_256(canonicalizeToBytes(value));
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @rubric-protocol/attest-decision — core SDK (DAR/0.1).
+ *
+ * Public surface: fire-and-forget attestation (`Attestor`), the DAR builder,
+ * JCS canonicalization, SHA3-256 hashing, ULID minting, the durable spool, and
+ * transports. See spec/dar-0.1.md and tasks/P1.md.
+ */
+
+export {
+  DAR_VERSION,
+  HASH_ALGORITHM,
+  HASH_PREFIX,
+  TIERED_ATTEST_PATH,
+  API_KEY_ENV,
+  type LeafType,
+  type HashString,
+  type DarCore,
+  type AdapterInfo,
+  type TransmitMode,
+  type PayloadRecord,
+} from "./constants.js";
+
+export { canonicalize, canonicalizeToBytes, JcsError } from "./jcs.js";
+export { sha3_256, sha3_256Hex, hashJson } from "./hash.js";
+export { ulid, monotonicUlidFactory } from "./ulid.js";
+export {
+  DarBuilder,
+  leafHash,
+  canonicalDar,
+  decisionHashOf,
+  toPayload,
+  type DarBuildInput,
+  type DarBuilderDeps,
+  type DarMeta,
+} from "./dar.js";
+export { Spool, DEFAULT_MAX_BYTES, type SpoolRecord, type SpoolOptions } from "./spool.js";
+export {
+  HttpTransport,
+  type Transport,
+  type HttpTransportOptions,
+} from "./transport.js";
+export { Attestor, type AttestorOptions } from "./attestor.js";

package/src/jcs.ts

@@ -0,0 +1,116 @@
+/**
+ * JCS canonicalization — RFC 8785 (spec/dar-0.1.md §3).
+ *
+ * We lean on the platform: ECMAScript's Number-to-String and `JSON.stringify`
+ * string escaping are byte-for-byte what RFC 8785 mandates (§3.2.2.2/§3.2.2.3),
+ * and the default string sort compares by UTF-16 code unit — exactly JCS's key
+ * ordering rule. So canonicalization reduces to: recurse, sort object keys, and
+ * defer scalar serialization to `JSON.stringify`.
+ */
+
+class JcsError extends Error {
+  constructor(message: string) {
+    super(`JCS: ${message}`);
+    this.name = "JcsError";
+  }
+}
+
+function serialize(v: unknown): string {
+  if (v === null) return "null";
+
+  const t = typeof v;
+
+  if (t === "number") {
+    const n = v as number;
+    if (!Number.isFinite(n)) {
+      throw new JcsError("non-finite number (NaN/Infinity) is not representable");
+    }
+    // Spec §3.3: integers beyond the safe range MUST be carried as strings — a
+    // JS number cannot represent them exactly, so we reject rather than hash a
+    // silently-rounded value.
+    if (Number.isInteger(n) && !Number.isSafeInteger(n)) {
+      throw new JcsError(`integer ${n} exceeds Number.MAX_SAFE_INTEGER; carry it as a string (spec §3.3)`);
+    }
+    // ES Number::toString === RFC 8785 §3.2.2.3. JSON.stringify(-0) === "0".
+    return JSON.stringify(n);
+  }
+
+  if (t === "boolean") return v ? "true" : "false";
+
+  // RFC 8785 §3.2.2.2 escaping is exactly JSON.stringify's minimal escaping.
+  if (t === "string") return escapeString(v as string);
+
+  if (t === "bigint") {
+    throw new JcsError("bigint is not JSON; carry large integers as strings");
+  }
+
+  if (Array.isArray(v)) {
+    return "[" + v.map(serializeElement).join(",") + "]";
+  }
+
+  if (t === "object") {
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) {
+      // Date, Map, Set, class instances, etc. are not part of the JSON model.
+      throw new JcsError("non-plain object is not JSON-canonicalizable");
+    }
+    const obj = v as Record<string, unknown>;
+    // Default sort compares by UTF-16 code unit — the RFC 8785 ordering.
+    const keys = Object.keys(obj).sort();
+    return (
+      "{" +
+      keys
+        .map((k) => {
+          const val = obj[k];
+          rejectNonJson(val, `property '${k}'`);
+          return escapeString(k) + ":" + serialize(val);
+        })
+        .join(",") +
+      "}"
+    );
+  }
+
+  // undefined, function, symbol at the top level.
+  throw new JcsError(`unsupported value of type '${t}'`);
+}
+
+/**
+ * Spec §3.3: `undefined`, functions, and symbols MUST NOT appear in a payload —
+ * we reject rather than silently stripping them, so a malformed producer input
+ * cannot canonicalize to bytes that differ from the producer's intent.
+ */
+function rejectNonJson(value: unknown, where: string): void {
+  const t = typeof value;
+  if (value === undefined || t === "function" || t === "symbol") {
+    throw new JcsError(`${where} has non-JSON value of type '${value === undefined ? "undefined" : t}'`);
+  }
+}
+
+function serializeElement(el: unknown): string {
+  rejectNonJson(el, "array element");
+  return serialize(el);
+}
+
+// Unpaired UTF-16 surrogate: a high surrogate not followed by a low, or a low
+// not preceded by a high — i.e. invalid Unicode that RFC 8785 does not admit.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/** JSON.stringify a string after rejecting invalid Unicode (unpaired surrogates). */
+function escapeString(s: string): string {
+  if (LONE_SURROGATE.test(s)) {
+    throw new JcsError("string contains an unpaired surrogate (invalid Unicode)");
+  }
+  return JSON.stringify(s);
+}
+
+/** Canonicalize a JSON value to its RFC 8785 (JCS) string form. */
+export function canonicalize(value: unknown): string {
+  return serialize(value);
+}
+
+/** Canonicalize a JSON value to its RFC 8785 (JCS) UTF-8 bytes. */
+export function canonicalizeToBytes(value: unknown): Buffer {
+  return Buffer.from(serialize(value), "utf8");
+}
+
+export { JcsError };