okengine 0.17.2 → 0.18.4

package/src/compiler/extract.ts

@@ -81,6 +81,8 @@ type DeclaredSchemaTable = {
   readonly rls?: boolean;
   readonly policies?: Record<string, TablePolicy>;
   readonly tenantScoped?: boolean;
+  /** `false` when `store.schema.live(false)` opted out (project flag on). */
+  readonly live?: boolean;
 };
 
 interface ProjectScope {
@@ -111,11 +113,30 @@ interface ProjectScope {
   i18n?: Manifest["i18n"];
   topology?: Manifest["topology"];
   images?: Record<string, string>;
+  /** Store-wide live defaulting — `oke({ store: { live: true } })`. */
+  store?: Manifest["store"];
   flows: Record<string, Flow>;
   /** Export name → flow id (for agent tools). */
   flowExports: Map<string, string>;
   /** Local binding name → store.resource declaration (for on(http.resource)). */
-  resources: Map<string, { storeName: string; storeRef: string; breaking?: boolean }>;
+  resources: Map<
+    string,
+    {
+      storeName: string;
+      storeRef: string;
+      breaking?: boolean;
+      /** Physical table name (second argument or schema-table binding ref). */
+      tableName?: string;
+      /**
+       * Raw `live` option on `store.resource(…, { live })` — `undefined`
+       * when omitted. Resolved against the project-wide `store.live` flag
+       * and the table's `live: false` opt-out in pass 2.
+       */
+      liveOpt?: boolean;
+      /** `true` when the resource carries a live query surface. */
+      live?: boolean;
+    }
+  >;
   /** Local binding name → medium, for `const x = channel.email(…)` binders. */
   channelMediumBindings: Map<string, ChannelMedium>;
 }
@@ -209,12 +230,14 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
   if (Object.keys(journeys).length > 0) manifest.journeys = journeys;
   if (Object.keys(drivers).length > 0) manifest.drivers = drivers;
   if (scope.tenancy) manifest.tenancy = scope.tenancy;
+  if (scope.store && scope.store.live === true) manifest.store = { live: true };
   if (scope.i18n) manifest.i18n = scope.i18n;
   if (scope.topology) manifest.topology = scope.topology;
   if (scope.images) manifest.images = scope.images;
 
   applyTenancyDefaults(manifest);
   assertTenantSafeSchema(manifest);
+  applyLiveDefaults(manifest, scope);
 
   return manifest;
 }
@@ -271,6 +294,7 @@ function collectDeclarations(filePath: string, program: AstNode, scope: ProjectS
     const name = stringProp(opts, "name");
     if (name) scope.app = name;
     applyOkeTenantConfig(opts, scope);
+    applyOkeStoreLiveConfig(opts, scope);
   });
 }
 
@@ -470,23 +494,26 @@ function tableFromDeclared(t: DeclaredSchemaTable): {
   rls?: boolean;
   policies?: Record<string, TablePolicy>;
   tenantScoped?: boolean;
+  live?: boolean;
 } {
   return {
     columns: t.columns,
     ...(t.rls ? { rls: true } : {}),
     ...(t.policies ? { policies: t.policies } : {}),
     ...(t.tenantScoped === false ? { tenantScoped: false } : {}),
+    ...(t.live === false ? { live: false } : {}),
   };
 }
 
 function parseSchemaTableExtras(
   node: AstNode | undefined,
-): Pick<DeclaredSchemaTable, "rls" | "policies" | "tenantScoped"> {
+): Pick<DeclaredSchemaTable, "rls" | "policies" | "tenantScoped" | "live"> {
   if (!node || node.type !== "ArrayExpression") return {};
   const els = (node as AstNode & { elements?: AstNode[] }).elements ?? [];
   const policies: Record<string, TablePolicy> = {};
   let rls = false;
   let tenantScoped: boolean | undefined;
+  let live: boolean | undefined;
   for (const el of els) {
     if (!el || el.type !== "CallExpression") continue;
     const extra = parseSchemaTableExtra(el as CallExpression);
@@ -499,6 +526,10 @@ function parseSchemaTableExtras(
       tenantScoped = false;
       continue;
     }
+    if (extra.kind === "live") {
+      live = false;
+      continue;
+    }
     policies[extra.name] = extra.policy;
     rls = true;
   }
@@ -506,6 +537,7 @@ function parseSchemaTableExtras(
     ...(rls ? { rls: true } : {}),
     ...(Object.keys(policies).length > 0 ? { policies } : {}),
     ...(tenantScoped === false ? { tenantScoped: false } : {}),
+    ...(live === false ? { live: false } : {}),
   };
 }
 
