okengine 0.14.1 → 0.15.2

package/src/drivers/pg-rls.ts

@@ -1,5 +1,6 @@
 /**
- * Postgres row-level security — identifiers and `CREATE POLICY` SQL.
+ * Postgres row-level security — identifiers, `CREATE POLICY` SQL,
+ * Drizzle emit, and Gate identity helpers (`oke.gate` / `oke.user` / `oke.has_scope`).
  */
 
 /** Policy command (`FOR`). */
@@ -31,6 +32,110 @@ export type SqlPolicyAlterSpec = {
 const POLICY_COMMANDS = new Set<string>(["ALL", "SELECT", "INSERT", "UPDATE", "DELETE"]);
 const POLICY_BEHAVIORS = new Set<string>(["PERMISSIVE", "RESTRICTIVE"]);
 
+/** Drizzle / Postgres `TO` targets that must not be quoted. */
+const SPECIAL_POLICY_ROLES = new Set(["public", "current_role", "current_user", "session_user"]);
+
+/** Drivers that honor `SET LOCAL row_security` + `oke.*` GUCs. */
+export const RLS_CONTEXT_DRIVERS = new Set<string>(["postgres", "pglite"]);
+
+/**
+ * Non-superuser role the stamp `SET LOCAL ROLE`s into so RLS applies.
+ * Table owners and PGlite's `postgres` superuser otherwise bypass policies.
+ */
+export const OKE_RLS_ROLE = "oke_app";
+
+/** Live Gate principal stamped onto a SQL statement. */
+export type RlsIdentity = {
+  readonly gate: string;
+  readonly userId: string;
+  readonly scopes: readonly string[];
+};
+
+/**
+ * One statement at a time — Bun.SQL `unsafe` / PGlite `query` reject
+ * multi-command batches. Safe to run repeatedly.
+ */
+export const OKE_RLS_HELPER_STATEMENTS: readonly string[] = [
+  "CREATE SCHEMA IF NOT EXISTS oke",
+  // DB user is often `oke` — default search_path `"$user", public` then
+  // creates unqualified tables in schema `oke`. Domain tables belong in public.
+  "SET search_path TO public, oke",
+  `DO $oke_search_path$
+BEGIN
+  EXECUTE 'ALTER ROLE CURRENT_USER SET search_path TO public, oke';
+EXCEPTION
+  WHEN others THEN NULL;
+END
+$oke_search_path$`,
+  `DO $oke_rehome$
+DECLARE r record;
+BEGIN
+  FOR r IN
+    SELECT c.relname AS name
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'oke' AND c.relkind = 'r'
+  LOOP
+    IF NOT EXISTS (
+      SELECT 1
+      FROM pg_class c2
+      JOIN pg_namespace n2 ON n2.oid = c2.relnamespace
+      WHERE n2.nspname = 'public' AND c2.relname = r.name AND c2.relkind = 'r'
+    ) THEN
+      EXECUTE format('ALTER TABLE oke.%I SET SCHEMA public', r.name);
+    END IF;
+  END LOOP;
+END
+$oke_rehome$`,
+  `CREATE OR REPLACE FUNCTION oke.gate() RETURNS text
+LANGUAGE sql STABLE AS $$ SELECT current_setting('oke.gate', true) $$`,
+  `CREATE OR REPLACE FUNCTION oke.user() RETURNS text
+LANGUAGE sql STABLE AS $$ SELECT current_setting('oke.user', true) $$`,
+  `CREATE OR REPLACE FUNCTION oke.has_scope(p_scope text) RETURNS boolean
+LANGUAGE sql STABLE AS $$
+  SELECT CASE
+    WHEN current_setting('oke.scopes', true) IN ('') THEN false
+    ELSE jsonb_exists(current_setting('oke.scopes', true)::jsonb, p_scope)
+  END
+$$`,
+  `DO $oke_rls_role$
+BEGIN
+  CREATE ROLE ${OKE_RLS_ROLE} NOSUPERUSER NOBYPASSRLS NOLOGIN;
+EXCEPTION
+  WHEN duplicate_object THEN NULL;
+END
+$oke_rls_role$`,
+  `GRANT USAGE ON SCHEMA public TO ${OKE_RLS_ROLE}`,
+  `GRANT USAGE ON SCHEMA oke TO ${OKE_RLS_ROLE}`,
+  `GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA oke TO ${OKE_RLS_ROLE}`,
+  `GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ${OKE_RLS_ROLE}`,
+  `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${OKE_RLS_ROLE}`,
+  `GRANT ${OKE_RLS_ROLE} TO CURRENT_USER`,
+  `DO $oke_app_search_path$
+BEGIN
+  EXECUTE 'ALTER ROLE ${OKE_RLS_ROLE} SET search_path TO public, oke';
+EXCEPTION
+  WHEN others THEN NULL;
+END
+$oke_app_search_path$`,
+];
+
+/**
+ * All {@link OKE_RLS_HELPER_STATEMENTS} as one script (PGlite `exec` / `oke db push`).
+ */
+export const OKE_RLS_HELPER_SQL = `${OKE_RLS_HELPER_STATEMENTS.join(";\n")};`;
+
+/**
+ * Install `oke.*` helpers one statement at a time.
+ *
+ * @param exec - Statement runner
+ */
+export async function installOkeRlsHelpers(exec: (sql: string) => Promise<unknown>): Promise<void> {
+  for (const stmt of OKE_RLS_HELPER_STATEMENTS) {
+    await exec(stmt);
+  }
+}
+
 /**
  * Quote a Postgres identifier (`"`), stripping embedded quotes.
  *
@@ -102,11 +207,38 @@ export function parseSqlPolicyRoles(raw: string): readonly string[] | null {
     .filter((part) => part.length > 0);
   if (parts.length === 0) return ["public"];
   for (const part of parts) {
-    if (part !== "public" && !isPgIdent(part)) return null;
+    if (!isPolicyRoleName(part)) return null;
   }
   return parts;
 }
 
+/**
+ * True when `name` is `public`, a Drizzle special role, or a simple identifier.
+ *
+ * @param name - Role token
+ */
+export function isPolicyRoleName(name: string): boolean {
+  return SPECIAL_POLICY_ROLES.has(name.toLowerCase()) || isPgIdent(name);
+}
+
+/**
+ * Format a `TO` role — special names stay unquoted.
+ *
+ * @param role - Role token
+ */
+export function formatPolicyRole(role: string): string {
+  return SPECIAL_POLICY_ROLES.has(role.toLowerCase()) ? role.toLowerCase() : quotePgIdent(role);
+}
+
+/**
+ * JSON text stored in `oke.scopes` (sorted unique).
+ *
+ * @param scopes - Scope strings
+ */
+export function rlsScopesJson(scopes: readonly string[]): string {
+  return JSON.stringify([...new Set(scopes)].sort());
+}
+
 /**
  * `CREATE POLICY` from a validated spec.
  *
@@ -116,7 +248,7 @@ export function buildCreatePolicySql(spec: SqlPolicySpec): string {
   const roles =
     spec.roles.length === 0
       ? "public"
-      : spec.roles.map((role) => (role === "public" ? "public" : quotePgIdent(role))).join(", ");
+      : spec.roles.map((role) => formatPolicyRole(role)).join(", ");
   let text = `CREATE POLICY ${quotePgIdent(spec.name)} ON ${quotePgIdent(spec.table)} AS ${spec.behavior} FOR ${spec.command} TO ${roles}`;
   if (spec.using !== undefined && spec.using.trim() !== "") {
     text += ` USING (${spec.using.trim()})`;
@@ -153,7 +285,7 @@ export function buildAlterPolicySql(spec: SqlPolicyAlterSpec): string {
     const roles =
       spec.roles.length === 0
         ? "public"
-        : spec.roles.map((role) => (role === "public" ? "public" : quotePgIdent(role))).join(", ");
+        : spec.roles.map((role) => formatPolicyRole(role)).join(", ");
     parts.push(`TO ${roles}`);
   }
   if (spec.using !== undefined && spec.using.trim() !== "") {
@@ -189,9 +321,9 @@ export function parseSqlPolicySpec(raw: Readonly<Record<string, unknown>>): SqlP
   const table = typeof raw.table === "string" ? raw.table.trim() : "";
   if (!isPgPolicyName(name)) throw new Error(`invalid policy name "${name}"`);
   if (!isPgIdent(table)) throw new Error(`invalid table name "${table}"`);
-  const command = parseSqlPolicyCommand(raw.command) ?? "SELECT";
-  const behavior = parseSqlPolicyBehavior(raw.behavior ?? raw.permissive) ?? "PERMISSIVE";
-  const rolesRaw = typeof raw.roles === "string" ? raw.roles : "public";
+  const command = parseSqlPolicyCommand(raw.command) ?? parseSqlPolicyCommand(raw.for) ?? "SELECT";
+  const behavior = parseSqlPolicyBehavior(raw.behavior ?? raw.permissive ?? raw.as) ?? "PERMISSIVE";
+  const rolesRaw = rolesField(raw.roles ?? raw.to);
   const roles = parseSqlPolicyRoles(rolesRaw);
   if (!roles) throw new Error("invalid policy roles");
   const using = typeof raw.using === "string" ? raw.using.trim() : "";
@@ -232,3 +364,97 @@ export function parseSqlPolicyRowId(id: string): { readonly table: string; reado
   }
   return { table: id.slice(0, cut), name: id.slice(cut + 1) };
 }
+
+function rolesField(raw: unknown): string {
+  if (typeof raw === "string") return raw;
+  if (Array.isArray(raw)) {
+    return raw.filter((part): part is string => typeof part === "string").join(", ");
+  }
+  return "public";
+}
+
+/**
+ * Drizzle `pgPolicy(...)` source for emit / Console copy-as-code.
+ *
+ * @param spec - Validated policy
+ */
+export function emitPgPolicySource(spec: SqlPolicySpec): string {
+  const to =
+    spec.roles.length === 1
+      ? JSON.stringify(formatEmitRole(spec.roles[0]!))
+      : `[${spec.roles.map((role) => JSON.stringify(formatEmitRole(role))).join(", ")}]`;
+  const lines = [
+    `pgPolicy(${JSON.stringify(spec.name)}, {`,
+    `  as: ${JSON.stringify(spec.behavior.toLowerCase())},`,
+    `  to: ${to},`,
+    `  for: ${JSON.stringify(spec.command.toLowerCase())},`,
+  ];
+  if (spec.using !== undefined && spec.using.trim() !== "") {
+    lines.push(`  using: sql\`${escapeSqlTemplate(spec.using.trim())}\`,`);
+  }
+  if (spec.withCheck !== undefined && spec.withCheck.trim() !== "") {
+    lines.push(`  withCheck: sql\`${escapeSqlTemplate(spec.withCheck.trim())}\`,`);
+  }
+  lines.push(`})`);
+  return lines.join("\n");
+}
+
+/**
+ * `store.schema.policy(...)` source for Console copy-as-code.
+ *
+ * @param spec - Validated policy
+ */
+export function emitStoreSchemaPolicySource(spec: SqlPolicySpec): string {
+  const to =
+    spec.roles.length === 1
+      ? JSON.stringify(formatEmitRole(spec.roles[0]!))
+      : `[${spec.roles.map((role) => JSON.stringify(formatEmitRole(role))).join(", ")}]`;
+  const lines = [
+    `store.schema.policy(${JSON.stringify(spec.name)}, {`,
+    `  as: ${JSON.stringify(spec.behavior.toLowerCase())},`,
+    `  to: ${to},`,
+    `  for: ${JSON.stringify(spec.command.toLowerCase())},`,
+  ];
+  if (spec.using !== undefined && spec.using.trim() !== "") {
+    lines.push(`  using: ${JSON.stringify(spec.using.trim())},`);
+  }
+  if (spec.withCheck !== undefined && spec.withCheck.trim() !== "") {
+    lines.push(`  withCheck: ${JSON.stringify(spec.withCheck.trim())},`);
+  }
+  lines.push(`})`);
+  return lines.join("\n");
+}
+
+function formatEmitRole(role: string): string {
+  return SPECIAL_POLICY_ROLES.has(role.toLowerCase()) ? role.toLowerCase() : role;
+}
+
+function escapeSqlTemplate(expr: string): string {
+  return expr.replaceAll("\\", "\\\\").replaceAll("`", "\\`");
+}
+
+/** One statement in the RLS identity prelude (never a multi-command batch). */
+export type RlsPreludeStatement = {
+  readonly sql: string;
+  readonly params?: readonly string[];
+};
+
+/**
+ * Per-statement identity frame (no user SQL, no `BEGIN`).
+ *
+ * The caller pins these to one backend connection via `SqlConnection.transaction`.
+ * PGlite's `query` path is prepared statements and rejects `BEGIN; SET; SELECT`
+ * as one script.
+ *
+ * @param identity - Gate principal
+ */
+export function buildRlsIdentityPreludeSql(identity: RlsIdentity): readonly RlsPreludeStatement[] {
+  return [
+    { sql: `SET LOCAL ROLE ${OKE_RLS_ROLE}` },
+    { sql: "SET LOCAL row_security = on" },
+    {
+      sql: `SELECT set_config('oke.gate', ?, true), set_config('oke.user', ?, true), set_config('oke.scopes', ?, true)`,
+      params: [identity.gate, identity.userId, rlsScopesJson(identity.scopes)],
+    },
+  ];
+}

package/src/drivers/pglite.ts

@@ -77,21 +77,44 @@ export async function connectPglite(options: SqlConnectOptions = {}): Promise<Sq
     resolved === "memory"
       ? await PGlite.create({ extensions: { vector } })
       : await PGlite.create(resolved, { extensions: { vector } });
-  return {
+  const connection: SqlConnection = {
     driverId: "pglite",
     role,
     async query(sql, params = []) {
-      const rs = await db.query<SqlRow>(toPostgresParams(sql), [...params]);
+      const rs = await db.query<SqlRow>(toPostgresParams(sql, params), [...params]);
       return rs.rows;
     },
     async exec(sql, params = []) {
-      const rs = await db.query<SqlRow>(toPostgresParams(sql), [...params]);
+      // Prepared `query` rejects multi-command scripts (`BEGIN; SET; …`).
+      // Param-less SQL uses simple-protocol `exec` (helpers, BEGIN, SET).
+      if (params.length === 0) {
+        const results = await db.exec(sql);
+        const last = results[results.length - 1];
+        return { changes: last?.affectedRows ?? 0 };
+      }
+      const rs = await db.query<SqlRow>(toPostgresParams(sql, params), [...params]);
       return { changes: rs.affectedRows ?? 0 };
     },
+    async transaction(fn) {
+      await db.exec("BEGIN");
+      try {
+        const result = await fn(connection);
+        await db.exec("COMMIT");
+        return result;
+      } catch (err) {
+        try {
+          await db.exec("ROLLBACK");
+        } catch {
+          // Already aborted.
+        }
+        throw err;
+      }
+    },
     async close() {
       await db.close();
     },
   };
+  return connection;
 }
 
 /** Protocol-named pglite driver. */

package/src/drivers/postgres.test.ts

@@ -0,0 +1,23 @@
+/**
+ * Postgres placeholder conversion.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { toPostgresParams } from "./postgres.ts";
+
+describe("toPostgresParams", () => {
+  test("rewrites ? only when values are bound", () => {
+    expect(toPostgresParams("SELECT * FROM t WHERE id = ?", ["a"])).toBe(
+      "SELECT * FROM t WHERE id = $1",
+    );
+    expect(toPostgresParams("INSERT INTO t (a, b) VALUES (?, ?)", [1, 2])).toBe(
+      "INSERT INTO t (a, b) VALUES ($1, $2)",
+    );
+  });
+
+  test("leaves jsonb ? operators unchanged when there are no values", () => {
+    const sql = "SELECT current_setting('oke.scopes', true)::jsonb ? p_scope";
+    expect(toPostgresParams(sql)).toBe(sql);
+    expect(toPostgresParams(sql, [])).toBe(sql);
+  });
+});

package/src/drivers/postgres.ts

@@ -4,7 +4,13 @@
  * Protocol-named: Neon, Supabase, RDS, Timescale all speak postgres.
  */
 
-import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRow } from "./types.ts";
+import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRole, SqlRow } from "./types.ts";
+
+/** Bun.SQL client checked out via {@link PostgresClientLike.reserve}. */
+export interface PostgresReservedClient extends PostgresClientLike {
+  /** Return the connection to the pool. */
+  release(): void;
+}
 
 /** Minimal surface we use from Bun.SQL (and test fakes). */
 export interface PostgresClientLike {
@@ -12,15 +18,98 @@ export interface PostgresClientLike {
     sql: string,
     values?: unknown[],
   ): PromiseLike<SqlRow[] | { length: number; changes?: number } | SqlRow[]>;
+  /**
+   * Pin one pooled TCP connection. Required in front of PgDog — `begin()`
+   * then `unsafe()` on the parent client can checkout a second slot and
+   * deadlock the pool (`checkout timeout`).
+   */
+  reserve?(): Promise<PostgresReservedClient>;
+  /**
+   * Reserve one pooled connection for a transaction (Bun.SQL).
+   *
+   * @param fn - Work on the reserved client
+   */
+  begin?<T>(fn: (tx: PostgresClientLike) => Promise<T> | T): Promise<T>;
   close?(options?: { timeout?: number }): Promise<void>;
 }
 
