@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

package/dist/{stack/table-helpers.d.ts → db/table-push.d.ts}

@@ -1,13 +1,13 @@
-import type { DbConnection } from "../db/connection.js";
-import type { ColumnMeta, EntityTableMeta, IndexMeta } from "../db/entity-table-meta.js";
-import type { EventDispatcher } from "../pipeline/index.js";
+import type { EntityDefinition } from "../engine/types/index.js";
+import type { DbConnection } from "./connection.js";
+import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.js";
 /**
  * Bypass: creates an entity-table directly without going through the
  * full registry. Reserved for framework-internal meta-tables and
  * test setup — apps declare data via `r.entity(...)`.
  */
-export declare function unsafeCreateEntityTable(db: DbConnection, entity: import("../engine/types/index.js").EntityDefinition, entityName?: string): Promise<void>;
-export declare function unsafeEnsureEntityTable(db: DbConnection, entity: import("../engine/types/index.js").EntityDefinition, entityName?: string): Promise<boolean>;
+export declare function unsafeCreateEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<void>;
+export declare function unsafeEnsureEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<boolean>;
 export declare function tableToMeta(table: unknown): EntityTableMeta;
 /** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
 export declare function addMissingColumns(db: DbConnection, tableName: string, columns: readonly ColumnMeta[]): Promise<void>;
@@ -22,13 +22,3 @@ export declare function addMissingIndexes(db: DbConnection, tableName: string, i
  * entities go through `kumiko schema apply` (committed SQL files).
  */
 export declare function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>): Promise<void>;
-/**
- * Wipes event store + framework-state + the given feature read-models in
- * one TRUNCATE, then re-registers the event-consumer state rows. Used in
- * test beforeEach-hooks to return the stack to a clean slate without
- * rebuilding it.
- */
-export declare function resetEventStore(stack: {
-    db: unknown;
-    eventDispatcher?: EventDispatcher;
-}, extraTables?: readonly (unknown | string)[]): Promise<void>;

package/dist/{stack/table-helpers.js → db/table-push.js}

@@ -1,21 +1,9 @@
-import { pgTypeToSqlType } from "../db/dialect.js";
-import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement, } from "../db/queries/ddl.js";
-import { truncateTablesRestartIdentity } from "../db/queries/test-stack.js";
-import { renderTableDdl } from "../db/render-ddl.js";
-import { tableExists } from "../db/schema-inspection.js";
-import { buildEntityTable, toTableName } from "../db/table-builder.js";
-import { asEntityTableMeta, schemaTableName } from "../db/table-introspection.js";
-function tableNameOf(table) {
-    if (typeof table !== "object" || table === null) {
-        throw new Error("table-helpers: table is not a SchemaTable object");
-    }
-    const symbolName = schemaTableName(table);
-    if (symbolName !== undefined)
-        return symbolName;
-    if ("tableName" in table && typeof table.tableName === "string")
-        return table.tableName;
-    throw new Error("table-helpers: table has no name");
-}
+import { pgTypeToSqlType } from "./dialect.js";
+import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./queries/ddl.js";
+import { renderTableDdl } from "./render-ddl.js";
+import { tableExists } from "./schema-inspection.js";
+import { buildEntityTable, toTableName } from "./table-builder.js";
+import { asEntityTableMeta } from "./table-introspection.js";
 /**
  * Bypass: creates an entity-table directly without going through the
  * full registry. Reserved for framework-internal meta-tables and
@@ -96,31 +84,3 @@ export async function unsafePushTables(db, tables, prevTables) {
 function renderColumnType(col) {
     return pgTypeToSqlType(col.pgType);
 }
-/**
- * Wipes event store + framework-state + the given feature read-models in
- * one TRUNCATE, then re-registers the event-consumer state rows. Used in
- * test beforeEach-hooks to return the stack to a clean slate without
- * rebuilding it.
- */
-export async function resetEventStore(stack, extraTables = []) {
-    const frameworkTables = [
-        "kumiko_events",
-        "kumiko_event_consumers",
-        "kumiko_archived_streams",
-        "kumiko_snapshots",
-        "kumiko_projections",
-    ];
-    const extraNames = extraTables.map((t) => (typeof t === "string" ? t : tableNameOf(t)));
-    const truncateAndReregister = async () => {
-        await truncateTablesRestartIdentity(stack.db, [...frameworkTables, ...extraNames]);
-        await stack.eventDispatcher?.ensureRegistered();
-    };
-    // The dispatcher's own timer/LISTEN must not start a pass between the
-    // TRUNCATE and the consumer re-registration, so they are paused for the whole reset.
-    if (stack.eventDispatcher) {
-        await stack.eventDispatcher.withBackgroundPassesPaused(truncateAndReregister);
-    }
-    else {
-        await truncateAndReregister();
-    }
-}

