@cosmicdrift/kumiko-types 0.413.0 → 0.414.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;
@@ -180,6 +179,7 @@ export type JobDefinition = {
     readonly runOnBoot?: boolean | undefined;
     readonly bootGate?: boolean | undefined;
     readonly perTenant?: boolean | undefined;
+    readonly includeSystemTenant?: boolean | undefined;
     readonly runIn?: JobRunIn | undefined;
     readonly escapeHatch?: EscapeHatchDeclaration | undefined;
     readonly tenantVisibleFailure?: {

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 { DeliveryAttemptLogFactory, 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,8 @@ export type ContextServices = {
     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 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;
@@ -162,15 +163,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 +237,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 +263,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 +344,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 +541,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 +555,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 +600,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/named-list-filters.d.ts

@@ -16,8 +16,34 @@ 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;
+    /** Shown instead of the generic "no matches" text when this filter yields an empty list and no search term is set; both are i18n keys. */
+    readonly emptyState?: {
+        readonly title: string;
+        readonly description?: string;
+    };
+    /** Set by the framework from the entity filter's role rule; the chip is offered only to users holding one of them. */
+    readonly roles?: readonly string[];
+};
+/** 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;
+    /** i18n key for the select's label, e.g. "To do". */
+    readonly label?: string;
 };

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 = {