@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

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,7 @@ export function createApiEntrypoint(options) {
         lifecycle,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        lifecycleHooks: server.lifecycleHooks,
         ...(server.eventDispatcher && { eventDispatcher: server.eventDispatcher }),
         mode: "api",
         async start() {
@@ -319,6 +324,7 @@ export function createAllInOneEntrypoint(options) {
         jobRunner: workerJobRunner,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        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.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,

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,

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.js

@@ -12,13 +12,13 @@ import { isFileField, isUuid, } from "../engine/types/index.js";
 import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
-import { createFileContext } from "./file-handle.js";
+import { createFileContext, createTenantFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 import { RecordWriteDecisions } from "./record-write-check.js";
 import { neutralFileNameForMimeType } from "./resolve-content-type.js";
 import { parseMaxSize, resolveServedContentType } from "./types.js";
-import { createFileUploadLedger } from "./upload-ledger.js";
+import { withUploadLedger } from "./upload-ledger.js";
 // Exactly the httpStatus values declared by KumikoError subclasses across packages/*.
 const ERROR_STATUSES = [400, 401, 403, 404, 409, 422, 429, 500, 503, 504];
 export function deleteFailureResponseFor(error) {
@@ -102,6 +102,10 @@ export function readFilesRouteOptions(registry) {
 }
 export function createFileRoutes(options) {
     const { db } = options;
+    // Plain resolvers (not built via withFileProviderResolver) get the ledger on the route's own root connection.
+    const resolveProvider = options.resolveProvider.uploadLedgerFor
+        ? options.resolveProvider
+        : withUploadLedger(options.resolveProvider, db);
     const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
     const guard = options.accessGuard ??
         createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? []);
@@ -200,19 +204,18 @@ export function createFileRoutes(options) {
             }
         }
         const data = new Uint8Array(await file.arrayBuffer());
-        const storageProvider = await options.resolveProvider(user.tenantId);
-        const uploadLedger = createFileUploadLedger(db, user.tenantId);
+        const files = createTenantFileContext(resolveProvider, user.tenantId);
         const outcome = await storeFileAsFileRef({
             user,
             tenantDb: tenantDbFor(user.tenantId),
             rowInOwnTransaction: true,
             registry: options.registry,
             defaultMaxUploadSize: options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
-            writeBytes: async (key, bytes, mimeType) => {
-                await uploadLedger.record(key);
-                await storageProvider.write(key, bytes, mimeType);
+            writeBytes: (key, bytes, mimeType) => files.writeUploadBytes(key, bytes, mimeType),
+            deleteBytes: async (key) => {
+                await files.ref(key).delete();
+                await files.forgetUploadBytes(key);
             },
-            deleteBytes: (key) => storageProvider.delete(key),
         }, {
             fileName: file.name,
             declaredMimeType: file.type,

package/dist/files/resolve-content-type.js

@@ -46,6 +46,49 @@ const NON_XML_ROOT_ELEMENTS = new Set([
     "article",
     "font",
     "center",
+    "form",
+    "iframe",
+    "input",
+    "button",
+    "nav",
+    "header",
+    "footer",
+    "main",
+    "pre",
+    "code",
+    "b",
+    "i",
+    "strong",
+    "em",
+    "label",
+    "textarea",
+    "select",
+    "fieldset",
+    "legend",
+    "tr",
+    "td",
+    "th",
+    "thead",
+    "tbody",
+    "tfoot",
+    "object",
+    "embed",
+    "video",
+    "audio",
+    "canvas",
+    "math",
+    "picture",
+    "figure",
+    "figcaption",
+    "blockquote",
+    "dl",
+    "dt",
+    "dd",
+    "aside",
+    "details",
+    "summary",
+    "dialog",
+    "noscript",
 ]);
 const ROOT_ELEMENT_PATTERN = /^<(?:[A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)/;
 const EXTENSION_FALLBACK = {

package/dist/files/upload-ledger.js

@@ -1,6 +1,8 @@
 import { defineUnmanagedTable } from "../db/entity-table-meta.js";
+import { runnerCanBeginTransaction } from "../db/query.js";
 import { createTenantDb } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { InternalError } from "../errors/index.js";
 const CREATED_AT_INDEX = "store_file_upload_ledger_created_at_idx";
 // One row per upload whose bytes are in storage but whose fileRef row is not committed yet. The
 // commit path deletes it inside the transaction that creates the fileRef; the sweep finds the
@@ -21,6 +23,11 @@ function isTenantDb(db) {
 // handler must not take the row with it, or the bytes it uploaded would be unfindable.
 export function createFileUploadLedger(db, tenantId) {
     const runner = isTenantDb(db) ? tenantDbRunner(db) : db;
+    if (!runnerCanBeginTransaction(runner)) {
+        throw new InternalError({
+            message: "createFileUploadLedger: the connection is already inside a transaction; the ledger row would roll back with it and the uploaded bytes become unfindable",
+        });
+    }
     const ledgerDb = createTenantDb({ db: runner, tenantId });
     return {
         record: async (storageKey) => {