okengine 0.10.3 → 0.11.0

package/src/elements/store/schema-decl.test.ts

@@ -56,7 +56,7 @@ describe("store.schema.table + field.*", () => {
     const decl = store.sql("notes", { schema: { notes } });
     const runtime = createStoreRuntime({
       drivers: {},
-      sql: { notes: { name: "notes", primary: { url: ":memory:" } } },
+      sql: { notes: { name: "notes", primary: {} } },
     });
     // Register so classificationsFor merges table columns.
     runtime.register(decl);
@@ -68,10 +68,10 @@ describe("store.schema.table + field.*", () => {
     expect(masked[0]!.email).toBe(PII_MASK);
 
     // Runtime path: open handle and query — ensure classificationsFromTable feeds mask.
-    const { sqliteDriver } = await import("../../drivers/index.ts");
+    const { memorySqlDriver } = await import("../../drivers/index.ts");
     const rt = createStoreRuntime({
-      drivers: { sql: sqliteDriver },
-      sql: { notes: { name: "notes", primary: { url: ":memory:" } } },
+      drivers: { sql: memorySqlDriver },
+      sql: { notes: { name: "notes", primary: {} } },
     });
     rt.register(decl);
     const handle = (await rt.open(decl, {
@@ -84,7 +84,7 @@ describe("store.schema.table + field.*", () => {
   });
 });
 
-describe("emitDrizzleSource — both dialects from one declaration", () => {
+describe("emitDrizzleSource — postgres pgTable from one declaration", () => {
   const notes = store.schema.table("notes", {
     id: field.text().primaryKey().defaultFn(id),
     title: field.text().notNull(),
@@ -92,24 +92,17 @@ describe("emitDrizzleSource — both dialects from one declaration", () => {
     createdAt: field.integer().notNull().defaultFn(now),
   });
 
-  test("sqlite emits sqliteTable", () => {
-    const src = emitDrizzleSource([notes], "sqlite");
-    expect(src.startsWith(GENERATED_SCHEMA_HEADER)).toBe(true);
-    expect(src).toContain('from "drizzle-orm/sqlite-core"');
-    expect(src).toContain("sqliteTable");
-    expect(src).not.toContain("pgTable");
-    expect(src).toContain('text("id").primaryKey().$defaultFn(id)');
-    expect(src).toContain('integer("created_at").notNull().$defaultFn(now)');
-    expect(src).toContain('text("body").notNull()');
-  });
-
-  test("postgres emits pgTable from the same decl", () => {
+  test("postgres emits pgTable", () => {
     const src = emitDrizzleSource([notes], "postgres");
+    expect(src.startsWith(GENERATED_SCHEMA_HEADER)).toBe(true);
     expect(src).toContain('from "drizzle-orm/pg-core"');
     expect(src).toContain("pgTable");
     expect(src).not.toContain("sqliteTable");
+    expect(src).not.toContain("drizzle-orm/sqlite-core");
     expect(src).toContain('text("id").primaryKey().$defaultFn(id)');
-    expect(src).toContain('integer("created_at").notNull().$defaultFn(now)');
+    // Postgres INTEGER is 32-bit — abstract integer maps to bigint for ms clocks.
+    expect(src).toContain('bigint("created_at", { mode: "number" }).notNull().$defaultFn(now)');
+    expect(src).toContain('text("body").notNull()');
   });
 });
 
@@ -142,9 +135,9 @@ describe("plugin table columns in generated schema", () => {
     expect(pluginTables[0]!.columns.actorId!.classification?.pii).toBe(true);
 
     const merged = mergeSchemaTables([notes], pluginTables);
-    const src = emitDrizzleSource(merged, "sqlite");
-    expect(src).toContain('sqliteTable("notes"');
-    expect(src).toContain('sqliteTable("audit_events"');
+    const src = emitDrizzleSource(merged, "postgres");
+    expect(src).toContain('pgTable("notes"');
+    expect(src).toContain('pgTable("audit_events"');
     expect(src).toContain('text("actor_id").notNull()');
   });
 
@@ -195,21 +188,12 @@ describe("emitDrizzleSource — references + relations (Linkly-shaped)", () => {
     },
   }));
 
-  test("sqlite emit includes FK + defineRelations", () => {
-    const src = emitDrizzleSource([links, daily], "sqlite", { relations: [relations] });
-    expect(src).toContain("sqliteTable");
-    expect(src).toContain(".references(() => links.code)");
-    expect(src).toContain('import { defineRelations } from "drizzle-orm"');
-    expect(src).toContain("defineRelations({ links, daily }");
-    expect(src).toContain("r.many.daily({ from: r.links.code, to: r.daily.code })");
-    expect(src).toContain("r.one.links({ from: r.daily.code, to: r.links.code, optional: false })");
-  });
-
-  test("postgres emit includes same FK + defineRelations from one decl", () => {
+  test("postgres emit includes FK + defineRelations", () => {
     const src = emitDrizzleSource([links, daily], "postgres", { relations: [relations] });
     expect(src).toContain("pgTable");
     expect(src).not.toContain("sqliteTable");
     expect(src).toContain(".references(() => links.code)");
+    expect(src).toContain('import { defineRelations } from "drizzle-orm"');
     expect(src).toContain("defineRelations({ links, daily }");
     expect(src).toContain("r.many.daily({ from: r.links.code, to: r.daily.code })");
     expect(src).toContain("r.one.links({ from: r.daily.code, to: r.links.code, optional: false })");

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

@@ -19,8 +19,7 @@ describe("defineSeed / resolveSeedCategory", () => {
   });
 
   test("resolveSeedCategory matches the env matrix", () => {
-    expect(resolveSeedCategory("local")).toBe("dev");
-    expect(resolveSeedCategory("docker")).toBe("dev");
+    expect(resolveSeedCategory("dev")).toBe("dev");
     expect(resolveSeedCategory("prod")).toBe("prod");
     expect(resolveSeedCategory("test")).toBe(null);
   });

package/src/elements/store/seed.ts

@@ -17,7 +17,7 @@ export type SeedFns = SeedFn | readonly SeedFn[];
  * Seed categories for {@link defineSeed}.
  *
  * - `essential` — every environment, always
- * - `dev` — `local` or `docker` only
+ * - `dev` — `dev` ConfigEnv only (Docker Compose laptop)
  * - `prod` — `prod` only
  */
 export interface SeedDef {
@@ -52,17 +52,16 @@ export function normalizeSeedFns(fns?: SeedFns): SeedFn[] {
 /**
  * Which optional category runs for `env` (single source of truth).
  *
- * | env    | category |
- * | ------ | -------- |
- * | local  | dev      |
- * | docker | dev      |
- * | test   | (none)   |
- * | prod   | prod     |
+ * | env  | category |
+ * | ---- | -------- |
+ * | dev  | dev      |
+ * | test | (none)   |
+ * | prod | prod     |
  *
  * @param env - Resolved {@link ConfigEnv}
  */
 export function resolveSeedCategory(env: ConfigEnv): SeedCategory | null {
-  if (env === "local" || env === "docker") return "dev";
+  if (env === "dev") return "dev";
   if (env === "prod") return "prod";
   return null;
 }

package/src/elements/store/sql-condition.test.ts

@@ -20,10 +20,10 @@ import {
   or,
   sql,
 } from "drizzle-orm";
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { integer, pgTable, text } from "drizzle-orm/pg-core";
 import { compileOrderBy, compileWhere } from "./sql-condition.ts";
 
-const notes = sqliteTable("notes", {
+const notes = pgTable("notes", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
   createdAt: integer("created_at").notNull(),

package/src/elements/store/sql-session.test.ts

@@ -7,22 +7,21 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { Database } from "bun:sqlite";
 import { and, desc, eq, like, lt, or } from "drizzle-orm";
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
-import { sqliteDriver } from "../../drivers/sqlite.ts";
+import { integer, pgTable, text } from "drizzle-orm/pg-core";
+import { pgliteDriver } from "../../drivers/pglite.ts";
 import type { SqlConnection } from "../../drivers/types.ts";
 import { createSqlStoreHandle, type SqlStoreHandle } from "./sql-session.ts";
 
-const posts = sqliteTable("posts", {
+const posts = pgTable("posts", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
   createdAt: integer("created_at").notNull(),
 });
 
 async function openHandle(): Promise<{ handle: SqlStoreHandle; conn: SqlConnection }> {
-  const conn = await sqliteDriver.connect({
-    client: new Database(":memory:"),
+  const conn = await pgliteDriver.connect({
+    url: "memory://",
     role: "primary",
   });
   const handle = createSqlStoreHandle("sql:app", {
@@ -36,8 +35,7 @@ async function openHandle(): Promise<{ handle: SqlStoreHandle; conn: SqlConnecti
 
 describe("SqlStoreHandle — no relational query surface (path b)", () => {
   test("created handle exposes exactly the single-table surface", async () => {
-    const db = new Database(":memory:");
-    const conn = await sqliteDriver.connect({ client: db, role: "primary" });
+    const conn = await pgliteDriver.connect({ url: "memory://", role: "primary" });
     const handle = createSqlStoreHandle("sql:app", {
       connection: conn,
       classifications: new Map(),
@@ -124,12 +122,12 @@ describe("SqlStoreHandle — orderBy / limit select chain", () => {
     await conn.close();
   });
 
-  test("like filters rows through the session (sqlite ASCII-insensitive)", async () => {
+  test("like filters rows through the session (postgres case-sensitive)", async () => {
     const { handle, conn } = await openHandle();
     await handle.insert(posts).values({ id: "p1", title: "alpha", createdAt: 100 });
     await handle.insert(posts).values({ id: "p2", title: "bravo", createdAt: 200 });
 
-    const rows = await handle.select().from(posts).where(like(posts.title, "A%"));
+    const rows = await handle.select().from(posts).where(like(posts.title, "a%"));
     expect(rows.map((r) => r.id)).toEqual(["p1"]);
     await conn.close();
   });

package/src/elements/store/sql-session.ts

@@ -363,9 +363,13 @@ export function createSqlStoreHandle(
     if (cols.length === 0) return;
     const name = resolveTableName(table);
     const pk = cols.find((c) => c.primary)?.sqlName;
+    // Postgres/PGLite INTEGER is 32-bit — abstract `integer` (ms timestamps via
+    // `now`) must map to BIGINT. SQLite INTEGER is flexible up to 64-bit.
+    const pgWideInt = connection.driverId === "postgres" || connection.driverId === "pglite";
     const colSql = cols
       .map((c) => {
-        const typ = pk && c.sqlName === pk ? `${c.sqlType} PRIMARY KEY` : c.sqlType;
+        const base = pgWideInt && c.sqlType === "INTEGER" ? "BIGINT" : c.sqlType;
+        const typ = pk && c.sqlName === pk ? `${base} PRIMARY KEY` : base;
         return `${quoteIdent(c.sqlName)} ${typ}`;
       })
       .join(", ");
@@ -734,6 +738,10 @@ export function createSqlStoreHandle(
     async ensureTable(table) {
       const cols = Object.values(table.columns);
       const pk = resolvePkColumn(table);
+      const intType =
+        connection.driverId === "postgres" || connection.driverId === "pglite"
+          ? "BIGINT"
+          : "INTEGER";
       const colSql = cols
         .map((c) => {
           const typ =
@@ -743,7 +751,7 @@ export function createSqlStoreHandle(
                   c.name === "qty" ||
                   c.name === "createdAt" ||
                   c.name === "created_at"
-                ? "INTEGER"
+                ? intType
                 : "TEXT";
           return `${quoteIdent(c.name)} ${typ}`;
         })

package/src/elements/store.test.ts

@@ -1,13 +1,13 @@
 /**
  * Store element acceptance:
- * - same flow runs unchanged against sqlite and postgres
+ * - same flow runs unchanged against memory and postgres
  * - read-only flow provably hits a replica
  * - auto-invalidation fires on exactly the writes touching the read's keys
  * - SELECT * masks classified columns
  */
 
 import { describe, expect, test } from "bun:test";
-import { createPostgresFakeClient, postgresDriver, sqliteDriver } from "../drivers/index.ts";
+import { createPostgresFakeClient, memorySqlDriver, postgresDriver } from "../drivers/index.ts";
 import type { Effects } from "../manifest/types.ts";
 import {
   classify,
@@ -73,7 +73,7 @@ describe("store facets", () => {
   });
 });
 
-describe("same flow against sqlite and postgres", () => {
+describe("same flow against memory and postgres", () => {
   test("insert / select / findById unchanged across drivers", async () => {
     const decl = store.sql("notes", {
       schema: { notes },
@@ -81,7 +81,7 @@ describe("same flow against sqlite and postgres", () => {
     });
 
     for (const [label, driver, client] of [
-      ["sqlite", sqliteDriver, undefined],
+      ["memory", memorySqlDriver, undefined],
       ["postgres", postgresDriver, createPostgresFakeClient()],
     ] as const) {
       const runtime = createStoreRuntime({
@@ -89,7 +89,7 @@ describe("same flow against sqlite and postgres", () => {
         sql: {
           notes: {
             name: "notes",
-            primary: { url: ":memory:", client },
+            primary: { client },
           },
         },
       });
@@ -218,8 +218,8 @@ describe("tier-1 cache invalidation from effects", () => {
 
   test("runtime putTier1 + onWriteEffects", async () => {
     const runtime = createStoreRuntime({
-      drivers: { sql: sqliteDriver },
-      sql: { notes: { name: "notes", primary: { url: ":memory:" } } },
+      drivers: { sql: memorySqlDriver },
+      sql: { notes: { name: "notes", primary: {} } },
     });
     const keys = runtime.putTier1({ reads: ["sql:notes"] }, ["cached"]);
     expect(runtime.cache.get<string[]>(keys[0]!)).toEqual(["cached"]);
@@ -237,7 +237,7 @@ describe("exists and increment helpers", () => {
 
   test("exists returns correctly for present / absent rows across sqlite and postgres", async () => {
     for (const [label, driver, client] of [
-      ["sqlite", sqliteDriver, undefined],
+      ["memory", memorySqlDriver, undefined],
       ["postgres", postgresDriver, createPostgresFakeClient()],
     ] as const) {
       const decl = store.sql("counters");
@@ -246,7 +246,7 @@ describe("exists and increment helpers", () => {
         sql: {
           counters: {
             name: "counters",
-            primary: { url: ":memory:", client },
+            primary: { client },
           },
         },
       });
@@ -267,7 +267,7 @@ describe("exists and increment helpers", () => {
 
   test("increment under 100 concurrent callers lands on the correct final value", async () => {
     for (const [label, driver, client] of [
-      ["sqlite", sqliteDriver, undefined],
+      ["memory", memorySqlDriver, undefined],
       ["postgres", postgresDriver, createPostgresFakeClient()],
     ] as const) {
       const decl = store.sql("counters");
@@ -276,7 +276,7 @@ describe("exists and increment helpers", () => {
         sql: {
           counters: {
             name: "counters",
-            primary: { url: ":memory:", client },
+            primary: { client },
           },
         },
       });
@@ -308,8 +308,8 @@ describe("PII masking at the driver boundary", () => {
       classify: { notes: { email: classify({ pii: true }) } },
     });
     const runtime = createStoreRuntime({
-      drivers: { sql: sqliteDriver },
-      sql: { notes: { name: "notes", primary: { url: ":memory:" } } },
+      drivers: { sql: memorySqlDriver },
+      sql: { notes: { name: "notes", primary: {} } },
     });
     runtime.register(decl);
     const handle = asSql(

package/src/elements/vault/audit.ts

@@ -0,0 +1,233 @@
+/**
+ * Vault audit trail — a tamper-evident hash chain of *operations*.
+ *
+ * An audit row records that something happened to a path, never what the
+ * value was. Each row hashes its own payload together with the previous
+ * row's hash, so removing or editing a row breaks every hash after it
+ * (`verifyAuditChain` in `storage.ts` walks the chain).
+ */
+
+import { VaultError } from "./errors.ts";
+import type { VaultErrorCode } from "./errors.ts";
+import type { VaultActorType } from "./types.ts";
+import type { VaultAuditSinkKind } from "./types.ts";
+
+/** Operations recorded in the audit chain. */
+export type AuditAction =
+  | "get"
+  | "set"
+  | "delete"
+  | "rotate"
+  | "list"
+  | "seal"
+  | "unseal"
+  | "initialize"
+  | "rewrap"
+  | "purge";
+
+/** Hash-chain genesis marker used for the first row. */
+export const AUDIT_GENESIS_HASH = "genesis";
+
+/** One operation to append to the chain. */
+export interface AuditEntry {
+  /** What happened. */
+  readonly action: AuditAction;
+  /** Canonical path, when the operation targets one. */
+  readonly path?: string;
+  /** Actor class. */
+  readonly actorType: VaultActorType;
+  /** Actor id within its class. */
+  readonly actorId?: string;
+  /** Whether the operation succeeded. */
+  readonly success: boolean;
+  /** Failure reason when `success` is `false`. */
+  readonly errorCode?: VaultErrorCode;
+  /** Safe, secret-free failure description. */
+  readonly errorMessage?: string;
+  /** Correlation id for the enclosing request/run. */
+  readonly requestId?: string;
+  /** Event time. Defaults to now at append time. */
+  readonly at?: Date;
+}
+
+/**
+ * Exact field set covered by a row hash.
+ *
+ * Normalized (`null` rather than `undefined`, ISO-8601 timestamps) so a row
+ * read back from SQL hashes identically to the row that was written.
+ */
+export interface AuditHashPayload {
+  /** What happened. */
+  readonly action: AuditAction;
+  /** Canonical path or `null`. */
+  readonly path: string | null;
+  /** Actor class. */
+  readonly actorType: VaultActorType;
+  /** Actor id or `null`. */
+  readonly actorId: string | null;
+  /** Whether the operation succeeded. */
+  readonly success: boolean;
+  /** Failure reason or `null`. */
+  readonly errorCode: VaultErrorCode | null;
+  /** Failure description or `null`. */
+  readonly errorMessage: string | null;
+  /** Correlation id or `null`. */
+  readonly requestId: string | null;
+  /** ISO-8601 event time. */
+  readonly createdAt: string;
+}
+
+/** Destination for audit rows. */
+export interface AuditSink {
+  /** Sink kind, mirroring the configured `audit.sink`. */
+  readonly kind: VaultAuditSinkKind;
+  /**
+   * Append one operation.
+   *
+   * @param entry - Operation to record
+   */
+  append(entry: AuditEntry): Promise<void>;
+  /** Release sink resources, if any. */
+  close?(): Promise<void>;
+}
+
+/**
+ * Backend-side audit writer.
+ *
+ * `storage.ts` implements this over `oke_vault_audit`; the `db` sink is a
+ * thin adapter so the audit module never imports SQL.
+ */
+export interface AuditWriter {
+  /**
+   * Persist one operation, computing and linking its row hash.
+   *
+   * @param entry - Operation to record
+   */
+  appendAuditEntry(entry: AuditEntry): Promise<void>;
+}
+
+/** Options accepted by {@link createAuditSink}. */
+export interface CreateAuditSinkOptions {
+  /** Required for the `db` sink. */
+  readonly writer?: AuditWriter;
+  /** Required for the `webhook` sink (not yet implemented). */
+  readonly webhookUrl?: string;
+  /** Line writer for the `stdout` sink (tests). */
+  readonly write?: (line: string) => void;
+  /** Clock for `stdout` timestamps (tests). */
+  readonly now?: () => Date;
+}
+
+/**
+ * Normalize an entry into the exact fields a row hash covers.
+ *
+ * @param entry - Operation to record
+ * @param createdAt - Event time
+ */
+export function toAuditHashPayload(entry: AuditEntry, createdAt: Date): AuditHashPayload {
+  return {
+    action: entry.action,
+    path: entry.path ?? null,
+    actorType: entry.actorType,
+    actorId: entry.actorId ?? null,
+    success: entry.success,
+    errorCode: entry.errorCode ?? null,
+    errorMessage: entry.errorMessage ?? null,
+    requestId: entry.requestId ?? null,
+    createdAt: createdAt.toISOString(),
+  };
+}
+
+/**
+ * Hash one audit row into the chain.
+ *
+ * Fields are joined with NUL in a fixed order — no JSON key-order or
+ * whitespace ambiguity — and prefixed with the previous row's hash.
+ *
+ * @param prevHash - Previous row hash, or `null` / {@link AUDIT_GENESIS_HASH} for the first row
+ * @param payload - Normalized row fields
+ * @returns Lowercase hex SHA-256 digest
+ */
+export async function computeAuditRowHash(
+  prevHash: string | null,
+  payload: AuditHashPayload,
+): Promise<string> {
+  const parts = [
+    "oke-vault-audit-v1",
+    prevHash ?? AUDIT_GENESIS_HASH,
+    payload.action,
+    payload.path ?? "",
+    payload.actorType,
+    payload.actorId ?? "",
+    payload.success ? "1" : "0",
+    payload.errorCode ?? "",
+    payload.errorMessage ?? "",
+    payload.requestId ?? "",
+    payload.createdAt,
+  ];
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(parts.join("\0")));
+  return Buffer.from(new Uint8Array(digest)).toString("hex");
+}
+
+/**
+ * Build an audit sink.
+ *
+ * - `db` delegates to an {@link AuditWriter} supplied by storage.
+ * - `stdout` writes one secret-free JSON line per operation.
+ * - `webhook` is not implemented yet and throws `UNSUPPORTED`.
+ *
+ * @param kind - Sink kind from `audit.sink`
+ * @param opts - Writer / webhook URL / test seams
+ * @throws VaultError `UNSUPPORTED` for `webhook`, or `MISSING_PEER` when `db` has no writer
+ */
+export function createAuditSink(
+  kind: VaultAuditSinkKind,
+  opts: CreateAuditSinkOptions = {},
+): AuditSink {
+  if (kind === "webhook") {
+    throw new VaultError("UNSUPPORTED", "vault: webhook audit sink is not implemented");
+  }
+
+  if (kind === "db") {
+    const writer = opts.writer;
+    if (!writer) {
+      throw new VaultError("MISSING_PEER", "vault: db audit sink requires a storage writer");
+    }
+    return {
+      kind: "db",
+      append(entry) {
+        return writer.appendAuditEntry(entry);
+      },
+    };
+  }
+
+  const write = opts.write ?? ((line: string) => void process.stdout.write(`${line}\n`));
+  const now = opts.now ?? (() => new Date());
+  return {
+    kind: "stdout",
+    async append(entry) {
+      // Only normalized metadata is serialized — an entry never holds a value.
+      write(
+        JSON.stringify({
+          sink: "oke.vault.audit",
+          ...toAuditHashPayload(entry, entry.at ?? now()),
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Sink that drops every entry (`audit.enabled: false`).
+ *
+ * Reports `kind: "stdout"` because {@link VaultAuditSinkKind} has no
+ * "off" member — callers gate on config, not on this field.
+ */
+export function createNullAuditSink(): AuditSink {
+  return {
+    kind: "stdout",
+    async append() {
+      // Intentionally empty — auditing is disabled.
+    },
+  };
+}

package/src/elements/vault/boot-chain.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Vault boot chain — managed provider wiring and driver-id normalization.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import type { VaultOpenOptions } from "../../drivers/vault-types.ts";
+import { buildVaultBootChain, normalizeVaultDriverId } from "./boot-chain.ts";
+
+/** Env keys these tests own. */
+const OWNED = [
+  "OKE_VAULT_PROVIDER",
+  "OKE_VAULT_URL",
+  "OKE_VAULT_TOKEN",
+  "OKE_VAULT_MOUNT",
+  "OKE_VAULT_REGION",
+] as const;
+
+afterEach(() => {
+  for (const key of OWNED) delete process.env[key];
+});
+
+describe("managed vault boot chain", () => {
+  test("no provider stays a single platform-injected layer", () => {
+    const chain = buildVaultBootChain({ driverId: "managed", env: "test", seed: { A: "1" } });
+    expect(chain).toHaveLength(1);
+    expect(chain[0]?.driver.id).toBe("managed");
+  });
+
+  test("a provider puts the env layers in front of the managed layer", () => {
+    process.env.OKE_VAULT_PROVIDER = "aws-secrets-manager";
+    process.env.OKE_VAULT_REGION = "eu-central-1";
+    process.env.OKE_VAULT_MOUNT = "oke/prod/";
+
+    const chain = buildVaultBootChain({ driverId: "managed", env: "prod" });
+    expect(chain[0]?.driver.id).toBe("env");
+    const last = chain.at(-1);
+    expect(last?.driver.id).toBe("managed");
+    const options = last?.options as VaultOpenOptions;
+    expect(options.provider).toBe("aws-secrets-manager");
+    expect(options.region).toBe("eu-central-1");
+    expect(options.mount).toBe("oke/prod/");
+  });
+
+  test("aws-secrets-manager carries region and prefix without inventing a mount", () => {
+    process.env.OKE_VAULT_PROVIDER = "aws-secrets-manager";
+    process.env.OKE_VAULT_REGION = "eu-central-1";
+
+    const chain = buildVaultBootChain({ driverId: "managed", env: "prod" });
+    const options = chain.at(-1)?.options as VaultOpenOptions;
+    expect(options.region).toBe("eu-central-1");
+    expect(options.mount).toBeUndefined();
+  });
+
+  test("built-in vault sits behind env layers", () => {
+    const chain = buildVaultBootChain({ driverId: "vault", env: "prod" });
+    expect(chain.map((l) => l.driver.id)).toContain("env");
+    expect(chain.at(-1)?.driver.id).toBe("vault");
+  });
+});
+
+describe("normalizeVaultDriverId", () => {
+  test("maps legacy labels onto protocol ids", () => {
+    expect(normalizeVaultDriverId("dotenv")).toBe("env");
+    expect(normalizeVaultDriverId("builtin")).toBe("vault");
+    expect(normalizeVaultDriverId("managed")).toBe("managed");
+    expect(normalizeVaultDriverId("vault")).toBe("vault");
+  });
+
+  test("rejects an unknown label", () => {
+    expect(() => normalizeVaultDriverId("acme")).toThrow(/unknown vault driver/);
+  });
+
+  test("rejects removed external vault driver id", () => {
+    const removed = ["open", "bao"].join("");
+    expect(() => normalizeVaultDriverId(removed)).toThrow(/unknown vault driver/);
+    expect(() => normalizeVaultDriverId(removed)).toThrow(/aws-secrets-manager/);
+  });
+});