@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

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

@@ -80,13 +80,20 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
-        await purgeExpiredRows(db, proj.source, proj.table, where, ctx);
+        await purgeExpiredRows(db, proj.source, proj.table, where, cutoff, ctx);
     }
 };
-async function purgeExpiredRows(db, source, table, where, ctx) {
+async function purgeExpiredRows(db, source, table, where, cutoff, ctx) {
     if (source === FILE_REF_ENTITY_NAME) {
         // The row is the only record of the storageKey, so its bytes go first.
-        await purgeExpiredFileRefsWithBytes({ db, table, where, files: ctx.files, log: ctx.log });
+        await purgeExpiredFileRefsWithBytes({
+            db,
+            table,
+            where,
+            expiredBefore: cutoff,
+            files: ctx.files,
+            log: ctx.log,
+        });
     }
     else {
         await deleteMany(db, table, where);

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

@@ -1,4 +1,4 @@
-import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
+import { requestedTenantIds, unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
 import { InternalError } from "../../errors/classes.js";
 import { SYSTEM_TENANT_ID } from "../types/identifiers.js";
 // unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
@@ -25,7 +25,10 @@ export function warnOnNarrowedForeignTenantFilter(ctx, stepKind, stepName, where
     if (requested === undefined)
         return;
     const allowed = [ctx.db.tenantId, SYSTEM_TENANT_ID];
-    const requestedList = Array.isArray(requested) ? requested : [requested];
+    const requestedList = requestedTenantIds(requested);
+    // skip: unrecognised operator form, narrowing cannot be judged.
+    if (requestedList === undefined)
+        return;
     // skip: every requested tenant is within the caller's scope.
     if (requestedList.every((t) => typeof t === "string" && allowed.includes(t)))
         return;

package/dist/engine/steps/retry.js

@@ -11,6 +11,7 @@ import { defineStep } from "../define-step.js";
 import { runStepList } from "../run-pipeline.js";
 import { SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, WORKFLOW_RETRY_SCHEDULED_TYPE, } from "./_step-dispatch-constants.js";
 import { describeWorkflowStepError } from "./describe-workflow-step-error.js";
+import { unwrapWorkflowStepError } from "./workflow-step-error.js";
 const log = createFallbackLogger("workflow-retry");
 defineStep({
     kind: "workflow.retry",
@@ -38,7 +39,7 @@ defineStep({
                 workflowName: ctx.workflow.workflowName,
                 stepIndex: ctx.workflow.stepIndex,
                 attempt,
-                error: String(error),
+                error: String(unwrapWorkflowStepError(error)),
             });
             const backoffMs = calculateBackoff(attempt, args.backoff);
             const wakeAt = Temporal.Now.instant().add({ milliseconds: backoffMs }).toString();

package/dist/engine/steps/unsafe-projection-delete.js

@@ -16,7 +16,7 @@
 // must commit in the same TX as the aggregate-mutation that triggered
 // it (stronger consistency than an async projection). Reviewer judges.
 import { deleteMany } from "../../db/query.js";
-import { tenantDbRunner } from "../../db/tenant-db-runner.js";
+import { tenantDbWriteRunner } from "../../db/tenant-db-runner.js";
 import { defineStep } from "../define-step.js";
 import { resolveRequired } from "./_resolver-utils.js";
 defineStep({
@@ -27,7 +27,7 @@ defineStep({
         // The `unsafe*`-step IS the sanctioned direct projection write — it exists
         // to bypass the executor deliberately (boot-validated allowlist + reviewer
         // gate). The brand-strip cast makes that explicit at the one blessed seam.
-        await deleteMany(tenantDbRunner(ctx.db), args.table, where);
+        await deleteMany(tenantDbWriteRunner(ctx.db, "unsafe projection delete"), args.table, where);
     },
 });
 export function buildUnsafeProjectionDeleteStep(args) {

package/dist/engine/steps/unsafe-projection-upsert.js

@@ -13,7 +13,7 @@
 import { extractTableName } from "../../db/index.js";
 import { executeRawQuery } from "../../db/queries/raw-sql.js";
 import { columnSqlNameOf } from "../../db/table-introspection.js";
-import { tenantDbRunner } from "../../db/tenant-db-runner.js";
+import { tenantDbWriteRunner } from "../../db/tenant-db-runner.js";
 import { defineStep } from "../define-step.js";
 import { resolveRequired } from "./_resolver-utils.js";
 function resolveColumnName(table, field) {
@@ -54,7 +54,7 @@ defineStep({
         }
         const sqlText = `INSERT INTO ${quoteIdent(tableName)} (${colNames.join(", ")}) VALUES (${placeholders.join(", ")}) ` +
             `ON CONFLICT (${conflictCols}) DO UPDATE SET ${setClauses.join(", ")}`;
-        await executeRawQuery(tenantDbRunner(ctx.db), sqlText, params);
+        await executeRawQuery(tenantDbWriteRunner(ctx.db, "unsafe projection upsert"), sqlText, params);
     },
 });
 export function buildUnsafeProjectionUpsertStep(args) {

package/dist/engine/template-variables.d.ts

@@ -11,6 +11,9 @@ export declare const templateVariable: {
     readonly link: (opts?: CommonOptions & {
         readonly example?: string;
     }) => TemplateScalarVariableDef;
+    readonly richText: (opts?: CommonOptions & {
+        readonly example?: string;
+    }) => TemplateScalarVariableDef;
     readonly money: (opts?: CommonOptions & {
         readonly example?: number | {
             readonly amount: number;

package/dist/engine/template-variables.js

@@ -10,6 +10,7 @@ export const templateVariable = {
         type: "link",
         ...opts,
     }),
+    richText: (opts = {}) => ({ type: "richText", ...opts }),
     money: (opts = {}) => ({ type: "money", ...opts }),
     date: (opts = {}) => ({
         type: "date",
@@ -39,6 +40,8 @@ function scalarToZod(def) {
     switch (def.type) {
         case "text":
             return z.string();
+        case "richText":
+            return z.string();
         case "link":
             return linkSchema;
         case "money":

package/dist/engine/tier-resolver-extension.d.ts

@@ -61,4 +61,5 @@ export type TierResolverPlugin = {
  *  plugin shape — the only thing every implementation must provide is the
  *  `build` factory. */
 export declare function isTierResolverPlugin(v: unknown): v is TierResolverPlugin;
+export declare function requireTierResolverPlugin(usage: RegistrarExtensionRegistration): TierResolverPlugin;
 export declare function findTierResolverUsage(features: readonly FeatureDefinition[]): RegistrarExtensionRegistration | undefined;

package/dist/engine/tier-resolver-extension.js

@@ -42,6 +42,12 @@ export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
 export function isTierResolverPlugin(v) {
     return isPlainObject(v) && typeof v["build"] === "function";
 }
+export function requireTierResolverPlugin(usage) {
+    if (!isTierResolverPlugin(usage.options)) {
+        throw new Error("tier-resolver registration options must provide a build() factory");
+    }
+    return usage.options;
+}
 export function findTierResolverUsage(features) {
     for (const feature of features) {
         for (const usage of feature.extensionUsages) {

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

@@ -7,7 +7,7 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, 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, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
+export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
 export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";

package/dist/entrypoint/index.d.ts

@@ -3,7 +3,7 @@ import type { AuthRoutesConfig } from "../api/auth-routes.js";
 import type { JwtHelper, JwtKeyring } from "../api/jwt.js";
 import type { ServerOptions } from "../api/server.js";
 import type { SseBroker } from "../api/sse-broker.js";
-import type { PgClient } from "../db/connection.js";
+import type { PgClient, PgListenClient } from "../db/connection.js";
 import type { AppContext, Registry } from "../engine/types/index.js";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner.js";
 import type { Lifecycle } from "../lifecycle/index.js";
@@ -82,4 +82,4 @@ export type AllInOneEntrypoint = Omit<ApiEntrypoint, "mode"> & Omit<WorkerEntryp
 export declare function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoint;
 export declare function createWorkerEntrypoint(options: WorkerEntrypointOptions): WorkerEntrypoint;
 export declare function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): AllInOneEntrypoint;
-export type { PgClient };
+export type { PgClient, PgListenClient };

package/dist/env/_zod-introspect.d.ts

@@ -2,6 +2,7 @@ import type * as z from "zod";
 export type ZodDef = {
     readonly innerType?: z.ZodType;
     readonly in?: z.ZodType;
+    readonly element?: z.ZodType;
     readonly defaultValue?: unknown;
 };
 /** Read Zod v4 `.meta()` value. Undefined when no meta is set. */

package/dist/errors/classes.js

@@ -223,6 +223,7 @@ export class RateLimitError extends KumikoError {
             message: `rate limited: ${details.bucket} (limit ${details.limit} per ${details.windowSeconds}s)`,
             i18nKey: opts?.i18nKey ?? "errors.rate_limited",
             details,
+            retryAfterSeconds: details.retryAfterSeconds,
             ...(opts?.cause && { cause: opts.cause }),
         });
         this.details = details;

package/dist/errors/docs-url.js

@@ -20,17 +20,17 @@ function isCoveredByConfig(reason, errorDocs) {
 function errorsUrl(baseUrl, slug) {
     return `${baseUrl}/errors/${encodeURIComponent(slug)}`;
 }
-// A reason the framework documents (or the error code itself) links to the framework docs,
-// overridable via KUMIKO_DOCS_URL. An app's own reason links only where `errorDocs` covers it —
-// otherwise the framework docs would have no page for it.
+// A reason the framework documents (or no reason, or the code itself) links to the framework docs, overridable via
+// KUMIKO_DOCS_URL. An app's own reason links to the app docs where `errorDocs` covers it; every
+// other reason falls back to the framework page of the error code, which exists for each code.
 export function resolveErrorDocsUrl(err, errorDocs) {
     const reason = reasonOf(err);
+    const frameworkBaseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
     if (reason === undefined || reason === err.code || frameworkReasons.has(reason)) {
-        const baseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
-        return errorsUrl(baseUrl, reason ?? err.code);
+        return errorsUrl(frameworkBaseUrl, reason ?? err.code);
     }
     if (errorDocs && isCoveredByConfig(reason, errorDocs)) {
         return errorsUrl(errorDocs.baseUrl, reason);
     }
-    return undefined;
+    return errorsUrl(frameworkBaseUrl, err.code);
 }

package/dist/errors/index.d.ts

@@ -9,7 +9,7 @@ export type { AgentReason, FrameworkReason } from "./reasons.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
-export { subjectErasedConflict } from "./subject-erased.js";
+export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export type { InvalidTransitionDetails } from "./transition-details.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";

package/dist/errors/index.js

@@ -4,7 +4,7 @@ export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
-export { subjectErasedConflict } from "./subject-erased.js";
+export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";
 export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";

package/dist/errors/kumiko-error.d.ts

@@ -11,6 +11,7 @@ export type ErrorCtorInput = {
     readonly i18nParams?: Readonly<Record<string, unknown>>;
     readonly details?: unknown;
     readonly cause?: Error;
+    readonly retryAfterSeconds?: number;
 };
 export declare abstract class KumikoError extends Error {
     abstract readonly code: string;
@@ -18,6 +19,7 @@ export declare abstract class KumikoError extends Error {
     readonly i18nKey: string;
     readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
     readonly details: unknown;
+    readonly retryAfterSeconds: number | undefined;
     constructor(input: ErrorCtorInput);
 }
 export declare function isKumikoError(e: unknown): e is KumikoError;

package/dist/errors/kumiko-error.js

@@ -6,12 +6,14 @@ export class KumikoError extends Error {
     i18nKey;
     i18nParams;
     details;
+    retryAfterSeconds;
     constructor(input) {
         super(input.message, input.cause ? { cause: input.cause } : undefined);
         this.name = new.target.name;
         this.i18nKey = input.i18nKey;
         this.i18nParams = input.i18nParams;
         this.details = input.details;
+        this.retryAfterSeconds = input.retryAfterSeconds;
     }
 }
 export function isKumikoError(e) {

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

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

package/dist/errors/subject-erased.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { ConflictError } from "./classes.js";
 import { FrameworkReasons } from "./reasons.js";
 export function subjectErasedConflict(cause) {
@@ -7,3 +8,8 @@ export function subjectErasedConflict(cause) {
         ...(cause instanceof Error && { cause }),
     });
 }
+export function isSubjectErasedConflict(e) {
+    return (e instanceof ConflictError &&
+        isPlainObject(e.details) &&
+        e.details["reason"] === FrameworkReasons.subjectErased);
+}

package/dist/errors/write-error-info.js

@@ -69,6 +69,7 @@ export function toWriteErrorInfo(err) {
         message: err.message,
         ...(err.i18nParams && { i18nParams: err.i18nParams }),
         ...(effectiveDetails !== undefined && { details: effectiveDetails }),
+        ...(err.retryAfterSeconds !== undefined && { retryAfterSeconds: err.retryAfterSeconds }),
     };
     if (err.cause instanceof Error)
         causeByWriteErrorInfo.set(info, err.cause);
@@ -91,6 +92,7 @@ class ReraisedError extends KumikoError {
             i18nKey: info.i18nKey,
             ...(info.i18nParams && { i18nParams: info.i18nParams }),
             ...(info.details !== undefined && { details: info.details }),
+            ...(info.retryAfterSeconds !== undefined && { retryAfterSeconds: info.retryAfterSeconds }),
             ...(cause && { cause }),
         });
         this.code = info.code;

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

@@ -7,6 +7,7 @@
 // Guard-Script `scripts/guard-admin-api.ts` blockt Aufrufe aus App-Code —
 // Allowlist: samples/*/migration/, scripts/migrations/, die Definition
 // selbst, das Guard-Script selbst.
+import { instantToTimestamptzParam } from "../bun-db/query.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, runAtomicEventWrite } from "../db/queries/event-store.js";
 import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";
@@ -53,7 +54,7 @@ function rawEventParams(event, newVersion, eventVersion) {
         eventVersion,
         payload: event.payload,
         metadata: event.metadata,
-        createdAt: event.createdAt.toString(),
+        createdAt: instantToTimestamptzParam(event.createdAt),
         createdBy: event.createdBy,
     };
 }
@@ -88,7 +89,7 @@ export async function appendRawBatch(runner, events) {
         const newVersion = e.expectedVersion + 1;
         const eventVersion = e.eventVersion ?? 1;
         const baseIdx = params.length;
-        params.push(e.aggregateId, e.aggregateType, e.tenantId, newVersion, e.type, eventVersion, e.payload, e.metadata, e.createdAt.toString(), e.createdBy);
+        params.push(e.aggregateId, e.aggregateType, e.tenantId, newVersion, e.type, eventVersion, e.payload, e.metadata, instantToTimestamptzParam(e.createdAt), e.createdBy);
         return `($${baseIdx + 1}::uuid, $${baseIdx + 2}, $${baseIdx + 3}::uuid, $${baseIdx + 4}, $${baseIdx + 5}, $${baseIdx + 6}, $${baseIdx + 7}::jsonb, $${baseIdx + 8}::jsonb, $${baseIdx + 9}::timestamptz, $${baseIdx + 10})`;
     });
     try {

package/dist/event-store/errors.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 export declare class VersionConflictError extends Error {
     readonly aggregateId: string;
     readonly expectedVersion: number;
@@ -8,6 +9,14 @@ export declare class IdempotentAppendConflictError extends Error {
     readonly idempotencyKey: string;
     constructor(tenantId: string, idempotencyKey: string);
 }
+export declare class SeedTimeOrderError extends Error {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly version: number;
+    readonly seedCreatedAt: Temporal.Instant;
+    readonly predecessorCreatedAt: Temporal.Instant;
+    constructor(aggregateType: string, aggregateId: string, version: number, seedCreatedAt: Temporal.Instant, predecessorCreatedAt: Temporal.Instant);
+}
 export declare class ArchivedStreamError extends Error {
     readonly tenantId: string;
     readonly aggregateId: string;

package/dist/event-store/errors.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 // Failure modes of the event-store's append() path. Surfaced as typed
 // errors so the executor layer can map them to the framework's
 // WriteResult error contract (version_conflict).
@@ -31,6 +32,25 @@ export class IdempotentAppendConflictError extends Error {
         this.idempotencyKey = idempotencyKey;
     }
 }
+// Thrown when a back-dated seed write would put a stream's next version
+// before its predecessor in time. loadAggregateAsOf and projection rebuilds
+// order by created_at, so such a stream would read and replay wrongly.
+export class SeedTimeOrderError extends Error {
+    aggregateType;
+    aggregateId;
+    version;
+    seedCreatedAt;
+    predecessorCreatedAt;
+    constructor(aggregateType, aggregateId, version, seedCreatedAt, predecessorCreatedAt) {
+        super(`Seed write for ${aggregateType} ${aggregateId} v${version} is dated ${seedCreatedAt.toString()}, before its predecessor (${predecessorCreatedAt.toString()}). Write a stream's events in ascending time.`);
+        this.name = "SeedTimeOrderError";
+        this.aggregateType = aggregateType;
+        this.aggregateId = aggregateId;
+        this.version = version;
+        this.seedCreatedAt = seedCreatedAt;
+        this.predecessorCreatedAt = predecessorCreatedAt;
+    }
+}
 // Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
 // are read-only — restoreStream() makes them writable again. The archive
 // state is not carried on the events themselves; it lives on the sparse

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

@@ -20,6 +20,12 @@ export declare function loadAggregate(db: DbRunner, aggregateId: string, tenantI
     readonly includeArchived?: boolean;
     readonly aggregateType?: string;
 }): Promise<readonly StoredEvent[]>;
+export declare function loadAggregateForWriting(db: DbRunner, aggregateId: string, tenantId: TenantId, options: {
+    readonly aggregateType: string;
+}): Promise<{
+    readonly events: readonly StoredEvent[];
+    readonly streamVersion: number;
+}>;
 export declare function loadAggregateAsOf(db: DbRunner, aggregateId: string, tenantId: TenantId, asOf: Temporal.Instant, options?: {
     readonly includeArchived?: boolean;
 }): Promise<readonly StoredEvent[]>;

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

@@ -2,12 +2,13 @@
 import { isPersonalDataGated, UNATTRIBUTED_ORIGIN, } from "@cosmicdrift/kumiko-types/event-store-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
+import { instantToTimestamptzParam } from "../bun-db/query.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
 import { insertOne, selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
-import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
+import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 import { eventsTable } from "./events-schema.js";
 import { toStoredEvent } from "./row-to-stored-event.js";
 import { currentSeedCreatedAt } from "./seed-clock.js";
@@ -44,14 +45,16 @@ export async function append(db, event) {
     });
     const toStore = stampOrigin(payload === event.payload ? event : { ...event, payload });
     const seedCreatedAt = currentSeedCreatedAt();
-    if (seedCreatedAt !== undefined && toStore.expectedVersion > 0) {
-        await assertSeedTimeNotBeforePredecessor(db, toStore, seedCreatedAt);
-    }
     const newVersion = toStore.expectedVersion + 1;
     const eventVersion = toStore.eventVersion ?? 1;
     try {
         const row = await runAtomicEventWrite(db, async (runner) => {
             await claimXactId(runner);
+            // Inside the write transaction so a concurrent live append cannot slip
+            // between the check and the insert.
+            if (seedCreatedAt !== undefined && toStore.expectedVersion > 0) {
+                await assertSeedTimeNotBeforePredecessor(runner, toStore, seedCreatedAt);
+            }
             const inserted = toStore.expectedVersion === 0
                 ? await insertFirstEvent(runner, toStore, newVersion, eventVersion, seedCreatedAt)
                 : await insertSubsequentEvent(runner, toStore, newVersion, eventVersion, seedCreatedAt);
@@ -105,7 +108,7 @@ async function assertSeedTimeNotBeforePredecessor(db, event, seedCreatedAt) {
         version: event.expectedVersion,
     });
     if (predecessor && predecessor.createdAt.epochMilliseconds > seedCreatedAt.epochMilliseconds) {
-        throw new Error(`Seed write for ${event.aggregateType} ${event.aggregateId} v${event.expectedVersion + 1} is dated ${seedCreatedAt.toString()}, before its predecessor (${predecessor.createdAt.toString()}). Write a stream's events in ascending time.`);
+        throw new SeedTimeOrderError(event.aggregateType, event.aggregateId, event.expectedVersion + 1, seedCreatedAt, predecessor.createdAt);
     }
 }
 async function insertFirstEvent(db, event, newVersion, eventVersion, seedCreatedAt) {
@@ -141,7 +144,7 @@ async function insertSubsequentEvent(db, event, newVersion, eventVersion, seedCr
         metadata: event.metadata,
         createdBy: event.metadata.userId,
         expectedVersion: event.expectedVersion,
-        createdAt: seedCreatedAt?.toString(),
+        createdAt: seedCreatedAt && instantToTimestamptzParam(seedCreatedAt),
     });
     if (!row)
         throw new VersionConflictError(event.aggregateId, event.expectedVersion);
@@ -201,6 +204,25 @@ export async function loadAggregate(db, aggregateId, tenantId, options) {
         : { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
     return rows.map(toStoredEvent);
 }
+// Events and the stream's latest version from ONE read, so both come from the same
+// snapshot: a commit landing between two separate statements would leave the caller
+// pinning a version its loaded events never covered. The aggregateType filter is applied
+// after the read because a foreign type sharing the aggregateId still occupies versions
+// the next append has to stack on. Archived streams load empty but keep their real version.
+export async function loadAggregateForWriting(db, aggregateId, tenantId, options) {
+    if (options.aggregateType === "") {
+        throw new Error("loadAggregateForWriting: aggregateType must be a non-empty string");
+    }
+    if (await isStreamArchived(db, tenantId, aggregateId)) {
+        return { events: [], streamVersion: await getStreamVersion(db, aggregateId, tenantId) };
+    }
+    const rows = await selectMany(db, eventsTable, { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
+    const all = rows.map(toStoredEvent);
+    return {
+        events: all.filter((e) => e.aggregateType === options.aggregateType),
+        streamVersion: all.at(-1)?.version ?? 0,
+    };
+}
 // Load events up to a point in time. Used for asOf queries that reconstruct
 // historical state. Includes events whose created_at is <= asOf. Same
 // archive semantics as loadAggregate.

package/dist/event-store/index.d.ts

@@ -1,7 +1,7 @@
 export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/system-event-pii.js";
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, type PiiBackfillBatchOptions, type PiiBackfillBatchResult, type PiiBackfillFailure, type PiiBackfillOptions, type PiiBackfillResult, type PiiBackfillScanCache, } from "../db/queries/backfill-pii.js";
 export { type ArchiveStreamArgs, archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
-export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError, } from "./errors.js";
+export { ArchivedStreamError, IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 export { append, EVENTS_PUBSUB_CHANNEL, type EventMetadata, type EventToAppend, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent, type ProvenanceEventInput } from "./provenance-append.js";

package/dist/event-store/index.js

@@ -1,7 +1,7 @@
 export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/system-event-pii.js";
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, } from "../db/queries/backfill-pii.js";
 export { archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
-export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError, } from "./errors.js";
+export { ArchivedStreamError, IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 export { append, EVENTS_PUBSUB_CHANNEL, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent } from "./provenance-append.js";

package/dist/event-store/tenant-db-append.js

@@ -1,11 +1,11 @@
-import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { tenantDbRunner, tenantDbWriteRunner } from "../db/tenant-db-runner.js";
 import { runProjectionsForEvent } from "../pipeline/projections-runner.js";
 import { append, getStreamVersion } from "./event-store.js";
 // Appends on the connection or transaction the TenantDb is bound to. The tenant is always the
 // TenantDb's own, so a caller cannot write into another tenant's stream; a TenantDb the framework
 // did not build (or a fail-closed systemScope guard) is rejected by tenantDbRunner.
 export async function appendEventInTenantDb(tenantDb, event, options = {}) {
-    const runner = tenantDbRunner(tenantDb);
+    const runner = tenantDbWriteRunner(tenantDb, "appendEventInTenantDb");
     const stored = await append(runner, { ...event, tenantId: tenantDb.tenantId });
     if (options.registry)
         await runProjectionsForEvent(stored, options.registry, runner);

package/dist/files/assert-file-refs-belong-to-tenant.d.ts

@@ -1,8 +1,7 @@
-import type { TenantDb } from "../db/tenant-db.js";
-import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+import { type Registry, type SaveContext } from "../engine/types/index.js";
+import type { FileRefRows } from "./load-save-file-refs.js";
 export declare function assertFileRefsBelongToTenant(args: {
     readonly registry: Registry;
     readonly result: SaveContext;
-    readonly user: SessionUser;
-    readonly db: TenantDb;
-}): Promise<void>;
+    readonly fileRefRows: FileRefRows;
+}): void;

package/dist/files/assert-file-refs-belong-to-tenant.js

@@ -1,16 +1,17 @@
-import { isFileField, isUuid, } from "../engine/types/index.js";
+import { isFileField } from "../engine/types/index.js";
 import { ValidationError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.js";
-import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 // A file field only stores an id, and the file routes authorize by tenant at
 // read time: without this check a writer could name another tenant's fileRef
 // and make the record point at it. Only newly written values are checked (all
 // of a create, `changes` of an update), so existing data is left alone. The
 // error is the same for "missing" and "belongs to another tenant" so the id
-// cannot be probed across tenants.
-export async function assertFileRefsBelongToTenant(args) {
-    const { registry, result, user, db } = args;
+// cannot be probed across tenants. `fileRefRows` holds only the writer's own
+// tenant's live rows, so a missing entry is exactly those two cases. Values
+// that are not UUIDs are skipped by fileRefIdsOf and never reach this check.
+export function assertFileRefsBelongToTenant(args) {
+    const { registry, result, fileRefRows } = args;
     // skip: saves of unregistered aggregates (custom executors) declare no file fields
     if (result.entityName === undefined)
         return;
@@ -21,12 +22,11 @@ export async function assertFileRefsBelongToTenant(args) {
     // skip: without the files feature the file_refs table is not part of the schema
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         return;
-    const executor = getFileRefExecutor();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            if (await isFileRefOfTenant(executor, fileRefId, user, db))
+            if (fileRefRows.has(fileRefId))
                 continue;
             throw new ValidationError({
                 fields: [
@@ -40,11 +40,3 @@ export async function assertFileRefsBelongToTenant(args) {
         }
     }
 }
-async function isFileRefOfTenant(executor, fileRefId, user, db) {
-    if (!isUuid(fileRefId))
-        return false;
-    // detail() widens its tenant filter to (self, SYSTEM); only the writer's own
-    // tenant counts here, same as GET /files/:id/meta.
-    const row = await executor.detail({ id: fileRefId }, user, db);
-    return row !== null && row["tenantId"] === user.tenantId;
-}

package/dist/files/bind-pending-file-refs.d.ts

@@ -1,9 +1,11 @@
 import type { TenantDb } from "../db/tenant-db.js";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+import type { FileRefRows } from "./load-save-file-refs.js";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
     readonly result: SaveContext;
     readonly user: SessionUser;
     readonly db: TenantDb;
+    readonly fileRefRows: FileRefRows;
 }): Promise<void>;

package/dist/files/bind-pending-file-refs.js

@@ -23,7 +23,7 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
 // someone else's upload id in a save payload must not pull that file into a
 // record the caller controls.
 export async function bindPendingFileRefs(args) {
-    const { registry, result, user, db } = args;
+    const { registry, result, user, db, fileRefRows } = args;
     // skip: saves of unnamed aggregates declare no file fields
     if (result.entityName === undefined)
         return;
@@ -42,8 +42,8 @@ export async function bindPendingFileRefs(args) {
         // changes, not data: an update's row carries every stored file id, including
         // ones bound earlier; only the ids this save names can be pending uploads.
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            const row = await executor.detail({ id: fileRefId }, user, db);
-            if (row === null || !isPendingUploadFor(row, entityName, fieldName, user))
+            const row = fileRefRows.get(fileRefId);
+            if (row === undefined || !isPendingUploadFor(row, entityName, fieldName, user))
                 continue;
             const version = typeof row["version"] === "number" ? row["version"] : undefined;
             const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);