@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/engine/strip-disabled-features-from-app-schema.js

@@ -11,42 +11,80 @@
 // gone it also drops every action, redirect, nav and workspace member that
 // pointed at them. The one reference it does not resolve is a nav `parent`
 // pointing at a missing nav; that is pruned here.
+import { createFallbackLogger, scrubLogText } from "../logging/index.js";
 import { resolveScreenTargetQn } from "./boot-validator/screens.js";
+import { workspaceOwnerOf } from "./build-app-schema.js";
 import { isToggleableFeature } from "./effective-features.js";
+import { isPureGroupingNav } from "./project-app-schema-for-roles.js";
 import { isValidQn, qualifyEntityName } from "./qualified-name.js";
+const schemaLogger = createFallbackLogger("app-schema");
 // Sorted, so the result doubles as a stable cache key. The trial gate is
 // consulted like the dispatcher's feature gate does, but only for toggleable
 // features: a trial can only unlock tier (toggleable) features, so a
-// cascade-disabled always-on feature needs no gate call.
+// cascade-disabled always-on feature needs no gate call. A failing gate counts
+// as "not unlocked" (the handlers answer 403 then anyway), so a gate outage
+// hides the add-on instead of taking the whole schema endpoint down.
 export async function resolveDisabledFeatureNames(registry, effectiveFeatures, tenantId) {
     const enabled = effectiveFeatures(tenantId);
-    const disabled = [];
-    for (const [featureName, feature] of registry.features) {
-        if (enabled.has(featureName))
-            continue;
-        if (isToggleableFeature(feature) &&
-            (await effectiveFeatures.trialGate?.(tenantId, featureName))) {
-            continue;
+    const trialGate = effectiveFeatures.trialGate;
+    const disabled = [...registry.features].filter(([featureName]) => !enabled.has(featureName));
+    const unlockedByTrial = await Promise.all(disabled.map(async ([featureName, feature]) => {
+        if (trialGate === undefined || !isToggleableFeature(feature))
+            return false;
+        try {
+            return await trialGate(tenantId, featureName);
         }
-        disabled.push(featureName);
-    }
-    return disabled.sort();
+        catch (error) {
+            schemaLogger.warn("trial gate failed, treating feature as not unlocked", {
+                featureName,
+                error: scrubLogText(error instanceof Error ? error.message : String(error)),
+            });
+            return false;
+        }
+    }));
+    return disabled
+        .filter((_, index) => !unlockedByTrial[index])
+        .map(([featureName]) => featureName)
+        .sort();
 }
 function navParentQn(featureName, parent) {
     return isValidQn(parent) ? parent : qualifyEntityName(featureName, "nav", parent);
 }
-// Navs of enabled features whose parent chain ends in a removed nav.
+function navQnsByParent(features) {
+    const childrenByParent = new Map();
+    for (const feature of features) {
+        for (const nav of feature.navs ?? []) {
+            if (nav.parent === undefined)
+                continue;
+            const parentQn = navParentQn(feature.featureName, nav.parent);
+            const children = childrenByParent.get(parentQn) ?? [];
+            children.push(qualifyEntityName(feature.featureName, "nav", nav.id));
+            childrenByParent.set(parentQn, children);
+        }
+    }
+    return childrenByParent;
+}
+// Navs of enabled features whose parent chain ends in a removed nav, plus pure grouping
+// navs whose children are all removed (an empty section the role projection cannot drop,
+// because it only drops groups that still have children).
 function collectOrphanedNavQns(features, removedNavQns) {
     const orphaned = new Set();
+    const childrenByParent = navQnsByParent(features);
     let changed = true;
     while (changed) {
         changed = false;
         for (const feature of features) {
             for (const nav of feature.navs ?? []) {
                 const qn = qualifyEntityName(feature.featureName, "nav", nav.id);
-                if (removedNavQns.has(qn) || nav.parent === undefined)
+                if (removedNavQns.has(qn))
                     continue;
-                if (removedNavQns.has(navParentQn(feature.featureName, nav.parent))) {
+                const parentRemoved = nav.parent !== undefined &&
+                    removedNavQns.has(navParentQn(feature.featureName, nav.parent));
+                const children = childrenByParent.get(qn) ?? [];
+                const emptiedGroup = isPureGroupingNav(nav) &&
+                    children.length > 0 &&
+                    children.every((childQn) => removedNavQns.has(childQn));
+                if (parentRemoved || emptiedGroup) {
                     removedNavQns.add(qn);
                     orphaned.add(qn);
                     changed = true;
@@ -104,10 +142,13 @@ export function stripDisabledFeaturesFromAppSchema(schema, registry, disabledFea
         const { navs: _navs, ...rest } = feature;
         return navs.length > 0 ? { ...rest, navs } : rest;
     });
-    // Workspace definitions carry the short id the author declared; the owning
-    // feature is only known to the registry.
+    // Workspace ids are unique per feature only, so the owner decides. A definition the build did
+    // not register (schema assembled elsewhere) falls back to the short id.
     const disabledWorkspaceIds = new Set(disabledFeatureNames.flatMap((featureName) => Object.keys(registry.features.get(featureName)?.workspaces ?? {})));
-    const workspaces = schema.workspaces?.filter((ws) => !disabledWorkspaceIds.has(ws.definition.id));
+    const workspaces = schema.workspaces?.filter((ws) => {
+        const owner = workspaceOwnerOf(ws.definition);
+        return owner === undefined ? !disabledWorkspaceIds.has(ws.definition.id) : !disabled.has(owner);
+    });
     const { workspaces: _original, ...restSchema } = schema;
     return {
         ...restSchema,

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

@@ -1 +1,2 @@
 export type * from "@cosmicdrift/kumiko-types/feature";
+export type * from "@cosmicdrift/kumiko-types/feature-registrar";

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

@@ -4,10 +4,11 @@ export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefin
 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";
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
-export type { BootCheckContext, BootCheckFn, BootOptionName, EntityObjectDefinition, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, HookDefinition, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StackBootRequirement, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
+export type { BootCheckContext, BootCheckFn, BootOptionName, FeatureDefinition, FeatureMetricDef, FeatureMetricType, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StackBootRequirement, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
+export type { EntityObjectDefinition, FeatureRegistrar, HookDefinition, } from "@cosmicdrift/kumiko-types/feature-registrar";
 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, EntityFieldDefinition, EntityIndexDef, EntityLongTextFieldDef, EntityTextFieldDef, 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, ResolvedPiiStance, 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, 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, JobDeferral, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, ProviderPluginContext, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitOptions, 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, JobDeferral, 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, RateLimitOptions, 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, declaredRateLimitOptions, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isRateLimitOption, 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";
@@ -17,7 +18,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionRowIdOf, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormFieldDerivation, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, BundledListsOptions, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, ExpandableRowGrouping, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormFieldDerivation, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, ListTableOptions, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

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

@@ -1,2 +1,2 @@
 export type * from "@cosmicdrift/kumiko-types/screen";
-export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
+export { DEFAULT_EXPORT_MAX_ROWS, LIST_BULK_ACTION_KEYS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_BULK_SELECTION, MAX_EXPORT_MAX_ROWS, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";

package/dist/engine/types/screen.js

@@ -1 +1 @@
-export { relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
+export { DEFAULT_EXPORT_MAX_ROWS, LIST_BULK_ACTION_KEYS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_BULK_SELECTION, MAX_EXPORT_MAX_ROWS, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";

package/dist/engine/validate-projection-allowlist.js

@@ -24,6 +24,7 @@
 // statically; today it lives in this comment + the StepBuilder doc.
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { resolveTableName } from "../db/entity-table-meta.js";
 import { schemaTableName } from "../db/table-introspection.js";
 import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
@@ -79,7 +80,7 @@ export function validateProjectionAllowlist(features) {
     const aggregateTables = new Map();
     for (const f of features) {
         for (const [entityName, entity] of Object.entries(f.entities ?? {})) {
-            const tableName = entity.table ?? entityName;
+            const tableName = resolveTableName(entityName, entity, undefined);
             const existing = aggregateTables.get(tableName);
             if (existing && existing !== f.name) {
                 throw new Error(`Aggregate-table "${tableName}" is registered by both feature "${existing}" and feature "${f.name}" via r.entity. ` +

package/dist/entrypoint/index.d.ts

@@ -10,7 +10,7 @@ import type { Lifecycle } from "../lifecycle/index.ts";
 import type { ObservabilityProvider } from "../observability/index.ts";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher.ts";
 import type { EventDedup, EventDispatcher } from "../pipeline/index.ts";
-import type { SystemHooks } from "../pipeline/lifecycle-pipeline.ts";
+import type { LifecycleHooks, SystemHooks } from "../pipeline/lifecycle-pipeline.ts";
 export type BaseEntrypointOptions = {
     readonly registry: Registry;
     readonly context: AppContext;
@@ -21,6 +21,7 @@ export type BaseEntrypointOptions = {
     readonly systemHooks?: SystemHooks;
     readonly eventDedup?: EventDedup;
     readonly lifecycle?: Lifecycle;
+    readonly instanceId?: ServerOptions["instanceId"];
 };
 type JobsBlock = {
     readonly redisUrl: string;
@@ -49,6 +50,7 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
         readonly runLocal?: boolean;
     };
     readonly trustedProxyHops?: ServerOptions["trustedProxyHops"];
+    readonly errorDocs?: ServerOptions["errorDocs"];
 };
 export type WorkerEntrypointOptions = BaseEntrypointOptions & JobsBlock & {
     readonly eventDispatcher?: ServerOptions["eventDispatcher"];
@@ -61,6 +63,8 @@ export type ApiEntrypoint = {
     readonly lifecycle: Lifecycle;
     readonly observability: ObservabilityProvider;
     readonly dispatcher: Dispatcher;
+    readonly context: AppContext;
+    readonly lifecycleHooks: LifecycleHooks;
     readonly eventDispatcher?: EventDispatcher;
     readonly mode: "api";
     start(): Promise<void>;
@@ -71,6 +75,7 @@ export type WorkerEntrypoint = {
     readonly eventDispatcher: EventDispatcher;
     readonly jobRunner: JobRunner;
     readonly observability: ObservabilityProvider;
+    readonly context: AppContext;
     readonly dispatcher: Dispatcher;
     readonly mode: "worker";
     start(): Promise<void>;

package/dist/entrypoint/index.js

@@ -40,7 +40,8 @@
 // connected to any API instance via Redis Pub/Sub, no per-instance
 // cursor needed. Without REDIS_URL, the in-memory broker still only
 // reaches clients on the same process.
-import { buildServer, withFileProviderResolver } from "../api/server.js";
+import { buildServer } from "../api/server.js";
+import { withFileProviderResolver } from "../api/server-wiring.js";
 import { createJobRunner } from "../jobs/job-runner.js";
 import { createLifecycle } from "../lifecycle/index.js";
 import { createNoopProvider } from "../observability/index.js";
@@ -119,6 +120,8 @@ function buildApiServer(opts, lifecycle, dispatcherOverride, jobRunner, processL
         jwtIssuer: opts.jwtIssuer,
         auth: opts.auth,
         trustedProxyHops: opts.trustedProxyHops,
+        errorDocs: opts.errorDocs,
+        instanceId: opts.instanceId,
         anonymousAccess: opts.anonymousAccess,
         sseBroker: opts.sseBroker,
         rateLimit: opts.rateLimit,
@@ -145,6 +148,7 @@ function buildWorkerServer(opts, lifecycle, jobRunner) {
         jwtSecret: opts.jwtSecret,
         lifecycle,
         processLane: "worker",
+        instanceId: opts.instanceId,
         observability: opts.observability,
         dispatcherOptions,
         systemHooks: opts.systemHooks,
@@ -240,6 +244,8 @@ export function createApiEntrypoint(options) {
         lifecycle,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        context: server.context,
+        lifecycleHooks: server.lifecycleHooks,
         ...(server.eventDispatcher && { eventDispatcher: server.eventDispatcher }),
         mode: "api",
         async start() {
@@ -274,6 +280,7 @@ export function createWorkerEntrypoint(options) {
         jobRunner,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        context: server.context,
         mode: "worker",
         async start() {
             await eventDispatcher.start();
@@ -319,6 +326,8 @@ export function createAllInOneEntrypoint(options) {
         jobRunner: workerJobRunner,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        context: server.context,
+        lifecycleHooks: server.lifecycleHooks,
         mode: "all-in-one",
         async start() {
             await eventDispatcher.start();

package/dist/errors/docs-url.d.ts

@@ -1,5 +1,5 @@
 import type { KumikoError } from "./kumiko-error.ts";
-/** Links an app's own error reasons to its own docs; without it only framework reasons carry a docsUrl. */
+/** Links an app's own error reasons to its own docs; uncovered reasons fall back to the framework page of the error code. */
 export type ErrorDocsConfig = {
     readonly baseUrl: string;
     readonly reasons?: readonly string[] | "all";

package/dist/errors/docs-url.js

@@ -5,6 +5,26 @@ const frameworkReasons = new Set([
     ...Object.values(FrameworkReasons),
     ...Object.values(AgentReasons),
 ]);
+// Codes of the built-in error classes: only these have a framework docs page.
+const frameworkErrorCodes = new Set([
+    "validation_error",
+    "feature_disabled",
+    "access_denied",
+    "unauthenticated",
+    "not_found",
+    "conflict",
+    "version_conflict",
+    "precondition_failed",
+    "record_locked",
+    "idempotent_replay",
+    "unique_violation",
+    "unprocessable",
+    "unconfigured",
+    "internal_error",
+    "member_read_timeout",
+    "rate_limited",
+    "rate_limit_unavailable",
+]);
 function reasonOf(err) {
     if (!err.details || typeof err.details !== "object")
         return undefined;
@@ -22,7 +42,7 @@ function errorsUrl(baseUrl, slug) {
 }
 // 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.
+// other reason falls back to the framework page of the error code, unless an app subclass overrode the code.
 export function resolveErrorDocsUrl(err, errorDocs) {
     const reason = reasonOf(err);
     const frameworkBaseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
@@ -32,5 +52,5 @@ export function resolveErrorDocsUrl(err, errorDocs) {
     if (errorDocs && isCoveredByConfig(reason, errorDocs)) {
         return errorsUrl(errorDocs.baseUrl, reason);
     }
-    return errorsUrl(frameworkBaseUrl, err.code);
+    return frameworkErrorCodes.has(err.code) ? errorsUrl(frameworkBaseUrl, err.code) : undefined;
 }

package/dist/es-ops/context.js

@@ -43,7 +43,7 @@ export function createSeedMigrationContext(args) {
             if (!result.isSuccess) {
                 const code = result.error?.code ?? "unknown";
                 const message = result.error?.message ?? "(no message)";
-                throw new Error(`[es-ops/seed-migration] systemWriteAs("${handlerQualifiedName}") failed: ${code} — ${message}`);
+                throw new Error(`systemWriteAs("${handlerQualifiedName}") failed: ${code} — ${message}`);
             }
             return result;
         },

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

@@ -6,10 +6,10 @@
 // path `@cosmicdrift/kumiko-framework/event-store/admin-api`. The guard script
 // `scripts/guard-admin-api.ts` blocks calls from application code. Allowlist: samples/*/migration/,
 // scripts/migrations/, this definition, and the guard script itself.
+import { instantToTimestamptzParam } from "../db/driver-value-preparation.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";
-import { instantToTimestamptzParam } from "../db/query.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
 function mapEventUniqueViolation(e, event) {
     if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {

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

@@ -19,6 +19,7 @@ export declare function append(db: DbRunner, event: EventToAppend): Promise<Stor
 export declare function loadAggregate(db: DbRunner, aggregateId: string, tenantId: TenantId, options?: {
     readonly includeArchived?: boolean;
     readonly aggregateType?: string;
+    readonly atVersion?: number;
 }): Promise<readonly StoredEvent[]>;
 export declare function loadAggregateForWriting(db: DbRunner, aggregateId: string, tenantId: TenantId, options: {
     readonly aggregateType: string;

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

@@ -3,9 +3,10 @@ import { isPersonalDataGated, UNATTRIBUTED_ORIGIN, } from "@cosmicdrift/kumiko-t
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
+import { instantToTimestamptzParam } from "../db/driver-value-preparation.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
-import { instantToTimestamptzParam, selectMany } from "../db/query.js";
+import { selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 import { eventsTable } from "./events-schema.js";
@@ -14,8 +15,11 @@ import { currentSeedCreatedAt } from "./seed-clock.js";
 // Append one event atomically. Two guarantees combined:
 //
 //   1. UNIQUE (tenant_id, aggregate_id, version) serializes concurrent writers
-//      within a tenant — a second writer racing the same expectedVersion
-//      receives a PG unique violation (SQLSTATE 23505) → VersionConflictError.
+//      within a tenant. A second writer racing the same expectedVersion hits
+//      ON CONFLICT DO NOTHING (no row), then the stream version is read inside
+//      the still-intact transaction → VersionConflictError. That relies on
+//      READ COMMITTED; REPEATABLE READ/SERIALIZABLE raise 40001 instead. Only
+//      the idempotency index still raises 23505.
 //      Cross-tenant aggregate_id collisions are not conflicts by definition:
 //      two tenants owning a row with the same UUID is just isolation, not a
 //      race.
@@ -28,7 +32,7 @@ import { currentSeedCreatedAt } from "./seed-clock.js";
 //      stays semantically obvious when read in isolation.
 //
 // Creates (expectedVersion === 0) skip the predecessor check — no predecessor
-// exists yet. Colliding creates fall out via UNIQUE (tenant_id, aggregate_id, version=1).
+// exists yet. Colliding creates fall out via the same index (tenant_id, aggregate_id, version=1).
 // Channel name used by append() → NOTIFY and the event-dispatcher → LISTEN
 // (Sprint E.4). The event-dispatcher subscribes to this channel on start and
 // fires a runOnce immediately on each commit, so delivery latency is bounded
@@ -66,6 +70,8 @@ export async function append(db, event) {
     }
     catch (e) {
         if (isUniqueViolation(e)) {
+            // The version index normally never throws (ON CONFLICT DO NOTHING); it
+            // only lands here for an unknown or renamed constraint.
             // Two unique constraints on this table: events_aggregate_version_uq
             // (tenant_id, aggregate_id, version) — a concurrent writer won the
             // race to the next version — and events_idempotency_uq (tenant_id,
@@ -207,9 +213,12 @@ export async function loadAggregate(db, aggregateId, tenantId, options) {
         if (archived)
             return [];
     }
-    const rows = await selectMany(db, eventsTable, options?.aggregateType !== undefined
-        ? { aggregateId, tenantId, aggregateType: options.aggregateType }
-        : { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
+    const rows = await selectMany(db, eventsTable, {
+        aggregateId,
+        tenantId,
+        ...(options?.aggregateType !== undefined && { aggregateType: options.aggregateType }),
+        ...(options?.atVersion !== undefined && { version: options.atVersion }),
+    }, { 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
@@ -305,7 +314,7 @@ export async function loadEventsAfterVersion(db, aggregateId, tenantId, afterVer
 // abort iteration. Checked both at batch boundaries (before the next
 // fetch) AND between yields (so abort lands within one event regardless
 // of batch size). Throws AbortError on the first check after abort;
-// in-flight queries are not actively cancelled (postgres-js connection-
+// in-flight queries are not actively cancelled (connection
 // cancel is a separate, riskier concern handled per-query at the TenantDb
 // boundary).
 export async function* streamAllEventsByType(db, aggregateType, batchSize = 1000, signal) {

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

@@ -32,7 +32,7 @@ export async function appendProvenanceEvent(db, event) {
             message: `appendProvenanceEvent: event tenant "${event.tenantId}" does not match the TenantDb's tenant "${db.tenantId}".`,
         });
     }
-    // postgres-js aborts the whole surrounding begin() on a statement
+    // Postgres aborts the whole surrounding transaction on a statement
     // error (25P02) even when the caller's catch swallows it — the savepoint
     // confines that to this scope. Pool connections have no ambient tx to poison.
     await runInSavepointIfSupported(runner, async (sp) => {

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

@@ -13,6 +13,9 @@ export function fileRefIdsOf(value) {
     return value.filter((item) => typeof item === "string" && isUuid(item));
 }
 function isPendingUploadFor(row, entityName, fieldName, user) {
+    // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
+    if (isAnonymousSessionUser(user))
+        return false;
     return (row["entityId"] === null &&
         row["entityType"] === entityName &&
         row["fieldName"] === fieldName &&
@@ -79,9 +82,6 @@ export async function bindPendingFileRefs(args) {
 }
 async function loadPendingRow(lookup) {
     const { fileRefId, entityName, fieldName, user, db } = lookup;
-    // Every anonymous visitor shares one user id, so insertedById cannot tell their uploads apart.
-    if (isAnonymousSessionUser(user))
-        return undefined;
     if (!isUuid(fileRefId))
         return undefined;
     const row = (await loadFileRefRows(db, [fileRefId], user.tenantId)).get(fileRefId);

package/dist/files/create-file-ref-from-bytes.js

@@ -27,7 +27,10 @@ export async function createFileRefFromBytes(ctx, input) {
         registry: ctx.registry,
         defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
         writeBytes: (key, data, mimeType) => files.writeUploadBytes(key, data, mimeType),
-        deleteBytes: (key) => files.ref(key).delete(),
+        deleteBytes: async (key) => {
+            await files.ref(key).delete();
+            await files.forgetUploadBytes(key);
+        },
     }, {
         fileName: input.fileName,
         declaredMimeType: input.mimeType,
@@ -43,6 +46,9 @@ export async function createFileRefFromBytes(ctx, input) {
             return fileRejectedFailure(outcome.error);
         case "failed":
             return outcome.failure;
+        case "target-locked":
+            // Only the HTTP route supplies the lock re-check, so this path cannot produce it.
+            return writeFailure(new InternalError({ message: "createFileRefFromBytes: unexpected target-locked outcome" }));
     }
 }
 function fileRejectedFailure(error) {

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

@@ -50,6 +50,7 @@ export type StoreFileDeps = {
     readonly defaultMaxUploadSize: string;
     readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;
     readonly deleteBytes: (storageKey: string) => Promise<void>;
+    readonly isAttachTargetLocked?: (rowDb: TenantDb) => Promise<boolean>;
 };
 export type CreatedFileRef = {
     readonly id: string;
@@ -80,6 +81,8 @@ export type StoreFileOutcome = {
 } | {
     readonly kind: "rejected";
     readonly error: string;
+} | {
+    readonly kind: "target-locked";
 } | {
     readonly kind: "failed";
     readonly failure: WriteFailure;

package/dist/files/create-file-ref.js

@@ -41,6 +41,8 @@ export function resolveAttachedField(registry, entityType, fieldName) {
         return { kind: "unresolvable" };
     return { kind: "resolved", fieldDef };
 }
+class AttachTargetLockedError extends Error {
+}
 function resolveUploadField(registry, input) {
     const { entityType, entityId, fieldName, actionForm } = input;
     if (actionForm === undefined)
@@ -196,14 +198,21 @@ export async function storeFileAsFileRef(deps, input) {
             // skip: the create failure is the error worth reporting; the leftover bytes stay in storage.
         }
     };
+    const createRow = async (rowDb) => {
+        if (await deps.isAttachTargetLocked?.(rowDb))
+            throw new AttachTargetLockedError();
+        return createFileRefRow({ user: deps.user, tenantDb: rowDb }, upload.uploaded);
+    };
     let row;
     try {
         row = deps.rowInOwnTransaction
-            ? await runInOwnTransaction(deps.tenantDb, (txDb) => createFileRefRow({ user: deps.user, tenantDb: txDb }, upload.uploaded))
-            : await createFileRefRow(deps, upload.uploaded);
+            ? await runInOwnTransaction(deps.tenantDb, createRow)
+            : await createRow(deps.tenantDb);
     }
     catch (e) {
         await deleteUploadedBytes();
+        if (e instanceof AttachTargetLockedError)
+            return { kind: "target-locked" };
         throw e;
     }
     if ("failure" in row) {

package/dist/files/file-handle.js

@@ -10,7 +10,7 @@
 // suffix before the file extension — `foo/bar.jpg` + `"medium-<16 hex>"` →
 // `foo/bar.medium-<16 hex>.jpg`. The suffix must be a `variantSuffix(...)` so
 // the erasure sweep recognizes it. Stable, reversible, no extra lookup tables.
-import { isDerivativeSuffix } from "../derivatives/variant-key.js";
+import { derivativeListPrefix, isDerivativeSuffix } from "../derivatives/variant-key.js";
 import { InternalError } from "../errors/index.js";
 import { assertSafeStorageKey } from "./types.js";
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
@@ -127,6 +127,5 @@ export function deriveKey(key, suffix) {
 // fileRef's original plus every already-rendered derivative, none of which have their own
 // `file_refs` row.
 export function storageKeyStemPrefix(key) {
-    const { stem, ext } = splitKeyExtension(key);
-    return ext === "" ? `${key}.` : `${stem}.`;
+    return derivativeListPrefix(key);
 }

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

@@ -1,3 +1,4 @@
+import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type { WriteErrorInfo } from "@cosmicdrift/kumiko-types/write-error-info-types";
 import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.ts";
@@ -30,6 +31,7 @@ export type FileAccessGuard = (args: {
 }) => FileAccessDecision | Promise<FileAccessDecision>;
 export type FileRoutesOptions = {
     readonly db: DbConnection;
+    readonly metaBatchRateLimitResolver?: RateLimitResolver;
     readonly resolveProvider: FileProviderResolver;
     readonly registry?: Registry;
     readonly maxUploadSize?: string;