okengine 0.3.5 → 0.4.3

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,

package/src/elements/store/declare.ts

@@ -40,6 +40,8 @@ export interface StoreDeclBase {
 
 /** Options for {@link store.sql}. */
 export interface SqlStoreOptions {
+  /** Optional human description for Console / docs (falls back to the store name). */
+  readonly description?: string;
   /**
    * Schema tables — okengine {@link TableHandle}s and/or Drizzle tables.
    * Classification is read from TableHandle columns when present.
@@ -56,6 +58,7 @@ export interface SqlStoreOptions {
 export interface SqlStoreDecl extends StoreDeclBase {
   readonly facet: "sql";
   readonly ref: `sql:${string}`;
+  readonly description?: string;
   readonly schema?: SqlStoreOptions["schema"];
   readonly classify?: SqlStoreOptions["classify"];
   /**
@@ -94,6 +97,8 @@ export interface FilesStoreDecl extends StoreDeclBase {
 
 /** Options for {@link store.index}. */
 export interface IndexStoreOptions {
+  /** Optional human description for Console / docs (falls back to the index name). */
+  readonly description?: string;
   /** Vector dimensions (default 3 for tests; set explicitly in apps). */
   readonly dims?: number;
 }
@@ -102,6 +107,7 @@ export interface IndexStoreOptions {
 export interface IndexStoreDecl extends StoreDeclBase {
   readonly facet: "index";
   readonly ref: `index:${string}`;
+  readonly description?: string;
   readonly dims?: number;
 }
 
@@ -119,6 +125,7 @@ export function sql(name: string, options: SqlStoreOptions = {}): SqlStoreDecl {
     facet: "sql",
     name,
     ref: `sql:${name}`,
+    ...(options.description !== undefined ? { description: options.description } : {}),
     schema: options.schema,
     classify: options.classify,
     table(table) {
@@ -147,7 +154,7 @@ export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
     facet: "kv",
     name,
     ref: `kv:${name}`,
-    description: options.description,
+    ...(options.description !== undefined ? { description: options.description } : {}),
   };
 }
 
@@ -162,7 +169,7 @@ export function files(name: string, options: FilesStoreOptions = {}): FilesStore
     facet: "files",
     name,
     ref: `files:${name}`,
-    description: options.description,
+    ...(options.description !== undefined ? { description: options.description } : {}),
   };
 }
 
@@ -177,6 +184,7 @@ export function index(name: string, options: IndexStoreOptions = {}): IndexStore
     facet: "index",
     name,
     ref: `index:${name}`,
+    ...(options.description !== undefined ? { description: options.description } : {}),
     dims: options.dims,
   };
 }

package/src/elements/store/index-boot.test.ts

