okengine 0.15.2 → 0.16.0

package/src/console/ui-next/src/features/access/state/access-selection.ts

@@ -0,0 +1,84 @@
+/**
+ * Access page URL search — selected key + sheet action.
+ */
+
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import { useCallback } from "react";
+
+/** Sheet opened from the URL. */
+export type AccessAction = "create" | "edit" | "refresh" | "revoke" | "rotate";
+
+/** Search params for `/access`. */
+export interface AccessSearch {
+  readonly q?: string;
+  readonly key?: string;
+  readonly action?: AccessAction;
+}
+
+/**
+ * Validate Access search params from the router.
+ *
+ * @param search - Raw search object
+ */
+export function validateAccessSearch(search: Record<string, unknown>): AccessSearch {
+  const q = typeof search.q === "string" && search.q.length > 0 ? search.q : undefined;
+  const key = typeof search.key === "string" && search.key.length > 0 ? search.key : undefined;
+  const action =
+    search.action === "create" ||
+    search.action === "edit" ||
+    search.action === "refresh" ||
+    search.action === "revoke" ||
+    search.action === "rotate"
+      ? search.action
+      : undefined;
+  return {
+    ...(q !== undefined ? { q } : {}),
+    ...(key !== undefined ? { key } : {}),
+    ...(action !== undefined ? { action } : {}),
+  };
+}
+
+/**
+ * Read + write the Access page selection from the URL.
+ */
+export function useAccessSelection(): {
+  readonly query: string;
+  readonly selectedKey: string | null;
+  readonly action: AccessAction | null;
+  readonly setQuery: (q: string) => void;
+  readonly setSelectedKey: (key: string | null) => void;
+  readonly setAction: (action: AccessAction | null) => void;
+} {
+  const search = useSearch({ strict: false }) as AccessSearch;
+  const navigate = useNavigate();
+
+  const query = typeof search.q === "string" ? search.q : "";
+  const selectedKey = typeof search.key === "string" ? search.key : null;
+  const action = search.action ?? null;
+
+  const patch = useCallback(
+    (next: Partial<AccessSearch>) => {
+      void navigate({
+        to: ".",
+        search: (prev: Record<string, unknown>) => validateAccessSearch({ ...prev, ...next }),
+        replace: true,
+      });
+    },
+    [navigate],
+  );
+
+  return {
+    query,
+    selectedKey,
+    action,
+    setQuery: (q) => {
+      patch({ q: q.length > 0 ? q : undefined });
+    },
+    setSelectedKey: (key) => {
+      patch({ key: key ?? undefined, action: undefined });
+    },
+    setAction: (next) => {
+      patch({ action: next ?? undefined });
+    },
+  };
+}

package/src/console/ui-next/src/features/auth/auth-redirect.test.ts

@@ -18,6 +18,7 @@ describe("sanitizeReturnTo", () => {
     expect(sanitizeReturnTo("/vault?name=STRIPE_KEY&action=rotate")).toBe(
       "/vault?name=STRIPE_KEY&action=rotate",
     );
+    expect(sanitizeReturnTo("/access?key=key_1")).toBe("/access?key=key_1");
     expect(sanitizeReturnTo("/observability?window=7d")).toBe("/observability?window=7d");
     expect(sanitizeReturnTo("/monitoring?window=7d")).toBe("/observability?window=7d");
   });
@@ -107,6 +108,10 @@ describe("afterAuthLocation", () => {
       to: "/vault",
       search: { name: "STRIPE_KEY", action: "rotate-master" },
     });
