okengine 0.3.5 → 0.4.3

package/src/cli/meilisearch-local.ts

@@ -0,0 +1,188 @@
+/**
+ * Local Meilisearch lifecycle for `oke dev` (local mode).
+ *
+ * A Meilisearch server is a fourth moving part only when the app actually
+ * opts into the `meilisearch` store.index driver. This module:
+ *
+ *  - generates the master key once and persists it under `.oke/meilisearch/`
+ *    (`0700` dir / `0600` file, atomic write — same material discipline as
+ *    OpenBao, minus the init/unseal ceremony: a single static key),
+ *  - resolves the `meilisearch` binary from `PATH` (a documented prerequisite,
+ *    like Docker for `--docker`; we never auto-download binaries),
+ *  - spawns it via `Bun.spawn` with its own data dir + port, polls `/health`,
+ *    and hands back an env overlay (`OKE_STORE_INDEX_URL` / `…_KEY`) plus a
+ *    `stop()` that kills the child alongside the app.
+ *
+ * Fail-loud: missing binary / unhealthy server / never-ready all throw
+ * {@link MeilisearchLocalError} — never a silent memory fallback.
+ */
+
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Material directory relative to the project root. */
+export const MEILISEARCH_STATE_DIR_REL = join(".oke", "meilisearch");
+/** Default loopback port for the local server. */
+export const MEILISEARCH_LOCAL_PORT = 7700;
+
+/** Fail-loud local Meilisearch error (missing binary / never healthy). */
+export class MeilisearchLocalError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MeilisearchLocalError";
+  }
+}
+
+/** Options for {@link startLocalMeilisearch}. */
+export interface LocalMeilisearchOptions {
+  readonly cwd?: string;
+  /** Loopback port (default {@link MEILISEARCH_LOCAL_PORT}). */
+  readonly port?: number;
+  /** Override state dir (tests). */
+  readonly stateDir?: string;
+  /** Binary name/path resolved via `Bun.which` (default `meilisearch`). */
+  readonly binary?: string;
+  /** Max ms to wait for `/health` to report available (default 30_000). */
+  readonly readyTimeoutMs?: number;
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+/** A running local Meilisearch child. */
+export interface LocalMeilisearchHandle {
+  /** Base URL the app should talk to. */
+  readonly url: string;
+  /** Master key (also persisted on disk). */
+  readonly masterKey: string;
+  /** Env overlay for the app child. */
+  readonly overlay: Record<string, string>;
+  /** Kill the child (idempotent). */
+  readonly stop: () => void;
+}
+
+/** Env overlay for the app child. */
+export function meilisearchStackEnv(handle: LocalMeilisearchHandle): Record<string, string> {
+  return handle.overlay;
+}
+
+function writeMaterial(path: string, value: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  chmodSync(dirname(path), 0o700);
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${value}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+  chmodSync(path, 0o600);
+  const back = readFileSync(path, "utf8").trim();
+  if (back !== value) {
+    throw new MeilisearchLocalError(`meilisearch local: verify failed reading ${path}`);
+  }
+}
+
+/** Read the persisted master key, or generate + persist a fresh one. */
+export function ensureMasterKey(stateDir: string): string {
+  const keyPath = join(stateDir, "master.key");
+  if (existsSync(keyPath)) {
+    const key = readFileSync(keyPath, "utf8").trim();
+    if (key.length >= 16) return key;
+    throw new MeilisearchLocalError(
+      `meilisearch local: ${keyPath} exists but is too short — delete it to regenerate`,
+    );
+  }
+  const key = randomBytes(32).toString("hex");
+  writeMaterial(keyPath, key);
+  return key;
+}
+
+/**
+ * Start a local Meilisearch server and wait for `/health`.
+ *
+ * @param options - cwd / port / binary / injected fetch
+ */
+export async function startLocalMeilisearch(
+  options: LocalMeilisearchOptions = {},
+): Promise<LocalMeilisearchHandle> {
+  const cwd = options.cwd ?? process.cwd();
+  const port = options.port ?? MEILISEARCH_LOCAL_PORT;
+  const stateDir = options.stateDir ?? resolve(cwd, MEILISEARCH_STATE_DIR_REL);
+  const dataDir = join(stateDir, "data");
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const readyTimeoutMs = options.readyTimeoutMs ?? 30_000;
+
+  const binary = options.binary ?? "meilisearch";
+  const resolved = Bun.which(binary);
+  if (!resolved) {
+    throw new MeilisearchLocalError(
+      "meilisearch local: `meilisearch` not found on PATH — install it to use the store.index FTS driver " +
+        "(brew install meilisearch · curl -L https://install.meilisearch.com | sh), " +
+        "or run `oke dev --docker` instead. OKE never auto-downloads binaries.",
+    );
+  }
+
+  const masterKey = ensureMasterKey(stateDir);
+  mkdirSync(dataDir, { recursive: true });
+
+  const url = `http://127.0.0.1:${port}`;
+  const proc = Bun.spawn(
+    [
+      resolved,
+      "--http-addr",
+      `127.0.0.1:${port}`,
+      "--master-key",
+      masterKey,
+      "--db-path",
+      dataDir,
+      "--env",
+      "development",
+      "--no-analytics",
+    ],
+    {
+      cwd,
+      stdout: "ignore",
+      stderr: "inherit",
+      env: { ...(process.env as Record<string, string>) },
+    },
+  );
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Already gone.
+    }
+  };
+
+  const deadline = Date.now() + readyTimeoutMs;
+  for (;;) {
+    if (proc.exitCode !== null) {
+      throw new MeilisearchLocalError(
+        `meilisearch local: server exited (${proc.exitCode}) before becoming healthy`,
+      );
+    }
+    try {
+      const res = await fetchFn(`${url}/health`);
+      if (res.ok) break;
+    } catch {
+      // Not up yet.
+    }
+    if (Date.now() > deadline) {
+      stop();
+      throw new MeilisearchLocalError(
+        `meilisearch local: no /health from ${url} within ${readyTimeoutMs}ms`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+
+  return {
+    url,
+    masterKey,
+    overlay: {
+      OKE_STORE_INDEX_URL: url,
+      OKE_STORE_INDEX_KEY: masterKey,
+    },
+    stop,
+  };
+}

package/src/compiler/extract.test.ts

@@ -240,6 +240,69 @@ export const db = store.sql("app", { schema: { notes } });
       sqlName: "id",
     });
   });
