@rubric-protocol/attest-decision 1.0.0

package/src/spool.ts

@@ -0,0 +1,244 @@
+/**
+ * Durable append-only spool (tasks/P1.md).
+ *
+ * Durability model: `attest()` must add <1 ms to the caller, so we CANNOT fsync
+ * on the append path. Instead each record is appended with a single `writeSync`.
+ * A `writeSync` hands the bytes to the kernel, so they survive process death
+ * (`kill -9`) — only a machine/OS crash could lose them, and that is what the
+ * background `fsync()` (called off the caller path, before each network flush)
+ * defends against. On restart, `pending()` replays everything not yet acked, so
+ * zero spooled records are lost.
+ *
+ * Format: one JSON line per record, `{"seq":N,"dar":{...}}\n`. Acknowledgement
+ * is a monotonic high-water mark `ackedThrough` persisted in a `<path>.ack`
+ * sidecar; records are FIFO so a single watermark suffices. When the file
+ * exceeds `maxBytes` it is compacted (acked records dropped; then oldest pending
+ * dropped — "drop-oldest" — until under cap).
+ */
+import {
+  closeSync,
+  fstatSync,
+  fsyncSync,
+  ftruncateSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import type { DarCore, PayloadRecord } from "./constants.js";
+
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024; // 50 MB (tasks/P1.md)
+
+export interface SpoolRecord {
+  seq: number;
+  dar: DarCore;
+  /** Raw content, present only in `payload` mode (spec §4). */
+  payload?: PayloadRecord;
+}
+
+export interface SpoolOptions {
+  maxBytes?: number;
+  /** Called when the drop-oldest cap policy discards records (data loss). */
+  onDrop?: (count: number) => void;
+}
+
+/** Write an entire buffer, looping over short writes (write(2) may be partial). */
+function writeFully(fd: number, buf: Buffer): void {
+  let offset = 0;
+  while (offset < buf.length) {
+    offset += writeSync(fd, buf, offset, buf.length - offset);
+  }
+}
+
+/** Durably write a small file (write + fsync). */
+function writeFileDurable(path: string, contents: string): void {
+  const fd = openSync(path, "w");
+  try {
+    writeFully(fd, Buffer.from(contents, "utf8"));
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** fsync a directory so a rename/create within it is durable. */
+function fsyncDir(path: string): void {
+  const fd = openSync(path, "r");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export class Spool {
+  private readonly path: string;
+  private readonly dir: string;
+  private readonly ackPath: string;
+  private readonly maxBytes: number;
+  private readonly onDrop?: (count: number) => void;
+
+  private fd: number;
+  private seq = 0;
+  private ackedThrough = 0;
+  private bytes = 0;
+  private droppedForCap = 0;
+  private compactionPending = false;
+  private pendingRecords: SpoolRecord[] = [];
+
+  constructor(path: string, options: SpoolOptions = {}) {
+    this.path = path;
+    this.dir = dirname(path);
+    this.ackPath = `${path}.ack`;
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    this.onDrop = options.onDrop;
+    // Create the spool directory if missing so a documented path like
+    // /var/lib/rubric/attest.spool works without a separate mkdir.
+    mkdirSync(this.dir, { recursive: true });
+    this.ackedThrough = this.readAck();
+    this.recover();
+    // Open the append fd after recovery has read the current contents.
+    this.fd = openSync(this.path, "a");
+    this.bytes = fstatSync(this.fd).size;
+  }
+
+  /** Records written but not yet acknowledged, in FIFO order. */
+  pending(): SpoolRecord[] {
+    return this.pendingRecords.slice();
+  }
+
+  /** Count of records dropped by the drop-oldest cap policy so far. */
+  droppedCount(): number {
+    return this.droppedForCap;
+  }
+
+  currentSeq(): number {
+    return this.seq;
+  }
+
+  /**
+   * Append a record durably (single `writeSync`, no fsync). Returns its seq.
+   * Never compacts inline — that would put a multi-MB `writeFileSync`+`fsync` on
+   * the caller's `attest()` path. Crossing the cap only flags compaction, which
+   * `compactIfNeeded()` performs off the caller path (see the Attestor flush).
+   */
+  append(dar: DarCore, payload?: PayloadRecord): number {
+    const seq = ++this.seq;
+    const record: SpoolRecord = payload ? { seq, dar, payload } : { seq, dar };
+    const line = JSON.stringify(record) + "\n";
+    const buf = Buffer.from(line, "utf8");
+    writeFully(this.fd, buf); // loop over short writes so a line is never torn
+    this.bytes += buf.byteLength;
+    this.pendingRecords.push(record);
+    if (this.bytes > this.maxBytes) this.compactionPending = true;
+    return seq;
+  }
+
+  /** Whether the file has grown past the cap and awaits compaction. */
+  needsCompaction(): boolean {
+    return this.compactionPending;
+  }
+
+  /** Reclaim acked space and enforce the cap (drop-oldest). Off the caller path. */
+  compactIfNeeded(): void {
+    if (!this.compactionPending) return;
+    this.compact();
+    this.compactionPending = false;
+  }
+
+  /**
+   * Acknowledge every record with seq <= `throughSeq` (they were delivered).
+   * Advances the durable watermark; truncates the file once fully drained.
+   */
+  ack(throughSeq: number): void {
+    if (throughSeq <= this.ackedThrough) return;
+    this.ackedThrough = throughSeq;
+    this.pendingRecords = this.pendingRecords.filter((r) => r.seq > throughSeq);
+    this.writeAck();
+    if (this.pendingRecords.length === 0) {
+      // Steady state: everything delivered. Reclaim the file entirely.
+      ftruncateSync(this.fd, 0);
+      this.bytes = 0;
+    }
+  }
+
+  /** Flush OS buffers to disk. Called off the caller path, before network I/O. */
+  fsync(): void {
+    fsyncSync(this.fd);
+  }
+
+  close(): void {
+    closeSync(this.fd);
+  }
+
+  // --- internals ---
+
+  private recover(): void {
+    let raw: string;
+    try {
+      raw = readFileSync(this.path, "utf8");
+    } catch {
+      return; // no spool file yet
+    }
+    let maxSeq = 0;
+    for (const line of raw.split("\n")) {
+      if (line.length === 0) continue;
+      let record: SpoolRecord;
+      try {
+        record = JSON.parse(line) as SpoolRecord;
+      } catch {
+        continue; // tolerate a torn trailing line from a crash mid-write
+      }
+      if (typeof record.seq !== "number") continue;
+      if (record.seq > maxSeq) maxSeq = record.seq;
+      if (record.seq > this.ackedThrough) this.pendingRecords.push(record);
+    }
+    this.pendingRecords.sort((a, b) => a.seq - b.seq);
+    this.seq = maxSeq;
+  }
+
+  private compact(): void {
+    // Drop oldest pending until the surviving set fits under the cap.
+    const kept = this.pendingRecords.slice();
+    let size = kept.reduce((n, r) => n + Buffer.byteLength(JSON.stringify(r) + "\n"), 0);
+    let droppedNow = 0;
+    while (size > this.maxBytes && kept.length > 0) {
+      const dropped = kept.shift()!;
+      size -= Buffer.byteLength(JSON.stringify(dropped) + "\n");
+      this.droppedForCap++;
+      droppedNow++;
+    }
+
+    const tmp = `${this.path}.compact`;
+    const body = kept.map((r) => JSON.stringify(r) + "\n").join("");
+    writeFileDurable(tmp, body);
+    closeSync(this.fd);
+    renameSync(tmp, this.path);
+    fsyncDir(this.dir); // make the rename durable across a power loss
+    this.fd = openSync(this.path, "a");
+    this.bytes = fstatSync(this.fd).size;
+    this.pendingRecords = kept;
+
+    // Surface the drop-oldest data loss rather than discarding silently.
+    if (droppedNow > 0) this.onDrop?.(droppedNow);
+  }
+
+  private readAck(): number {
+    try {
+      const n = Number.parseInt(readFileSync(this.ackPath, "utf8").trim(), 10);
+      return Number.isFinite(n) && n >= 0 ? n : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  private writeAck(): void {
+    // fsync the watermark so a crash cannot resurrect already-acked records
+    // (bounding duplicate re-delivery on recovery).
+    writeFileDurable(this.ackPath, String(this.ackedThrough));
+  }
+}
+
+export { DEFAULT_MAX_BYTES };

package/src/transport.ts

@@ -0,0 +1,76 @@
+/**
+ * Batch transport. One POST per flush to /v1/tiered-attest (tasks/P1.md).
+ * The SDK reads exactly one credential env var: RUBRIC_API_KEY (CLAUDE.md).
+ */
+import { API_KEY_ENV, TIERED_ATTEST_PATH, type DarCore, type PayloadRecord } from "./constants.js";
+
+export interface Transport {
+  /**
+   * Deliver one batch. `records` are hashes-only DAR cores; `payloads` (raw
+   * content) is present only in `payload` mode and rides in the envelope, never
+   * in a core. Must reject on failure so the spool retains the batch.
+   */
+  send(records: DarCore[], payloads?: PayloadRecord[]): Promise<void>;
+}
+
+export interface HttpTransportOptions {
+  baseUrl: string;
+  /** Defaults to reading process.env.RUBRIC_API_KEY at send time. */
+  apiKey?: () => string | undefined;
+  fetchImpl?: typeof fetch;
+  /** Abort a POST after this many ms so a hung endpoint can't stall flushing. Default 30000. */
+  timeoutMs?: number;
+  /** Permit a non-HTTPS baseUrl (localhost is always allowed). Default false. */
+  allowInsecure?: boolean;
+}
+
+function isLocalhost(u: URL): boolean {
+  return u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+}
+
+/** Default transport: one JSON POST of the batch to `${baseUrl}/v1/tiered-attest`. */
+export class HttpTransport implements Transport {
+  private readonly baseUrl: string;
+  private readonly apiKey: () => string | undefined;
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(options: HttpTransportOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    // Refuse to send the bearer credential over cleartext unless explicitly allowed.
+    const parsed = new URL(this.baseUrl);
+    if (parsed.protocol !== "https:" && !isLocalhost(parsed) && !options.allowInsecure) {
+      throw new Error(
+        `HttpTransport: refusing non-HTTPS baseUrl '${this.baseUrl}' (set allowInsecure to override)`,
+      );
+    }
+    this.apiKey = options.apiKey ?? (() => process.env[API_KEY_ENV]);
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.timeoutMs = options.timeoutMs ?? 30_000;
+  }
+
+  async send(records: DarCore[], payloads?: PayloadRecord[]): Promise<void> {
+    const key = this.apiKey();
+    if (!key) throw new Error(`${API_KEY_ENV} is not set`);
+
+    const body = payloads && payloads.length > 0 ? { records, payloads } : { records };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}${TIERED_ATTEST_PATH}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${key}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        throw new Error(`tiered-attest POST failed: ${res.status} ${res.statusText}`);
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/ulid.ts

@@ -0,0 +1,75 @@
+/**
+ * ULID (https://github.com/ulid/spec): 48-bit millisecond timestamp + 80 bits
+ * of randomness, Crockford base32, 26 chars. Used for `decisionId` (spec §2).
+ *
+ * A monotonic factory guarantees strictly increasing ids even within the same
+ * millisecond (randomness is incremented), so per-agent `prev` chains built from
+ * mint order are well-defined.
+ */
+import { randomFillSync } from "node:crypto";
+
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford base32 (no I,L,O,U)
+const TIME_LEN = 10;
+const RAND_LEN = 16;
+
+function encodeTime(ms: number): string {
+  if (!Number.isInteger(ms) || ms < 0 || ms > 0xffffffffffff) {
+    throw new Error(`ulid: time ${ms} out of 48-bit range`);
+  }
+  let out = "";
+  let t = ms;
+  for (let i = 0; i < TIME_LEN; i++) {
+    out = ENCODING[t % 32] + out;
+    t = Math.floor(t / 32);
+  }
+  return out;
+}
+
+function randomDigits(): number[] {
+  // Each byte's low 5 bits are uniform over 0..31 (256 is a multiple of 32).
+  const bytes = randomFillSync(new Uint8Array(RAND_LEN));
+  return Array.from(bytes, (b) => b & 31);
+}
+
+function incrementDigits(digits: number[]): number[] {
+  const next = digits.slice();
+  for (let i = RAND_LEN - 1; i >= 0; i--) {
+    if (next[i]! < 31) {
+      next[i]!++;
+      return next;
+    }
+    next[i] = 0;
+  }
+  // Overflow within one millisecond (2^80 ids) — astronomically unlikely.
+  return randomDigits();
+}
+
+function encodeDigits(digits: number[]): string {
+  let out = "";
+  for (const d of digits) out += ENCODING[d];
+  return out;
+}
+
+/**
+ * Create a monotonic ULID generator. `now` returns epoch milliseconds
+ * (injectable for deterministic tests). If the clock does not advance (or goes
+ * backwards) the randomness is incremented to keep ids strictly increasing.
+ */
+export function monotonicUlidFactory(now: () => number = Date.now): () => string {
+  let lastTime = -1;
+  let lastRand: number[] = [];
+  return function ulid(): string {
+    let t = Math.trunc(now());
+    if (t <= lastTime) {
+      t = lastTime;
+      lastRand = incrementDigits(lastRand);
+    } else {
+      lastTime = t;
+      lastRand = randomDigits();
+    }
+    return encodeTime(t) + encodeDigits(lastRand);
+  };
+}
+
+/** Default process-wide monotonic ULID generator. */
+export const ulid = monotonicUlidFactory();