catherd-cli 0.2.0 → 1.0.0

package/src/domain/catalog.ts

@@ -0,0 +1,262 @@
+import { z } from "zod";
+import { type Rung, parseRung } from "./ids.ts";
+import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "./lane.ts";
+import type { Role } from "./roles.ts";
+
+/** Spec §5.2: the scored dimensions, each on one named benchmark. */
+export const DIMS = ["repo_code", "terminal", "honesty"] as const;
+export type Dim = (typeof DIMS)[number];
+
+/**
+ * Spec §7.1 `billing` keys: a rung's backend, except that opencode's Go models (`opencode-go/…`) are billed
+ * apart from its Zen models (`opencode/…`).
+ */
+export const BILLING_KEYS = [
+  "codex",
+  "claude",
+  "claude-code",
+  "opencode-go",
+  "opencode",
+  "cursor",
+  "grok",
+] as const;
+export type BillingKey = (typeof BILLING_KEYS)[number];
+
+/** The keys a family's `on` map uses; the native `claude` pseudo-backend runs claude-code's model ids. */
+const MODEL_KEYS = ["codex", "claude-code", "opencode-go", "opencode", "cursor", "grok"] as const;
+type ModelKey = (typeof MODEL_KEYS)[number];
+
+export function billingKeyOf(r: Rung): BillingKey {
+  if (r.backend === "opencode" && r.model.startsWith("opencode-go/")) return "opencode-go";
+  return r.backend;
+}
+
+const modelKeyOf = (k: BillingKey): ModelKey => (k === "claude" ? "claude-code" : k);
+
+const BackendModelSchema = z.object({
+  id: z.string().min(1),
+  efforts: z.array(z.string().min(1)),
+  context: z.number().int().positive(),
+});
+
+/** `vendor` and `status` (current or legacy) stay in the data as documentation; nothing reads them. */
+const FamilySchema = z.looseObject({
+  id: z.string().min(1),
+  name: z.string(),
+  capabilities: z.object({ toolUse: z.boolean(), imageIn: z.boolean(), reasoning: z.boolean() }),
+  /** API list price, dollars per million tokens */
+  price: z.object({ input: z.number(), cached: z.number(), output: z.number() }),
+  /** chatgpt-plan: messages per 5 hours relative to GPT-6 Luna (spec §5.3) */
+  planWeight: z.number().positive().optional(),
+  /** claude-plan: billed as usage credits, not from the plan's limits */
+  meteredOnPlan: z.boolean().default(false),
+  on: z.partialRecord(z.enum(MODEL_KEYS), BackendModelSchema),
+  notes: z.record(z.string(), z.string()).default({}),
+});
+export type Family = z.infer<typeof FamilySchema>;
+
+/** `sources` (where the data came from) stays in the file as documentation; nothing reads it. */
+export const ModelsFileSchema = z.looseObject({
+  schema: z.literal(1),
+  version: z.string(),
+  backends: z.record(
+    z.string(),
+    z.looseObject({
+      imageGen: z.object({ tool: z.string(), requires: z.string(), source: z.string() }).optional(),
+    }),
+  ),
+  families: z.array(FamilySchema),
+});
+export type ModelsFile = z.infer<typeof ModelsFileSchema>;
+
+/** A canonical rung: `<canonical model id>#<effort>`, the key scores and treat-likes use. */
+export const CanonicalRung = z.string().regex(/^[^:#\s]+#[^#\s]+$/, "a canonical rung is model#effort");
+
+const ScoreSchema = z.object({
+  rung: CanonicalRung,
+  dim: z.enum(DIMS),
+  value: z.number(),
+  benchmark: z.string(),
+  version: z.string(),
+  url: z.url(),
+  date: z.iso.date(),
+  confidence: z.enum(["verified", "secondary", "inferred"]),
+  note: z.string().optional(),
+});
+export type Score = z.infer<typeof ScoreSchema>;
+
+const BarSchema = z.partialRecord(z.enum(DIMS), z.number());
+type Bars = Record<Kind, Record<Difficulty, Partial<Record<Dim, number>>>>;
+const BarsSchema = z.record(z.enum(KINDS), z.record(z.enum(DIFFICULTIES), BarSchema));
+
+/** `barsWhy` (the reasoning behind the bars) stays in the file as documentation; nothing reads it. */
+export const ScoresFileSchema = z.looseObject({
+  schema: z.literal(1),
+  version: z.string(),
+  benchmarks: z.record(z.enum(DIMS), z.object({ benchmark: z.string(), version: z.string() })),
+  scores: z.array(ScoreSchema),
+  treatLike: z.record(CanonicalRung, z.object({ like: CanonicalRung, note: z.string() })),
+  bars: BarsSchema,
+});
+export type ScoresFile = z.infer<typeof ScoresFileSchema>;
+
+/** `<config>/catalog.override.json` (spec §3.5): the user's treat-likes, scores and bars. */
+export const OverrideSchema = z.looseObject({
+  schema: z.literal(1).default(1),
+  treatLike: z.record(CanonicalRung, CanonicalRung).default({}),
+  scores: z.array(ScoreSchema).default([]),
+  bars: z.partialRecord(z.enum(KINDS), z.partialRecord(z.enum(DIFFICULTIES), BarSchema)).default({}),
+});
+export type Override = z.infer<typeof OverrideSchema>;
+
+interface Listed {
+  id: string;
+  efforts: string[];
+  context: number | null;
+  imageIn: boolean;
+}
+
+/** Everything routing reads, merged from the three layers plus the user's override and own timings. */
+export interface Catalog {
+  families: Family[];
+  backends: ModelsFile["backends"];
+  /** canonical rung → its best-sourced value per dimension (the override's win) */
+  scores: Record<string, Partial<Record<Dim, Score>>>;
+  treatLike: Record<string, { like: string; source: "shipped" | "user" }>;
+  bars: Bars;
+  /** per backend id, the last `listModels()`; absent when never listed */
+  listed: Record<string, { fetchedAt: string; models: Listed[] }>;
+  /** `<canonical rung>|<kind or *>` → median seconds, only with ≥ 5 samples (spec §5.2) */
+  secs: Record<string, number>;
+}
+
+const RANK: Record<Score["confidence"], number> = { verified: 0, secondary: 1, inferred: 2 };
+
+export function buildCatalog(o: {
+  models: ModelsFile;
+  scores: ScoresFile;
+  override?: Override;
+  listed?: Catalog["listed"];
+  secs?: Catalog["secs"];
+}): Catalog {
+  const scores: Catalog["scores"] = {};
+  const put = (s: Score, force: boolean) => {
+    const cur = (scores[s.rung] ??= {});
+    const had = cur[s.dim];
+    if (force || !had || RANK[s.confidence] < RANK[had.confidence]) cur[s.dim] = s;
+  };
+  for (const s of o.scores.scores) put(s, false);
+  for (const s of o.override?.scores ?? []) put(s, true);
+  const treatLike: Catalog["treatLike"] = {};
+  for (const [rung, t] of Object.entries(o.scores.treatLike))
+    treatLike[rung] = { like: t.like, source: "shipped" };
+  for (const [rung, like] of Object.entries(o.override?.treatLike ?? {}))
+    treatLike[rung] = { like, source: "user" };
+  const bars = structuredClone(o.scores.bars) as Bars;
+  for (const kind of KINDS)
+    for (const d of DIFFICULTIES) {
+      const bar = o.override?.bars[kind]?.[d];
+      if (bar) bars[kind][d] = bar;
+    }
+  return {
+    families: o.models.families,
+    backends: o.models.backends,
+    scores,
+    treatLike,
+    bars,
+    listed: o.listed ?? {},
+    secs: o.secs ?? {},
+  };
+}
+
+/** What the catalog knows about one `backend:model#effort` rung. */
+export interface RungInfo {
+  rung: string;
+  parsed: Rung;
+  key: BillingKey;
+  family: Family | null;
+  /** `<family id or backend model id>#<effort>`: the key scores, treat-likes and timings use */
+  canonical: string;
+  efforts: string[];
+  context: number | null;
+  /** true when the backend's last listing has it, false when that listing lacks it, null with no listing */
+  listed: boolean | null;
+}
+
+function familyOf(c: Catalog, r: Rung): Family | null {
+  const mk = modelKeyOf(billingKeyOf(r));
+  return c.families.find((f) => f.on[mk]?.id === r.model) ?? null;
+}
+
+/** The backend's listing; the native `claude` backend has none of its own: it runs claude-code's models. */
+const listingOf = (c: Catalog, backend: string) => c.listed[backend === "claude" ? "claude-code" : backend];
+
+/** A rung's catalog facts; `rung` must parse (E_ADMIT_RUNG otherwise). */
+export function rungInfo(c: Catalog, rung: string): RungInfo {
+  const parsed = parseRung(rung);
+  const key = billingKeyOf(parsed);
+  const family = familyOf(c, parsed);
+  const shipped = family?.on[modelKeyOf(key)];
+  const listing = listingOf(c, parsed.backend);
+  const found = listing?.models.find((m) => m.id === parsed.model);
+  return {
+    rung,
+    parsed,
+    key,
+    family,
+    canonical: `${family?.id ?? parsed.model}#${parsed.effort}`,
+    efforts: found?.efforts ?? shipped?.efforts ?? [],
+    context: found?.context ?? shipped?.context ?? null,
+    listed: listing && listing.models.length > 0 ? found !== undefined : null,
+  };
+}
+
+/** The rung's scores: its own, else those of the rung it is treated like. null when unscored. */
+export function scoresOf(
+  c: Catalog,
+  canonical: string,
+): { values: Partial<Record<Dim, number>>; records: Partial<Record<Dim, Score>>; via: string | null } | null {
+  const own = c.scores[canonical];
+  const via = own ? null : (c.treatLike[canonical]?.like ?? null);
+  const records = own ?? (via ? c.scores[via] : undefined);
+  if (!records || Object.keys(records).length === 0) return null;
+  const values: Partial<Record<Dim, number>> = {};
+  for (const d of DIMS) if (records[d]) values[d] = records[d].value;
+  return { values, records, via };
+}
+
+/** Spec §4 roles: what a rung must offer to be placed on a role. */
+export const ROLE_NEEDS: Record<Role, { toolUse?: true; imageIn?: true; imageGen?: true }> = {
+  architect: { toolUse: true },
+  verifier: { toolUse: true },
+  worker: { toolUse: true },
+  reviewer: { toolUse: true },
+  "ui-reviewer": { toolUse: true, imageIn: true },
+  artist: { imageGen: true },
+  writer: { toolUse: true },
+  researcher: { toolUse: true },
+};
+
+/**
+ * A listed model catherd has no family for can use tools (Zen and Go serve coding models) and reports
+ * its own image input; image generation is a backend capability (spec §5.2: Codex's tool).
+ */
+export function capableFor(c: Catalog, info: RungInfo, role: Role): boolean {
+  const need = ROLE_NEEDS[role];
+  const listedImage = listingOf(c, info.parsed.backend)?.models.find(
+    (m) => m.id === info.parsed.model,
+  )?.imageIn;
+  const caps = info.family?.capabilities ?? {
+    toolUse: true,
+    imageIn: listedImage ?? false,
+    reasoning: false,
+  };
+  if (need.toolUse && !caps.toolUse) return false;
+  if (need.imageIn && !caps.imageIn) return false;
+  if (need.imageGen && !c.backends[info.parsed.backend]?.imageGen) return false;
+  return true;
+}
+
+/** An effort the rung's model offers; `default` (no effort flag, spec §5.1) always is. */
+export const effortOffered = (info: RungInfo): boolean =>
+  info.parsed.effort === "default" || info.efforts.includes(info.parsed.effort);

package/src/domain/changes.ts

@@ -0,0 +1,52 @@
+import { overlaps } from "./lane.ts";
+
+/**
+ * `git status --porcelain=v1 -z` rows. A rename or copy (R/C in either column) carries its source path as
+ * the next token; both paths are reported, so moving a file out of a path counts as a change to it.
+ */
+export function parsePorcelainZ(out: string): { xy: string; path: string }[] {
+  const tokens = out.split("\0");
+  const rows: { xy: string; path: string }[] = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i] as string;
+    if (t.length < 4) continue;
+    const xy = t.slice(0, 2);
+    rows.push({ xy, path: t.slice(3) });
+    if (/[RC]/.test(xy)) {
+      const source = tokens[++i];
+      if (source) rows.push({ xy, path: source });
+    }
+  }
+  return rows;
+}
+
+/** Repo-relative path → a fingerprint of its dirty state (status, size, mtime); clean paths are absent. */
+export type Snapshot = Record<string, string>;
+
+/**
+ * The paths dirty after a run whose fingerprint differs from before it, so an edit to a file that was
+ * already dirty counts. A path that became clean (committed or reverted meanwhile) does not.
+ */
+export function changedPaths(before: Snapshot, after: Snapshot): string[] {
+  return Object.keys(after)
+    .filter((p) => before[p] !== after[p])
+    .sort();
+}
+
+/**
+ * Spec §4.4: `changedOwned` are the changes inside the lane's Owns; `violations` the ones outside it
+ * that no overlapping dispatch owns either. `strict` is false for a laneless dispatch that may write
+ * (it has no Owns to break), so it reports no violations.
+ */
+export function splitChanges(
+  changed: string[],
+  owns: string[],
+  others: string[],
+  strict: boolean,
+): { changedOwned: string[]; violations: string[] } {
+  const inside = (p: string, paths: string[]) => overlaps([p], paths).length > 0;
+  return {
+    changedOwned: changed.filter((p) => inside(p, owns)),
+    violations: strict ? changed.filter((p) => !inside(p, owns) && !inside(p, others)) : [],
+  };
+}

