@facilis.dev/db 0.0.0-stage → 0.1.0

package/src/schema-drift.ts

@@ -0,0 +1,234 @@
+import type { LivePolicySnapshot, LiveSchemaSnapshot, LiveTableSnapshot } from "./live-schema.ts";
+import type { PolicySnapshot, SchemaSnapshot, TableSnapshot } from "./snapshot.ts";
+
+/**
+ * Code↔live schema diff (SPEC §11.1): a pure comparison of the snapshot derived from
+ * `db/schema.ts` with the one read from the running database. The Studio renders the
+ * resulting entries; the release preview (SPEC §11.3) can reuse the same typed drift.
+ */
+
+export type SchemaDriftKind =
+  | "table_missing"
+  | "table_extra"
+  | "column_missing"
+  | "column_extra"
+  | "column_type"
+  | "column_nullability"
+  | "rls_disabled"
+  | "policy_missing"
+  | "policy_extra"
+  | "policy_changed";
+
+/**
+ * One difference. `expected` is the code-side value and `actual` the live one, so a
+ * consumer never has to guess which side of the diff it is looking at.
+ */
+export interface SchemaDrift {
+  kind: SchemaDriftKind;
+  table: string;
+  column?: string;
+  policy?: string;
+  expected?: string | null;
+  actual?: string | null;
+}
+
+/** Compare the code schema against the live one, deterministically ordered. */
+export function diffSchemaSnapshots(code: SchemaSnapshot, live: LiveSchemaSnapshot): SchemaDrift[] {
+  const liveTables = new Map(live.tables.map((table) => [table.name, table]));
+  const codeTables = new Set(code.tables.map((table) => table.name));
+  const drift: SchemaDrift[] = [];
+
+  for (const table of code.tables) {
+    const liveTable = liveTables.get(table.name);
+    if (liveTable === undefined) {
+      drift.push({ kind: "table_missing", table: table.name });
+      continue;
+    }
+    diffColumns(table, liveTable, drift);
+    // A scoped table without RLS is the one combo the security invariants forbid
+    // (SPEC §8.4.5); RLS off on an unscoped table is reported by the panel badge only.
+    if (table.scopeColumn !== undefined && !liveTable.rlsEnabled) {
+      drift.push({ kind: "rls_disabled", table: table.name });
+    }
+    diffPolicies(table, liveTable, drift);
+  }
+
+  for (const table of live.tables) {
+    if (!codeTables.has(table.name)) drift.push({ kind: "table_extra", table: table.name });
+  }
+
+  return drift.toSorted(compareDrift);
+}
+
+function diffColumns(
+  table: TableSnapshot,
+  liveTable: LiveTableSnapshot,
+  drift: SchemaDrift[],
+): void {
+  const liveColumns = new Map(liveTable.columns.map((column) => [column.name, column]));
+  for (const column of table.columns) {
+    const liveColumn = liveColumns.get(column.name);
+    if (liveColumn === undefined) {
+      drift.push({ kind: "column_missing", table: table.name, column: column.name });
+      continue;
+    }
+    const expectedType = canonicalColumnType(column.type);
+    const actualType = canonicalColumnType(liveColumn.type);
+    if (expectedType !== actualType) {
+      drift.push({
+        kind: "column_type",
+        table: table.name,
+        column: column.name,
+        expected: column.type,
+        actual: liveColumn.type,
+      });
+    }
+    if (column.notNull !== liveColumn.notNull) {
+      drift.push({
+        kind: "column_nullability",
+        table: table.name,
+        column: column.name,
+        expected: nullability(column.notNull),
+        actual: nullability(liveColumn.notNull),
+      });
+    }
+  }
+  const codeColumns = new Set(table.columns.map((column) => column.name));
+  for (const liveColumn of liveTable.columns) {
+    if (!codeColumns.has(liveColumn.name)) {
+      drift.push({ kind: "column_extra", table: table.name, column: liveColumn.name });
+    }
+  }
+}
+
+function diffPolicies(
+  table: TableSnapshot,
+  liveTable: LiveTableSnapshot,
+  drift: SchemaDrift[],
+): void {
+  const livePolicies = new Map(liveTable.policies.map((policy) => [policy.name, policy]));
+  const codePolicies = new Set(table.policies.map((policy) => policy.name));
+  for (const policy of table.policies) {
+    const livePolicy = livePolicies.get(policy.name);
+    if (livePolicy === undefined) {
+      drift.push({ kind: "policy_missing", table: table.name, policy: policy.name });
+      continue;
+    }
+    const expected = policySignature(policy);
+    const actual = livePolicySignature(livePolicy);
+    if (expected !== actual) {
+      drift.push({
+        kind: "policy_changed",
+        table: table.name,
+        policy: policy.name,
+        expected,
+        actual,
+      });
+    }
+  }
+  for (const livePolicy of liveTable.policies) {
+    if (!codePolicies.has(livePolicy.name)) {
+      drift.push({ kind: "policy_extra", table: table.name, policy: livePolicy.name });
+    }
+  }
+}
+
+function nullability(notNull: boolean): string {
+  return notNull ? "not null" : "nullable";
+}
+
+/** Code-side signature: command + permissiveness + rendered predicates. */
+function policySignature(policy: PolicySnapshot): string {
+  return [
+    policy.command.toUpperCase(),
+    isRestrictivePolicy(policy) ? "RESTRICTIVE" : "PERMISSIVE",
+    normalizePolicySql(policy.using),
+    normalizePolicySql(policy.withCheck),
+  ].join("|");
+}
+
+function livePolicySignature(policy: LivePolicySnapshot): string {
+  return [
+    policy.command.toUpperCase(),
+    policy.restrictive ? "RESTRICTIVE" : "PERMISSIVE",
+    normalizePolicySql(policy.using),
+    normalizePolicySql(policy.withCheck),
+  ].join("|");
+}
+
+/**
+ * Code-side permissiveness: `PolicySnapshot` keeps only the rendered SQL, so the flag is
+ * read from the `AS RESTRICTIVE` clause the generator emits (D-008).
+ */
+export function isRestrictivePolicy(policy: PolicySnapshot): boolean {
+  return /\bas\s+restrictive\b/i.test(policy.sql);
+}
+
+/**
+ * Postgres re-renders a policy's qualifier (adds parentheses and explicit `::text`
+ * casts), so raw SQL text never matches the Drizzle rendering even when the policies are
+ * identical. Compare a normalized form instead: lower-case, casts removed, quotes and
+ * parentheses dropped, whitespace collapsed away.
+ *
+ * Exported so the canonical schema digest (./schema-digest.ts) normalizes the same way
+ * instead of carrying a second copy.
+ */
+export function normalizePolicySql(value: string | null): string {
+  if (value === null) return "";
+  return value
+    .toLowerCase()
+    .replace(
+      /::(?:uuid|text|jsonb|json|integer|int4|int8|bigint|boolean|bool|numeric|date|timestamptz|timestamp(?: with(?:out)? time zone)?)\b/g,
+      "",
+    )
+    .replace(/["'()]/g, "")
+    .replace(/\s+/g, "");
+}
+
+const TYPE_ALIASES: Readonly<Record<string, string>> = {
+  serial: "integer",
+  serial4: "integer",
+  bigserial: "bigint",
+  serial8: "bigint",
+  smallserial: "smallint",
+  serial2: "smallint",
+  int: "integer",
+  int4: "integer",
+  int8: "bigint",
+  int2: "smallint",
+  bool: "boolean",
+  float4: "real",
+  float8: "double precision",
+  decimal: "numeric",
+  bpchar: "char",
+};
+
+/**
+ * Normalize both renderers onto one spelling: Drizzle says `varchar(120)`/`serial`,
+ * `format_type()` says `character varying(120)`/`integer`. Without this every column
+ * would look like drift.
+ */
+export function canonicalColumnType(value: string): string {
+  const array = value.trim().endsWith("[]") ? "[]" : "";
+  const bare = array === "[]" ? value.trim().slice(0, -2) : value.trim();
+  const type = bare
+    .toLowerCase()
+    .replace(/\bcharacter varying\b/g, "varchar")
+    .replace(/\bcharacter\b/g, "char")
+    // Only the "without" suffix is catalog-only: Drizzle renders no-tz columns as plain
+    // `timestamp`/`time`, while the catalog spells the default timezone out. Keeping
+    // "with time zone" makes a tz change a real type drift.
+    .replace(/\s+without\s+time zone\b/g, "")
+    .replace(/\s*,\s*/g, ",");
+  const base = /^([a-z][a-z0-9_]*)/.exec(type)?.[1] ?? type;
+  return (TYPE_ALIASES[base] ?? base) + type.slice(base.length) + array;
+}
+
+function compareDrift(left: SchemaDrift, right: SchemaDrift): number {
+  return (
+    left.table.localeCompare(right.table) ||
+    (left.column ?? "").localeCompare(right.column ?? "") ||
+    (left.policy ?? "").localeCompare(right.policy ?? "") ||
+    left.kind.localeCompare(right.kind)
+  );
+}

package/src/snapshot-readers.ts

@@ -0,0 +1,212 @@
+import { is, SQL } from "drizzle-orm";
+import { getTableConfig, PgDialect, PgTable, type PgColumn } from "drizzle-orm/pg-core";
+
+import { DEFAULT_OWNER_COLUMNS, DEFAULT_TENANT_COLUMNS } from "./client.ts";
+import { policyCreateSql } from "./rls.ts";
+import type {
+  ColumnSnapshot,
+  IndexSnapshot,
+  PolicyCommand,
+  ScopeColumnSnapshot,
+  TableSnapshot,
+  UnsupportedDeclarationSnapshot,
+} from "./snapshot.ts";
+
+/**
+ * The read half of the declared snapshot: Drizzle's table config -> the public shapes in
+ * ./snapshot.ts. Kept separate so the contract file stays a contract.
+ */
+
+const dialect = new PgDialect();
+
+export function snapshotTable(table: PgTable, enums: Map<string, string[]>): TableSnapshot {
+  const config = getTableConfig(table);
+  const primaryKey = primaryKeyColumns(config);
+  const columns = config.columns.map((column) => snapshotColumn(column, primaryKey, enums));
+  const unsupported: UnsupportedDeclarationSnapshot[] = [];
+  const indexes = config.indexes.map((index) => snapshotIndex(index, config.name, unsupported));
+  const snapshot: TableSnapshot = {
+    name: config.name,
+    rlsEnabled: config.enableRLS,
+    columns,
+    foreignKeys: config.foreignKeys.map((foreignKey) => {
+      const reference = foreignKey.reference();
+      const onDelete = toForeignKeyAction(foreignKey.onDelete);
+      const onUpdate = toForeignKeyAction(foreignKey.onUpdate);
+      return {
+        columns: reference.columns.map((column) => column.name),
+        targetTable: getTableConfig(reference.foreignTable).name,
+        targetColumns: reference.foreignColumns.map((column) => column.name),
+        ...(onDelete === undefined ? {} : { onDelete }),
+        ...(onUpdate === undefined ? {} : { onUpdate }),
+      };
+    }),
+    policies: config.policies.map((policy) => ({
+      name: policy.name,
+      command: (policy.for ?? "all").toUpperCase() as PolicyCommand,
+      using: policy.using === undefined ? null : dialect.sqlToQuery(policy.using).sql,
+      withCheck: policy.withCheck === undefined ? null : dialect.sqlToQuery(policy.withCheck).sql,
+      sql: policyCreateSql(config.name, policy),
+    })),
+    primaryKey,
+    indexes,
+    checks: config.checks.map((check) => ({
+      name: check.name,
+      expression: dialect.sqlToQuery(check.value).sql,
+    })),
+    uniqueConstraints: config.uniqueConstraints.map((constraint) => ({
+      name:
+        constraint.name ?? constraint.getName() ?? derivedUniqueName(config.name, constraint.columns),
+      columns: constraint.columns.map((column) => column.name),
+    })),
+  };
+
+  if (unsupported.length > 0) snapshot.unsupported = unsupported;
+  const scopeColumn = detectScopeColumn(columns.map((column) => column.name));
+  if (scopeColumn !== undefined) snapshot.scopeColumn = scopeColumn;
+  return snapshot;
+}
+
+/** The table's ordered PK: a table-level `primaryKey()` wins over column-level `.primaryKey()`. */
+function primaryKeyColumns(config: ReturnType<typeof getTableConfig>): string[] {
+  const tableLevel = config.primaryKeys[0];
+  if (tableLevel !== undefined) return tableLevel.columns.map((column) => column.name);
+  return config.columns.filter((column) => column.primary).map((column) => column.name);
+}
+
+function snapshotColumn(
+  column: PgColumn,
+  primaryKey: readonly string[],
+  enums: Map<string, string[]>,
+): ColumnSnapshot {
+  const snapshot: ColumnSnapshot = {
+    name: column.name,
+    type: column.getSQLType(),
+    notNull: column.notNull,
+    default: renderDefault(column.default),
+    // A composite (table-level) PK is declared on the table, not on its columns, so
+    // `column.primary` alone would disagree with the live catalog's indisprimary view.
+    isPrimaryKey: column.primary || primaryKey.includes(column.name),
+    isUnique: column.isUnique,
+  };
+  if (column.generatedIdentity !== undefined) snapshot.identity = column.generatedIdentity.type;
+  if (column.generated !== undefined) snapshot.generated = true;
+  const enumValues = column.enumValues;
+  if (enumValues !== undefined && enumValues.length > 0) {
+    recordEnum(enums, column.getSQLType().replace(/\[\]$/, ""), enumValues);
+  }
+  return snapshot;
+}
+
+/**
+ * Enum columns expose their values and their SQL type is the enum name (`mood` or
+ * `mood[]`). Two columns of the same enum must agree; a conflict is a broken declaration,
+ * so it throws instead of picking one.
+ */
+function recordEnum(enums: Map<string, string[]>, name: string, values: readonly string[]): void {
+  const existing = enums.get(name);
+  if (existing === undefined) {
+    enums.set(name, [...values]);
+    return;
+  }
+  if (existing.length !== values.length || existing.some((value, index) => value !== values[index])) {
+    throw new Error(
+      `schema declares enum "${name}" with conflicting values: [${existing.join(", ")}] vs [${values.join(", ")}]`,
+    );
+  }
+}
+
+/**
+ * Indexes are only representable when they are a plain (optionally unique) b-tree over
+ * plain columns; every other shape is recorded as unsupported rather than misrendered.
+ */
+function snapshotIndex(
+  index: ReturnType<typeof getTableConfig>["indexes"][number],
+  tableName: string,
+  unsupported: UnsupportedDeclarationSnapshot[],
+): IndexSnapshot {
+  const config = index.config;
+  const columns = config.columns.map(indexColumnName);
+  const name =
+    config.name ??
+    `${tableName}_${columns.filter((column): column is string => column !== null).join("_")}_${
+      config.unique ? "unique_" : ""
+    }idx`;
+  const unsupportedShape =
+    config.concurrently === true ||
+    config.only === true ||
+    config.where !== undefined ||
+    config.with !== undefined ||
+    (config.method !== undefined && config.method !== "btree") ||
+    columns.some((column) => column === null);
+  if (unsupportedShape) {
+    unsupported.push({ construct: "index", name });
+    return { name, columns: [], unique: config.unique };
+  }
+  return {
+    name,
+    columns: columns.filter((column): column is string => column !== null),
+    unique: config.unique,
+  };
+}
+
+/** An index member that is not a plain ordered column returns null (unsupported shape). */
+function indexColumnName(column: unknown): string | null {
+  if (typeof column !== "object" || column === null) return null;
+  const candidate = column as {
+    name?: unknown;
+    indexConfig?: { order?: unknown; nulls?: unknown; opClass?: unknown };
+  };
+  if (typeof candidate.name !== "string" || candidate.name.length === 0) return null;
+  const extra = candidate.indexConfig;
+  // Drizzle fills the ascending defaults explicitly (`asc`/`last`); anything else is a
+  // shape the plain-column rendering below would silently drop.
+  const unsupported =
+    extra !== undefined &&
+    ((extra.order !== undefined && extra.order !== "asc") ||
+      (extra.nulls !== undefined && extra.nulls !== "last") ||
+      extra.opClass !== undefined);
+  return unsupported ? null : candidate.name;
+}
+
+function derivedUniqueName(tableName: string, columns: readonly { name: string }[]): string {
+  return `${tableName}_${columns.map((column) => column.name).join("_")}_unique`;
+}
+
+/**
+ * SPEC §7.3 does not model SQL's SET DEFAULT, and "no action" is Postgres' default, so
+ * both are omitted rather than invented or echoed as noise.
+ */
+function toForeignKeyAction(
+  action: "cascade" | "restrict" | "no action" | "set null" | "set default" | undefined,
+): "cascade" | "set null" | "restrict" | undefined {
+  switch (action) {
+    case "cascade":
+    case "restrict":
+    case "set null":
+      return action;
+    default:
+      return undefined;
+  }
+}
+
+function renderDefault(value: PgColumn["default"]): string | null {
+  if (value === undefined) return null;
+  if (is(value, SQL)) return dialect.sqlToQuery(value).sql;
+  if (typeof value === "string") return quoteLiteral(value);
+  if (value instanceof Date) return quoteLiteral(value.toISOString());
+  if (typeof value === "object" && value !== null) return JSON.stringify(value);
+  return String(value);
+}
+
+function detectScopeColumn(columnNames: readonly string[]): ScopeColumnSnapshot | undefined {
+  const tenant = columnNames.find((name) => DEFAULT_TENANT_COLUMNS.includes(name));
+  if (tenant !== undefined) return { name: tenant, kind: "tenant" };
+  const owner = columnNames.find((name) => DEFAULT_OWNER_COLUMNS.includes(name));
+  if (owner !== undefined) return { name: owner, kind: "owner" };
+  return undefined;
+}
+
+function quoteLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}

package/src/snapshot.ts

@@ -0,0 +1,122 @@
+import { is } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+
+import type { FacilisDb } from "./client.ts";
+import { snapshotTable } from "./snapshot-readers.ts";
+
+/** SPEC §7.3 taxonomy. Core re-exports these types as the manifest contract. */
+export type PolicyCommand = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL";
+
+export interface PolicySnapshot {
+  name: string;
+  command: PolicyCommand;
+  using: string | null;
+  withCheck: string | null;
+  sql: string;
+}
+
+export interface ColumnSnapshot {
+  name: string;
+  type: string;
+  notNull: boolean;
+  default: string | null;
+  isPrimaryKey: boolean;
+  isUnique: boolean;
+  /**
+   * Identity columns are readable but not renderable by the v1 generator
+   * (`GENERATED ... AS IDENTITY` sequence options are lost in this projection), so the
+   * flag is carried and the P2 planner refuses instead of writing a plain column.
+   */
+  identity?: "always" | "byDefault";
+  /** Generated/computed columns: same fail-closed treatment, no faithful v1 DDL. */
+  generated?: true;
+}
+
+export interface ForeignKeySnapshot {
+  columns: string[];
+  targetTable: string;
+  targetColumns: string[];
+  onDelete?: "cascade" | "set null" | "restrict" | "no action";
+  onUpdate?: "cascade" | "set null" | "restrict" | "no action";
+}
+
+export interface IndexSnapshot {
+  name: string;
+  /** Plain column names only; any other index shape lands in `unsupported`. */
+  columns: string[];
+  unique: boolean;
+}
+
+export interface CheckSnapshot {
+  name: string;
+  /** Rendered with PgDialect, like `default`; columns may stay table-qualified. */
+  expression: string;
+}
+
+/** A table-level `unique()`, distinct from a column's `isUnique`. */
+export interface UniqueConstraintSnapshot {
+  name: string;
+  columns: string[];
+}
+
+export interface EnumSnapshot {
+  name: string;
+  values: string[];
+}
+
+/**
+ * A declaration the snapshot can read but the v1 shapes above cannot represent (expression,
+ * partial or method-specific indexes; `ON DELETE SET DEFAULT`). It is carried, never
+ * dropped, so the P2 generator can fail the release closed instead of silently ignoring it
+ * (D-158: an unsupported declaration fails the release, never degrades silently).
+ */
+export interface UnsupportedDeclarationSnapshot {
+  construct: "index" | "foreign_key";
+  name: string;
+}
+
+export interface ScopeColumnSnapshot {
+  name: string;
+  kind: "tenant" | "owner";
+}
+
+export interface TableSnapshot {
+  name: string;
+  rlsEnabled: boolean;
+  columns: ColumnSnapshot[];
+  foreignKeys: ForeignKeySnapshot[];
+  policies: PolicySnapshot[];
+  scopeColumn?: ScopeColumnSnapshot;
+  /** Ordered column names of the primary key; empty when the table has none. */
+  primaryKey?: string[];
+  indexes?: IndexSnapshot[];
+  checks?: CheckSnapshot[];
+  uniqueConstraints?: UniqueConstraintSnapshot[];
+  unsupported?: UnsupportedDeclarationSnapshot[];
+}
+
+export interface SchemaSnapshot {
+  tables: TableSnapshot[];
+  /** Enum types referenced by columns, deduped by name. */
+  enums?: EnumSnapshot[];
+}
+
+/**
+ * Derives the SPEC §7.3 schema snapshot from the Drizzle schema namespace passed to
+ * `createDb`. No database round-trip: the code schema is the source of truth, as in
+ * SPEC §11.1's code↔live comparison.
+ */
+export async function schemaSnapshot(db: FacilisDb): Promise<SchemaSnapshot> {
+  const enums = new Map<string, string[]>();
+  const tables = Object.values(db.schema)
+    .filter((value): value is PgTable => is(value, PgTable))
+    .map((table) => snapshotTable(table, enums))
+    .toSorted((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    tables,
+    enums: [...enums.entries()]
+      .map(([name, values]) => ({ name, values }))
+      .toSorted((left, right) => left.name.localeCompare(right.name)),
+  };
+}

package/src/sudo-audit.ts

@@ -0,0 +1,91 @@
+/**
+ * Sudo audit trail (D-099).
+ *
+ * A sudo escalation is recorded on a dedicated, append-only sink, never in the database:
+ * the trail must survive the transaction rollback it describes, and the framework has no
+ * update/delete operation for it. The default sink is stdout (one JSON line per event) so a
+ * deploy's log platform can ship it to WORM/retention storage; tests swap the sink.
+ *
+ * Fail closed: if the sink throws, the escalation must not happen, so writeSudoAudit throws
+ * a SudoAuditUnavailableError and the caller refuses to switch roles.
+ */
+
+export type SudoAuditEventName = "started" | "succeeded" | "failed";
+
+/** One immutable audit entry. `id` is shared by every entry of the same sudo call. */
+export interface SudoAuditEvent {
+  readonly event: SudoAuditEventName;
+  /** Shared call id; also written to the app.sudo_id GUC while the role is elevated. */
+  readonly id: string;
+  /** ISO-8601 timestamp of the append (not of the call start). */
+  readonly at: string;
+  /** Acting user id; absent for a system job (actor is the label). */
+  readonly actorUserId?: string;
+  /** "user:<id>" for a route session, "system:<job>" for a job/CLI caller. */
+  readonly actor: string;
+  /** SHA-256 of the session id; the raw cookie/token is never logged. */
+  readonly sessionHash?: string;
+  readonly roles: readonly string[];
+  readonly tenantId?: string;
+  /** Request pathname, e.g. "/api/order-requests". */
+  readonly route?: string;
+  /** Request method, when known. */
+  readonly method?: string;
+  /** The route's declared permission (the first one), for context. */
+  readonly permission?: string;
+  readonly operation: string;
+  readonly reason: string;
+  readonly tables: readonly string[];
+  /** Succeeded entries: the declared tables the elevated callback actually reached (D-157). */
+  readonly observedTables?: readonly string[];
+  readonly requestId?: string;
+  /** Terminal entries only: how the elevated block ended. */
+  readonly outcome?: "succeeded" | "failed";
+  /** Terminal failure entries: canonical code, never the internal message. */
+  readonly errorCode?: string;
+  readonly durationMs?: number;
+}
+
+/** Appends one entry. Synchronous by design: a sink cannot silently promise to log later. */
+export type SudoAuditSink = (event: SudoAuditEvent) => void;
+
+/** Thrown when the audit sink is not writable; sudo refuses to escalate untraced. */
+export class SudoAuditUnavailableError extends Error {
+  readonly code = "sudo_audit_unavailable";
+
+  constructor(cause: unknown) {
+    super("The sudo audit sink is not writable; refusing to escalate a database call.", { cause });
+    this.name = "SudoAuditUnavailableError";
+  }
+}
+
+/** New call id: WebCrypto randomUUID (available in Node and the browser VM alike). */
+export function newSudoId(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+const consoleSink: SudoAuditSink = (event): void => {
+  // oxlint-disable-next-line no-console -- the default audit sink IS stdout: one JSON line per entry for the deploy's log pipeline.
+  console.log("facilis:sudo " + JSON.stringify(event));
+};
+
+let sink: SudoAuditSink = consoleSink;
+
+/** Replaces the process-wide sink (tests/tooling). Production leaves the stdout default. */
+export function setSudoAuditSink(next: SudoAuditSink): void {
+  sink = next;
+}
+
+/** Restores the default stdout sink. */
+export function resetSudoAuditSink(): void {
+  sink = consoleSink;
+}
+
+/** Append one entry, failing closed: a broken sink throws instead of dropping the trail. */
+export function writeSudoAudit(event: SudoAuditEvent): void {
+  try {
+    sink(event);
+  } catch (cause) {
+    throw new SudoAuditUnavailableError(cause);
+  }
+}