@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/dist/engine/role-assignment.js

@@ -1,4 +1,5 @@
 import { ROLES } from "../auth/roles.js";
+import { EXT_ASSIGNABLE_ROLE } from "./extension-names.js";
 import { isForbiddenMembershipRole } from "./membership-roles.js";
 const PLATFORM_ROLE_NAMES = new Set(Object.values(ROLES));
 // Prototype-free rank table — Object literals leak Object.prototype
@@ -15,18 +16,19 @@ const ROLE_RANKS = new Map([
     ["SystemAdmin", 4],
     ["system", 5],
 ]);
-// App roles are ordinary, non-privileged tiers: whoever may manage members
-// (access.admin) may grant them; an app raises the bar via assignableFrom.
-export const DEFAULT_APP_ROLE_ASSIGNABLE_FROM = "Admin";
-const NO_ASSIGNABLE_APP_ROLES = new Map();
-const ASSIGNABLE_FROM_ROLES = new Set([
+const ASSIGNABLE_FROM_ROLE_LIST = [
     "User",
     "Member",
     "Editor",
     "Admin",
     "TenantAdmin",
     "SystemAdmin",
-]);
+];
+// App roles are ordinary, non-privileged tiers: whoever may manage members
+// (access.admin) may grant them; an app raises the bar via assignableFrom.
+export const DEFAULT_APP_ROLE_ASSIGNABLE_FROM = "Admin";
+const NO_ASSIGNABLE_APP_ROLES = new Map();
+const ASSIGNABLE_FROM_ROLES = new Set(ASSIGNABLE_FROM_ROLE_LIST);
 function isAssignableFromRole(value) {
     return typeof value === "string" && ASSIGNABLE_FROM_ROLES.has(value);
 }
@@ -88,6 +90,24 @@ function requiredAssignRank(role, assignableAppRoles) {
     const assignableFrom = assignableAppRoles.get(role);
     return assignableFrom === undefined ? Number.POSITIVE_INFINITY : getRoleRank(assignableFrom);
 }
