@cosmicdrift/kumiko-framework 0.273.0 → 0.275.0

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

@@ -9,14 +9,19 @@ import {
   normalizeAccessEntry,
   shiftParams,
 } from "../engine/ownership";
-import type { EntityDefinition, EntityId } from "../engine/types";
+import type { EntityDefinition, EntityId, SessionUser } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import { UnprocessableError } from "../errors";
 import { getStreamVersion } from "../event-store";
+import type { SearchAdapter } from "../search/types";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta";
 import { rehydrateCompoundTypes } from "./compound-types";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor";
-import { collectEncryptedFieldNames } from "./entity-field-encryption";
+import {
+  collectEncryptedFieldNames,
+  hasSearchablePlaintext,
+  isSensitiveLabelField,
+} from "./entity-field-encryption";
 import type { EventStoreExecutor } from "./event-store-executor";
 import { buildFilterWhere, type ExecutorContext, type Table } from "./event-store-executor-context";
 import { buildParentRefClause } from "./parent-ref-clause";
@@ -104,26 +109,27 @@ function keysetBoundarySql(
 
 type ListFilter = {
   readonly field: string;
-  readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+  readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
   readonly value: unknown;
 };
 
 // multiSelect stores its options as a jsonb array — a filter value is one
 // option, not the whole array, so eq/ne/in must check array containment
 // (`@>`) instead of scalar `=`/`<>`/`IN` against the jsonb column (fw#2490).
-// lt/gt have no containment analogue; the boot-validator already blocks them
-// for screen-declared filters (screen-filter-ops.ts EQUALITY_ONLY), but a
-// client-supplied facet filter reaches here unvalidated, so treat it as
-// unsatisfiable rather than emitting SQL Postgres would reject.
+// lt/gt/lte/gte have no containment analogue; the boot-validator already
+// blocks them for screen-declared filters (screen-filter-ops.ts
+// EQUALITY_ONLY), but a client-supplied facet filter reaches here
+// unvalidated, so treat it as unsatisfiable rather than emitting SQL
+// Postgres would reject.
 function applyMultiSelectFilter(
   colSql: (field: string) => string,
   whereSql: string[],
   params: unknown[],
   f: ListFilter,
 ): void {
-  if (f.op === "lt" || f.op === "gt") {
+  if (f.op === "lt" || f.op === "gt" || f.op === "lte" || f.op === "gte") {
     whereSql.push("FALSE");
-    // skip: lt/gt is unsatisfiable on a multiSelect column
+    // skip: lt/gt/lte/gte is unsatisfiable on a multiSelect column
     return;
   }
   if (f.op === "in") {
@@ -290,11 +296,86 @@ function collectReferenceSearchDescriptors(
 // unscoped SQL, a match in a foreign tenant must never surface a row here
 // (fw#2660's hard constraint). Mirrors the main table's own tenant filter
 // (see the `table["tenantId"]` check further down in list()).
+async function resolveReferenceMatchesViaIlike(
+  descriptor: ReferenceSearchDescriptor,
+  searchTerm: string,
+  targetTable: Table,
+  targetTableName: string,
+  db: TenantDb,
+): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
+  const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+  const subParams: unknown[] = [`%${escapeLikePattern(searchTerm)}%`];
+  let tenantClause = "";
+  if (targetTable["tenantId"] !== undefined && db.mode === "tenant") {
+    subParams.push(db.tenantId, SYSTEM_TENANT_ID);
+    tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
+  }
+  // ::text cast covers a non-text labelField (e.g. a number/select column
+  // used as label) — Postgres has no ILIKE for those types otherwise.
+  const sql =
+    `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
+    `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
+  const rows = await executeRawQueryRead<{ id: string }>(tenantDbRunner(db), sql, subParams);
+  if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
+    // skip: no match, or over the cap — drop the clause rather than
+    // truncate to an arbitrary slice of matching targets
+    return undefined;
+  }
+  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+
+// Same lookup, but the target's index is tenant-wide, not per-viewer, so
+// candidate ids get re-checked against the target entity's own read access.
+async function resolveReferenceMatchesViaSearchIndex(
+  descriptor: ReferenceSearchDescriptor,
+  searchTerm: string,
+  targetEntity: EntityDefinition,
+  targetTable: Table,
+  targetTableName: string,
+  user: SessionUser,
+  db: TenantDb,
+  searchAdapter: SearchAdapter,
+): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
+  const searchTenantId = targetEntity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+  const results = await searchAdapter.search(searchTenantId, searchTerm, {
+    filterType: descriptor.targetEntityName,
+    limit: MAX_REFERENCE_SEARCH_IDS + 1,
+  });
+  if (results.length === 0 || results.length > MAX_REFERENCE_SEARCH_IDS) {
+    // skip: no match, or over the cap — same drop-the-clause policy as the ILIKE path
+    return undefined;
+  }
+
+  const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+  if (ownership.kind === "empty") return undefined;
+
+  const candidateIds = results.map((r) => String(r.entityId));
+  if (ownership.kind === "pass") {
+    return { ownColumn: descriptor.ownColumn, ids: candidateIds };
+  }
+
+  const params: unknown[] = [...candidateIds];
+  const idPlaceholders = candidateIds.map((_, i) => `$${i + 1}`);
+  const shifted = shiftParams(
+    { sqlText: ownership.sqlText, params: ownership.params },
+    params.length,
+  );
+  const sql =
+    `SELECT "id" FROM "${targetTableName}" WHERE "id" IN (${idPlaceholders.join(", ")}) ` +
+    `AND ${shifted.sqlText}`;
+  for (const p of shifted.params) params.push(p);
+  const rows = await executeRawQueryRead<{ id: string }>(tenantDbRunner(db), sql, params);
+  if (rows.length === 0) return undefined;
+  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+
 async function resolveReferenceMatches(
   descriptor: ReferenceSearchDescriptor,
   searchTerm: string,
   resolveEntity: (entityName: string) => EntityDefinition | undefined,
   db: TenantDb,
+  user: SessionUser,
+  searchAdapter: SearchAdapter,
 ): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
   const targetEntity = resolveEntity(descriptor.targetEntityName);
   if (targetEntity === undefined) {
@@ -308,38 +389,36 @@ async function resolveReferenceMatches(
     // `name` is a declared field on the tenant entity, not an id/row-meta column
     return undefined;
   }
-  if (
-    collectEncryptedFieldNames(targetEntity).has(descriptor.labelField) ||
-    collectPiiSubjectFields(targetEntity).includes(descriptor.labelField)
-  ) {
-    // skip: encrypted/PII labelField — ILIKE can never match ciphertext,
-    // emitting the query would just be a silent, permanent non-match
-    return undefined;
-  }
 
   const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
   const targetTableName = String(
     (targetTable as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL],
   );
-  const labelCol = physicalColumnName(targetTable, descriptor.labelField);
-  const subParams: unknown[] = [`%${escapeLikePattern(searchTerm)}%`];
-  let tenantClause = "";
-  if (targetTable["tenantId"] !== undefined && db.mode === "tenant") {
-    subParams.push(db.tenantId, SYSTEM_TENANT_ID);
-    tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
+
+  if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
+    return resolveReferenceMatchesViaIlike(
+      descriptor,
+      searchTerm,
+      targetTable,
+      targetTableName,
+      db,
+    );
   }
-  // ::text cast covers a non-text labelField (e.g. a number/select column
-  // used as label) — Postgres has no ILIKE for those types otherwise.
-  const sql =
-    `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
-    `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
-  const rows = await executeRawQueryRead<{ id: string }>(tenantDbRunner(db), sql, subParams);
-  if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
-    // skip: no match, or over the cap — drop the clause rather than
-    // truncate to an arbitrary slice of matching targets
+  if (!hasSearchablePlaintext(targetEntity, descriptor.labelField)) {
+    // skip: no plaintext anywhere to match — boot rejects this normally,
+    // this is defense-in-depth for a target entity resolved only at runtime.
     return undefined;
   }
-  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+  return resolveReferenceMatchesViaSearchIndex(
+    descriptor,
+    searchTerm,
+    targetEntity,
+    targetTable,
+    targetTableName,
+    user,
+    db,
+    searchAdapter,
+  );
 }
 
 // Projected alongside the row when a reference sort is active, so the keyset
@@ -517,7 +596,14 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           ? (
               await Promise.all(
                 descriptors.map((d) =>
-                  resolveReferenceMatches(d, searchTerm, referenceSearch.resolveEntity, db),
+                  resolveReferenceMatches(
+                    d,
+                    searchTerm,
+                    referenceSearch.resolveEntity,
+                    db,
+                    user,
+                    effectiveSearchAdapter,
+                  ),
                 ),
               )
             ).filter(

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

@@ -2306,7 +2306,7 @@ describe("boot-validator", () => {
     function makeFeature(
       filter: {
         readonly field: string;
-        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+        readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
         readonly value: unknown;
       },
       fields: Record<string, unknown> = {
@@ -2365,6 +2365,25 @@ describe("boot-validator", () => {
       ).not.toThrow();
     });
 
+    test("filter.op=lte/gte auf number-Feld → kein Throw (vergleichbar)", () => {
+      const fields = {
+        name: { type: "text", filterable: true },
+        rank: { type: "number", filterable: true },
+      };
+      expect(() =>
+        validateBoot([makeFeature({ field: "rank", op: "lte", value: 5 }, fields)]),
+      ).not.toThrow();
+      expect(() =>
+        validateBoot([makeFeature({ field: "rank", op: "gte", value: 5 }, fields)]),
+      ).not.toThrow();
+    });
+
+    test("filter.op=lte auf text-Feld → Throw (op-vs-Type-Compat)", () => {
+      expect(() => validateBoot([makeFeature({ field: "status", op: "lte", value: "x" })])).toThrow(
+        /filter\.op "lte" is not allowed on field "status" \(type "text"\)/,
+      );
+    });
+
     test('filter.op="in" mit non-array value → Throw', () => {
       expect(() =>
         validateBoot([makeFeature({ field: "status", op: "in", value: "active" })]),

package/src/engine/__tests__/dedupe-features.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { createApp, createRegistry, dedupeFeatures, defineFeature } from "../index";
+
+describe("dedupeFeatures", () => {
+  test("same reference mounted twice collapses to one entry, order preserved", () => {
+    const shared = defineFeature("shared", () => {});
+    const other = defineFeature("other", () => {});
+
+    const result = dedupeFeatures([shared, other, shared]);
+
+    expect(result).toEqual([shared, other]);
+    expect(result[0]).toBe(shared);
+  });
+
+  test("registry builds when the same reference is mounted twice", () => {
+    const shared = defineFeature("shared", () => {});
+
+    expect(() => createRegistry([shared, shared])).not.toThrow();
+  });
+
+  test("two instances with shallow-equal dedupeOptions collapse — first instance kept", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { limit: 3 } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { limit: 3 } });
+    const other = defineFeature("y", () => {});
+
+    const result = dedupeFeatures([a, other, b]);
+
+    expect(result).toEqual([a, other]);
+    expect(result[0]).toBe(a);
+  });
+
+  test("differing primitive dedupeOptions throws with a 'different options' message", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { limit: 3 } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { limit: 5 } });
+
+    expect(() => dedupeFeatures([a, b])).toThrow(/Duplicate feature: "x".*different options/);
+  });
+
+  test("same function reference in dedupeOptions collapses", () => {
+    const onTrigger = () => {};
+    const a = defineFeature("x", () => {}, { dedupeOptions: { onTrigger } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { onTrigger } });
+
+    const result = dedupeFeatures([a, b]);
+
+    expect(result).toEqual([a]);
+  });
+
+  test("different function reference in dedupeOptions throws", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { onTrigger: () => {} } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { onTrigger: () => {} } });
+
+    expect(() => dedupeFeatures([a, b])).toThrow(/Duplicate feature: "x".*different options/);
+  });
+
+  test("{ a: undefined } and {} are treated as shallow-equal (missing key == undefined)", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { a: undefined } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: {} });
+
+    const result = dedupeFeatures([a, b]);
+
+    expect(result).toEqual([a]);
+  });
+
+  test("two distinct instances with no dedupeOptions throw with a 'distinct instances' message", () => {
+    const a = defineFeature("x", () => {});
+    const b = defineFeature("x", () => {});
+
+    expect(() => dedupeFeatures([a, b])).toThrow(
+      /Duplicate feature: "x" mounted twice as distinct instances/,
+    );
+  });
+
+  test("createApp boots end-to-end with a feature mounted twice via dedupeOptions", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: {} });
+    const b = defineFeature("x", () => {}, { dedupeOptions: {} });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin"],
+        features: [a, b],
+      }),
+    ).not.toThrow();
+  });
+});

