okengine 0.11.2 → 0.12.0

package/src/console/server/store.ts

@@ -15,7 +15,10 @@ import {
   computedCacheKey,
   createStoreRuntime,
   files as declareFiles,
+  fileKeyWarnings,
   index as declareIndex,
+  coerceSafeFileObjectKey,
+  inferFileContentType,
   isInvalidatedByWrite,
   kv as declareKv,
   projectFileKeys,
@@ -27,8 +30,37 @@ import {
   type StoreRuntime,
 } from "../../elements/store.ts";
 import { DryRunWriteIsolationError, withDryRun } from "../../kernel/dry-run.ts";
-import type { Effects, Manifest, ResourceRef, StoreFacet } from "../../manifest/types.ts";
+import { addPiiFieldName, piiNameAliases, PII_MASK } from "../../elements/store/classify.ts";
+import { rankIndexHits } from "./index-search.ts";
+import type {
+  ColumnClassification,
+  Effects,
+  Manifest,
+  ResourceRef,
+  StoreFacet,
+} from "../../manifest/types.ts";
 import type { WideEvent } from "../../runs/types.ts";
+import { consoleAuthStoreEnabled, projectConsoleAuthStore } from "./auth-store.ts";
+import {
+  fileObjectRecord,
+  isFilesCatalogKey,
+  readFilesCatalog,
+  removeFilesCatalogRecords,
+  upsertFilesCatalogRecord,
+} from "./files-catalog.ts";
+import {
+  alterSqlPolicy,
+  createSqlPolicy,
+  dropSqlPolicy,
+  applySqlTableRls,
+  listSqlCatalog,
+  listSqlTableRls,
+  setSqlExtension,
+  setSqlRowSecurity,
+  sqlCatalogKind,
+  sqlCatalogStoreChildren,
+  upgradeSqlExtension,
+} from "./sql-catalog.ts";
 
 /** Whether multi-tenancy is declared on the Manifest (off by default). */
 export function tenancyDeclared(manifest: Manifest | null): boolean {
@@ -64,6 +96,8 @@ export interface ConsoleStoreChild {
   readonly name: string;
   /** Effect ref used in Manifest (`sql:bookings`). */
   readonly effectRef: ResourceRef;
+  /** SQL catalog folder when not a table. */
+  readonly kind?: "table" | "index" | "function" | "trigger" | "extension" | "policy";
   readonly writers: readonly string[];
   readonly readers: readonly string[];
   readonly cache: ConsoleStoreCacheView;
@@ -71,6 +105,8 @@ export interface ConsoleStoreChild {
   readonly piiColumns: readonly string[];
   /** Column key → optional human description (SQL tables). */
   readonly columnDescriptions: Readonly<Record<string, string>>;
+  /** Live RLS (`pg_class.relrowsecurity`) when the engine can report it. */
+  readonly rls?: boolean;
 }
 
 /** One row in `console.store.list`. */
@@ -83,6 +119,8 @@ export interface ConsoleStoreRow {
   readonly replicaLagMs: number | null;
   readonly migrationDrift: ConsoleMigrationDrift | null;
   readonly contentAddressed: boolean;
+  /** Files driver when the runtime could open the handle (`memory` / `fs` / `s3`). */
+  readonly driverId?: "memory" | "fs" | "s3";
   readonly warnings: ReadonlyArray<{
     readonly code: string;
     readonly message: string;
@@ -99,6 +137,11 @@ export interface ProjectStoresOptions {
   /** Injected fingerprints for tests. */
   readonly declaredFingerprint?: string;
   readonly appliedFingerprint?: string | null;
+  /**
+   * Surface `sql:oke_console` (operator-plane auth). Default: env
+   * `OKE_CONSOLE_AUTH_STORE=1`.
+   */
+  readonly includeAuthStore?: boolean;
 }
 
 /**
@@ -135,17 +178,26 @@ export async function projectStoresList(options: ProjectStoresOptions): Promise<
   for (const [name, store] of Object.entries(manifest?.stores ?? {})) {
     const facet = store.facet;
     const ref = `${facet}:${name}` as ResourceRef;
-    const children = childrenOf(manifest!, name, facet, store);
+    const children = await withSqlTableRls(
+      options.runtime,
+      ref,
+      facet,
+      childrenOf(manifest!, name, facet, store),
+    );
     const replicaLagMs = facet === "sql" ? latestReplicaLag(options.runs ?? [], children) : null;
 
     let warnings: ConsoleStoreRow["warnings"] = [];
+    let filesDriverId: FilesStoreFxHandle["driverId"] | undefined;
     if (facet === "files" && options.runtime) {
       try {
         const handle = (await options.runtime.openRef(ref, {
           effects: { reads: [ref] },
         })) as FilesStoreFxHandle;
+        filesDriverId = handle.driverId;
         const keys = await handle.list();
-        warnings = projectFileKeys(keys).flatMap((k) => k.warnings);
+        warnings = projectFileKeys(keys.filter((k) => !isFilesCatalogKey(k))).flatMap(
+          (k) => k.warnings,
+        );
       } catch {
         warnings = [];
       }
@@ -160,10 +212,15 @@ export async function projectStoresList(options: ProjectStoresOptions): Promise<
       replicaLagMs,
       migrationDrift: facet === "sql" ? drift : null,
       contentAddressed: facet === "files",
+      ...(filesDriverId ? { driverId: filesDriverId } : {}),
       warnings,
     });
   }
 
+  if (options.includeAuthStore ?? consoleAuthStoreEnabled()) {
+    stores.push(projectConsoleAuthStore());
+  }
+
   stores.sort((a, b) => {
     const order: StoreFacet[] = ["sql", "kv", "files", "index"];
     const d = order.indexOf(a.facet) - order.indexOf(b.facet);
@@ -200,10 +257,8 @@ function childrenOf(
   }
 
   const unique = [...new Set(names)].sort();
-  return unique.map((childName) => {
-    const effectRef = (
-      facet === "sql" ? `sql:${childName}` : `${facet}:${storeName}`
-    ) as ResourceRef;
+  const tables = unique.map((childName) => {
+    const effectRef = `${facet}:${childName}` as ResourceRef;
     const writers = flowsTouching(manifest, effectRef, "writes");
     const readers = flowsTouching(manifest, effectRef, "reads");
     const willNotFire = willNotFireFor(manifest, writers);
@@ -224,8 +279,26 @@ function childrenOf(
       willNotFire,
       piiColumns,
       columnDescriptions: columnDescriptionsFor(store, childName),
+      ...(facet === "sql" ? { kind: "table" as const, rls: false } : {}),
     };
   });
+  if (facet !== "sql") return tables;
+  return [...tables, ...sqlCatalogStoreChildren(`${facet}:${storeName}` as ResourceRef)];
+}
+
+async function withSqlTableRls(
+  runtime: StoreRuntime | null,
+  ref: ResourceRef,
+  facet: StoreFacet,
+  children: readonly ConsoleStoreChild[],
+): Promise<readonly ConsoleStoreChild[]> {
+  if (facet !== "sql" || runtime === null) return children;
+  try {
+    const sql = (await runtime.openRef(ref, { effects: { reads: [ref] } })) as SqlStoreHandle;
+    return applySqlTableRls(children, await listSqlTableRls(sql));
+  } catch {
+    return children;
+  }
 }
 
 function columnDescriptionsFor(
@@ -278,10 +351,16 @@ export function willNotFireFor(
 }
 
 function piiColumnsFor(store: NonNullable<Manifest["stores"]>[string], table: string): string[] {
-  const cols: string[] = [];
+  const cols = new Set<string>();
   const tableMeta = store.tables?.[table];
   for (const [col, tags] of Object.entries(tableMeta?.columns ?? {})) {
-    if (tags?.pii) cols.push(col);
+    if (!tags?.pii) continue;
+    addPiiFieldName(cols, col);
+    const sqlName =
+      "sqlName" in tags && typeof (tags as { sqlName?: unknown }).sqlName === "string"
+        ? (tags as { sqlName: string }).sqlName
+        : undefined;
+    if (sqlName) addPiiFieldName(cols, sqlName);
   }
   for (const [key, tags] of Object.entries(store.classifications ?? {})) {
     if (
@@ -292,10 +371,10 @@ function piiColumnsFor(store: NonNullable<Manifest["stores"]>[string], table: st
       "pii" in tags &&
       (tags as { pii?: boolean }).pii
     ) {
-      cols.push(key.slice(table.length + 1));
+      addPiiFieldName(cols, key.slice(table.length + 1));
     }
   }
-  return [...new Set(cols)].sort();
+  return [...cols].sort();
 }
 
 function latestReplicaLag(
@@ -341,6 +420,9 @@ export interface StoreQueryResult {
   readonly keys?: ReadonlyArray<{
     readonly key: string;
     readonly value?: unknown;
+    readonly ttlMs?: number | null;
+    readonly sizeBytes?: number;
+    readonly originalName?: string;
     readonly warnings?: ReadonlyArray<{
       readonly code: string;
       readonly message: string;
@@ -356,6 +438,62 @@ export interface StoreQueryResult {
   readonly routedRole?: "primary" | "replica";
 }
 
+const KV_TTL_RE = /^(\d+)(ms|s|m|h|d)$/;
+
+/**
+ * Prefix for `kv.list` when Console browse does not pass an explicit one.
+ *
+ * A dedicated `store.kv("drafts")` keeps keys at the namespace root
+ * (`ENG-184`). `${child}:` is only for a shared KV store whose children
+ * are key prefixes (`kv:cache` / `drafts:…`).
+ *
+ * @param ref - Store ref (`kv:drafts`)
+ * @param child - Selected child / namespace
+ * @param explicit - Operator-supplied list prefix
+ */
+function kvBrowsePrefix(
+  ref: string,
+  child: string | undefined,
+  explicit: string | undefined,
+): string {
+  if (explicit !== undefined) return explicit;
+  if (!child) return "";
+  const storeName = ref.split(":")[1] ?? "";
+  if (child === storeName) return "";
+  return `${child}:`;
+}
+
+/**
+ * Resolve the TTL argument for `kv.set` from a Console patch.
+ * Omitted `ttl` keeps the remaining expiry; `null` / empty clears it.
+ *
+ * @param patch - Edit patch
+ * @param remainingMs - Current remaining TTL, or null
+ */
+function kvTtlFromPatch(
+  patch: Readonly<Record<string, unknown>>,
+  remainingMs: number | null,
+): string | undefined {
+  if (!("ttl" in patch)) {
+    return remainingMs !== null && remainingMs > 0 ? `${Math.ceil(remainingMs)}ms` : undefined;
+  }
+  const raw = patch.ttl;
+  if (raw === null || raw === "") return undefined;
+  if (typeof raw !== "string" || !KV_TTL_RE.test(raw.trim())) {
+    throw new Error("TTL must be a duration like 30m, 1h, or empty to clear");
+  }
+  return raw.trim();
+}
+
+/** UTF-8 byte length of a JSON-serialized KV value. */
+function kvValueSizeBytes(value: unknown): number {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value ?? null)).length;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * Browse a store facet through the runtime (PII masked unless reveal).
  *
@@ -381,6 +519,12 @@ export async function queryStore(
     if (!table) {
       return { facet, rows: [], masked: !input.revealPii, routedRole: sql.routedRole };
     }
+    const catalog = sqlCatalogKind(table);
+    if (catalog) {
+      const storeName = input.ref.split(":")[1] ?? "";
+      const rows = await listSqlCatalog(sql, catalog, manifest, storeName, input.limit ?? 200);
+      return { facet, rows, masked: false, routedRole: sql.routedRole };
+    }
     const limit = input.limit ?? 50;
     let sqlText = `SELECT * FROM "${table}"`;
     const params: unknown[] = [];
@@ -410,51 +554,203 @@ export async function queryStore(
 
   if (facet === "kv") {
     const kv = handle as KvStoreFxHandle;
-    const keys = await kv.list(input.prefix ?? "");
+    const keys = await kv.list(kvBrowsePrefix(input.ref, input.child, input.prefix));
     const limited = keys.slice(0, input.limit ?? 100);
     const entries = await Promise.all(
-      limited.map(async (key) => ({
-        key,
-        value: await kv.get(key),
-      })),
+      limited.map(async (key) => {
+        const value = await kv.get(key);
+        return {
+          key,
+          value,
+          ttlMs: await kv.ttlMs(key),
+          sizeBytes: kvValueSizeBytes(value),
+        };
+      }),
     );
     return { facet, keys: entries, masked: false };
   }
 
   if (facet === "files") {
     const filesHandle = handle as FilesStoreFxHandle;
-    const keys = await filesHandle.list(input.prefix ?? "");
+    const keys = (await filesHandle.list(input.prefix ?? "")).filter((k) => !isFilesCatalogKey(k));
+    const catalog = await readFilesCatalog(filesHandle);
     const projected = projectFileKeys(keys.slice(0, input.limit ?? 100));
-    return {
-      facet,
-      keys: projected.map((k) => ({
-        key: k.key,
-        warnings: k.warnings.map((w) => ({
-          code: w.code,
-          message: w.message,
-        })),
-      })),
-      masked: false,
-    };
+    const entries = await Promise.all(
+      projected.map(async (k) => {
+        const data = await filesHandle.get(k.key);
+        const meta = catalog.objects[k.key];
+        return {
+          key: k.key,
+          sizeBytes: data?.byteLength ?? 0,
+          ...(meta ? { originalName: meta.originalName } : {}),
+          warnings: k.warnings.map((w) => ({
+            code: w.code,
+            message: w.message,
+          })),
+        };
+      }),
+    );
+    return { facet, keys: entries, masked: false };
   }
 
-  // index
+  // index — text query ranks stored meta; a vector still probes ANN.
   const idx = handle as IndexStoreFxHandle;
   void manifest;
+  const topK = input.topK ?? 5;
+  const listLimit = input.limit ?? 100;
+  const q = input.q?.trim() ?? "";
+  const vector = input.vector ?? [];
+
   if (idx.driverId === "meilisearch") {
-    const q = input.q ?? "";
-    if (q.trim().length === 0) {
-      return { facet, hits: [], masked: false };
+    if (q.length > 0) {
+      const result = await idx.search(q, { topK });
+      return {
+        facet,
+        hits: result.hits,
+        facetDistribution: result.facetDistribution,
+        masked: false,
+      };
     }
-    const result = await idx.search(q, { topK: input.topK ?? 5 });
-    return { facet, hits: result.hits, facetDistribution: result.facetDistribution, masked: false };
+    return { facet, hits: await idx.list(listLimit), masked: false };
   }
-  const vector = input.vector ?? [];
-  if (vector.length === 0) {
-    return { facet, hits: [], masked: false };
+
+  if (vector.length > 0) {
+    return { facet, hits: await idx.search(vector, topK), masked: false };
+  }
+  if (q.length > 0) {
+    return {
+      facet,
+      hits: rankIndexHits(await idx.list(INDEX_TEXT_SCAN), q, topK),
+      masked: false,
+    };
   }
-  const hits = await idx.search(vector, input.topK ?? 5);
-  return { facet, hits, masked: false };
+  return { facet, hits: await idx.list(listLimit), masked: false };
+}
+
+/** How many documents a text query scans before ranking. */
+const INDEX_TEXT_SCAN = 2_000;
+
+/** Max object body returned by {@link getStoreFile} (2 MiB). */
+export const STORE_FILE_BODY_MAX = 2_000_000;
+
+/** Request for {@link getStoreFile}. */
+export interface StoreFileGetInput {
+  readonly ref: ResourceRef;
+  readonly key: string;
+  readonly tenant?: string;
+}
+
+/** Object payload for Console preview / download. */
+export interface StoreFileObject {
+  readonly key: string;
+  readonly sizeBytes: number;
+  readonly contentType: string;
+  readonly encoding: "utf8" | "base64";
+  readonly body: string;
+  readonly truncated: boolean;
+  readonly originalName?: string;
+  readonly warnings: ReadonlyArray<{
+    readonly code: string;
+    readonly message: string;
+  }>;
+}
+
+/**
+ * Read one files object for Console preview / download.
+ *
+ * @param runtime - Store runtime
+ * @param input - Store ref + object key
+ */
+export async function getStoreFile(
+  runtime: StoreRuntime,
+  input: StoreFileGetInput,
+): Promise<StoreFileObject> {
+  const [facet] = input.ref.split(":") as [StoreFacet, string];
+  if (facet !== "files") {
+    throw new Error(`store object get requires a files ref, got ${input.ref}`);
+  }
+  const handle = (await runtime.openRef(input.ref, {
+    effects: { reads: [input.ref] },
+  })) as FilesStoreFxHandle;
+  const data = await handle.get(input.key);
+  if (!data) {
+    throw new StoreFileNotFoundError(input.ref, input.key);
+  }
+  const truncated = data.byteLength > STORE_FILE_BODY_MAX;
+  const slice = truncated ? data.subarray(0, STORE_FILE_BODY_MAX) : data;
+  const catalog = await readFilesCatalog(handle);
+  const meta = catalog.objects[input.key];
+  const contentType = meta?.contentType ?? inferFileContentType(meta?.originalName ?? input.key);
+  const asText = fileBytesAsUtf8(slice, contentType);
+  return {
+    key: input.key,
+    sizeBytes: data.byteLength,
+    contentType,
+    encoding: asText !== null ? "utf8" : "base64",
+    body: asText ?? bytesToBase64(slice),
+    truncated,
+    ...(meta ? { originalName: meta.originalName } : {}),
+    warnings: fileKeyWarnings(input.key).map((w) => ({
+      code: w.code,
+      message: w.message,
+    })),
+  };
+}
+
+/** Missing object on {@link getStoreFile}. */
+export class StoreFileNotFoundError extends Error {
+  readonly ref: string;
+  readonly key: string;
+
+  constructor(ref: string, key: string) {
+    super(`object not found: ${key}`);
+    this.name = "StoreFileNotFoundError";
+    this.ref = ref;
+    this.key = key;
+  }
+}
+
+function fileBytesAsUtf8(bytes: Uint8Array, contentType: string): string | null {
+  if (bytes.includes(0)) return null;
+  const textual =
+    contentType.startsWith("text/") ||
+    contentType === "application/json" ||
+    contentType === "application/xml" ||
+    contentType === "application/javascript";
+  if (!textual) return null;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+
+function decodeFilePatchBody(patch: Readonly<Record<string, unknown>>): Uint8Array {
+  const body = patch.body;
+  if (typeof body !== "string") {
+    throw new Error("files put requires string patch.body");
+  }
+  if (patch.encoding === "utf8") {
+    return new TextEncoder().encode(body);
+  }
+  if (patch.encoding !== undefined && patch.encoding !== "base64") {
+    throw new Error("files put encoding must be utf8 or base64");
+  }
+  const binary = atob(body);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
 }
 
 /** Options for a direct edit (not a flow execution). */
@@ -464,6 +760,7 @@ export interface StoreEditInput {
   readonly tenant?: string;
   readonly id?: string;
   readonly key?: string;
+  /** Column values. Omit {@link StoreEditInput.id} to INSERT (requires `patch.id`). */
   readonly patch: Record<string, unknown>;
   readonly confirmation?: string;
   readonly reason?: string;
@@ -512,7 +809,7 @@ export async function editStore(
     const snapshot = await snapshotEditTarget(runtime, input);
     try {
       const { wouldHaveFired } = await withDryRun(async () => {
-        await applyEdit(runtime, input, { revealPii: false });
+        await applyEdit(runtime, input, { revealPii: false, persistMeta: false });
       });
       await restoreEditTarget(runtime, snapshot);
       return {
@@ -531,7 +828,7 @@ export async function editStore(
     }
   }
 
-  await applyEdit(runtime, input, { revealPii: false });
+  await applyEdit(runtime, input, { revealPii: false, persistMeta: true }, manifest);
   // Direct edit: invalidate cache for written resource (effects-derived).
   runtime.onWriteEffects({ writes: [effectRef] });
   void options.production;
@@ -551,6 +848,7 @@ type EditSnapshot =
       readonly ref: ResourceRef;
       readonly key: string;
       readonly value: unknown;
+      readonly ttlMs: number | null;
     }
   | {
       readonly kind: "sql";
@@ -559,6 +857,27 @@ type EditSnapshot =
       readonly id: string;
       readonly row: Record<string, unknown> | null;
     }
+  | {
+      readonly kind: "extension";
+      readonly ref: ResourceRef;
+      readonly name: string;
+      readonly enabled: boolean;
+      readonly version: string | null;
+    }
+  | {
+      readonly kind: "policy";
+      readonly ref: ResourceRef;
+      readonly id: string;
+      readonly existed: boolean;
+    }
+  | {
+      readonly kind: "files";
+      readonly ref: ResourceRef;
+      readonly key: string;
+      readonly data: Uint8Array | null;
+      readonly writtenKey: string;
+      readonly writtenData: Uint8Array | null;
+    }
   | { readonly kind: "none" };
 
 async function snapshotEditTarget(
@@ -566,6 +885,21 @@ async function snapshotEditTarget(
   input: StoreEditInput,
 ): Promise<EditSnapshot> {
   const [facet] = input.ref.split(":") as [StoreFacet, string];
+  if (facet === "files" && input.key) {
+    const filesHandle = (await runtime.openRef(input.ref, {
+      effects: { reads: [input.ref] },
+    })) as FilesStoreFxHandle;
+    const writtenKey = coerceSafeFileObjectKey(input.key);
+    const data = await filesHandle.get(input.key);
+    return {
+      kind: "files",
+      ref: input.ref,
+      key: input.key,
+      data,
+      writtenKey,
+      writtenData: writtenKey === input.key ? data : await filesHandle.get(writtenKey),
+    };
+  }
   if (facet === "kv" && input.key) {
     const kv = (await runtime.openRef(input.ref, {
       effects: { reads: [input.ref] },
@@ -575,37 +909,83 @@ async function snapshotEditTarget(
       ref: input.ref,
       key: input.key,
       value: await kv.get(input.key),
+      ttlMs: await kv.ttlMs(input.key),
     };
   }
-  if (facet === "sql" && input.child && input.id) {
+  if (facet === "sql" && input.child && input.id && sqlCatalogKind(input.child) === "policy") {
     const sql = (await runtime.openRef(input.ref, {
       effects: { reads: [input.ref] },
     })) as SqlStoreHandle;
-    try {
-      const rows = await sql.raw(`SELECT * FROM "${input.child}" WHERE "id" = ? LIMIT 1`, [
-        input.id,
-      ]);
-      return {
-        kind: "sql",
-        ref: input.ref,
-        child: input.child,
-        id: input.id,
-        row: rows[0] ?? null,
-      };
-    } catch {
-      return {
-        kind: "sql",
-        ref: input.ref,
-        child: input.child,
-        id: input.id,
-        row: null,
-      };
+    const rows = await listSqlCatalog(sql, "policy", null, "", 500);
+    return {
+      kind: "policy",
+      ref: input.ref,
+      id: input.id,
+      existed: rows.some((r) => String(r.id) === input.id),
+    };
+  }
+  if (facet === "sql" && input.child && input.id && sqlCatalogKind(input.child) === "extension") {
+    const sql = (await runtime.openRef(input.ref, {
+      effects: { reads: [input.ref] },
+    })) as SqlStoreHandle;
+    const rows = await listSqlCatalog(sql, "extension", null, "", 500);
+    const row = rows.find((r) => String(r.name) === input.id);
+    return {
+      kind: "extension",
+      ref: input.ref,
+      name: input.id,
+      enabled: row?.enabled === true,
+      version: typeof row?.version === "string" ? row.version : null,
+    };
+  }
+  if (facet === "sql" && input.child) {
+    const id = input.id ?? sqlInsertRowId(input.patch);
+    if (id) {
+      const sql = (await runtime.openRef(input.ref, {
+        effects: { reads: [input.ref] },
+      })) as SqlStoreHandle;
+      try {
+        const rows = await sql.raw(`SELECT * FROM "${input.child}" WHERE "id" = ? LIMIT 1`, [id]);
+        return {
+          kind: "sql",
+          ref: input.ref,
+          child: input.child,
+          id,
+          row: rows[0] ?? null,
+        };
+      } catch {
+        return {
+          kind: "sql",
+          ref: input.ref,
+          child: input.child,
+          id,
+          row: null,
+        };
+      }
     }
   }
   return { kind: "none" };
 }
 
 async function restoreEditTarget(runtime: StoreRuntime, snapshot: EditSnapshot): Promise<void> {
+  if (snapshot.kind === "files") {
+    const filesHandle = (await runtime.openRef(snapshot.ref, {
+      effects: { writes: [snapshot.ref] },
+    })) as FilesStoreFxHandle;
+    if (snapshot.writtenKey !== snapshot.key) {
+      if (snapshot.writtenData === null) {
+        await filesHandle.delete(snapshot.writtenKey);
+      } else {
+        await filesHandle.put(snapshot.writtenKey, snapshot.writtenData);
+      }
+    }
+    if (snapshot.data === null) {
+      await filesHandle.delete(snapshot.key);
+    } else {
+      await filesHandle.put(snapshot.key, snapshot.data);
+    }
+    return;
+  }
   if (snapshot.kind === "kv") {
     const kv = (await runtime.openRef(snapshot.ref, {
       effects: { writes: [snapshot.ref] },
@@ -613,7 +993,33 @@ async function restoreEditTarget(runtime: StoreRuntime, snapshot: EditSnapshot):
     if (snapshot.value === undefined) {
       await kv.delete(snapshot.key);
     } else {
-      await kv.set(snapshot.key, snapshot.value);
+      const ttl =
+        snapshot.ttlMs !== null && snapshot.ttlMs > 0
+          ? `${Math.ceil(snapshot.ttlMs)}ms`
+          : undefined;
+      await kv.set(snapshot.key, snapshot.value, ttl);
+    }
+    return;
+  }
+  if (snapshot.kind === "policy") {
+    if (snapshot.existed) return;
+    const sql = (await runtime.openRef(snapshot.ref, {
+      effects: { writes: [snapshot.ref] },
+    })) as SqlStoreHandle;
+    try {
+      await dropSqlPolicy(sql, snapshot.id);
+    } catch {
+      /* best-effort restore */
+    }
+    return;
+  }
+  if (snapshot.kind === "extension") {
+    const sql = (await runtime.openRef(snapshot.ref, {
+      effects: { writes: [snapshot.ref] },
+    })) as SqlStoreHandle;
+    await setSqlExtension(sql, snapshot.name, snapshot.enabled);
+    if (snapshot.enabled && snapshot.version) {
+      await upgradeSqlExtension(sql, snapshot.name, snapshot.version);
     }
     return;
   }
@@ -642,10 +1048,83 @@ async function restoreEditTarget(runtime: StoreRuntime, snapshot: EditSnapshot):
   }
 }
 
+function findFileObjectsTable(
+  manifest: Manifest | null,
+): { readonly ref: ResourceRef; readonly table: string } | null {
+  if (!manifest?.stores) return null;
+  for (const [name, store] of Object.entries(manifest.stores)) {
+    if (store.facet === "sql" && store.tables && "file_objects" in store.tables) {
+      return { ref: `sql:${name}` as ResourceRef, table: "file_objects" };
+    }
+  }
+  return null;
+}
+
+async function upsertFileObjectsSql(
+  runtime: StoreRuntime,
+  manifest: Manifest | null,
+  storeRef: string,
+  row: {
+    readonly objectKey: string;
+    readonly originalName: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+  },
+): Promise<void> {
+  const found = findFileObjectsTable(manifest);
+  if (!found) return;
+  try {
+    const sql = (await runtime.openRef(found.ref, {
+      effects: { writes: [found.ref] },
+    })) as SqlStoreHandle;
+    const existing = await sql.raw(
+      `SELECT "id" FROM "${found.table}" WHERE "object_key" = ? LIMIT 1`,
+      [row.objectKey],
+    );
+    if (existing.length > 0) {
+      await sql.raw(
+        `UPDATE "${found.table}" SET "original_name" = ?, "content_type" = ?, "size_bytes" = ?, "store_ref" = ? WHERE "object_key" = ?`,
+        [row.originalName, row.contentType, row.sizeBytes, storeRef, row.objectKey],
+      );
+      return;
+    }
+    await sql.raw(
+      `INSERT INTO "${found.table}" ("id", "object_key", "original_name", "content_type", "size_bytes", "store_ref") VALUES (?, ?, ?, ?, ?, ?)`,
+      [row.objectKey, row.objectKey, row.originalName, row.contentType, row.sizeBytes, storeRef],
+    );
+  } catch {
+    /* table missing or driver refused — catalog still holds the row */
+  }
+}
+
+async function deleteFileObjectsSql(
+  runtime: StoreRuntime,
+  manifest: Manifest | null,
+  storeRef: string,
+  keys: readonly string[],
+): Promise<void> {
+  const found = findFileObjectsTable(manifest);
+  if (!found || keys.length === 0) return;
+  try {
+    const sql = (await runtime.openRef(found.ref, {
+      effects: { writes: [found.ref] },
+    })) as SqlStoreHandle;
+    for (const key of keys) {
+      await sql.raw(`DELETE FROM "${found.table}" WHERE "object_key" = ? AND "store_ref" = ?`, [
+        key,
+        storeRef,
+      ]);
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
 async function applyEdit(
   runtime: StoreRuntime,
   input: StoreEditInput,
-  ctx: { readonly revealPii: boolean },
+  ctx: { readonly revealPii: boolean; readonly persistMeta?: boolean },
+  manifest?: Manifest | null,
 ): Promise<void> {
   const [facet] = input.ref.split(":") as [StoreFacet, string];
   const handle = await runtime.openRef(input.ref, {
@@ -653,11 +1132,51 @@ async function applyEdit(
     revealPii: ctx.revealPii,
   });
 
+  if (facet === "files") {
+    const filesHandle = handle as FilesStoreFxHandle;
+    const requested = input.key;
+    if (!requested) throw new Error("files edit requires key");
+    const bytes = decodeFilePatchBody(input.patch);
+    const key = coerceSafeFileObjectKey(requested);
+    const originalName =
+      typeof input.patch.originalName === "string" && input.patch.originalName.trim().length > 0
+        ? input.patch.originalName.trim()
+        : requested.slice(requested.lastIndexOf("/") + 1);
+    await filesHandle.put(key, bytes);
+    if (key !== requested) {
+      await filesHandle.delete(requested);
+    }
+    if (ctx.persistMeta !== false) {
+      if (key !== requested) {
+        await removeFilesCatalogRecords(filesHandle, [requested]);
+        await deleteFileObjectsSql(runtime, manifest ?? null, input.ref, [requested]);
+      }
+      await upsertFilesCatalogRecord(
+        filesHandle,
+        key,
+        fileObjectRecord(originalName, bytes.byteLength, key),
+      );
+      await upsertFileObjectsSql(runtime, manifest ?? null, input.ref, {
+        objectKey: key,
+        originalName,
+        contentType: inferFileContentType(originalName),
+        sizeBytes: bytes.byteLength,
+      });
+    }
+    return;
+  }
+
   if (facet === "kv") {
     const kv = handle as KvStoreFxHandle;
     const key = input.key;
     if (!key) throw new Error("kv edit requires key");
-    await kv.set(key, input.patch.value ?? input.patch);
+    const current = await kv.get(key);
+    const nextValue = "value" in input.patch ? input.patch.value : current;
+    if (nextValue === undefined) {
+      throw new Error("kv edit requires a value for a new key");
+    }
+    const ttl = kvTtlFromPatch(input.patch, await kv.ttlMs(key));
+    await kv.set(key, nextValue, ttl);
     return;
   }
 
@@ -665,9 +1184,66 @@ async function applyEdit(
     const sql = handle as SqlStoreHandle;
     const table = input.child;
     const id = input.id;
-    if (!table || !id) throw new Error("sql edit requires child + id");
+    if (!table) throw new Error("sql edit requires child");
+    if (!id && sqlCatalogKind(table) !== null) {
+      throw new Error("sql edit requires child + id");
+    }
+    if (id && sqlCatalogKind(table) === "policy") {
+      if (input.patch.create === true) {
+        await createSqlPolicy(sql, input.patch);
+        return;
+      }
+      if (input.patch.drop === true) {
+        await dropSqlPolicy(sql, id);
+        return;
+      }
+      if (typeof input.patch.rls === "boolean") {
+        const tableName = typeof input.patch.table === "string" ? input.patch.table : id;
+        await setSqlRowSecurity(sql, tableName, input.patch.rls);
+        return;
+      }
+      await alterSqlPolicy(sql, id, input.patch);
+      return;
+    }
+    if (id && sqlCatalogKind(table) === "extension") {
+      if (input.patch.upgrade === true) {
+        const to = typeof input.patch.version === "string" ? input.patch.version : undefined;
+        await setSqlExtension(sql, id, true);
+        await upgradeSqlExtension(sql, id, to);
+        return;
+      }
+      const enabled = input.patch.enabled;
+      if (typeof enabled !== "boolean") {
+        throw new Error("extension edit requires boolean enabled or upgrade");
+      }
+      await setSqlExtension(sql, id, enabled, {
+        ...(typeof input.patch.schema === "string" ? { schema: input.patch.schema } : {}),
+        ...(typeof input.patch.version === "string" ? { version: input.patch.version } : {}),
+        ...(input.patch.cascade === true ? { cascade: true } : {}),
+      });
+      return;
+    }
     const sets = Object.keys(input.patch);
     if (sets.length === 0) return;
+    const pii = piiColumnsForRef(runtime, input.ref, table);
+    for (const column of sets) {
+      if (pii.has(column) && input.patch[column] === PII_MASK) {
+        throw new Error(
+          `refusing to persist PII mask placeholder over column "${column}" — reveal or set a new value`,
+        );
+      }
+    }
+    if (!id) {
+      const insertId = sqlInsertRowId(input.patch);
+      if (!insertId) throw new Error("sql insert requires an id in the patch");
+      const columns = sets.map((c) => `"${c}"`).join(", ");
+      const placeholders = sets.map(() => "?").join(", ");
+      await sql.raw(
+        `INSERT INTO "${table}" (${columns}) VALUES (${placeholders})`,
+        sets.map((c) => input.patch[c]),
+      );
+      return;
+    }
     const assignments = sets.map((c) => `"${c}" = ?`).join(", ");
     const params = [...sets.map((c) => input.patch[c]), id];
     await sql.raw(`UPDATE "${table}" SET ${assignments} WHERE "id" = ?`, params);
@@ -677,6 +1253,35 @@ async function applyEdit(
   throw new Error(`direct edit not supported for facet ${facet}`);
 }
 
+/**
+ * Row id for a SQL insert (`patch.id`). Used when `input.id` is omitted.
+ *
+ * @param patch - Insert column values
+ */
+function sqlInsertRowId(patch: Readonly<Record<string, unknown>>): string | undefined {
+  const raw = patch.id;
+  if (typeof raw === "string" && raw.length > 0) return raw;
+  if (typeof raw === "number" && Number.isFinite(raw)) return String(raw);
+  return undefined;
+}
+
+/** PII columns for a SQL child from the Manifest bound to this runtime. */
+function piiColumnsForRef(
+  runtime: StoreRuntime,
+  ref: ResourceRef,
+  table: string,
+): ReadonlySet<string> {
+  const manifest = runtimeManifest.get(runtime);
+  const storeName = ref.split(":")[1];
+  if (!storeName) return new Set();
+  const store = manifest?.stores?.[storeName];
+  if (!store) return new Set();
+  return new Set(piiColumnsFor(store, table));
+}
+
+/** Manifest captured when the Console runtime is created (for PII guard). */
+const runtimeManifest = new WeakMap<StoreRuntime, Manifest | null>();
+
 /** Delete rows/keys. */
 export interface StoreDeleteInput {
   readonly ref: ResourceRef;
@@ -695,6 +1300,7 @@ export interface StoreDeleteInput {
 export async function deleteStore(
   runtime: StoreRuntime,
   input: StoreDeleteInput,
+  manifest?: Manifest | null,
 ): Promise<{ readonly deleted: number }> {
   const [facet] = input.ref.split(":") as [StoreFacet, string];
   const handle = await runtime.openRef(input.ref, {
@@ -708,9 +1314,16 @@ export async function deleteStore(
     }
   } else if (facet === "files") {
     const filesHandle = handle as FilesStoreFxHandle;
+    const removed: string[] = [];
     for (const key of input.keys ?? []) {
-      if (await filesHandle.delete(key)) deleted++;
+      if (isFilesCatalogKey(key)) continue;
+      if (await filesHandle.delete(key)) {
+        deleted++;
+        removed.push(key);
+      }
     }
+    await removeFilesCatalogRecords(filesHandle, removed);
+    await deleteFileObjectsSql(runtime, manifest ?? null, input.ref, removed);
   } else if (facet === "sql") {
     const sql = handle as SqlStoreHandle;
     const table = input.child;
@@ -757,13 +1370,61 @@ export function purgeStoreCache(
   return { keys: [...new Set([...event.keys, ...extra])] };
 }
 
+/**
+ * True when `name` is `public` or a declared policy Gate (rate gates excluded).
+ *
+ * @param manifest - Current Manifest
+ * @param name - Gate name from the query console
+ */
+export function isKnownConsoleSqlGate(manifest: Manifest | null, name: string): boolean {
+  if (name === "public") return true;
+  const gate = manifest?.gates?.[name];
+  if (!gate) return false;
+  return gate.kind !== "rate" && !name.startsWith("rate:");
+}
+
+const GATE_CONTEXT_DRIVERS = new Set<SqlStoreHandle["driverId"]>(["postgres", "pglite"]);
+
+/** DML / DDL heads — keep in sync with `isSqlWrite` in the query console. */
+const STORE_SQL_WRITE_HEADS = new Set([
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "DROP",
+  "ALTER",
+  "CREATE",
+  "TRUNCATE",
+  "REPLACE",
+  "GRANT",
+  "REVOKE",
+  "VACUUM",
+  "COMMENT",
+  "COPY",
+  "CALL",
+  "REFRESH",
+  "MERGE",
+]);
+
+/**
+ * True when console SQL mutates the store (DML / DDL / `EXPLAIN ANALYZE`).
+ *
+ * @param sql - One statement (already trimmed)
+ */
+export function isStoreSqlWrite(sql: string): boolean {
+  const trimmed = sql.trim().replace(/;+\s*$/, "");
+  const head = /^([A-Za-z]+)/.exec(trimmed)?.[1]?.toUpperCase() ?? "";
+  if (head === "EXPLAIN") return /\bANALYZE\b/i.test(trimmed);
+  if (head === "ANALYZE") return true;
+  return STORE_SQL_WRITE_HEADS.has(head);
+}
+
 /**
  * Raw SQL console — read-only by default.
  *
  * @param runtime - Store runtime
  * @param ref - SQL store ref
  * @param sqlText - SQL
- * @param options - Write allow + reveal
+ * @param options - Write allow + reveal + optional Gate
  */
 export async function runStoreSql(
   runtime: StoreRuntime,
@@ -773,14 +1434,18 @@ export async function runStoreSql(
     readonly allowWrite: boolean;
     readonly revealPii?: boolean;
     readonly tenant?: string;
+    /** View rows as this Gate (`oke.gate` GUC on postgres / pglite). */
+    readonly asGate?: string;
   },
 ): Promise<{
   readonly rows: readonly Record<string, unknown>[];
   readonly masked: boolean;
   readonly routedRole: "primary" | "replica";
+  readonly asGate: string | null;
+  readonly gateApplied: boolean;
 }> {
-  const trimmed = sqlText.trim();
-  const isWrite = /^(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|REPLACE)\b/i.test(trimmed);
+  const trimmed = sqlText.trim().replace(/;+\s*$/, "");
+  const isWrite = isStoreSqlWrite(trimmed);
   if (isWrite && !options.allowWrite) {
     throw new Error("SQL console is read-only by default — write requires console:store.sql:write");
   }
@@ -788,12 +1453,53 @@ export async function runStoreSql(
     effects: isWrite ? { writes: [ref] } : { reads: [ref] },
     revealPii: options.revealPii === true,
   })) as SqlStoreHandle;
-  const rows = await handle.raw(trimmed);
-  return {
-    rows,
-    masked: !options.revealPii,
-    routedRole: handle.routedRole,
-  };
+  const asGate = options.asGate?.trim() || null;
+  let gateApplied = false;
+  try {
+    if (asGate) gateApplied = await applySqlGateContext(handle, asGate);
+    const rows = await handle.raw(trimmed);
+    if (gateApplied) await handle.raw("COMMIT");
+    return {
+      rows,
+      masked: !options.revealPii,
+      routedRole: handle.routedRole,
+      asGate,
+      gateApplied,
+    };
+  } catch (err) {
+    if (gateApplied) {
+      try {
+        await handle.raw("ROLLBACK");
+      } catch {
+        // Connection may already be idle after a failed SET.
+      }
+    }
+    throw err;
+  }
+}
+
+/**
+ * Open a transaction and set `oke.gate` + `row_security` for RLS simulation.
+ * No-op on memory SQL.
+ *
+ * @param handle - Open SQL handle
+ * @param gate - Validated Gate name
+ */
+async function applySqlGateContext(handle: SqlStoreHandle, gate: string): Promise<boolean> {
+  if (!GATE_CONTEXT_DRIVERS.has(handle.driverId)) return false;
+  try {
+    await handle.raw("BEGIN");
+    await handle.raw("SET LOCAL row_security = on");
+    await handle.raw("SELECT set_config('oke.gate', ?, true)", [gate]);
+    return true;
+  } catch {
+    try {
+      await handle.raw("ROLLBACK");
+    } catch {
+      // ignore
+    }
+    return false;
+  }
 }
 
 /**
@@ -834,7 +1540,7 @@ export async function createManifestStoreRuntime(
       case "sql":
         runtime.register(
           declareSql(name, {
-            classify: store.classifications as never,
+            classify: sqlClassifyFromManifest(store),
           }),
         );
         break;
@@ -849,5 +1555,82 @@ export async function createManifestStoreRuntime(
         break;
     }
   }
+  runtimeManifest.set(runtime, manifest);
   return runtime;
 }
+
+/**
+ * Merge flat `store.classifications` with table-column tags from Manifest
+ * `stores.*.tables.*.columns` into the nested `table → column → tags` shape
+ * {@link declareSql} expects (driver-boundary masking).
+ *
+ * @param store - Manifest store row
+ */
+function sqlClassifyFromManifest(
+  store: NonNullable<Manifest["stores"]>[string],
+): Readonly<Record<string, Readonly<Record<string, ColumnClassification>>>> {
+  const nested: Record<string, Record<string, ColumnClassification>> = {};
+
+  for (const [key, value] of Object.entries(store.classifications ?? {})) {
+    const dot = key.indexOf(".");
+    if (dot <= 0) continue;
+    const table = key.slice(0, dot);
+    const column = key.slice(dot + 1);
+    if (column.length === 0) continue;
+    const tags = classificationFromValue(value);
+    if (!tags) continue;
+    putClassifyAliases(nested, table, column, tags);
+  }
+
+  for (const [table, meta] of Object.entries(store.tables ?? {})) {
+    for (const [column, tags] of Object.entries(meta.columns ?? {})) {
+      const normalized = classificationFromValue(tags);
+      if (!normalized) continue;
+      putClassifyAliases(nested, table, column, normalized);
+      const sqlName =
+        "sqlName" in tags && typeof (tags as { sqlName?: unknown }).sqlName === "string"
+          ? (tags as { sqlName: string }).sqlName
+          : undefined;
+      if (sqlName) putClassifyAliases(nested, table, sqlName, normalized);
+    }
+  }
+
+  return nested;
+}
+
+/**
+ * Register classify tags under JS and SQL spellings of a column.
+ *
+ * @param nested - table → column → tags
+ * @param table - Table name
+ * @param column - Manifest or SQL column name
+ * @param tags - Classification tags
+ */
+function putClassifyAliases(
+  nested: Record<string, Record<string, ColumnClassification>>,
+  table: string,
+  column: string,
+  tags: ColumnClassification,
+): void {
+  const row = { ...(nested[table] ?? {}) };
+  for (const name of piiNameAliases(column)) {
+    row[name] = tags;
+  }
+  nested[table] = row;
+}
+
+/**
+ * Normalize a Manifest classification value into tags, or null when not a
+ * tag object (e.g. string / string[] classification forms).
+ *
+ * @param value - Manifest classification value
+ */
+function classificationFromValue(value: unknown): ColumnClassification | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value as Record<string, unknown>;
+  const tags: ColumnClassification = {};
+  if (v.pii === true) tags.pii = true;
+  if (v.sensitive === true) tags.sensitive = true;
+  if (typeof v.retain === "string") tags.retain = v.retain;
+  return Object.keys(tags).length > 0 ? tags : null;
+}