+
+  test("extracts optional description fields additively", async () => {
+    const source = `
+import { store, field, signal, channel, clock, gate, vault } from "okengine";
+
+export const notes = store.schema.table("notes", {
+  title: field.text().notNull().describe("Note title"),
+});
+
+export const db = store.sql("app", {
+  description: "Primary app database",
+  schema: { notes },
+});
+
+export const embeddings = store.index("embeddings", {
+  description: "Document embeddings",
+  dims: 3,
+});
+
+export const sessions = store.kv("sessions", { description: "Session cache" });
+
+export const orderPlaced = signal("order-placed", {
+  delivery: "once",
+  description: "Order placed event",
+});
+
+export const bookingConfirmed = channel.template("booking-confirmed", {
+  medium: "email",
+  description: "Booking confirmation email",
+});
+
+export const expireHolds = clock("expire-holds", {
+  every: "10m",
+  description: "Expire unpaid holds",
+});
+
+export const member = gate.policy("member", {
+  description: "Verified members only",
+  check: ({ auth }) => !!auth?.verified,
+});
+
+export const stripeKey = vault.secret("STRIPE_KEY", {
+  description: "Payments gateway key",
+});
+`;
+    const manifest = await extractFromSources({
+      "src/described.ts": source,
+    });
+
+    expect(manifest.stores?.app?.description).toBe("Primary app database");
+    expect(manifest.stores?.app?.tables?.notes?.columns?.title).toMatchObject({
+      description: "Note title",
+    });
+    expect(manifest.stores?.embeddings?.description).toBe("Document embeddings");
+    expect(manifest.stores?.sessions?.description).toBe("Session cache");
+    expect(manifest.signals?.["order-placed"]?.description).toBe("Order placed event");
+    expect(manifest.channels?.["booking-confirmed"]?.description).toBe(
+      "Booking confirmation email",
+    );
+    expect(manifest.clocks?.["expire-holds"]?.description).toBe("Expire unpaid holds");
+    expect(manifest.gates?.member?.description).toBe("Verified members only");
+    expect(manifest.vault?.STRIPE_KEY?.description).toBe("Payments gateway key");
+  });
 });
 
 describe("extractManifest — on(http.resource(...))", () => {

package/src/compiler/extract.ts

@@ -420,6 +420,7 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
   const chain: string[] = [];
   let sqlType: "text" | "integer" | undefined;
   let sqlName: string | undefined;
+  let description: string | undefined;
   let defaultValue: string | number | boolean | null | undefined;
   let hasDefault = false;
   let cur: AstNode | undefined = node;
@@ -435,6 +436,9 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
         if (method === "as") {
           sqlName = stringArg(call.arguments[0]) ?? sqlName;
         }
+        if (method === "describe") {
+          description = stringArg(call.arguments[0]) ?? description;
+        }
         if (method === "default") {
           const lit = call.arguments[0];
           if (lit && lit.type === "Literal") {
@@ -504,6 +508,7 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
     ...(methods.has("primaryKey") ? { primaryKey: true } : {}),
     ...(methods.has("unique") ? { unique: true } : {}),
     ...(hasDefault ? { default: defaultValue ?? null } : {}),
+    ...(description !== undefined ? { description } : {}),
     ...(methods.has("pii") ? { pii: true } : {}),
     ...(methods.has("sensitive") ? { sensitive: true } : {}),
   };
@@ -597,7 +602,12 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
         const storeName = stringArg(call.arguments[0]) ?? "store";
         const ref = `${facet}:${storeName}` as const;
         const bindingName = enclosingConstName(call, program);
+        const storeOpts = objectArg(call.arguments[1]);
+        const description = stringProp(storeOpts, "description");
         scope.stores[storeName] = scope.stores[storeName] ?? { facet };
+        if (description) {
+          scope.stores[storeName]!.description = description;
+        }
         if (facet === "sql") {
           attachSchemaOption(call.arguments[1], scope.stores[storeName]!, scope);
         }
@@ -643,7 +653,13 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
     if (obj === "gate" && prop === "policy") {
       const policyName = stringArg(call.arguments[0]);
       if (policyName) {
-        scope.gates[policyName] = { kind: "policy", roles: [policyName] };
+        const opts = objectArg(call.arguments[1]);
+        const description = stringProp(opts, "description");
+        scope.gates[policyName] = {
+          kind: "policy",
+          roles: [policyName],
+          ...(description ? { description } : {}),
+        };
         const bindingName = enclosingConstName(call, program);
         if (bindingName) {
           scope.gateIds.set(bindingName, policyName);
@@ -661,26 +677,23 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
       const max = numberProp(opts, "max");
       const per = stringProp(opts, "per");
       const keyBy = stringProp(opts, "keyBy");
+      const description = stringProp(opts, "description");
       if (max !== undefined && per) {
         const expr = `rate:${strategy}:${max}/${per}`;
         const bindingName = enclosingConstName(call, program);
+        const rateGate = {
+          kind: "rate" as const,
+          strategy,
+          max,
+          per,
+          ...(keyBy ? { keyBy } : {}),
+          ...(description ? { description } : {}),
+        };
         if (bindingName) {
-          scope.gates[bindingName] = {
-            kind: "rate",
-            strategy,
-            max,
-            per,
-            ...(keyBy ? { keyBy } : {}),
-          };
+          scope.gates[bindingName] = rateGate;
           scope.gateIds.set(bindingName, expr);
         } else {
-          scope.gates[expr] = {
-            kind: "rate",
-            strategy,
-            max,
-            per,
-            ...(keyBy ? { keyBy } : {}),
-          };
+          scope.gates[expr] = rateGate;
         }
       }
     }
@@ -691,9 +704,11 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
       if (templateName) {
         const medium = stringProp(opts, "medium");
         const locales = stringArrayProp(opts, "locales");
+        const description = stringProp(opts, "description");
         scope.channels[templateName] = {
           ...(medium ? { medium: medium as Channel["medium"] } : { medium: "email" }),
           ...(locales ? { locales } : {}),
+          ...(description ? { description } : {}),
         };
         const bindingName = enclosingConstName(call, program);
         if (bindingName) {
@@ -809,6 +824,9 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
       if (delivery) {
         const signal: Signal = {
           delivery,
+          ...(stringProp(opts, "description")
+            ? { description: stringProp(opts, "description") }
+            : {}),
           ...(numberProp(opts, "retries") !== undefined
             ? { retries: numberProp(opts, "retries") }
             : {}),
@@ -839,6 +857,9 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
         ...(boolProp(opts, "overridable") !== undefined
           ? { overridable: boolProp(opts, "overridable") }
           : {}),
+        ...(stringProp(opts, "description")
+          ? { description: stringProp(opts, "description") }
+          : {}),
       };
     }
   }

package/src/compiler/fixtures/skyport/src/flows/payments/index.ts

@@ -5,7 +5,11 @@ export const chargeBooking = flow({
   name: "payments.chargeBooking",
   durable: true,
   do: async ({ orderId }, fx) => {
-    const intent = await fx.step("create-intent", () => fx.vault(stripeKey));
+    // Journal only serializable step values — a Redacted is not journaled.
+    const intent = await fx.step("create-intent", async () => ({
+      id: `pi_${orderId}`,
+      key: fx.vault(stripeKey).reveal(),
+    }));
     await fx.clock.sleep("verify-window", "2m");
     return fx.step("confirm", () => intent);
   },

package/src/console/server/channels.ts

@@ -41,6 +41,7 @@ export type ChannelsFace = "inbox" | "deliverability";
 /** One Manifest template row. */
 export interface ConsoleChannelTemplate {
   readonly name: string;
+  readonly description?: string;
   readonly medium: string;
   readonly locales: readonly string[];
   readonly from: string | null;
@@ -214,6 +215,7 @@ export function projectTemplates(manifest: Manifest | null): readonly ConsoleCha
   return Object.entries(manifest?.channels ?? {})
     .map(([name, c]) => ({
       name,
+      ...(c.description !== undefined ? { description: c.description } : {}),
       medium: c.medium ?? "email",
       locales: c.locales ?? [],
       from: c.from ?? null,

package/src/console/server/clock.ts

@@ -28,6 +28,7 @@ import {
 /** One cron row in `console.clock.list`. */
 export interface ConsoleClockRow {
   readonly name: string;
+  readonly description?: string;
   readonly status: CronRow["status"];
   readonly timezone: string;
   readonly overridable: boolean;
@@ -110,8 +111,10 @@ export async function projectClocksList(options: ProjectClocksOptions): Promise<
     .map((row) => {
       const flowIds = flowIdsForCronRow(row, options.manifest);
       const external = flowIds.some((id) => isExternal(flows[id]));
+      const description = options.manifest?.clocks?.[row.name]?.description;
       return {
         name: row.name,
+        ...(description !== undefined ? { description } : {}),
         status: row.status,
         timezone: row.timezone,
         overridable: row.overridable,

package/src/console/server/flows.ts

@@ -158,6 +158,7 @@ const SignalsListOut = z.object({
   signals: z.array(
     z.object({
       name: z.string(),
+      description: z.string().optional(),
       delivery: z.enum(["once", "broadcast", "live"]),
       retries: z.number(),
       deadLetterEnabled: z.boolean(),
@@ -336,6 +337,7 @@ const ChannelsListOut = z.object({
   templates: z.array(
     z.object({
       name: z.string(),
+      description: z.string().optional(),
       medium: z.string(),
       locales: z.array(z.string()),
       from: z.string().nullable(),
@@ -465,6 +467,7 @@ const CronHealthOut = z.object({
 
 const ClockCronOut = z.object({
   name: z.string(),
+  description: z.string().optional(),
   status: z.enum(["active", "paused", "orphaned"]),
   timezone: z.string(),
   overridable: z.boolean(),
@@ -753,6 +756,7 @@ const GatesListOut = z.object({
   gates: z.array(
     z.object({
       name: z.string(),
+      description: z.string().optional(),
       kind: z.enum(["policy", "rate"]),
       scopes: z.array(z.string()),
       roles: z.array(z.string()),
@@ -853,6 +857,13 @@ const PluginsListOut = z.object({
         }),
       ),
       declares: z.array(z.string()),
+      tables: z.record(
+        z.string(),
+        z.object({
+          plane: z.string().optional(),
+          description: z.string().optional(),
+        }),
+      ),
       intercepts: z.array(
         z.object({
           stage: z.string(),
@@ -1216,6 +1227,7 @@ const StoreListOut = z.object({
       ref: z.string(),
       facet: z.enum(["sql", "kv", "files", "index"]),
       name: z.string(),
+      description: z.string().optional(),
       children: z.array(
         z.object({
           name: z.string(),
@@ -1229,6 +1241,7 @@ const StoreListOut = z.object({
           }),
           willNotFire: WillNotFireOut,
           piiColumns: z.array(z.string()),
+          columnDescriptions: z.record(z.string(), z.string()),
         }),
       ),
       replicaLagMs: z.number().nullable(),

package/src/console/server/gates.ts

@@ -48,6 +48,7 @@ export type GatePrincipalKind = "role" | "key" | "user";
 /** One Module:Action / flow / gate surface row. */
 export interface ConsoleGateDefRow {
   readonly name: string;
+  readonly description?: string;
   readonly kind: "policy" | "rate";
   readonly scopes: readonly string[];
   readonly roles: readonly string[];
@@ -477,6 +478,7 @@ function projectGateDefs(
       def.kind === "rate" || name.startsWith("rate:") ? "rate" : "policy";
     rows.push({
       name,
+      ...(def.description !== undefined ? { description: def.description } : {}),
       kind,
       scopes: [...(def.scopes ?? [])],
       roles: [...(def.roles ?? [])],

package/src/console/server/plugins.ts

@@ -8,7 +8,13 @@
 
 import { allHookCostSummaries, type HookCostSummary } from "../../kernel/hook-timing.ts";
 import type { PluginRegistry } from "../../kernel/registry.ts";
-import type { Manifest, ManifestChange, Plugin, PluginOrigin } from "../../manifest/types.ts";
+import type {
+  Manifest,
+  ManifestChange,
+  Plugin,
+  PluginOrigin,
+  PluginTable,
+} from "../../manifest/types.ts";
 import { CORE_PLUGINS, isCorePluginOn, type PluginConfigProbe } from "../../plugins/catalogue.ts";
 import type { PackageJsonProbe, SupplyChainSignals } from "../../plugins/supply-chain.ts";
 import type { ScanSourceFile } from "../../plugins/node-import-scan.ts";
@@ -46,6 +52,8 @@ export interface ConsolePluginRow {
   readonly summary: string | null;
   readonly scopes: readonly PluginScopeView[];
   readonly declares: readonly string[];
+  /** Optional metadata for `table:*` declares. */
+  readonly tables: Readonly<Record<string, PluginTable>>;
   readonly intercepts: readonly PluginInterceptView[];
   readonly hookCost: {
     readonly count: number;
@@ -133,6 +141,7 @@ export async function projectPluginsList(
         version: meta?.version ?? manifestPlugin?.version ?? null,
         summary: spec.summary,
         declares: meta?.declares ?? manifestPlugin?.declares ?? [],
+        tables: meta?.tables ?? manifestPlugin?.tables ?? {},
         interceptStages: meta?.intercepts ?? manifestPlugin?.intercepts ?? [],
         scopes: meta?.scopes ?? [],
         costs,
@@ -155,6 +164,7 @@ export async function projectPluginsList(
         version: meta.version,
         summary: null,
         declares: meta.declares,
+        tables: meta.tables,
         interceptStages: meta.intercepts,
         scopes: meta.scopes,
         costs,
@@ -184,6 +194,7 @@ interface PluggedMeta {
   readonly version: string | null;
   readonly declares: readonly string[];
   readonly intercepts: readonly string[];
+  readonly tables: Readonly<Record<string, PluginTable>>;
   readonly scopes: readonly PluginScopeView[];
   readonly origin?: PluginOrigin;
 }
@@ -199,6 +210,7 @@ function collectPlugged(
         version: p.version ?? null,
         declares: p.declares ?? [],
         intercepts: p.intercepts ?? [],
+        tables: p.tables ?? {},
         scopes: [],
         origin: p.origin,
       });
@@ -214,10 +226,15 @@ function collectPlugged(
           ? { kind: "app" }
           : { kind: entry.scope.kind, name: entry.scope.name };
       const scopes = [...(prev?.scopes ?? []), scope];
+      const tables = {
+        ...(prev?.tables ?? {}),
+        ...(caps.tables ?? {}),
+      };
       out.set(id, {
         version: caps.version ?? prev?.version ?? null,
         declares: caps.declares.length ? [...caps.declares] : (prev?.declares ?? []),
         intercepts: caps.intercepts.length ? [...caps.intercepts] : (prev?.intercepts ?? []),
+        tables,
         scopes,
         origin: prev?.origin,
       });
@@ -243,6 +260,7 @@ async function buildRow(input: {
   readonly version: string | null;
   readonly summary: string | null;
   readonly declares: readonly string[];
+  readonly tables: Readonly<Record<string, PluginTable>>;
   readonly interceptStages: readonly string[];
   readonly scopes: readonly PluginScopeView[];
   readonly costs: Readonly<Record<string, HookCostSummary>>;
@@ -286,6 +304,7 @@ async function buildRow(input: {
     summary: input.summary,
     scopes: input.scopes,
     declares: [...input.declares],
+    tables: { ...input.tables },
     intercepts,
     hookCost: cost
       ? {

package/src/console/server/signals.ts

@@ -28,6 +28,7 @@ export interface SignalEndpoint {
 /** One row in `console.signals.list`. */
 export interface ConsoleSignalRow {
   readonly name: string;
+  readonly description?: string;
   readonly delivery: "once" | "broadcast" | "live";
   readonly retries: number;
   readonly deadLetterEnabled: boolean;
@@ -112,8 +113,10 @@ export async function projectSignalsList(
       withCause(dl, cfg.name, options.runs),
     );
 
+    const description = options.manifest?.signals?.[cfg.name]?.description;
     rows.push({
       name: cfg.name,
+      ...(description !== undefined ? { description } : {}),
       delivery: cfg.delivery,
       retries: stats?.retries ?? cfg.retries,
       deadLetterEnabled: stats?.deadLetterEnabled ?? cfg.deadLetter,
@@ -142,8 +145,10 @@ export async function projectSignalsList(
     if (rows.some((r) => r.name === name)) continue;
     const producers = producersOf(name, flows);
     const consumers = consumersOf(name, flows);
+    const description = options.manifest?.signals?.[name]?.description;
     rows.push({
       name,
+      ...(description !== undefined ? { description } : {}),
       delivery: stats.delivery,
       retries: stats.retries,
       deadLetterEnabled: stats.deadLetterEnabled,

package/src/console/server/store.test.ts

@@ -130,6 +130,23 @@ describe("willNotFireFor", () => {
   });
 });
 
+describe("index driver resolution", () => {
+  test("console manifest runtime uses the shared boot switch (memory default)", async () => {
+    const runtime = await createManifestStoreRuntime(MANIFEST);
+    const decl = runtime.declarations.get("index:docs");
+    expect(decl).toBeDefined();
+    const handle = (await runtime.open(decl!, {
+      effects: { reads: ["index:docs"], writes: ["index:docs"] },
+    })) as import("../../elements/store.ts").VectorIndexStoreFxHandle;
+    expect(handle.driverId).toBe("memory");
+    await handle.upsert("d1", [1, 0, 0], { t: 1 });
+    const hits = await handle.search([1, 0, 0], 1);
+    expect(hits[0]?.id).toBe("d1");
+    expect(hits[0]?.meta).toEqual({ t: 1 });
+    await runtime.close();
+  });
+});
+
 describe("PII masking survives SELECT *", () => {
   test("masks classified columns; reveal returns cleartext", async () => {
     const runtime = await createManifestStoreRuntime(MANIFEST);