okengine 0.3.4 → 0.3.6

package/src/drivers/drizzle-dialect.ts

@@ -4,7 +4,9 @@
  * drizzle-kit `1.0.0-rc.4` dialects (from its schema validator):
  * `postgresql` · `mysql` · `sqlite` · `turso` · `singlestore` · `mssql` ·
  * `cockroach` · `duckdb`. OKE owns kit-facing SQL drivers `sqlite` /
- * `postgres` only — map those, never infer from connection URLs.
+ * `postgres` / `libsql` / `pglite` only — map those, never infer from
+ * connection URLs. `libsql` speaks the sqlite wire dialect; `pglite` speaks
+ * postgresql (same dialect as `postgres`, different transport).
  */
 
 import type { StoreDriverId } from "./types.ts";
@@ -18,20 +20,22 @@ export type OkeDrizzleKitDialect = "sqlite" | "postgresql";
  * dialect months later.
  */
 export const SQL_DRIVER_TO_DRIZZLE_DIALECT: Record<
-  Extract<StoreDriverId, "sqlite" | "postgres">,
+  Extract<StoreDriverId, "sqlite" | "postgres" | "libsql" | "pglite">,
   OkeDrizzleKitDialect
 > = {
   sqlite: "sqlite",
   postgres: "postgresql",
+  libsql: "sqlite",
+  pglite: "postgresql",
 };
 
 /**
  * Resolve the drizzle-kit dialect for an OKE SQL driver id.
  *
- * @param driverId - Protocol driver id (`sqlite` | `postgres`)
+ * @param driverId - Protocol driver id (`sqlite` | `postgres` | `libsql` | `pglite`)
  */
 export function drizzleDialectFromSqlDriver(
-  driverId: Extract<StoreDriverId, "sqlite" | "postgres">,
+  driverId: Extract<StoreDriverId, "sqlite" | "postgres" | "libsql" | "pglite">,
 ): OkeDrizzleKitDialect {
   return SQL_DRIVER_TO_DRIZZLE_DIALECT[driverId];
 }

package/src/drivers/index.ts

@@ -77,6 +77,10 @@ export { s3Driver, openS3Bucket, createS3FakeClient } from "./s3.ts";
 
 export { pgvectorDriver, openPgvectorIndex } from "./pgvector.ts";
 
