@cosmicdrift/kumiko-framework 0.341.0 → 0.343.0

package/dist/db/migrate-runner.js

@@ -14,7 +14,7 @@
 // fehl mit klarer Fehlermeldung (production-DBs haben das alte SQL drin —
 // edit nachträglich = production-state inkonsistent mit committed-state).
 import { createHash } from "node:crypto";
-import { readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 // Adapter: extract raw postgres-js client from drizzle DbConnection,
 // or use Bun.sql instance directly. Either way `.unsafe()` is the
@@ -171,6 +171,16 @@ export function loadMigrationsFromDir(dir, preprocess) {
         };
     });
 }
+// Raw file texts in migration order, comments intact (loadMigrationsFromDir
+// strips them) — the retired-table scan reads them for DESTRUCTIVE markers.
+export function readMigrationSqlTexts(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort()
+        .map((file) => readFileSync(join(dir, file), "utf8"));
+}
 // Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
 async function executeRaw(db, sqlText) {
     await rawClient(db).unsafe(sqlText);

package/dist/db/projection-registry-binding.d.ts

@@ -0,0 +1,3 @@
+import type { Registry } from "../engine/types/index.js";
+export declare function bindProjectionRegistry(target: object, registry: Registry): void;
+export declare function projectionRegistryOf(target: object): Registry | undefined;

package/dist/db/projection-registry-binding.js

@@ -0,0 +1,12 @@
+// A WeakMap rather than a process-global registry: test files boot several
+// stacks in one process, each with its own Registry. Keys are TenantDbs and
+// per-grant runner proxies — never the shared pool or tx handle, which would
+// leak one dispatcher's registry onto sibling TenantDbs.
+const bindings = new WeakMap();
+export function bindProjectionRegistry(target, registry) {
+    bindings.set(target, registry);
+}
+// WeakMap.get never reads a property off target — safe for fail-closed guard Proxies.
+export function projectionRegistryOf(target) {
+    return bindings.get(target);
+}

package/dist/db/retired-framework-tables.d.ts

@@ -0,0 +1,10 @@
+import type { Snapshot } from "./migrate-generator.js";
+export type RetiredFrameworkTable = {
+    readonly tableName: string;
+    readonly sinceVersion: string;
+    readonly explanation: string;
+};
+export declare const retiredFrameworkTables: readonly RetiredFrameworkTable[];
+export declare function findRetiredTableDrops(priorMigrationsSql: readonly string[], nextSnapshot: Snapshot): readonly RetiredFrameworkTable[];
+export declare function findCommentedDropTables(migrationsSql: readonly string[], snapshot: Snapshot | null): readonly string[];
+export declare function isRetiredFrameworkTable(tableName: string): boolean;

package/dist/db/retired-framework-tables.js

@@ -0,0 +1,72 @@
+// Framework tables that a framework release stopped creating and whose data
+// was explicitly declared dispensable. `kumiko schema generate` drops them
+// for real (instead of the commented-out DESTRUCTIVE marker app tables get),
+// because the framework — not the app — owns the decision that the data is
+// gone. Without this, every app carried a stale table forever behind a
+// commented drop nobody uncomments.
+//
+// Add an entry only when the release notes state the data is not preserved.
+// A rename is NOT a retirement: the data lives on under the new name.
+export const retiredFrameworkTables = [
+    {
+        tableName: "read_job_runs",
+        sinceVersion: "0.210.0",
+        explanation: "replaced by store_job_runs; the job run history was not migrated (operational data, not a system of record)",
+    },
+];
+const IDENT = `"?([^"\\s(;,.]+)"?`;
+const CREATE_TABLE_RE = new RegExp(`^CREATE TABLE\\s+(?:IF NOT EXISTS\\s+)?${IDENT}`, "i");
+const DROP_TABLE_RE = new RegExp(`^DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+const COMMENTED_DROP_TABLE_RE = new RegExp(`^--\\s*DESTRUCTIVE:\\s*DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+// Last known state per table across all migrations, in order — so a
+// DROP followed by a re-CREATE (managed-projection recreate) counts as
+// "created", and a commented drop followed by an executable one as "dropped".
+function scanTableLifecycle(sqlTexts) {
+    const states = new Map();
+    for (const text of sqlTexts) {
+        for (const rawLine of text.split("\n")) {
+            const line = rawLine.trim();
+            const commentedDrop = COMMENTED_DROP_TABLE_RE.exec(line)?.[1];
+            if (commentedDrop !== undefined) {
+                states.set(commentedDrop, "commented-drop");
+                continue;
+            }
+            if (line.startsWith("--"))
+                continue;
+            const created = CREATE_TABLE_RE.exec(line)?.[1];
+            if (created !== undefined) {
+                states.set(created, "created");
+                continue;
+            }
+            const dropped = DROP_TABLE_RE.exec(line)?.[1];
+            if (dropped !== undefined)
+                states.set(dropped, "dropped");
+        }
+    }
+    return states;
+}
+function snapshotHasTable(snapshot, tableName) {
+    return snapshot?.tables.some((t) => t.tableName === tableName) ?? false;
+}
+// Retired tables the next migration must drop: a migration created them (or
+// carries a commented drop), none dropped them for real, and the schema no
+// longer declares them.
+export function findRetiredTableDrops(priorMigrationsSql, nextSnapshot) {
+    const states = scanTableLifecycle(priorMigrationsSql);
+    return retiredFrameworkTables.filter((retired) => {
+        const state = states.get(retired.tableName);
+        return ((state === "created" || state === "commented-drop") &&
+            !snapshotHasTable(nextSnapshot, retired.tableName));
+    });
+}
+// Tables a migration only carries as a commented DESTRUCTIVE drop although
+// the snapshot no longer has them: if they still exist in the live DB, the
+// drop was never made.
+export function findCommentedDropTables(migrationsSql, snapshot) {
+    return [...scanTableLifecycle(migrationsSql)]
+        .filter(([tableName, state]) => state === "commented-drop" && !snapshotHasTable(snapshot, tableName))
+        .map(([tableName]) => tableName);
+}
+export function isRetiredFrameworkTable(tableName) {
+    return retiredFrameworkTables.some((retired) => retired.tableName === tableName);
+}

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

@@ -5,6 +5,7 @@ import { type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmi
 import { asRawClient } from "../db/query.js";
 import type { EntityDefinition } from "../engine/types/fields.js";
 import { type TenantId } from "../engine/types/identifiers.js";
+import type { Registry } from "../engine/types/index.js";
 import { type Meter, type Tracer } from "../observability/index.js";
 import type { DbRunner } from "./connection.js";
 type Table = SchemaTable;
@@ -23,6 +24,7 @@ export type TenantDbGrants = {
     readonly report?: EscapeHatchReporter;
     readonly memberReadOnly?: boolean;
     readonly personalDataGate?: PersonalDataGate;
+    readonly projectionRegistry?: Registry;
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
 export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;

package/dist/db/tenant-db.js

@@ -4,6 +4,7 @@ import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, co
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
+import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
 import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
@@ -14,7 +15,7 @@ const personalDataGates = new WeakMap();
 // Lets createTenantDb(ctx.db.unsafeRaw(), ...) inherit the gate. Keyed by a
 // per-grant proxy, never the shared pool/tx: tagging that would gate every sibling TenantDb.
 const runnerPersonalDataGates = new WeakMap();
-function gatedRunner(runner, gate) {
+function gatedRunner(runner, gate, projectionRegistry) {
     const proxy = new Proxy(runner, {
         // Tagged-template calls need the real driver object as `this`.
         apply(target, _thisArg, args) {
@@ -33,7 +34,7 @@ function gatedRunner(runner, gate) {
                     }
                     const gatedArgs = [
                         ...args.slice(0, -1),
-                        (tx) => callback(gatedRunner(tx, gate)),
+                        (tx) => callback(gatedRunner(tx, gate, projectionRegistry)),
                     ];
                     return Reflect.apply(value, target, gatedArgs);
                 };
@@ -43,6 +44,8 @@ function gatedRunner(runner, gate) {
         // @cast-boundary proxy-erasure — Proxy<object> re-tags as the wrapped DbRunner shape.
     });
     runnerPersonalDataGates.set(proxy, gate);
+    if (projectionRegistry)
+        bindProjectionRegistry(proxy, projectionRegistry);
     return proxy;
 }
 // The executor passes its entity so the check does not depend on the table-name lookup.
@@ -119,7 +122,9 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
         report("unsafe-raw", forwardedDeclaredStep ? reason : (gate?.grant?.reason ?? reason));
         const runner = tenantDbRunner(db);
         const personalDataGate = personalDataGates.get(db);
-        return personalDataGate ? gatedRunner(runner, personalDataGate) : runner;
+        return personalDataGate
+            ? gatedRunner(runner, personalDataGate, projectionRegistryOf(db))
+            : runner;
     }
     const uncheckedSystemDb = {
         [SYSTEM_SCOPE_CHECK_BRAND]: true,
@@ -272,6 +277,11 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         registerStandardMetrics(meter);
     const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
     const personalDataGate = grants?.personalDataGate ?? runnerPersonalDataGates.get(db);
+    const projectionRegistry = grants?.projectionRegistry ?? projectionRegistryOf(db);
+    // Rebinders carry the resolved registry explicitly: a fresh tx handle is not tagged.
+    const rebindGrants = projectionRegistry && grants?.projectionRegistry === undefined
+        ? { ...grants, projectionRegistry }
+        : grants;
     function withDbSpan(operation, table, runner) {
         signal?.throwIfAborted();
         if (!tracer && !meter)
@@ -446,7 +456,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         }
         // Engine-forwarded steps carry their own declared reason; otherwise the grant's reason is audited.
         report("unsafe-raw", declaredStepReason ?? grants?.unsafeRaw?.reason ?? "");
-        return personalDataGate ? gatedRunner(db, personalDataGate) : db;
+        return personalDataGate ? gatedRunner(db, personalDataGate, projectionRegistry) : db;
     }
     const tenantDb = {
         tenantId,
@@ -509,10 +519,13 @@ 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, { ...grants, unsafeRaw: grant }));
+    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, {
+        ...rebindGrants,
+        unsafeRaw: grant,
+    }));
     crossTenantRebinders.set(tenantDb, (reason) => {
         report("acknowledge-cross-tenant", reason);
-        return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
+        return createTenantDb(db, tenantId, "system", tracer, meter, signal, rebindGrants);
     });
     ownTransactionRebinders.set(tenantDb, async (fn) => {
         if (grants?.memberReadOnly) {
@@ -522,12 +535,14 @@ 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 ? { ...grants, personalDataGate } : grants;
+        const txGrants = personalDataGate ? { ...rebindGrants, personalDataGate } : rebindGrants;
         return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
     });
     bindTenantDbRunner(tenantDb, db);
     if (personalDataGate)
         personalDataGates.set(tenantDb, personalDataGate);
+    if (projectionRegistry)
+        bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
 export { asRawClient };

package/dist/engine/boot-validator/index.d.ts

@@ -1,3 +1,4 @@
+import type { EnvelopeCipher } from "../../secrets/envelope-cipher.js";
 import type { FeatureDefinition } from "../types/index.js";
 export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
 export { collectWriteHandlerQns } from "./nav.js";
@@ -26,7 +27,17 @@ export type ValidateBootOptions = {
      *  `process.env`; runners pass their resolved env so a ciphertext-only
      *  key (already decrypted at boot) is visible to the probe. */
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The cipher the runner injects after validation (built from the app's
+     *  `masterKey` or the env keyring). Satisfies the availability check for
+     *  `encrypted: true` fields without an env KEK. */
+    readonly entityFieldCipher?: EnvelopeCipher;
 };
+/**
+ * Subset-safe slice of validateBoot for test stacks: nav references (screen,
+ * parent, workspace, tree actions), workspaces and nav cycles. The checks that
+ * need the whole app composition (screens, ref entities) run only in validateBoot.
+ */
+export declare function validateNavBootSubset(rawFeatures: readonly FeatureDefinition[]): void;
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.

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

@@ -34,6 +34,50 @@ export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
 export { collectWriteHandlerQns } from "./nav.js";
 export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline.js";
 export { MAX_TRANSFER_DEPTH } from "./transfer-graph.js";
+// Test stacks mount feature subsets, so a reference into a feature that is not
+// mounted cannot be judged: it counts as present. A reference into a mounted
+// feature must still resolve.
+function mountedPrefixOf(qn) {
+    return qn.split(":", 1)[0] ?? qn;
+}
+class PrefixTolerantSet extends Set {
+    mountedFeatures;
+    constructor(members, mountedFeatures) {
+        super(members);
+        this.mountedFeatures = mountedFeatures;
+    }
+    has(qn) {
+        return super.has(qn) || !this.mountedFeatures.has(mountedPrefixOf(qn));
+    }
+}
+class PrefixTolerantMap extends Map {
+    mountedFeatures;
+    constructor(members, mountedFeatures) {
+        super(members);
+        this.mountedFeatures = mountedFeatures;
+    }
+    has(qn) {
+        return super.has(qn) || !this.mountedFeatures.has(mountedPrefixOf(qn));
+    }
+}
+/**
+ * Subset-safe slice of validateBoot for test stacks: nav references (screen,
+ * parent, workspace, tree actions), workspaces and nav cycles. The checks that
+ * need the whole app composition (screens, ref entities) run only in validateBoot.
+ */
+export function validateNavBootSubset(rawFeatures) {
+    const features = dedupeFeatures(rawFeatures);
+    const mounted = new Set(features.map((f) => f.name));
+    const allNavQns = collectNavQns(features);
+    const tolerantScreens = new PrefixTolerantSet(collectScreenQns(features), mounted);
+    const tolerantNavs = new PrefixTolerantMap(allNavQns, mounted);
+    const tolerantWorkspaces = new PrefixTolerantMap(collectWorkspaceQns(features), mounted);
+    for (const feature of features) {
+        validateNavs(feature, tolerantScreens, tolerantNavs, tolerantWorkspaces);
+        validateWorkspaces(feature, tolerantNavs);
+    }
+    validateNavCycles(allNavQns);
+}
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.
@@ -187,7 +231,7 @@ export function validateBoot(rawFeatures, options) {
         // catches malformed keys (wrong length, bad base64) at boot instead of
         // on the first encrypted read in prod. An injected cipher (test seam,
         // custom KMS provider) satisfies the requirement without env keys.
-        validateEntityFieldEncryptionAvailable(options?.env);
+        validateEntityFieldEncryptionAvailable(options?.env, options?.entityFieldCipher);
     }
     if (hasFileFields && !(options?.env ?? process.env)[FILE_STORAGE_PROVIDER_ENV]) {
         throw new Error(`${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`);

package/dist/engine/boot-validator/query-output-columns.js

@@ -165,13 +165,13 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
     checkPanelField("deltaToneField", panel.deltaToneField);
 }
 // visibleWhen reads a flat record like stat panels; a typo'd field would hide
-// the panel forever without any message.
-function checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel) {
-    // skip: panel is always visible, no field to check
-    if (panel.visibleWhen === undefined)
+// the panel or screen forever without any message.
+function checkVisibleWhenField(queryHandlers, visibleWhen, owner) {
+    // skip: always visible, no field to check
+    if (visibleWhen === undefined)
         return;
-    const { query, field } = panel.visibleWhen;
-    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}" visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
+    const { query, field } = visibleWhen;
+    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `${owner} visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
 }
 function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
     for (const panel of screen.panels) {
@@ -184,7 +184,7 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
             }
         }
         else if (panel.kind === "screen") {
-            checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel);
+            checkVisibleWhenField(queryHandlers, panel.visibleWhen, `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}"`);
         }
         else if (panel.kind === "list") {
             const rowShape = resolveListRowShape(queryHandlers, panel.query, `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`);
@@ -197,6 +197,7 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
     }
 }
 function checkScreenOutputColumns(queryHandlers, featureName, screenId, screen) {
+    checkVisibleWhenField(queryHandlers, screen.visibleWhen, `[Feature ${featureName}] Screen "${screenId}" (${screen.type})`);
     if (screen.type === "projectionList") {
         checkProjectionListOutputColumns(queryHandlers, featureName, screenId, screen);
     }

package/dist/engine/boot-validator/query-refs.js

@@ -52,6 +52,9 @@ function checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screenTyp
     }
 }
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
+    if (screen.visibleWhen !== undefined) {
+        checkQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
+    }
     if (screen.type === "projectionList") {
         checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);
     }

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

