okengine 0.17.2 → 0.18.3

package/src/elements/store.test.ts

@@ -70,7 +70,9 @@ describe("store facets", () => {
   });
 
   test("id and now helpers", () => {
-    expect(id()).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+    const value = id();
+    expect(value).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(value.length).toBe(21);
     expect(now()).toBeGreaterThan(0);
   });
 });

package/src/elements/store.ts

@@ -93,7 +93,15 @@ export type { CacheTier, CacheEntry, InvalidationEvent, StoreCache } from "./sto
 export { isReadOnlyStoreFlow, sqlRoleForEffects, resolveSqlTarget } from "./store/replica.ts";
 export type { SqlBindingConfig } from "./store/replica.ts";
 
-export { defineTable, resolveTableName, classificationsFromTable, id, now } from "./store/table.ts";
+export {
+  defineTable,
+  resolveTableName,
+  classificationsFromTable,
+  id,
+  now,
+  nowIso,
+  nowDate,
+} from "./store/table.ts";
 export type { ColumnDef, TableHandle } from "./store/table.ts";
 
 export { resource } from "./store/resource.ts";
@@ -109,6 +117,9 @@ export type {
   ResolvedListConfig,
 } from "./store/resource.ts";
 
+export { liveQuery } from "./store/live-query.ts";
+export type { ListOptions } from "./store/list-query.ts";
+
 export {
   defineSeed,
   normalizeSeedFns,

package/src/elements/vault/chaos-child.ts

@@ -18,12 +18,15 @@
  *   audit-tamper      — raw SQL UPDATE on oke_vault_audit (bypass adapter)
  *   rotate-race       — call rotateMaster once; write ok/error JSON
  *   read-loop         — get(path) until stopPath appears or duration elapses
+ *   bench-read-loop   — read-loop variant that records per-read durationMs
+ *                       (G7 rotate-under-read bench)
  *   set-race          — write `count` distinct paths; append to donePath
  */
 
 import { connectPglite } from "../../drivers/pglite.ts";
 import { connectPostgres } from "../../drivers/postgres.ts";
 import type { SqlConnection } from "../../drivers/types.ts";
+import { appendFile } from "node:fs/promises";
 import {
   createBuiltinVaultAdapter,
   sqlConnectionAsExec,
@@ -56,7 +59,9 @@ interface RotateState {
  */
 async function openSql(sqlUrl: string): Promise<SqlConnection> {
   if (/^postgres(ql)?:\/\//.test(sqlUrl)) {
-    return connectPostgres({ url: sqlUrl });
+    // Dedicated client: rotation / manual-BEGIN workloads fail on a shared
+    // pooled client (ERR_POSTGRES_UNSAFE_TRANSACTION).
+    return connectPostgres({ url: sqlUrl, pool: { max: 1 } });
   }
   return connectPglite({ url: sqlUrl });
 }
@@ -390,6 +395,74 @@ if (mode === "read-loop") {
   }
 }
 
+if (mode === "bench-read-loop") {
+  const sqlUrl = process.argv[3];
+  const masterKey = process.argv[4];
+  const path = process.argv[5];
+  const readsPath = process.argv[6];
+  const stopPath = process.argv[7];
+  const durationMs = Number(process.argv[8] ?? "15000");
+  if (!sqlUrl || !masterKey || !path || !readsPath || !stopPath) {
+    console.error(
+      "usage: bench-read-loop <sqlUrl> <masterKey> <path> <readsPath> <stopPath> [durationMs]",
+    );
+    process.exit(2);
+  }
+
+  const conn = await openSql(sqlUrl);
+  try {
+    const adapter = createBuiltinVaultAdapter({ db: sqlConnectionAsExec(conn) });
+    await adapter.unseal(masterKey);
+    // Append-only JSONL without re-reading the file each iteration.
+    const lines: string[] = [];
+    let flushTimer: ReturnType<typeof setTimeout> | undefined;
+    const flush = async () => {
+      if (lines.length === 0) return;
+      const batch = lines.splice(0).join("");
+      await appendFile(readsPath, batch);
+    };
+    const scheduleFlush = () => {
+      if (flushTimer) return;
+      flushTimer = setTimeout(() => {
+        flushTimer = undefined;
+        void flush();
+      }, 50);
+    };
+
+    const deadline = Date.now() + durationMs;
+    while (Date.now() < deadline) {
+      if (await Bun.file(stopPath).exists()) break;
+      const s = performance.now();
+      try {
+        const secret = await adapter.get(path);
+        const dur = performance.now() - s;
+        lines.push(
+          `${JSON.stringify({
+            ok: true,
+            durMs: Number(dur.toFixed(3)),
+            value: secret?.value ?? null,
+            kekVersion: secret?.kekVersion ?? null,
+            at: Date.now(),
+          })}\n`,
+        );
+      } catch (error) {
+        const dur = performance.now() - s;
+        const message = error instanceof Error ? error.message : String(error);
+        lines.push(
+          `${JSON.stringify({ ok: false, durMs: Number(dur.toFixed(3)), error: message, at: Date.now() })}\n`,
+        );
+      }
+      scheduleFlush();
+      await Bun.sleep(2);
+    }
+    if (flushTimer) clearTimeout(flushTimer);
+    await flush();
+    process.exit(0);
+  } finally {
+    await conn.close();
+  }
+}
+
 if (mode === "set-race") {
   const sqlUrl = process.argv[3];
   const masterKey = process.argv[4];

package/src/elements/vault/chaos.test.ts

@@ -251,7 +251,7 @@ describe.skipIf(!LIVE_URL)("chaos — 2b. concurrent rotateMaster (multi-process
     const dir = await mkdtemp(join(tmpdir(), "oke-vault-chaos-rotate-race-"));
     const resultPath = join(dir, "results.jsonl");
 
-    const schema = await connectPostgres({ url });
+    const schema = await connectPostgres({ url, pool: { max: 1 } });
     try {
       await resetVaultTables(schema);
       const adapter = createBuiltinVaultAdapter({ db: sqlConnectionAsExec(schema) });
@@ -345,7 +345,9 @@ describe.skipIf(!LIVE_URL)("chaos — 3b. read during rotation (second process,
     const stopPath = join(dir, "stop");
     const path = "chaos/cross-read";
 
-    const conn = await connectPostgres({ url });
+    // Dedicated client: rotateMaster holds manual BEGIN state across
+    // statements — the shared pool raises ERR_POSTGRES_UNSAFE_TRANSACTION.
+    const conn = await connectPostgres({ url, pool: { max: 1 } });
     try {
       await resetVaultTables(conn);
       const adapter = createBuiltinVaultAdapter({

package/src/elements/vault/storage.ts

@@ -153,9 +153,11 @@ CREATE TABLE IF NOT EXISTS oke_vault_status (
 
 /**
  * Claim the rotate-master lease — same predicate as Clock/Signal
- * (`FOR UPDATE SKIP LOCKED` + lease-expiry reclaim).
+ * (lease-expiry reclaim). Plain `FOR UPDATE` (no `SKIP LOCKED`): a row busy
+ * with a concurrent audit append must briefly wait, not be misread as
+ * "lease held by another instance".
  */
-export const CLAIM_ROTATE_LEASE_SQL: string = `SELECT id FROM oke_vault_status WHERE id = 1 AND ((rotate_locked_by IS NULL) OR (rotate_locked_by = $1) OR (rotate_lease_expires_at IS NULL) OR (rotate_lease_expires_at <= $2)) FOR UPDATE SKIP LOCKED`;
+export const CLAIM_ROTATE_LEASE_SQL: string = `SELECT id FROM oke_vault_status WHERE id = 1 AND ((rotate_locked_by IS NULL) OR (rotate_locked_by = $1) OR (rotate_lease_expires_at IS NULL) OR (rotate_lease_expires_at <= $2)) FOR UPDATE`;
 
 /** Default rotate-master lease TTL (ms) — lazy reclaim, no sweeper. */
 export const DEFAULT_ROTATE_LEASE_MS: number = 30_000;

package/src/index.ts

@@ -24,7 +24,7 @@ export {
 } from "./kernel/app.ts";
 export { on, type Binding } from "./kernel/on.ts";
 export { flow, isFlow, type FlowDef } from "./kernel/flow.ts";
-export { http, every, internal, table } from "./kernel/triggers.ts";
+export { http, every, internal, table, mcp } from "./kernel/triggers.ts";
 export { registerFlowUnits } from "./kernel/flow-units.ts";
 export { stampFlowName, stampHttpPath } from "./kernel/stamp-http.ts";
 export { fail, type FlowFailure, type FlowErrorValue } from "./kernel/errors.ts";
@@ -51,6 +51,8 @@ export {
   classify,
   id,
   now,
+  nowIso,
+  nowDate,
   defineTable,
   field,
   defineSeed,
@@ -59,6 +61,7 @@ export {
   resolveSeedIdentity,
   seedPromptMessage,
   createStoreRuntime,
+  liveQuery,
   type StoreDecl,
   type StoreRuntime,
   type SqlStoreHandle,

package/src/kernel/app-auth.ts

@@ -80,6 +80,7 @@ export function wireGateAuth(options: WireGateAuthOptions): WiredGateAuth {
   setActiveGateAuthContext({
     secret: authBinding.secret,
     sessions: authBinding.sessions,
+    identities: auth.identities,
     now: authBinding.now,
     passwordPolicy: auth.passwordPolicy,
     password: auth.password,

package/src/kernel/app.ts

@@ -26,6 +26,7 @@ import type { BootOptions, BootResult, ElementRuntimes } from "./boot.ts";
 import type { CapabilityToken } from "./capability.ts";
 import type { AppAuthBinding } from "./auth-resolve.ts";
 import type { ApiKeyStore } from "../auth/api-keys.ts";
+import type { IdentityStore } from "../auth/identity.ts";
 import type { AuthHttpMaterialization } from "../auth/bindings.ts";
 import type { WiredGateAuth } from "./app-auth.ts";
 import {
@@ -42,6 +43,8 @@ import { runWithLocale } from "../i18n/locale-context.ts";
 import { isFlow, type AnyFlowDef } from "./flow.ts";
 import { failureFromUnknown, runCompensationPhase } from "./compensate.ts";
 import { withAbortSignal } from "./abort-scope.ts";
+import { withCdcMutationId } from "../elements/store/sql-session.ts";
+import { MUTATION_ID_HEADER } from "./realtime-bind.ts";
 import { fxRetry } from "./concurrency.ts";
 import type {
   CreateFxOptions,
@@ -125,6 +128,7 @@ import {
   type SmartRouter,
 } from "./router.ts";
 import { isPendingHttpPath } from "./http-path-pending.ts";
+import { drainPendingResourceLiveMounts } from "./resource-live.ts";
 import type {
   CdcTrigger,
   EveryTrigger,
@@ -263,6 +267,16 @@ export interface OkeOptions {
   readonly clocks?: BootOptions["clocks"];
   /** Store facet declarations to register. */
   readonly stores?: BootOptions["stores"];
+  /**
+   * Store-wide behavior options. `{ live: true }` flips NEW
+   * `store.schema.table()` declarations to live-by-default (an automatic
+   * CDC + RLS-per-event live stream, same as `.live(table)` /
+   * `liveQuery()`) unless a table explicitly opts out with
+   * `store.schema.live(false)`. Default `false` — today's explicit-only
+   * behavior, zero change to existing apps. Declaration ergonomics only;
+   * never the runtime cost model.
+   */
+  readonly store?: { readonly live?: boolean };
   /** Channel runtime options. */
   readonly channel?: BootOptions["channel"];
   /** AI runtime options. */
@@ -399,6 +413,8 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
   readonly authBinding: AppAuthBinding | undefined;
   /** Shared API key store when `gate.auth` is enabled. */
   readonly apiKeys: ApiKeyStore | undefined;
+  /** Shared identity/credential store when `gate.auth` is enabled. */
+  readonly identities: IdentityStore | undefined;
   /**
    * Attach a plugin app-wide. Scope is the attachment point.
    * Types accumulate — decorations are visible on downstream handlers.
@@ -546,6 +562,14 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
    * @param input - Input
    */
   call(ref: NamedRef | AnyFlowDef, input?: unknown): Promise<unknown>;
+  /**
+   * Resolve a user-plane MCP tool exposure by its declared tool name.
+   * Returns the bound flow when {@link on}`(`{@link mcp.tool}`(`"name"`).gate(...)`)
+   * registered it; `undefined` when absent or ungated (not indexed).
+   *
+   * @param name - Tool name from `mcp.tool("…")`
+   */
+  resolveMcpTool(name: string): AnyFlowDef | undefined;
   /** All adopted bindings. */
   readonly bindings: readonly Binding[];
   /**
@@ -692,6 +716,35 @@ function registerHttpRoute(
   compiled.set(binding, compileHttpBinding(binding, aot));
 }
 
+/**
+ * Register one MCP tool binding: unique tool name, indexed for dispatch lookup.
+ *
+ * Only gated exposures are indexed — bare `mcp.tool(name)` bindings remain
+ * unlisted (deny-by-default) and are rejected at boot by gate posture audit.
+ *
+ * @param binding - MCP tool binding
+ * @param seenMcpTools - Tool names already registered
+ * @param mcpToolsByName - Tool name → binding index for dispatch
+ */
+function registerMcpTool(
+  binding: Binding,
+  seenMcpTools: Set<string>,
+  mcpToolsByName: Map<string, Binding>,
+): void {
+  const trigger = binding.trigger;
+  if (trigger.kind !== "mcp") return;
+  if (seenMcpTools.has(trigger.name)) {
+    throwOke("MCP_TOOL_DUPLICATE", {
+      tool: trigger.name,
+      flow: binding.flow.name || "(unnamed)",
+    });
+  }
+  seenMcpTools.add(trigger.name);
+  if (trigger.gates.length > 0) {
+    mcpToolsByName.set(trigger.name, binding);
+  }
+}
+
 /**
  * Fold `generated.ts` units into `$routes` and `flowsByName`.
  *
@@ -832,6 +885,7 @@ export function oke(options: OkeOptions): OkeApp {
   const $options: OkeOptions = {
     ...options,
     ...(effectiveAi !== undefined ? { ai: effectiveAi } : {}),
+    ...(effectiveChannel !== undefined ? { channel: effectiveChannel } : {}),
     ...(effectiveStores.length > 0 ? { stores: effectiveStores } : {}),
     ...(effectiveSecrets.length > 0 ? { secrets: effectiveSecrets } : {}),
     ...(effectiveSignals.length > 0 ? { signals: effectiveSignals } : {}),
@@ -873,11 +927,16 @@ export function oke(options: OkeOptions): OkeApp {
   const smart = createRouter<Binding>(options.router ?? "default");
   const seenHttpRoutes = new Set<string>();
   const seenLiveExposures = new Map<string, string>();
+  const seenMcpTools = new Set<string>();
+  const mcpToolsByName = new Map<string, Binding>();
   for (const b of adopted) {
     if (b.trigger.kind === "http") {
       assertHttpBindingReady(b);
       registerHttpRoute(b, seenHttpRoutes, seenLiveExposures, smart, compiled, aot);
     }
+    if (b.trigger.kind === "mcp") {
+      registerMcpTool(b, seenMcpTools, mcpToolsByName);
+    }
   }
   // Defer SmartRouter selection until first match so `.plug()` can still
   // contribute auth-method Bindings before traffic (plan Phase 2).
@@ -890,8 +949,18 @@ export function oke(options: OkeOptions): OkeApp {
       assertHttpBindingReady(b);
       registerHttpRoute(b, seenHttpRoutes, seenLiveExposures, smart, compiled, aot);
     }
+    if (b.trigger.kind === "mcp") {
+      registerMcpTool(b, seenMcpTools, mcpToolsByName);
+    }
   }
 
+  // Project-wide `store.live` default — drain deferred resource live mounts
+  // now that the flag is known. Off flag: pending state is discarded and the
+  // behavior is 100% today's explicit-only. On flag: every pending resource
+  // whose table did not opt out with `store.schema.live(false)` adopts its
+  // `GET <path>/live` SSE binding through the normal route path.
+  drainPendingResourceLiveMounts(options.store?.live === true, adoptBinding);
+
   // Phase 1a: mirror tokens into Set-Cookie when gate.auth.cookies.enabled.
   if (gateConfig.auth?.cookies.enabled) {
     const cookieCfg = gateConfig.auth.cookies;
@@ -1260,6 +1329,24 @@ export function oke(options: OkeOptions): OkeApp {
       const { bindHostApiKeySqlFromStore } = await import("../auth/api-key-sql.ts");
       await bindHostApiKeySqlFromStore(result.store, gateConfig.auth.apiKeyStore);
     }
+    if (gateConfig.auth?.identities && result.store) {
+      const { bindHostIdentitySqlFromStore } = await import("../auth/identity-sql.ts");
+      await bindHostIdentitySqlFromStore(result.store, gateConfig.auth.identities);
+    }
+    // Realtime bridge — CDC sink + LiveQuery runtime + outbox poller when a
+    // Postgres-capable primary SQL connection exists. No-op otherwise.
+    if (result.store) {
+      const { bindRealtimeBridge } = await import("./realtime-bind.ts");
+      const primaryConn = await result.store.primarySql();
+      if (primaryConn) {
+        bindRealtimeBridge(primaryConn, (tableName, payload) =>
+          app.dispatchCdc(tableName, {
+            before: (payload.before ?? null) as Record<string, unknown> | null,
+            after: (payload.after ?? null) as Record<string, unknown> | null,
+          }),
+        );
+      }
+    }
     // otp() provider / app mode capability — fail loud at boot, never silent downgrade.
     if (result.channel) {
       const { assertOtpPluginCapability } = await import("../auth/otp-capability.ts");
@@ -1360,8 +1447,24 @@ export function oke(options: OkeOptions): OkeApp {
     );
 
     return runWithLocale({ locale: resolvedLocale, defaultLocale }, () => {
-      const run = () =>
-        executeInLocale({
+      const run = async (): Promise<ExecuteResult> => {
+        // Ambient mutation id — the client's `X-Oke-Mutation-Id` header rides
+        // onto every CDC event this write produces so optimistic clients can
+        // dedupe their own writes (Realtime correctness contract).
+        const mutationId = extras?.request?.headers.get(MUTATION_ID_HEADER)?.trim();
+        if (mutationId !== undefined && mutationId.length > 0) {
+          return withCdcMutationId(mutationId, () =>
+            executeInLocale({
+              flowDef,
+              input,
+              trigger,
+              extras,
+              resolvedLocale,
+              defaultLocale,
+            }),
+          );
+        }
+        return executeInLocale({
           flowDef,
           input,
           trigger,
@@ -1369,6 +1472,7 @@ export function oke(options: OkeOptions): OkeApp {
           resolvedLocale,
           defaultLocale,
         });
+      };
       const abort = extras?.request?.signal;
       return abort ? withAbortSignal(abort, run) : run();
     });
@@ -1901,6 +2005,11 @@ export function oke(options: OkeOptions): OkeApp {
     async stop() {
       if (!bootResult) return;
       bootResult.stopScheduler();
+      // Realtime bridge down before connections close.
+      {
+        const { unbindRealtimeBridge } = await import("./realtime-bind.ts");
+        unbindRealtimeBridge();
+      }
       // Proactive lease release so survivors need not wait for TTL reclaim.
       await releaseInstanceLeases({
         bootResult: {
@@ -1919,6 +2028,8 @@ export function oke(options: OkeOptions): OkeApp {
       return authBinding;
     },
     apiKeys: gateConfig.auth?.apiKeyStore,
+    /** Shared identity store when `gate.auth` is enabled. */
+    identities: gateConfig.auth?.identities,
     async resumeDurable(now) {
       const t = now ?? bootResult?.clock?.now() ?? options.fx?.now?.() ?? Date.now();
       const { store, instanceId, leaseMs } = activeJournal();
@@ -2227,6 +2338,9 @@ export function oke(options: OkeOptions): OkeApp {
       if (result.failure) return result.failure;
       return result.output;
     },
+    resolveMcpTool(name) {
+      return mcpToolsByName.get(name)?.flow;
+    },
     compiledFor(binding) {
       return compiled.get(binding);
     },

package/src/kernel/auth-sharing.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Shared identity store + locked account-linking rules across Gate auth method
+ * plugins:
+ *
+ * (b) two different auth methods (e.g. username sign-up then magic-link with
+ *     the same email) do NOT silently resolve to the same user without an
+ *     authenticated linking action — `email_in_use` is refused on the second
+ *     credential rather than auto-linked by email match.
+ * (c) linking a new credential while genuinely authenticated as an existing
+ *     user correctly attaches to that user's real row (passkey precedent,
+ *     now generalized and enforced for all methods).
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { linkOrProvision, type IdentityStore } from "../auth/identity.ts";
+import { oke } from "./app.ts";
+import { resetFlowSeq } from "./flow.ts";
+import { resetBindings } from "./on.ts";
+import { magicLink } from "../plugins/magic-link.ts";
+import { username } from "../plugins/username.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+const SECRET = "test-secret-at-least-16";
+
+function jsonPost(path: string, body: unknown, headers: Record<string, string> = {}): Request {
+  return new Request(`http://localhost${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(body),
+  });
+}
+
+function authApp() {
+  return oke({
+    name: `link-${crypto.randomUUID()}`,
+    env: "test",
+    registry: "ignore",
+    gate: {
+      auth: {
+        secret: SECRET,
+        emailAndPassword: { enabled: true },
+      },
+    },
+  })
+    .plug(username())
+    .plug(magicLink({ exposeDevToken: true }));
+}
+
+describe("shared identity store — method plugins share one store", () => {
+  test("username, magic-link, and gate.auth resolve against the app's single store", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+    const identities = app.identities as IdentityStore | undefined;
+    expect(identities).toBeDefined();
+
+    const signUp = await app.fetch(
+      jsonPost("/auth/sign-up/username", {
+        username: "shared_store_user",
+        password: "CorrectHorse1!",
+      }),
+    );
+    expect(signUp.status).toBe(200);
+    const created = (await signUp.json()) as { data: { userId: string } };
+
+    // The identity store now holds the username credential account.
+    const usernameAccount = [...identities!.accounts.values()].find(
+      (a) => a.provider === "username",
+    );
+    expect(usernameAccount?.userId).toBe(created.data.userId);
+
+    // A magic-link sign-in for the same email must NOT silently adopt the
+    // username principal — it provisions its own user (or is refused).
+    const req = await app.fetch(
+      jsonPost("/auth/magic-link/request", { email: "shared_store_user@example.com" }),
+    );
+    const devToken = ((await req.json()) as { data: { devToken: string } }).data.devToken;
+    const verify = await app.fetch(jsonPost("/auth/magic-link/verify", { token: devToken }));
+    const magic = (await verify.json()) as { data: { userId: string } };
+    expect(magic.data.userId).not.toBe(created.data.userId);
+
+    await app.stop();
+  });
+});
+
+describe("locked account-linking rule (never email-match auto-link)", () => {
+  test("a second unauthenticated credential for an email owned by another user is refused (email_in_use)", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+    const identities = app.identities as IdentityStore;
+
+    // Provision a magic-link user with an email.
+    const first = await linkOrProvision(identities, {
+      provider: "magic-link",
+      providerAccountId: "linkme@example.com",
+      email: "linkme@example.com",
+      emailVerified: true,
+      now: () => 3_000_000,
+    });
+    expect(first.created).toBe(true);
+
+    // A new unauthenticated credential claiming the same email must be refused,
+    // NOT auto-linked to the magic-link user by email match.
+    let refused: string | undefined;
+    try {
+      await linkOrProvision(identities, {
+        provider: "otp",
+        providerAccountId: "linkme@example.com",
+        email: "linkme@example.com",
+        now: () => 3_000_100,
+      });
+    } catch (err) {
+      refused = err instanceof Error && "code" in err ? (err as { code: string }).code : undefined;
+    }
+    expect(refused).toBe("email_in_use");
+
+    await app.stop();
+  });
+
+  test("username sign-up then magic-link with the same email do NOT resolve to the same user (real HTTP)", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+
+    const signUp = await app.fetch(
+      jsonPost("/auth/sign-up/username", {
+        username: "dual_identity",
+        password: "CorrectHorse1!",
+      }),
+    );
+    expect(signUp.status).toBe(200);
+    const created = (await signUp.json()) as { data: { userId: string } };
+
+    // magic-link with the same email as an identifier: must NOT silently resolve
+    // to the username user.
+    const req = await app.fetch(
+      jsonPost("/auth/magic-link/request", { email: "dual@example.com" }),
+    );
+    const devToken = ((await req.json()) as { data: { devToken: string } }).data.devToken;
+    const verify = await app.fetch(jsonPost("/auth/magic-link/verify", { token: devToken }));
+    const magic = (await verify.json()) as { data: { userId: string } };
+    expect(magic.data.userId).not.toBe(created.data.userId);
+
+    // And the username user resolves via sign-in to the SAME id as before.
+    const signIn = await app.fetch(
+      jsonPost("/auth/sign-in/username", {
+        username: "dual_identity",
+        password: "CorrectHorse1!",
+      }),
+    );
+    const session = (await signIn.json()) as { data: { userId: string } };
+    expect(session.data.userId).toBe(created.data.userId);
+
+    await app.stop();
+  });
+
+  test("authenticated linking attaches a second credential to the same user row", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+    const identities = app.identities as IdentityStore;
+
+    const signUp = await app.fetch(
+      jsonPost("/auth/sign-up/username", {
+        username: "linked_user",
+        password: "CorrectHorse1!",
+      }),
+    );
+    expect(signUp.status).toBe(200);
+    const created = (await signUp.json()) as { data: { accessToken: string; userId: string } };
+
+    // Authenticated linking: attach an OTP credential to the same user while
+    // holding the user's session (matching the passkey precedent).
+    const linked = await linkOrProvision(identities, {
+      provider: "otp",
+      providerAccountId: "linked_phone",
+      currentUserId: created.data.userId,
+      now: () => 4_000_000,
+    });
+    expect(linked.user.id).toBe(created.data.userId);
+    expect(linked.account.userId).toBe(created.data.userId);
+    expect(linked.created).toBe(true);
+
+    // Signing in via the new credential resolves to the SAME user.
+    const res = await linkOrProvision(identities, {
+      provider: "otp",
+      providerAccountId: "linked_phone",
+      now: () => 4_000_001,
+    });
+    expect(res.user.id).toBe(created.data.userId);
+    expect(res.created).toBe(false);
+
+    await app.stop();
+  });
+});

package/src/kernel/boot.test.ts

@@ -116,9 +116,9 @@ describe("boot — lazy element needs", () => {
         if (raw.byteLength === 0) continue;
         total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
       }
-      // Rebased after host API-key persist + allowlist on `oke()`.
-      // (~50.3 kB gzip with export externals).
-      expect(total).toBeLessThan(51_000);
+      // Rebased after host API-key persist + allowlist on `oke()` and the
+      // realtime bridge (CDC sink, LiveQuery runtime, openLiveStream).
+      expect(total).toBeLessThan(58_000);
     } finally {
       await rm(dir, { recursive: true, force: true });
     }

package/src/kernel/errors.ts

@@ -216,6 +216,14 @@ export const OKE_ERRORS = {
       'Live signal "{signal}" is exposed twice with the same gates ({gates}) and match ({match}).',
     fix: "Use a different gate or path-param filter, or drop the extra route.",
   },
+  /**
+   * Two MCP tool bindings share the same exposed tool name.
+   */
+  MCP_TOOL_DUPLICATE: {
+    code: 1018,
+    cause: 'MCP tool "{tool}" is bound twice (flow "{flow}").',
+    fix: "Give each MCP tool exposure a unique tool name.",
+  },
   /**
    * Emit target has no subscriber (unified-theory §21).
    * Thrown at emit when `optional` is false and nobody is subscribed.

package/src/kernel/fx.test.ts

@@ -574,6 +574,7 @@ describe("fx — wholesale swap", () => {
       get signal() {
         return new AbortController().signal;
       },
+      rlsIdentity: undefined,
       all(thunks) {
         return Promise.all(thunks.map((t) => t())) as never;
       },