@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

package/dist/engine/boot-validator/query-refs.js

@@ -11,6 +11,18 @@ export function checkQueryRef(queryHandlers, query, buildPrefix) {
         return;
     throw new Error(`${buildPrefix()} query "${query}" ${NOT_REGISTERED_SUFFIX}`);
 }
+// visibleWhen queries are run with an empty payload by the client gate, so a query
+// that requires input would fail on every call and the screen/panel would stay
+// unavailable with no hint.
+function checkVisibleWhenQueryRef(queryHandlers, query, buildPrefix) {
+    checkQueryRef(queryHandlers, query, buildPrefix);
+    const handler = queryHandlers.get(query);
+    // skip: nothing to check for an unknown handler (checkQueryRef already threw) or an input-free query
+    if (handler === undefined || handler.schema.safeParse({}).success)
+        return;
+    throw new Error(`${buildPrefix()} query "${query}" requires input; visibleWhen queries run with an empty payload. ` +
+        "Make the query's input fields optional or use a query without required input.");
+}
 // relatedList is currently only reachable on projectionDetail — screens.ts
 // rejects it outright on entityEdit/actionForm/configEdit (fw#2166). Walking
 // the shared EditLayout uniformly here (instead of excluding those three
@@ -27,7 +39,7 @@ function checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen) {
         if (panel.kind === "custom")
             continue;
         if (panel.visibleWhen !== undefined) {
-            checkQueryRef(queryHandlers, panel.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) ${panel.kind === "screen" ? "screen-panel" : "panel"} "${panel.id}" visibleWhen`);
+            checkVisibleWhenQueryRef(queryHandlers, panel.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) ${panel.kind === "screen" ? "screen-panel" : "panel"} "${panel.id}" visibleWhen`);
         }
         if (panel.kind === "screen")
             continue;
@@ -60,7 +72,7 @@ function checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screenTyp
 }
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
     if (screen.visibleWhen !== undefined) {
-        checkQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
+        checkVisibleWhenQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
     }
     if (screen.type === "projectionList") {
         checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);

package/dist/engine/dedupe-features.js

@@ -11,13 +11,40 @@ function sameKeys(a, b) {
     const bKeys = new Set(Object.keys(b ?? {}));
     return aKeys.length === bKeys.size && aKeys.every((key) => bKeys.has(key));
 }