+    expect(afterAuthLocation("/access?key=key_1")).toEqual({
+      to: "/access",
+      search: { key: "key_1" },
+    });
     expect(afterAuthLocation("/observability?window=7d&run=r1")).toEqual({
       to: "/observability",
       search: { window: "7d", run: "r1" },

package/src/console/ui-next/src/features/auth/auth-redirect.ts

@@ -2,7 +2,7 @@
  * Post-auth return path — keep the operator on the module they were in
  * after a session expires, instead of always landing on `/overview`.
  *
- * Only `/overview`, `/flows`, `/store`, `/vault`, and `/observability` (plus their
+ * Only `/overview`, `/flows`, `/store`, `/vault`, `/access`, and `/observability` (plus their
  * search) are legal. `/monitoring` is rewritten to `/observability`. Anything else
  * is dropped so `?next=` cannot be an open redirect.
  */
@@ -15,12 +15,20 @@ import {
   type ObservabilitySearch,
 } from "../observability/state/observability-selection.ts";
 import { validateVaultSearch, type VaultSearch } from "../vault/state/vault-selection.ts";
+import { validateAccessSearch, type AccessSearch } from "../access/state/access-selection.ts";
 
 /** Default shell module when no safe return path is present. */
 export const DEFAULT_AFTER_AUTH = "/overview" as const;
 
 /** Shell pathnames that may be restored after login. */
-const SHELL_PATHS = new Set(["/overview", "/flows", "/store", "/vault", "/observability"]);
+const SHELL_PATHS = new Set([
+  "/overview",
+  "/flows",
+  "/store",
+  "/vault",
+  "/access",
+  "/observability",
+]);
 
 /** Retired live module — rewritten to {@link CANONICAL_OBSERVABILITY}. */
 const LEGACY_MONITORING = "/monitoring";
@@ -40,6 +48,7 @@ export type AfterAuthLocation =
   | { readonly to: "/flows"; readonly search: UnitsSearch }
   | { readonly to: "/store"; readonly search: StoreSearch }
   | { readonly to: "/vault"; readonly search: VaultSearch }
+  | { readonly to: "/access"; readonly search: AccessSearch }
   | { readonly to: "/observability"; readonly search: ObservabilitySearch };
 
 /**
@@ -111,6 +120,9 @@ export function afterAuthLocation(value: unknown): AfterAuthLocation {
   if (url.pathname === "/vault") {
     return { to: "/vault", search: validateVaultSearch(raw) };
   }
+  if (url.pathname === "/access") {
+    return { to: "/access", search: validateAccessSearch(raw) };
+  }
   if (url.pathname === CANONICAL_OBSERVABILITY) {
     return { to: "/observability", search: validateObservabilitySearch(raw) };
   }
@@ -123,6 +135,7 @@ export type AfterAuthNavigate = {
   (opts: { to: "/flows"; search: UnitsSearch }): unknown;
   (opts: { to: "/store"; search: StoreSearch }): unknown;
   (opts: { to: "/vault"; search: VaultSearch }): unknown;
+  (opts: { to: "/access"; search: AccessSearch }): unknown;
   (opts: { to: "/observability"; search: ObservabilitySearch }): unknown;
 };
 
@@ -144,6 +157,9 @@ export function goAfterAuth(navigate: AfterAuthNavigate, value: unknown): void {
     case "/vault":
       void navigate({ to: "/vault", search: dest.search });
       return;
+    case "/access":
+      void navigate({ to: "/access", search: dest.search });
+      return;
     case "/observability":
       void navigate({ to: "/observability", search: dest.search });
       return;

package/src/console/ui-next/src/features/not-found/not-found-page.tsx

@@ -6,7 +6,7 @@ import { authLabelClassName } from "@/components/auth-card";
 import { ConsoleChrome } from "@/components/console-chrome";
 
 /**
- * 404 for any path that is not `/`, `/overview`, `/flows`, `/store`, `/vault`, or `/observability`.
+ * 404 for any path that is not `/`, `/overview`, `/flows`, `/store`, `/vault`, `/access`, or `/observability`.
  */
 export function NotFoundPage() {
   return (

package/src/console/ui-next/src/lib/document-meta.test.ts

@@ -25,6 +25,7 @@ describe("consoleDocumentTitle", () => {
       `Observability · ${CONSOLE_DOCUMENT_TITLE}`,
     );
     expect(consoleDocumentTitle("/vault")).toBe(`Vault · ${CONSOLE_DOCUMENT_TITLE}`);
+    expect(consoleDocumentTitle("/access")).toBe(`Access · ${CONSOLE_DOCUMENT_TITLE}`);
     expect(consoleDocumentTitle("/monitoring")).toBe(`Observability · ${CONSOLE_DOCUMENT_TITLE}`);
   });
 

package/src/console/ui-next/src/lib/document-meta.ts

@@ -7,7 +7,7 @@ export const CONSOLE_DOCUMENT_TITLE = "okengine Console";
 
 /** Operator-facing `meta name="description"` / Open Graph copy. */
 export const CONSOLE_DOCUMENT_DESCRIPTION =
-  "Operator Console for okengine — Flows, Store, Observability, and Vault.";
+  "Operator Console for okengine — Flows, Store, Observability, Vault, and Access.";
 
 const PAGE_TITLES: Record<string, string> = {
   "/overview": "Overview",
@@ -15,6 +15,7 @@ const PAGE_TITLES: Record<string, string> = {
   "/store": "Store",
   "/observability": "Observability",
   "/vault": "Vault",
+  "/access": "Access",
   "/monitoring": "Observability",
 };
 

package/src/console/ui-next/src/lib/last-module-search.test.ts

@@ -12,6 +12,7 @@ describe("last-module-search", () => {
     expect(isConsoleModulePath("/overview")).toBe(true);
     expect(isConsoleModulePath("/flows")).toBe(true);
     expect(isConsoleModulePath("/observability")).toBe(true);
+    expect(isConsoleModulePath("/access")).toBe(true);
     expect(isConsoleModulePath("/monitoring")).toBe(false);
     expect(isConsoleModulePath("/units")).toBe(false);
     expect(isConsoleModulePath("/")).toBe(false);

package/src/console/ui-next/src/lib/last-module-search.ts

@@ -1,6 +1,6 @@
 /**
  * Remember each Console module's last URL search so sidebar hops
- * restore Overview / Flows / Store / Observability / Vault instead of wiping them.
+ * restore Overview / Flows / Store / Observability / Vault / Access instead of wiping them.
  */
 
 /** Authenticated Console modules that own URL search. */
@@ -10,6 +10,7 @@ export const CONSOLE_MODULE_PATHS = [
   "/store",
   "/observability",
   "/vault",
+  "/access",
 ] as const;
 
 /** Pathname for a Console module. */

package/src/console/ui-next/src/lib/shortcut.test.ts

@@ -21,6 +21,7 @@ describe("consoleShortcut", () => {
     expect(consoleShortcut("store")).toEqual(modChord("3"));
     expect(consoleShortcut("observability")).toEqual(modChord("4"));
     expect(consoleShortcut("vault")).toEqual(modChord("5"));
+    expect(consoleShortcut("access")).toEqual(modChord("6"));
   });
 
   test("digits map to module paths", () => {
@@ -29,6 +30,7 @@ describe("consoleShortcut", () => {
     expect(MODULE_DIGIT_PATH["3"]).toBe("/store");
     expect(MODULE_DIGIT_PATH["4"]).toBe("/observability");
     expect(MODULE_DIGIT_PATH["5"]).toBe("/vault");
+    expect(MODULE_DIGIT_PATH["6"]).toBe("/access");
   });
 });
 

package/src/console/ui-next/src/lib/shortcut.ts

@@ -63,6 +63,7 @@ export type ConsoleShortcutId =
   | "flows"
   | "store"
   | "vault"
+  | "access"
   | "observability";
 
 const MODULE_DIGIT: Readonly<
@@ -73,6 +74,7 @@ const MODULE_DIGIT: Readonly<
   store: "3",
   observability: "4",
   vault: "5",
+  access: "6",
 };
 
 /**
@@ -94,6 +96,7 @@ export const MODULE_DIGIT_PATH: Readonly<Record<string, ConsoleModulePath>> = {
   "3": "/store",
   "4": "/observability",
   "5": "/vault",
+  "6": "/access",
 };
 
 /**

package/src/console/ui-next/src/router.tsx

@@ -1,6 +1,6 @@
 /**
  * Console router — code-based TanStack Router (Vite SPA).
- * Pre-auth `/` and authenticated shell `/overview` | `/flows` | `/store` | `/vault` | `/observability`.
+ * Pre-auth `/` and authenticated shell `/overview` | `/flows` | `/store` | `/vault` | `/access` | `/observability`.
  * `/monitoring` is a one-shot search-preserving redirect to `/observability`.
  * Authenticated pages are `lazyRouteComponent` so Vite splits them out of the entry.
  * Any other path is a 404 — no legacy rewrites.
@@ -30,6 +30,7 @@ import { validateStoreSearch } from "./features/store/state/store-selection.ts";
 import { validateUnitsSearch } from "./features/units/state/units-selection.ts";
 import { validateObservabilitySearch } from "./features/observability/state/observability-selection.ts";
 import { validateVaultSearch } from "./features/vault/state/vault-selection.ts";
+import { validateAccessSearch } from "./features/access/state/access-selection.ts";
 import { DocumentTitle } from "./components/document-title.tsx";
 import { ShellLayout } from "./components/shell/shell-layout.tsx";
 
@@ -120,6 +121,13 @@ const vaultRoute = createRoute({
   component: lazyRouteComponent(() => import("./features/vault/vault-page.tsx"), "VaultPage"),
 });
 
+const accessRoute = createRoute({
+  getParentRoute: () => authenticatedRoute,
+  path: "/access",
+  validateSearch: validateAccessSearch,
+  component: lazyRouteComponent(() => import("./features/access/access-page.tsx"), "AccessPage"),
+});
+
 const observabilityRoute = createRoute({
   getParentRoute: () => authenticatedRoute,
   path: "/observability",
@@ -146,6 +154,7 @@ const routeTree = rootRoute.addChildren([
     flowsRoute,
     storeRoute,
     vaultRoute,
+    accessRoute,
     observabilityRoute,
     monitoringRedirectRoute,
   ]),

package/src/console/ui-next/ui-next-seed-app-schema.ts

@@ -7,6 +7,7 @@
 import { AUTH_TABLES } from "../../auth/tables.ts";
 import { resolveAuthSchema } from "../../auth/schema.ts";
 import type { DeclaredColumn, Table } from "../../manifest/types.ts";
+import { KEEL_LADDER_GRANTS, KEEL_SCOPES } from "../server/dev-identities.ts";
 
 const PII_COLUMNS = new Set([
   "email",
@@ -163,9 +164,63 @@ export const UI_NEXT_SEED_APP_SYSTEM_TABLES: Record<string, Table> = {
 const NOW = 1_723_622_400_000;
 const LATER = NOW + 30 * 24 * 60 * 60 * 1000;
 
-const PEOPLE = [
-  { id: "user_demo", email: "demo@example.com", name: "Demo User", status: "active" },
-  { id: "user_member", email: "member@example.com", name: "Member", status: "active" },
+/** Ten-rung owner → guest ladder (demo + member keep historic ids). */
+const LADDER = [
+  {
+    id: "user_demo",
+    email: "demo@example.com",
+    name: "Demo User",
+    status: "active",
+    role: "owner",
+  },
+  { id: "user_admin", email: "admin@example.com", name: "Admin", status: "active", role: "admin" },
+  {
+    id: "user_workspace",
+    email: "workspace@example.com",
+    name: "Workspace Admin",
+    status: "active",
+    role: "workspace_admin",
+  },
+  {
+    id: "user_pm",
+    email: "pm@example.com",
+    name: "Project Manager",
+    status: "active",
+    role: "project_manager",
+  },
+  { id: "user_lead", email: "lead@example.com", name: "Lead", status: "active", role: "lead" },
+  {
+    id: "user_dev",
+    email: "developer@example.com",
+    name: "Developer",
+    status: "active",
+    role: "developer",
+  },
+  {
+    id: "user_writer",
+    email: "writer@example.com",
+    name: "Contributor",
+    status: "active",
+    role: "contributor",
+  },
+  {
+    id: "user_member",
+    email: "member@example.com",
+    name: "Member",
+    status: "active",
+    role: "member",
+  },
+  {
+    id: "user_commenter",
+    email: "commenter@example.com",
+    name: "Commenter",
+    status: "active",
+    role: "commenter",
+  },
+  { id: "user_guest", email: "guest@example.com", name: "Guest", status: "active", role: "guest" },
+] as const;
+
+const STORY = [
   { id: "idn_aria", email: "aria@keel.dev", name: "Aria Chen", status: "active" },
   { id: "idn_ben", email: "ben@keel.dev", name: "Ben Okonkwo", status: "active" },
   { id: "idn_cai", email: "cai@keel.dev", name: "Cai Moreno", status: "active" },
@@ -185,6 +240,8 @@ const PEOPLE = [
   { id: "idn_zio", email: "zio@keel.dev", name: "Zio Hart", status: "active" },
 ] as const;
 
+const PEOPLE = [...LADDER, ...STORY];
+
 /**
  * Seeded rows for app-plane system tables (never secret values).
  */
@@ -209,49 +266,43 @@ export const UI_NEXT_SEED_APP_SYSTEM_ROWS: Readonly<Record<string, readonly obje
     updated_at: NOW,
   })),
   [AUTH_TABLES.identityRoles]: [
-    ...PEOPLE.map((p) => ({
+    ...LADDER.filter((p) => p.role !== "guest").map((p) => ({
+      id: `ir_${p.id}_${p.role}`,
+      identity_id: p.id,
+      role_id: `role_${p.role}`,
+    })),
+    ...STORY.map((p) => ({
       id: `ir_${p.id}_member`,
       identity_id: p.id,
       role_id: "role_member",
     })),
-    { id: "ir_idn_aria_staff", identity_id: "idn_aria", role_id: "role_staff" },
-    { id: "ir_user_demo_staff", identity_id: "user_demo", role_id: "role_staff" },
-  ],
-  [AUTH_TABLES.roles]: [
-    { id: "role_member", name: "member", plane: "user", description: "Signed-in workspace member" },
-    { id: "role_staff", name: "staff", plane: "user", description: "May accept triage" },
-    {
-      id: "role_issue_write",
-      name: "issue:write",
-      plane: "user",
-      description: "May create and update issues",
-    },
-    {
-      id: "role_team_admin",
-      name: "team:admin",
-      plane: "user",
-      description: "May create teams and close cycles",
-    },
-  ],
-  [AUTH_TABLES.roleGrants]: [
-    { id: "rg_1", role_id: "role_member", action: "member" },
-    { id: "rg_2", role_id: "role_staff", action: "member" },
-    { id: "rg_3", role_id: "role_staff", action: "triage:accept" },
-    { id: "rg_4", role_id: "role_issue_write", action: "issue:write" },
-    { id: "rg_5", role_id: "role_issue_write", action: "project:admin" },
-    { id: "rg_6", role_id: "role_issue_write", action: "comment:write" },
-    { id: "rg_7", role_id: "role_issue_write", action: "files:write" },
-    { id: "rg_8", role_id: "role_team_admin", action: "team:admin" },
-    { id: "rg_9", role_id: "role_team_admin", action: "member:admin" },
-    { id: "rg_10", role_id: "role_team_admin", action: "webhook:admin" },
+    { id: "ir_idn_aria_pm", identity_id: "idn_aria", role_id: "role_project_manager" },
   ],
+  [AUTH_TABLES.roles]: Object.keys(KEEL_LADDER_GRANTS).map((role) => ({
+    id: `role_${role}`,
+    name: role,
+    plane: "user",
+    description:
+      role === "owner"
+        ? "Full workspace authorization"
+        : role === "guest"
+          ? "Least authorization — no write scopes"
+          : `Keel ${role.replaceAll("_", " ")}`,
+  })),
+  [AUTH_TABLES.roleGrants]: Object.entries(KEEL_LADDER_GRANTS).flatMap(([role, actions]) =>
+    actions.map((action, i) => ({
+      id: `rg_${role}_${i + 1}`,
+      role_id: `role_${role}`,
+      action,
+    })),
+  ),
   [AUTH_TABLES.apiKeys]: [
     {
       id: "key_keel_ci",
       plane: "user",
       hash: "sha256$keel_ci",
       name: "Keel CI",
-      scopes: "member,issue:write",
+      scopes: "member,task:write",
       expires_at: null,
       created_at: NOW,
       last_used_at: NOW - 3_600_000,
@@ -279,7 +330,7 @@ export const UI_NEXT_SEED_APP_SYSTEM_ROWS: Readonly<Record<string, readonly obje
       created_at: NOW,
       expires_at: LATER,
       last_active_at: NOW,
-      scopes: "member,issue:write",
+      scopes: KEEL_LADDER_GRANTS.project_manager.join(","),
       audience: "oke-app",
     },
     {
@@ -291,7 +342,7 @@ export const UI_NEXT_SEED_APP_SYSTEM_ROWS: Readonly<Record<string, readonly obje
       created_at: NOW,
       expires_at: LATER,
       last_active_at: NOW,
-      scopes: "member,issue:write",
+      scopes: KEEL_SCOPES.join(","),
       audience: "oke-app",
     },
   ],

package/src/console/ui-next/ui-next-seed-store.ts

@@ -41,6 +41,20 @@ const SEED_SPACES = [
 ] as const;
 
 const SEED_MEMBERS = [
+  {
+    id: "mem_demo",
+    space_id: "space_eng",
+    name: "Demo User",
+    email: "demo@example.com",
+    role: "owner",
+  },
+  {
+    id: "mem_admin",
+    space_id: "space_eng",
+    name: "Avery Cole",
+    email: "admin@keel.dev",
+    role: "admin",
+  },
   {
     id: "mem_aria",
     space_id: "space_eng",
@@ -48,6 +62,13 @@ const SEED_MEMBERS = [
     email: "aria@keel.dev",
     role: "project_manager",
   },
+  {
+    id: "mem_lead",
+    space_id: "space_eng",
+    name: "Jules Hart",
+    email: "jules@keel.dev",
+    role: "lead",
+  },
   {
     id: "mem_ben",
     space_id: "space_eng",
@@ -55,6 +76,13 @@ const SEED_MEMBERS = [
     email: "ben@keel.dev",
     role: "developer",
   },
+  {
+    id: "mem_eli",
+    space_id: "space_eng",
+    name: "Eli Park",
+    email: "eli@keel.dev",
+    role: "contributor",
+  },
   {
     id: "mem_cai",
     space_id: "space_des",
@@ -62,6 +90,20 @@ const SEED_MEMBERS = [
     email: "cai@keel.dev",
     role: "member",
   },
+  {
+    id: "mem_member",
+    space_id: "space_des",
+    name: "Member",
+    email: "member@example.com",
+    role: "member",
+  },
+  {
+    id: "mem_commenter",
+    space_id: "space_gtm",
+    name: "Kit Rowe",
+    email: "kit@keel.dev",
+    role: "commenter",
+  },
   {
     id: "mem_dia",
     space_id: "space_gtm",
@@ -69,13 +111,6 @@ const SEED_MEMBERS = [
     email: "dia@keel.dev",
     role: "guest",
   },
-  {
-    id: "mem_eli",
-    space_id: "space_eng",
-    name: "Eli Park",
-    email: "eli@keel.dev",
-    role: "developer",
-  },
 ] as const;
 
 const SEED_GOALS = [
@@ -640,14 +675,7 @@ function generateKeelVolume(): {
     email: `${p.id}@keel.dev`,
     role: "member",
   }));
-  const emails = [
-    "aria@keel.dev",
-    "ben@keel.dev",
-    "cai@keel.dev",
-    "dia@keel.dev",
-    "eli@keel.dev",
-    ...members.map((m) => m.email),
-  ];
+  const emails = [...SEED_MEMBERS.map((m) => m.email), ...members.map((m) => m.email)];
 
   const projects = Array.from({ length: GENERATED.projects }, (_, i) => ({
     id: `proj_g_${String(i + 1).padStart(2, "0")}`,

package/src/console/xss.gate.test.ts

@@ -21,6 +21,7 @@ const FEATURES_ROOT = `${UI_ROOT}/features`;
  * already covers it; the list makes coverage explicit in CI output.
  */
 export const CONSOLE_UI_FEATURE_DIRS = [
+  "access",
   "auth",
   "flows",
   "not-found",

package/src/elements/gate/declare.ts

@@ -19,6 +19,8 @@ export interface GatePolicyContext {
     readonly userId: string | null;
     readonly scopes: ReadonlySet<string>;
     readonly verified?: boolean;
+    /** Authenticating API key id when the principal is a key; otherwise omitted. */
+    readonly apiKeyId?: string | null;
   };
   /** Operator-plane principal (`fx.operator`). */
   readonly operator: {

package/src/elements/store/cache.ts

@@ -63,7 +63,7 @@ export function tier1KeysForReads(
  * @param effects - Write flow effects
  */
 export function resourcesTouchedByWrites(effects: Effects): ResourceRef[] {
-  return [...(effects.writes ?? [])];
+  return (effects.writes ?? []).filter((r): r is ResourceRef => isStoreResourceRef(r));
 }
 
 /**

package/src/elements/store/runtime.ts

@@ -239,6 +239,13 @@ export interface StoreRuntime {
    * @param ref - `kv:name`
    */
   kvNamespace(ref: ResourceRef): Promise<KvNamespace>;
+  /**
+   * Shared primary SQL connection (`sharedSqlConn`).
+   *
+   * Host auth persist (`oke_api_keys`) and durable KV borrow this same
+   * connection — never a second open against `store.sql()` / `DATABASE_URL`.
+   */
+  primarySql(): Promise<SqlConnection | undefined>;
   /**
    * Register a declaration (usually done at module load).
    *
@@ -545,6 +552,13 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
       if (!ns) throw new Error(`Unknown kv ref: ${ref}`);
       return ns;
     },
+    async primarySql() {
+      const sqlDriver = options.drivers.sql;
+      if (!sqlDriver) return undefined;
+      const firstSql = Object.values(options.sql ?? [])[0];
+      const url = options.sqlUrl ?? firstSql?.primary.url;
+      return sharedSqlConn(sqlDriver, "primary", { url });
+    },
     onWriteEffects(effects) {
       return cache.invalidateFromEffects(effects);
     },