+export { libsqlDriver, connectLibsql, libsqlIndexDriver, openLibsqlIndex } from "./libsql.ts";
+
+export { pgliteDriver, connectPglite } from "./pglite.ts";
+
 export { memorySignalDriver, openMemorySignal } from "./signal-memory.ts";
 
 export {

package/src/drivers/libsql.ts

@@ -0,0 +1,179 @@
+/**
+ * `libsql` driver — binds `@libsql/client` (optional peer, dynamic import).
+ *
+ * Protocol-named: libSQL speaks the sqlite wire dialect plus native ANN
+ * vectors (`F32_BLOB` + `libsql_vector_idx` + `vector_top_k`). Classic libSQL
+ * only — never the Turso Rust rewrite (`@tursodatabase/database`).
+ *
+ * Serves both the `sql` facet (same `?` placeholder convention as `sqlite`)
+ * and the `index` facet (native ANN, no JS-side distance math).
+ *
+ * Latency note: local file / `:memory:` opens are in-process like sqlite.
+ */
+
+import { customType, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import type {
+  IndexDriver,
+  IndexHit,
+  IndexOpenOptions,
+  IndexStore,
+  SqlConnectOptions,
+  SqlConnection,
+  SqlDriver,
+  SqlRow,
+} from "./types.ts";
+
+/** `@libsql/client` is an optional peer — loaded only when this driver runs. */
+type LibsqlModule = typeof import("@libsql/client");
+
+async function loadLibsql(): Promise<LibsqlModule> {
+  try {
+    return await import("@libsql/client");
+  } catch {
+    throw new Error(
+      "libsql driver: install optional peer `@libsql/client` (bun add @libsql/client)",
+    );
+  }
+}
+
+/** Bare file paths become `file:` URLs; `:memory:` / scheme URLs pass through. */
+function normalizeLibsqlUrl(url: string): string {
+  if (url === ":memory:" || url.includes("://") || url.startsWith("file:")) return url;
+  return `file:${url}`;
+}
+
+/**
+ * Open a libSQL connection implementing {@link SqlConnection}.
+ *
+ * @param options - URL (`:memory:` / `file:…` / `libsql://…`) / role
+ */
+export async function connectLibsql(options: SqlConnectOptions = {}): Promise<SqlConnection> {
+  const role = options.role ?? "primary";
+  const { createClient } = await loadLibsql();
+  const client = createClient({ url: normalizeLibsqlUrl(options.url ?? ":memory:") });
+  return {
+    driverId: "libsql",
+    role,
+    async query(sql, params = []) {
+      const rs = await client.execute({ sql, args: params as never });
+      return rs.rows as unknown as SqlRow[];
+    },
+    async exec(sql, params = []) {
+      const rs = await client.execute({ sql, args: params as never });
+      return { changes: rs.rowsAffected };
+    },
+    async close() {
+      client.close();
+    },
+  };
+}
+
+/** Protocol-named libsql sql driver. */
+export const libsqlDriver: SqlDriver = {
+  id: "libsql",
+  facet: "sql",
+  connect: connectLibsql,
+};
+
+/** libSQL native vector column: `F32_BLOB(dims)` (float32, validated by the engine). */
+const f32Blob = customType<{
+  data: readonly number[];
+  driverData: string;
+  config: { dimensions: number };
+}>({
+  dataType(config) {
+    return `F32_BLOB(${config?.dimensions ?? 0})`;
+  },
+  toDriver(value) {
+    return JSON.stringify(value);
+  },
+});
+
+/**
+ * Open a libSQL-backed index with native ANN.
+ *
+ * DDL: `F32_BLOB(dims)` column + `libsql_vector_idx` ANN index (validated
+ * against `@libsql/client@0.17`). Queries run `vector_top_k` joined back to
+ * the base table — approximate nearest neighbours, never a full scan. Score
+ * is cosine similarity (`1 - vector_distance_cos`), matching the memory
+ * driver's higher-is-better convention.
+ *
+ * @param options - Name / dims / shared SQL connection
+ */
+export async function openLibsqlIndex(options: IndexOpenOptions): Promise<IndexStore> {
+  const ownsSql = !options.sql;
+  const sql = options.sql ?? (await connectLibsql({ url: options.url }));
+  if (sql.driverId !== "libsql") {
+    if (ownsSql) await sql.close();
+    throw new Error(
+      `libsql index: needs a libsql SQL connection, got "${sql.driverId}" — ` +
+        `set store.sql to "libsql" so the index shares its connection`,
+    );
+  }
+
+  const tableName = `oke_idx_${options.name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+  const indexName = `${tableName}_vec`;
+  const table = sqliteTable(tableName, {
+    id: text("id").primaryKey(),
+    embedding: f32Blob("embedding", { dimensions: options.dims }).notNull(),
+    meta: text("meta"),
+  });
+
+  await sql.exec(
+    `CREATE TABLE IF NOT EXISTS "${tableName}" (id TEXT PRIMARY KEY, embedding ${table.embedding.getSQLType()} NOT NULL, meta TEXT)`,
+  );
+  // ANN index — fails loud on engines without vector support (never falls back).
+  await sql.exec(
+    `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${tableName}" (libsql_vector_idx(embedding))`,
+  );
+
+  return {
+    driverId: "libsql",
+    async upsert(id, vector, meta) {
+      if (vector.length !== options.dims) {
+        throw new Error(`vector dims ${vector.length} !== index dims ${options.dims}`);
+      }
+      await sql.exec(
+        `INSERT INTO "${tableName}" (id, embedding, meta) VALUES (?, vector32(?), ?) ` +
+          `ON CONFLICT (id) DO UPDATE SET embedding = excluded.embedding, meta = excluded.meta`,
+        [id, JSON.stringify(vector), meta ? JSON.stringify(meta) : null],
+      );
+    },
+    async search(vector, topK = 10): Promise<IndexHit[]> {
+      const k = Math.max(1, Math.floor(topK));
+      const rows = await sql.query(
+        `SELECT t.id AS id, t.meta AS meta, ` +
+          `vector_distance_cos(t.embedding, vector32(?)) AS distance ` +
+          `FROM vector_top_k('${indexName}', vector32(?), ${k}) AS i ` +
+          `JOIN "${tableName}" AS t ON t.rowid = i.id ` +
+          `ORDER BY distance ASC`,
+        [JSON.stringify(vector), JSON.stringify(vector)],
+      );
+      return rows.map((row) => {
+        const metaRaw = row.meta;
+        return {
+          id: String(row.id),
+          score: 1 - Number(row.distance),
+          meta:
+            typeof metaRaw === "string"
+              ? (JSON.parse(metaRaw) as Record<string, unknown>)
+              : undefined,
+        };
+      });
+    },
+    async delete(id) {
+      const result = await sql.exec(`DELETE FROM "${tableName}" WHERE id = ?`, [id]);
+      return result.changes > 0;
+    },
+    async close() {
+      if (ownsSql) await sql.close();
+    },
+  };
+}
+
+/** Protocol-named libsql index driver. */
+export const libsqlIndexDriver: IndexDriver = {
+  id: "libsql",
+  facet: "index",
+  open: openLibsqlIndex,
+};

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,10 +1,18 @@
 /**
  * `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,
@@ -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, "_")}`;
+  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() {

package/src/drivers/types.ts

@@ -8,7 +8,16 @@
 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";
 
 /** Facets a driver may serve. */
 export type DriverFacet = StoreFacet;
@@ -37,7 +46,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 +70,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";
   /**
@@ -248,7 +257,7 @@ export interface IndexHit {
 
 /** Vector index handle. */
 export interface IndexStore {
-  readonly driverId: "memory" | "pgvector";
+  readonly driverId: "memory" | "pgvector" | "libsql";
   /**
    * Upsert a vector.
    *
@@ -280,15 +289,15 @@ export interface IndexOpenOptions {
   readonly name: string;
   /** Vector dimensions. */
   readonly dims: number;
-  /** Postgres URL when using pgvector. */
+  /** SQL URL when the index driver shares the sql facet's engine. */
   readonly url?: string;
-  /** Injected SQL connection for pgvector tests. */
+  /** Injected SQL connection — shared with `store.sql` at boot. */
   readonly sql?: SqlConnection;
 }
 
 /** Index driver factory. */
 export interface IndexDriver {
-  readonly id: "memory" | "pgvector";
+  readonly id: "memory" | "pgvector" | "libsql";
   readonly facet: "index";
   /**
    * Open an index.

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";

package/src/elements/signal/declare.ts

@@ -17,6 +17,8 @@ export interface SignalOptions {
    * - `live` — client-subscribable stream (replayable)
    */
   readonly delivery: SignalDelivery;
+  /** Optional human description for Console / docs (falls back to the signal name). */
+  readonly description?: string;
   /** Max delivery attempts before dead-letter (once). */
   readonly retries?: number;
   /** Preserve exhausted messages in the DLQ (once). */
@@ -35,6 +37,8 @@ export interface SignalDecl<T = unknown> {
   readonly name: string;
   /** Delivery physics. */
   readonly delivery: SignalDelivery;
+  /** Optional human description. */
+  readonly description?: string;
   /** Max retries before DLQ. */
   readonly retries: number;
   /** Whether exhausted messages enter the DLQ. */
@@ -64,6 +68,7 @@ export function signal<T = unknown>(name: string, options: SignalOptions): Signa
   return {
     name,
     delivery: options.delivery,
+    ...(options.description !== undefined ? { description: options.description } : {}),
     retries: options.retries ?? 3,
     deadLetter: options.deadLetter ?? true,
     schema: options.schema,