package/src/domain/cost.ts

@@ -0,0 +1,89 @@
+import type { BillingKey, Family } from "./catalog.ts";
+
+/** Spec §5.3: how the user pays for each billing key. */
+export const BILLING_MODES = ["chatgpt-plan", "claude-plan", "subscription", "metered"] as const;
+export type BillingMode = (typeof BILLING_MODES)[number];
+
+/** Spec §7.1's default `billing`: the owner's Codex/ChatGPT plan, Claude plan and OpenCode Go. */
+export const DEFAULT_BILLING: Record<BillingKey, BillingMode> = {
+  codex: "chatgpt-plan",
+  claude: "claude-plan",
+  "claude-code": "claude-plan",
+  "opencode-go": "subscription",
+  opencode: "metered",
+  cursor: "metered",
+  grok: "metered",
+};
+
+/**
+ * Tokens per task relative to `medium`, from GPT-6 Sol's published DeepSWE dollars per task
+ * (low 0.16, medium 0.38, high 0.64, xhigh 1.00, max 2.74; research 2026-09-25-models.md §3.1).
+ * `ultra` is `max` with parallel subagents: ×4 is catherd's estimate. An unknown variant counts as 1.
+ */
+const EFFORT_FACTOR: Record<string, number> = {
+  none: 0.3,
+  minimal: 0.3,
+  low: 0.4,
+  medium: 1,
+  default: 1,
+  high: 1.7,
+  xhigh: 2.6,
+  max: 7.2,
+  ultra: 28.8,
+};
+
+/** A reference task at medium effort: uncached input, cached input and output tokens (≈ $0.38 on Sol). */
+const REF_TASK = { input: 60_000, cached: 400_000, output: 18_000 };
+
+export const effortFactor = (effort: string): number => EFFORT_FACTOR[effort] ?? 1;
+
+/** Estimated list-price dollars for one task at `effort`. */
+export function taskUsd(price: Family["price"], effort: string): number {
+  const perTask =
+    REF_TASK.input * price.input + REF_TASK.cached * price.cached + REF_TASK.output * price.output;
+  return (perTask / 1_000_000) * effortFactor(effort);
+}
+
+/** One GPT-6 Luna task at medium, in list-price dollars: the unit of a chatgpt-plan weight of 1. */
+export const CHATGPT_UNIT_USD = 0.019;
+
+export interface Cost {
+  /** 0: paid from a subscription; 1: metered. Every tier-0 rung ranks before any tier-1 rung. */
+  tier: 0 | 1;
+  /** comparable across billing modes, in list-price dollars per task; null when unknown */
+  value: number | null;
+  mode: BillingMode;
+}
+
+/**
+ * Spec §5.3. Every mode yields list-price dollars per task, so plans compare with each other:
+ * chatgpt-plan scales the official quota weight (Luna 1, Sol 20, Astra 60) by the effort factor;
+ * claude-plan uses API prices as the proxy, with Fable metered (catherd cannot tell Pro from Max);
+ * Go's share of its monthly dollar limit is dollars / limit, which orders the same as dollars.
+ */
+export function costOf(family: Family | null, effort: string, mode: BillingMode): Cost {
+  if (!family) return { tier: mode === "metered" ? 1 : 0, value: null, mode };
+  const usd = taskUsd(family.price, effort);
+  switch (mode) {
+    case "chatgpt-plan":
+      return {
+        tier: 0,
+        value:
+          family.planWeight === undefined ? usd : family.planWeight * CHATGPT_UNIT_USD * effortFactor(effort),
+        mode,
+      };
+    case "claude-plan":
+      return { tier: family.meteredOnPlan ? 1 : 0, value: usd, mode };
+    case "subscription":
+      return { tier: 0, value: usd, mode };
+    case "metered":
+      return { tier: 1, value: usd, mode };
+  }
+}
+
+/** Cheaper first: tier, then value, an unknown value last. */
+export function compareCost(a: Cost, b: Cost): number {
+  if (a.tier !== b.tier) return a.tier - b.tier;
+  if (a.value === null || b.value === null) return (a.value === null ? 1 : 0) - (b.value === null ? 1 : 0);
+  return a.value - b.value;
+}