+const KEYED_SURFACE_PROPERTIES = [
+    "entities",
+    "writeHandlers",
+    "queryHandlers",
+    "streamHandlers",
+    "screens",
+    "navs",
+    "jobs",
+    "events",
+    "translations",
+    "configKeys",
+    "notifications",
+    "metrics",
+];
+// Hooks are keyed per phase, then per target: flatten so a hook added under an
+// existing phase still shows up as a difference.
+function hookKeys(feature) {
+    const keys = new Set();
+    for (const [phase, byTarget] of Object.entries(feature.hooks ?? {})) {
+        for (const target of Object.keys(byTarget ?? {}))
+            keys.add(`${phase}/${target}`);
+    }
+    return keys;
+}
+function sameHookKeys(a, b) {
+    const aKeys = hookKeys(a);
+    const bKeys = hookKeys(b);
+    return aKeys.size === bKeys.size && [...aKeys].every((key) => bKeys.has(key));
+}
 // dedupeOptions is a declaration, not proof: two same-named features that both
 // carry `{}` but register different surface must still clash, not silently drop one.
 function sameRegisteredSurface(a, b) {
-    return (sameKeys(a.entities, b.entities) &&
-        sameKeys(a.writeHandlers, b.writeHandlers) &&
-        sameKeys(a.queryHandlers, b.queryHandlers) &&
-        sameKeys(a.streamHandlers, b.streamHandlers));
+    return (KEYED_SURFACE_PROPERTIES.every((property) => sameKeys(a[property], b[property])) &&
+        sameHookKeys(a, b));
 }
 function isInterchangeable(existing, next) {
     if (existing === next)

package/dist/engine/entity-handlers.js

@@ -4,6 +4,7 @@ import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences,
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
+import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
@@ -49,8 +50,8 @@ const WRITE_VERBS = ["create", "update", "delete", "restore"];
 const QUERY_VERBS = ["list", "detail"];
 const idSchema = z.object({ id: z.uuid() });
 const SYSTEM_ADMIN_ROLE = "SystemAdmin";
-// A write handler with escapeHatch reads/writes rows of every tenant, so only an operator
-// role may reach it — otherwise any tenant-level role holder could mutate foreign tenants.
+// A handler with escapeHatch reads/writes rows of every tenant, so only an operator
+// role may reach it — otherwise any tenant-level role holder could read or mutate foreign tenants.
 function isSystemAdminOnly(access) {
     return ("roles" in access &&
         access.roles.length > 0 &&
@@ -65,8 +66,8 @@ function resolveCrossTenantReason(name, options, kind) {
     const placeholderProblem = codemodPlaceholderReasonProblem(options.escapeHatch.reason);
     if (placeholderProblem !== undefined)
         throw new Error(`"${name}": ${placeholderProblem}`);
-    if (kind === "write" && !isSystemAdminOnly(options.access)) {
-        throw new Error(`"${name}": a write handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
+    if (!isSystemAdminOnly(options.access)) {
+        throw new Error(`"${name}": a ${kind} handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
     }
     return options.escapeHatch.reason;
 }
@@ -235,7 +236,13 @@ export function defineEntityWriteHandler(name, entity, options) {
         }
         if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId)
             return undefined;
-        return parseTenantId(rowTenantId) ?? undefined;
+        const streamTenantId = parseTenantId(rowTenantId);
+        if (streamTenantId === null) {
+            throw new InternalError({
+                message: `"${name}": row ${String(id)} has tenantId "${rowTenantId}" which is not a TenantId; refusing to append to the wrong stream.`,
+            });
+        }
+        return streamTenantId;
     };
     let schema;
     let handler;
@@ -569,7 +576,7 @@ export function registerEntityCrud(r, entityName, entity, options) {
             ...writeOpts,
             access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
             description: options?.descriptions?.[verb] ?? writeOpts?.description,
-            ...(verbAgent !== undefined && { agent: verbAgent }),
+            ...(verbAgent !== undefined && { agent: { ...writeOpts?.agent, ...verbAgent } }),
             ...(excludeFields !== undefined && { excludeFields }),
         };
     };
@@ -579,7 +586,7 @@ export function registerEntityCrud(r, entityName, entity, options) {
             ...readOpts,
             access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
             description: options?.descriptions?.[verb] ?? readOpts?.description,
-            ...(verbAgent !== undefined && { agent: verbAgent }),
+            ...(verbAgent !== undefined && { agent: { ...readOpts?.agent, ...verbAgent } }),
         };
     };
     if (verbs.create) {

package/dist/engine/index.d.ts

@@ -78,10 +78,10 @@ export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-ste
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { assertNotificationVariables, templateVariable, templateVariablesToZod, } from "./template-variables.js";
-export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
+export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MaxPerTenantOptions, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/index.js

@@ -71,7 +71,7 @@ export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-ste
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { assertNotificationVariables, templateVariable, templateVariablesToZod, } from "./template-variables.js";
-export { findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
+export { findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";

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

@@ -26,6 +26,7 @@ export declare function resolveJobTriggers(state: RegistryState): void;
 export declare function validateLiveEntities(state: RegistryState): void;
 export declare function validateBootGates(state: RegistryState): void;
 export declare function validateJobBackoff(state: RegistryState): void;
+export declare function validateMaxPerTenant(state: RegistryState): void;
 export declare function validateExtensionUsageTargets(state: RegistryState): void;
 export declare function computeHasRateLimitedHandler(state: RegistryState): void;
 export declare function publishEventPiiCatalog(state: RegistryState): void;

package/dist/engine/registry-validate.js

@@ -1,6 +1,7 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii.js";
 import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption.js";
 import { entityEventName } from "../db/event-store-executor-context.js";
+import { resolveMaxPerTenant } from "../jobs/max-per-tenant.js";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { resolveName } from "./handler-helpers.js";
 import { parseRefTargetEntityName } from "./parse-ref-target.js";
@@ -744,6 +745,26 @@ export function validateJobBackoff(state) {
         }
     }
 }
+export function validateMaxPerTenant(state) {
+    for (const [jobName, jobDef] of state.jobMap) {
+        const resolved = resolveMaxPerTenant(jobDef);
+        if (!resolved)
+            continue;
+        if (!Number.isInteger(resolved.limit) || resolved.limit <= 0) {
+            throw new Error(`Job "${jobName}" maxPerTenant limit must be a positive integer (got ${resolved.limit})`);
+        }
+        if (typeof jobDef.maxPerTenant !== "object")
+            continue;
+        const { deferMs } = jobDef.maxPerTenant;
+        if (deferMs !== undefined && (!Number.isInteger(deferMs) || deferMs <= 0)) {
+            throw new Error(`Job "${jobName}" maxPerTenant.deferMs must be a positive integer (got ${deferMs})`);
+        }
+        // The inline boot-gate path has no BullMQ token to move the job to delayed with.
+        if (resolved.onLimit === "defer" && jobDef.bootGate) {
+            throw new Error(`Job "${jobName}" cannot combine bootGate with maxPerTenant onLimit "defer"`);
+        }
+    }
+}
 export function validateExtensionUsageTargets(state) {
     // Validate: extension usages must reference existing extensions
     for (const usage of state.extensionUsages) {

package/dist/engine/registry.js

@@ -3,7 +3,7 @@ import { dedupeFeatures } from "./dedupe-features.js";
 import { buildRegistryFacade } from "./registry-facade.js";
 import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
-import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateNotificationRecordMappings, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
+import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxPerTenant, validateNotificationRecordMappings, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -48,6 +48,7 @@ export function createRegistry(rawFeatures) {
     validateBootGates(state);
     validateLiveEntities(state);
     validateJobBackoff(state);
+    validateMaxPerTenant(state);
     validateExtensionUsageTargets(state);
     computeHasRateLimitedHandler(state);
     publishEventPiiCatalog(state);

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

@@ -34,6 +34,7 @@ export type UnavailableSelectOption = {
 };
 /** Options of a select field that are offered for the given row values, in declaration order. */
 export declare function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): readonly string[];
+export declare function isUnchangedValue(a: unknown, b: unknown): boolean;
 /** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
  *  checked when it or one of its condition fields changed, so legacy rows stay editable. */
 export declare function findUnavailableSelectOptions(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): readonly UnavailableSelectOption[];

package/dist/engine/screen-helpers.js

@@ -126,7 +126,7 @@ export function availableSelectOptions(field, values) {
         return field.options;
     return field.options.filter((option) => rules.every((rule) => !rule.options.includes(option) || evalFieldCondition(rule.when, values)));
 }
-function isSameValue(a, b) {
+export function isUnchangedValue(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
 /** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
@@ -141,7 +141,7 @@ export function findUnavailableSelectOptions(fields, values, previous) {
             continue;
         if (previous) {
             const watched = [name, ...def.conditionalOptions.map((rule) => rule.when.field)];
-            if (watched.every((key) => isSameValue(values[key], previous[key])))
+            if (watched.every((key) => isUnchangedValue(values[key], previous[key])))
                 continue;
         }
         const allowed = availableSelectOptions(def, values);

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/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

@@ -1,5 +1,5 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
+export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, MaxPerTenantOptions, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "@cosmicdrift/kumiko-types/define-handler";
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";

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/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/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/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";