@cosmicdrift/kumiko-types 0.413.1 → 0.415.0

package/dist/access-predicates.d.ts

@@ -1,4 +1,5 @@
 import type { AccessRule } from "./handlers.ts";
 export declare function isOpenToAllGranted(rule: AccessRule): boolean;
+export declare const ANONYMOUS_ROLE: "anonymous";
 export declare function isUiAccessGranted(access: AccessRule | undefined, userRoles: readonly string[] | undefined): boolean;
 export declare function isAnySignedInGranted(rule: AccessRule): boolean;

package/dist/access-predicates.js

@@ -11,7 +11,7 @@ export function isOpenToAllGranted(rule) {
         return false;
     return openToAll.reason.trim().length > 0;
 }
-const ANONYMOUS_ACCESS_ROLE = "anonymous";
+export const ANONYMOUS_ROLE = "anonymous";
 // UI-visibility predicate — DEFAULT-VISIBLE, the opposite stance from
 // `hasAccess` and the default-deny doc on AccessRule (handlers.ts): an unset `access`
 // means every signed-in user may see the screen/nav/workspace, not nobody.
@@ -28,7 +28,7 @@ export function isUiAccessGranted(access, userRoles) {
         return false;
     if (!("roles" in access))
         return false;
-    if (isAnySignedInGranted(access) && !userRoles.includes(ANONYMOUS_ACCESS_ROLE))
+    if (isAnySignedInGranted(access) && !userRoles.includes(ANONYMOUS_ROLE))
         return true;
     return access.roles.some((role) => userRoles.includes(role));
 }
@@ -38,5 +38,5 @@ export function isAnySignedInGranted(rule) {
     if (!("roles" in rule) || !("anySignedIn" in rule))
         return false;
     const anySignedIn = rule.anySignedIn;
-    return (anySignedIn === true && Array.isArray(rule.roles) && rule.roles.includes(ANONYMOUS_ACCESS_ROLE));
+    return anySignedIn === true && Array.isArray(rule.roles) && rule.roles.includes(ANONYMOUS_ROLE);
 }

package/dist/config.d.ts

@@ -56,7 +56,7 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
     readonly options?: readonly string[];
     /** Only on `type: "select"`: loads the options from this query (QN), contract
      *  `{ rows: { value, label, description?, group? }[] }`, labels shown verbatim. Mutually exclusive with
-     *  `options` and `allowPerRequest`. The write side does not check the value against
+     *  `options`. The write side does not check the value against
      *  the query result; the consuming feature validates it where it uses it. */
     readonly optionsQuery?: string;
     /** Payload sent with every `optionsQuery` call. Requires `optionsQuery`. `{ field }`
@@ -70,7 +70,6 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
     };
     readonly computed?: ConfigComputedFn<T>;
     readonly validate?: ConfigValidateFn<T>;
-    readonly allowPerRequest?: boolean;
     readonly required?: boolean;
     readonly env?: string;
     readonly inheritedToTenant?: boolean;
@@ -165,6 +164,8 @@ export type MaxPerTenantOptions = {
     readonly onLimit: "skip" | "defer";
     readonly deferMs?: number | undefined;
 };
+export declare const IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES: readonly ["rebuildable-derived-data", "high-risk-or-cron-pipeline", "per-dispatch-record-key"];
+export type IrreversibleWithoutEntryHandler = (typeof IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES)[number];
 export type JobDefinition = {
     readonly name: string;
     readonly handler: JobHandlerFn;
@@ -190,6 +191,7 @@ export type JobDefinition = {
     readonly tenantVisibleRun?: {
         readonly subjectFields?: readonly string[] | undefined;
     } | undefined;
+    readonly irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler | undefined;
 };
 export type NotificationRecipientFn = (result: import("./hooks.ts").SaveContext) => string | readonly string[] | {
     readonly tenant: string;

package/dist/config.js

@@ -1 +1,10 @@
-export {};
+// The only pipelines allowed to call an irreversible primitive (forget, hard delete, kms.eraseKey,
+// readAsInstruction write) without a directly dispatched entry handler. A new case is a framework change.
+//   rebuildable-derived-data   deletes derived data that is re-created from a reversible source
+//   high-risk-or-cron-pipeline runs behind a risk "high" handler or as a cron scan of expired data
+//   per-dispatch-record-key    the step-dispatcher erasing its per-dispatch record key
+export const IRREVERSIBLE_WITHOUT_ENTRY_HANDLER_CASES = [
+    "rebuildable-derived-data",
+    "high-risk-or-cron-pipeline",
+    "per-dispatch-record-key",
+];

package/dist/db-connection.d.ts

@@ -2,9 +2,6 @@ import type { SQL, TransactionSQL } from "bun";
 export type RawDbClient = {
     unsafe: (sql: string, params?: readonly unknown[]) => PromiseLike<readonly unknown[]>;
     begin: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
-    end?: (options?: {
-        timeout?: number;
-    }) => Promise<void>;
 };
 export type DbConnection = SQL | RawDbClient;
 export type DbTx = TransactionSQL | RawDbClient;

package/dist/define-handler.d.ts

@@ -9,7 +9,7 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly access: AccessRule;
     readonly description?: string;
     readonly agent?: AgentHandlerHints;
-    /** Set by the entity convention create/update handlers; see WriteHandlerDef.excludedFields. */
+    /** Set by the entity convention create/update handlers; a hand-written handler may declare it for its form, its own schema still decides what it accepts. See WriteHandlerDef.excludedFields. */
     readonly excludedFields?: readonly string[];
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;