+/** Cap shared Bun.SQL pools so one process cannot outrun PgDog (default 10). */
+export const POSTGRES_POOL_MAX = 8;
+
+const sharedClients = new Map<string, PostgresClientLike>();
+
+/**
+ * Resolve the Postgres URL (injected, `DATABASE_URL`, then localhost).
+ *
+ * @param url - Explicit URL
+ */
+export function resolvePostgresUrl(url?: string): string {
+  return url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke";
+}
+
+/**
+ * One Bun.SQL pool per URL for store / journal / clock / vault / console.
+ *
+ * @param url - Connection URL
+ */
+export function sharedPostgresClient(url?: string): PostgresClientLike {
+  const key = resolvePostgresUrl(url);
+  const existing = sharedClients.get(key);
+  if (existing) return existing;
+  const created = new Bun.SQL(key, { max: POSTGRES_POOL_MAX }) as unknown as PostgresClientLike;
+  sharedClients.set(key, created);
+  return created;
+}
+
+/**
+ * Pin one pooled connection, `BEGIN`, run `fn`, `COMMIT`/`ROLLBACK`, release.
+ *
+ * Prefer `reserve()` — Bun.SQL `begin()` then `unsafe()` on the parent
+ * client can checkout a second slot and deadlock PgDog.
+ *
+ * @param client - Pool or test fake
+ * @param fn - Work on the pinned client
+ */
+export async function withPinnedPostgres<T>(
+  client: PostgresClientLike,
+  fn: (tx: PostgresClientLike) => Promise<T>,
+): Promise<T> {
+  if (typeof client.reserve === "function") {
+    const reserved = await client.reserve();
+    try {
+      await reserved.unsafe("BEGIN");
+      try {
+        const result = await fn(reserved);
+        await reserved.unsafe("COMMIT");
+        return result;
+      } catch (err) {
+        try {
+          await reserved.unsafe("ROLLBACK");
+        } catch {
+          // Already aborted.
+        }
+        throw err;
+      }
+    } finally {
+      reserved.release();
+    }
+  }
+  if (typeof client.begin === "function") {
+    return client.begin(fn);
+  }
+  throw new Error("postgres client needs reserve() or begin() to pin a transaction");
+}
+
 /**
  * Convert `?` placeholders to Postgres `$1…$n`.
+ * Leaves SQL unchanged when there are no bound values so operators
+ * like `jsonb ? key` are not rewritten.
  *
  * @param sql - SQL with `?` placeholders
+ * @param values - Bound values (empty skips conversion)
  */
