@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/db/__tests__/big-int-field.test.ts

@@ -0,0 +1,131 @@
+// Unit-Tests fuer den BigInt-Field-Type — Atom 1a aus dem User-Data-
+// Rights Async-Export-Plan.
+//
+// Pinst:
+//   - createBigIntField liefert FieldDefinition.type === "bigInt"
+//   - buildDrizzleTable mappt auf bigint(name, mode:"number"), nicht
+//     integer (32-bit) → kein silent 2 GB-Cap
+//   - Zod-Schema akzeptiert int + safe-integer + lehnt non-int + Float
+//     + non-safe-integer ab
+//   - required + sortable + filterable + default reisen durch
+//
+// Echter DB-Roundtrip-Test (Insert >2^31, Select, identisch zurueck)
+// kommt mit Atom 1b sobald `exportJobEntity.bytesWritten` auf bigInt
+// migriert ist + die existing integration-Tests die Tabelle wieder
+// einrichten — pinst dort auf realer Postgres + Drizzle-customType-
+// Path statt parallel-mock hier.
+
+import { describe, expect, test } from "vitest";
+import { createBigIntField, createEntity, createNumberField } from "../../engine";
+import { buildInsertSchema } from "../../engine/schema-builder";
+import { buildDrizzleTable } from "../table-builder";
+
+function colByName(table: ReturnType<typeof buildDrizzleTable>, dbName: string) {
+  for (const col of Object.values(table) as Array<{
+    name?: string;
+    notNull?: boolean;
+    columnType?: string;
+    dataType?: string;
+  }>) {
+    if (col && typeof col === "object" && col.name === dbName) return col;
+  }
+  throw new Error(`Column ${dbName} not found in table`);
+}
+
+describe("createBigIntField factory", () => {
+  test("liefert FieldDef mit type='bigInt' + default required=false", () => {
+    const f = createBigIntField();
+    expect(f.type).toBe("bigInt");
+    expect(f.required).toBe(false);
+  });
+
+  test("Overrides reisen durch (required, sortable, filterable, default)", () => {
+    const f = createBigIntField({
+      required: true,
+      sortable: true,
+      filterable: true,
+      default: 42,
+    });
+    expect(f.required).toBe(true);
+    expect(f.sortable).toBe(true);
+    expect(f.filterable).toBe(true);
+    expect(f.default).toBe(42);
+  });
+});
+
+describe("buildDrizzleTable — bigInt-Mapping", () => {
+  test("bigInt-Spalte ist DISTINCT von number-Spalte (number=integer/32-bit, bigInt=bigint/64-bit)", () => {
+    const entity = createEntity({
+      fields: {
+        smallCount: createNumberField({}),
+        bigCount: createBigIntField({}),
+      },
+    });
+    const table = buildDrizzleTable("counters", entity);
+
+    const small = colByName(table, "small_count");
+    const big = colByName(table, "big_count");
+
+    // PgInteger vs PgBigint sind unterschiedliche columnType-Klassen in
+    // Drizzle — der genaue String ist Drizzle-Internal aber MUSS
+    // unterschiedlich sein, sonst geht der ganze 64-bit-Punkt verloren.
+    expect(small.columnType).not.toBe(big.columnType);
+  });
+
+  test("required bigInt wird NOT NULL", () => {
+    const entity = createEntity({
+      fields: {
+        requiredBig: createBigIntField({ required: true }),
+        optionalBig: createBigIntField({}),
+      },
+    });
+    const table = buildDrizzleTable("t", entity);
+    expect(colByName(table, "required_big").notNull).toBe(true);
+    expect(colByName(table, "optional_big").notNull).toBe(false);
+  });
+});
+
+describe("buildInsertSchema — bigInt-Validation", () => {
+  test("akzeptiert safe-integer-Werte inkl. >2^31", () => {
+    const entity = createEntity({
+      fields: { bytesWritten: createBigIntField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+
+    // 2^31 = 2_147_483_648 — Klassisches integer-Overflow-Pattern.
+    expect(schema.parse({ bytesWritten: 2_147_483_648 })).toEqual({
+      bytesWritten: 2_147_483_648,
+    });
+    // 2^50 — weit ueber integer, klar in bigInt-Territorium.
+    expect(schema.parse({ bytesWritten: 2 ** 50 })).toEqual({
+      bytesWritten: 2 ** 50,
+    });
+  });
+
+  test("lehnt Float ab (silent-Truncation-Schutz)", () => {
+    const entity = createEntity({
+      fields: { count: createBigIntField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(() => schema.parse({ count: 1.5 })).toThrow();
+  });
+
+  test("lehnt non-safe-integer ab (>2^53)", () => {
+    const entity = createEntity({
+      fields: { count: createBigIntField({ required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+    // 2^53 = 9_007_199_254_740_992 ist Number.MAX_SAFE_INTEGER.
+    // Werte ueber dem Cap koennen nicht round-trip-en ohne Praezisions-
+    // Verlust — Zod's .safe() greift hier.
+    expect(() => schema.parse({ count: Number.MAX_SAFE_INTEGER + 2 })).toThrow();
+  });
+
+  test("default-Wert reist in Zod-Schema durch", () => {
+    const entity = createEntity({
+      fields: { count: createBigIntField({ default: 100 }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.parse({})).toEqual({ count: 100 });
+  });
+});

package/src/db/assert-exists-in.ts

@@ -1,5 +1,5 @@
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { and, eq, type SQL } from "drizzle-orm";
+import type { TenantId } from "../engine/types/identifiers";
 import { NotFoundError } from "../errors";
 import type { DbConnection } from "./connection";
 import type { TenantDb } from "./tenant-db";
@@ -43,7 +43,7 @@ export async function assertExistsIn(
   const [row] = await db
     .select()
     .from(entity)
-    .where(and(...conditions) as SQL);
+    .where(and(...conditions) as SQL); // @cast-boundary db-operator
 
   if (!row) {
     const entityName = options.entityName ?? String(options.field).replace(/Id$/, "");

package/src/db/cursor.ts

@@ -1,5 +1,5 @@
-import type { EntityId, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { and, asc, desc, eq, gt, inArray, type SQL, sql } from "drizzle-orm";
+import type { EntityId, TenantId } from "../engine/types/identifiers";
 import type { SelectQuery as PgSelect } from "./dialect";
 
 export type CursorQueryOptions = {
@@ -61,7 +61,7 @@ export function applyCursorQuery<T extends PgSelect>(
       // werfen.
       conditions.push(sql`false`);
     } else {
-      conditions.push(inArray(table.id, options.filterIds as readonly string[]));
+      conditions.push(inArray(table.id, options.filterIds as readonly string[])); // @cast-boundary db-operator
     }
   }
 
@@ -79,5 +79,5 @@ export function applyCursorQuery<T extends PgSelect>(
       options.sortDirection === "desc" ? result.orderBy(desc(column)) : result.orderBy(asc(column));
   }
 
-  return result as T;
+  return result as T; // @cast-boundary engine-bridge
 }

package/src/db/event-store-executor.ts

@@ -1,4 +1,5 @@
 import { and, asc, desc, eq, gt, inArray, lt, ne, type SQL, sql } from "drizzle-orm";
+import type { AnyPgColumn } from "drizzle-orm/pg-core";
 import { requestContext } from "../api/request-context";
 import { checkWriteFieldOwnership } from "../engine/field-access";
 import {
@@ -32,7 +33,7 @@ import {
 } from "../event-store";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
-import { generateId } from "../utils";
+import { assertUnreachable, generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 import type { DbRow } from "./connection";
@@ -54,8 +55,11 @@ type Table = TableColumns<any>;
 // vs-Type-Compat ohnehin Kontrolle was reinkommt.
 //
 // Empty-array IN ist explizit "no match" (SQL false), nicht "match all".
-// biome-ignore lint/suspicious/noExplicitAny: Drizzle-Column ist generic; siehe oben.
-function buildFilterCondition(col: any, op: "eq" | "ne" | "lt" | "gt" | "in", value: unknown): SQL {
+function buildFilterCondition(
+  col: AnyPgColumn,
+  op: "eq" | "ne" | "lt" | "gt" | "in",
+  value: unknown,
+): SQL {
   switch (op) {
     case "eq":
       return eq(col, value as never); // @cast-boundary db-operator
@@ -70,6 +74,8 @@ function buildFilterCondition(col: any, op: "eq" | "ne" | "lt" | "gt" | "in", va
         return inArray(col, value as never); // @cast-boundary db-operator
       }
       return sql`false`;
+    default:
+      assertUnreachable(op, "filter op");
   }
 }
 
@@ -281,7 +287,7 @@ export function createEventStoreExecutor(
     }
     // Drizzle's variadic `and()` is typed `SQL | undefined`; conditions is
     // guaranteed non-empty above (we pushed at least one).
-    return and(...conditions) as SQL;
+    return and(...conditions) as SQL; // @cast-boundary db-operator
   }
 
   async function loadById(id: EntityId, db: TenantDb): Promise<Record<string, unknown> | null> {
@@ -295,7 +301,7 @@ export function createEventStoreExecutor(
       // Respect an explicit id in the payload (seed pattern, SCIM import). Without
       // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
       // event payload so defaults + downstream consumers don't see a redundant id field.
-      const explicitId = typeof payload["id"] === "string" ? (payload["id"] as string) : undefined;
+      const explicitId = typeof payload["id"] === "string" ? (payload["id"] as string) : undefined; // @cast-boundary engine-payload
       const aggregateId = explicitId ?? generateId();
       const { id: _id, ...payloadWithoutId } = payload;
       const data = applyDefaults(payloadWithoutId);
@@ -561,7 +567,7 @@ export function createEventStoreExecutor(
           isSuccess: true,
           data: {
             kind: "save",
-            id: data["id"] as EntityId,
+            id: data["id"] as EntityId, // @cast-boundary engine-payload
             data,
             changes: payload.changes,
             previous,
@@ -793,7 +799,7 @@ export function createEventStoreExecutor(
         }
       }
 
-      const whereClause = conditions.length > 0 ? (and(...conditions) as SQL) : undefined;
+      const whereClause = conditions.length > 0 ? (and(...conditions) as SQL) : undefined; // @cast-boundary db-operator
       let query = whereClause
         ? db.select().from(table).where(whereClause)
         : db.select().from(table);
@@ -822,13 +828,13 @@ export function createEventStoreExecutor(
         await entityCache.mset(
           user.tenantId,
           entityName,
-          rows.map((r) => ({ id: r["id"] as EntityId, data: r })),
+          rows.map((r) => ({ id: r["id"] as EntityId, data: r })), // @cast-boundary engine-payload
         );
       }
 
       const lastRow = rows[rows.length - 1];
       const nextCursor =
-        rows.length === limit && lastRow ? encodeCursor(lastRow["id"] as string) : null;
+        rows.length === limit && lastRow ? encodeCursor(lastRow["id"] as string) : null; // @cast-boundary engine-payload
 
       // total: extra COUNT(*) — nur wenn explizit angefordert (Pager-UI).
       // Postgres-Cost ist O(table-scan) ohne Filter, mit Filter so teuer
@@ -842,7 +848,7 @@ export function createEventStoreExecutor(
           const countQuery = whereClause
             ? db.select({ count: sql<number>`count(*)::int` }).from(table).where(whereClause)
             : db.select({ count: sql<number>`count(*)::int` }).from(table);
-          const countRow = (await countQuery) as Array<{ count: number }>;
+          const countRow = (await countQuery) as Array<{ count: number }>; // @cast-boundary db-row
           total = countRow[0]?.count ?? 0;
         }
       }
@@ -872,7 +878,7 @@ export function createEventStoreExecutor(
             const checked = await db
               .select()
               .from(table)
-              .where(and(idFilter(payload.id), ownership.sql) as SQL)
+              .where(and(idFilter(payload.id), ownership.sql) as SQL) // @cast-boundary db-operator
               .limit(1);
             if (checked.length === 0) return null;
           }
@@ -887,11 +893,11 @@ export function createEventStoreExecutor(
       // thread the ownership clause.
       const baseFilter = idFilter(payload.id);
       const whereClause =
-        ownership.kind === "sql" ? (and(baseFilter, ownership.sql) as SQL) : baseFilter;
+        ownership.kind === "sql" ? (and(baseFilter, ownership.sql) as SQL) : baseFilter; // @cast-boundary db-operator
       const rows = (await db.select().from(table).where(whereClause).limit(1)) as Record<
         string,
         unknown
-      >[];
+      >[]; // @cast-boundary db-row
       const raw = rows[0];
       if (!raw) return null;
       const row = rehydrateCompoundTypes(raw, entity);

package/src/db/located-timestamp.ts

@@ -51,7 +51,7 @@ export function flattenLocatedTimestamp(
         `flattenLocatedTimestamp: field "${name}" expects { at, tz } or { utc, tz } object, got ${typeof raw}`,
       );
     }
-    const pair = raw as { at?: string; tz?: string; utc?: string };
+    const pair = raw as { at?: string; tz?: string; utc?: string }; // @cast-boundary schema-walk
 
     delete result[name];
 

package/src/db/money.ts

@@ -26,6 +26,11 @@ const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
  *
  * Pure — mutiert nicht.
  */
+interface MoneyPair {
+  amount: number;
+  currency?: string;
+}
+
 export function flattenMoney(
   payload: Record<string, unknown>,
   entity: EntityDefinition,
@@ -42,8 +47,13 @@ export function flattenMoney(
     let amount: number;
     let currency: string;
 
-    if (typeof raw === "object" && "amount" in raw) {
-      const pair = raw as { amount: number; currency?: string };
+    if (
+      typeof raw === "object" &&
+      raw !== null &&
+      "amount" in raw &&
+      typeof (raw as MoneyPair).amount === "number" // @cast-boundary schema-walk
+    ) {
+      const pair = raw as MoneyPair; // @cast-boundary schema-walk
       amount = pair.amount;
       currency = pair.currency ?? fallbackCurrency;
     } else if (typeof raw === "number") {

package/src/db/pg-error.ts

@@ -20,7 +20,7 @@ export function extractPgError(e: unknown): PgErrorInfo | null {
   for (const layer of layers) {
     // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
     const code = (layer as { code?: string }).code;
-    const constraintName = (layer as { constraint_name?: string }).constraint_name;
+    const constraintName = (layer as { constraint_name?: string }).constraint_name; // @cast-boundary error-details
     if (code !== undefined || constraintName !== undefined) {
       return { code, constraint_name: constraintName };
     }

package/src/db/row-helpers.ts

@@ -49,5 +49,5 @@ export async function fetchOne<TRow = DbRow>(
 ): Promise<TRow | undefined> {
   const where = conditions.length === 1 ? conditions[0] : and(...conditions);
   const rows = await db.select().from(table).where(where).limit(1);
-  return rows[0] as TRow | undefined;
+  return rows[0] as TRow | undefined; // @cast-boundary db-row
 }

package/src/db/table-builder.ts

@@ -8,6 +8,7 @@ import type {
 } from "../engine/types";
 import { assertUnreachable } from "../utils";
 import {
+  bigint,
   boolean,
   index,
   instant,
@@ -25,6 +26,7 @@ import {
 type ColumnBuilder =
   | ReturnType<typeof text>
   | ReturnType<typeof integer>
+  | ReturnType<typeof bigint>
   | ReturnType<typeof boolean>
   | ReturnType<typeof moneyAmount>
   | ReturnType<typeof jsonb>
@@ -92,6 +94,15 @@ function fieldToColumns(
       const col = integer(snakeName);
       return { [name]: field.required ? col.notNull() : col };
     }
+    case "bigInt": {
+      // 64-bit-Integer fuer Audit-Counter, Byte-Sizes, Cumulative-Sums.
+      // mode:"number" liefert JS-`number` (sicher bis 2^53 ≈ 9 PB) statt
+      // JS-`bigint` — JSON-serialisierbar, Frontend-tauglich. Wer >2^53
+      // braucht (Astronomie-Astronomie), nutzt einen Text-Field mit
+      // eigenem Codec.
+      const col = bigint(snakeName, { mode: "number" });
+      return { [name]: field.required ? col.notNull() : col };
+    }
     case "reference":
       // Tier 2.7e-3: FK-Style UUID-Spalte. Multi-Mode (Tier 2.7e-Multi)
       // speichert UUIDs als jsonb-Array<string>. Single-Mode bleibt
@@ -122,10 +133,8 @@ function fieldToColumns(
       // wrapper-feld mit boolean-flag oder discriminierte-union.
       return { [name]: jsonb(snakeName).default({}).notNull() };
     case "date": {
-      // TODO(Sprint G): semantisch falsch — `type:"date"` sollte
-      // Temporal.PlainDate sein (PG `date` Spalte, kein TZ). Heute aliased auf
-      // instant() = TIMESTAMPTZ damit Caller die gleiche API nutzen wie für
-      // type:"timestamp". Echte PlainDate-Migration kommt nach Sprint F.
+      // `type:"date"` aliased auf instant() = TIMESTAMPTZ. Echte
+      // PlainDate-Migration (PG `date` Spalte, kein TZ) kommt später.
       const col = instant(snakeName);
       return { [name]: field.required ? col.notNull() : col };
     }
@@ -467,7 +476,13 @@ export function buildDrizzleTable<E extends EntityDefinition>(
           def.name ?? `${tableName}_${def.columns.map((c) => toSnakeCase(c)).join("_")}_${suffix}`;
         const builder = def.unique === true ? uniqueIndex(indexName) : index(indexName);
         // biome-ignore lint/suspicious/noExplicitAny: drizzle's .on(...cols) is variadic generic
-        indexes.push((builder.on as any)(...cols));
+        let chain = (builder.on as any)(...cols); // @cast-boundary drizzle-bridge
+        if (def.where !== undefined) {
+          // Partial-Index: drizzle's IndexBuilder.where(SQL) emittiert das
+          // `WHERE <condition>` ans Ende der `CREATE [UNIQUE] INDEX`-DDL.
+          chain = chain.where(def.where);
+        }
+        indexes.push(chain);
       }
       return indexes;
     },

package/src/db/tenant-db.ts

@@ -1,5 +1,5 @@
-import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { and, type Column, eq, getTableName, or, type SQL } from "drizzle-orm";
+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";
@@ -148,7 +148,7 @@ export function createTenantDb(
   // types don't include PromiseLike. Cast via this helper so the double-
   // cast is named and lives in exactly one place per scope.
   function asDrizzleThenable<T>(builder: unknown): PromiseLike<T> {
-    return builder as PromiseLike<T>;
+    return builder as PromiseLike<T>; // @cast-boundary engine-bridge
   }
 
   // Wrap a DB query promise in a `db.query` span + emit the DB duration
@@ -229,7 +229,7 @@ export function createTenantDb(
     const ownOrGlobal = or(
       eq(table["tenantId"], tenantId),
       eq(table["tenantId"], SYSTEM_TENANT_ID),
-    ) as SQL;
+    ) as SQL; // @cast-boundary db-operator
     return extra.length > 0 ? and(ownOrGlobal, ...extra) : ownOrGlobal;
   }
 
@@ -309,7 +309,7 @@ export function createTenantDb(
           reject ?? undefined,
         );
       },
-    } as TenantSelectQuery;
+    } as TenantSelectQuery; // @cast-boundary drizzle-bridge
   }
 
   // --- Where helper for update/delete ---
@@ -342,7 +342,7 @@ export function createTenantDb(
               return withDbSpan<Record<string, unknown>[]>(
                 "insert",
                 table,
-                () => q.returning() as PromiseLike<Record<string, unknown>[]>,
+                () => q.returning() as PromiseLike<Record<string, unknown>[]>, // @cast-boundary db-runner
               );
             },
             onConflictDoUpdate(spec: ConflictUpdate) {
@@ -370,7 +370,7 @@ export function createTenantDb(
                 reject,
               );
             },
-          } as TenantInsertValues;
+          } as TenantInsertValues; // @cast-boundary drizzle-bridge
         },
       };
     },
@@ -387,7 +387,7 @@ export function createTenantDb(
                   return withDbSpan<Record<string, unknown>[]>(
                     "update",
                     table,
-                    () => wq.returning() as PromiseLike<Record<string, unknown>[]>,
+                    () => wq.returning() as PromiseLike<Record<string, unknown>[]>, // @cast-boundary db-runner
                   );
                 },
                 // biome-ignore lint/suspicious/noThenProperty: thenable for await
@@ -397,7 +397,7 @@ export function createTenantDb(
                     reject,
                   );
                 },
-              } as TenantUpdateWhere;
+              } as TenantUpdateWhere; // @cast-boundary drizzle-bridge
             },
             returning(): PromiseLike<Record<string, unknown>[]> {
               return Promise.reject(
@@ -416,7 +416,7 @@ export function createTenantDb(
                 ),
               ).then(resolve, reject);
             },
-          } as TenantUpdateSet;
+          } as TenantUpdateSet; // @cast-boundary drizzle-bridge
         },
       };
     },

package/src/engine/__tests__/_pipeline-test-utils.ts

@@ -0,0 +1,23 @@
+// Shared helpers for unit-tests of pipeline.ts / run-pipeline.ts and the
+// step-builders. The minimal-ctx helper was 4 lines duplicated in every
+// pipeline-* test file; centralised here for the M.1.6 cleanup-pass
+// (Followup #7 splitting).
+//
+// Real-ctx integration lives in pipeline-handler.integration.ts —
+// these helpers are deliberately for the no-DB tests where step-args
+// + assembly + boot-time guards are what's exercised.
+
+import type { HandlerContext } from "../types/handlers";
+
+/**
+ * Returns an empty object cast as HandlerContext. Steps that only
+ * exercise their own arg-resolution + step-list-assembly don't read
+ * any ctx field; the runner needs an object-shaped ctx but no surface
+ * beyond that.
+ *
+ * Tests that actually use ctx fields (db, query, appendEvent, etc.)
+ * belong in pipeline-handler.integration.ts against the real stack.
+ */
+export function buildMinimalCtx(): HandlerContext {
+  return {} as HandlerContext;
+}

package/src/engine/__tests__/boot-validator-api-exposure.test.ts

@@ -0,0 +1,142 @@
+// Boot-Validator-Tests fuer r.exposesApi / r.usesApi (S0.4).
+//
+// Pflicht-Validierungen (Error / throw):
+//   - r.usesApi(name) ohne passenden r.exposesApi(name) → throw
+//   - r.usesApi(name) ohne r.requires(providerFeature) → throw
+//   - r.exposesApi(name) zweimal in einem Feature → throw
+//   - Globale Doppel-Exposure (zwei Features, gleicher Name) → throw
+//
+// Soft-Warning (console.warn):
+//   - Feature ruft eigene exposesApi via usesApi (Refactor-Leftover)
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+
+describe("validateBoot — r.exposesApi / r.usesApi", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("matching exposesApi/usesApi with requires() passes", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.requires("compliance-profiles");
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([provider, consumer])).not.toThrow();
+  });
+
+  test("matching exposesApi/usesApi with optionalRequires() passes", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.optionalRequires("compliance-profiles");
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([provider, consumer])).not.toThrow();
+  });
+
+  test("usesApi without any exposer throws with known-list", () => {
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([consumer])).toThrow(
+      /r\.usesApi\("compliance\.forTenant"\) but no feature exposes that API/,
+    );
+  });
+
+  test("usesApi with typo throws and lists known APIs", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      r.requires("compliance-profiles");
+      r.usesApi("compliance.fortenant"); // typo: lowercase t
+    });
+    expect(() => validateBoot([provider, consumer])).toThrow(
+      /Known exposed APIs: compliance\.forTenant/,
+    );
+  });
+
+  test("usesApi exists but missing requires() throws", () => {
+    const provider = defineFeature("compliance-profiles", (r) => {
+      r.exposesApi("compliance.forTenant");
+    });
+    const consumer = defineFeature("user-data-rights", (r) => {
+      // missing r.requires("compliance-profiles")
+      r.usesApi("compliance.forTenant");
+    });
+    expect(() => validateBoot([provider, consumer])).toThrow(
+      /not in requires\/optionalRequires\. Add r\.requires\("compliance-profiles"\)/,
+    );
+  });
+
+  test("exposesApi twice in same feature throws", () => {
+    expect(() =>
+      defineFeature("dup", (r) => {
+        r.exposesApi("api.foo");
+        r.exposesApi("api.foo");
+      }),
+    ).toThrow(/r\.exposesApi\("api\.foo"\) called twice/);
+  });
+
+  test("two features expose the same API throws on boot", () => {
+    const a = defineFeature("a", (r) => {
+      r.exposesApi("shared.api");
+    });
+    const b = defineFeature("b", (r) => {
+      r.exposesApi("shared.api");
+    });
+    expect(() => validateBoot([a, b])).toThrow(
+      /Cross-feature API "shared\.api" exposed by both "a" and "b"/,
+    );
+  });
+
+  test("self-exposure (feature uses its own exposed API) warns", () => {
+    const f = defineFeature("self-loop", (r) => {
+      r.exposesApi("self.api");
+      r.usesApi("self.api");
+    });
+    validateBoot([f]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes("typically a refactor leftover"),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
+  test("feature with no API surface boots clean (regression guard)", () => {
+    const plain = defineFeature("plain", (r) => {
+      r.requires();
+    });
+    expect(() => validateBoot([plain])).not.toThrow();
+  });
+
+  test("global double-exposure throws before consumer-resolution kicks in", () => {
+    // Edge-case: zwei Features exposen denselben Namen UND ein drittes
+    // Feature ruft den Namen. Erwartet: Doppel-Exposure-Error wirft im
+    // Pre-Walk (validateBoot) BEVOR validateApiExposureMatching laeuft.
+    const a = defineFeature("provider-a", (r) => {
+      r.exposesApi("shared.api");
+    });
+    const b = defineFeature("provider-b", (r) => {
+      r.exposesApi("shared.api");
+    });
+    const consumer = defineFeature("consumer", (r) => {
+      r.requires("provider-a");
+      r.usesApi("shared.api");
+    });
+    expect(() => validateBoot([a, b, consumer])).toThrow(
+      /Cross-feature API "shared\.api" exposed by both/,
+    );
+  });
+});