@ticket-gate/engine 0.0.0-stage → 0.1.0-rc.1

package/ledger.mjs

@@ -0,0 +1,186 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { VERIFIED_STATUSES } from './digest.mjs';
+import { ROOT } from './root.mjs';
+import { HISTORY_REL, readHistory } from './tree.mjs';
+import { formatMs } from './summary.mjs';
+
+export const LEDGER_REL = '.turbo/ticket-verify-steps.jsonl';
+
+export const LEDGER = join(ROOT, LEDGER_REL);
+
+export const LEDGER_MAX = 200;
+
+// One line per e2e spec per run, kept apart from the step ledger.
+export const SPEC_LEDGER = join(ROOT, '.turbo', 'ticket-verify-specs.jsonl');
+
+export const SPEC_LEDGER_MAX = 2000;
+
+export const HISTORY = join(ROOT, HISTORY_REL);
+
+export const HISTORY_MAX = 50;
+
+/** { treeHash, ranAt } (exactly these keys) of a green receipt, else null. */
+export function historyEntry(receipt) {
+  if (receipt?.ok !== true) return null;
+  if (receipt.oversize === true) return null;
+  // prettier-ignore
+  if (!(receipt.results ?? []).every((r) => VERIFIED_STATUSES.includes(r.status))) return null;
+  if (typeof receipt.treeHash !== 'string') return null;
+  return { treeHash: receipt.treeHash, ranAt: receipt.ranAt };
+}
+
+const writeLines = (path, entries) => {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    `${path}.tmp`,
+    entries.map((e) => `${JSON.stringify(e)}\n`).join(''),
+  );
+  renameSync(`${path}.tmp`, path);
+};
+
+/** No history file yet and receiptPath holds a receipt historyEntry accepts: write that one line. */
+export function seedHistory(historyPath, receiptPath) {
+  if (existsSync(historyPath)) return false;
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+  } catch {
+    return false;
+  }
+  const entry = historyEntry(receipt);
+  if (!entry) return false;
+  writeLines(historyPath, [entry]);
+  return true;
+}
+
+/** historyEntry(receipt) null: no write. Else keep the newest HISTORY_MAX lines. */
+export function appendHistory(historyPath, receipt) {
+  const entry = historyEntry(receipt);
+  if (!entry) return false;
+  const kept = [...readHistory(historyPath), entry].slice(-HISTORY_MAX);
+  writeLines(historyPath, kept);
+  return true;
+}
+
+/** Lines of the step ledger in file order. Missing file -> []; a blank, non-JSON or non-object line is skipped. */
+export function readLedger(path = LEDGER) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const raw of readFileSync(path, 'utf8').split('\n')) {
+    if (raw.trim() === '') continue;
+    let line;
+    try {
+      line = JSON.parse(raw);
+    } catch {
+      continue; // a corrupt line is skipped, never fatal
+    }
+    if (line && typeof line === 'object' && !Array.isArray(line))
+      out.push(line);
+  }
+  return out;
+}
+
+/** The newest ledger line matching id, cmd and digest. */
+export function newestLedgerLine(ledger, { id, cmd, digest }) {
+  return ledger.findLast(
+    (l) => l.id === id && l.cmd === cmd && l.digest === digest,
+  );
+}
+
+/**
+ * One ledger line per pass or fail result (a timeout is a fail) whose inputs
+ * are still what the plan digested: `digestNow(id, cmd)` is the digest of the
+ * tree after the steps ran. A pass is never filed under inputs it did not see.
+ */
+export function ledgerLines(results, { ranAt, digestNow }) {
+  return results
+    .filter(
+      (r) =>
+        (r.status === 'pass' || r.status === 'fail') &&
+        typeof r.digest === 'string' &&
+        digestNow(r.id, r.cmd) === r.digest,
+    )
+    .map((r) => ({
+      id: r.id,
+      cmd: r.cmd,
+      digest: r.digest,
+      status: r.status,
+      ranAt,
+      summary: r.summary,
+      ms: r.ms,
+      ...(r.mode ? { mode: r.mode } : {}),
+    }));
+}
+
+/** Append `lines` to the ledger at `path`, keeping the newest LEDGER_MAX. */
+export function appendLedger(path, lines) {
+  writeLines(path, [...readLedger(path), ...lines].slice(-LEDGER_MAX));
+}
+
+/** Append `lines` to the spec ledger at `path`, keeping the newest SPEC_LEDGER_MAX. */
+export function appendSpecLedger(path, lines) {
+  writeLines(path, [...readLedger(path), ...lines].slice(-SPEC_LEDGER_MAX));
+}
+
+/** One spec-ledger line per pass or fail entry whose digest still holds after the run. */
+export function specLedgerLines(specs, { ranAt, mode, ms, digestNow }) {
+  return specs
+    .filter(
+      (s) =>
+        (s.status === 'pass' || s.status === 'fail') &&
+        typeof s.digest === 'string' &&
+        digestNow(s.file) === s.digest,
+    )
+    .map((s) => ({
+      id: 'e2e-spec',
+      file: s.file,
+      digest: s.digest,
+      status: s.status,
+      ranAt,
+      mode,
+      ms: s.ms ?? ms,
+    }));
+}
+
+/** D10: median of the newest 5 full e2e passes, with the largest specs of the newest when it is over budget. */
+export function fullMedianLine(ledger, specLedger) {
+  const runs = ledger
+    .filter(
+      (l) =>
+        l.id === 'e2e' &&
+        l.status === 'pass' &&
+        typeof l.ms === 'number' &&
+        (l.mode ?? 'full') === 'full',
+    )
+    .slice(-5);
+  if (runs.length === 0) return null;
+  const sorted = runs.map((l) => l.ms).sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  const median =
+    sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+  const warn = median > FULL_MEDIAN_WARN_MS;
+  let line = `e2e full median: ${formatMs(median)} over the last ${runs.length} full runs`;
+  if (warn) {
+    const newest = runs.at(-1).ranAt;
+    const top = specLedger
+      .filter(
+        (l) =>
+          l.id === 'e2e-spec' && l.ranAt === newest && typeof l.ms === 'number',
+      )
+      .sort((a, b) => b.ms - a.ms)
+      .slice(0, 5)
+      .map((l) => `${l.file} ${formatMs(l.ms)}`);
+    line += `\nWARNING: over the 20 min budget (D10)${top.length ? `; largest specs: ${top.join(', ')}` : ''}`;
+  }
+  return { line, warn };
+}
+
+// D10: a full-suite median above this prints a warning.
+export const FULL_MEDIAN_WARN_MS = 20 * 60 * 1000;