package/dist/db/tenant-db.d.ts

@@ -37,6 +37,17 @@ export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, rea
 }): TenantDb;
 export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
 export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
+export type CreateTenantDbOptions = {
+    readonly db: DbRunner;
+    readonly tenantId: TenantId;
+    readonly mode?: TenantDbMode;
+    readonly tracer?: Tracer;
+    readonly meter?: Meter;
+    readonly signal?: AbortSignal;
+    readonly grants?: TenantDbGrants;
+};
+export declare function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+/** @deprecated Positional form, use createTenantDb({ db, tenantId, ... }). Run `bun kumiko-upgrade --apply` to rewrite call sites. Removed in the first release after 2026-10-29. */
 export declare function createTenantDb(db: DbRunner, tenantId: TenantId, mode?: TenantDbMode, tracer?: Tracer, meter?: Meter, signal?: AbortSignal, grants?: TenantDbGrants): TenantDb;
 export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };

package/dist/db/tenant-db.js

@@ -225,7 +225,7 @@ export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEs
 // same connection/transaction. For code that must run caller-supplied callbacks (e.g. config
 // validators) without handing them a cross-tenant view.
 export function scopeTenantDbToTenant(db, tenantId) {
-    return createTenantDb(tenantDbRunner(db), tenantId, "tenant");
+    return createTenantDb({ db: tenantDbRunner(db), tenantId, mode: "tenant" });
 }
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
@@ -311,7 +311,26 @@ export async function runInOwnTransaction(tenantDb, fn) {
     }
     return rebind(fn);
 }
-export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, signal, grants) {
+// Runners (postgres-js Sql/tx handles) are functions and RawDbClient mocks carry no own
+// `tenantId`/`db`, so a runner is never mistaken for the options object.
+function isCreateTenantDbOptions(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Object.hasOwn(value, "tenantId") &&
+        Object.hasOwn(value, "db"));
+}
+export function createTenantDb(dbOrOptions, tenantId, mode, tracer, meter, signal, grants) {
+    if (isCreateTenantDbOptions(dbOrOptions))
+        return buildTenantDb(dbOrOptions);
+    return buildTenantDb({ db: dbOrOptions, tenantId, mode, tracer, meter, signal, grants });
+}
+// Untyped JS callers or an `as` cast can still hand in undefined; a scoped handle
+// without a tenant would bind `tenant_id = NULL` instead of failing loudly.
+function buildTenantDb(options) {
+    const { db, tenantId, mode = "tenant", tracer, meter, signal, grants } = options;
+    if (tenantId === undefined) {
+        throw new InternalError({ message: "createTenantDb: tenantId is required" });
+    }
     if (meter)
         registerStandardMetrics(meter);
     const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
@@ -585,16 +604,32 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         },
     };
     declaredUnsafeRawRunners.set(tenantDb, grantedUnsafeRawRunner);
-    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, {
-        ...rebindGrants,
-        unsafeRaw: grant,
-        // db.global() writes are write-handler-only: a rebind (a hook's own grant) must not inherit them.
-        globalWrites: undefined,
+    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb({
+        db,
+        tenantId,
+        mode,
+        tracer,
+        meter,
+        signal,
+        grants: {
+            ...rebindGrants,
+            unsafeRaw: grant,
+            // db.global() writes are write-handler-only: a rebind (a hook's own grant) must not inherit them.
+            globalWrites: undefined,
+        },
     }));
     crossTenantRebinders.set(tenantDb, (reason, deferReport) => {
         if (!deferReport)
             report("acknowledge-cross-tenant", reason);
-        const acknowledged = createTenantDb(db, tenantId, "system", tracer, meter, signal, rebindGrants);
+        const acknowledged = createTenantDb({
+            db,
+            tenantId,
+            mode: "system",
+            tracer,
+            meter,
+            signal,
+            grants: rebindGrants,
+        });
         crossTenantUseReporters.set(acknowledged, (target) => report("acknowledge-cross-tenant", reason, target));
         return acknowledged;
     });
@@ -607,7 +642,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         }
         // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
         const txGrants = personalDataGate ? { ...rebindGrants, personalDataGate } : rebindGrants;