@@ -0,0 +1,299 @@
+/**
+ * End-to-end `store.index()` boot wiring — the CONFIGURED driver resolves at
+ * real boot for every backend (memory / libsql / pgvector over pglite /
+ * pgvector over real Postgres), SQL-backed indexes share store.sql's
+ * already-open connection (never a second, redundant one), and search runs
+ * through each engine's native ANN index — no JS-side full scan survives.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  connectLibsql,
+  libsqlDriver,
+  libsqlIndexDriver,
+  openLibsqlIndex,
+} from "../../drivers/libsql.ts";
+import { connectPglite } from "../../drivers/pglite.ts";
+import { openPgvectorIndex } from "../../drivers/pgvector.ts";
+import { connectPostgres } from "../../drivers/postgres.ts";
+import type { SqlConnection, SqlDriver } from "../../drivers/types.ts";
+import { bindStore } from "../../kernel/boot-bind/store.ts";
+import {
+  createStoreRuntime,
+  index as declareIndex,
+  sql as declareSql,
+  type SqlStoreHandle,
+  type VectorIndexStoreFxHandle,
+} from "../store.ts";
+
+const WRITE_CTX = (name: string) => ({
+  effects: { reads: [`index:${name}` as const], writes: [`index:${name}` as const] },
+});
+
+const prev = {
+  libsql: process.env.OKE_LIBSQL_URL,
+  pglite: process.env.OKE_PGLITE_URL,
+};
+
+afterEach(() => {
+  if (prev.libsql === undefined) delete process.env.OKE_LIBSQL_URL;
+  else process.env.OKE_LIBSQL_URL = prev.libsql;
+  if (prev.pglite === undefined) delete process.env.OKE_PGLITE_URL;
+  else process.env.OKE_PGLITE_URL = prev.pglite;
+});
+
+/** Wrap a real connection so the SQL it executes can be asserted on. */
+function recordingConn(conn: SqlConnection): { conn: SqlConnection; statements: string[] } {
+  const statements: string[] = [];
+  return {
+    statements,
+    conn: {
+      driverId: conn.driverId,
+      role: conn.role,
+      query: (sql, params) => {
+        statements.push(sql);
+        return conn.query(sql, params);
+      },
+      exec: (sql, params) => {
+        statements.push(sql);
+        return conn.exec(sql, params);
+      },
+      close: () => conn.close(),
+    },
+  };
+}
+
+describe("store.index boot wiring — memory", () => {
+  test("boot with no configured index driver resolves memory end to end", async () => {
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore({ stores: [kb] }, "local", () => Date.now());
+    const handle = (await runtime.open(kb, WRITE_CTX("kb"))) as VectorIndexStoreFxHandle;
+    expect(handle.driverId).toBe("memory");
+    await handle.upsert("near", [1, 0, 0]);
+    await handle.upsert("far", [0, 1, 0]);
+    const hits = await handle.search([1, 0, 0], 2);
+    expect(hits[0]?.id).toBe("near");
+    await runtime.close();
+  });
+});
+
+describe("store.index boot wiring — libsql", () => {
+  test("boot: sql=libsql + index=libsql resolves native ANN end to end", async () => {
+    process.env.OKE_LIBSQL_URL = ":memory:";
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "libsql" }, index: { local: "libsql" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    const handle = (await runtime.open(kb, WRITE_CTX("kb"))) as VectorIndexStoreFxHandle;
+    expect(handle.driverId).toBe("libsql");
+
+    await handle.upsert("near", [1, 0.1, 0], { label: "near" });
+    await handle.upsert("far", [0, 1, 0]);
+    await handle.upsert("farther", [-1, 0, 0]);
+    const hits = await handle.search([1, 0, 0], 3);
+    expect(hits.map((h: { id: string }) => h.id)).toEqual(["near", "far", "farther"]);
+    expect(hits[0]!.score).toBeGreaterThan(hits[1]!.score);
+    expect(hits[0]!.meta).toEqual({ label: "near" });
+    expect(await handle.delete("farther")).toBe(true);
+    await runtime.close();
+  });
+
+  test("sql and index facets share one already-open libsql connection", async () => {
+    let connects = 0;
+    const countingLibsql: SqlDriver = {
+      ...libsqlDriver,
+      connect: async (opts) => {
+        connects++;
+        return libsqlDriver.connect(opts);
+      },
+    };
+    const docs = declareSql("docs");
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = createStoreRuntime({
+      drivers: { sql: countingLibsql, index: libsqlIndexDriver },
+      sql: { docs: { name: "docs", primary: { url: ":memory:" } } },
+      index: { kb: { url: ":memory:" } },
+    });
+    // Index first: it must open the connection the sql facet then reuses.
+    const idxHandle = (await runtime.open(kb, WRITE_CTX("kb"))) as VectorIndexStoreFxHandle;
+    await idxHandle.upsert("a", [1, 0, 0]);
+    const sqlHandle = (await runtime.open(docs, {
+      effects: { reads: ["sql:docs"], writes: ["sql:docs"] },
+    })) as SqlStoreHandle;
+    await sqlHandle.raw("CREATE TABLE IF NOT EXISTS t_share (id TEXT)", []);
+    expect(connects).toBe(1);
+    await runtime.close();
+  });
+
+  test("libsql index searches through vector_top_k — real ANN, not a scan", async () => {
+    const real = await connectLibsql({ url: ":memory:" });
+    const { conn, statements } = recordingConn(real);
+    const idx = await openLibsqlIndex({ name: "ann", dims: 3, sql: conn });
+    await idx.upsert("x", [1, 0, 0]);
+    await idx.upsert("y", [0, 1, 0]);
+    const hits = await idx.search([1, 0, 0], 1);
+    expect(hits[0]?.id).toBe("x");
+    expect(statements.some((s) => s.includes("libsql_vector_idx"))).toBe(true);
+    expect(statements.some((s) => s.includes("vector_top_k"))).toBe(true);
+    const plan = await real.query(
+      `EXPLAIN QUERY PLAN SELECT * FROM vector_top_k('oke_idx_ann_vec', vector32('[1,0,0]'), 1)`,
+    );
+    expect(JSON.stringify(plan)).toContain("vector_top_k");
+    await idx.close();
+    await real.close();
+  });
+});
+
+describe("store.index boot wiring — pglite + pgvector", () => {
+  test("boot: sql=pglite + index=pgvector resolves end to end", async () => {
+    process.env.OKE_PGLITE_URL = "memory://";
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "pglite" }, index: { local: "pgvector" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    const handle = (await runtime.open(kb, WRITE_CTX("kb"))) as VectorIndexStoreFxHandle;
+    expect(handle.driverId).toBe("pgvector");
+
+    await handle.upsert("near", [1, 0.1, 0], { label: "near" });
+    await handle.upsert("far", [0, 1, 0]);
+    await handle.upsert("farther", [-1, 0, 0]);
+    const hits = await handle.search([1, 0, 0], 3);
+    expect(hits.map((h: { id: string }) => h.id)).toEqual(["near", "far", "farther"]);
+    expect(hits[0]!.score).toBeGreaterThan(hits[1]!.score);
+    expect(hits[0]!.meta).toEqual({ label: "near" });
+    expect(await handle.delete("farther")).toBe(true);
+    await runtime.close();
+  });
+
+  test("pglite runs the shared pgvector HNSW path — real ANN, not a scan", async () => {
+    const real = await connectPglite({ url: "memory://" });
+    const { conn, statements } = recordingConn(real);
+    const idx = await openPgvectorIndex({ name: "ann", dims: 3, sql: conn });
+    await idx.upsert("a", [1, 0, 0]);
+    await idx.upsert("b", [0, 1, 0]);
+    const hits = await idx.search([1, 0, 0], 2);
+    expect(hits[0]?.id).toBe("a");
+    expect(statements.some((s) => s.includes("CREATE EXTENSION IF NOT EXISTS vector"))).toBe(true);
+    expect(
+      statements.some((s) => s.includes("USING hnsw") && s.includes("vector_cosine_ops")),
+    ).toBe(true);
+    expect(statements.some((s) => s.includes("<=>"))).toBe(true);
+    const indexes = await real.query(
+      `SELECT indexdef FROM pg_indexes WHERE tablename = 'oke_idx_ann'`,
+    );
+    expect(JSON.stringify(indexes)).toContain("USING hnsw");
+    await idx.close();
+    await real.close();
+  });
+});
+
+describe("store.index boot wiring — fail loud", () => {
+  test("pgvector index with memory sql driver throws — never silently memory", async () => {
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "memory" }, index: { local: "pgvector" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    await expect(runtime.open(kb, WRITE_CTX("kb"))).rejects.toThrow(/cannot share sql driver/);
+    await runtime.close();
+  });
+
+  test("libsql index with sqlite sql driver throws", async () => {
+    const kb = declareIndex("kb", { dims: 3 });
+    const runtime = bindStore(
+      {
+        config: { drivers: { store: { sql: { local: "sqlite" }, index: { local: "libsql" } } } },
+        stores: [kb],
+      },
+      "local",
+      () => Date.now(),
+    );
+    await expect(runtime.open(kb, WRITE_CTX("kb"))).rejects.toThrow(/cannot share sql driver/);
+    await runtime.close();
+  });
+
+  test("meilisearch without OKE_STORE_INDEX_URL throws at bind — never sqlUrl, never memory", () => {
+    const prev = process.env.OKE_STORE_INDEX_URL;
+    delete process.env.OKE_STORE_INDEX_URL;
+    try {
+      const kb = declareIndex("kb");
+      expect(() =>
+        bindStore(
+          { config: { drivers: { store: { index: { local: "meilisearch" } } } }, stores: [kb] },
+          "local",
+          () => Date.now(),
+        ),
+      ).toThrow(/OKE_STORE_INDEX_URL/);
+    } finally {
+      if (prev === undefined) delete process.env.OKE_STORE_INDEX_URL;
+      else process.env.OKE_STORE_INDEX_URL = prev;
+    }
+  });
+
+  test("meilisearch binds its own URL + key (never the sql connection)", async () => {
+    const prevUrl = process.env.OKE_STORE_INDEX_URL;
+    const prevKey = process.env.OKE_STORE_INDEX_KEY;
+    process.env.OKE_STORE_INDEX_URL = "http://127.0.0.1:7700";
+    process.env.OKE_STORE_INDEX_KEY = "master-key";
+    try {
+      const kb = declareIndex("kb");
+      const runtime = bindStore(
+        { config: { drivers: { store: { index: { local: "meilisearch" } } } }, stores: [kb] },
+        "local",
+        () => Date.now(),
+      );
+      // No live server in unit tests: opening must fail loud (unreachable),
+      // proving the binding pointed at HTTP, not silently degraded to memory.
+      await expect(runtime.open(kb, WRITE_CTX("kb"))).rejects.toThrow(/meilisearch index/);
+      await runtime.close();
+    } finally {
+      if (prevUrl === undefined) delete process.env.OKE_STORE_INDEX_URL;
+      else process.env.OKE_STORE_INDEX_URL = prevUrl;
+      if (prevKey === undefined) delete process.env.OKE_STORE_INDEX_KEY;
+      else process.env.OKE_STORE_INDEX_KEY = prevKey;
+    }
+  });
+});
+
+const PGVECTOR_URL = process.env.OKE_TEST_PGVECTOR_URL;
+if (!PGVECTOR_URL) {
+  console.log("skip: live pgvector e2e (OKE_TEST_PGVECTOR_URL not set)");
+}
+const liveTest = PGVECTOR_URL ? test : test.skip;
+
+describe("store.index boot wiring — real Postgres pgvector", () => {
+  liveTest("live Postgres runs real HNSW ANN, not a scan", async () => {
+    const real = await connectPostgres({ url: PGVECTOR_URL });
+    const { conn, statements } = recordingConn(real);
+    const idx = await openPgvectorIndex({ name: "live", dims: 3, sql: conn });
+    await idx.upsert("near", [1, 0.1, 0]);
+    await idx.upsert("far", [0, 1, 0]);
+    await idx.upsert("farther", [-1, 0, 0]);
+    const hits = await idx.search([1, 0, 0], 3);
+    expect(hits.map((h) => h.id)).toEqual(["near", "far", "farther"]);
+    expect(statements.some((s) => s.includes("CREATE EXTENSION IF NOT EXISTS vector"))).toBe(true);
+    expect(statements.some((s) => s.includes("USING hnsw"))).toBe(true);
+    expect(statements.some((s) => s.includes("<=>"))).toBe(true);
+    const indexes = await real.query(
+      `SELECT indexdef FROM pg_indexes WHERE tablename = 'oke_idx_live'`,
+    );
+    expect(JSON.stringify(indexes)).toContain("USING hnsw");
+    await idx.delete("farther");
+    await idx.close();
+    await real.close();
+  });
+});