package/src/engine/__tests__/engine.test.ts

@@ -754,6 +754,92 @@ describe("createRegistry", () => {
     expect(() => createRegistry([feature])).toThrow(/multiple/);
   });
 
+  test("throws at boot when a searchable reference targets an encrypted labelField", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({
+          table: "Customers",
+          fields: {
+            name: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
+          },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/encrypted\/PII/);
+  });
+
+  test('throws at boot when a searchable reference targets a PII labelField without find: "fuzzy" (no plaintext index)', () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          table: "Contacts",
+          fields: { displayName: createTextField({ personal: "self", find: "exact" }) },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            contactId: {
+              type: "reference",
+              entity: "contact",
+              labelField: "displayName",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/encrypted\/PII/);
+  });
+
+  test('does not throw when a searchable reference targets a PII labelField with find: "fuzzy" (derived search index)', () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          table: "Contacts",
+          fields: { displayName: createTextField({ personal: "self", find: "fuzzy" }) },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            contactId: {
+              type: "reference",
+              entity: "contact",
+              labelField: "displayName",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).not.toThrow();
+  });
+
   test("returns sortable reference fields for entity, without leaking them into getSortableFields (fw#2741)", () => {
     const feature = defineFeature("crm", (r) => {
       r.entity(

package/src/engine/__tests__/screen-filter-ops.test.ts

@@ -3,7 +3,7 @@ import { createDecimalField, createMoneyField, createNumberField } from "../fact
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { ScreenFilterOp } from "../types";
 
-const COMPARABLE: ScreenFilterOp[] = ["eq", "ne", "lt", "gt", "in"];
+const COMPARABLE: ScreenFilterOp[] = ["eq", "ne", "lt", "gt", "lte", "gte", "in"];
 
 describe("getAllowedFilterOps — decimal is comparable (#343/1)", () => {
   test("decimal yields the full comparable op-set, not the empty default", () => {

package/src/engine/__tests__/soft-delete-cleanup-job-tenant-db.integration.test.ts

@@ -0,0 +1,82 @@
+// fw#2914 — soft-delete cleanup runs through the real job runner with ctx.db as a
+// tenant-filtered TenantDb: a run purges only its own tenant's expired rows.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../bun-db/query";
+import { selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { waitFor } from "../../testing";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineFeature,
+} from "../index";
+import { SOFT_DELETE_CLEANUP_JOB } from "../soft-delete-cleanup";
+
+const itemEntity = createEntity({
+  table: "fw2914_sdc_items",
+  softDelete: true,
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+});
+const itemTable = buildEntityTable("item", itemEntity);
+
+const feature = defineFeature("sdcjob", (r) => {
+  r.entity("item", itemEntity);
+  r.writeHandler(defineEntityCreateHandler("item", itemEntity, { access: { roles: ["Admin"] } }));
+  r.writeHandler(defineEntityDeleteHandler("item", itemEntity, { access: { roles: ["Admin"] } }));
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [feature],
+    jobs: {
+      consumerLane: "worker",
+      getActiveTenantIds: async () => [TestUsers.admin.tenantId],
+    },
+  });
+  await unsafeCreateEntityTable(stack.db, itemEntity, "item");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function createExpiredDeletedItem(user: typeof TestUsers.admin): Promise<string> {
+  const created = await stack.http.writeOk<{ id: string }>(
+    "sdcjob:write:item:create",
+    { label: `expired-${user.tenantId}` },
+    user,
+  );
+  await stack.http.writeOk("sdcjob:write:item:delete", { id: created.id }, user);
+  // kumiko-lint-ignore raw-sql test fixture ages deletedAt past the default grace period
+  await asRawClient(stack.db).unsafe(
+    `UPDATE fw2914_sdc_items SET deleted_at = now() - interval '400 days' WHERE id = $1`,
+    [created.id],
+  );
+  return created.id;
+}
+
+describe("soft-delete cleanup job smoke run on a tenant-filtered JobContext.db (fw#2914)", () => {
+  test("a per-tenant fan-out run purges only the active tenant's expired soft-deleted rows", async () => {
+    const ownId = await createExpiredDeletedItem(TestUsers.admin);
+    const foreignId = await createExpiredDeletedItem(TestUsers.otherTenant);
+    const jobRunner = stack.jobRunner;
+    if (!jobRunner) throw new Error("setupTestStack({ jobs }) did not wire a jobRunner");
+
+    await jobRunner.dispatch(SOFT_DELETE_CLEANUP_JOB, {});
+
+    await waitFor(async () => {
+      const own = await selectMany(stack.db, itemTable, { id: ownId });
+      expect(own).toHaveLength(0);
+    });
+    const foreign = await selectMany(stack.db, itemTable, { id: foreignId });
+    expect(foreign).toHaveLength(1);
+    expect(foreign[0]?.["isDeleted"]).toBe(true);
+  });
+});

package/src/engine/boot-validator/index.ts

@@ -1,4 +1,5 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
+import { dedupeFeatures } from "../dedupe-features";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
 import { validateAccessDeclarations } from "./access-declarations";
@@ -91,9 +92,10 @@ export type ValidateBootOptions = {
  * Throws on the first error found — fail fast.
  */
 export function validateBoot(
-  features: readonly FeatureDefinition[],
+  rawFeatures: readonly FeatureDefinition[],
   options?: ValidateBootOptions,
 ): void {
+  const features = dedupeFeatures(rawFeatures);
   const featureMap = new Map<string, FeatureDefinition>();
   for (const f of features) {
     featureMap.set(f.name, f);

package/src/engine/boot-validator/projection-list-screens.ts

@@ -96,7 +96,7 @@ function validateProjectionListFilterSchemaAcceptance(
   if (screen.filter === undefined || schemaAccepts(schema, "filter")) return;
   throw new Error(
     `${prefix}: declares filter but query "${screen.query}" has no "filter" parameter in its Zod ` +
-      `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","in"]), ` +
+      `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
       `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
   );
 }
@@ -203,7 +203,7 @@ function validateRelatedListParentFilter(
   if (!schemaAccepts(schema, "filter")) {
     throw new Error(
       `${prefix}: declares parentFilter but query "${section.query}" has no "filter" parameter in its ` +
-        `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","in"]), ` +
+        `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
         `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
     );
   }

package/src/engine/create-app.ts

@@ -1,4 +1,5 @@
 import { type ValidateBootOptions, validateBoot } from "./boot-validator";
+import { dedupeFeatures } from "./dedupe-features";
 import { createRegistry } from "./registry";
 import type { FeatureDefinition, Registry } from "./types";
 import { DEFAULT_CURRENCIES } from "./types";
@@ -20,6 +21,7 @@ export type App = {
 };
 
 export function createApp(config: AppConfig): App {
+  const features = dedupeFeatures(config.features);
   const validRoles = new Set(config.roles);
 
   // "system" is reserved for SYSTEM_USER — cannot be used as an app role
@@ -32,7 +34,7 @@ export function createApp(config: AppConfig): App {
 
   // Validate all roles referenced by features exist in app-defined roles.
   // openToAll access has no role list — nothing to validate there.
-  for (const feature of config.features) {
+  for (const feature of features) {
     for (const handler of Object.values(feature.writeHandlers)) {
       if (handler.access && "roles" in handler.access) {
         for (const role of handler.access.roles) {
@@ -83,7 +85,7 @@ export function createApp(config: AppConfig): App {
   const currencies = [...new Set([...DEFAULT_CURRENCIES, ...(config.currencies ?? [])])];
 
   // Validate defaultCurrency on entities that have money fields
-  for (const feature of config.features) {
+  for (const feature of features) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
       // A top-level money field isn't the only way an entity can hold money —
       // an embedded-list's sub-schema (e.g. invoice lines) can carry a money
@@ -110,10 +112,10 @@ export function createApp(config: AppConfig): App {
   }
 
   // Run boot-time validation before creating registry
-  validateBoot(config.features, config.validateBootOptions);
+  validateBoot(features, config.validateBootOptions);
 
   return {
-    registry: createRegistry(config.features),
+    registry: createRegistry(features),
     roles: config.roles,
     softDeleteDefault,
     currencies,

package/src/engine/dedupe-features.ts

@@ -0,0 +1,46 @@
+import type { FeatureDefinition } from "./types";
+
+function dedupeOptionsShallowEqual(
+  a: Readonly<Record<string, unknown>>,
+  b: Readonly<Record<string, unknown>>,
+): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+function isInterchangeable(existing: FeatureDefinition, next: FeatureDefinition): boolean {
+  if (existing === next) return true;
+  if (existing.dedupeOptions !== undefined && next.dedupeOptions !== undefined) {
+    return dedupeOptionsShallowEqual(existing.dedupeOptions, next.dedupeOptions);
+  }
+  return false;
+}
+
+// First occurrence wins: runtimes late-bind closure state (sessions' autoRevoke) on the kept instance.
+export function dedupeFeatures(features: readonly FeatureDefinition[]): FeatureDefinition[] {
+  const byName = new Map<string, FeatureDefinition>();
+  const result: FeatureDefinition[] = [];
+
+  for (const feature of features) {
+    const existing = byName.get(feature.name);
+    if (existing === undefined) {
+      byName.set(feature.name, feature);
+      result.push(feature);
+      continue;
+    }
+    if (isInterchangeable(existing, feature)) continue;
+    if (existing.dedupeOptions !== undefined && feature.dedupeOptions !== undefined) {
+      throw new Error(
+        `Duplicate feature: "${feature.name}" mounted twice with different options — mount it once or pass identical options`,
+      );
+    }
+    throw new Error(
+      `Duplicate feature: "${feature.name}" mounted twice as distinct instances — mount it once`,
+    );
+  }
+
+  return result;
+}