package/src/domain/errors.ts

@@ -0,0 +1,58 @@
+export type ErrorCode =
+  | "E_CONFIG_INVALID"
+  | "E_CONFIG_NEWER_SCHEMA"
+  | "E_CONFIG_KEYBIND"
+  | "E_BACKEND_MISSING"
+  | "E_BACKEND_TOO_OLD"
+  | "E_BACKEND_NOT_LOGGED_IN"
+  | "E_BACKEND_MODEL_UNKNOWN"
+  | "E_RUN_NOT_FOUND"
+  | "E_RUN_CORRUPT"
+  | "E_RUN_BUDGET"
+  | "E_RUN_COMMIT"
+  | "E_RUN_NOT_LIVE"
+  | "E_ADMIT_RUNG"
+  | "E_ADMIT_DUPLICATE"
+  | "E_ADMIT_OVERLAP"
+  | "E_ADMIT_ID"
+  | "E_ADMIT_THREAD"
+  | "E_LANE_INVALID"
+  | "E_JEV_KEY"
+  | "E_JEV_NETWORK"
+  | "E_JEV_RESPONSE"
+  | "E_IO_LOCK"
+  | "E_IO_WRITE"
+  | "E_IO_PATH"
+  | "E_IO_UNEXPECTED"
+  | "E_INPUT_INVALID"
+  | "E_RUNTIME_TOO_OLD";
+
+/**
+ * How to get a newer catherd. `bunx catherd-cli@latest` alone opens the newest one's dashboard and upgrades
+ * nothing that is installed (audit N12).
+ */
+export const UPGRADE = "bun add -g catherd-cli@latest (or run bunx catherd-cli@latest <command>)";
+
+/** Every failure catherd reports: a stable code, a message, and the exact action that fixes it. */
+export class CatherdError extends Error {
+  readonly code: ErrorCode;
+  readonly fix: string | undefined;
+
+  constructor(code: ErrorCode, message: string, opts: { fix?: string; cause?: unknown } = {}) {
+    super(message, opts.cause === undefined ? undefined : { cause: opts.cause });
+    this.name = "CatherdError";
+    this.code = code;
+    this.fix = opts.fix;
+  }
+
+  toJSON(): { code: ErrorCode; message: string; fix?: string } {
+    return this.fix === undefined
+      ? { code: this.code, message: this.message }
+      : { code: this.code, message: this.message, fix: this.fix };
+  }
+}
+
+export const isCatherdError = (e: unknown): e is CatherdError => e instanceof CatherdError;
+
+/** The message of anything thrown: an Error's message, else the value as a string. */
+export const errorMessage = (e: unknown): string => (e instanceof Error ? e.message : String(e));