package/lock.d.mts

@@ -0,0 +1,72 @@
+// Types for lock.mjs, the stack lock shared by the gate, the nightly and the profiler.
+export interface LockHolder {
+  owner: string;
+  pid: number;
+  id: string;
+  startedAt: string;
+  cwd: string;
+  nested?: boolean;
+  [key: string]: unknown;
+}
+export interface LockOptions {
+  now?: () => number;
+  alive?: (pid: number) => boolean;
+  env?: NodeJS.ProcessEnv;
+}
+export type TakeResult =
+  | { ok: true; holder: LockHolder; nested?: boolean }
+  | { ok: false; holder: LockHolder };
+export interface GateLock {
+  acquire(): { ok: boolean; [key: string]: unknown };
+  release(): void;
+  [key: string]: unknown;
+}
+
+export const OWNERS: string[];
+export const STALE_EMPTY_MS: number;
+export const WAIT_S: number;
+export const POLL_S: number;
+export const PRINT_S: number;
+
+export function mainCheckout(cwd?: string): string;
+export function lockPath(
+  cwd?: string,
+  opts?: { env?: NodeJS.ProcessEnv },
+): string;
+export function isAlive(pid: number): boolean;
+export function readLock(
+  path: string,
+  opts?: { now?: () => number },
+): LockHolder | null;
+export function readReleased(path: string): Record<string, unknown> | null;
+export function reapStale(path: string, opts?: LockOptions): boolean;
+export function tryTake(
+  path: string,
+  opts: LockOptions & { owner: string; cwd?: string; pid?: number },
+): TakeResult;
+export function release(
+  path: string,
+  holder: LockHolder,
+  opts?: { now?: () => number },
+): boolean;
+export function heldByOther(path: string, opts?: LockOptions): LockHolder | null;
+export function holderLine(holder: LockHolder): string;
+export function refuseIfHeld(path?: string, opts?: LockOptions): void;
+export function takeOrExit(
+  owner: string,
+  opts?: {
+    path?: string;
+    exit?: (code: number) => unknown;
+    log?: (line: string) => void;
+  },
+): LockHolder;
+export function sleepSync(ms: number): void;
+export function gateLock(opts?: {
+  path?: string;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  sleep?: (ms: number) => void;
+  log?: (line: string) => void;
+  alive?: (pid: number) => boolean;
+  commands?: Record<string, unknown>;
+}): GateLock;

