okengine 0.11.2 → 0.12.0

package/src/elements/vault/builtin-adapter.test.ts

@@ -446,6 +446,7 @@ describe("builtin vault adapter — audit and backup", () => {
       const result = await h.adapter.verifyAudit();
       expect(result.ok).toBe(false);
       expect(result.brokenAt).toBe(victim);
+      expect(result.reason).toBe("payload");
     } finally {
       await h.close();
     }

package/src/elements/vault/builtin-adapter.ts

@@ -51,6 +51,7 @@ import {
   purgeAuditBefore as purgeAuditRows,
   purgeExpiredSecrets,
   readAuditPage,
+  readAuditRow,
   releaseRotateLease,
   renewRotateLease,
   verifyAuditChain,
@@ -179,6 +180,12 @@ export interface BuiltinVaultAdapter extends VaultAdapter {
    * @param options - Limit / path filter
    */
   listAudit(options?: AuditPageOptions): Promise<readonly VaultAuditRecord[]>;
+  /**
+   * Load one audit row by id (operator-safe fields).
+   *
+   * @param id - Audit row id
+   */
+  readAuditRow(id: string): Promise<VaultAuditRecord | null>;
   /** Export every live secret as one bundle encrypted under the backup KEK. */
   exportBackup(): Promise<Uint8Array>;
   /**
@@ -1015,6 +1022,11 @@ export function createBuiltinVaultAdapter(opts: CreateBuiltinVaultOptions): Buil
       return readAuditPage(db, options ?? {});
     },
 
+    async readAuditRow(id: string): Promise<VaultAuditRecord | null> {
+      await ensureReady();
+      return readAuditRow(db, id);
+    },
+
     async exportBackup(): Promise<Uint8Array> {
       await ensureReady();
       const active = requireUnsealer();

package/src/elements/vault/chain.ts

@@ -1,34 +1,20 @@
 /**
- * Canonical vault compose-env path resolution — shared by app boot and Console.
- *
- * Compose credentials live at `docker/.env.docker`. Legacy project-root
- * `.env.docker` is consulted when absent (soft-compat).
+ * Canonical stack-env path — used to read compose credentials for driver
+ * open options (not a separate Vault resolution layer).
  */
 
-import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import type { VaultResolutionSource } from "./runtime.ts";
 
-/** Canonical relative path for compose stack credentials. */
-export const COMPOSE_ENV_REL = "docker/.env.docker";
+/** Canonical relative path for stack credentials (project `.env.local`). */
+export const COMPOSE_ENV_REL = ".env.local";
 
 /**
- * Resolve the compose-env path: prefer `docker/.env.docker`, then legacy
- * project-root `.env.docker`.
+ * Resolve the stack-env path (project `.env.local`).
  *
  * @param root - Project root
  */
 export function resolveComposeEnvPath(root: string): {
   readonly path: string;
-  readonly source: Extract<VaultResolutionSource, ".env.docker">;
 } {
-  const dockerPath = resolve(root, COMPOSE_ENV_REL);
-  if (existsSync(dockerPath)) {
-    return { path: dockerPath, source: ".env.docker" };
-  }
-  const legacyDocker = resolve(root, ".env.docker");
-  if (existsSync(legacyDocker)) {
-    return { path: legacyDocker, source: ".env.docker" };
-  }
-  return { path: dockerPath, source: ".env.docker" };
+  return { path: resolve(root, COMPOSE_ENV_REL) };
 }

package/src/elements/vault/declare.ts

@@ -10,7 +10,10 @@ import { requiredEnvRegistry, secretRegistry } from "../../kernel/element-regist
 export interface VaultSecretOptions {
   /** Human description shown in boot-gap listings. */
   readonly description?: string;
-  /** Rotation hint (`"90d"`, …). */
+  /**
+   * Rotation cadence (`"90d"`) or `"never"` when the secret must not
+   * rotate. Omit is the same as `"never"`.
+   */
   readonly rotate?: string;
   /** Optional schema validator (Standard Schema / zod / …). */
   readonly schema?: unknown;
@@ -264,7 +267,7 @@ export const vaultEnvApi: VaultEnvApi = Object.assign(envValue, {
 
 /**
  * Marker prefix for {@link vault.fromDocker} local fallbacks.
- * Resolved from `docker/.env.docker` by `oke dev --docker` / vault boot.
+ * Resolved from the compose stack env by `oke dev --docker` / vault boot.
  */
 export const FROM_DOCKER_PREFIX = "__oke_from_docker__:";
 

package/src/elements/vault/runtime.ts

@@ -34,14 +34,17 @@ export class VaultBootError extends Error {
 
 /**
  * Named layer in the resolution chain (console §9.8).
- * Spec order: process.env → .env.local → .env.docker → driver → dev-fallback.
+ * Spec order: driver → process.env → .env.local → dev-fallback.
  */
-export type VaultResolutionSource =
-  | "process.env"
-  | ".env.local"
-  | ".env.docker"
-  | "driver"
-  | "dev-fallback";
+export type VaultResolutionSource = "driver" | "process.env" | ".env.local" | "dev-fallback";
+
+/** Spec lock-path — first hit wins. */
+export const VAULT_RESOLUTION_ORDER: readonly VaultResolutionSource[] = [
+  "driver",
+  "process.env",
+  ".env.local",
+  "dev-fallback",
+];
 
 /** One layer in the resolution chain. */
 export interface VaultChainLayer {
@@ -85,6 +88,11 @@ export interface CreateVaultRuntimeOptions {
    * Never enable in production boot.
    */
   readonly allowDevFallbacks?: boolean;
+  /**
+   * When true, boot succeeds with missing contracts so Console can `put`
+   * the first value. App boot must leave this off.
+   */
+  readonly allowGaps?: boolean;
   /** Clock for last-read timestamps (tests). */
   readonly now?: () => number;
 }
@@ -245,7 +253,7 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
       }
     }
     gaps.push(...requiredEnvGaps(options.requiredEnv ?? [], new Set(contracts.keys())));
-    if (gaps.length > 0) {
+    if (gaps.length > 0 && options.allowGaps !== true) {
       throw new VaultBootError(gaps);
     }
 
@@ -281,7 +289,7 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
       if (!booted) {
         throw new Error(`vault: put("${name}") before boot`);
       }
-      const idx = bags.findIndex((b) => typeof b.set === "function");
+      const idx = writableBagIndex(bags, layerSources);
       if (idx < 0) {
         throw new Error("vault: no mutable bag for put()");
       }
@@ -355,7 +363,10 @@ export function createVaultRuntime(options: CreateVaultRuntimeOptions = {}): Vau
           won: winner === "dev-fallback",
         });
       }
-      return steps;
+      return [...steps].sort(
+        (a, b) =>
+          VAULT_RESOLUTION_ORDER.indexOf(a.source) - VAULT_RESOLUTION_ORDER.indexOf(b.source),
+      );
     },
     lastReadAt(name) {
       return lastReads.get(name);
@@ -410,6 +421,32 @@ export function requiredEnvGaps(
   return gaps;
 }
 
+/**
+ * Prefer a real backend bag; for `env` driver write `.env.local` so the
+ * front memory seed does not swallow Console / `oke vault set`.
+ *
+ * @param bags - Opened bags (same order as {@link layerSources})
+ * @param layerSources - Spec source id per bag
+ */
+function writableBagIndex(
+  bags: readonly VaultBag[],
+  layerSources: readonly VaultResolutionSource[],
+): number {
+  const hasEnvLayer = bags.some((b) => b.driverId === "env");
+  const driverIdx = layerSources.findIndex(
+    (source, i) => source === "driver" && typeof bags[i]?.set === "function",
+  );
+  const localIdx = layerSources.findIndex(
+    (source, i) => source === ".env.local" && typeof bags[i]?.set === "function",
+  );
+  const driverBag = driverIdx >= 0 ? bags[driverIdx] : undefined;
+  if (driverIdx >= 0 && !(hasEnvLayer && driverBag?.driverId === "memory")) {
+    return driverIdx;
+  }
+  if (localIdx >= 0) return localIdx;
+  return bags.findIndex((b) => typeof b.set === "function");
+}
+
 /**
  * Infer the Console source id for a chain layer.
  *
@@ -422,9 +459,6 @@ export function resolveLayerSource(layer: VaultChainLayer): VaultResolutionSourc
     if (path.endsWith(".env.local") || path.includes("/.env.local")) {
       return ".env.local";
     }
-    if (path.endsWith(".env.docker") || path.includes("/.env.docker")) {
-      return ".env.docker";
-    }
   }
   if (layer.driver.id === "env" && path === undefined) {
     return "process.env";

package/src/elements/vault/storage.ts

@@ -338,7 +338,33 @@ export async function readAuditPage(
     throw new VaultError("BACKEND_ERROR", "vault: failed to read audit rows");
   }
 
-  return rows.map((row) => ({
+  return rows.map((row) => toAuditRecord(row));
+}
+
+/**
+ * Load one audit row by id (operator-safe fields, no chain hashes).
+ *
+ * @param db - SQL surface
+ * @param id - Audit row id
+ */
+export async function readAuditRow(db: SqlExec, id: string): Promise<VaultAuditRecord | null> {
+  let rows: (AuditDbRow & { seq: number | string | bigint })[];
+  try {
+    rows = await db.query(
+      `SELECT id, seq, action, path, actor_type, actor_id, success, error_code, error_message,
+              request_id, prev_hash, row_hash, created_at
+       FROM oke_vault_audit WHERE id = $1`,
+      [id],
+    );
+  } catch {
+    throw new VaultError("BACKEND_ERROR", "vault: failed to read audit row");
+  }
+  const row = rows[0];
+  return row === undefined ? null : toAuditRecord(row);
+}
+
+function toAuditRecord(row: AuditDbRow & { seq: number | string | bigint }): VaultAuditRecord {
+  return {
     id: row.id,
     seq: typeof row.seq === "number" ? row.seq : Number(row.seq),
     action: row.action as AuditAction,
@@ -350,15 +376,20 @@ export async function readAuditPage(
     errorMessage: row.error_message,
     requestId: row.request_id,
     createdAt: row.created_at instanceof Date ? row.created_at : new Date(row.created_at),
-  }));
+  };
 }
 
+/** Why {@link verifyAuditChain} rejected a row. */
+export type AuditChainBreakReason = "link" | "payload";
+
 /** Result of {@link verifyAuditChain}. */
 export interface AuditChainResult {
   /** Whether every retained row hashes and links correctly. */
   readonly ok: boolean;
   /** Id of the first row that failed verification. */
   readonly brokenAt?: string;
+  /** `link` = prev_hash mismatch; `payload` = stored row_hash ≠ recomputed. */
+  readonly reason?: AuditChainBreakReason;
 }
 
 /** Raw `oke_vault_audit` row shape. */
@@ -404,7 +435,7 @@ export async function verifyAuditChain(db: SqlExec): Promise<AuditChainResult> {
   let previousHash: string | undefined;
   for (const row of rows) {
     if (previousHash !== undefined && row.prev_hash !== previousHash) {
-      return { ok: false, brokenAt: row.id };
+      return { ok: false, brokenAt: row.id, reason: "link" };
     }
     const expected = await computeAuditRowHash(row.prev_hash, {
       action: row.action as AuditAction,
@@ -418,7 +449,7 @@ export async function verifyAuditChain(db: SqlExec): Promise<AuditChainResult> {
       createdAt: toIso(row.created_at),
     });
     if (expected !== row.row_hash) {
-      return { ok: false, brokenAt: row.id };
+      return { ok: false, brokenAt: row.id, reason: "payload" };
     }
     previousHash = row.row_hash;
   }

package/src/elements/vault.test.ts

@@ -126,6 +126,7 @@ describe("resolution chain", () => {
     expect(runtime.read("KEY")).toBe("from-a");
     expect(runtime.resolution("KEY")).toBe("process.env");
     const chain = runtime.resolutionChain("KEY");
+    expect(chain.map((s) => s.source)).toEqual(["driver", "process.env"]);
     expect(chain.find((s) => s.source === "process.env")?.won).toBe(true);
     expect(chain.find((s) => s.source === "driver")?.present).toBe(true);
     expect(chain.find((s) => s.source === "driver")?.won).toBe(false);

package/src/elements/vault.ts

@@ -97,11 +97,13 @@ export {
   purgeAuditBefore,
   purgeExpiredSecrets,
   readAuditPage,
+  readAuditRow,
   releaseRotateLease,
   verifyAuditChain,
   VAULT_DDL_STATEMENTS,
 } from "./vault/storage.ts";
 export type {
+  AuditChainBreakReason,
   AuditChainResult,
   AuditPageOptions,
   PurgeExpiredResult,

package/src/full.ts

@@ -64,6 +64,8 @@ export {
   defineSeed,
   normalizeSeedFns,
   resolveSeedCategory,
+  resolveSeedIdentity,
+  seedPromptMessage,
   createStoreRuntime,
   type StoreDecl,
   type StoreRuntime,
@@ -74,6 +76,7 @@ export {
   type SeedDef,
   type SeedFn,
   type SeedFns,
+  type SeedIdentity,
   type SeedCategory,
   type UpsertResult,
   type UpsertStatus,
@@ -240,9 +243,16 @@ export {
   memoryRunsDriver,
   postgresRunsDriver,
   clickhouseRunsDriver,
+  wrapRunsForConsoleIngest,
+  resolveRunsConsoleBridge,
+  RUNS_INGEST_SECRET_HEADER,
+  RUNS_INGEST_URL_ENV,
+  RUNS_INGEST_SECRET_ENV,
   type RunsRuntime,
   type WideEvent,
   type CreateRunsRuntimeOptions,
+  type RunsConsoleBridgeFetch,
+  type RunsConsoleBridgeTarget,
   type OutlierFinding,
   type SubjectKeyVault,
 } from "./runs/index.ts";

package/src/http.ts

@@ -8,7 +8,7 @@
  * ```ts
  * import { on, flow, http, gate, oke, createBunRuntime } from "okengine/http";
  *
- * on(http.get("/").gate(gate.public), flow("ping", { do: () => "Hi" }));
+ * on(http.get("/").gate.public, flow("ping", { do: () => "Hi" }));
  * const app = oke({ name: "ping" });
  * createBunRuntime().serve(app);
  * ```

package/src/index.ts

@@ -47,6 +47,8 @@ export {
   defineSeed,
   normalizeSeedFns,
   resolveSeedCategory,
+  resolveSeedIdentity,
+  seedPromptMessage,
   createStoreRuntime,
   type StoreDecl,
   type StoreRuntime,
@@ -57,6 +59,7 @@ export {
   type SeedDef,
   type SeedFn,
   type SeedFns,
+  type SeedIdentity,
   type SeedCategory,
   type UpsertResult,
   type UpsertStatus,
@@ -87,7 +90,12 @@ export {
 export {
   gate,
   GATE_PUBLIC_NAME,
+  flattenGateArgs,
+  flattenGateMembers,
+  isGateAllDecl,
+  type GateAllDecl,
   type GateDecl,
+  type GateMember,
   type RateOptions,
 } from "./elements/gate/declare.ts";
 export {

package/src/kernel/adopt-barrel-fresh.test.ts

@@ -12,7 +12,6 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { gate } from "../elements/gate.ts";
 import { assertAdoptBarrelFresh, resetStaleAdoptBarrelWarnForTests } from "./boot.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
 import { on, resetBindings } from "./on.ts";
@@ -90,7 +89,7 @@ describe("boot-level: stale barrel through a real oke() boot", () => {
         effects: {},
         do: () => ({ ok: true as const }),
       });
-      on(http.get("/health").gate(gate.public), mainFlow);
+      on(http.get("/health").gate.public, mainFlow);
       const app = oke({ name: "stale-barrel", gate: { unguardedHttp: "allow" } });
 
       await expect(

package/src/kernel/app-auth.ts

@@ -11,7 +11,12 @@ import { createAuthHttpBindings, type AuthHttpMaterialization } from "../auth/bi
 import { tokenFromCookieHeader } from "../auth/cookies.ts";
 import { setActiveGateAuthContext } from "../auth/method-context.ts";
 import type { ResolvedGateConfig } from "../elements/gate/config.ts";
-import { createAppAuthBinding, verifyBearerToken, type AppAuthBinding } from "./auth-resolve.ts";
+import {
+  createAppAuthBinding,
+  verifyBearerOrApiKey,
+  verifyBearerToken,
+  type AppAuthBinding,
+} from "./auth-resolve.ts";
 import type { PluginDef } from "./plugin.ts";
 
 /** Result of wiring Gate auth at construction. */
@@ -20,6 +25,7 @@ export interface WiredGateAuth {
   readonly authPlugin: PluginDef | undefined;
   readonly authBinding: AppAuthBinding;
   readonly verifyBearerToken: typeof verifyBearerToken;
+  readonly verifyBearerOrApiKey: typeof verifyBearerOrApiKey;
   readonly tokenFromCookieHeader: typeof tokenFromCookieHeader;
   /** Rebuild binding when boot supplies a clock. */
   rebind(now: () => number): AppAuthBinding;
@@ -85,6 +91,7 @@ export function wireGateAuth(options: WireGateAuthOptions): WiredGateAuth {
     authPlugin: pluginDef,
     authBinding,
     verifyBearerToken,
+    verifyBearerOrApiKey,
     tokenFromCookieHeader,
     rebind(now) {
       authBinding = createAppAuthBinding({