package/src/domain/hints.ts

@@ -0,0 +1,22 @@
+import type { RunRecord } from "./record.ts";
+
+/** Spec §4.4: what the orchestrator does next, read off one finished record. `dir` is the dispatch folder, relative to the run. */
+export function dispatchHints(r: RunRecord, owns: string[], dir: string): string[] {
+  const h: string[] = [];
+  if (r.status === "limit") h.push(`limit: ${r.backend} hit a usage limit on ${r.rung}`);
+  if (r.status === "cli-too-old") h.push(`cli-too-old: ${r.error?.message ?? `upgrade ${r.backend}`}`);
+  if (r.status === "failed") h.push(`failed: read ${dir}/stderr`);
+  if (r.gitUnavailable) h.push("git-unavailable: changed files unknown");
+  if (r.replyStatus === "refused" || r.replyStatus === "blocked") h.push(`climb: ${r.replyStatus}`);
+  else if (
+    r.status === "ok" &&
+    !r.gitUnavailable &&
+    r.access !== "read-only" &&
+    owns.length > 0 &&
+    r.changedOwned.length === 0
+  )
+    h.push("climb: unchanged");
+  if (r.violations.length > 0) h.push(`violation: ${r.violations.join(", ")}`);
+  if (r.threadHeavy) h.push("thread-heavy");
+  return h;
+}