+export function canActorAssignRole(actorRoles, role, assignableAppRoles = NO_ASSIGNABLE_APP_ROLES) {
+    return requiredAssignRank(role, assignableAppRoles) <= maxRoleRank(actorRoles);
+}
+// An actor only removes what it could also grant; clients (the member form)
+// cannot render roles outside their option list, so those must survive a save.
+export function mergeAssignedRoles(actorRoles, assignedRoles, targetCurrentRoles, assignableAppRoles) {
+    const preserved = targetCurrentRoles.filter((role) => !assignedRoles.includes(role) && !canActorAssignRole(actorRoles, role, assignableAppRoles));
+    return [...new Set([...assignedRoles, ...preserved])];
+}
+const assignableAppRolesByRegistry = new WeakMap();
+export function assignableAppRolesOf(registry) {
+    const cached = assignableAppRolesByRegistry.get(registry);
+    if (cached !== undefined)
+        return cached;
+    const built = assignableAppRolesFromUsages(registry.getExtensionUsages(EXT_ASSIGNABLE_ROLE));
+    assignableAppRolesByRegistry.set(registry, built);
+    return built;
+}
 export function findForbiddenRoleAssignment(actorRoles, assignedRoles, 
 // Required so callers cannot accidentally disable the downgrade/
 // takeover guard by omitting the third argument (new users: pass []).
@@ -96,7 +116,7 @@ targetCurrentRoles, assignableAppRoles = NO_ASSIGNABLE_APP_ROLES) {
     // Assign path: fail-closed on unknown / above-actor roles — except unranked
     // app roles the target already holds (round-trip restore after strip).
     const forbiddenAssigned = assignedRoles.find((role) => {
-        if (requiredAssignRank(role, assignableAppRoles) <= actorRank)
+        if (canActorAssignRole(actorRoles, role, assignableAppRoles))
             return false;
         if (knownRoleRank(role) === undefined && targetCurrentRoles.includes(role))
             return false;

package/dist/engine/schema-builder.d.ts

@@ -3,7 +3,9 @@ import type { EntityDefinition, FieldDefinition } from "./types/index.js";
 export declare function isRepresentableAtScale(n: number, scale: number): boolean;
 export declare function fieldToZod(field: FieldDefinition, currencies: readonly string[], opts?: {
     readonly applyDefaults?: boolean;
+    readonly isUpdate?: boolean;
 }): z.ZodTypeAny;
+export declare const SYSTEM_ONLY_JSON_SCHEMA_KEY = "x-kumiko-system-only";
 export declare function buildInsertSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[], options?: {
     readonly allowCallerId?: boolean;
 }): z.ZodObject<Record<string, z.ZodTypeAny>>;

package/dist/engine/schema-builder.js

@@ -87,6 +87,13 @@ export function fieldToZod(field, currencies, opts = {}) {
             let schema = z.string();
             if (field.maxLength)
                 schema = schema.max(field.maxLength);
+            if (field.writeOnly === true) {
+                // Update: "" = unchanged (dropped before the executor), null = clear,
+                // unless required. Create: "" would leave a required field unset.
+                if (opts.isUpdate !== true)
+                    return field.required ? schema.min(1) : schema;
+                return field.required ? schema : schema.nullable();
+            }
             if (field.format === "email")
                 schema = schema.email();
             if (field.format === "url")
@@ -366,6 +373,7 @@ function applyTotalsMatchRefinements(entity, schema) {
 function notWritableField() {
     return z.never().optional();
 }
+export const SYSTEM_ONLY_JSON_SCHEMA_KEY = "x-kumiko-system-only";
 export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = [], options = {}) {
     const shape = {};
     for (const [name, field] of Object.entries(entity.fields)) {
@@ -380,8 +388,14 @@ export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES],
     }
     // Opt-in only for the generic create verb, which honors the id for system identities;
     // other schema consumers must keep stripping an unknown `id`.
-    if (options.allowCallerId)
-        shape["id"] = z.uuid().optional();
+    if (options.allowCallerId) {
+        // Marked so agent-facing exports can drop it: agent dispatch never runs as
+        // a system identity, so a caller-chosen id would be silently discarded.
+        shape["id"] = z
+            .uuid()
+            .optional()
+            .meta({ [SYSTEM_ONLY_JSON_SCHEMA_KEY]: true });
+    }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }
 export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = []) {
@@ -399,7 +413,10 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.
-        shape[name] = fieldToZod(field, currencies, { applyDefaults: false }).optional();
+        shape[name] = fieldToZod(field, currencies, {
+            applyDefaults: false,
+            isUpdate: true,
+        }).optional();
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }

package/dist/engine/screen-helpers.js

@@ -12,21 +12,32 @@ export function explicitListScreenId(screen) {
             return undefined;
     }
 }
