okengine 0.3.5 → 0.4.3

package/src/drivers/pglite.ts

@@ -0,0 +1,79 @@
+/**
+ * `pglite` driver — binds `@electric-sql/pglite` (optional peer, dynamic import).
+ *
+ * Protocol-named transport: PGlite is Postgres compiled to WASM — same wire
+ * dialect as `postgres` (`?` params convert to `$n`), different transport.
+ * drizzle-kit dialect: `postgresql`.
+ *
+ * Honest latency trade-off (measured on `@electric-sql/pglite@0.5.4`): first
+ * init ~900 ms one-time (WASM instantiation); reopen of an existing datadir
+ * ~44 ms; warm CRUD ~45 ms vs ~3 ms for `bun:sqlite` (~15× slower). Choose
+ * `pglite` for dialect/pgvector parity on a laptop — never as a
+ * latency-competitive default. `local` stays on `sqlite`.
+ */
+
+import { toPostgresParams } from "./postgres.ts";
+import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRow } from "./types.ts";
+
+/** `@electric-sql/pglite` is an optional peer — loaded only when this driver runs. */
+type PgliteModule = typeof import("@electric-sql/pglite");
+type PgliteVectorModule = typeof import("@electric-sql/pglite-pgvector");
+
+async function loadPglite(): Promise<PgliteModule> {
+  try {
+    return await import("@electric-sql/pglite");
+  } catch {
+    throw new Error(
+      "pglite driver: install optional peer `@electric-sql/pglite` (bun add @electric-sql/pglite)",
+    );
+  }
+}
+
+async function loadPgliteVector(): Promise<PgliteVectorModule> {
+  try {
+    return await import("@electric-sql/pglite-pgvector");
+  } catch {
+    throw new Error(
+      "pglite driver: install optional peer `@electric-sql/pglite-pgvector` (bun add @electric-sql/pglite-pgvector)",
+    );
+  }
+}
+
+/**
+ * Open a PGlite connection implementing {@link SqlConnection}.
+ *
+ * The pgvector extension is loaded at `PGlite.create` so `CREATE EXTENSION
+ * vector` in the pgvector index driver succeeds — same real-ANN code path as
+ * `postgres`.
+ *
+ * @param options - URL (`memory://` or a datadir path; default `.oke/pgdata`) / role
+ */
+export async function connectPglite(options: SqlConnectOptions = {}): Promise<SqlConnection> {
+  const role = options.role ?? "primary";
+  const { PGlite } = await loadPglite();
+  const { vector } = await loadPgliteVector();
+  const dataDir = options.url && options.url.length > 0 ? options.url : ".oke/pgdata";
+  const db = await PGlite.create(dataDir, { extensions: { vector } });
+  return {
+    driverId: "pglite",
+    role,
+    async query(sql, params = []) {
+      const rs = await db.query<SqlRow>(toPostgresParams(sql), [...params]);
+      return rs.rows;
+    },
+    async exec(sql, params = []) {
+      const rs = await db.query<SqlRow>(toPostgresParams(sql), [...params]);
+      return { changes: rs.affectedRows ?? 0 };
+    },
+    async close() {
+      await db.close();
+    },
+  };
+}
+
+/** Protocol-named pglite driver. */
+export const pgliteDriver: SqlDriver = {
+  id: "pglite",
+  facet: "sql",
+  connect: connectPglite,
+};

package/src/drivers/pgvector.ts

@@ -1,16 +1,24 @@
 /**
  * `pgvector` driver — vector index facet over Postgres + pgvector.
  *
+ * Real ANN via drizzle-orm's pg vector API: `vector(dims)` column, HNSW index
+ * (`vector_cosine_ops`), `cosineDistance` ordering — no JS-side distance math
+ * on the SQL path. One implementation serves both the `postgres` and `pglite`
+ * sql drivers (identical wire dialect); the caller injects the already-open
+ * {@link SqlConnection} (shared with `store.sql`, never a second connection).
+ *
  * When no SQL connection is provided, falls back to an in-process cosine index
  * so the conformance suite runs without a live Postgres.
  */
 