package/src/domain/ids.ts

@@ -0,0 +1,97 @@
+import { CatherdError } from "./errors.ts";
+
+/** Run, role, lane and dispatch ids end up in file names: no separator, no leading dot or dash. */
+export const ID_PATTERN = /^[A-Za-z0-9][\w.-]{0,127}$/;
+
+export function assertId(kind: string, value: string): string {
+  if (!ID_PATTERN.test(value) || value.includes(".."))
+    throw new CatherdError("E_ADMIT_ID", `bad ${kind} id "${value}"`, {
+      fix: "use letters, digits, '.', '_' and '-', starting with a letter or digit",
+    });
+  return value;
+}
+
+/** The backends that run as a process through a `BackendAdapter` (cursor and grok: plan 8). */
+export const ADAPTER_IDS = ["codex", "claude-code", "opencode", "cursor", "grok"] as const;
+
+/** `claude` is the native Claude Code subagent path (no process); the rest are adapters. */
+const RUNG_BACKENDS = [...ADAPTER_IDS, "claude"] as const;
+type RungBackend = (typeof RUNG_BACKENDS)[number];
+
+export interface Rung {
+  backend: RungBackend;
+  model: string;
+  effort: string;
+}
+
+/** A model id or effort starts with a letter or digit and holds no space, so it can never read as a flag. */
+const MODEL = /^[A-Za-z0-9][^\s#]*$/;
+const EFFORT = /^[A-Za-z0-9][\w-]*$/;
+
+export function parseRung(s: string): Rung {
+  const colon = s.indexOf(":");
+  const hash = s.lastIndexOf("#");
+  const backend = s.slice(0, Math.max(colon, 0));
+  const model = s.slice(colon + 1, hash);
+  const effort = s.slice(hash + 1);
+  if (
+    colon < 1 ||
+    hash <= colon + 1 ||
+    !MODEL.test(model) ||
+    !EFFORT.test(effort) ||
+    !(RUNG_BACKENDS as readonly string[]).includes(backend)
+  )
+    throw new CatherdError("E_ADMIT_RUNG", `bad rung "${s}"`, {
+      fix: "write it as <backend>:<model>#<effort>",
+    });
+  return { backend: backend as RungBackend, model, effort };
+}
+
+/** `parseRung`, or null for a malformed rung (profile validation is what reports it). */
+export function tryParseRung(s: string): Rung | null {
+  try {
+    return parseRung(s);
+  } catch {
+    return null;
+  }
+}
+
+export const formatRung = (r: Rung): string => `${r.backend}:${r.model}#${r.effort}`;
+
+const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+let lastTime = -1;
+let lastRand: number[] = [];
+
+/**
+ * A monotonic ULID: 10 chars of millisecond time, then 16 random, so ids sort by creation.
+ * Within one millisecond (or when the clock steps back) the previous time is reused and
+ * the random part is incremented, so ids made in one process are strictly increasing.
+ */
+export function newDispatchId(now: number = Date.now()): string {
+  if (now <= lastTime && increment(lastRand)) now = lastTime;
+  else {
+    if (now <= lastTime) now = lastTime + 1;
+    lastRand = Array.from(crypto.getRandomValues(new Uint8Array(16)), (b) => b % 32);
+  }
+  lastTime = now;
+  let t = now;
+  let time = "";
+  for (let i = 0; i < 10; i++) {
+    time = B32.charAt(t % 32) + time;
+    t = Math.floor(t / 32);
+  }
+  return time + lastRand.map((d) => B32.charAt(d)).join("");
+}
+
+/** Adds one to base32 digits in place; false when all 16 digits overflow. */
+function increment(digits: number[]): boolean {
+  for (let i = digits.length - 1; i >= 0; i--) {
+    if ((digits[i] as number) < 31) {
+      digits[i] = (digits[i] as number) + 1;
+      return true;
+    }
+    digits[i] = 0;
+  }
+  return false;
+}