+// Screen refs may be short ids or `<feature>:screen:<id>` QNs (boot-validator
+// accepts both for navigate targets and listScreenId); compare on the short id.
+function screenShortId(ref) {
+    return ref.slice(ref.lastIndexOf(":") + 1);
+}
 // Shared by the renderer breadcrumb and the boot-validator so both resolve
 // parents the same way; `getId` lets each caller normalize `screen.id`.
 export function resolveNavParentScreen(screens, detail, getId) {
-    const detailScreenId = getId(detail);
+    const detailScreenId = screenShortId(getId(detail));
     const listFromExplicit = (() => {
         const explicitId = explicitListScreenId(detail);
-        return explicitId !== undefined ? screens.find((s) => getId(s) === explicitId) : undefined;
+        return explicitId !== undefined
+            ? screens.find((s) => screenShortId(getId(s)) === screenShortId(explicitId))
+            : undefined;
     })();
     // rowActions, toolbarActions, and drawer-kind actions (which mount inline
     // and have no page of their own) all count as "reached from" this list.
-    const navigatesToDetail = (actions) => (actions ?? []).some((a) => (a.kind === "navigate" || a.kind === "drawer") && a.screen === detailScreenId);
+    const navigatesToDetail = (actions) => (actions ?? []).some((a) => (a.kind === "navigate" || a.kind === "drawer") &&
+        a.screen !== undefined &&
+        screenShortId(a.screen) === detailScreenId);
     // The create button of an entityList navigates to its createScreen, so the
     // list is that screen's parent just like for a rowAction target.
     const listFromRowAction = screens.find((s) => {
-        if (s.type === "entityList" && s.createScreen === detailScreenId)
+        if (s.type === "entityList" &&
+            s.createScreen !== undefined &&
+            screenShortId(s.createScreen) === detailScreenId)
             return true;
         if (s.type !== "entityList" && s.type !== "projectionList")
             return false;

package/dist/engine/steps/_event-match.js

@@ -48,6 +48,8 @@ function evaluateOp(op, actual) {
         case "ne":
             return actual !== op.value;
         case "in":
+            if (!Array.isArray(op.values))
+                throw malformed(`"in" op has no "values" array`);
             return op.values.some((value) => value === actual);
         case "gt":
         case "gte":
@@ -66,13 +68,28 @@ function evaluateOp(op, actual) {
         }
     }
 }
+// The AST round-trips through jsonb, so a truncated or hand-edited row must
+// fail with a readable format error rather than a bare TypeError.
+function malformed(what) {
+    return new Error(`Malformed EventMatch: ${what}`);
+}
 function evaluateExpr(expr, payload) {
+    if (!isRecord(expr))
+        throw malformed("expr is not an object");
     switch (expr.kind) {
         case "and":
-            return expr.nodes.every((node) => evaluateExpr(node, payload));
-        case "or":
-            return expr.nodes.some((node) => evaluateExpr(node, payload));
+        case "or": {
+            if (!Array.isArray(expr.nodes))
+                throw malformed(`"${expr.kind}" expr has no "nodes" array`);
+            return expr.kind === "and"
+                ? expr.nodes.every((node) => evaluateExpr(node, payload))
+                : expr.nodes.some((node) => evaluateExpr(node, payload));
+        }
         case "atom":
+            if (!Array.isArray(expr.path))
+                throw malformed(`"atom" expr has no "path" array`);
+            if (!isRecord(expr.op))
+                throw malformed(`"atom" expr has no "op" object`);
             return evaluateOp(expr.op, resolvePath(payload, expr.path));
         default: {
             const unrecognized = expr;
@@ -81,6 +98,8 @@ function evaluateExpr(expr, payload) {
     }
 }
 export function evaluateEventMatch(match, payload) {
+    if (!isRecord(match))
+        throw malformed("match is not an object");
     if (match.version !== 1) {
         throw new Error(`Unsupported EventMatch version ${JSON.stringify(match.version)} — expected 1`);
     }

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

@@ -1,7 +1,15 @@
 import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
+import { InternalError } from "../../errors/classes.js";
 // unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
 export function readSourceFor(ctx, unsafeAllTenants) {
     if (!unsafeAllTenants)
         return ctx.db;
+    // Step args come from untyped call sites too; a boolean `true` (the shape other
+    // framework APIs use) must fail as a framework error, not a TypeError on `.reason`.
+    if (typeof unsafeAllTenants !== "object" || typeof unsafeAllTenants.reason !== "string") {
+        throw new InternalError({
+            message: "unsafeAllTenants on a read step must be { reason: string }",
+        });
+    }
     return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
 }

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

@@ -6,7 +6,7 @@ export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap,
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, 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, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
+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, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, 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 { 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";

package/dist/engine/where-rule-lint.js

@@ -17,8 +17,9 @@ const SELF_COMPARISON_RE = new RegExp(`(${QUALIFIED_SRC})\\s*(?<![!<>=])=(?!=)\\
 const QUALIFIED_PARSE_RE = new RegExp(`^(${IDENT_SRC})(?:\\.(${IDENT_SRC}))?$`);
 // Resolve the SQL column names a table exposes, so the lint can tell a
 // real column reference apart from a table alias / function name / SQL
-// keyword. Returns an empty set when nothing is derivable (fail-open on
-// the lint itself would be worse than skipping it).
+// keyword. Returns an empty set when nothing is derivable; the column-aware
+// check then finds no bare column and is effectively skipped (only the
+// self-comparison check still applies).
 export function tableColumnSqlNames(table) {
     if (table === null || typeof table !== "object")
         return new Set();
@@ -131,16 +132,33 @@ function findSelfComparison(cleaned) {
 // column on the OUTER table is the fail-open shape — Postgres resolves it
 // against the innermost table first. A qualifier (`t.x`) or a table/alias
 // name immediately followed by `.` is not a column reference and is
-// ignored.
+// ignored. Bare identifiers on the outer level bind to the outer table and
+// are fine, so only tokens inside a `( SELECT ...` parenthesis block count.
+const SUBQUERY_OPEN_RE = /^\s*SELECT\b/i;
 function findUnqualifiedColumnReference(cleaned, columnSqlNames) {
+    const parenIsSubquery = [];
+    let subqueryDepth = 0;
+    let scanned = 0;
     TOKEN_RE.lastIndex = 0;
     let match = TOKEN_RE.exec(cleaned);
     while (match !== null) {
         const start = match.index;
         const end = start + match[0].length;
+        for (; scanned < start; scanned++) {
+            const ch = cleaned[scanned];
+            if (ch === "(") {
+                const opensSubquery = SUBQUERY_OPEN_RE.test(cleaned.slice(scanned + 1));
+                parenIsSubquery.push(opensSubquery);
+                if (opensSubquery)
+                    subqueryDepth++;
+            }
+            else if (ch === ")" && parenIsSubquery.pop() === true) {
+                subqueryDepth--;
+            }
+        }
         const precededByDot = start > 0 && cleaned[start - 1] === ".";
         const followedByDot = cleaned[end] === ".";
-        if (!precededByDot && !followedByDot) {
+        if (subqueryDepth > 0 && !precededByDot && !followedByDot) {
             const normalized = normalizeIdent(match[0]);
             if (columnSqlNames.has(normalized))
                 return normalized;

package/dist/env/index.js

@@ -57,6 +57,9 @@ export function kmsSlotsOf(schema) {
 // only exists after the boot-time decrypt, so requiring it here would reject
 // exactly the deployment this meta enables. safeExtend, not extend: Zod 4 throws
 // on extend for schemas carrying refinements (app-level superRefine).
+// Caveat: refinements run against the relaxed object, so they see such a slot as
+// `undefined` despite `z.infer<S>` promising a string. A refinement that reads the
+// slot must tolerate that; a throw from it is reported by parseEnv as a boot error.
 function relaxCiphertextOnlySlots(schema, env) {
     const shape = zodShape(schema);
     const relaxed = {};
@@ -227,6 +230,23 @@ export class KumikoBootError extends Error {
         return formatBootError(this.errors);
     }
 }
+// safeParse does not catch exceptions thrown inside refinements; a refinement
+// reading a ciphertext-only slot (undefined here) would otherwise escape as a raw
+// TypeError past the KumikoBootError mapping.
+function safeParseReportingThrows(schema, input) {
+    try {
+        return schema.safeParse(input);
+    }
+    catch (error) {
+        throw new KumikoBootError([
+            {
+                name: "<schema refinement>",
+                kind: "invalid",
+                message: `an env schema refinement threw: ${error instanceof Error ? error.message : String(error)}. If it reads a kms slot delivered only as <NAME>_CIPHERTEXT, the value is undefined at this point.`,
+            },
+        ]);
+    }
+}
 export function parseEnv(schema, env, options = {}) {
     // Filter undefined values to keep Zod's required-vs-invalid signal clean.
     // (process.env returns string|undefined; passing undefined would parse
@@ -236,7 +256,7 @@ export function parseEnv(schema, env, options = {}) {
         if (v !== undefined)
             cleaned[k] = v;
     }
-    const result = relaxCiphertextOnlySlots(schema, cleaned).safeParse(cleaned);
+    const result = safeParseReportingThrows(relaxCiphertextOnlySlots(schema, cleaned), cleaned);
     if (result.success) {
         // @cast-boundary schema-walk — z.infer<S> erasure across safeParse result
         return result.data;

package/dist/errors/reasons.d.ts

@@ -17,7 +17,6 @@ export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkRe
 export declare const AgentReasons: {
     readonly toolNotAllowed: "agent.tool_not_allowed";
     readonly iterationLimit: "agent.iteration_limit";
-    readonly permissionDenied: "agent.permission_denied";
     readonly highRiskNoAlways: "agent.high_risk_no_always";
 };
 export type AgentReason = (typeof AgentReasons)[keyof typeof AgentReasons];

package/dist/errors/reasons.js

@@ -13,8 +13,8 @@
 // reasons surface from the AI-agent runtime (tool dispatch, permission and
 // risk gates), not from a handler's own domain logic, and the `agent.`
 // prefix keeps them visibly distinct from FrameworkReasons in error payloads.
-// Both the docs site (`errors/` pages) and the enterprise repo read this same
-// source, so the prefix stays a naming convention here, not a new registry.
+// The docs site (`errors/` pages) reads this source; the enterprise repo keeps
+// its own AGENT_REASONS, so only reasons it actually emits belong in both.
 export const FrameworkReasons = {
     // ConflictError: atomic UPDATE lost the race (another writer moved the row
     // between our snapshot and our WHERE clause). Client SDK default: toast +
@@ -73,9 +73,6 @@ export const AgentReasons = {
     // Not thrown: the run ends with a `clarify` turn (`payload.reason`) once
     // MAX_AGENT_ROUNDS is reached.
     iterationLimit: "agent.iteration_limit",
-    // AccessDeniedError: the tool exists, but the caller's roles don't cover
-    // the handler behind it.
-    permissionDenied: "agent.permission_denied",
     // UnprocessableError: a permission rule with `always` was requested for an
     // `agent: { risk: "high" }` handler; `details.handlerQn` names it.
     highRiskNoAlways: "agent.high_risk_no_always",

package/dist/event-store/event-store.js

@@ -175,12 +175,17 @@ function buildStoredEvent(event, newVersion, eventVersion, row) {
 // style collision) must pass it to avoid folding a foreign type's events
 // into the loaded stream.
 export async function loadAggregate(db, aggregateId, tenantId, options) {
+    // "" must not fall through to the unfiltered load: a dynamically computed
+    // type that came out empty would silently fold in foreign aggregate types.
+    if (options?.aggregateType === "") {
+        throw new Error("loadAggregate: aggregateType must be a non-empty string when provided");
+    }
     if (!options?.includeArchived) {
         const archived = await isStreamArchived(db, tenantId, aggregateId);
         if (archived)
             return [];
     }
-    const rows = await selectMany(db, eventsTable, options?.aggregateType
+    const rows = await selectMany(db, eventsTable, options?.aggregateType !== undefined
         ? { aggregateId, tenantId, aggregateType: options.aggregateType }
         : { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
     return rows.map(toStoredEvent);

package/dist/event-store/provenance-append.js

@@ -1,6 +1,7 @@
 import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { runInSavepointIfSupported } from "../db/query.js";
 import { unsafeRawForDeclaredStep, withUnsafeRawGrant } from "../db/tenant-db.js";
+import { qnScope } from "../engine/qualified-name.js";
 import { AccessDeniedError, InternalError } from "../errors/index.js";
 import { append, getStreamVersion } from "./event-store.js";
 // Fixed by the framework, not the caller — the point of this entry point is
@@ -14,7 +15,9 @@ export async function appendProvenanceEvent(db, event) {
             message: `appendProvenanceEvent("${event.type}") — the "${SYSTEM_EVENT_PREFIX}" namespace is framework-internal and is not reachable through this entry point.`,
         });
     }
-    if (!event.type.includes(":")) {
+    // qnScope is the same owner definition appendDomainEventCore uses: a leading
+    // ":" (empty owner) counts as unowned there, so it must here too.
+    if (!qnScope(event.type) || event.type.endsWith(":")) {
         throw new InternalError({
             message: `appendProvenanceEvent("${event.type}") — event types must be owner-qualified ("<feature>:<name>"). Unowned types are not allowed here.`,
         });

package/dist/files/file-ref-entity.d.ts

@@ -9,6 +9,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -29,6 +30,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -49,6 +51,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -81,6 +84,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -101,6 +105,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -121,6 +126,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/files/file-ref-table.d.ts

@@ -9,6 +9,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -29,6 +30,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -49,6 +51,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -81,6 +84,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -101,6 +105,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -121,6 +126,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/files/file-routes.d.ts

@@ -14,7 +14,6 @@ export type FileRef = {
     entityId: string | null;
     fieldName: string | null;
     insertedById: string | null;
-    isDeleted: boolean;
 };
 export type FileAccessGuard = (args: {
     readonly fileRef: FileRef;

package/dist/files/file-routes.js

@@ -3,7 +3,7 @@ import { bodyLimit } from "hono/body-limit";
 import { getUser } from "../api/auth-middleware.js";
 import { requestContext } from "../api/request-context.js";
 import { selectMany } from "../bun-db/index.js";
-import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, } from "../crypto/index.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { createTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
@@ -106,11 +106,27 @@ export function createFileRoutes(options) {
         if (!isPiiCiphertext(fileRef.fileName))
             return fileRef.fileName;
         const kms = configuredPiiSubjectKms();
+        // skip: the framework has no logger at this route layer and the file bytes are
+        // still served; the "download" fallback only hides the stored ciphertext name.
         if (!kms) {
             return "download";
         }
-        const decrypted = await decryptPiiFieldValues({ fileName: fileRef.fileName }, piiSubjectFields, kms, kmsContextFor());
-        return typeof decrypted["fileName"] === "string" ? decrypted["fileName"] : "download";
+        try {
+            const decrypted = await decryptPiiFieldValues({ fileName: fileRef.fileName }, piiSubjectFields, kms, kmsContextFor());
+            const name = decrypted["fileName"];
+            // decryptPiiFieldValues returns the row untouched when fileName isn't
+            // annotated as PII (annotation drift), so ciphertext/erased sentinel
+            // can still be here and must never reach a header.
+            if (typeof name !== "string" || isPiiCiphertext(name) || name === PII_ERASED_SENTINEL) {
+                return "download";
+            }
+            return name;
+        }
+        catch {
+            // skip: broken crypto metadata (malformed ciphertext, auth failure, missing key)
+            // must not make intact bytes unreachable; the route layer has no logger.
+            return "download";
+        }
     }
     // Runs before parseBody buffers the request below: checks Content-Length
     // upfront, counts chunked bodies while streaming.
@@ -397,11 +413,10 @@ export function createFileRoutes(options) {
         if (!row)
             return c.json({ error: "not_found" }, 404);
         const fileRef = row; // @cast-boundary db-row (decrypted via executor.detail)
-        // detail()'s "pass"-ownership read widens to tenantId IN (self, SYSTEM)
-        // and doesn't filter isDeleted (list() does, detail() doesn't) — both
+        // detail()'s "pass"-ownership read widens to tenantId IN (self, SYSTEM),
         // narrower in loadFileForTenant's selectMany. Restore that here so meta
-        // doesn't leak reference-tenant or soft-deleted rows.
-        if (fileRef.tenantId !== user.tenantId || fileRef.isDeleted) {
+        // doesn't leak reference-tenant rows.
+        if (fileRef.tenantId !== user.tenantId) {
             return c.json({ error: "not_found" }, 404);
         }
         const decision = await guard({ fileRef, user, operation: "read" });

package/dist/files/local-provider.js

@@ -1,6 +1,6 @@
 import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { assertSafeStorageKey } from "./types.js";
 // Local-filesystem backend — intended for dev + tests. Production deploys
@@ -101,25 +101,28 @@ export function createLocalProvider(basePath) {
             }
         },
         async list(prefix) {
-            // recursive:true returns POSIX- or OS-sep-joined relative paths for
-            // both files and directories; normalize to "/" (storage keys are
-            // always "/"-joined, matching S3) before the prefix match, then stat
-            // only the (few) matches to drop directory entries.
+            // Walk only the directory part of the prefix: a tenant-scoped sweep must
+            // not traverse every other tenant's files in a shared storage root.
+            // Keys are normalized to "/" (storage keys are always "/"-joined,
+            // matching S3) before the final prefix match.
+            const prefixDir = prefix.slice(0, prefix.lastIndexOf("/") + 1);
+            const walkRoot = prefixDir === "" ? resolvedBase : resolveContainedPath(prefixDir);
             let entries;
             try {
-                entries = await readdir(resolvedBase, { recursive: true });
+                entries = await readdir(walkRoot, { recursive: true, withFileTypes: true });
             }
             catch (err) {
-                if (err.code === "ENOENT")
+                const code = err.code;
+                if (code === "ENOENT" || code === "ENOTDIR")
                     return [];
                 throw err;
             }
             const results = [];
             for (const entry of entries) {
-                const key = entry.split(sep).join("/");
-                if (!key.startsWith(prefix))
+                if (!entry.isFile())
                     continue;
-                if ((await stat(join(resolvedBase, entry))).isFile())
+                const key = relative(resolvedBase, join(entry.parentPath, entry.name)).split(sep).join("/");
+                if (key.startsWith(prefix))
                     results.push(key);
             }
             return results;