package/lock.mjs

@@ -0,0 +1,329 @@
+// One lock for the single local Supabase stack .
+//
+// The stack (db, edge runtime, :3000) holds one database that e2e resets and
+// seeds. Two runs at once corrupt each other, so every run that resets it takes
+// this lock: verify:ticket, mutate:check, profile:web and the nightly e2e.
+//
+// The lock is a directory `<main checkout>/.turbo/stack.lock` made by one
+// atomic mkdir, with `owner.json` inside. A holder that dies leaves a lock
+// naming a dead pid; the next taker removes it (takeover) and records
+// `lastReleasedAt`, so nobody needs a signal handler (contract L-R1).
+// Node built-ins only; no build step.
+
+import { execFileSync } from 'node:child_process';
+import {
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { DEFAULT_COMMANDS } from './config.mjs';
+import { bothNames, envName } from './env-name.mjs';
+import { ROOT } from './root.mjs';
+
+export const OWNERS = [
+  'verify:ticket',
+  'mutate:check',
+  'profile:web',
+  'nightly',
+];
+export const STALE_EMPTY_MS = 10_000;
+export const WAIT_S = 2700,
+  POLL_S = 5,
+  PRINT_S = 60;
+
+/** The main checkout, also from inside a linked worktree. */
+export function mainCheckout(cwd = ROOT) {
+  const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd,
+    encoding: 'utf8',
+  }).trim();
+  return realpathSync(dirname(resolve(cwd, common)));
+}
+
+export function lockPath(cwd = ROOT, { env = process.env } = {}) {
+  return (
+    envName(env, 'STACK_LOCK_PATH') ?? join(mainCheckout(cwd), '.turbo', 'stack.lock')
+  );
+}
+
+export function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+export function readLock(path, { now = Date.now } = {}) {
+  let st;
+  try {
+    st = statSync(path);
+  } catch {
+    return null;
+  }
+  void now;
+  const o = readJson(join(path, 'owner.json'));
+  if (o && typeof o.id === 'string' && Number.isInteger(o.pid)) return o;
+  return {
+    owner: 'unknown',
+    pid: 0,
+    id: '',
+    startedAt: new Date(st.mtimeMs).toISOString(),
+    cwd: '',
+  };
+}
+
+export function readReleased(path) {
+  return readJson(`${path}.released.json`);
+}
+
+function writeReleased(path, { owner, pid, stale, now = Date.now }) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    `${path}.released.json`,
+    `${JSON.stringify({ v: 1, lastReleasedAt: new Date(now()).toISOString(), owner, pid, stale })}\n`,
+  );
+}
+
+const emptyAndOld = (holder, now) =>
+  holder.owner === 'unknown' &&
+  now() - Date.parse(holder.startedAt) > STALE_EMPTY_MS;
+
+export function reapStale(path, { now = Date.now, alive = isAlive } = {}) {
+  const holder = readLock(path, { now });
+  // An empty lock dir has no pid to test: it is stale only once it is old.
+  if (holder?.owner === 'unknown')
+    return emptyAndOld(holder, now) && reap(path, holder, now);
+  if (holder === null || alive(holder.pid)) return false;
+  return reap(path, holder, now);
+}
+
+// Reapers are serialized by an atomic mkdir of `${path}.reaping`, and the lock
+// is re-read inside it: between readLock and the rename another taker may have
+// reaped the dead holder and taken the lock, and a bare rename would take that
+// live lock away from it.
+function reap(path, holder, now) {
+  const guard = `${path}.reaping`;
+  try {
+    mkdirSync(guard);
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    // A reaper that died inside the guard must not block reaping forever.
+    try {
+      if (now() - statSync(guard).mtimeMs > STALE_EMPTY_MS)
+        rmSync(guard, { recursive: true, force: true });
+    } catch {
+      // already gone
+    }
+    return false;
+  }
+  try {
+    const onDisk = readLock(path, { now });
+    if (onDisk === null || onDisk.id !== holder.id) return false;
+    if (onDisk.id === '' && !emptyAndOld(onDisk, now)) return false;
+    const gone = `${path}.stale-${process.pid}-${now()}`;
+    renameSync(path, gone);
+    rmSync(gone, { recursive: true, force: true });
+    writeReleased(path, {
+      owner: holder.owner,
+      pid: holder.pid,
+      stale: true,
+      now,
+    });
+    return true;
+  } catch {
+    return false; // lost a race on the rename
+  } finally {
+    rmSync(guard, { recursive: true, force: true });
+  }
+}
+
+export function tryTake(
+  path,
+  {
+    owner,
+    cwd = process.cwd(),
+    pid = process.pid,
+    now = Date.now,
+    alive = isAlive,
+    env = process.env,
+  },
+) {
+  if (!OWNERS.includes(owner))
+    throw new Error(`unknown stack lock owner: ${owner}`);
+  reapStale(path, { now, alive });
+  const current = readLock(path, { now });
+  if (
+    current !== null &&
+    current.id !== '' &&
+    envName(env, 'STACK_LOCK_OWNER') === current.id &&
+    alive(current.pid)
+  )
+    return { ok: true, holder: { ...current, nested: true }, nested: true };
+  mkdirSync(dirname(path), { recursive: true });
+  try {
+    mkdirSync(path);
+  } catch (e) {
+    if (e.code === 'EEXIST')
+      return { ok: false, holder: readLock(path, { now }) };
+    throw e;
+  }
+  const startedAtMs = now();
+  const holder = {
+    v: 1,
+    id: `${owner}:${pid}:${startedAtMs}`,
+    owner,
+    pid,
+    cwd,
+    startedAt: new Date(startedAtMs).toISOString(),
+  };
+  writeFileSync(join(path, 'owner.json'), `${JSON.stringify(holder)}\n`);
+  return { ok: true, holder };
+}
+
+export function release(path, holder, { now = Date.now } = {}) {
+  if (holder.nested === true) return false;
+  const onDisk = readLock(path, { now });
+  if (onDisk?.id !== holder.id) return false;
+  rmSync(path, { recursive: true, force: true });
+  // prettier-ignore
+  writeReleased(path, { owner: holder.owner, pid: holder.pid, stale: false, now });
+  return true;
+}
+
+/** The live holder that is not the caller's own tree, else null. */
+export function heldByOther(
+  path,
+  { env = process.env, alive = isAlive, now = Date.now } = {},
+) {
+  const holder = readLock(path, { now });
+  if (holder === null) return null;
+  if (holder.owner === 'unknown')
+    return emptyAndOld(holder, now) ? null : holder;
+  if (envName(env, 'STACK_LOCK_OWNER') === holder.id) return null;
+  return alive(holder.pid) ? holder : null;
+}
+
+export function holderLine(holder) {
+  return `${holder.owner} running since ${holder.startedAt} (pid ${holder.pid}, ${holder.cwd})`;
+}
+
+export function refuseIfHeld(path = lockPath(), opts) {
+  const h = heldByOther(path, opts);
+  if (h !== null)
+    throw new Error(
+      `stack lock held: ${holderLine(h)}. Wait for it, or stop it; TICKET_GATE_STACK_LOCK_OWNER lets the holder's own runs pass.`,
+    );
+}
+
+/** Take the lock or exit 1 naming the holder; release on exit. */
+export function takeOrExit(
+  owner,
+  { path = lockPath(), exit = process.exit, log = console.error } = {},
+) {
+  const got = tryTake(path, { owner });
+  if (!got.ok) {
+    log(`${owner}: stack lock held: ${holderLine(got.holder)}`);
+    exit(1);
+    return got.holder;
+  }
+  Object.assign(process.env, bothNames('STACK_LOCK_OWNER', got.holder.id));
+  process.on('exit', () => release(path, got.holder));
+  return got.holder;
+}
+
+/** Blocks the calling thread; no signal handler, so Ctrl-C kills a waiting gate at once (L-R1). */
+export function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const envS = (env, name, dflt) => {
+  const n = Number.parseInt(envName(env, name) ?? '', 10);
+  return Number.isInteger(n) && n >= 0 ? n : dflt;
+};
+
+/**
+ * The stack lock around the stack steps. `acquire` waits for any
+ * holder up to TICKET_GATE_STACK_LOCK_WAIT_S (45 min), then fails the preflight step with
+ * a summary naming the holder. `release` is safe to call twice.
+ */
+export function gateLock({
+  path = lockPath(),
+  env = process.env,
+  now = Date.now,
+  sleep = sleepSync,
+  log = console.log,
+  alive = isAlive,
+  commands: given,
+} = {}) {
+  const commands = { ...DEFAULT_COMMANDS, ...given };
+  let held = null;
+  const waiter = join(`${path}.waiters`, `${process.pid}.json`);
+  const dropWaiter = () => rmSync(waiter, { force: true });
+  return {
+    acquire() {
+      const waitS = envS(env, 'STACK_LOCK_WAIT_S', WAIT_S);
+      const pollS = envS(env, 'STACK_LOCK_POLL_S', POLL_S);
+      const printS = envS(env, 'STACK_LOCK_PRINT_S', PRINT_S);
+      const take = () =>
+        tryTake(path, { owner: 'verify:ticket', now, alive, env });
+      const taken = (got) => {
+        dropWaiter();
+        held = got.holder;
+        Object.assign(env, bothNames('STACK_LOCK_OWNER', got.holder.id));
+        return { ok: true };
+      };
+      let got = take();
+      if (got.ok) return taken(got);
+      const started = now();
+      let lastPrint = -Infinity;
+      mkdirSync(dirname(waiter), { recursive: true });
+      writeFileSync(
+        waiter,
+        `${JSON.stringify({ v: 1, owner: 'verify:ticket', pid: process.pid, cwd: process.cwd(), since: new Date(started).toISOString() })}\n`,
+      );
+      const fail = (holder) => {
+        dropWaiter();
+        const min = Math.round((now() - started) / 60000);
+        const who = holder ? holderLine(holder) : 'unknown holder';
+        return {
+          ok: false,
+          summary: `stack lock: ${who}; waited ${min} min. Wait for it to finish${commands.nightlyStatus ? ` (${commands.nightlyStatus} shows the nightly)` : ''}, then rerun ${commands.verify}.`,
+        };
+      };
+      for (;;) {
+        const { holder } = got;
+        if (now() - started >= waitS * 1000) return fail(holder);
+        if (now() - lastPrint >= printS * 1000) {
+          lastPrint = now();
+          const min = Math.floor((now() - started) / 60000);
+          log(
+            `stack lock held by ${holderLine(holder ?? {})}; waiting (${min} of ${waitS / 60} min)`,
+          );
+        }
+        sleep(pollS * 1000);
+        got = take();
+        if (got.ok) return taken(got);
+      }
+    },
+    release() {
+      dropWaiter();
+      if (held) release(path, held, { now });
+      held = null;
+    },
+  };
+}