@@ -514,6 +546,7 @@ function parseSchemaTableExtra(
 ):
   | { kind: "rls" }
   | { kind: "unscoped" }
+  | { kind: "live" }
   | { kind: "policy"; name: string; policy: TablePolicy }
   | undefined {
   const callee = call.callee;
@@ -526,6 +559,9 @@ function parseSchemaTableExtra(
   if (method === "unscoped" && isStoreSchemaCallee(member.object)) {
     return { kind: "unscoped" };
   }
+  if (method === "live" && isStoreSchemaCallee(member.object)) {
+    return { kind: "live" };
+  }
   if (method === "policy" && isStoreSchemaCallee(member.object)) {
     const name = stringArg(call.arguments[0]);
     if (!name) return undefined;
@@ -610,19 +646,63 @@ function parseDeclaredColumns(obj: AstNode): Record<string, DeclaredColumn> {
   return out;
 }
 
+/**
+ * Abstract `field.*` SQL type heads recognized by the compiler.
+ */
+const FIELD_SQL_TYPES: ReadonlySet<string> = new Set([
+  "text",
+  "varchar",
+  "char",
+  "boolean",
+  "smallint",
+  "integer",
+  "bigint",
+  "serial",
+  "smallserial",
+  "bigserial",
+  "numeric",
+  "decimal",
+  "real",
+  "doublePrecision",
+  "json",
+  "jsonb",
+  "uuid",
+  "time",
+  "timestamp",
+  "date",
+  "interval",
+  "point",
+  "line",
+  "bytea",
+  "inet",
+  "cidr",
+  "macaddr",
+  "macaddr8",
+]);
+
+/** Manifest primitive for a field head (`decimal` collapses into `numeric`). */
+function manifestFieldType(head: string): DeclaredColumn["type"] {
+  return head === "decimal" ? "numeric" : (head as DeclaredColumn["type"]);
+}
+
 /**
  * Walk `field.text().notNull().pii()` (and similar) into a DeclaredColumn.
  *
+ * Recognizes every {@link FIELD_SQL_TYPES} head plus the option bag passed to
+ * the factory call (`field.varchar({ length: 256 })`,
+ * `field.timestamp({ mode: "date", precision: 6 })`, …).
+ *
  * @param node - AST node for the column value
  * @param key - JS key (for default sqlName)
  */
 function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined {
   const chain: string[] = [];
-  let sqlType: "text" | "integer" | undefined;
+  let sqlType: DeclaredColumn["type"];
   let sqlName: string | undefined;
   let description: string | undefined;
   let defaultValue: string | number | boolean | null | undefined;
   let hasDefault = false;
+  let optionsNode: AstNode | undefined;
   let cur: AstNode | undefined = node;
 
   while (cur && cur.type === "CallExpression") {
@@ -639,7 +719,7 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
         if (method === "describe") {
           description = stringArg(call.arguments[0]) ?? description;
         }
-        if (method === "defaultFn") {
+        if (method === "defaultFn" || method === "okid" || method === "now") {
           hasDefault = true;
           defaultValue = defaultValue ?? null;
         }
@@ -669,30 +749,29 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
     break;
   }
 
-  // Remaining should be field.text / field.integer
+  // Remaining should be field.<type> — bare MemberExpression or factory call
+  // with an options object (field.varchar({ length: 256 })).
   if (cur && cur.type === "MemberExpression") {
     const member = cur as AstNode & { object: AstNode; property: AstNode };
     if (identifierName(member.object) === "field") {
       const t = identifierName(member.property);
-      if (t === "text" || t === "integer") sqlType = t;
+      if (t && FIELD_SQL_TYPES.has(t)) sqlType = manifestFieldType(t);
     }
   }
 
   // Also: field.text() ends as CallExpression with callee MemberExpression field.text
   if (!sqlType && node.type === "CallExpression") {
-    // Re-walk to find field.text() / field.integer() as a call
     let probe: AstNode | undefined = node;
     while (probe && probe.type === "CallExpression") {
       const call = probe as CallExpression;
       const callee = call.callee;
       if (callee.type === "MemberExpression") {
         const member = callee as AstNode & { object: AstNode; property: AstNode };
-        if (
-          identifierName(member.object) === "field" &&
-          (identifierName(member.property) === "text" ||
-            identifierName(member.property) === "integer")
-        ) {
-          sqlType = identifierName(member.property) as "text" | "integer";
+        const head = identifierName(member.property);
+        if (identifierName(member.object) === "field" && head && FIELD_SQL_TYPES.has(head)) {
+          sqlType = manifestFieldType(head);
+          const arg0 = call.arguments[0];
+          if (arg0?.type === "ObjectExpression") optionsNode = arg0;
           break;
         }
         probe = member.object;
@@ -715,6 +794,7 @@ function parseFieldChain(node: AstNode, key: string): DeclaredColumn | undefined
     ...(description !== undefined ? { description } : {}),
     ...(methods.has("pii") ? { pii: true } : {}),
     ...(methods.has("sensitive") ? { sensitive: true } : {}),
+    ...parseFieldOptions(optionsNode),
   };
   if (methods.has("retain")) {
     // retain("7y") — find the call in the original chain by re-walk
@@ -780,6 +860,49 @@ function parseReferencesArg(
   return {};
 }
 
+/**
+ * Extract per-type options (`length`, `precision`, `scale`, `withTimezone`,
+ * `mode`, `fields`, `enumValues`) from a factory call's options object.
+ *
+ * @param node - Options object AST node (may be undefined)
+ */
+function parseFieldOptions(node: AstNode | undefined): Partial<DeclaredColumn> | undefined {
+  if (!node || node.type !== "ObjectExpression") return undefined;
+  const length = numberProp(node, "length");
+  const precision = numberProp(node, "precision");
+  const scale = numberProp(node, "scale");
+  const withTimezone = boolProp(node, "withTimezone");
+  const mode = stringProp(node, "mode");
+  const fields = stringProp(node, "fields");
+  const enumNode = objectProp(node, "enum");
+  const enumValues =
+    enumNode?.type === "ArrayExpression"
+      ? ((enumNode as AstNode & { elements?: AstNode[] }).elements ?? [])
+          .map((el) => stringArg(el))
+          .filter((v): v is string => v !== undefined)
+      : undefined;
+  if (
+    length === undefined &&
+    precision === undefined &&
+    scale === undefined &&
+    withTimezone === undefined &&
+    mode === undefined &&
+    fields === undefined &&
+    (enumValues === undefined || enumValues.length === 0)
+  ) {
+    return undefined;
+  }
+  return {
+    ...(length !== undefined ? { length } : {}),
+    ...(precision !== undefined ? { precision } : {}),
+    ...(scale !== undefined ? { scale } : {}),
+    ...(withTimezone !== undefined ? { withTimezone } : {}),
+    ...(mode !== undefined ? { mode } : {}),
+    ...(fields !== undefined ? { fields } : {}),
+    ...(enumValues !== undefined && enumValues.length > 0 ? { enumValues } : {}),
+  };
+}
+
 function camelToSnakeKey(key: string): string {
   return key
     .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
@@ -852,11 +975,27 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
         const storeName = ref.split(":")[1] ?? dbName ?? "store";
         const opts = objectArg(call.arguments[2]);
         const breaking = opts ? boolProp(opts, "breaking") === true : false;
+        // Table name: the second argument may be a schema-table binding
+        // (resolve to its declared name) or a bare string literal.
+        const tableArgName = identifierName(call.arguments[1]);
+        const tableName =
+          (tableArgName
+            ? scope.bindings.get(tableArgName)?.kind === "table"
+              ? scope.bindings.get(tableArgName)?.ref
+              : undefined
+            : undefined) ?? stringArg(call.arguments[1]);
         if (bindingName) {
+          // Raw declaration: `{ live: true }` opts in, `{ live: false }`
+          // opts out of the project-wide default, omitted defers to the
+          // project flag resolved in pass 2 (scope/store live stamp complete
+          // and `schemaTables` populated regardless of file order).
+          const liveOpt = opts ? boolProp(opts, "live") : undefined;
           scope.resources.set(bindingName, {
             storeName,
             storeRef: ref,
             ...(breaking ? { breaking: true } : {}),
+            ...(tableName !== undefined ? { tableName } : {}),
+            ...(liveOpt !== undefined ? { liveOpt } : {}),
           });
         }
       }
@@ -1584,7 +1723,21 @@ function registerFlow(args: {
   flow.source = `${args.file.path}:${line}`;
 
   if (boolProp(opts, "durable")) flow.durable = true;
-  if (typeof liveFromTrigger === "string") flow.live = liveFromTrigger;
+  if (typeof liveFromTrigger === "string") {
+    flow.live = liveFromTrigger;
+    // Manual live surface — `.live(tableBinding)` on the trigger. Synthesize
+    // the internal signal exactly like `store.resource({ live: true })` so
+    // the Manifest stays a faithful mirror of what booted, and enforce the
+    // same guardrails (PK required; updatedAt / RLS warnings).
+    const liveTable = trigger?.liveTable;
+    if (liveTable !== undefined) {
+      assertLiveGuardrails(args.scope, liveTable, `sql:${liveTable}`);
+      args.scope.signals[`oke/live/sql:${liveTable}`] = {
+        delivery: "live",
+        description: `Live query CDC fan-out for ${liveTable} (synthesized by .live(table))`,
+      };
+    }
+  }
   if (boolProp(opts, "breaking")) flow.breaking = true;
 
   const slo = parseSlo(objectProp(opts, "slo"));
@@ -1787,6 +1940,19 @@ function registerResourceMount(
   }
   const resource = baseName ? scope.resources.get(baseName) : undefined;
 
+  // Resolve the table's live posture once: an explicit `{ live: false }`
+  // opts out, an explicit `{ live: true }` opts in, and an omitted `live`
+  // defers to the project-wide `store.live` flag unless the table itself
+  // declared `store.schema.live(false)`. The raw option stays on the
+  // resource; this pass-2 resolution relies on the fully-populated scope
+  // (project flag stamped in pass 1, `schemaTables` regardless of file order).
+  const resourceLive =
+    resource?.liveOpt !== undefined
+      ? resource.liveOpt
+      : resource?.tableName !== undefined &&
+        scope.store?.live === true &&
+        scope.schemaTables.get(resource.tableName)?.live !== false;
+
   const storeRef: ResourceRef | undefined =
     resource?.storeRef !== undefined ? (resource.storeRef as ResourceRef) : undefined;
   const effects: Effects | undefined = storeRef
@@ -1823,6 +1989,40 @@ function registerResourceMount(
     scope.bindings.set(name, { kind: "flow", ref: name });
   }
 
+  // Live query surface — synthesize GET <path>/live + the internal signal
+  // exactly like `store.resource({ live: true })` does at runtime so the
+  // Manifest stays a faithful mirror of what booted. Gate is the resolved
+  // `resourceLive` (explicit opt-in/opt-out, else the project-wide
+  // `store.live` flag minus the table's `live: false` opt-out). Requires a
+  // statically known table name; runtime `resolveTableName` throws for
+  // anything else, so an unresolvable table never boots a live surface either.
+  if (resourceLive === true && resource !== undefined) {
+    const tableName = resource.tableName;
+    if (tableName !== undefined) {
+      const resourceStoreRef = resource.storeRef;
+      assertLiveGuardrails(scope, tableName, resourceStoreRef);
+      const signalName = `oke/live/sql:${tableName}`;
+      scope.signals[signalName] = {
+        delivery: "live",
+        description: `Live query CDC fan-out for ${tableName} (synthesized by store.resource live)`,
+      };
+      const flowName = `_live_${tableName}`;
+      scope.flows[flowName] = {
+        trigger: { http: { method: "GET", path: `${path}/live` } },
+        effects: {
+          reads: [
+            (resourceStoreRef ?? sqlTableRef(tableName)) as ResourceRef,
+            `signal:${signalName}` as ResourceRef,
+          ],
+        },
+        ...(gates && gates.length > 0 ? { gates } : {}),
+        ...(resource.breaking ? { breaking: true } : {}),
+        source: `${file.path}:${line}`,
+      };
+      scope.bindings.set(flowName, { kind: "flow", ref: flowName });
+    }
+  }
+
   const exportName = enclosingConstName(onCall, program);
   if (exportName) {
     scope.bindings.set(exportName, { kind: "flow", ref: baseName ?? exportName });
@@ -1942,8 +2142,10 @@ function registerNamedTableCrud(call: CallExpression, file: SourceFile, scope: P
 interface ParsedTrigger {
   trigger: Trigger;
   gates?: string[];
-  /** Live signal name from `.live(signal)` / `http.live(signal)`. */
+  /** Live signal name from `.live(signal)` / `http.live(signal)` / `.live(table)`. */
   live?: string;
+  /** Physical table name when `.live(tableBinding)` — manual live surface. */
+  liveTable?: string;
 }
 
 function parseTrigger(
@@ -1963,6 +2165,10 @@ function parseTrigger(
       return { trigger: {} };
     }
 
+    // mcp.tool("bookings.create").gate(...) / mcp.tool(name)
+    const mcpTool = parseMcpTrigger(call, scope);
+    if (mcpTool) return mcpTool;
+
     // http.post("/x").gate(...) / http.get("/x").live(signal) / http.live(signal)
     const http = parseHttpTrigger(call, scope, filePath);
     if (http) return http;
@@ -1977,6 +2183,8 @@ function parseTrigger(
   if (node.type === "MemberExpression") {
     const http = parseHttpTrigger(node, scope, filePath);
     if (http) return http;
+    const mcp = parseMcpTrigger(node, scope);
+    if (mcp) return mcp;
   }
 
   if (node.type === "Identifier") {
@@ -2004,6 +2212,19 @@ function resolveSignalName(node: AstNode | undefined, scope: ProjectScope): stri
   return id;
 }
 
+/**
+ * Resolve a `.live(tableBinding)` argument — a `store.schema.table(...)`
+ * (or `table(...)`) binding — to the internal live-signal name
+ * `oke/live/sql:<table>`. Returns `undefined` for anything that is not a
+ * table binding (signal handles resolve through {@link resolveSignalName}).
+ */
+function resolveLiveTableName(node: AstNode | undefined, scope: ProjectScope): string | undefined {
+  const id = identifierName(node);
+  if (!id) return undefined;
+  const binding = scope.bindings.get(id);
+  return binding?.kind === "table" ? binding.ref : undefined;
+}
+
 function parseHttpTrigger(
   leaf: AstNode,
   scope: ProjectScope,
@@ -2014,6 +2235,8 @@ function parseHttpTrigger(
   let method: string | undefined;
   let path: string | undefined;
   let live: string | undefined;
+  /** Table name when `.live(tableBinding)` — a manual live query surface. */
+  let liveTable: string | undefined;
   const gateNames: string[] = [];
 
   for (const node of chain) {
@@ -2028,10 +2251,20 @@ function parseHttpTrigger(
       if (obj.type === "Identifier" && (obj as Identifier).name === "http" && prop) {
         if (prop === "live") {
           method = "GET";
-          const signalName = resolveSignalName(c.arguments[0], scope);
+          const tableName = resolveLiveTableName(c.arguments[0], scope);
+          const signalName =
+            tableName !== undefined
+              ? `oke/live/sql:${tableName}`
+              : resolveSignalName(c.arguments[0], scope);
           if (signalName) {
             live = signalName;
-            path = `/_oke/live/${encodeURIComponent(signalName)}`;
+            if (tableName !== undefined) liveTable = tableName;
+            // Keep any explicit GET path chained so far (e.g.
+            // `http.get("/tasks/live").live(tasks)`); only synthesize the
+            // firehose path for the bare `http.live(signal)` form.
+            if (path === undefined) {
+              path = `/_oke/live/${encodeURIComponent(signalName)}`;
+            }
           }
           continue;
         }
@@ -2049,8 +2282,15 @@ function parseHttpTrigger(
 
       if (prop === "public") gateNames.push("public");
       if (prop === "live") {
-        const signalName = resolveSignalName(c.arguments[0], scope);
-        if (signalName) live = signalName;
+        const tableName = resolveLiveTableName(c.arguments[0], scope);
+        const signalName =
+          tableName !== undefined
+            ? `oke/live/sql:${tableName}`
+            : resolveSignalName(c.arguments[0], scope);
+        if (signalName) {
+          live = signalName;
+          if (tableName !== undefined) liveTable = tableName;
+        }
       }
     }
   }
@@ -2082,6 +2322,7 @@ function parseHttpTrigger(
     },
     gates: gateNames.length > 0 ? gateNames : undefined,
     ...(live !== undefined ? { live } : {}),
+    ...(liveTable !== undefined ? { liveTable } : {}),
   };
 }
 
@@ -2119,6 +2360,45 @@ function stripTriggerExtras(trigger: Trigger): Trigger {
   return trigger;
 }
 
+/**
+ * `mcp.tool("name").gate(...)` — per-flow MCP tool opt-in. The Manifest
+ * records `trigger.mcp: { name }` plus any chained gates; absence of the
+ * trigger means the flow is not an MCP tool.
+ */
+function parseMcpTrigger(leaf: AstNode, scope: ProjectScope): ParsedTrigger | undefined {
+  const chain = flattenMemberCallChain(leaf);
+  let toolName: string | undefined;
+  const gateNames: string[] = [];
+
+  for (const node of chain) {
+    if (node.type !== "CallExpression") continue;
+    const c = node as CallExpression;
+    const callee = c.callee;
+    if (callee.type !== "MemberExpression") continue;
+    const member = callee as AstNode & { object: AstNode; property: AstNode };
+    const prop = identifierName(member.property);
+    if (
+      prop === "tool" &&
+      member.object.type === "Identifier" &&
+      (member.object as Identifier).name === "mcp"
+    ) {
+      toolName = stringArg(c.arguments[0]);
+      continue;
+    }
+    if (prop === "gate") {
+      for (const arg of c.arguments) {
+        gateNames.push(...gateNamesFromArg(arg, scope));
+      }
+    }
+  }
+
+  if (!toolName) return undefined;
+  return {
+    trigger: { mcp: { name: toolName } },
+    gates: gateNames.length > 0 ? gateNames : undefined,
+  };
+}
+
 function parseEffectsObject(node: AstNode | undefined): Effects | undefined {
   if (!node) return undefined;
   const effects: Effects = {};
@@ -2493,6 +2773,93 @@ function applyTenancyDefaults(manifest: Manifest): void {
   }
 }
 
+/**
+ * Stamp the project-wide store-live default from `oke({ store: { live: true } })`.
+ *
+ * Mirrors {@link applyOkeTenantConfig} — the proven "opt-in flag flips the
+ * default posture for NEW declarations" pattern. Only `live: true` flips the
+ * default; `false` / omitted leaves today's explicit-only behavior untouched.
+ */
+function applyOkeStoreLiveConfig(opts: AstNode | undefined, scope: ProjectScope): void {
+  const store = objectProp(opts, "store");
+  const live = boolProp(store, "live");
+  if (live !== true) return;
+  scope.store = { ...scope.store, live: true };
+}
+
+/**
+ * Default every SQL table to live when `oke({ store: { live: true } })` is
+ * on, unless the table explicitly opted out with `store.schema.live(false)`.
+ *
+ * The default flip is declaration ergonomics only: each live table is
+ * recorded in the Manifest and its DX Pack A guardrails run through the exact
+ * same {@link assertLiveGuardrails} path as an explicit `live: true` — no
+ * separate, weaker code path. RLS-per-event fan-out cost is unchanged.
+ */
+function applyLiveDefaults(manifest: Manifest, scope: ProjectScope): void {
+  if (manifest.store?.live !== true) return;
+  for (const [storeName, store] of Object.entries(manifest.stores ?? {})) {
+    if (store.facet !== "sql" || !store.tables) continue;
+    for (const [tableName, table] of Object.entries(store.tables)) {
+      if (table.live === false) continue;
+      table.live = true;
+      const signalName = `oke/live/sql:${tableName}`;
+      if (manifest.signals?.[signalName] === undefined) {
+        manifest.signals = manifest.signals ?? {};
+        manifest.signals[signalName] = {
+          delivery: "live",
+          description: `Live query CDC fan-out for ${tableName} (synthesized by store.live project default)`,
+        };
+      }
+      assertLiveGuardrails(scope, tableName, `sql:${storeName}`);
+    }
+  }
+}
+
+/**
+ * DX Pack A guardrails for live query surfaces (Realtime Hardening plan) —
+ * enforced identically for `store.resource({ live: true })` and manual
+ * `.live(table)` flows:
+ *
+ * - **error** — table has no primary key column (upsert/revoked/delete are
+ *   PK-addressed; without one classification cannot address rows).
+ * - **warn** — no `updatedAt`/`updated_at` timestamp column (`rowVersion`
+ *   LWW guard unavailable; optimistic races rely on `mutationId` only).
+ * - **warn** — table carries no RLS policies (live without RLS is
+ *   operator-bypass territory — confirm intent).
+ *
+ * Column information lives on the declared schema table; when the compiler
+ * could not resolve columns statically (bare string table), checks skip.
+ *
+ * @param scope - Project scope (declared tables + resolved drivers)
+ * @param tableName - Physical SQL table name
+ * @param storeRef - ResourceRef of the owning store (`sql:<name>`)
+ */
+function assertLiveGuardrails(scope: ProjectScope, tableName: string, storeRef: string): void {
+  const declared = scope.schemaTables.get(tableName);
+  if (!declared) return;
+  const columns = Object.values(declared.columns);
+  if (columns.length > 0 && !columns.some((c) => c.primaryKey === true)) {
+    throw new Error(
+      `extract: live: true on table "${tableName}" requires a primary key column (upsert/revoked/delete address rows by PK)`,
+    );
+  }
+  const hasUpdatedAt = columns.some((c) => c.sqlName === "updated_at" || c.sqlName === "updatedAt");
+  if (columns.length > 0 && !hasUpdatedAt) {
+    console.warn(
+      `[oke extract] warn: live: true on "${tableName}" has no updatedAt/updated_at column — rowVersion LWW guard unavailable; optimistic races rely on mutationId`,
+    );
+  }
+  if (
+    (declared.rls !== true || Object.keys(declared.policies ?? {}).length === 0) &&
+    storeRef.startsWith("sql:")
+  ) {
+    console.warn(
+      `[oke extract] warn: live: true on "${tableName}" without RLS policies — every gated subscriber sees every row; confirm this is intended`,
+    );
+  }
+}
+
 function assertTenantSafeSchema(manifest: Manifest): void {
   if (manifest.tenancy?.enabled !== true) return;
   for (const [storeName, store] of Object.entries(manifest.stores ?? {})) {

package/src/console/server/invoke-user-flow.ts

@@ -16,6 +16,7 @@ import { isFlowFailure } from "../../kernel/hooks.ts";
 import type { Trigger } from "../../kernel/triggers.ts";
 import type { RlsIdentity } from "../../drivers/pg-rls.ts";
 import { resolveRlsIdentity } from "../../elements/store.ts";
+import { okid } from "../../okid.ts";
 import type { Manifest } from "../../manifest/types.ts";
 import type { ConsoleIdentity } from "./state.ts";
 
@@ -361,7 +362,7 @@ export function bindHostInvokeUserFlow(app: InvokeHostApp): ConsoleInvokeUserFlo
       ...(input.body !== undefined ? { body: input.body } : {}),
     });
 
-    const runId = crypto.randomUUID();
+    const runId = okid();
     const result = await app.execute(flowDef, assembled, trigger, {
       trustedInvoke: true,
       runId,