@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/table-builder.ts

@@ -1,3 +1,4 @@
+import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type {
   EntityDefinition,
   EntityRelations,
@@ -15,6 +16,7 @@ import {
   type ColumnBuilder,
   type ColumnHandle,
   decimalColumn,
+  doublePrecision,
   type IndexBuilderWithCols,
   index,
   instant,
@@ -69,7 +71,13 @@ function fieldToColumns(
       const base = text(snakeName);
       const withDefault =
         "default" in field && field.default !== undefined ? base.default(field.default) : base;
-      return { [name]: field.required ? withDefault.notNull() : withDefault };
+      const mainCol = { [name]: field.required ? withDefault.notNull() : withDefault };
+      // lookupable → nullable HMAC-Blind-Index-Spalte (lock-step mit
+      // fieldToColumnMeta in entity-table-meta.ts).
+      if (field.type === "text" && field.lookupable === true) {
+        return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
+      }
+      return mainCol;
     }
     case "boolean":
       return {
@@ -101,7 +109,7 @@ function fieldToColumns(
       // multi-select.
       return { [name]: jsonb(snakeName).default([]).notNull() };
     case "number": {
-      const base = integer(snakeName);
+      const base = field.integer === true ? integer(snakeName) : doublePrecision(snakeName);
       const col = field.default !== undefined ? base.default(field.default) : base;
       return { [name]: field.required ? col.notNull() : col };
     }
@@ -272,63 +280,72 @@ type NullCol<_T> = ColumnHandle & { readonly __notNull: false };
 // columns (resolved via FileRef table). `notNull` propagiert von
 // `field.required` (literal preserved by createXField generics).
 type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
-  type: "text" | "select" | "tz";
+  type: "text";
+  lookupable: true;
 }
-  ? F extends { required: true }
-    ? { readonly [P in K]: Col<string> }
-    : { readonly [P in K]: NullCol<string> }
-  : F extends { type: "boolean" }
-    ? // boolean default OR required → notNull (DB has DEFAULT, structurally never-null)
-      F extends { default: boolean } | { required: true }
-      ? { readonly [P in K]: Col<boolean> }
-      : { readonly [P in K]: NullCol<boolean> }
-    : F extends { type: "multiSelect" }
-      ? // jsonb default `[]`, immer notNull
-        { readonly [P in K]: Col<readonly string[]> }
-      : F extends { type: "number" }
-        ? F extends { required: true }
-          ? { readonly [P in K]: Col<number> }
-          : { readonly [P in K]: NullCol<number> }
-        : F extends { type: "decimal" }
+  ? (F extends { required: true }
+      ? { readonly [P in K]: Col<string> }
+      : { readonly [P in K]: NullCol<string> }) & {
+      readonly [P in `${K}Bidx`]: NullCol<string>;
+    }
+  : F extends {
+        type: "text" | "select" | "tz";
+      }
+    ? F extends { required: true }
+      ? { readonly [P in K]: Col<string> }
+      : { readonly [P in K]: NullCol<string> }
+    : F extends { type: "boolean" }
+      ? // boolean default OR required → notNull (DB has DEFAULT, structurally never-null)
+        F extends { default: boolean } | { required: true }
+        ? { readonly [P in K]: Col<boolean> }
+        : { readonly [P in K]: NullCol<boolean> }
+      : F extends { type: "multiSelect" }
+        ? // jsonb default `[]`, immer notNull
+          { readonly [P in K]: Col<readonly string[]> }
+        : F extends { type: "number" }
           ? F extends { required: true }
             ? { readonly [P in K]: Col<number> }
             : { readonly [P in K]: NullCol<number> }
-          : F extends { type: "money" }
+          : F extends { type: "decimal" }
             ? F extends { required: true }
-              ? { readonly [P in K]: Col<number> } & {
-                  readonly [P in `${K}Currency`]: Col<string>;
-                }
-              : { readonly [P in K]: NullCol<number> } & {
-                  readonly [P in `${K}Currency`]: Col<string>;
-                }
-            : F extends { type: "reference"; multiple: true }
-              ? { readonly [P in K]: Col<readonly string[]> }
-              : F extends { type: "reference" }
-                ? F extends { required: true }
-                  ? { readonly [P in K]: Col<string> }
-                  : { readonly [P in K]: NullCol<string> }
-                : F extends { type: "embedded" }
-                  ? // jsonb default `{}`, immer notNull
-                    { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
-                  : F extends { type: "date" | "timestamp" }
-                    ? F extends { required: true }
-                      ? { readonly [P in K]: Col<Temporal.Instant> }
-                      : { readonly [P in K]: NullCol<Temporal.Instant> }
-                    : F extends { type: "locatedTimestamp" }
+              ? { readonly [P in K]: Col<number> }
+              : { readonly [P in K]: NullCol<number> }
+            : F extends { type: "money" }
+              ? F extends { required: true }
+                ? { readonly [P in K]: Col<number> } & {
+                    readonly [P in `${K}Currency`]: Col<string>;
+                  }
+                : { readonly [P in K]: NullCol<number> } & {
+                    readonly [P in `${K}Currency`]: Col<string>;
+                  }
+              : F extends { type: "reference"; multiple: true }
+                ? { readonly [P in K]: Col<readonly string[]> }
+                : F extends { type: "reference" }
+                  ? F extends { required: true }
+                    ? { readonly [P in K]: Col<string> }
+                    : { readonly [P in K]: NullCol<string> }
+                  : F extends { type: "embedded" }
+                    ? // jsonb default `{}`, immer notNull
+                      { readonly [P in K]: Col<Readonly<Record<string, unknown>>> }
+                    : F extends { type: "date" | "timestamp" }
                       ? F extends { required: true }
-                        ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
-                            readonly [P in `${K}Tz`]: Col<string>;
-                          }
-                        : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
-                            readonly [P in `${K}Tz`]: NullCol<string>;
-                          }
-                      : F extends { type: "file" | "image" }
+                        ? { readonly [P in K]: Col<Temporal.Instant> }
+                        : { readonly [P in K]: NullCol<Temporal.Instant> }
+                      : F extends { type: "locatedTimestamp" }
                         ? F extends { required: true }
-                          ? { readonly [P in K]: Col<string> }
-                          : { readonly [P in K]: NullCol<string> }
-                        : F extends { type: "files" | "images" }
-                          ? Record<never, never>
-                          : never;
+                          ? { readonly [P in `${K}Utc`]: Col<Temporal.Instant> } & {
+                              readonly [P in `${K}Tz`]: Col<string>;
+                            }
+                          : { readonly [P in `${K}Utc`]: NullCol<Temporal.Instant> } & {
+                              readonly [P in `${K}Tz`]: NullCol<string>;
+                            }
+                        : F extends { type: "file" | "image" }
+                          ? F extends { required: true }
+                            ? { readonly [P in K]: Col<string> }
+                            : { readonly [P in K]: NullCol<string> }
+                          : F extends { type: "files" | "images" }
+                            ? Record<never, never>
+                            : never;
 
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
   k: infer I,
@@ -366,25 +383,7 @@ type SoftDeleteColumnsType = {
 };
 
 // ── ES-write brand ──────────────────────────────────────────────────────
-// A managed projection is only writable through the executor (event →
-// rebuild-safe). To make a direct write a *compile* error rather than a
-// convention, EntityTable carries a phantom `unique symbol` prop; the public
-// write helpers reject anything that has it (see NotExecutorOnly + query.ts).
-// The symbol key dodges SchemaTable's `[field: string]: unknown` index
-// signature (string index sigs don't cover symbol keys), so the brand
-// survives the type-erasure that would swallow a plain marker prop — and the
-// executor seam (applyEntityEvent) erases `table` to TableColumns<any>, which
-// carries no such prop, so the one legitimate writer stays green.
-declare const EXECUTOR_ONLY: unique symbol;
-export interface ExecutorOnly {
-  readonly [EXECUTOR_ONLY]: true;
-}
-// Negative brand for write-helper params: a branded EntityTable is NOT
-// assignable (its `true` clashes with `never`), while unmanaged EntityTableMeta
-// and erased SchemaTable pass (they lack the prop, so `?: never` is satisfied).
-export type NotExecutorOnly = {
-  readonly [EXECUTOR_ONLY]?: never;
-};
+export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 
 export type EntityTable<E extends EntityDefinition = EntityDefinition> =
   TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.
@@ -526,6 +525,18 @@ export function buildEntityTable<E extends EntityDefinition>(
           ).on(column);
         }
       }
