okengine 0.3.4 → 0.3.6

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/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").IndexStoreFxHandle;
+    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);

package/src/console/server/store.ts

@@ -69,6 +69,8 @@ export interface ConsoleStoreChild {
   readonly cache: ConsoleStoreCacheView;
   readonly willNotFire: ConsoleWillNotFire;
   readonly piiColumns: readonly string[];
+  /** Column key → optional human description (SQL tables). */
+  readonly columnDescriptions: Readonly<Record<string, string>>;
 }
 
 /** One row in `console.store.list`. */
@@ -76,6 +78,7 @@ export interface ConsoleStoreRow {
   readonly ref: ResourceRef;
   readonly facet: StoreFacet;
   readonly name: string;
+  readonly description?: string;
   readonly children: readonly ConsoleStoreChild[];
   readonly replicaLagMs: number | null;
   readonly migrationDrift: ConsoleMigrationDrift | null;
@@ -152,6 +155,7 @@ export async function projectStoresList(options: ProjectStoresOptions): Promise<
       ref,
       facet,
       name,
+      ...(store.description !== undefined ? { description: store.description } : {}),
       children,
       replicaLagMs,
       migrationDrift: facet === "sql" ? drift : null,
@@ -219,10 +223,27 @@ function childrenOf(
       },
       willNotFire,
       piiColumns,
+      columnDescriptions: columnDescriptionsFor(store, childName),
     };
   });
 }
 
+function columnDescriptionsFor(
+  store: NonNullable<Manifest["stores"]>[string],
+  tableName: string,
+): Readonly<Record<string, string>> {
+  const cols = store.tables?.[tableName]?.columns;
+  if (!cols) return {};
+  const out: Record<string, string> = {};
+  for (const [key, col] of Object.entries(cols)) {
+    if (col && typeof col === "object" && "description" in col) {
+      const d = (col as { description?: string }).description;
+      if (typeof d === "string" && d.length > 0) out[key] = d;
+    }
+  }
+  return out;
+}
+
 function flowsTouching(manifest: Manifest, ref: ResourceRef, kind: "reads" | "writes"): string[] {
   const out: string[] = [];
   for (const [flowId, flow] of Object.entries(manifest.flows ?? {})) {
@@ -779,6 +800,9 @@ export function cacheKeyInvalidatedBy(key: string, writeRef: ResourceRef): boole
 /**
  * Open a memory StoreRuntime seeded from Manifest stores (Console default).
  *
+ * The Console Manifest sandbox uses memory drivers for every facet. Real app
+ * boot resolves configured drivers before the Console binds to live runtimes.
+ *
  * @param manifest - Manifest snapshot
  * @param now - Clock
  */

package/src/console/ui/channels/types.ts

@@ -29,6 +29,7 @@ export interface OutcomeRow {
 /** Template row. */
 export interface ChannelTemplate {
   readonly name: string;
+  readonly description?: string;
   readonly medium: string;
   readonly locales: readonly string[];
   readonly from: string | null;

package/src/console/ui/clock/types.ts

@@ -29,6 +29,7 @@ export interface DstAmbiguityView {
 /** One cron row from `console.clock.list`. */
 export interface ClockCronRecord {
   readonly name: string;
+  readonly description?: string;
   readonly status: CronStatus;
   readonly timezone: string;
   readonly overridable: boolean;

package/src/console/ui/display.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "bun:test";
+import { displayLabel } from "./display.ts";
+
+describe("displayLabel", () => {
+  test("falls back to the raw key when description is absent", () => {
+    expect(displayLabel("DATABASE_URL")).toBe("DATABASE_URL");
+    expect(displayLabel("DATABASE_URL", undefined)).toBe("DATABASE_URL");
+    expect(displayLabel("DATABASE_URL", "")).toBe("DATABASE_URL");
+  });
+
+  test("prefers a non-empty description", () => {
+    expect(displayLabel("DATABASE_URL", "Primary database URL")).toBe("Primary database URL");
+  });
+});

package/src/console/ui/display.ts

@@ -0,0 +1,9 @@
+/**
+ * Human-facing label for a technical key when an optional description exists.
+ *
+ * @param key - Technical identifier (Manifest map key / declaration name)
+ * @param description - Optional human description
+ */
+export function displayLabel(key: string, description?: string | null): string {
+  return description && description.length > 0 ? description : key;
+}