package/dist/delivery-attempt-types.d.ts

@@ -0,0 +1,22 @@
+import type { DbConnection } from "./db-connection.ts";
+import type { NotifyPriority, SessionUser } from "./handlers.ts";
+import type { TenantId } from "./identifiers.ts";
+export type NotifyDeliveryStatus = "queued" | "sent" | "failed" | "skipped";
+export declare const DELIVERY_FAILURE_CODES: readonly ["timeout", "network_error", "redirect_blocked", "host_not_allowed", "missing_credentials", "invalid_address", "unexpected_response", "render_failed", "send_failed", "channel_error"];
+export declare const DELIVERY_SKIP_REASONS: readonly ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
+export type DeliveryFailureCode = (typeof DELIVERY_FAILURE_CODES)[number];
+export type DeliverySkipReason = (typeof DELIVERY_SKIP_REASONS)[number];
+export type DeliveryErrorCode = DeliveryFailureCode | DeliverySkipReason | `http_${number}`;
+export type ChatSendFailureCode = `http_${number}` | Exclude<DeliveryFailureCode, "render_failed" | "send_failed" | "channel_error">;
+export declare const HTTP_ERROR_CODE_PATTERN: RegExp;
+export declare function isDeliveryErrorCode(value: unknown): value is DeliveryErrorCode;
+export type DeliveryAttemptLogEntry = {
+    readonly notificationType: string;
+    readonly channel: string;
+    readonly recipientAddress: string | null;
+    readonly status: NotifyDeliveryStatus;
+    readonly error: DeliveryErrorCode | null;
+    readonly priority: NotifyPriority;
+};
+export type DeliveryAttemptLogFn = (entry: DeliveryAttemptLogEntry) => Promise<void>;
+export type DeliveryAttemptLogFactory = (user: SessionUser, tenantId: TenantId, deliveryDb?: DbConnection) => DeliveryAttemptLogFn;

package/dist/delivery-attempt-types.js

