@cosmicdrift/kumiko-framework 0.353.0 → 0.354.0

package/dist/engine/ownership.js

@@ -108,10 +108,9 @@ export function userCanReadFieldRow(user, accessMap, row) {
         const rule = accessMap[role];
         if (!rule)
             continue;
-        // where-rules are SQL predicates (buildOwnershipClause); matchesRule
-        // can't evaluate them in-memory and throws. Read maps may legitimately
-        // carry one — it just belongs on the SQL path, so an in-memory read
-        // check denies rather than crashing.
+        // where-rules are SQL predicates; matchesRule can't evaluate them in-memory.
+        // The boot validator rejects them on field maps, so this only fails closed
+        // for maps that bypassed boot validation.
         // skip: where-rules are SQL-layer only — fail closed instead of throwing.
         if (rule !== "all" && rule.kind === "where")
             continue;

package/dist/engine/project-app-schema-for-roles.js

@@ -443,7 +443,9 @@ function dropUnreachableCreateScreen(screen, feature, keptScreenQns) {
     if (isScreenTargetKept(feature.featureName, screen.createScreen, keptScreenQns))
         return screen;
     const { createScreen: _unreachable, ...rest } = screen;
-    return rest;
+    // Marker, not a bare delete: the renderer treats a missing createScreen as
+    // "not set" and would fall back to the entity's edit form.
+    return { ...rest, createUnavailable: true };
 }
 function projectListScreen(original, feature, indices, keptScreenQns) {
     const screen = dropUnreachableCreateScreen(original, feature, keptScreenQns);

package/dist/engine/registry-ingest.d.ts

@@ -7,6 +7,7 @@ export declare function populateJobsAndNotifications(state: RegistryState, featu
 export declare function populateEvents(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateSystemEvents(state: RegistryState): void;
 export declare function populateTranslations(state: RegistryState, feature: FeatureDefinition): void;
+export declare function qualifyTranslationKey(featureName: string, key: string): string;
 export declare function populateHooks(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateExtensionsAndSeeds(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateMetricsAndSecrets(state: RegistryState, feature: FeatureDefinition): void;

package/dist/engine/registry-ingest.js

@@ -1,5 +1,6 @@
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { buildMetricName, validateMetricName } from "../observability/index.js";
+import { toKebab } from "./qualified-name.js";
 import { mergeHookList, mergeHookListQualified, qualify } from "./registry-state.js";
 import { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 // Feature registration + entities (globally-unique, physical-table-checked) + relations
@@ -149,12 +150,16 @@ export function populateTranslations(state, feature) {
     // bare and qualified spellings for the same key are accepted; if a
     // feature defines both, whichever is declared last wins (Object.entries
     // = insertion order, not "qualified always wins").
-    const prefix = `${feature.name}:`;
     for (const [key, value] of Object.entries(feature.translations ?? {})) {
-        const qualifiedKey = key.startsWith(prefix) ? key : `${prefix}${key}`;
-        state.mergedTranslations[qualifiedKey] = value;
+        state.mergedTranslations[qualifyTranslationKey(feature.name, key)] = value;
     }
 }
+// Handler QNs use the kebab scope, so a camelCase feature's full QN key
+// (`my-feature:write:x:title`) must count as qualified too.
+export function qualifyTranslationKey(featureName, key) {
+    const isQualified = key.startsWith(`${featureName}:`) || key.startsWith(`${toKebab(featureName)}:`);
+    return isQualified ? key : `${featureName}:${key}`;
+}
 // Lifecycle hooks (handler-targeted, qualified) + entity hooks (entity-targeted,
 // unprefixed) + search-payload-extensions (additive per entity).
 export function populateHooks(state, feature) {

package/dist/engine/run-pipeline.js

@@ -25,6 +25,7 @@ import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
 import { SUSPEND_SENTINEL } from "./steps/_step-dispatch-constants.js";
 import { RETURN_RESULT_KEY } from "./steps/return.js";
+import { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-step-error.js";
 export async function runPipeline(pipelineDef, event, handlerCtx, workflow, resumeFrom) {
     const steps = buildPipelineSteps(pipelineDef, event);
     const stepsAcc = {};
@@ -92,7 +93,17 @@ export async function runStepList(steps, event, handlerCtx, stepsAcc, scopeAcc,
                 workflow: { ...workflow, stepIndex: i },
             }),
         };
-        const value = await stepDef.run(instance.args, pipelineCtx);
+        let value;
+        try {
+            value = await stepDef.run(instance.args, pipelineCtx);
+        }
+        catch (error) {
+            // Workflow runs only: plain handler pipelines must keep surfacing the raw error to the
+            // dispatcher's error mapping. Nested lists re-wrap, so the outermost index wins.
+            if (!workflow)
+                throw error;
+            throw new WorkflowStepError(i, unwrapWorkflowStepError(error));
+        }
         // Tier-3 suspension: the step wrote a waiting event and returned
         // SUSPEND_SENTINEL to signal the pipeline should stop. The caller
         // (defineWorkflow/workflow-engine) persists the suspension state.

package/dist/engine/screen-helpers.d.ts

@@ -1,3 +1,4 @@
+import type { FieldDefinition, SelectFieldDef } from "./types/fields.js";
 import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, FieldCondition, FormatSpec, ListColumnSpec, ProjectionDetailScreenDefinition, ScreenDefinition, SecretMintScreenDefinition } from "./types/screen.js";
 export declare function explicitListScreenId(screen: ScreenDefinition): string | undefined;
 export declare function resolveNavParentScreen(screens: readonly ScreenDefinition[], detail: ScreenDefinition, getId: (screen: ScreenDefinition) => string): ScreenDefinition | undefined;
@@ -24,4 +25,16 @@ export declare function normalizeListColumn(c: ListColumnSpec): Exclude<ListColu
  *  (form-condition closures) reuse it; three hand-rolled copies had
  *  already drifted in shape. */
 export declare function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean;
+type SelectOptionRules = Pick<SelectFieldDef, "options" | "conditionalOptions">;
+export type UnavailableSelectOption = {
+    readonly field: string;
+    readonly value: string;
+    readonly allowed: readonly string[];
+};
+/** Options of a select field that are offered for the given row values, in declaration order. */
+export declare function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): readonly string[];
+/** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
+ *  checked when it or one of its condition fields changed, so legacy rows stay editable. */
+export declare function findUnavailableSelectOptions(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): readonly UnavailableSelectOption[];
 export declare function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string>;
+export {};

package/dist/engine/screen-helpers.js

@@ -110,6 +110,37 @@ export function evalFieldCondition(cond, values) {
         return !cond.notIn.includes(val);
     return val !== cond.ne;
 }
+/** Options of a select field that are offered for the given row values, in declaration order. */
+export function availableSelectOptions(field, values) {
+    const rules = field.conditionalOptions;
+    if (!rules || rules.length === 0)
+        return field.options;
+    return field.options.filter((option) => rules.every((rule) => !rule.options.includes(option) || evalFieldCondition(rule.when, values)));
+}
+function isSameValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
+ *  checked when it or one of its condition fields changed, so legacy rows stay editable. */
+export function findUnavailableSelectOptions(fields, values, previous) {
+    const unavailable = [];
+    for (const [name, def] of Object.entries(fields)) {
+        if (def.type !== "select" || !def.conditionalOptions)
+            continue;
+        const value = values[name];
+        if (typeof value !== "string" || value === "")
+            continue;
+        if (previous) {
+            const watched = [name, ...def.conditionalOptions.map((rule) => rule.when.field)];
+            if (watched.every((key) => isSameValue(values[key], previous[key])))
+                continue;
+        }
+        const allowed = availableSelectOptions(def, values);
+        if (!allowed.includes(value))
+            unavailable.push({ field: name, value, allowed });
+    }
+    return unavailable;
+}
 export function normalizeEditField(f) {
     return typeof f === "string" ? { field: f } : f;
 }

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

@@ -101,7 +101,8 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff } };
         if (isGlobalTenancyTable(proj.table)) {
-            await db.global(proj.table).deleteMany(where);
+            // db.global() rejects writes on executor-managed tables; a retention purge has no event to append.
+            await deleteMany(db.unsafeRaw(), proj.table, where);
         }
         else {
             await deleteMany(db, proj.table, where);
@@ -127,7 +128,7 @@ export function buildSoftDeleteCleanupSystemJob() {
         runIn: "worker",
         escapeHatch: {
             reason: "hard-deletes expired soft-deleted rows of global entities (e.g. user) once, system-wide",
-            grants: ["globalWrites"],
+            grants: ["unsafeRaw"],
         },
     };
 }

package/dist/engine/steps/_read-source.d.ts

@@ -1,6 +1,10 @@
 import type { DbRunner } from "../../db/connection.js";
+import type { WhereObject } from "../../db/query.js";
 import { type TenantDb } from "../../db/tenant-db.js";
 import type { PipelineCtx } from "../types/step.js";
 export declare function readSourceFor(ctx: PipelineCtx, unsafeAllTenants: {
     readonly reason: string;
 } | undefined): TenantDb | DbRunner;
+export declare function warnOnNarrowedForeignTenantFilter(ctx: PipelineCtx, stepKind: string, stepName: string, where: WhereObject | undefined, unsafeAllTenants: {
+    readonly reason: string;
+} | undefined): void;

package/dist/engine/steps/_read-source.js

@@ -1,5 +1,6 @@
 import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
 import { InternalError } from "../../errors/classes.js";
+import { SYSTEM_TENANT_ID } from "../types/identifiers.js";
 // unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
 export function readSourceFor(ctx, unsafeAllTenants) {
     if (!unsafeAllTenants)
@@ -13,3 +14,24 @@ export function readSourceFor(ctx, unsafeAllTenants) {
     }
     return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
 }
+// TenantDb silently narrows a foreign where.tenantId to the caller's scope; the step keeps that
+// behavior but makes the dropped filter visible, since it usually means a cross-tenant read was intended.
+export function warnOnNarrowedForeignTenantFilter(ctx, stepKind, stepName, where, unsafeAllTenants) {
+    // skip: explicit cross-tenant read, nothing was narrowed.
+    if (unsafeAllTenants)
+        return;
+    const requested = where?.["tenantId"];
+    // skip: no tenantId filter requested.
+    if (requested === undefined)
+        return;
+    const allowed = [ctx.db.tenantId, SYSTEM_TENANT_ID];
+    const requestedList = Array.isArray(requested) ? requested : [requested];
+    // skip: every requested tenant is within the caller's scope.
+    if (requestedList.every((t) => typeof t === "string" && allowed.includes(t)))
+        return;
+    ctx.log?.warn(`${stepKind} "${stepName}": where.tenantId is outside the caller's tenant scope and was narrowed`, {
+        step: stepKind,
+        name: stepName,
+        hint: "pass unsafeAllTenants: { reason } (with an escapeHatch on the handler) to read across tenants",
+    });
+}

package/dist/engine/steps/describe-workflow-step-error.js

@@ -1,6 +1,8 @@
 // Workflow events (run-failed, retry.scheduled) outlive an Art. 17 erase, and a
 // raw error message can echo recipients or payload fragments. Events carry only
 // this generic text; the raw error goes to the log.
+import { unwrapWorkflowStepError } from "./workflow-step-error.js";
 export function describeWorkflowStepError(error) {
-    return `workflow step failed (${error instanceof Error ? error.name : "unknown error"})`;
+    const original = unwrapWorkflowStepError(error);
+    return `workflow step failed (${original instanceof Error ? original.name : "unknown error"})`;
 }

package/dist/engine/steps/read-find-many.js

@@ -11,7 +11,7 @@
 // `limit` explicitly when the row-count could grow without bound.
 import { selectMany } from "../../db/query.js";
 import { defineStep } from "../define-step.js";
-import { readSourceFor } from "./_read-source.js";
+import { readSourceFor, warnOnNarrowedForeignTenantFilter } from "./_read-source.js";
 import { resolveOptional } from "./_resolver-utils.js";
 defineStep({
     kind: "read.findMany",
@@ -19,6 +19,7 @@ defineStep({
     resultKey: (args) => args.name,
     run: async (args, ctx) => {
         const where = resolveOptional(args.where, ctx);
+        warnOnNarrowedForeignTenantFilter(ctx, "read.findMany", args.name, where, args.unsafeAllTenants);
         const source = readSourceFor(ctx, args.unsafeAllTenants);
         const rows = await selectMany(source, args.table, where, args.limit !== undefined ? { limit: args.limit } : undefined);
         return rows;

package/dist/engine/steps/read-find-one.js

@@ -20,7 +20,7 @@
 // runtime check; reviewer responsibility.
 import { selectMany } from "../../db/query.js";
 import { defineStep } from "../define-step.js";
-import { readSourceFor } from "./_read-source.js";
+import { readSourceFor, warnOnNarrowedForeignTenantFilter } from "./_read-source.js";
 import { resolveRequired } from "./_resolver-utils.js";
 defineStep({
     kind: "read.findOne",
@@ -28,6 +28,7 @@ defineStep({
     resultKey: (args) => args.name,
     run: async (args, ctx) => {
         const where = resolveRequired(args.where, ctx);
+        warnOnNarrowedForeignTenantFilter(ctx, "read.findOne", args.name, where, args.unsafeAllTenants);
         const source = readSourceFor(ctx, args.unsafeAllTenants);
         const rows = await selectMany(source, args.table, where, { limit: 1 });
         return rows[0] ?? null;

package/dist/engine/steps/workflow-step-error.d.ts

@@ -0,0 +1,5 @@
+export declare class WorkflowStepError extends Error {
+    readonly stepIndex: number;
+    constructor(stepIndex: number, cause: unknown);
+}
+export declare function unwrapWorkflowStepError(error: unknown): unknown;

package/dist/engine/steps/workflow-step-error.js

@@ -0,0 +1,13 @@
+// Carries the top-level step index a workflow run failed at, so run-failed
+// events don't have to guess it. `cause` stays the original throw.
+export class WorkflowStepError extends Error {
+    stepIndex;
+    constructor(stepIndex, cause) {
+        super(`workflow step ${stepIndex} failed`, { cause });
+        this.stepIndex = stepIndex;
+        this.name = "WorkflowStepError";
+    }
+}
+export function unwrapWorkflowStepError(error) {
+    return error instanceof WorkflowStepError ? error.cause : error;
+}

package/dist/engine/transfer-adjacency.d.ts

@@ -0,0 +1,24 @@
+import type { EntityDefinition } from "./types/index.js";
+export declare const MAX_TRANSFER_DEPTH = 5;
+export type TransferEdgeLink = {
+    readonly kind: "parentRef";
+    readonly typeField: string;
+    readonly idField: string;
+} | {
+    readonly kind: "reference";
+    readonly field: string;
+};
+export type TransferEdge = {
+    readonly entityName: string;
+    readonly entity: EntityDefinition;
+    /** The already-resolved type this edge hangs off — its moved row ids are
+     *  the parent ids the mover matches this edge's rows against. */
+    readonly parentEntityName: string;
+    readonly link: TransferEdgeLink;
+};
+/** Outgoing edges per type: keyed by the type an edge hangs off, so the mover
+ *  can ask "what hangs off the rows I just moved" for any type it reaches, at
+ *  any depth, as often as it reaches it. */
+export type TransferAdjacency = ReadonlyMap<string, readonly TransferEdge[]>;
+export declare function resolveTransferAdjacency(entities: ReadonlyMap<string, EntityDefinition>, rootEntityType?: string): TransferAdjacency;
+export declare function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: readonly string[]): readonly string[] | undefined;

package/dist/engine/transfer-adjacency.js

@@ -0,0 +1,107 @@
+import { parseRefTargetEntityName } from "./parse-ref-target.js";
+// The single definition of the limit. It lives here rather than next to the
+// resolver in bundled-features because the dependency only runs that way:
+// bundled-features imports from the framework, never the reverse.
+//
+// Guards against a schema whose reference edges span more levels than anyone
+// intended — a runaway graph would move rows an operator never associated with
+// the handover. Deliberately a constant and not per-feature config: the limit
+// is a safety net, and a configurable one gets raised by whoever trips it
+// instead of prompting them to reconsider their graph.
+export const MAX_TRANSFER_DEPTH = 5;
+// A `multiple` reference stores a jsonb array rather than a single id column,
+// which the mover's `= ANY($ids)` match cannot address. The boot validator
+// (boot-validator/transfer-graph.ts) rejects that combination on transferable
+// entities, so skipping it here can only ever hit an entity that is not
+// transferable — never a silent partial move.
+// `handover: "stay"` is the declared opt-out: the reference crosses the tenant
+// boundary after a handover on purpose, so the edge is not walked.
+function referenceEdgesFrom(entityName, entity) {
+    const edges = [];
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+        if (field.type !== "reference")
+            continue;
+        if (field.multiple === true)
+            continue;
+        if (field.handover === "stay")
+            continue;
+        edges.push({
+            entityName,
+            entity,
+            parentEntityName: parseRefTargetEntityName(field.entity),
+            link: { kind: "reference", field: fieldName },
+        });
+    }
+    return edges;
+}
+// A parentRef names the types it accepts; without `allowedTypes` it accepts
+// any of them, so the edge is recorded against every registered type.
+function parentRefEdgesFrom(entityName, entity, allEntityNames) {
+    const parentRef = entity.parentRef;
+    if (!parentRef)
+        return [];
+    const link = {
+        kind: "parentRef",
+        typeField: parentRef.entityTypeField,
+        idField: parentRef.entityIdField,
+    };
+    return (parentRef.allowedTypes ?? allEntityNames).map((parentEntityName) => ({
+        entityName,
+        entity,
+        parentEntityName,
+        link,
+    }));
+}
+// The one definition of the transfer graph, shared by the boot validator
+// (depth limit) and the tenant-handover mover (traversal), so the limit that is
+// checked at boot is measured over exactly the edges that are walked at claim
+// time. Edges are kept for every entity, transferable or not: a
+// non-transferable node in the middle of a chain is still a hop the mover
+// takes before it fails the claim.
+//
+// A type can legitimately be reached by more than one edge — `note.vehicleId`
+// and `note.campaignId` are distinct, and collapsing them by entity name would
+// leave one edge's rows behind, the silent partial move #3088 exists to end.
+export function resolveTransferAdjacency(entities, rootEntityType) {
+    const allEntityNames = [...entities.keys()];
+    const byParent = new Map();
+    for (const [entityName, entity] of entities) {
+        // skip: the root is never collected as someone else's descendant. A self
+        // reference would otherwise drag unrelated rows of the root's own type
+        // across the tenant boundary along with the one that was claimed.
+        if (entityName === rootEntityType)
+            continue;
+        for (const edge of [
+            ...parentRefEdgesFrom(entityName, entity, allEntityNames),
+            ...referenceEdgesFrom(entityName, entity),
+        ]) {
+            const edges = byParent.get(edge.parentEntityName) ?? [];
+            edges.push(edge);
+            byParent.set(edge.parentEntityName, edges);
+        }
+    }
+    return byParent;
+}
+// `onPath` counts NODES, the limit counts EDGES: a chain of exactly
+// MAX_TRANSFER_DEPTH edges holds MAX_TRANSFER_DEPTH + 1 entities, and the
+// mover runs MAX_TRANSFER_DEPTH rounds of one hop each, so it still walks that
+// chain whole. Returns the first path that exceeds the limit.
+export function findOverDeepTransferChain(adjacency, onPath) {
+    if (onPath.length > MAX_TRANSFER_DEPTH + 1)
+        return onPath;
+    const startName = onPath[onPath.length - 1];
+    if (startName === undefined)
+        return undefined;
+    for (const edge of adjacency.get(startName) ?? []) {
+        // skip: a cycle revisits a type already on this path, and schema depth
+        // cannot measure how far it actually runs — that depends on the rows, not
+        // the declaration. The mover carries this one instead, failing with
+        // `transfer_graph_too_deep` when its rounds run out (#3131).
+        if (onPath.includes(edge.entityName))
+            continue;
+        const deeper = findOverDeepTransferChain(adjacency, [...onPath, edge.entityName]);
+        if (deeper !== undefined)
+            return deeper;
+    }
+    return undefined;
+}

package/dist/entrypoint/index.d.ts

@@ -30,6 +30,8 @@ type JobsBlock = {
     readonly onJobStart?: JobRunnerOptions["onJobStart"];
     readonly onJobComplete?: JobRunnerOptions["onJobComplete"];
     readonly onJobFailed?: JobRunnerOptions["onJobFailed"];
+    readonly onJobQueued?: JobRunnerOptions["onJobQueued"];
+    readonly onJobDropped?: JobRunnerOptions["onJobDropped"];
 };
 export type ApiEntrypointOptions = BaseEntrypointOptions & {
     readonly auth?: AuthRoutesConfig;

package/dist/entrypoint/index.js

@@ -176,6 +176,8 @@ function buildJobRunnerWithHook(registry, context, jobs, consumerLane, lifecycle
         onJobStart: jobs.onJobStart,
         onJobComplete: jobs.onJobComplete,
         onJobFailed: jobs.onJobFailed,
+        onJobQueued: jobs.onJobQueued,
+        onJobDropped: jobs.onJobDropped,
     });
     lifecycle.registerShutdownHook(hookName, async () => {
         await jobRunner.stop();

package/dist/env/index.js

@@ -135,6 +135,42 @@ export function withOptionalEnvKeys(schema, keys) {
     }
     return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
 }
+// The very same field instance is a shared fragment (several features read one
+// variable), not a conflict; the first declaring feature owns it.
+function isSharedFeatureFragment(featureFields, key, field) {
+    return featureFields.get(key) === field;
+}
+// Required beats optional, independent of feature order: a feature outside
+// optionalFeatures must not end up with a silently optional slot.
+function keepStrictestOfSharedFragment(merged, key, field, declaringFeatureIsOptional) {
+    if (!declaringFeatureIsOptional)
+        merged[key] = field;
+}
+function envVarConflictError(key, firstOwner, secondOwner) {
+    return new KumikoBootError([
+        {
+            name: key,
+            kind: "invalid",
+            message: `env-var conflict: "${key}" declared by both ` +
+                `"${firstOwner}" and "${secondOwner}" — pick one owner.`,
+        },
+    ]);
+}
+// The twin follows from the slot, so a versioned family (`…_V2`) needs no
+// second declaration. An already declared twin (apps that predate this) stays.
+function declareKmsCiphertextTwins(merged, sources, kmsFields) {
+    for (const { name, source } of kmsFields) {
+        const twin = `${name}_CIPHERTEXT`;
+        if (merged[twin] !== undefined)
+            continue;
+        merged[twin] = z
+            .string()
+            .min(1)
+            .optional()
+            .describe(`Key-Manager ciphertext of ${name}; used when ${name} is unset.`);
+        sources[twin] = source;
+    }
+}
 export function composeEnvSchema(options) {
     const optionalSet = new Set(options.optionalFeatures ?? []);
     const merged = {};
@@ -157,22 +193,20 @@ export function composeEnvSchema(options) {
             noteKms(key, field, "framework-core");
         }
     }
+    const featureFields = new Map();
     for (const feature of options.features) {
         if (!feature.envSchema)
             continue;
-        const shape = zodShape(feature.envSchema);
         const wrap = optionalSet.has(feature.name);
-        for (const [key, field] of Object.entries(shape)) {
+        for (const [key, field] of Object.entries(zodShape(feature.envSchema))) {
             if (merged[key] !== undefined) {
-                throw new KumikoBootError([
-                    {
-                        name: key,
-                        kind: "invalid",
-                        message: `env-var conflict: "${key}" declared by both ` +
-                            `"${sources[key]}" and "${feature.name}" — pick one owner.`,
-                    },
-                ]);
+                if (!isSharedFeatureFragment(featureFields, key, field)) {
+                    throw envVarConflictError(key, sources[key], feature.name);
+                }
+                keepStrictestOfSharedFragment(merged, key, field, wrap);
+                continue;
             }
+            featureFields.set(key, field);
             merged[key] = wrap ? optionalKeepingKmsMeta(field) : field;
             sources[key] = feature.name;
             noteKms(key, field, feature.name);
@@ -195,19 +229,7 @@ export function composeEnvSchema(options) {
             noteKms(key, field, "app");
         }
     }
-    // The twin follows from the slot, so a versioned family (`…_V2`) needs no
-    // second declaration. An already declared twin (apps that predate this) stays.
-    for (const { name, source } of kmsFields) {
-        const twin = `${name}_CIPHERTEXT`;
-        if (merged[twin] !== undefined)
-            continue;
-        merged[twin] = z
-            .string()
-            .min(1)
-            .optional()
-            .describe(`Key-Manager ciphertext of ${name}; used when ${name} is unset.`);
-        sources[twin] = source;
-    }
+    declareKmsCiphertextTwins(merged, sources, kmsFields);
     return {
         schema: z.object(merged),
         sources,

package/dist/errors/classes.d.ts

@@ -98,6 +98,14 @@ export declare class InternalError extends KumikoError {
     readonly httpStatus = 500;
     constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
 }
+export declare class MemberReadTimeoutError extends KumikoError {
+    readonly code = "member_read_timeout";
+    readonly httpStatus = 504;
+    constructor(opts: {
+        readonly timeoutMs: number;
+        readonly cause?: Error;
+    });
+}
 export type RateLimitDetails = {
     readonly bucket: string;
     readonly limit: number;

package/dist/errors/classes.js

@@ -189,6 +189,19 @@ export class InternalError extends KumikoError {
         });
     }
 }
+// A ctx.queryAsMember read ran into its statement timeout (SQLSTATE 57014). Reuses the generic
+// errors.internal i18n key: the client can do nothing but retry, and the code is for log/alert routing.
+export class MemberReadTimeoutError extends KumikoError {
+    code = "member_read_timeout";
+    httpStatus = 504;
+    constructor(opts) {
+        super({
+            message: `ctx.queryAsMember read exceeded its ${opts.timeoutMs}ms statement timeout`,
+            i18nKey: "errors.internal",
+            ...(opts.cause && { cause: opts.cause }),
+        });
+    }
+}
 export class RateLimitError extends KumikoError {
     code = "rate_limited";
     httpStatus = 429;

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export type { ErrorDocsConfig } from "./docs-url.js";
 export { resolveErrorDocsUrl } from "./docs-url.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
@@ -9,6 +9,7 @@ export type { AgentReason, FrameworkReason } from "./reasons.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
+export { subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export type { InvalidTransitionDetails } from "./transition-details.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";

package/dist/errors/index.js

@@ -1,9 +1,10 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { resolveErrorDocsUrl } from "./docs-url.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
+export { subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";
 export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";

package/dist/errors/reasons.d.ts

@@ -12,6 +12,7 @@ export declare const FrameworkReasons: {
     readonly publicIntakeRequired: "public_intake_required";
     readonly irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk";
     readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
+    readonly subjectErased: "subject_erased";
 };
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
 export declare const AgentReasons: {

package/dist/errors/reasons.js

@@ -61,6 +61,9 @@ export const FrameworkReasons = {
     // delegation via ctx.write/writeAs from a lower-risk handler does not
     // inherit the gate.
     instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk",
+    // ConflictError: a write touched a personal-data field of a data subject whose
+    // key was erased (crypto-shredding); the subject can no longer receive data.
+    subjectErased: "subject_erased",
 };
 // Reason codes the AI-agent runtime surfaces via `details.reason`. Kept as a
 // sister catalog to FrameworkReasons instead of extending it — see the

package/dist/errors/subject-erased.d.ts

@@ -0,0 +1,2 @@
+import { ConflictError } from "./classes.js";
+export declare function subjectErasedConflict(cause?: unknown): ConflictError;

package/dist/errors/subject-erased.js

@@ -0,0 +1,9 @@
+import { ConflictError } from "./classes.js";
+import { FrameworkReasons } from "./reasons.js";
+export function subjectErasedConflict(cause) {
+    return new ConflictError({
+        message: "the data subject was erased — its personal data can no longer be written",
+        details: { reason: FrameworkReasons.subjectErased },
+        ...(cause instanceof Error && { cause }),
+    });
+}