-export function toPostgresParams(sql: string): string {
+export function toPostgresParams(sql: string, values: readonly unknown[] = []): string {
+  if (values.length === 0) return sql;
   let i = 0;
   return sql.replace(/\?/g, () => `$${++i}`);
 }
@@ -32,21 +121,34 @@ export function toPostgresParams(sql: string): string {
  */
 export async function connectPostgres(options: SqlConnectOptions = {}): Promise<SqlConnection> {
   const role = options.role ?? "primary";
-  const client =
-    (options.client as PostgresClientLike | undefined) ??
-    new Bun.SQL(options.url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke");
+  const injected = options.client as PostgresClientLike | undefined;
+  const client = injected ?? sharedPostgresClient(options.url);
+  return wrapPostgresClient(client, role, { shared: injected === undefined });
+}
 
-  return {
+/**
+ * Bind a Bun.SQL-compatible client as {@link SqlConnection}.
+ *
+ * @param client - Pool or reserved transaction client
+ * @param role - Primary vs replica
+ * @param opts - Shared-pool / already-pinned flags
+ */
+function wrapPostgresClient(
+  client: PostgresClientLike,
+  role: SqlRole,
+  opts: { readonly shared?: boolean; readonly pinned?: boolean } = {},
+): SqlConnection {
+  const connection: SqlConnection = {
     driverId: "postgres",
     role,
     async query(sql, params = []) {
-      const pg = toPostgresParams(sql);
+      const pg = toPostgresParams(sql, params);
       const result = await client.unsafe(pg, [...params]);
       if (Array.isArray(result)) return result as SqlRow[];
       return Array.from(result as ArrayLike<SqlRow>);
     },
     async exec(sql, params = []) {
-      const pg = toPostgresParams(sql);
+      const pg = toPostgresParams(sql, params);
       const result = await client.unsafe(pg, [...params]);
       if (
         result &&
@@ -61,10 +163,15 @@ export async function connectPostgres(options: SqlConnectOptions = {}): Promise<
       }
       return { changes: 0 };
     },
+    async transaction(fn) {
+      if (opts.pinned) return fn(connection);
+      return withPinnedPostgres(client, (tx) => fn(wrapPostgresClient(tx, role, { pinned: true })));
+    },
     async close() {
-      await client.close?.();
+      if (!opts.shared) await client.close?.();
     },
   };
+  return connection;
 }
 
 /**
@@ -82,10 +189,27 @@ export function createPostgresFakeClient(): PostgresClientLike & {
 
   return {
     tables,
+    async begin(fn) {
+      return fn(this);
+    },
+    async reserve() {
+      return Object.assign(this, {
+        release() {
+          /* fake has no pool */
+        },
+      });
+    },
     async unsafe(sql, values = []) {
       const text = sql.trim();
       // Accept both ? (pre-conversion) and $n forms.
       const normalised = text.replace(/\$\d+/g, "?");
+      if (
+        /^(begin|commit|rollback|set\b|select set_config|create\b|grant\b|do\b|alter\b)\b/i.test(
+          normalised,
+        )
+      ) {
+        return [];
+      }
 
       const create =
         /^CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+("?[a-zA-Z_][a-zA-Z0-9_]*"?)\s*\((.+)\)\s*$/i.exec(

package/src/drivers/types.ts

@@ -62,6 +62,16 @@ export interface SqlConnection {
    * @param params - Bound parameters
    */
   exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+  /**
+   * Pin `fn` to one backend connection for a single transaction.
+   *
+   * Required for `SET LOCAL` RLS stamps on pooled `postgres` (Bun.SQL /
+   * PgDog transaction mode). A standalone `BEGIN` via {@link exec} returns
+   * the connection to the pool still in a transaction and exhausts checkout.
+   *
+   * @param fn - Work that must share the reserved connection
+   */
+  transaction?<T>(fn: (tx: SqlConnection) => Promise<T>): Promise<T>;
   /** Close the connection. */
   close(): Promise<void>;
 }

package/src/elements/clock/declare.ts

@@ -5,6 +5,8 @@
  * the effective state from the Store (console §5), never the code directly.
  */
 
+import { clockRegistry } from "../../kernel/element-registries.ts";
+
 /** Options for {@link clock}. */
 export interface ClockOptions {
   /** Cron expression (`m h dom mon dow`). */
@@ -40,6 +42,27 @@ export interface ClockDecl {
   readonly description?: string;
 }
 
+/**
+ * `clock()` pushes into the shared {@link clockRegistry}
+ * (`src/kernel/element-registries.ts`) so {@link oke} can auto-populate
+ * `clocks` with zero explicit array — mirrors the {@link on} trigger-drain
+ * registry (`src/kernel/on.ts`).
+ *
+ * Snapshot of every clock declared since the last reset.
+ */
+export function listClocks(): readonly ClockDecl[] {
+  return clockRegistry.slice();
+}
+
+/**
+ * Clear the clock registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetClocks(): void {
+  clockRegistry.length = 0;
+}
+
 /**
  * Declare a named clock / cron schedule.
  *
@@ -50,7 +73,7 @@ export function clock(name: string, options: ClockOptions = {}): ClockDecl {
   if (!options.cron && !options.every) {
     throw new TypeError(`clock("${name}"): require cron or every`);
   }
-  return {
+  const decl: ClockDecl = {
     name,
     cron: options.cron,
     every: options.every,
@@ -58,4 +81,6 @@ export function clock(name: string, options: ClockOptions = {}): ClockDecl {
     overridable: options.overridable ?? false,
     ...(options.description !== undefined ? { description: options.description } : {}),
   };
+  clockRegistry.push(decl);
+  return decl;
 }

package/src/elements/gate/boot.ts

@@ -1,9 +1,9 @@
 /**
  * Gate boot audit — every HTTP trigger must declare auth posture.
  *
- * Fail loud: missing gate and missing {@link gate.public} → {@link GateBootError}.
+ * Fail loud: missing gate and missing `.public()` → {@link GateBootError}.
  * `unguardedHttp: "allow"` is honoured **only** when `env === "test"` — never a
- * production-wide bypass. Migrate real apps with per-trigger `gate.public`.
+ * production-wide bypass. Migrate real apps with per-trigger `.public()`.
  */
 
 import { GATE_PUBLIC_NAME } from "./declare.ts";
@@ -19,7 +19,7 @@ export interface GatePostureGap {
 }
 
 /**
- * Thrown when HTTP triggers omit both a gate chain and {@link gate.public}.
+ * Thrown when HTTP triggers omit both a gate chain and `.public()`.
  * Lists every gap (Vault-style — fail once with the full set).
  */
 export class GateBootError extends Error {
@@ -28,7 +28,7 @@ export class GateBootError extends Error {
   constructor(gaps: readonly GatePostureGap[]) {
     const lines = gaps.map((g) => `  - ${g.flowId} ${g.method} ${g.path}`);
     super(
-      `gate boot failed — ${gaps.length} HTTP trigger(s) missing auth posture (attach a gate or gate.public):\n${lines.join("\n")}`,
+      `gate boot failed — ${gaps.length} HTTP trigger(s) missing auth posture (attach a gate or .public()):\n${lines.join("\n")}`,
     );
     this.name = "GateBootError";
     this.gaps = gaps;
@@ -84,7 +84,7 @@ export function hasHttpGatePosture(
 }
 
 /**
- * Collect HTTP triggers with neither a gate nor {@link gate.public}.
+ * Collect HTTP triggers with neither a gate nor `.public()`.
  *
  * @param bindings - Adopted / registered bindings
  */