+      // lookupable-Felder: Index auf der bidx-Spalte (lock-step mit
+      // buildEntityTableMeta).
+      const bidxFieldByField = new Map<string, string>();
+      for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type !== "text" || field.lookupable !== true) continue;
+        bidxFieldByField.set(name, `${name}Bidx`);
+        const column = tHandle[`${name}Bidx`];
+        if (column) {
+          const idxName = `${tableName}_${toSnakeCase(name)}_bidx_idx`;
+          indexes[idxName] = index(idxName).on(column);
+        }
+      }
       // entity.indexes = composite/unique-Indices die der Author explizit
       // deklariert hat. Spalten werden via field-name (camelCase) angesprochen,
       // der Index-Name folgt der Convention <table>_<col1>_<col2>_<unique|idx>
@@ -546,6 +557,26 @@ export function buildEntityTable<E extends EntityDefinition>(
           chain = chain.where(def.where as SqlExpression);
         }
         indexes[indexName] = chain;
+        // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
+        // (lock-step mit buildEntityTableMeta).
+        if (def.unique === true && def.where === undefined) {
+          const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
+          if (bidxFieldNames.some((c, i) => c !== def.columns[i])) {
+            const bidxCols = bidxFieldNames
+              .map((c) => tHandle[c])
+              .filter((col): col is ColumnHandle => col !== undefined);
+            if (bidxCols.length === bidxFieldNames.length) {
+              const whereText = bidxFieldNames
+                .filter((c, i) => c !== def.columns[i])
+                .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`)
+                .join(" AND ");
+              const partialWhere: SqlExpression = { kind: "sql-expr", text: whereText, params: [] };
+              indexes[`${indexName}_bidx`] = uniqueIndex(`${indexName}_bidx`)
+                .on(...bidxCols)
+                .where(partialWhere);
+            }
+          }
+        }
       }
       return indexes;
     },

package/src/db/tenant-db.ts

@@ -1,4 +1,7 @@
+import { KUMIKO_NAME_SYMBOL, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import {
+  asEntityTableMeta,
   asRawClient,
   deleteMany as bunDeleteMany,
   fetchOne as bunFetchOne,
@@ -11,70 +14,29 @@ import {
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
-import type { TableColumns } from "./dialect";
-
-// biome-ignore lint/suspicious/noExplicitAny: Dynamic tables — keys depend on user-defined schema.
-type Table = TableColumns<any>;
-
-/**
- * TenantDb scope modes:
- *
- * - "tenant" (default): SELECT/UPDATE/DELETE filtered by tenantId + reference data (tenantId=SYSTEM_TENANT_ID).
- *   INSERT forces tenantId — handler cannot override.
- *
- * - "system" (r.systemScope()): No tenant filter on reads/updates/deletes.
- *   INSERT uses tenantId as default but handler can override.
- *
- * Tables without a tenantId column are always unfiltered regardless of mode.
- */
-export type TenantDbMode = "tenant" | "system";
-
-export type TenantDb = {
-  readonly tenantId: TenantId;
-  readonly mode: TenantDbMode;
-  /**
-   * Underlying DbRunner. Framework-internal use (event-store, migrations) —
-   * bypasses tenant-filter. Feature code uses the typed helpers above so the
-   * automatic scoping stays intact.
-   */
-  readonly raw: DbRunner;
-  selectMany<T = Record<string, unknown>>(
-    table: Table,
-    where?: WhereObject,
-    options?: SelectOptions,
-  ): Promise<readonly T[]>;
-  fetchOne<T = Record<string, unknown>>(table: Table, where: WhereObject): Promise<T | undefined>;
-  insertOne<T = Record<string, unknown>>(
-    table: Table,
-    values: Record<string, unknown>,
-  ): Promise<T | undefined>;
-  updateMany<T = Record<string, unknown>>(
-    table: Table,
-    set: Record<string, unknown>,
-    where: WhereObject,
-  ): Promise<readonly T[]>;
-  // Method-form writes (ctx.db.insertOne/updateMany/deleteMany) keep the erased
-  // Table param: the executor-only brand is enforced on the free-function
-  // helpers (the reflexive path all production writes take), while method-form
-  // on a branded table is covered by the guard-direct-entity-writes AST guard
-  // (P5) — branding it here would force every push+write test into casts for
-  // zero production benefit (no prod code writes a projection via method-form).
-  deleteMany(table: Table, where: WhereObject): Promise<void>;
-};
+
+type Table = SchemaTable;
+
+export type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
 
 // @cast-boundary tenant-db-row
 export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[] {
   return rows as unknown as readonly T[];
 }
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-
 function tableNameOf(table: Table): string {
-  const sym = (table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+  const sym = table[KUMIKO_NAME_SYMBOL];
   return typeof sym === "string" ? sym : "<unknown>";
 }
 
+// Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
+// or a plain buildEntityTableMeta/defineUnmanagedTable result), not a direct
+// `table.tenantId` property read — the latter only exists on branded EntityTables
+// and silently returned false (no tenant filter!) for plain EntityTableMeta
+// tables like unmanaged direct-write stores, e.g. userSessionTable.
 function hasTenantColumn(table: Table): boolean {
+  const meta = asEntityTableMeta(table);
+  if (meta) return meta.columns.some((c) => c.name === "tenant_id");
   return (table as Record<string, unknown>)["tenantId"] !== undefined;
 }
 

package/src/engine/__tests__/boot-validator-action-wiring.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+describe("validateBoot — action wiring (no function values)", () => {
+  test("rowAction writeHandler payload as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: ((row: unknown) => ({ id: row })) as any,
+          },
+        ],
+      });
+      r.writeHandler("sync", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/rowAction "sync" payload is a function/);
+  });
+
+  test("rowAction writeHandler payload as declarative pick → kein Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField({ sortable: true }) } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        defaultSort: { field: "name", dir: "asc" },
+        rowActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            payload: { pick: ["name"] },
+          },
+        ],
+      });
+      r.writeHandler("sync", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { roles: ["Admin"] },
+      });
+      r.translations({
+        keys: {
+          "screen:product-list.title": { de: "Liste", en: "List" },
+          "shop:entity:product:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rowAction navigate visible as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "product-list",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            visible: (() => true) as any,
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/rowAction "edit" visible is a function/);
+  });
+
+  test("toolbarAction writeHandler payload as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: (() => ({})) as any,
+          },
+        ],
+      });
+      r.writeHandler("sync", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/toolbarAction "sync" payload is a function/);
+  });
+
+  test("entityList column renderer as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: [
+          // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+          { field: "name", renderer: ((v: unknown) => String(v)) as any },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/column "name" renderer is a function/);
+  });
+
+  test("entityEdit field visible as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+              fields: [{ field: "name", visible: (() => true) as any }],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "name" visible is a function/);
+  });
+
+  test("entityEdit field renderer as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+              fields: [{ field: "name", renderer: ((v: unknown) => String(v)) as any }],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "name" renderer is a function/);
+  });
+
+  test("entityEdit field with declarative visible/readOnly/required → kein Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              fields: [
+                {
+                  field: "name",
+                  visible: { field: "name", ne: "" },
+                  readOnly: false,
+                  required: true,
+                },
+              ],
+            },
+          ],
+        },
+      });
+      r.translations({
+        keys: {
+          "screen:product-edit.title": { de: "Bearbeiten", en: "Edit" },
+          "shop:entity:product:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("projectionList column renderer as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.screen({
+        id: "sales-list",
+        type: "projectionList",
+        query: "shop:query:sales",
+        columns: [
+          // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+          { field: "amount", renderer: ((v: unknown) => String(v)) as any },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/column "amount" renderer is a function/);
+  });
+
+  test("projectionList rowAction payload as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.screen({
+        id: "sales-list",
+        type: "projectionList",
+        query: "shop:query:sales",
+        columns: ["amount"],
+        rowActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: (() => ({})) as any,
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/rowAction "sync" payload is a function/);
+  });
+});

package/src/engine/__tests__/boot-validator-boot-check.test.ts

@@ -0,0 +1,99 @@
+// r.bootCheck(fn) — feature-declared mount invariants, checked at boot.
+// Mirrors the prompt-store trap (kumiko-enterprise#229): a feature with
+// PII-annotated fields was mounted without its required companion feature,
+// and nothing caught it at boot. The conditional-invariant tests below
+// reproduce that shape: the check only fails when the feature actually has
+// PII fields AND the companion is missing — a bare "is X mounted" check
+// would already be covered by r.requires and wouldn't justify this API.
+
+import { describe, expect, test } from "bun:test";
+import { validateFeatureBootChecks } from "../boot-validator/boot-check";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function catchMessage(fn: () => void): string {
+  try {
+    fn();
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  throw new Error("expected function to throw, but it did not");
+}
+
+const requiresUserDataHook = (features: readonly { readonly name: string }[]) =>
+  features.some((f) => f.name === "user-data-hook");
+
+const promptStore = () =>
+  defineFeature("prompt-store", (r) => {
+    const promptFields = { text: createTextField({ pii: true }) };
+    r.entity("prompt", createEntity({ fields: promptFields }));
+    r.bootCheck(({ features }) => {
+      // Conditional on this feature's own shape (has a pii field), closed
+      // over from setup — r.requires("user-data-hook") can't express that.
+      const hasPiiField = Object.values(promptFields).some((field) => field.pii);
+      if (hasPiiField && !requiresUserDataHook(features)) {
+        throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
+      }
+    });
+  });
+
+describe("r.bootCheck / validateFeatureBootChecks", () => {
+  test("no bootChecks registered → no-op", () => {
+    const noop = defineFeature("noop", () => {});
+    expect(() => validateFeatureBootChecks([noop])).not.toThrow();
+  });
+
+  test("conditional invariant satisfied (companion mounted) → boot succeeds", () => {
+    const userDataHook = defineFeature("user-data-hook", () => {});
+    expect(() => validateFeatureBootChecks([userDataHook, promptStore()])).not.toThrow();
+  });
+
+  test("conditional invariant violated (PII field, no companion) → boot fails with feature-prefixed message", () => {
+    const message = catchMessage(() => validateFeatureBootChecks([promptStore()]));
+    expect(message).toContain("[Feature prompt-store]");
+    expect(message).toContain(
+      "prompt-store has PII fields but no user-data-hook feature is mounted",
+    );
+  });
+
+  test("no PII field → boot succeeds even without the companion", () => {
+    const noPiiFields = { text: createTextField() };
+    const noPii = defineFeature("prompt-store-no-pii", (r) => {
+      r.entity("note", createEntity({ fields: noPiiFields }));
+      r.bootCheck(({ features }) => {
+        const hasPiiField = Object.values(noPiiFields).some((field) => field.pii);
+        if (hasPiiField && !requiresUserDataHook(features)) {
+          throw new Error("unreachable in this test");
+        }
+      });
+    });
+    expect(() => validateFeatureBootChecks([noPii])).not.toThrow();
+  });
+
+  test("multiple bootChecks on one feature all run in order until one throws", () => {
+    const calls: string[] = [];
+    const feature = defineFeature("multi-check", (r) => {
+      r.bootCheck(() => {
+        calls.push("first");
+      });
+      r.bootCheck(() => {
+        calls.push("second");
+        throw new Error("second check failed");
+      });
+    });
+    expect(() => validateFeatureBootChecks([feature])).toThrow("second check failed");
+    expect(calls).toEqual(["first", "second"]);
+  });
+
+  test("ctx.features exposes every mounted feature, not just the declaring one", () => {
+    const a = defineFeature("feature-a", () => {});
+    let seenNames: string[] = [];
+    const b = defineFeature("feature-b", (r) => {
+      r.bootCheck(({ features }) => {
+        seenNames = features.map((f) => f.name);
+      });
+    });
+    validateFeatureBootChecks([a, b]);
+    expect(seenNames).toEqual(["feature-a", "feature-b"]);
+  });
+});