-        return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
+        return runInNewTransaction(db, (tx) => fn(createTenantDb({ db: tx, tenantId, mode, tracer, meter, signal, grants: txGrants })));
     });
     bindTenantDbRunner(tenantDb, db);
     if (grants?.writesDeniedReason !== undefined) {
@@ -619,9 +654,13 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
-// Tenant-mode TenantDb whose writes reach the registry's custom projections. The positional
-// undefineds of createTenantDb would hide a moved grants parameter from the type checker.
+// Tenant-mode TenantDb whose writes reach the registry's custom projections.
 export function createProjectingTenantDb(db, tenantId, projectionRegistry) {
-    return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionRegistry ? { projectionRegistry } : undefined);
+    return createTenantDb({
+        db,
+        tenantId,
+        mode: "tenant",
+        grants: projectionRegistry ? { projectionRegistry } : undefined,
+    });
 }
 export { asRawClient };

package/dist/derivatives/derivatives-context.d.ts

@@ -1,5 +1,5 @@
 import type { DerivativeRendererPlugin, DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
-import { type AnyDb } from "../bun-db/query.js";
+import { type AnyDb } from "../db/query.js";
 import type { Registry, TenantId } from "../engine/types/index.js";
 import type { FileContext } from "../files/file-handle.js";
 export type DerivativesContextDeps = {

package/dist/derivatives/derivatives-context.js

@@ -1,4 +1,4 @@
-import { fetchOne } from "../bun-db/query.js";
+import { fetchOne } from "../db/query.js";
 import { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_RENDERER, } from "../engine/extension-names.js";
 import { InternalError, NotFoundError } from "../errors/index.js";
 import { fileRefsTable } from "../files/file-ref-table.js";

package/dist/engine/boot-validator/gdpr-storage.js

@@ -1,7 +1,7 @@
 // Providers whose bytes do not survive a process restart. Only "inmemory"
 // today; extend if another ephemeral bundled provider lands.
 const EPHEMERAL_PROVIDERS = new Set(["inmemory"]);
-// Env vars file-provider-s3-env reads (see files-provider-s3/env-helper).
+// Env vars createFileProviderS3Feature({ fromEnv: true }) reads (see file-provider-s3/lib/env-helper).
 // Missing any → createS3ProviderFromEnv throws on the first file op.
 const S3_ENV_REQUIRED = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"];
 // Cross-feature GDPR storage guard (V1). Catches the failure class we shipped
@@ -31,7 +31,7 @@ export function validateGdprStoragePersistence(features) {
     const persistent = [...registeredProviders].filter((p) => !EPHEMERAL_PROVIDERS.has(p));
     if (persistent.length === 0) {
         // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-        console.warn("[kumiko:boot] user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount file-provider-s3 or file-provider-s3-env and select it via the file-foundation provider config.");
+        console.warn("[kumiko:boot] user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount createFileProviderS3Feature() or createFileProviderS3Feature({ fromEnv: true }) and select it via the file-foundation provider config.");
         // skip: ephemeral store already warned; the s3-env env-var check below is moot
         return;
     }
@@ -42,7 +42,7 @@ export function validateGdprStoragePersistence(features) {
         const missing = S3_ENV_REQUIRED.filter((v) => !process.env[v]);
         if (missing.length > 0) {
             // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-            console.warn(`[kumiko:boot] file-provider-s3-env is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`);
+            console.warn(`[kumiko:boot] createFileProviderS3Feature({ fromEnv: true }) (provider "s3-env") is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`);
         }
     }
 }

package/dist/engine/boot-validator/pii-retention.js

@@ -204,11 +204,11 @@ export function validatePiiAndRetention(feature) {
                     throw new Error(`[Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`);
                 }
                 const { whenAbsent } = annot.userOwned;
-                if (whenAbsent !== undefined && whenAbsent !== "tenant") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant".`);
+                if (whenAbsent !== undefined && whenAbsent !== "tenant" && whenAbsent !== "self") {
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" or "self" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant" (tenant key) or "self" (the row's own record key).`);
                 }
                 if (ownerField.required !== true && whenAbsent === undefined) {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, whenAbsent: "self" to encrypt them under the row's own record key (shreddable per record), or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
                 }
                 // Soft-Warning wenn das reference-target nicht offensichtlich user
                 // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind

package/dist/engine/boot-validator/record-owned.js

@@ -1,4 +1,4 @@
-// A recordOwned field is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
+// A recordOwned field (or one with whenAbsent: "self") is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
 // and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts) requires that id
 // to be a UUID — an entity with idType: "serial" would encrypt the field but
 // could never satisfy a forget-subject request for it.
@@ -8,9 +8,9 @@ export function validateRecordOwnedSubjects(feature) {
             continue;
         for (const [fieldName, field] of Object.entries(entity.fields)) {
             const annot = field; // @cast-boundary schema-walk
-            if (annot.recordOwned !== true)
+            if (annot.recordOwned !== true && annot.userOwned?.whenAbsent !== "self")
                 continue;
-            throw new Error(`[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`);
+            throw new Error(`[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned (or whenAbsent: "self") but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`);
         }
     }
 }

package/dist/engine/boot-validator/screens.js

@@ -7,6 +7,7 @@ import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs, SELECT_OPTION_TONES, } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isListFilterAllowed } from "../../db/entity-field-encryption.js";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { isEncryptedAtRest } from "../config-helpers.js";
@@ -230,7 +231,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
         if (!featureMap.has("form-draft")) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but the ` +
                 `bundled feature "form-draft" is not mounted — every resume would silently lose its ` +
-                `values. Add formDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
+                `values. Add createFormDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
                 `feature list.`);
         }
     }
@@ -550,6 +551,25 @@ function validateOptionsQueryFieldRefs(where, fieldName, payload, siblingFieldNa
 function isWriteOnlyField(fdef) {
     return fdef?.writeOnly === true; // @cast-boundary schema-walk
 }
+// A secret on a configEdit form keeps its value out of the client like an encrypted
+// config key does, and the secrets store only exists per tenant.
+function validateConfigEditSecretField(featureName, screen, fieldName, secretQn, featureMap) {
+    const where = `[Feature ${featureName}] Screen "${screen.id}" (configEdit) field "${fieldName}"`;
+    if (screen.configKeys[fieldName] !== undefined) {
+        throw new Error(`${where} is mapped in both configKeys and secretKeys — keep one.`);
+    }
+    if (screen.scope !== "tenant") {
+        throw new Error(`${where} maps secret "${secretQn}" on a ${screen.scope}-scope screen — secrets are tenant-scoped.`);
+    }
+    const fdef = screen.fields[fieldName];
+    if (fdef?.type !== "text" || !isWriteOnlyField(fdef)) {
+        throw new Error(`${where} maps secret "${secretQn}" but is no writeOnly text field — a stored secret never goes back to the client.`);
+    }
+    const declared = [...featureMap.values()].some((feature) => Object.values(feature.secretKeys ?? {}).some((def) => def.qualifiedName === secretQn));
+    if (!declared) {
+        throw new Error(`${where} → secret "${secretQn}" is not declared via r.secret() in any feature.`);
+    }
+}
 // Inline forms have no stored value to hide or keep: writeOnly there would
 // render a "set / keep" affordance with nothing behind it.
 function rejectWriteOnlyFormField(featureName, screenId, context, fieldName, fdef) {
@@ -1476,9 +1496,19 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 }
             }
             validateWizardLayout(feature.name, screenId, "configEdit", screen.layout, featureMap);
+            for (const fname of Object.keys(screen.secretKeys ?? {})) {
+                if (!fieldNames.has(fname)) {
+                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) secretKeys names unknown field "${fname}".`);
+                }
+            }
             // configKeys: jeder fieldName muss einen Mapping-Eintrag haben,
             // jeder qualifizierte Key muss in der Registry existieren.
             for (const fname of fieldNames) {
+                const secretQn = screen.secretKeys?.[fname];
+                if (secretQn !== undefined) {
+                    validateConfigEditSecretField(feature.name, screen, fname, secretQn, featureMap);
+                    continue;
+                }
                 const qualified = screen.configKeys[fname];
                 if (qualified === undefined) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" has ` +
@@ -1641,6 +1671,12 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter references unknown ` +
                         `field "${filterField}". Known fields: ${[...fieldNames].sort().join(", ")}`);
                 }
+                if (!isListFilterAllowed(entityDef, filterField, screen.filter)) {
+                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter references field ` +
+                        `"${filterField}" which is encrypted, personal or secret, so the list handler rejects ` +
+                        `this filter at runtime. Only op "eq" works on a personal field with find: "exact" or ` +
+                        `"fuzzy"; otherwise drop the filter or filter on another field.`);
+                }
                 const fieldDef = entityDef.fields[filterField];
                 if (fieldDef !== undefined && !isFieldFilterable(fieldDef)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter references field ` +

package/dist/engine/bridge-stub.d.ts

@@ -0,0 +1,4 @@
+import type { HandlerContext, SessionUser } from "./types/index.js";
+export declare function bridgeStub(opts?: {
+    readonly user?: SessionUser;
+}): Pick<HandlerContext, "query" | "queryAs" | "write" | "writeAs" | "appendEvent" | "unsafeAppendEvent" | "tryAppendEvent" | "fetchForWriting" | "loadAggregate" | "archiveStream" | "restoreStream" | "isStreamArchived" | "snapshotAggregate" | "loadAggregateWithSnapshot" | "queryProjection" | "resolveAuthClaims" | "resolveActiveMembership" | "queryAsMember" | "hasFeature" | "metrics" | "metricsFor" | "tracer" | "tz" | "locale" | "user">;

package/dist/engine/bridge-stub.js

@@ -0,0 +1,62 @@
+import { DEFAULT_LOCALE } from "../i18n/request-locale.js";
+import { createNoopMetricsHandle, getFallbackTracer } from "../observability/index.js";
+import { createTzContext } from "../time/index.js";
+import { createAnonymousUser } from "./system-user.js";
+// Test/service helper: cross-feature bridge methods that throw on use.
+//
+// Production code always receives a full HandlerContext from the Dispatcher's
+// buildHandlerContext (with real query/write closures). Some internal services
+// and tests construct a mini-context manually (typically just `{ db, registry }`)
+// to invoke a single handler. Those call sites don't use ctx.query/write —
+// the stubs make the TypeScript shape match while still failing loudly if
+// anything downstream accidentally reaches for them.
+//
+// Use: `{ db, registry, ...bridgeStub() }`
+const notAvailable = (what) => async () => {
+    throw new Error(`ctx.${what} not available in this context — use the dispatcher, not a stubbed handler context`);
+};
+// Noop observability — hand back the shared fallback tracer so ctx.tracer has
+// a valid Tracer shape. No allocations per call.
+const noopTracer = getFallbackTracer();
+export function bridgeStub(opts) {
+    // ctx.user is a convenience alias for event.user (see HandlerContext
+    // docs). Caller code expects the field; bridgeStub hands back a stub with
+    // anonymous default values when no user is passed explicitly. Test code
+    // that cares about identity passes its own SessionUser here and gets it
+    // back on ctx.
+    const stubUser = opts?.user ??
+        createAnonymousUser("00000000-0000-0000-0000-000000000000"); // @cast-boundary engine-bridge
+    return {
+        user: stubUser,
+        query: notAvailable("query"), // @cast-boundary engine-bridge
+        queryAs: notAvailable("queryAs"),
+        write: notAvailable("write"),
+        writeAs: notAvailable("writeAs"),
+        appendEvent: notAvailable("appendEvent"),
+        unsafeAppendEvent: notAvailable("unsafeAppendEvent"),
+        tryAppendEvent: notAvailable("tryAppendEvent"),
+        fetchForWriting: notAvailable("fetchForWriting"),
+        loadAggregate: notAvailable("loadAggregate"),
+        archiveStream: notAvailable("archiveStream"),
+        restoreStream: notAvailable("restoreStream"),
+        isStreamArchived: notAvailable("isStreamArchived"),
+        snapshotAggregate: notAvailable("snapshotAggregate"),
+        loadAggregateWithSnapshot: notAvailable("loadAggregateWithSnapshot"),
+        queryProjection: notAvailable("queryProjection"),
+        resolveAuthClaims: notAvailable("resolveAuthClaims"),
+        resolveActiveMembership: notAvailable("resolveActiveMembership"),
+        queryAsMember: notAvailable("queryAsMember"),
+        // Stub defaults to always-enabled — matches the dispatcher's behaviour
+        // when no effectiveFeatures resolver is wired (tests without toggles).
+        hasFeature: async () => true,
+        metrics: createNoopMetricsHandle(),
+        metricsFor: () => createNoopMetricsHandle(),
+        tracer: noopTracer,
+        // Real TzContext, not notAvailable — test code uses ctx.tz routinely,
+        // it isn't a "bridge" concept. Defaults to UTC.
+        tz: createTzContext(),
+        // Same reasoning as tz above — ctx.locale is always-present, not a
+        // bridge method. Defaults to DEFAULT_LOCALE.
+        locale: DEFAULT_LOCALE,
+    };
+}