package/src/elements/store/runtime.ts

@@ -14,9 +14,16 @@ import type {
   KvDriver,
   KvNamespace,
   SqlConnection,
+  SqlConnectOptions,
   SqlDriver,
+  SqlRole,
   SqlRow,
+  TextIndexSearchOptions,
+  TextIndexSearchResult,
+  VectorIndexDriver,
+  VectorIndexStore,
 } from "../../drivers/types.ts";
+import { indexDriverNeedsSql } from "../../drivers/types.ts";
 import { buildClassificationMap, type MaskRowsOptions } from "./classify.ts";
 import {
   createStoreCache,
@@ -62,7 +69,15 @@ export interface CreateStoreRuntimeOptions {
   readonly files?: Readonly<Record<string, { readonly root?: string; readonly client?: unknown }>>;
   /** Index open options keyed by store name. */
   readonly index?: Readonly<
-    Record<string, { readonly dims?: number; readonly url?: string; readonly sql?: SqlConnection }>
+    Record<
+      string,
+      {
+        readonly dims?: number;
+        readonly url?: string;
+        readonly apiKey?: string;
+        readonly sql?: SqlConnection;
+      }
+    >
   >;
   /** Clock for cache TTLs. */
   readonly now?: () => number;
@@ -113,18 +128,30 @@ export interface FilesStoreFxHandle {
   list(prefix?: string): Promise<string[]>;
 }
 
-/** Index handle on `fx.store`. */
-export interface IndexStoreFxHandle {
+/** Vector index handle on `fx.store`. */
+export interface VectorIndexStoreFxHandle {
   readonly ref: `index:${string}`;
-  readonly driverId: "memory" | "pgvector";
+  readonly driverId: "memory" | "pgvector" | "libsql";
   upsert(id: string, vector: readonly number[], meta?: Record<string, unknown>): Promise<void>;
   search(
     vector: readonly number[],
     topK?: number,
-  ): Promise<Array<{ id: string; score: number; meta?: Record<string, unknown> }>>;
+  ): Promise<ReadonlyArray<{ id: string; score: number; meta?: Record<string, unknown> }>>;
   delete(id: string): Promise<boolean>;
 }
 
+/** Full-text index handle on `fx.store`. */
+export interface TextIndexStoreFxHandle {
+  readonly ref: `index:${string}`;
+  readonly driverId: "meilisearch";
+  upsert(id: string, document: Record<string, unknown>): Promise<void>;
+  search(q: string, opts?: TextIndexSearchOptions): Promise<TextIndexSearchResult>;
+  delete(id: string): Promise<boolean>;
+}
+
+/** Index handle on `fx.store` — discriminated by `driverId`. */
+export type IndexStoreFxHandle = VectorIndexStoreFxHandle | TextIndexStoreFxHandle;
+
 /** Store runtime. */
 export interface StoreRuntime {
   /** Shared multi-tier cache. */
@@ -186,6 +213,19 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
   const kvNs = new Map<string, KvNamespace>();
   const fileBuckets = new Map<string, FilesBucket>();
   const indexes = new Map<string, IndexStore>();
+  const clientIds = new WeakMap<object, number>();
+  let nextClientId = 0;
+
+  /** Injected test clients with the same URL still get distinct cache entries. */
+  function clientTag(client: unknown): string {
+    if ((typeof client !== "object" && typeof client !== "function") || client === null) return "";
+    let id = clientIds.get(client as object);
+    if (id === undefined) {
+      id = ++nextClientId;
+      clientIds.set(client as object, id);
+    }
+    return `#c${id}`;
+  }
 
   function classificationsFor(decl: SqlStoreDecl): ClassificationMap {
     const nested: Record<
@@ -215,13 +255,7 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
     const driver = options.drivers.sql;
     if (!driver) throw new Error("No sql driver configured");
 
-    const cacheKey = `${decl.name}:${target.role}:${JSON.stringify(target.options.url ?? "")}`;
-    let conn = sqlConns.get(cacheKey);
-    if (!conn) {
-      conn = await driver.connect(target.options);
-      sqlConns.set(cacheKey, conn);
-    }
-
+    const conn = await sharedSqlConn(driver, target.role, target.options);
     return createSqlStoreHandle(`sql:${decl.name}`, {
       connection: conn,
       classifications: classificationsFor(decl),
@@ -231,6 +265,51 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
     });
   }
 
+  /**
+   * One connection per driver+role+URL (+ injected client) — `store.sql` and a
+   * SQL-backed `store.index` share the same already-open connection, never a
+   * second one.
+   */
+  async function sharedSqlConn(
+    driver: SqlDriver,
+    role: SqlRole,
+    connectOptions: SqlConnectOptions,
+  ): Promise<SqlConnection> {
+    const cacheKey = `${driver.id}:${role}:${connectOptions.url ?? ""}${clientTag(connectOptions.client)}`;
+    let conn = sqlConns.get(cacheKey);
+    if (!conn) {
+      conn = await driver.connect({ ...connectOptions, role });
+      sqlConns.set(cacheKey, conn);
+    }
+    return conn;
+  }
+
+  /** SQL-backed index drivers borrow the sql facet's connection. */
+  async function sqlConnForIndex(
+    driver: VectorIndexDriver & { id: "pgvector" | "libsql" },
+    url: string | undefined,
+  ): Promise<SqlConnection> {
+    const sqlDriver = options.drivers.sql;
+    if (!sqlDriver) {
+      throw new Error(
+        `oke store: index driver "${driver.id}" needs a configured sql driver to share its connection`,
+      );
+    }
+    const compatible =
+      driver.id === "pgvector"
+        ? sqlDriver.id === "postgres" || sqlDriver.id === "pglite"
+        : sqlDriver.id === "libsql";
+    if (!compatible) {
+      throw new Error(
+        `oke store: index driver "${driver.id}" cannot share sql driver "${sqlDriver.id}" — ` +
+          (driver.id === "pgvector"
+            ? `pgvector needs store.sql on "postgres" or "pglite"`
+            : `libsql index needs store.sql on "libsql"`),
+      );
+    }
+    return sharedSqlConn(sqlDriver, "primary", { url });
+  }
+
   async function openKv(decl: KvStoreDecl): Promise<KvStoreFxHandle> {
     const driver = options.drivers.kv;
     if (!driver) throw new Error("No kv driver configured");
@@ -288,16 +367,30 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
         name: decl.name,
         dims: binding.dims ?? decl.dims ?? 3,
         url: binding.url,
-        sql: binding.sql,
+        apiKey: binding.apiKey,
+        sql: indexDriverNeedsSql(driver)
+          ? (binding.sql ?? (await sqlConnForIndex(driver, binding.url)))
+          : undefined,
       });
       indexes.set(decl.name, idx);
     }
+    if (idx.driverId === "meilisearch") {
+      const text = idx;
+      return {
+        ref: `index:${decl.name}`,
+        driverId: text.driverId,
+        upsert: (id, document) => text.upsert(id, document),
+        search: (q, opts) => text.search(q, opts),
+        delete: (id) => text.delete(id),
+      };
+    }
+    const vector = idx as VectorIndexStore;
     return {
       ref: `index:${decl.name}`,
-      driverId: idx.driverId,
-      upsert: (id, vector, meta) => idx!.upsert(id, vector, meta),
-      search: (vector, topK) => idx!.search(vector, topK),
-      delete: (id) => idx!.delete(id),
+      driverId: vector.driverId,
+      upsert: (id, vec, meta) => vector.upsert(id, vec, meta),
+      search: (vec, topK) => vector.search(vec, topK),
+      delete: (id) => vector.delete(id),
     };
   }
 