@@ -0,0 +1,31 @@
+// Closed vocabulary for delivery failures and skips. Only these values (plus
+// `http_<status>`) are ever stored or returned as a delivery error, never a raw
+// error message: provider errors can carry URLs, tokens and addresses.
+export const DELIVERY_FAILURE_CODES = [
+    "timeout",
+    "network_error",
+    "redirect_blocked",
+    "host_not_allowed",
+    "missing_credentials",
+    "invalid_address",
+    "unexpected_response",
+    "render_failed",
+    "send_failed",
+    "channel_error",
+];
+export const DELIVERY_SKIP_REASONS = [
+    "channel_disabled",
+    "preference_disabled",
+    "rate_limited",
+    "no_address",
+    "unsubscribed",
+    "duplicate_idempotency_key",
+];
+export const HTTP_ERROR_CODE_PATTERN = /^http_(\d{3})$/;
+export function isDeliveryErrorCode(value) {
+    if (typeof value !== "string")
+        return false;
+    return (HTTP_ERROR_CODE_PATTERN.test(value) ||
+        DELIVERY_FAILURE_CODES.some((code) => code === value) ||
+        DELIVERY_SKIP_REASONS.some((reason) => reason === value));
+}

package/dist/entity-table-meta-types.d.ts

@@ -30,6 +30,7 @@ export type EntityTableMeta = {
     readonly source: "managed" | "unmanaged";
     readonly piiSubjectFields?: readonly string[];
     readonly tenancy?: "global";
+    readonly systemRowsReadable?: true;
 };
 export type BuildEntityTableMetaOptions = {
     readonly featureName?: string;
@@ -42,4 +43,5 @@ export type UnmanagedTableInput = {
     readonly indexes?: readonly IndexMeta[];
     readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
     readonly tenancy?: EntityTenancy;
+    readonly systemRowsReadable?: true;
 };

package/dist/event-store-executor-types.d.ts

@@ -15,6 +15,7 @@ export type ParentVisibilityOption = {
     }>;
     readonly canReadEntity?: (entityName: string) => boolean;
     readonly resolveTable?: (entityName: string) => SchemaTable;
+    readonly globalHostIds?: ReadonlyMap<string, readonly string[]>;
 };
 export type ParentVisibilityGateOption = {
     readonly parentVisibility?: ParentVisibilityOption;
@@ -91,7 +92,9 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
     }) => Promise<WriteResult<SaveContext>>;
     delete: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & ParentVisibilityGateOption) => Promise<WriteResult<DeleteContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & ParentVisibilityGateOption & {
+        expect?: Readonly<Record<string, string | number | boolean | null>>;
+    }) => Promise<WriteResult<DeleteContext>>;
     forget: (payload: {
         id: EntityId;
     }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & ParentVisibilityGateOption) => Promise<WriteResult<DeleteContext>>;

package/dist/feature.d.ts

@@ -37,6 +37,7 @@ export type SecretKeyDefinition = {
     };
     readonly scope: "tenant";
     readonly required?: boolean;
+    readonly requiredWhenConfigSet?: string;
     readonly writeRoles?: readonly string[];
     readonly valueSchema?: ZodType<string>;
 };

package/dist/fields.d.ts

@@ -728,6 +728,8 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
      *  only for genuinely tenant-independent aggregates like `user`. The first
      *  event (create) is what's routed; updates resolve the stream tenant upstream. */
     readonly systemStream?: boolean;
+    /** Tenant sessions may read this entity's SYSTEM_TENANT_ID rows (shared templates, config defaults, catalogs). Without it the table's row level security hides them. Never set it on credential, session, secret or PII entities. */
+    readonly systemRowsReadable?: boolean;
     /** Lets token scopes release `<entity>.created/.updated/.deleted` as webhook events. Off by default: bundle entities can hold secrets. */
     readonly webhookEvents?: boolean;
     /** Schema version stamped on every lifecycle event (default 1, integer 1..999). Bump it together with a step in `eventMigrations`. */

package/dist/handler-context-facets.d.ts