+import { cosineDistance } from "drizzle-orm";
+import { PgDialect, index as pgIndex, pgTable, text, vector } from "drizzle-orm/pg-core";
 import type {
-  IndexDriver,
   IndexHit,
   IndexOpenOptions,
-  IndexStore,
   SqlConnection,
+  VectorIndexDriver,
+  VectorIndexStore,
 } from "./types.ts";
 
 /**
@@ -18,7 +26,7 @@ import type {
  *
  * @param options - Name / dims / SQL connection
  */
-export async function openPgvectorIndex(options: IndexOpenOptions): Promise<IndexStore> {
+export async function openPgvectorIndex(options: IndexOpenOptions): Promise<VectorIndexStore> {
   if (options.sql) {
     return openPgvectorSql(options.name, options.dims, options.sql);
   }
@@ -26,48 +34,75 @@ export async function openPgvectorIndex(options: IndexOpenOptions): Promise<Inde
   return openPgvectorMemory(options.dims);
 }
 
+const pgDialect = new PgDialect();
+
 async function openPgvectorSql(
   name: string,
   dims: number,
   sql: SqlConnection,
-): Promise<IndexStore> {
-  const table = `oke_idx_${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+): Promise<VectorIndexStore> {
+  if (sql.driverId !== "postgres" && sql.driverId !== "pglite") {
+    throw new Error(
+      `pgvector index: needs a postgres/pglite SQL connection, got "${sql.driverId}" — ` +
+        `set store.sql to "postgres" or "pglite" so the index shares its connection`,
+    );
+  }
+
+  const tableName = `oke_idx_${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+  const indexName = `${tableName}_hnsw`;
+  const table = pgTable(
+    tableName,
+    {
+      id: text("id").primaryKey(),
+      embedding: vector("embedding", { dimensions: dims }).notNull(),
+      meta: text("meta"),
+    },
+    (t) => [pgIndex(indexName).using("hnsw", t.embedding.op("vector_cosine_ops"))],
+  );
+
+  // Extension + DDL — fail loud when pgvector is not installed (never fall back).
+  await sql.exec(`CREATE EXTENSION IF NOT EXISTS vector`);
   await sql.exec(
-    `CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, embedding TEXT NOT NULL, meta TEXT)`,
+    `CREATE TABLE IF NOT EXISTS "${tableName}" (id TEXT PRIMARY KEY, embedding vector(${dims}) NOT NULL, meta TEXT)`,
+  );
+  await sql.exec(
+    `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${tableName}" USING hnsw (embedding vector_cosine_ops)`,
   );
 
   return {
     driverId: "pgvector",
-    async upsert(id, vector, meta) {
-      if (vector.length !== dims) {
-        throw new Error(`vector dims ${vector.length} !== index dims ${dims}`);
+    async upsert(id, vec, meta) {
+      if (vec.length !== dims) {
+        throw new Error(`vector dims ${vec.length} !== index dims ${dims}`);
       }
-      await sql.exec(`DELETE FROM "${table}" WHERE id = ?`, [id]);
-      await sql.exec(`INSERT INTO "${table}" (id, embedding, meta) VALUES (?, ?, ?)`, [
-        id,
-        JSON.stringify(vector),
-        meta ? JSON.stringify(meta) : null,
-      ]);
+      await sql.exec(
+        `INSERT INTO "${tableName}" (id, embedding, meta) VALUES (?, ?::vector, ?) ` +
+          `ON CONFLICT (id) DO UPDATE SET embedding = excluded.embedding, meta = excluded.meta`,
+        [id, JSON.stringify(vec), meta ? JSON.stringify(meta) : null],
+      );
     },
-    async search(vector, topK = 10): Promise<IndexHit[]> {
-      const rows = await sql.query(`SELECT id, embedding, meta FROM "${table}"`);
-      const hits: IndexHit[] = rows.map((row) => {
-        const emb = JSON.parse(String(row.embedding)) as number[];
+    async search(vec, topK = 10): Promise<IndexHit[]> {
+      const distance = pgDialect.sqlToQuery(cosineDistance(table.embedding, [...vec]));
+      const distanceSql = distance.sql.replace(/\$\d+/g, "?");
+      const rows = await sql.query(
+        `SELECT "id", "meta", ${distanceSql} AS "distance" FROM "${tableName}" ` +
+          `ORDER BY "distance" ASC LIMIT ?`,
+        [...distance.params, Math.max(1, Math.floor(topK))],
+      );
+      return rows.map((row) => {
         const metaRaw = row.meta;
         return {
           id: String(row.id),
-          score: cosine(vector, emb),
+          score: 1 - Number(row.distance),
           meta:
             typeof metaRaw === "string"
               ? (JSON.parse(metaRaw) as Record<string, unknown>)
               : undefined,
         };
       });
-      hits.sort((a, b) => b.score - a.score);
-      return hits.slice(0, topK);
     },
     async delete(id) {
-      const result = await sql.exec(`DELETE FROM "${table}" WHERE id = ?`, [id]);
+      const result = await sql.exec(`DELETE FROM "${tableName}" WHERE id = ?`, [id]);
       return result.changes > 0;
     },
     async close() {
@@ -76,7 +111,7 @@ async function openPgvectorSql(
   };
 }
 
-function openPgvectorMemory(dims: number): IndexStore {
+function openPgvectorMemory(dims: number): VectorIndexStore {
   const docs = new Map<string, { vector: number[]; meta?: Record<string, unknown> }>();
   return {
     driverId: "pgvector",
@@ -119,7 +154,7 @@ function cosine(a: readonly number[], b: readonly number[]): number {
 }
 
 /** Protocol-named pgvector driver. */
-export const pgvectorDriver: IndexDriver = {
+export const pgvectorDriver: VectorIndexDriver = {
   id: "pgvector",
   facet: "index",
   open: openPgvectorIndex,

package/src/drivers/types.ts

@@ -8,7 +8,17 @@
 import type { ColumnClassification, StoreFacet } from "../manifest/types.ts";
 
 /** Protocol ids for store drivers in scope. */
-export type StoreDriverId = "sqlite" | "postgres" | "memory" | "redis" | "fs" | "s3" | "pgvector";
+export type StoreDriverId =
+  | "sqlite"
+  | "postgres"
+  | "libsql"
+  | "pglite"
+  | "memory"
+  | "redis"
+  | "fs"
+  | "s3"
+  | "pgvector"
+  | "meilisearch";
 
 /** Facets a driver may serve. */
 export type DriverFacet = StoreFacet;
@@ -37,7 +47,7 @@ export interface SqlConnectOptions {
 /** Low-level SQL connection used by every sql driver. */
 export interface SqlConnection {
   /** Protocol driver id. */
-  readonly driverId: "sqlite" | "postgres" | "memory";
+  readonly driverId: "sqlite" | "postgres" | "libsql" | "pglite" | "memory";
   /** Primary vs replica. */
   readonly role: SqlRole;
   /**
@@ -61,7 +71,7 @@ export interface SqlConnection {
 /** SQL driver factory. */
 export interface SqlDriver {
   /** Protocol id. */
-  readonly id: "sqlite" | "postgres" | "memory";
+  readonly id: "sqlite" | "postgres" | "libsql" | "pglite" | "memory";
   /** Facet this driver serves. */
   readonly facet: "sql";
   /**
@@ -239,16 +249,20 @@ export interface FilesDriver {
   open(options: FilesOpenOptions): Promise<FilesBucket>;
 }
 
-/** Vector index hit. */
+/** Index hit — score meaning depends on the driver. */
 export interface IndexHit {
   readonly id: string;
+  /**
+   * Vector drivers: cosine similarity (higher = more similar).
+   * Full-text (`meilisearch`): relevance score (`_rankingScore`, higher = more relevant).
+   */
   readonly score: number;
   readonly meta?: Record<string, unknown>;
 }
 
-/** Vector index handle. */
-export interface IndexStore {
-  readonly driverId: "memory" | "pgvector";
+/** Vector (ANN) index handle. */
+export interface VectorIndexStore {
+  readonly driverId: "memory" | "pgvector" | "libsql";
   /**
    * Upsert a vector.
    *
@@ -263,7 +277,7 @@ export interface IndexStore {
    * @param vector - Query embedding
    * @param topK - Max hits
    */
-  search(vector: readonly number[], topK?: number): Promise<IndexHit[]>;
+  search(vector: readonly number[], topK?: number): Promise<readonly IndexHit[]>;
   /**
    * Delete a vector.
    *
@@ -274,28 +288,104 @@ export interface IndexStore {
   close(): Promise<void>;
 }
 
+/** Full-text search options (meilisearch). */
+export interface TextIndexSearchOptions {
+  /** Max hits (Meilisearch `limit`). */
+  readonly topK?: number;
+  /** Filter expression (attribute must be filterable). */
+  readonly filter?: string | string[];
+  /** Facet attributes to aggregate. */
+  readonly facets?: string[];
+}
+
+/** Full-text search result (meilisearch). */
+export interface TextIndexSearchResult {
+  readonly hits: readonly IndexHit[];
+  /** Facet counts per attribute, when `facets` was requested. */
+  readonly facetDistribution?: Record<string, Record<string, number>>;
+}
+
+/** Full-text index handle. */
+export interface TextIndexStore {
+  readonly driverId: "meilisearch";
+  /**
+   * Upsert a document.
+   *
+   * @param id - Document id
+   * @param document - Field map (must include the id field)
+   */
+  upsert(id: string, document: Record<string, unknown>): Promise<void>;
+  /**
+   * Full-text search.
+   *
+   * @param q - Query text (typo tolerant)
+   * @param opts - topK / filter / facets
+   */
+  search(q: string, opts?: TextIndexSearchOptions): Promise<TextIndexSearchResult>;
+  /**
+   * Delete a document.
+   *
+   * @param id - Document id
+   */
+  delete(id: string): Promise<boolean>;
+  /** Close / release. */
+  close(): Promise<void>;
+}
+
+/** Index handle — discriminated by `driverId`. */
+export type IndexStore = VectorIndexStore | TextIndexStore;
+
 /** Options when opening an index. */
 export interface IndexOpenOptions {
   /** Index name. */
   readonly name: string;
-  /** Vector dimensions. */
+  /** Vector dimensions (vector drivers only). */
   readonly dims: number;
-  /** Postgres URL when using pgvector. */
+  /**
+   * Vector: SQL URL when the driver shares the sql facet's engine.
+   * Meilisearch: base HTTP URL.
+   */
   readonly url?: string;
-  /** Injected SQL connection for pgvector tests. */
+  /** Injected SQL connection — shared with `store.sql` at boot (vector only). */
   readonly sql?: SqlConnection;
+  /** Meilisearch API / master key. */
+  readonly apiKey?: string;
+  /** Injected fetch (tests). */
+  readonly fetch?: typeof fetch;
 }
 
-/** Index driver factory. */
-export interface IndexDriver {
-  readonly id: "memory" | "pgvector";
+/** Vector index driver factory. */
+export interface VectorIndexDriver {
+  readonly id: "memory" | "pgvector" | "libsql";
   readonly facet: "index";
   /**
-   * Open an index.
+   * Open a vector index.
    *
    * @param options - Name / dims / SQL
    */
-  open(options: IndexOpenOptions): Promise<IndexStore>;
+  open(options: IndexOpenOptions): Promise<VectorIndexStore>;
+}
+
+/** Full-text index driver factory. */
+export interface TextIndexDriver {
+  readonly id: "meilisearch";
+  readonly facet: "index";
+  /**
+   * Open a full-text index.
+   *
+   * @param options - Name / HTTP URL / apiKey
+   */
+  open(options: IndexOpenOptions): Promise<TextIndexStore>;
+}
+
+/** Index driver factory — discriminated by `id`. */
+export type IndexDriver = VectorIndexDriver | TextIndexDriver;
+
+/** True when the index driver shares the sql facet's engine (never memory). */
+export function indexDriverNeedsSql(
+  driver: IndexDriver,
+): driver is VectorIndexDriver & { id: "pgvector" | "libsql" } {
+  return driver.id === "pgvector" || driver.id === "libsql";
 }
 
 /** Union of all store drivers. */

package/src/drivers/vault-driver-removal.test.ts

@@ -12,6 +12,8 @@ const ROOT = join(import.meta.dir, "../..");
 
 /** Forbidden driver id, split so this file does not match itself. */
 const FORBIDDEN_DRIVER = ["so", "ps"].join("");
+/** Forbidden vault driver id, split so this file does not match itself. */
+const FORBIDDEN_SECRETS_SAAS = ["infi", "sical"].join("");
 /** Forbidden optional peer, split so this file does not match itself. */
 const FORBIDDEN_AGE = ["age", "-", "encryption"].join("");
 
@@ -49,6 +51,10 @@ describe("removed vault driver gate", () => {
     assertZeroGitGrep(FORBIDDEN_DRIVER);
   });
 
+  test("tracked tree has zero matches for the removed secrets-saas driver id", () => {
+    assertZeroGitGrep(FORBIDDEN_SECRETS_SAAS, ["changelog.md:"]);
+  });
+
   test("tracked tree has zero matches for the removed age peer outside lockfiles", () => {
     assertZeroGitGrep(FORBIDDEN_AGE, LOCKFILE_PREFIXES);
   });

package/src/drivers/vault-types.ts

@@ -1,12 +1,12 @@
 /**
  * Protocol-named vault driver contracts.
  *
- * Driver ids: `env` · `openbao` · `infisical` · `managed` · `memory`.
- * Never vendor names (`neon`, `infisical-cloud`, …) — vendor choice lives in `images`.
+ * Driver ids: `env` · `openbao` · `managed` · `memory`.
+ * Never vendor names (`neon`, …) — vendor choice lives in `images`.
  */
 
 /** Protocol ids for vault drivers. */
-export type VaultDriverId = "env" | "openbao" | "infisical" | "managed" | "memory";
+export type VaultDriverId = "env" | "openbao" | "managed" | "memory";
 
 /** Options when opening a vault backend. */
 export interface VaultOpenOptions {
@@ -16,7 +16,7 @@ export interface VaultOpenOptions {
   readonly envPrefix?: string;
   /** Injected env map for tests (defaults to `process.env`). */
   readonly env?: Readonly<Record<string, string | undefined>>;
-  /** OpenBao / Infisical / managed base URL. */
+  /** OpenBao / managed base URL. */
   readonly url?: string;
   /** Token / API key for remote vaults. */
   readonly token?: string;

package/src/elements/ai/runtime.ts

@@ -485,6 +485,12 @@ export function createAiRuntime(options: CreateAiRuntimeOptions = {}): AiRuntime
       if (!index) {
         throw new Error(`ai: index "${decl.into}" not registered`);
       }
+      if (index.driverId === "meilisearch") {
+        throw new Error(
+          `ai: embed into "${decl.into}" needs a vector index (memory/pgvector/libsql) — ` +
+            `"${index.driverId}" is full-text; embeddings don't apply`,
+        );
+      }
       const modelName = decl.model ?? [...models.keys()][0] ?? "mock";
       const client = await clientFor(modelName);
       if (!client.embed) {

package/src/elements/ai.test.ts

@@ -263,6 +263,28 @@ describe("embeddings into store.index", () => {
     const hits = await index.search((await client.embed!({ input: "hello world" })).vectors[0]!, 1);
     expect(hits[0]?.id).toBe("doc-1");
   });
+
+  test("embed into a meilisearch (full-text) index fails loud", async () => {
+    const smart = ai.model("smart", { provider: "mock" });
+    const embed = ai.embed("docs", { model: smart, into: "kb" });
+    const client = await mockAiDriver.open({ model: "mock" });
+    const textIndex = {
+      driverId: "meilisearch" as const,
+      upsert: async () => {},
+      search: async () => ({ hits: [] }),
+      delete: async () => true,
+      close: async () => {},
+    };
+    const runtime = createAiRuntime({
+      models: [smart],
+      embeds: [embed],
+      clients: { smart: client },
+      indexes: { kb: textIndex as never },
+    });
+    await expect(runtime.embed("docs", "doc-1", "hello world")).rejects.toThrow(
+      /needs a vector index/,
+    );
+  });
 });
 
 describe("model fallback chain", () => {

package/src/elements/channel/declare.ts

@@ -14,6 +14,8 @@ export interface ChannelMediumOptions {
 
 /** Options for {@link channel.template} / medium `.template`. */
 export interface ChannelTemplateOptions {
+  /** Optional human description for Console / docs (falls back to the template name). */
+  readonly description?: string;
   readonly medium?: ChannelMedium;
   readonly locales?: string[];
   readonly schema?: unknown;
@@ -24,6 +26,7 @@ export interface ChannelTemplateOptions {
 export interface ChannelTemplateDecl {
   readonly kind: "template";
   readonly name: string;
+  readonly description?: string;
   readonly medium: ChannelMedium;
   readonly locales?: string[];
   readonly schema?: unknown;
@@ -65,6 +68,7 @@ function mediumBinder(
         kind: "template",
         name,
         medium,
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
         ...(opts.locales ? { locales: opts.locales } : {}),
         ...(opts.schema !== undefined ? { schema: opts.schema } : {}),
         ...(from !== undefined ? { from } : {}),
@@ -110,6 +114,7 @@ export const channel: ChannelNamespace = {
       kind: "template",
       name,
       medium: options.medium ?? "email",
+      ...(options.description !== undefined ? { description: options.description } : {}),
       ...(options.locales ? { locales: options.locales } : {}),
       ...(options.schema !== undefined ? { schema: options.schema } : {}),
       ...(options.from !== undefined ? { from: options.from } : {}),

package/src/elements/clock/declare.ts

@@ -18,6 +18,8 @@ export interface ClockOptions {
    * Without it, no override is possible (console §4.1).
    */
   readonly overridable?: boolean;
+  /** Optional human description for Console / docs (falls back to the clock name). */
+  readonly description?: string;
 }
 
 /**
@@ -34,6 +36,8 @@ export interface ClockDecl {
   readonly timezone: string;
   /** Whether Console override is allowed. */
   readonly overridable: boolean;
+  /** Optional human description. */
+  readonly description?: string;
 }
 
 /**
@@ -52,5 +56,6 @@ export function clock(name: string, options: ClockOptions = {}): ClockDecl {
     every: options.every,
     timezone: options.timezone ?? "UTC",
     overridable: options.overridable ?? false,
+    ...(options.description !== undefined ? { description: options.description } : {}),
   };
 }

package/src/elements/clock/durable.ts

@@ -6,6 +6,7 @@
  * step never re-runs (four-applications · Provisions).
  */
 
+import { fxRetry } from "../../kernel/concurrency.ts";
 import type { AnyFlowDef } from "../../kernel/flow.ts";
 import { createFxContext, type CreateFxOptions, type Fx } from "../../kernel/fx.ts";
 import {
@@ -95,7 +96,12 @@ export async function runDurable<O = unknown>(
   });
 
   try {
-    const output = await options.flow.do(options.input as never, fx);
+    const run = () => {
+      // Same journal session across attempts — rewind so completed steps replay.
+      session.rewind();
+      return options.flow.do(options.input as never, fx);
+    };
+    const output = await (options.flow.retry ? fxRetry(run, options.flow.retry) : run());
     await session.commit("completed", { output });
     return {
       status: "completed",

package/src/elements/gate/declare.ts

@@ -45,6 +45,16 @@ export interface RateOptions {
    * Without it, no override is possible (console §4.1).
    */
   readonly overridable?: boolean;
+  /** Optional human description for Console / docs (falls back to the rate name). */
+  readonly description?: string;
+}
+
+/** Options object form of {@link gate.policy} (keeps the two-arg check form valid). */
+export interface PolicyGateOptions {
+  /** Predicate over {@link GatePolicyContext}. */
+  readonly check: (ctx: GatePolicyContext) => boolean | Promise<boolean>;
+  /** Optional human description for Console / docs (falls back to the policy name). */
+  readonly description?: string;
 }
 
 /** Policy gate declaration. */
@@ -52,6 +62,7 @@ export interface PolicyGateDecl {
   readonly kind: "policy";
   readonly name: string;
   readonly check: (ctx: GatePolicyContext) => boolean | Promise<boolean>;
+  readonly description?: string;
 }
 
 /** Rate gate declaration. */
@@ -63,6 +74,7 @@ export interface RateGateDecl {
   readonly per: string;
   readonly keyBy?: string;
   readonly overridable: boolean;
+  readonly description?: string;
 }
 
 /** Declared gate handle. */
@@ -76,11 +88,11 @@ export interface GateNamespace {
    * Declare a named ABAC / auth policy.
    *
    * @param name - Policy id (also a Module:Action when it contains `:`)
-   * @param check - Predicate over {@link GatePolicyContext}
+   * @param checkOrOptions - Predicate, or `{ check, description? }`
    */
   policy(
     name: string,
-    check: (ctx: GatePolicyContext) => boolean | Promise<boolean>,
+    checkOrOptions: ((ctx: GatePolicyContext) => boolean | Promise<boolean>) | PolicyGateOptions,
   ): PolicyGateDecl;
   /**
    * Declare a rate limit (atomic Lua on the kv driver).
@@ -98,13 +110,23 @@ export const gate: GateNamespace = {
    * Declare a named ABAC / auth policy.
    *
    * @param name - Policy id (also a Module:Action when it contains `:`)
-   * @param check - Predicate over {@link GatePolicyContext}
+   * @param checkOrOptions - Predicate, or `{ check, description? }`
    */
   policy(
     name: string,
-    check: (ctx: GatePolicyContext) => boolean | Promise<boolean>,
+    checkOrOptions: ((ctx: GatePolicyContext) => boolean | Promise<boolean>) | PolicyGateOptions,
   ): PolicyGateDecl {
-    return { kind: "policy", name, check };
+    if (typeof checkOrOptions === "function") {
+      return { kind: "policy", name, check: checkOrOptions };
+    }
+    return {
+      kind: "policy",
+      name,
+      check: checkOrOptions.check,
+      ...(checkOrOptions.description !== undefined
+        ? { description: checkOrOptions.description }
+        : {}),
+    };
   },
 
   /**
@@ -129,6 +151,7 @@ export const gate: GateNamespace = {
       per: options.per,
       keyBy: options.keyBy,
       overridable: options.overridable ?? false,
+      ...(options.description !== undefined ? { description: options.description } : {}),
     };
   },
 };

package/src/elements/gate.ts

@@ -13,6 +13,7 @@ export type {
   GateDecl,
   GatePolicyContext,
   PolicyGateDecl,
+  PolicyGateOptions,
   RateGateDecl,
   RateOptions,
 } from "./gate/declare.ts";