@@ -636,6 +636,33 @@ function validateRecordActionRedirect(feature, screenId, screenKind, action, all
         validateRedirectTarget(feature, screenId, screenKind, action.redirect, allScreenQns);
     }
 }
+function validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap) {
+    const { visibleWhen, fallback } = screen;
+    const context = `[Feature ${feature.name}] Screen "${screenId}" (${screen.type})`;
+    if (visibleWhen === undefined && fallback !== undefined) {
+        throw new Error(`${context} declares fallback without visibleWhen.`);
+    }
+    if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
+        throw new Error(`${context} visibleWhen needs a non-empty query and field.`);
+    }
+    if (fallback !== undefined) {
+        validateScreenFallback(feature, screenId, screen.type, fallback, allScreenQns, featureMap);
+    }
+}
+function validateScreenFallback(feature, screenId, screenType, fallback, allScreenQns, featureMap) {
+    const context = `[Feature ${feature.name}] Screen "${screenId}" (${screenType})`;
+    validateScreenNavTarget(feature.name, screenId, screenType, "fallback", fallback, allScreenQns, feature.screens);
+    const fallbackQn = resolveScreenTargetQn(feature.name, fallback);
+    if (fallbackQn === qualifyEntityName(feature.name, "screen", screenId)) {
+        throw new Error(`${context} fallback points at the screen itself.`);
+    }
+    // A gated fallback could hide in turn and chain or cycle (A→B→A); one hop keeps the
+    // runtime gate trivially terminating.
+    const [fallbackFeatureName = "", , fallbackShortId = ""] = fallbackQn.split(":");
+    if (featureMap.get(fallbackFeatureName)?.screens[fallbackShortId]?.visibleWhen !== undefined) {
+        throw new Error(`${context} fallback "${fallback}" has its own visibleWhen; a fallback must always render.`);
+    }
+}
 function validateInlineFormNavTargets(feature, screenId, screen, kind, allScreenQns) {
     if (screen.redirect !== undefined) {
         validateRedirectTarget(feature, screenId, kind, screen.redirect, allScreenQns);
@@ -869,6 +896,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
     };
     for (const [screenId, screen] of Object.entries(feature.screens)) {
         validateScreenHasNavArea(feature, screenId, screen, featureMap);
+        validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap);
         if (screen.type === "custom") {
             if (!screen.renderer.react && !screen.renderer.native) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" has type="custom" but the renderer ` +

package/dist/engine/index.d.ts

@@ -74,7 +74,7 @@ export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
-export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EntityDefinition, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TenantId, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/index.js

@@ -68,5 +68,5 @@ export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, isAgentVisibleScreen, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export { runValidation } from "./validation.js";

package/dist/engine/soft-delete-cleanup.d.ts

@@ -1,9 +1,11 @@
 import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/config.js";
+import type { EntityDefinition } from "./types/index.js";
 export declare const SOFT_DELETE_CLEANUP_JOB = "soft-delete:job:cleanup";
 export declare const SOFT_DELETE_CLEANUP_SYSTEM_JOB = "soft-delete:job:cleanup-system";
 export declare const SOFT_DELETE_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
 export declare const DEFAULT_GRACE_DAYS = 30;
 export declare const softDeleteGraceDaysConfig: ConfigKeyDefinition;
+export declare function isSystemScopedSoftDeleteTable(table: unknown, entity: Pick<EntityDefinition, "tenancy">): boolean;
 export declare const softDeleteCleanupJob: JobHandlerFn;
 export declare const softDeleteCleanupSystemJob: JobHandlerFn;
 export declare function buildSoftDeleteCleanupJob(): JobDefinition;

package/dist/engine/soft-delete-cleanup.js

@@ -10,7 +10,7 @@
 // resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
 // table growth; irreversible event-log purging is data-retention's job
 // (pruneEvents), a separate, consumer-lag-guarded path.
-import { deleteMany } from "../db/query.js";
+import { asEntityTableMeta, deleteMany } from "../db/query.js";
 import { SYSTEM_USER_ID } from "./system-user.js";
 // qualifyEntityName convention (feature:type:kebab-name) with a reserved
 // "soft-delete" owner — no real feature owns these; the framework synthesizes
@@ -31,6 +31,18 @@ export const softDeleteGraceDaysConfig = {
     // existing silent-below-bound / audited-crossing behavior.
     bounds: { min: 1 },
 };
+function hasTenantIdColumn(table) {
+    return table["tenantId"] !== undefined;
+}
+// The entity declaration decides, not the column: a `tenancy: "global"` table
+// (e.g. user) still carries a tenantId column (SYSTEM_TENANT_ID), yet no
+// tenant-mode delete can ever match its rows.
+export function isSystemScopedSoftDeleteTable(table, entity) {
+    return entity.tenancy === "global" || !hasTenantIdColumn(table);
+}
+function isGlobalTenancyTable(table) {
+    return asEntityTableMeta(table)?.tenancy === "global";
+}
 export const softDeleteCleanupJob = async (_payload, ctx) => {
     const { db, registry } = ctx;
     if (!db || !registry) {
@@ -57,21 +69,18 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         const entity = registry.getEntity(proj.source);
         if (!entity?.softDelete)
             continue;
-        // @cast-boundary column-presence probe — identical access the executor's
-        // list() does on table["tenantId"] to decide tenant-scoping.
-        const hasTenantColumn = proj.table["tenantId"] !== undefined;
-        // System-global entities (no tenantId column, e.g. `user`) are NOT swept
+        // System-global entities (tenancy "global" or no tenantId column, e.g. `user`) are NOT swept
         // here: this handler runs once PER TENANT, so a tenant-scoped grace value
         // would purge every OTHER tenant's still-within-grace rows too (effective
         // grace = min() across all tenants). softDeleteCleanupSystemJob handles
         // these separately, once, with a fixed grace period.
-        if (!hasTenantColumn)
+        if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
         await deleteMany(db, proj.table, where);
     }
 };
-// System-global soft-deleted entities (no tenantId column) can't take a
+// System-global soft-deleted entities (tenancy "global" or no tenantId column) can't take a
 // per-tenant grace period — there's no "this tenant's view" of a row that
 // isn't scoped to any tenant. Runs once (not perTenant) with a fixed grace
 // period; a future system-scope config key could make this configurable
@@ -88,9 +97,15 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
         const entity = registry.getEntity(proj.source);
         if (!entity?.softDelete)
             continue;
-        if (proj.table["tenantId"] !== undefined)
+        if (!isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
-        await deleteMany(db, proj.table, { isDeleted: true, deletedAt: { lt: cutoff } });
+        const where = { isDeleted: true, deletedAt: { lt: cutoff } };
+        if (isGlobalTenancyTable(proj.table)) {
+            await db.global(proj.table).deleteMany(where);
+        }
+        else {
+            await deleteMany(db, proj.table, where);
+        }
     }
 };
 export function buildSoftDeleteCleanupJob() {
@@ -110,5 +125,9 @@ export function buildSoftDeleteCleanupSystemJob() {
         trigger: { cron: "15 3 * * *" },
         concurrency: "skip",
         runIn: "worker",
+        escapeHatch: {
+            reason: "hard-deletes expired soft-deleted rows of global entities (e.g. user) once, system-wide",
+            grants: ["globalWrites"],
+        },
     };
 }

package/dist/engine/types/index.d.ts

@@ -7,8 +7,8 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
-export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";
 export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";

package/dist/engine/types/index.js

@@ -1,7 +1,7 @@
 // Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
 // runtime helpers below that stay framework-side.
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-types/identifiers";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, isFileField } from "../field-helpers.js";

package/dist/env/index.d.ts

@@ -57,6 +57,9 @@ export type ComposedEnvSchema = {
      *  "app" from `extend`, or "framework-core" from `core`. */
     readonly sources: Readonly<Record<string, string>>;
 };
+/** Makes the named env keys optional while keeping their `kms` meta. Keys
+ *  missing from the schema shape are ignored. */
+export declare function withOptionalEnvKeys(schema: z.ZodObject<z.ZodRawShape>, keys: readonly string[]): z.ZodObject<z.ZodRawShape>;
 export declare function composeEnvSchema(options: ComposeEnvSchemaOptions): ComposedEnvSchema;
 export type EnvErrorKind = "missing" | "invalid";
 export type EnvError = {

package/dist/env/index.js

@@ -123,6 +123,18 @@ function optionalKeepingKmsMeta(field) {
         ? optional.meta({ kumiko: readKumikoMeta(field) })
         : optional;
 }
+/** Makes the named env keys optional while keeping their `kms` meta. Keys
+ *  missing from the schema shape are ignored. */
+export function withOptionalEnvKeys(schema, keys) {
+    const shape = zodShape(schema);
+    const relaxed = {};
+    for (const key of keys) {
+        const field = shape[key];
+        if (field)
+            relaxed[key] = optionalKeepingKmsMeta(field);
+    }
+    return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
+}
 export function composeEnvSchema(options) {
     const optionalSet = new Set(options.optionalFeatures ?? []);
     const merged = {};

package/dist/errors/docs-url.d.ts

@@ -0,0 +1,7 @@
+import type { KumikoError } from "./kumiko-error.js";
+/** Links an app's own error reasons to its own docs; without it only framework reasons carry a docsUrl. */
+export type ErrorDocsConfig = {
+    readonly baseUrl: string;
+    readonly reasons?: readonly string[] | "all";
+};
+export declare function resolveErrorDocsUrl(err: KumikoError, errorDocs?: ErrorDocsConfig): string | undefined;