okengine 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {

package/src/cli/dev-app-runner.ts

@@ -51,6 +51,12 @@ const consoleUrl = Bun.env["OKE_DEV_HERO_CONSOLE"];
 const mcpUrl = Bun.env["OKE_DEV_HERO_MCP"];
 const heroMeta = decodeHeroSnapshot(Bun.env["OKE_DEV_HERO_META"]);
 
+// Signal to boot() where to lazily extract effects from when a flow has no
+// hand-declared `effects` — kernel/boot.ts's mintCapabilities() reads this
+// (explicit opt-in only; the kernel itself never defaults to cwd). `cwd` is
+// already the project root here (Bun.spawn's `cwd` option in dev.ts).
+process.env["OKE_ROOT_DIR"] ??= process.cwd();
+
 const absoluteEntry = resolve(entry);
 const mod = (await import(pathToFileURL(absoluteEntry).href)) as {
   app?: BootableApp;

package/src/cli/dev.ts

@@ -233,6 +233,21 @@ export interface DevOptions {
     readonly env: Record<string, string>;
     readonly onUpdate?: (service: string, status: DevStatus) => void;
   }) => Promise<Map<string, DevStatus>>;
+  /**
+   * Injectable `docker compose ps` runner for live health polls
+   * ({@link startComposeHealthWatch} / keyboard refresh). Default: real
+   * `docker`. When {@link DevOptions.composeHealth} is set and this is
+   * omitted, live polls return empty (unit tests never shell out).
+   *
+   * @param args - Args after `docker` (e.g. `compose -f … ps -a …`)
+   * @param cwd - Compose directory
+   * @param env - Stack env merged into the process env
+   */
+  readonly composeHealthRun?: (
+    args: readonly string[],
+    cwd: string,
+    env: Record<string, string>,
+  ) => Promise<string>;
   /**
    * Regenerate client types (injectable).
    *
@@ -298,6 +313,14 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   /** Reassigned to {@link createAnchoredBoard} wrap after the status board paints. */
   let write: (text: string) => void = options.write ?? ((t) => process.stdout.write(t));
   const chromeWrite = (t: string) => write(formatCliChrome(t));
+  /**
+   * `docker compose ps` runner for live / default health polls.
+   * Explicit inject wins; otherwise a `composeHealth` inject implies tests —
+   * never shell out to a real `docker` binary.
+   */
+  const composeHealthRun =
+    options.composeHealthRun ??
+    (options.composeHealth ? async (): Promise<string> => "[]" : undefined);
   const previousWarn = console.warn;
   console.warn = (...args: unknown[]) => {
     const msg = args.map(String).join(" ");
@@ -656,6 +679,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
               files: composeFiles,
               cwd: dockerOut,
               env: dockerStarted.env,
+              run: composeHealthRun,
               timeoutMs: 20_000,
               isDone: (map) => {
                 // Empty ps (compose just-created / injectable gap): do not spin 20s.
@@ -952,6 +976,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       files: started.files,
       cwd: started.cwd,
       env: started.env,
+      run: composeHealthRun,
       intervalMs: 2_000,
       onChange: (map) => {
         liveComposeHealth = map;
@@ -1325,6 +1350,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
         files: started.files,
         cwd: started.cwd,
         env: started.env,
+        run: composeHealthRun,
       });
       if (liveComposeHealth.get("ai") === "error") heroAiStatus = "error";
       repaintBoard();

package/src/cli/docker-cli.test.ts

@@ -207,6 +207,21 @@ describe("oke start", () => {
     expect(code).toBe(0);
     expect(ran).toBe(entry);
   });
+
+  test("sets OKE_ROOT_DIR so boot() can lazily derive effects for undeclared flows", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-start-rootdir-"));
+    await Bun.write(join(dir, "src/app.ts"), "export {}\n");
+    let seenRootDir: string | undefined;
+    const code = await runStart({
+      cwd: dir,
+      runEntry: async (_e, env) => {
+        seenRootDir = env.OKE_ROOT_DIR;
+      },
+      write: () => {},
+    });
+    expect(code).toBe(0);
+    expect(seenRootDir).toBe(dir);
+  });
 });
 
 describe("oke vault", () => {

package/src/cli/start.ts

@@ -55,7 +55,18 @@ export async function runStart(options: StartOptions = {}): Promise<number> {
   try {
     const entry = await resolveStartEntry(cwd, options.entry);
     const port = String(options.port ?? Number(Bun.env.PORT ?? APP_PORT));
-    const env = { ...process.env, NODE_ENV: "production", PORT: port } as Record<string, string>;
+    const env = {
+      ...process.env,
+      NODE_ENV: "production",
+      PORT: port,
+      // Signal to boot() where to lazily extract effects from when a flow
+      // has no hand-declared `effects` — kernel/boot.ts's mintCapabilities()
+      // reads this (explicit opt-in only). docker/prod hard-fail (OKE1008)
+      // rather than silently open when neither this nor an explicit
+      // `manifest` resolves anything — this just gives that resolution a
+      // real chance to succeed instead of failing every time.
+      OKE_ROOT_DIR: process.env["OKE_ROOT_DIR"] ?? cwd,
+    } as Record<string, string>;
     write(`oke start: ${entry} (port ${port})\n`);
     if (options.runEntry) {
       await options.runEntry(entry, env);

package/src/compiler/effects-infer.ts

@@ -15,6 +15,7 @@ import type {
   TemplateRef,
   FlowRef,
 } from "../manifest/types.ts";
+import { sqlTableRef } from "../manifest/sql-resource.ts";
 
 /** Minimal ESTree-shaped nodes produced by oxc-parser. */
 export interface AstNode {
@@ -54,6 +55,7 @@ export interface InferBinding {
     | "template"
     | "flow"
     | "embed"
+    | "table"
     | "unknown";
   /** Resolved resource / name. */
   readonly ref: string;
@@ -103,9 +105,20 @@ const READ_METHODS = new Set([
   "findMany",
   "findFirst",
   "find",
+  "list",
 ]);
 
-const WRITE_METHODS = new Set(["insert", "set", "delete", "increment", "update", "upsert", "log"]);
+const WRITE_METHODS = new Set([
+  "insert",
+  "set",
+  "delete",
+  "increment",
+  "update",
+  "upsert",
+  "log",
+  "put",
+  "putImage",
+]);
 
 /** Methods whose first argument is a table / collection identifier. */
 const TABLE_ARG_METHODS = new Set([
@@ -203,7 +216,7 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       // Skip incomplete chains (`select` before `.from`, `insert` before table) —
       // the sibling call that carries the table arg records the real resource.
       const leaf = resolved.methods[resolved.methods.length - 1]!;
-      const hasTable = tableFromStoreChain(call) !== undefined;
+      const hasTable = tableFromStoreChain(call, options.bindings) !== undefined;
       if (!hasTable && (leaf === "select" || leaf === "insert" || leaf === "update")) {
         continue;
       }
@@ -352,11 +365,14 @@ export function storeResourceFromCall(
   const storeBinding = resolveBinding(storeArg, bindings);
   const facet = storeBinding?.facet ?? "sql";
 
-  const table = tableFromStoreChain(call);
+  const table = tableFromStoreChain(call, bindings);
 
   if (table) {
     return {
-      resource: `${facet}:${table}` as ResourceRef,
+      // sql:<table> is the shared naming convention with the kernel's
+      // runtime capability gate (see ../manifest/sql-resource.ts) — table
+      // args only ever occur on sql-facet methods in practice.
+      resource: (facet === "sql" ? sqlTableRef(table) : `${facet}:${table}`) as ResourceRef,
       methods: chain.methods,
     };
   }
@@ -382,11 +398,21 @@ export function storeResourceFromCall(
 }
 
 /**
- * Walk an `fx.store(…).a().b(table)` chain and return the table identifier.
+ * Walk an `fx.store(…).a().b(table)` chain and return the declared table
+ * name — resolved through a registered `table` binding (the real string
+ * passed to `store.schema.table(name, …)`) when the argument is one, so a
+ * JS binding named differently from its declared table (`const notesTable
+ * = store.schema.table("notes", …)`) still resolves to `"notes"`, matching
+ * what the kernel reads off the live table object at call time. Falls back
+ * to the raw identifier text otherwise.
  *
  * @param call - Any call in the chain
+ * @param bindings - Scope bindings
  */
-function tableFromStoreChain(call: CallExpression): string | undefined {
+function tableFromStoreChain(
+  call: CallExpression,
+  bindings: ReadonlyMap<string, InferBinding>,
+): string | undefined {
   let current: AstNode | undefined = call;
   while (current && current.type === "CallExpression") {
     const c = current as CallExpression;
@@ -394,8 +420,11 @@ function tableFromStoreChain(call: CallExpression): string | undefined {
     if (!link || link.rootMethod !== "store") break;
     const leaf = link.methods[link.methods.length - 1]!;
     if (TABLE_ARG_METHODS.has(leaf)) {
-      const table = identifierName(c.arguments[0]);
-      if (table) return table;
+      const id = identifierName(c.arguments[0]);
+      if (id) {
+        const binding = bindings.get(id);
+        return binding?.kind === "table" ? binding.ref : id;
+      }
     }
     const callee = c.callee;
     if (callee.type === "MemberExpression") {

package/src/compiler/extract.test.ts

@@ -344,3 +344,128 @@ export const remove = mounted.remove;
     expect(manifest.flows?.list?.breaking).toBe(true);
   });
 });
+
+describe("extractManifest — files-store write methods", () => {
+  test("fx.store(files).put(...) infers a write, unannotated", async () => {
+    const source = `
+import { on, flow, http, gate, store } from "okengine";
+
+export const files = store.files("uploads");
+
+export const attach = on(
+  http.post("/attach").gate(gate.public),
+  flow({
+    name: "notes.attach",
+    unit: "notes",
+    do: async (input, fx) => {
+      await fx.store(files).put("key", input.text);
+      return { ok: true };
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/attach.ts": source });
+
+    expect(manifest.flows?.["notes.attach"]?.effects?.writes).toEqual(["files:uploads"]);
+  });
+
+  test("fx.store(files).putImage(...) infers a write, unannotated", async () => {
+    const source = `
+import { on, flow, http, gate, store } from "okengine";
+
+export const files = store.files("uploads");
+
+export const attach = on(
+  http.post("/attach").gate(gate.public),
+  flow({
+    name: "notes.attachImage",
+    unit: "notes",
+    do: async (input, fx) => {
+      await fx.store(files).putImage("key", input.bytes);
+      return { ok: true };
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/attach.ts": source });
+
+    expect(manifest.flows?.["notes.attachImage"]?.effects?.writes).toEqual(["files:uploads"]);
+  });
+
+  test("fx.store(files).list(...) infers a read, unannotated", async () => {
+    const source = `
+import { on, flow, every, store } from "okengine";
+
+export const files = store.files("uploads");
+
+export const sweep = on(
+  every("1d"),
+  flow({
+    name: "notes.sweep",
+    unit: "notes",
+    do: async (_input, fx) => {
+      const keys = await fx.store(files).list();
+      return { count: keys.length };
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/sweep.ts": source });
+
+    expect(manifest.flows?.["notes.sweep"]?.effects?.reads).toEqual(["files:uploads"]);
+  });
+});
+
+describe("extractManifest — channel medium binder aliasing", () => {
+  test("mail.template(...) resolves through `const mail = channel.email(...)`", async () => {
+    const source = `
+import { on, flow, http, gate, channel } from "okengine";
+
+const mail = channel.email({ from: "Notes <notes@localhost>" });
+
+export const noteCreatedMail = mail.template("note-created", {
+  locales: ["en", "ar"],
+});
+
+export const onCreated = on(
+  http.post("/hook").gate(gate.public),
+  flow({
+    name: "notes.onCreated",
+    unit: "notes",
+    do: async (payload, fx) => {
+      await fx.send(noteCreatedMail, { to: "you@localhost", data: payload });
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/notes.ts": source });
+
+    expect(manifest.flows?.["notes.onCreated"]?.effects?.sends).toEqual(["note-created"]);
+    expect(manifest.channels?.["note-created"]?.medium).toBe("email");
+  });
+
+  test("sms medium binder alias carries its medium (not defaulted to email)", async () => {
+    const source = `
+import { on, flow, http, gate, channel } from "okengine";
+
+const otp = channel.sms({});
+
+export const otpTemplate = otp.template("otp-code", {});
+
+export const send = on(
+  http.post("/otp").gate(gate.public),
+  flow({
+    name: "notes.sendOtp",
+    unit: "notes",
+    do: async (payload, fx) => {
+      await fx.send(otpTemplate, { to: "+10000000000", data: payload });
+    },
+  }),
+);
+`;
+    const manifest = await extractFromSources({ "src/flows/otp.ts": source });
+
+    expect(manifest.flows?.["notes.sendOtp"]?.effects?.sends).toEqual(["otp-code"]);
+    expect(manifest.channels?.["otp-code"]?.medium).toBe("sms");
+  });
+});

package/src/compiler/extract.ts

@@ -14,6 +14,7 @@ import type {
   AiModel,
   AiPrompt,
   Channel,
+  ChannelMedium,
   Clock,
   DeclaredColumn,
   Effects,
@@ -94,6 +95,8 @@ interface ProjectScope {
     string,
     { storeName: string; storeRef: string; unit?: string; breaking?: boolean }
   >;
+  /** Local binding name → medium, for `const x = channel.email(…)` binders. */
+  channelMediumBindings: Map<string, ChannelMedium>;
 }
 
 /**
@@ -123,6 +126,7 @@ export async function extractManifest(options: ExtractManifestOptions = {}): Pro
     flows: {},
     flowExports: new Map(),
     resources: new Map(),
+    channelMediumBindings: new Map(),
   };
 
   const parsed = files.map((file) => {
@@ -329,7 +333,14 @@ function collectSchemaTable(call: CallExpression, program: AstNode, scope: Proje
   const entry = { name: tableName, columns };
   scope.schemaTables.set(tableName, entry);
   const bindingName = enclosingConstName(call, program);
-  if (bindingName) scope.schemaTables.set(bindingName, entry);
+  if (bindingName) {
+    scope.schemaTables.set(bindingName, entry);
+    // Declared table name, not the JS binding — resolved by
+    // tableFromStoreChain so `const notesTable = store.schema.table("notes",
+    // …)` still infers "sql:notes", matching what the kernel reads off the
+    // live table object (see ../manifest/sql-resource.ts).
+    scope.bindings.set(bindingName, { kind: "table", ref: tableName });
+  }
 }
 
 function attachSchemaOption(
@@ -584,6 +595,8 @@ function camelToSnakeKey(key: string): string {
     .toLowerCase();
 }
 
+const CHANNEL_MEDIUM_METHODS = new Set(["email", "sms", "whatsapp", "push"]);
+
 function visitDeclarationCall(call: CallExpression, program: AstNode, scope: ProjectScope): void {
   const callee = call.callee;
 
@@ -718,7 +731,17 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
       }
     }
 
-    if (obj === "channel" && prop === "template") {
+    // channel.email(…) / .sms(…) / .whatsapp(…) / .push(…) — medium binder,
+    // usually held in a local const and called later as `mail.template(…)`.
+    if (obj === "channel" && prop && CHANNEL_MEDIUM_METHODS.has(prop)) {
+      const bindingName = enclosingConstName(call, program);
+      if (bindingName) {
+        scope.channelMediumBindings.set(bindingName, prop as ChannelMedium);
+      }
+    }
+
+    const boundMedium = obj ? scope.channelMediumBindings.get(obj) : undefined;
+    if ((obj === "channel" && prop === "template") || (prop === "template" && boundMedium)) {
       const templateName = stringArg(call.arguments[0]);
       const opts = objectArg(call.arguments[1]);
       if (templateName) {
@@ -726,7 +749,9 @@ function visitDeclarationCall(call: CallExpression, program: AstNode, scope: Pro
         const locales = stringArrayProp(opts, "locales");
         const description = stringProp(opts, "description");
         scope.channels[templateName] = {
-          ...(medium ? { medium: medium as Channel["medium"] } : { medium: "email" }),
+          ...(medium
+            ? { medium: medium as Channel["medium"] }
+            : { medium: boundMedium ?? "email" }),
           ...(locales ? { locales } : {}),
           ...(description ? { description } : {}),
         };

package/src/elements/store/cache.test.ts

@@ -43,4 +43,32 @@ describe("tier-1 cache — exact per-resource invalidation (path b)", () => {
     expect(cache.invalidateFromEffects({ writes: ["sql:links"] }).keys).toEqual(keys);
     expect(cache.get(keys[0]!)).toBeUndefined();
   });
+
+  test("write to table A does not invalidate a cached read of table B in the same sql store", () => {
+    // Two tables under one `store.sql("app", …)` — the exact shape Direction
+    // B's per-table kernel resolution (fx.ts `gatedTable`) now produces:
+    // `sql:notes` / `sql:orders`, not the old coarse `sql:app` for both.
+    // This precision was already correct in cache.ts before Direction B —
+    // it simply never received per-table refs to prove it with. Confirmed
+    // here with the exact naming the kernel now emits.
+    const cache = createStoreCache();
+    const notesRead: Effects = { reads: ["sql:notes"] };
+    const keys = tier1KeysForReads(notesRead);
+
+    cache.set({
+      tier: 1,
+      key: keys[0]!,
+      value: [{ id: "n1" }],
+      resources: ["sql:notes"],
+      expiresAt: null,
+    });
+
+    // A write to "orders" — a different table, same store — must not touch it.
+    expect(cache.invalidateFromEffects({ writes: ["sql:orders"] }).keys).toEqual([]);
+    expect(cache.get(keys[0]!)).toBeDefined();
+
+    // A write to "notes" itself still invalidates.
+    expect(cache.invalidateFromEffects({ writes: ["sql:notes"] }).keys).toEqual(keys);
+    expect(cache.get(keys[0]!)).toBeUndefined();
+  });
 });

package/src/kernel/app.ts

@@ -162,6 +162,18 @@ export interface OkeOptions {
   readonly docker?: BootOptions["docker"];
   /** Optional `oke.config.ts` document consumed at boot. */
   readonly config?: BootOptions["config"];
+  /**
+   * Compiled Manifest for flows with no hand-declared `effects` — highest
+   * priority source for the boot-time capability stamp (see
+   * {@link BootOptions.manifest}).
+   */
+  readonly manifest?: BootOptions["manifest"];
+  /**
+   * Project root for a lazy, best-effort effects extraction when a flow has
+   * no hand-declared `effects` and no {@link manifest} was given (see
+   * {@link BootOptions.rootDir}).
+   */
+  readonly rootDir?: BootOptions["rootDir"];
   /** Pre-built element runtimes (skip construction at boot when present). */
   readonly elements?: BootOptions["elements"];
   /** Vault create options (chain / allowDevFallbacks / secrets). */
@@ -827,6 +839,8 @@ export function oke(options: OkeOptions): OkeApp {
       env: bootEnv,
       docker: overrides?.docker ?? options.docker,
       config: overrides?.config ?? options.config,
+      manifest: overrides?.manifest ?? options.manifest,
+      rootDir: overrides?.rootDir ?? options.rootDir,
       elements: overrides?.elements ?? options.elements,
       secrets: [...baseSecrets, ...pluginSecrets],
       vault: overrides?.vault ?? options.vault,

package/src/kernel/boot.ts

@@ -17,7 +17,10 @@
  * Element runtimes are loaded via `new URL("./boot-bind/"+name+".ts", …)` so
  * unused binders stay out of the `oke()` bundle (semantic tree-shaking).
  * Vault still loads whenever secrets are declared and lists every gap in one
- * failure; capability minting uses flow effect refs only — no element modules.
+ * failure; capability minting uses flow effect refs only — no element modules,
+ * except a lazy `extractManifest` import when a flow has no hand-declared
+ * `effects` and neither {@link BootOptions.manifest} nor
+ * {@link BootOptions.rootDir} / `OKE_ROOT_DIR` are set to derive one.
  *
  * The scheduler reads the effective state from the Store after reconciliation,
  * never the code directly (console §5).
@@ -38,8 +41,11 @@ import type {
 import type { JournalRuntime } from "./boot-bind/journal.ts";
 import type { CreateRunsRuntimeOptions, RunsRuntime } from "../runs/index.ts";
 import { createCapabilityToken, type CapabilityToken } from "./capability.ts";
+import { throwOke } from "./errors.ts";
 import type { AnyFlowDef } from "./flow.ts";
 import type { Binding } from "./on.ts";
+import type { Manifest } from "../manifest/types.ts";
+import { emitBootWarn } from "../runtime/boot-warn.ts";
 
 /** Pre-built or partially-built element runtimes. */
 export interface ElementRuntimes {
@@ -104,6 +110,21 @@ export interface BootOptions {
   readonly bindings?: readonly Binding[];
   /** Flows known to the app (for capability minting). */
   readonly flows?: readonly AnyFlowDef[];
+  /**
+   * Compiled Manifest to derive capability tokens from for flows with no
+   * hand-declared `effects` (highest priority — build tooling / bundler
+   * import, never a filesystem read the kernel performs itself).
+   */
+  readonly manifest?: Manifest;
+  /**
+   * Project root for a lazy, best-effort `extractManifest` when a flow has
+   * no hand-declared `effects` and no {@link manifest} was given. Explicit
+   * opt-in only — never defaults to `process.cwd()` — so the existing test
+   * suite (hundreds of boots against synthetic flows, not a real source
+   * tree) never pays extraction cost. Falls back to `OKE_ROOT_DIR` when
+   * unset (the CLI sets this for `oke dev` / `oke start`).
+   */
+  readonly rootDir?: string;
   /**
    * Dispatch a cron / every interval when the scheduler fires.
    *
@@ -457,8 +478,11 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
     }
   }
 
-  // 8. Caps — effect refs only; no element modules.
-  const capabilities = mintCapabilities(options.flows ?? []);
+  // 8. Caps — effect refs only; no element modules (unless a lazy extract is needed).
+  const capabilities = await mintCapabilities(options.flows ?? [], env, {
+    manifest: options.manifest,
+    rootDir: options.rootDir,
+  });
 
   return {
     vault,
@@ -491,16 +515,90 @@ export async function bootApplication(input: BootOptions = {}): Promise<BootResu
   };
 }
 
+/** Per-process guard so the "no effects" boot warning fires once, not per-flow. */
+let noEffectsWarned = false;
+
+/** Reset the once-per-process "no effects" warn latch (tests only). */
+export function resetNoEffectsWarnForTests(): void {
+  noEffectsWarned = false;
+}
+
+/**
+ * Best-effort AoT extraction from `rootDir` — mirrors the CLI's own lazy,
+ * defensive `extractManifest` use (`oke dev`'s `tryLoadProjectManifest`).
+ * Never throws: a broken or mid-edit source tree just means "no Manifest
+ * available," handled by the caller like any other missing Manifest.
+ *
+ * `new URL` (not a literal specifier) so `oxc-parser` / the whole compiler
+ * never enters the bundler graph for apps that never hit this path — same
+ * trick as {@link loadBind} for the element binders.
+ *
+ * @param rootDir - Project root to extract from
+ */
+async function tryAutoExtractManifest(rootDir: string): Promise<Manifest | undefined> {
+  try {
+    const url = new URL("../compiler/extract.ts", import.meta.url);
+    const { extractManifest } = (await import(url.href)) as typeof import("../compiler/extract.ts");
+    return await extractManifest({ rootDir });
+  } catch {
+    return undefined;
+  }
+}
+
 /**
- * Mint capability tokens from each flow's declared effects.
- * Tokens come from the Manifest / flow contract — never hand-passed sets.
+ * Mint capability tokens from each flow's declared effects, falling back to
+ * a Manifest-derived stamp when a flow declares no `effects` of its own —
+ * an explicit {@link BootOptions.manifest}, or a lazy AoT extract from
+ * {@link BootOptions.rootDir} / `OKE_ROOT_DIR`.
+ *
+ * When neither is available: `local` / `test` stay open (today's dev-loop
+ * behavior, unbroken) with a once-per-process `oke boot:` warning; `docker`
+ * / `prod` fail loud (`OKE1008`) — docker mirrors prod's posture, never a
+ * silent open door in a deploy-shaped environment.
  *
  * @param flows - Adopted flows
+ * @param env - Resolved {@link ConfigEnv}
+ * @param options - Manifest / rootDir sources for the fallback stamp
  */
-export function mintCapabilities(flows: readonly AnyFlowDef[]): Map<string, CapabilityToken> {
+export async function mintCapabilities(
+  flows: readonly AnyFlowDef[],
+  env: ConfigEnv = "local",
+  options: { readonly manifest?: Manifest; readonly rootDir?: string } = {},
+): Promise<Map<string, CapabilityToken>> {
   const map = new Map<string, CapabilityToken>();
+
+  let manifest = options.manifest;
+  const needsManifest = manifest === undefined && flows.some((f) => f.effects === undefined);
+  if (needsManifest) {
+    const rootDir = options.rootDir ?? process.env["OKE_ROOT_DIR"];
+    if (rootDir) manifest = await tryAutoExtractManifest(rootDir);
+  }
+
   for (const f of flows) {
-    map.set(f.name, createCapabilityToken(f.name, f.effects));
+    if (f.effects !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, f.effects));
+      continue;
+    }
+
+    const stamped = manifest?.flows?.[f.name]?.effects;
+    if (stamped !== undefined) {
+      map.set(f.name, createCapabilityToken(f.name, stamped));
+      continue;
+    }
+
+    if (env === "docker" || env === "prod") {
+      throwOke("NO_EFFECTS_DECLARED", { flow: f.name });
+    }
+    if (!noEffectsWarned) {
+      noEffectsWarned = true;
+      emitBootWarn(
+        `oke boot: flow "${f.name}" (and possibly others) has no declared effects and no ` +
+          "Manifest-derived effects — running with an OPEN capability token (every access " +
+          "allowed, ledgered but not gated). Run `oke build`, or boot with `manifest` / " +
+          "`rootDir`, before deploying — docker/prod refuse to boot this way.",
+      );
+    }
+    map.set(f.name, createCapabilityToken(f.name, undefined));
   }
   return map;
 }

package/src/kernel/effects-stamping.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Boot-level proof: compiled/inferred effects reaching a REAL running app's
+ * capability token — not an isolated compiler-only or kernel-only test.
+ *
+ * Before this file existed, `flow({...})` with no hand-declared `effects`
+ * always minted an OPEN capability token (every access allowed, no gate at
+ * all) in every environment, including `docker` / `prod` — `extractManifest`
+ * inference only ever fed the static `manifest.oke.json` artifact (Console,
+ * docs, publish), never the live boot path. Confirmed via real `oke()` boot
+ * + `app.fetch()`, not assumption.
+ *
+ * Also documents the sql:<table> (compiler inference) vs sql:<store-name>
+ * (kernel `gatedSqlHandle`) naming mismatch this stamping bridge surfaces:
+ * once inference actually reaches the runtime, a flow relying on it for a
+ * real `fx.store(db).insert(table)` write must not throw `UNDECLARED_WRITE`
+ * for touching the exact table it declared.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { gate } from "../elements/gate.ts";
+import { field, id, now, store } from "../elements/store.ts";
+import { oke } from "./app.ts";
+import { resetNoEffectsWarnForTests } from "./boot.ts";
+import { flow, resetFlowSeq } from "./flow.ts";
+import { on, resetBindings } from "./on.ts";
+import { createTestApp } from "../test/create-test-app.ts";
+import { http } from "./triggers.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+  resetNoEffectsWarnForTests();
+});
+
+const notes = store.schema.table("notes", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});
+
+const CreateIn = z.object({ id: z.string(), title: z.string() });
+const CreateOut = z.object({ ok: z.boolean() });
+
+function buildUnannotatedCreateFlow(db: ReturnType<typeof store.sql>) {
+  return on(
+    http.post("/notes").gate(gate.public),
+    flow({
+      name: "notes.create",
+      in: CreateIn,
+      out: CreateOut,
+      // Deliberately no `effects` — the "let the compiler infer it" case.
+      do: async (input, fx) => {
+        await fx.store(db).insert(notes).values({ id: input.id, title: input.title, createdAt: 1 });
+        return { ok: true };
+      },
+    }),
+  );
+}
+
+describe("boot-level: undeclared-effects flow, no manifest / rootDir", () => {
+  test("local / test: open token — real insert succeeds (documented dev-loop fallback)", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    // `on(...)` (inside buildUnannotatedCreateFlow) must run BEFORE `oke(...)`
+    // is constructed — oke() synchronously drains the global on() registry
+    // at construction time; a binding created only as .adopt()'s argument
+    // (after oke() already ran) never gets wired to a route.
+    const create = buildUnannotatedCreateFlow(db);
+    const app = oke({ name: "stamp-open", gate: { policies: [gate.public] } }).adopt({ create });
+    Object.assign(app.$options, { stores: [db] });
+    await createTestApp(app); // createTestApp always boots env: "test"
+
+    const res = await app.fetch(
+      new Request("http://localhost/notes", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: "x1", title: "hi" }),
+      }),
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("docker: hard fail at boot — OKE1008, never an open token in a deploy-shaped env", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    const create = buildUnannotatedCreateFlow(db);
+    const app = oke({ name: "stamp-docker", gate: { policies: [gate.public] } }).adopt({ create });
+
+    await expect(
+      app.boot({ env: "docker", stores: [db], unguardedHttp: "allow", startScheduler: false }),
+    ).rejects.toThrow(/OKE1008/);
+  });
+
+  test("prod: hard fail at boot — same posture as docker", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    const create = buildUnannotatedCreateFlow(db);
+    const app = oke({ name: "stamp-prod", gate: { policies: [gate.public] } }).adopt({ create });
+
+    await expect(
+      app.boot({ env: "prod", stores: [db], unguardedHttp: "allow", startScheduler: false }),
+    ).rejects.toThrow(/OKE1008/);
+  });
+});
+
+describe("boot-level: table-ref resolution stays backward compatible", () => {
+  test("older store-level effects (sql:<store>) still cover a schema-table op — every existing template's convention", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const db = store.sql("app", { schema: { notes } });
+    const create = on(
+      http.post("/notes").gate(gate.public),
+      flow({
+        name: "notes.create",
+        in: CreateIn,
+        out: CreateOut,
+        // The convention every template/test predates Direction B with —
+        // store-level, not table-level. Must keep working unchanged.
+        effects: { writes: ["sql:app"] },
+        do: async (input, fx) => {
+          await fx
+            .store(db)
+            .insert(notes)
+            .values({ id: input.id, title: input.title, createdAt: 1 });
+          return { ok: true };
+        },
+      }),
+    );
+    const app = oke({ name: "stamp-back-compat", gate: { policies: [gate.public] } }).adopt({
+      create,
+    });
+    Object.assign(app.$options, { stores: [db] });
+    await createTestApp(app);
+
+    const res = await app.fetch(
+      new Request("http://localhost/notes", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: "x1", title: "hi" }),
+      }),
+    );
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("boot-level: undeclared-effects flow, rootDir stamping from a real source tree", () => {
+  test("real fx.store(db).insert(table) write succeeds once inference is stamped onto the capability token", async () => {
+    resetBindings();
+    resetFlowSeq();
+    const dir = await mkdtemp(join(tmpdir(), "oke-stamp-"));
+    try {
+      await mkdir(join(dir, "flows", "notes"), { recursive: true });
+      // A real source file with NO manual `effects:` — extractManifest infers
+      // `writes: ["sql:notes"]` for this from the real `fx.store(db).insert`
+      // call, exactly like the kernel test flow above.
+      await writeFile(
+        join(dir, "flows", "notes", "index.ts"),
+        `
+import { on, flow, http, gate } from "okengine";
+// Unresolved bindings are fine — extraction is AST-only, never executed.
+// What matters is the literal shape: fx.store(db).insert(notes) so the
+// same table-name inference that produced "sql:notes" earlier fires here.
+const db = {} as any;
+const notes = {} as any;
+export const create = on(
+  http.post("/notes").gate(gate.public),
+  flow({
+    name: "notes.create",
+    do: async (input, fx) => {
+      await fx.store(db).insert(notes).values({ id: input.id, title: input.title, createdAt: 1 });
+      return { ok: true };
+    },
+  }),
+);
+`,
+      );
+
+      const db = store.sql("app", { schema: { notes } });
+      const create = buildUnannotatedCreateFlow(db);
+      const app = oke({ name: "stamp-rootdir", gate: { policies: [gate.public] } }).adopt({
+        create,
+      });
+      Object.assign(app.$options, { stores: [db] });
+      await createTestApp(app, { boot: { rootDir: dir } });
+
+      const res = await app.fetch(
+        new Request("http://localhost/notes", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ id: "x1", title: "hi" }),
+        }),
+      );
+      const body = (await res.json()) as { data: unknown; error: { message?: string } | null };
+      expect(res.status, body.error?.message ?? "").toBe(200);
+      expect(body.data).toEqual({ ok: true });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/kernel/errors.ts

@@ -142,6 +142,17 @@ export const OKE_ERRORS = {
     cause: 'Flow "{flow}" calls "{resource}" without declaring it.',
     fix: 'Add "{resource}" to this flow\'s effects.calls.',
   },
+  /**
+   * Flow has no declared `effects` and no Manifest-derived effects were
+   * available to stamp at boot (docker / prod — never a silent open token).
+   */
+  NO_EFFECTS_DECLARED: {
+    code: 1008,
+    cause: 'Flow "{flow}" has no declared effects and no Manifest to derive them from.',
+    fix:
+      "Add explicit `effects` to this flow, or boot with a Manifest (`oke build`) / " +
+      "`rootDir` so effects can be derived. docker/prod refuse an open capability token.",
+  },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.

package/src/kernel/fx.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Effects, ResourceRef } from "../manifest/types.ts";
+import { schemaTableName, sqlTableRef } from "../manifest/sql-resource.ts";
 import type {
   FilesStoreDecl,
   FilesStoreFxHandle,
@@ -852,6 +853,34 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         );
       }
     };
+    /**
+     * Gate a table-scoped SQL operation. Prefers the precise `sql:<table>`
+     * ref (matches what the compiler's AST inference derives from the same
+     * call site — {@link "../manifest/sql-resource.ts"}); falls back to the
+     * store-level ref when the table ref isn't declared — every flow that
+     * hand-declared the older `effects: { writes: ["sql:<store>"] }`
+     * convention (every existing template, `upsert-app.test.ts`, …) must
+     * keep working unchanged. Ledger / journal record whichever ref the
+     * capability check actually matched, not always the coarser one.
+     *
+     * @param kind - Effect kind
+     * @param table - Table argument passed to a `SqlStoreHandle` method
+     * @param body - Work to run under the gate
+     */
+    const gatedTable = <T>(
+      kind: Parameters<CapabilityToken["assert"]>[0],
+      table: unknown,
+      body: () => T | Promise<T>,
+    ): Promise<T> => {
+      const name = schemaTableName(table);
+      if (name !== undefined) {
+        const perTable = sqlTableRef(name);
+        if (perTable !== ref && capability.allows(kind, perTable)) {
+          return gated(kind, perTable, body);
+        }
+      }
+      return gated(kind, ref, body);
+    };
 
     return {
       ref,
@@ -870,7 +899,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
               limit?: number;
               offset?: number;
             }): Promise<SqlRow[]> =>
-              gated("read", ref, async () => {
+              gatedTable("read", table, async () => {
                 const h = await ensure();
                 const from = h.select(columns).from(table);
                 const filtered = plan.where === undefined ? from : from.where(plan.where);
@@ -920,14 +949,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         return {
           values(row) {
             const runExecute = () =>
-              gated("write", ref, async () => {
+              gatedTable("write", table, async () => {
                 refuseDryRunWrite();
                 const h = await ensure();
                 await h.insert(table).values(row).execute();
               });
             return {
               returning() {
-                return gated("write", ref, async () => {
+                return gatedTable("write", table, async () => {
                   refuseDryRunWrite();
                   const h = await ensure();
                   return h.insert(table).values(row).returning();
@@ -946,7 +975,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
           set(row) {
             return {
               where(where) {
-                return gated("write", ref, async () => {
+                return gatedTable("write", table, async () => {
                   refuseDryRunWrite();
                   const h = await ensure();
                   return h.update(table).set(row).where(where);
@@ -957,14 +986,14 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         };
       },
       findById(table, id) {
-        return gated("read", ref, async () => {
+        return gatedTable("read", table, async () => {
           const h = await ensure();
           return h.findById(table, id);
         });
       },
       delete(table: Parameters<SqlStoreHandle["delete"]>[0], id?: string) {
         if (id !== undefined) {
-          return gated("write", ref, async () => {
+          return gatedTable("write", table, async () => {
             refuseDryRunWrite();
             const h = await ensure();
             return h.delete(table, id);
@@ -972,7 +1001,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         }
         return {
           where(where: unknown) {
-            return gated("write", ref, async () => {
+            return gatedTable("write", table, async () => {
               refuseDryRunWrite();
               const h = await ensure();
               return h.delete(table).where(where);
@@ -981,20 +1010,20 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         };
       },
       exists(table, idOrWhere) {
-        return gated("read", ref, async () => {
+        return gatedTable("read", table, async () => {
           const h = await ensure();
           return h.exists(table, idOrWhere);
         });
       },
       upsert(table, matchOn, values, upsertOptions) {
-        return gated("write", ref, async () => {
+        return gatedTable("write", table, async () => {
           refuseDryRunWrite();
           const h = await ensure();
           return h.upsert(table, matchOn, values, upsertOptions);
         });
       },
       increment(table, id, column, by) {
-        return gated("write", ref, async () => {
+        return gatedTable("write", table, async () => {
           refuseDryRunWrite();
           const h = await ensure();
           return h.increment(table, id, column, by);
@@ -1007,19 +1036,19 @@ export function createFxContext(options: CreateFxOptions): FxContext {
         });
       },
       count(table, where) {
-        return gated("read", ref, async () => {
+        return gatedTable("read", table, async () => {
           const h = await ensure();
           return h.count(table, where);
         });
       },
       page(table, pageOptions) {
-        return gated("read", ref, async () => {
+        return gatedTable("read", table, async () => {
           const h = await ensure();
           return h.page(table, pageOptions);
         });
       },
       ensureTable(table) {
-        return gated("write", ref, async () => {
+        return gatedTable("write", table, async () => {
           refuseDryRunWrite();
           const h = await ensure();
           return h.ensureTable(table);

package/src/manifest/sql-resource.ts

@@ -0,0 +1,41 @@
+/**
+ * SQL resource-ref naming — the one place both the compiler's AST-based
+ * effect inference ({@link "../compiler/effects-infer.ts"}) and the
+ * kernel's capability gate ({@link "../kernel/fx.ts"} `gatedSqlHandle`)
+ * compute a per-table `sql:<table>` ref, so the two cannot silently
+ * drift apart again.
+ *
+ * Table-name *resolution* differs by nature — the compiler reads a static
+ * AST identifier (or, better, the declared name behind a
+ * `store.schema.table(name, …)` binding); the kernel reads the declared
+ * name straight off the live table object at call time. Only the
+ * naming/formatting step is shared here; that is the part a second,
+ * independently-written implementation could get wrong.
+ */
+
+import type { ResourceRef } from "./types.ts";
+
+/**
+ * The declared name a real `store.schema.table(name, columns)` object
+ * carries at runtime — the same string that was the first argument to
+ * `store.schema.table(...)` in source, regardless of what the JS binding
+ * is called. `undefined` for anything else (raw ORM tables, plain
+ * objects, missing/optional table arguments).
+ *
+ * @param value - Value passed where a table argument is expected
+ */
+export function schemaTableName(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const v = value as { kind?: unknown; name?: unknown };
+  if (v.kind !== "schema-table") return undefined;
+  return typeof v.name === "string" ? v.name : undefined;
+}
+
+/**
+ * `sql:<table>` resource ref for a declared table name.
+ *
+ * @param table - Declared table name
+ */
+export function sqlTableRef(table: string): ResourceRef {
+  return `sql:${table}` as ResourceRef;
+}