package/src/elements/store/schema-decl.ts

@@ -55,6 +55,8 @@ export interface SchemaColumnDecl extends ColumnDef {
   readonly tableName?: string;
   /** Foreign key when `.references()` was used. */
   readonly references?: ColumnReference;
+  /** Optional human description for Console / docs (falls back to the JS key). */
+  readonly description?: string;
 }
 
 /** Table from {@link store.schema.table} — extends {@link TableHandle}. */
@@ -75,6 +77,8 @@ export interface FieldBuilder {
   retain(duration: string): FieldBuilder;
   /** Override snake_case SQL name. */
   as(sqlName: string): FieldBuilder;
+  /** Optional human description for Console / docs (falls back to the JS key). */
+  describe(description: string): FieldBuilder;
   /**
    * Declare a foreign key to another column (dialect-agnostic).
    *
@@ -100,6 +104,7 @@ interface FieldState {
   readonly defaultFnKind?: DefaultFnKind;
   readonly classification?: ColumnClassification;
   readonly sqlName?: string;
+  readonly description?: string;
   readonly references?: ColumnReference;
 }
 
@@ -145,6 +150,7 @@ function createBuilder(state: FieldState): FieldBuilder {
     retain: (duration) =>
       next({ classification: mergeClassification(state.classification, { retain: duration }) }),
     as: (sqlName) => next({ sqlName }),
+    describe: (description) => next({ description }),
     references: (ref, actions) =>
       next({
         references: actions ? { ref, actions } : { ref },
@@ -163,6 +169,7 @@ function createBuilder(state: FieldState): FieldBuilder {
         ...(state.defaultFn ? { defaultFn: state.defaultFn } : {}),
         ...(state.defaultFnKind ? { defaultFnKind: state.defaultFnKind } : {}),
         ...(state.classification ? { classification: state.classification } : {}),
+        ...(state.description !== undefined ? { description: state.description } : {}),
         ...(state.references ? { references: state.references } : {}),
       };
     },

package/src/elements/store.ts

@@ -116,6 +116,8 @@ export type {
   KvStoreFxHandle,
   FilesStoreFxHandle,
   IndexStoreFxHandle,
+  VectorIndexStoreFxHandle,
+  TextIndexStoreFxHandle,
 } from "./store/runtime.ts";
 
 export { fileKeyWarnings, contentAddressedKey, projectFileKeys } from "./store/files-policy.ts";

package/src/elements/vault.test.ts

@@ -9,6 +9,7 @@
 import { describe, expect, test } from "bun:test";
 import { envVaultDriver, memoryVaultDriver } from "../drivers/index.ts";
 import { createFx } from "../kernel/fx.ts";
+import { REDACTED_PLACEHOLDER, Redacted } from "../kernel/redacted.ts";
 import {
   createVaultRuntime,
   fingerprintSecretSync,
@@ -200,17 +201,39 @@ describe("redaction + fingerprints", () => {
     const lines: Array<{ message: string; data?: Record<string, unknown> }> = [];
     const { fx } = createFxContextWithVault(runtime, lines);
 
-    const value = fx.vault("STRIPE_KEY");
-    expect(value).toBe(secret);
+    const wrapped = fx.vault("STRIPE_KEY");
+    expect(wrapped.reveal()).toBe(secret);
 
-    fx.log.info(`charging with ${value}`, { key: value, nested: { k: value } });
+    fx.log.info(`charging with ${wrapped}`, { key: wrapped, nested: { k: wrapped } });
+    // Revealed cleartext still hits the known-value substring scrub.
     fx.log.error(secret, { stripe: secret });
 
     for (const line of lines) {
       expect(line.message).not.toContain(secret);
       expect(JSON.stringify(line.data ?? {})).not.toContain(secret);
-      expect(line.message).toContain(SECRET_MASK);
     }
+    expect(lines[0]!.message).toContain(REDACTED_PLACEHOLDER);
+    expect(lines[1]!.message).toContain(SECRET_MASK);
+  });
+
+  test("Redacted from fx.vault is masked in fx.log without a vault runtime", () => {
+    const secret = "sk_no_vault_runtime";
+    const lines: Array<{ message: string; data?: Record<string, unknown> }> = [];
+    const fx = createFx({
+      flow: "test.redacted",
+      secrets: { STRIPE_KEY: secret },
+      onLog: (_level, message, data) => lines.push({ message, data }),
+    });
+
+    const wrapped = fx.vault("STRIPE_KEY");
+    expect(wrapped).toBeInstanceOf(Redacted);
+    expect(String(wrapped)).toBe(REDACTED_PLACEHOLDER);
+    expect(`${wrapped}`).toBe(REDACTED_PLACEHOLDER);
+    expect(JSON.stringify({ v: wrapped })).toBe(`{"v":"${REDACTED_PLACEHOLDER}"}`);
+
+    fx.log.info("paying", { key: wrapped, nested: { k: [wrapped] } });
+    expect(JSON.stringify(lines[0]!.data)).not.toContain(secret);
+    expect(lines[0]!.data?.key).toBe(REDACTED_PLACEHOLDER);
   });
 
   test("fingerprint is stable and not the value", async () => {