@@ -40,9 +40,11 @@ export type HandlerEvents<TMap extends object = KumikoEventTypeMap> = {
     readonly load: (aggregateId: string, options?: {
         readonly asOf?: Temporal.Instant;
         readonly atVersion?: never;
+        readonly includeArchived?: boolean;
     } | {
         readonly atVersion?: number;
         readonly asOf?: never;
+        readonly includeArchived?: boolean;
     }) => Promise<readonly import("./event-store-types.ts").StoredEvent[]>;
     readonly archive: (aggregateId: string, args: {
         readonly aggregateType: string;
@@ -85,7 +87,7 @@ export type HandlerObservability = {
     readonly metricsFor: (featureName: string) => MetricsHandle;
     readonly meter?: Meter;
 };
-export type JobEvents = Pick<HandlerEvents, "append">;
+export type JobEvents = Pick<HandlerEvents, "append" | "load">;
 export type JobDispatch = Pick<HandlerDispatch, "write" | "writeAs" | "queryAs" | "queryAsMember">;
 export type JobObservability = Pick<HandlerObservability, "log" | "metricsFor" | "meter">;
 type PhaseWithoutTransaction = "events" | "notify" | "dispatch" | "lifecycle";
@@ -97,7 +99,8 @@ export type ReservationContext<TMap extends object = KumikoEventTypeMap> = Omit<
     readonly dispatch: Omit<HandlerDispatch, "write" | "writeAs">;
     readonly lifecycle: Omit<HandlerLifecycle, "afterCommit" | "afterRollback">;
 };
-/** ctx of `beforeTransaction`: external I/O and reads only, so the outside-transaction handles are gone too. */
+/** ctx of `beforeTransaction`: external I/O and reads only, so the outside-transaction handles are gone too.
+ *  A long external call that must also write (metering, provenance) belongs in `transaction: "perCommand"`. */
 export type BeforeTransactionContext<TMap extends object = KumikoEventTypeMap> = Omit<ReservationContext<TMap>, "db" | "systemDb"> & {
     readonly db: TenantDb & {
         readonly outsideTransaction: undefined;

package/dist/handler-context-services.d.ts

@@ -6,7 +6,7 @@ import type { EntityCache } from "./entity-cache.ts";
 import type { EnvelopeCipher } from "./envelope-cipher-types.ts";
 import type { FileContext } from "./file-handle-types.ts";
 import type { FileProviderResolver } from "./file-provider-resolver-types.ts";
-import type { EscapeHatchAuditSink, JobRunnerRef, NotifyFactory, NotifyFn, SessionUser, TenantWriteTarget } from "./handlers.ts";
+import type { DeliveryAttemptLogFn, EscapeHatchAuditSink, JobRunnerRef, NotifyFactory, NotifyFn, SessionUser, TenantWriteTarget } from "./handlers.ts";
 import type { TenantId } from "./identifiers.ts";
 import type { KmsAdapter } from "./kms-adapter-types.ts";
 import type { RateLimitResolver } from "./rate-limit-types.ts";
@@ -44,6 +44,7 @@ export type ContextServices = {
     readonly _notifyFactory?: NotifyFactory;
     readonly _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
     readonly _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+    readonly _logOwnDeliveryAttempt?: DeliveryAttemptLogFn;
     readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly extensions: Readonly<Record<string, unknown>>;
 };

package/dist/handlers.d.ts

@@ -4,6 +4,7 @@ import type { ZodType } from "zod";
 import type { CacheSyncBus } from "./cache-sync-types.ts";
 import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config.ts";
 import type { DbConnection, DbTx } from "./db-connection.ts";
+import type { DeliveryAttemptLogFactory, DeliveryAttemptLogFn, DeliveryErrorCode, NotifyDeliveryStatus } from "./delivery-attempt-types.ts";
 import type { DerivativesContext } from "./derivatives-types.ts";
 import type { EntityCache } from "./entity-cache.ts";
 import type { EventMetadata, WriteOrigin } from "./event-store-types.ts";
@@ -49,7 +50,7 @@ export declare function crossTenantReadsGrantFor(declaration: EscapeHatchDeclara
 export declare function escapeHatchGrantsProblem(declaration: {
     readonly grants?: unknown;
 }): string | undefined;
-export { isAnySignedInGranted, isOpenToAllGranted, isUiAccessGranted, } from "./access-predicates.ts";
+export { ANONYMOUS_ROLE, isAnySignedInGranted, isOpenToAllGranted, isUiAccessGranted, } from "./access-predicates.ts";
 export type SessionUserOrigin = "member-resolution";
 export type SessionUser = {
     readonly id: string;
@@ -142,6 +143,7 @@ export type JobRunnerRef = {
         readonly priority?: number;
         readonly jobId?: string;
     }): Promise<unknown>;
+    isJobPending?(jobName: string, jobId: string): Promise<boolean>;
 };
 export type DispatchWriteRef = {
     readonly write: (user: SessionUser, qn: string, payload: unknown, inheritedOrigin?: WriteOrigin) => Promise<WriteResult>;
@@ -162,15 +164,7 @@ export type NotifyOptions = {
     readonly immediate?: boolean;
     readonly locale?: string;
 };
-export type NotifyDeliveryStatus = "queued" | "sent" | "failed" | "skipped";
-export declare const DELIVERY_FAILURE_CODES: readonly ["timeout", "network_error", "redirect_blocked", "host_not_allowed", "missing_credentials", "invalid_address", "unexpected_response", "render_failed", "send_failed", "channel_error"];
-export declare const DELIVERY_SKIP_REASONS: readonly ["channel_disabled", "preference_disabled", "rate_limited", "no_address", "unsubscribed", "duplicate_idempotency_key"];
-export type DeliveryFailureCode = (typeof DELIVERY_FAILURE_CODES)[number];
-export type DeliverySkipReason = (typeof DELIVERY_SKIP_REASONS)[number];
-export type DeliveryErrorCode = DeliveryFailureCode | DeliverySkipReason | `http_${number}`;
-export type ChatSendFailureCode = `http_${number}` | Exclude<DeliveryFailureCode, "render_failed" | "send_failed" | "channel_error">;
-export declare const HTTP_ERROR_CODE_PATTERN: RegExp;
-export declare function isDeliveryErrorCode(value: unknown): value is DeliveryErrorCode;
+export { type ChatSendFailureCode, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, type DeliveryAttemptLogEntry, type DeliveryAttemptLogFactory, type DeliveryAttemptLogFn, type DeliveryErrorCode, type DeliveryFailureCode, type DeliverySkipReason, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, type NotifyDeliveryStatus, } from "./delivery-attempt-types.ts";
 export type NotifyDelivery = {
     readonly channel: string;
     readonly recipientId: string | null;
@@ -244,6 +238,8 @@ type SharedContextFields = {
     readonly _notifyFactory?: NotifyFactory;
     readonly _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
     readonly _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+    readonly _deliveryAttemptLogFactory?: DeliveryAttemptLogFactory;
+    readonly _logOwnDeliveryAttempt?: DeliveryAttemptLogFn;
     readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly secrets?: import("./secrets-types.ts").SecretsContext;
     readonly masterKeyProvider?: import("./secrets-types.ts").MasterKeyProvider;
@@ -268,9 +264,10 @@ export type AppContext = SharedContextFields & {
         readonly id: string;
         readonly tenantId: TenantId;
     } | null;
-    /** For job-handler calls triggered by an event
-     *  (`r.job` with `trigger: { on: ... }`): the qualified name of the event
-     *  that fired the trigger, e.g. `inbound-mail-foundation:event:inbound-message-received`.
+    /** For job-handler calls triggered by an `on` entry
+     *  (`r.job` with `trigger: { on: ... }`): the qualified name the entry matched,
+     *  either a write/query-handler QN (e.g. `multi:write:order:open`) or an
+     *  `r.defineEvent` QN (e.g. `inbound-mail-foundation:event:inbound-message-received`).
      *  For multi-trigger jobs (`on: [...]`), this is the only way for the
      *  handler to know which trigger fired. Cron and manual jobs leave the
      *  field undefined. */
@@ -348,7 +345,6 @@ export type JobContext = {
     readonly dispatch: JobDispatch;
     readonly triggerName?: string;
     readonly triggerEvent?: JobTriggerEvent;
-    readonly _tenantId?: TenantId;
     readonly config?: ConfigAccessor;
     readonly notify?: NotifyFn;
     readonly services: ContextServices;
@@ -546,7 +542,9 @@ export type BeforeTransactionResult<TPrepared = unknown> = {
     readonly release?: ReservationRelease;
 } | WriteFailure;
 export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: BeforeTransactionContext) => Promise<BeforeTransactionResult<TPrepared>>;
-/** `perCommand`: the handler runs without a transaction of its own. */
+/** `perCommand`: the handler runs without a transaction of its own. Use it for long external calls
+ *  (minutes) that also need writes: no transaction or connection is held while the call runs, and
+ *  `ctx.db.outsideTransaction` stays available for metering/provenance bookings. */
 export type WriteHandlerTransactionMode = "perCommand";
 /** `skip`: run as a nested write without the `beforeTransaction` phase. */
 export type BeforeTransactionWhenNested = "skip";
@@ -558,6 +556,9 @@ export type WriteHandlerDef = {
     readonly name: string;
     readonly schema: ZodType;
     readonly handler: WriteHandlerFn;
+    /** Set only by defineEntityWriteHandler, which wires the parent-ref visibility gate.
+     *  The boot-validator requires it on a `parentRef` entity's update/delete/restore handler. */
+    readonly [ENTITY_CONVENTION_WRITE_BRAND]?: true;
     readonly access: AccessRule;
     readonly description?: string;
     readonly agent?: AgentHandlerHints;
@@ -600,6 +601,7 @@ export type WriteHandlerDef = {
     readonly perform?: import("./step.ts").PipelineDef;
 };
 export declare const ENTITY_CONVENTION_QUERY_BRAND = "__kumikoEntityConventionQuery";
+export declare const ENTITY_CONVENTION_WRITE_BRAND = "__kumikoEntityConventionWrite";
 export type QueryHandlerDef = {
     readonly name: string;
     readonly schema: ZodType;

package/dist/handlers.js

@@ -39,38 +39,8 @@ export function escapeHatchGrantsProblem(declaration) {
     }
     return undefined;
 }
-export { isAnySignedInGranted, isOpenToAllGranted, isUiAccessGranted, } from "./access-predicates.js";
-// Closed vocabulary for delivery failures and skips. Only these values (plus
-// `http_<status>`) are ever stored or returned as a delivery error, never a raw
-// error message: provider errors can carry URLs, tokens and addresses.
-export const DELIVERY_FAILURE_CODES = [
-    "timeout",
-    "network_error",
-    "redirect_blocked",
-    "host_not_allowed",
-    "missing_credentials",
-    "invalid_address",
-    "unexpected_response",
-    "render_failed",
-    "send_failed",
-    "channel_error",
-];
-export const DELIVERY_SKIP_REASONS = [
-    "channel_disabled",
-    "preference_disabled",
-    "rate_limited",
-    "no_address",
-    "unsubscribed",
-    "duplicate_idempotency_key",
-];
-export const HTTP_ERROR_CODE_PATTERN = /^http_(\d{3})$/;
-export function isDeliveryErrorCode(value) {
-    if (typeof value !== "string")
-        return false;
-    return (HTTP_ERROR_CODE_PATTERN.test(value) ||
-        DELIVERY_FAILURE_CODES.some((code) => code === value) ||
-        DELIVERY_SKIP_REASONS.some((reason) => reason === value));
-}
+export { ANONYMOUS_ROLE, isAnySignedInGranted, isOpenToAllGranted, isUiAccessGranted, } from "./access-predicates.js";
+export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, } from "./delivery-attempt-types.js";
 export function normalizeEventPiiSubject(spec) {
     if ("subjectField" in spec) {
         return { kind: "user", ownerField: spec.subjectField, whenAbsent: undefined };
@@ -122,3 +92,5 @@ export function isRateLimitDisabled(v) {
 // workspace can evaluate a module twice, and two Symbol() calls would not
 // compare equal across those instances.
 export const ENTITY_CONVENTION_QUERY_BRAND = "__kumikoEntityConventionQuery";
+// Same brand for the update/delete/restore handlers built by defineEntityWriteHandler.
+export const ENTITY_CONVENTION_WRITE_BRAND = "__kumikoEntityConventionWrite";

package/dist/hooks.d.ts

@@ -16,6 +16,7 @@ export type SaveContext = {
     readonly isNew: boolean;
     readonly entityName?: string | undefined;
     readonly event: StoredEvent;
+    readonly claimedFileRefIds?: readonly string[] | undefined;
 };
 export type DeleteContext = {
     readonly kind: "delete";

package/dist/identifiers.d.ts

@@ -1,6 +1,13 @@
 export type TenantId = string;
 export declare const UUID_SHAPE_PATTERN = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
 export declare function isUuid(value: unknown): value is string;
+export type FileHandleParts = {
+    readonly id: string;
+    readonly claim: string;
+};
+export declare function parseFileHandle(value: unknown): FileHandleParts | null;
+export declare function isFileHandle(value: unknown): value is string;
+export declare function formatFileHandle(parts: FileHandleParts): string;
 export declare function parseTenantId(value: unknown): TenantId | null;
 export declare const SYSTEM_TENANT_ID: TenantId;
 export declare function isSystemTenant(tenantId: TenantId | null | undefined): boolean;

package/dist/identifiers.js

@@ -20,6 +20,26 @@ const TENANT_ID_REGEX = new RegExp(UUID_SHAPE_PATTERN);
 export function isUuid(value) {
     return typeof value === "string" && TENANT_ID_REGEX.test(value);
 }
+// Opaque reference to a pending anonymous upload: `<fileRef uuid>.<claim>`. The claim is 32 random
+// bytes, base64url; the server stores only its hash. Field values accept this form and persist
+// the bare uuid.
+const FILE_HANDLE_CLAIM_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+export function parseFileHandle(value) {
+    if (typeof value !== "string")
+        return null;
+    const separator = value.indexOf(".");
+    if (separator === -1)
+        return null;
+    const id = value.slice(0, separator);
+    const claim = value.slice(separator + 1);
+    return isUuid(id) && FILE_HANDLE_CLAIM_PATTERN.test(claim) ? { id, claim } : null;
+}
+export function isFileHandle(value) {
+    return parseFileHandle(value) !== null;
+}
+export function formatFileHandle(parts) {
+    return `${parts.id}.${parts.claim}`;
+}
 // Validates a candidate string against the tenantId format and returns it
 // as a TenantId, or `null` when it doesn't match. Use at every system
 // boundary that admits untrusted input (HTTP headers, cookies, query

package/dist/minor-units.d.ts

@@ -0,0 +1,3 @@
+export declare const MINOR_UNIT_SCALE = 100;
+export declare function toMajorUnits(minorAmount: number): number;
+export declare function toMinorUnits(amount: number): number;

package/dist/minor-units.js

@@ -0,0 +1,11 @@
+// 2 decimal places (cents) — covers every currently-supported currency
+// (EUR/USD/GBP/...). No ISO-4217 minor-unit table yet (JPY=0, BHD=3) —
+// upgrade path once a currency needing a different scale actually lands.
+// Client-safe on purpose: db/money.ts pulls in engine runtime values.
+export const MINOR_UNIT_SCALE = 100;
+export function toMajorUnits(minorAmount) {
+    return minorAmount / MINOR_UNIT_SCALE;
+}
+export function toMinorUnits(amount) {
+    return Math.round(amount * MINOR_UNIT_SCALE);
+}

package/dist/multi-stream-apply-context-types.d.ts

@@ -8,7 +8,9 @@ import type { AppendEventFn, UnsafeAppendEventFn } from "./handlers.ts";
 import type { SecretsContext } from "./secrets-types.ts";
 export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
     readonly appendEvent: AppendEventFn<TMap>;
-    readonly unsafeAppendEvent: UnsafeAppendEventFn;
+    readonly unsafeAppendEvent: (args: Parameters<UnsafeAppendEventFn>[0] & {
+        readonly expectedVersion?: number;
+    }) => Promise<void>;
     readonly loadAggregate: (aggregateId: string, options?: {
         readonly asOf?: Temporal.Instant;
     }) => Promise<readonly StoredEvent[]>;

package/dist/named-list-filters.d.ts

@@ -16,8 +16,47 @@ export type NamedListFilterDef = {
     readonly access?: AccessRule;
     readonly filters: (scope: NamedListFilterScope) => readonly NamedListFilterCondition[] | Promise<readonly NamedListFilterCondition[]>;
 };
+export type ListSortDir = "asc" | "desc";
+export type ListSortSpec = {
+    readonly field: string;
+    readonly dir: ListSortDir;
+};
+/** One entry of a list's "Sorted by" select; `label` is an i18n key. */
+export type ListSortOption = ListSortSpec & {
+    readonly label: string;
+};
 /** Screen-side reference to an entity-defined named filter; `label` is an i18n key. */
 export type NamedListFilterRef = {
     readonly id: string;
     readonly label: string;
+    /** Order while this filter is active and the URL carries no sort of its own; wins over `defaultSort`. */
+    readonly sort?: ListSortSpec;
+    /** Select display: draws a divider line below this entry in the dropdown. */
+    readonly separatorAfter?: boolean;
+    /**
+     * Shown instead of the generic "no matches" text when this filter yields an empty list and no
+     * search term is set; `title` and `description` are i18n keys. `paramsQuery` (a registered query
+     * QN, called without payload) runs only while the empty state is on screen; its result object
+     * becomes the translation params of `description`. Without data (loading, error, no result) the
+     * description is not rendered.
+     */
+    readonly emptyState?: {
+        readonly title: string;
+        readonly description?: string;
+        readonly paramsQuery?: string;
+    };
+    /** Set by the framework from the entity filter's access rule; the client offers the chip only where `isUiAccessGranted` allows it. */
+    readonly access?: AccessRule;
+};
+/** How the named filters appear in the toolbar: toggle chips (default) or one single-choice select. */
+export type NamedFilterFacetOptions = {
+    readonly display?: "chips" | "select";
+    /** Ask the list query for each filter's hit count and show it next to the label. */
+    readonly showCounts?: boolean;
+    /** Select entries with zero hits are left out (the active one and "all" stay). Asks for the counts like `showCounts` does, without showing the number unless `showCounts` is set. */
+    readonly hideEmpty?: boolean;
+    /** "behind-filter": the select opens behind the filter icon next to the search field instead of standing as a pill. Only below `sm`; otherwise it stays a pill. */
+    readonly narrowPlacement?: "behind-filter";
+    /** i18n key for the select's label, e.g. "To do". */
+    readonly label?: string;
 };

package/dist/nav-icon.js

@@ -10,7 +10,7 @@
 // versa.
 //
 // Declared as a runtime tuple (not just a type) so callers that sit outside
-// this repo's `tsc --build` project graph (e.g. samples, external consumers
+// this repo's typecheck project graph (e.g. samples, external consumers
 // resolving from a stale published type) still get a runtime-checkable
 // vocabulary — the boot-validator's validateActionHasIcon checks a declared
 // icon against NAV_ICON_KEYS instead of trusting "not undefined".

package/dist/observability/provider.d.ts

@@ -8,8 +8,6 @@ export type SamplingConfig = {
     };
 };
 export type SensitiveFilterConfig = {
-    readonly redactedHeaders: readonly string[];
-    readonly redactedQueryParams: readonly string[];
     readonly redactedAttributeKeyPatterns: readonly RegExp[];
 };
 export type ObservabilityOptions = {

package/dist/projection.d.ts

@@ -1,4 +1,4 @@
-import type { RunIn } from "./config.ts";
+import type { IrreversibleWithoutEntryHandler, RunIn } from "./config.ts";
 import type { StoredEvent } from "./event-store-types.ts";
 import type { ExecutorManagedRunner } from "./executor-brand.ts";
 import type { EntityDefinition } from "./fields.ts";
@@ -38,4 +38,5 @@ export type MultiStreamProjectionDefinition = {
     readonly runIn?: RunIn;
     readonly delivery?: "shared" | "per-instance";
     readonly startFrom?: "beginning" | "now";
+    readonly irreversibleWithoutEntryHandler?: IrreversibleWithoutEntryHandler;
 };