@cosmicdrift/kumiko-framework 0.364.0 → 0.365.0

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

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

@@ -1,4 +1,4 @@
-import type { TenantDb } from "../db/tenant-db.js";
+import { type TenantDb } from "../db/tenant-db.js";
 import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.js";
 import type { WriteFailure } from "../errors/index.js";
 export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
@@ -24,6 +24,7 @@ export type StoreFileInput = {
 export type StoreFileDeps = {
     readonly user: SessionUser;
     readonly tenantDb: TenantDb;
+    readonly rowInOwnTransaction?: boolean;
     readonly registry: Registry | undefined;
     readonly defaultMaxUploadSize: string;
     readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;

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

@@ -1,4 +1,5 @@
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { runInOwnTransaction } from "../db/tenant-db.js";
 import { isFileField, } from "../engine/types/index.js";
 import { generateId } from "../utils/index.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
@@ -149,14 +150,27 @@ export async function storeFileAsFileRef(deps, input) {
     // A failed create deletes the bytes again; a later rollback of an enclosing transaction or a
     // crash cannot, so those bytes stay in storage (no job sweeps an original without a fileRef row).
     // Losing a row on append-failure is acceptable; a committed row with a missing binary is not.
-    const row = await createFileRefRow(deps, upload.uploaded);
-    if ("failure" in row) {
+    // A throwing projection on fileRef.created fails the create by exception, not by WriteFailure.
+    const deleteUploadedBytes = async () => {
         try {
             await deps.deleteBytes(upload.uploaded.storageKey);
         }
         catch {
             // skip: the create failure is the error worth reporting; the leftover bytes stay in storage.
         }
+    };
+    let row;
+    try {
+        row = deps.rowInOwnTransaction
+            ? await runInOwnTransaction(deps.tenantDb, (txDb) => createFileRefRow({ user: deps.user, tenantDb: txDb }, upload.uploaded))
+            : await createFileRefRow(deps, upload.uploaded);
+    }
+    catch (e) {
+        await deleteUploadedBytes();
+        throw e;
+    }
+    if ("failure" in row) {
+        await deleteUploadedBytes();
         return { kind: "failed", failure: row.failure };
     }
     return { kind: "created", fileRef: row.fileRef };

package/dist/files/dispose-removed-file-refs.js

@@ -3,16 +3,31 @@ import { reraiseAsKumikoError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
-function isBoundTo(row, entityName, entityId, fieldName) {
+// The bound fieldName may differ from the field the id was removed from: an id
+// moved A -> B stays bound to A (binding never re-targets).
+function isBoundToRecord(row, entityName, entityId, fileFields) {
+    const boundField = row["fieldName"];
     return (row["entityType"] === entityName &&
         row["entityId"] === entityId &&
-        row["fieldName"] === fieldName);
+        typeof boundField === "string" &&
+        isFileField(fileFields[boundField]));
+}
+// Across all file fields: an id moved from one field to another is still in use.
+function fileRefIdsStoredInAnyField(fields, data) {
+    const ids = new Set();
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        if (!isFileField(fieldDef))
+            continue;
+        for (const fileRefId of fileRefIdsOf(data[fieldName]))
+            ids.add(fileRefId);
+    }
+    return ids;
 }
 // An update that drops or replaces a file id leaves the fileRef readable to
 // everyone who may read the record. Deleting it goes through the same executor
 // path as DELETE /files/:id (soft delete, bytes kept until retention), so
 // record readers get 404 afterwards. Only fileRefs bound to exactly this
-// record and field are touched: an id that is pending, shared or bound
+// record are touched: an id that is pending, shared or bound
 // elsewhere is not this save's to dispose. The authority is the caller's write
 // right on the record (the fileRef entity declares no write access of its own).
 export async function disposeRemovedFileRefs(args) {
@@ -33,15 +48,15 @@ export async function disposeRemovedFileRefs(args) {
         return;
     const entityId = String(result.id);
     const executor = getFileRefExecutor();
+    const keptAnywhere = fileRefIdsStoredInAnyField(entity.fields, result.data);
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef) || !(fieldName in result.changes))
             continue;
-        const kept = new Set(fileRefIdsOf(result.data[fieldName]));
         for (const fileRefId of fileRefIdsOf(result.previous[fieldName])) {
-            if (kept.has(fileRefId))
+            if (keptAnywhere.has(fileRefId))
                 continue;
             const row = await executor.detail({ id: fileRefId }, user, db);
-            if (row === null || !isBoundTo(row, entityName, entityId, fieldName))
+            if (row === null || !isBoundToRecord(row, entityName, entityId, entity.fields))
                 continue;
             const removed = await executor.delete({ id: fileRefId }, user, db);
             if (!removed.isSuccess)

package/dist/files/feature.d.ts

@@ -7,4 +7,5 @@ export type FilesFeatureOptions = {
     readonly unclaimedUploadReaders?: readonly string[];
     readonly maxUploadSize?: string;
 };
+export declare const FILES_FEATURE: "files";
 export declare function createFilesFeature(options?: FilesFeatureOptions): FeatureDefinition;

package/dist/files/feature.js

@@ -13,8 +13,9 @@ export { fileRefEntity } from "./file-ref-entity.js";
 // userData/tenantData-Extensions sichtbar und registriert die implizite
 // Entity-Projektion (für rebuildProjection). Liegt im Framework neben
 // file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
+export const FILES_FEATURE = "files";
 export function createFilesFeature(options = {}) {
-    return defineFeature("files", (r) => {
+    return defineFeature(FILES_FEATURE, (r) => {
         r.describe("Exposes the `fileRef` entity from the framework core so that uploaded files — tracked in the `file_refs` table by `createFileRoutes` — participate in cross-feature hooks: `user-data-rights-defaults` automatically includes file blobs in GDPR exports and forget flows, and tenant-lifecycle cleanup deletes all refs on tenant destroy. Upload/download routes are registered by the server bootstrap when a `file-provider-*` feature is mounted; this feature carries their access/size policy via `createFilesFeature(opts?)`.");
         r.uiHints({
             displayLabel: "Files · Metadata",

package/dist/files/file-handle.js

@@ -62,6 +62,10 @@ export function createFileContext(resolve, tenantId) {
             assertSafeStorageKey(row.storageKey);
             return createFileHandle(row.storageKey, getProvider);
         },
+        listFromFileRef: async (row) => {
+            assertSafeStorageKey(row.storageKey);
+            return (await getProvider()).list(storageKeyStemPrefix(row.storageKey));
+        },
         list: async (prefix) => {
             if (tenantId !== undefined && !prefix.startsWith(`${tenantId}/`)) {
                 throw new Error(`FileContext.list: prefix must start with "${tenantId}/"`);

package/dist/files/file-routes.js

@@ -4,8 +4,9 @@ import { getUser } from "../api/auth-middleware.js";
 import { requestContext } from "../api/request-context.js";
 import { selectMany } from "../bun-db/index.js";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
-import { createTenantDb } from "../db/tenant-db.js";
+import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
+import { SYSTEM_USER_ID } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
@@ -32,8 +33,11 @@ function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReade
             return "allow";
         if (privilegedRoles.some((role) => user.roles.includes(role)))
             return "allow";
-        const isUnclaimed = fileRef.entityType === null && fileRef.entityId === null;
-        if (isUnclaimed &&
+        // System-generated documents are created without attachTo too, but belong to a person's data, not to an inbox.
+        const isUnclaimedUpload = fileRef.entityType === null &&
+            fileRef.entityId === null &&
+            fileRef.insertedById !== SYSTEM_USER_ID;
+        if (isUnclaimedUpload &&
             operation === "read" &&
             unclaimedUploadReaders.some((role) => user.roles.includes(role))) {
             return "allow";
@@ -88,8 +92,7 @@ export function createFileRoutes(options) {
     const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();
-    const projectionGrants = options.registry ? { projectionRegistry: options.registry } : undefined;
-    const tenantDbFor = (tenantId) => createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionGrants);
+    const tenantDbFor = (tenantId) => createProjectingTenantDb(db, tenantId, options.registry);
     const fileNameIsPersonal = piiSubjectFields.includes("fileName");
     function kmsContextFor() {
         return { requestId: requestContext.get()?.requestId ?? "file-routes" };
@@ -171,6 +174,7 @@ export function createFileRoutes(options) {
         const outcome = await storeFileAsFileRef({
             user,
             tenantDb: tenantDbFor(user.tenantId),
+            rowInOwnTransaction: true,
             registry: options.registry,
             defaultMaxUploadSize: options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
             writeBytes: (key, bytes, mimeType) => storageProvider.write(key, bytes, mimeType),

package/dist/files/index.d.ts

@@ -1,6 +1,6 @@
 export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
-export { createFilesFeature } from "./feature.js";
+export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 export type { FileContext, FileHandle } from "./file-handle.js";
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";
 export { fileRefEntity } from "./file-ref-entity.js";

package/dist/files/index.js

@@ -1,5 +1,5 @@
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
-export { createFilesFeature } from "./feature.js";
+export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, deriveKey, storageKeyStemPrefix } from "./file-handle.js";

package/dist/files/purge-expired-file-ref-bytes.js

@@ -1,5 +1,5 @@
 import { deleteMany, selectMany } from "../db/query.js";
-import { deleteStoredFileAndDerivatives } from "../derivatives/delete-stored-file.js";
+import { deleteFileRefBytes } from "../derivatives/delete-stored-file.js";
 export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
 const PAGE_ORDER = [
     { col: "deletedAt", direction: "asc" },
@@ -31,7 +31,6 @@ export async function purgeExpiredFileRefsWithBytes(args) {
         log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
         return;
     }
-    const store = { list: files.list, delete: (key) => files.ref(key).delete() };
     let cursor;
     for (;;) {
         const rows = await selectNextPage({ db, table, where, expiredBefore, cursor, pageSize });
@@ -43,7 +42,7 @@ export async function purgeExpiredFileRefsWithBytes(args) {
         const purgedIds = [];
         for (const row of rows) {
             try {
-                const failedKeys = await deleteStoredFileAndDerivatives(row.storageKey, store, "soft-delete-cleanup:fileRef");
+                const failedKeys = await deleteFileRefBytes(files, row, "soft-delete-cleanup:fileRef");
                 if (failedKeys.length === 0) {
                     purgedIds.push(row.id);
                     continue;

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

@@ -13,6 +13,41 @@ const UNAMBIGUOUS_SNIFFED_TYPES = new Set([
 ]);
 const ZIP_SIGNATURE = [0x50, 0x4b, 0x03, 0x04];
 const XML_PROBE_BYTES = 512;
+// Root elements of markup that starts with `<` but is not a document the XML
+// ingest providers should receive: HTML (documents and fragments), SVG.
+const NON_XML_ROOT_ELEMENTS = new Set([
+    "html",
+    "head",
+    "body",
+    "script",
+    "style",
+    "meta",
+    "link",
+    "title",
+    "svg",
+    "div",
+    "span",
+    "p",
+    "a",
+    "img",
+    "br",
+    "hr",
+    "table",
+    "ul",
+    "ol",
+    "li",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "section",
+    "article",
+    "font",
+    "center",
+]);
+const ROOT_ELEMENT_PATTERN = /^<(?:[A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)/;
 const EXTENSION_FALLBACK = {
     xml: "application/xml",
     pdf: "application/pdf",
@@ -38,8 +73,8 @@ function hasPrefix(bytes, prefix) {
     return prefix.every((byte, i) => bytes[i] === byte);
 }
 // Textual start only: a NUL in the probe means binary (or UTF-16, which is
-// deliberately not detected). HTML also starts with `<` and must not be
-// relabelled as XML.
+// deliberately not detected). Without an XML declaration the root element
+// decides: HTML/SVG roots (also namespace-prefixed) are not relabelled as XML.
 function looksLikeXml(bytes) {
     const probe = bytes.subarray(0, XML_PROBE_BYTES);
     if (probe.includes(0))
@@ -47,9 +82,10 @@ function looksLikeXml(bytes) {
     const text = new TextDecoder().decode(probe).replace(/^/, "").trimStart();
     if (text.startsWith("<?xml"))
         return true;
-    if (!/^<[A-Za-z_]/.test(text))
+    const root = ROOT_ELEMENT_PATTERN.exec(text)?.[1];
+    if (root === undefined)
         return false;
-    return !/^<(html|head|body|script)\b/i.test(text);
+    return !NON_XML_ROOT_ELEMENTS.has(root.toLowerCase());
 }
 function extensionOf(filename) {
     const dot = filename.lastIndexOf(".");

package/dist/files/storage-tracking.js

@@ -12,6 +12,7 @@
 // into createApp / setupTestStack alongside their domain features.
 import { bigint, instant, integer, table as pgTable, sql, uuid } from "../db/dialect.js";
 import { entityEventName, executeRawQueryRead } from "../db/index.js";
+import { toPostgresArrayLiteral } from "../db/queries/postgres-array-literal.js";
 import { incrementCounter } from "../db/query.js";
 import { defineFeature, qn, toKebab } from "../engine/index.js";
 import { SHARED_INSTANCE_SENTINEL, selectConsumerCursorForUpdate, } from "../pipeline/index.js";
@@ -141,12 +142,12 @@ export async function transferTenantStorageUsage(args) {
     if (!cursor)
         return;
     const rows = await executeRawQueryRead(db, `SELECT "id"::text AS id, "type", "payload"::text AS payload FROM kumiko_events
-     WHERE "tenant_id" = $1 AND "aggregate_type" = $2 AND "aggregate_id" = ANY($3)
-       AND "type" = ANY($4) AND "id" <= $5`, [
+     WHERE "tenant_id" = $1 AND "aggregate_type" = $2 AND "aggregate_id" = ANY($3::uuid[])
+       AND "type" = ANY($4::text[]) AND "id" <= $5`, [
         sourceTenantId,
         FILE_REF_AGGREGATE_TYPE,
-        fileRefIds,
-        TRACKED_FILE_REF_EVENT_TYPES,
+        toPostgresArrayLiteral(fileRefIds),
+        toPostgresArrayLiteral(TRACKED_FILE_REF_EVENT_TYPES),
         cursor.lastProcessedEventId,
     ]);
     let bytes = 0;

package/dist/files/types.js

@@ -1,3 +1,4 @@
+import { readZipEntryNames } from "./zip-entry-names.js";
 // Lives here (not in file-ref-entity.ts) so engine code can name the entity without importing
 // a module that calls createEntity at load time.
 export const FILE_REF_ENTITY_NAME = "fileRef";
@@ -111,13 +112,9 @@ const MAGIC_BYTE_SIGNATURES = [
 // so a byte search finds the docx part directory without unzipping. The main
 // part is resolved via _rels/.rels and may be named e.g. word/document2.xml.
 const DOCX_PART_PREFIX = "word/";
-function containsAscii(bytes, ascii) {
-    const first = ascii.charCodeAt(0);
-    for (let i = bytes.indexOf(first); i !== -1; i = bytes.indexOf(first, i + 1)) {
-        if (startsWithAscii(bytes, ascii, i))
-            return true;
-    }
-    return false;
+function hasDocxPart(zipBytes) {
+    const names = readZipEntryNames(zipBytes);
+    return names?.some((name) => name.startsWith(DOCX_PART_PREFIX)) ?? false;
 }
 function startsWithBytes(bytes, signature) {
     if (bytes.length < signature.length)
@@ -237,7 +234,7 @@ export function validateFileContent(fileName, content, accept) {
         return { kind: "ok" };
     const sniffed = sniffMimeType(content);
     // sniffMimeType only sees the ZIP container; any .xlsx/.pptx/.zip shares it.
-    if (sniffed === DOCX_MIME_TYPE && !containsAscii(content, DOCX_PART_PREFIX)) {
+    if (sniffed === DOCX_MIME_TYPE && !hasDocxPart(content)) {
         return {
             kind: "rejected",
             error: `content_mismatch: ".${ext}" upload bytes are a ZIP archive without ${DOCX_PART_PREFIX} entries, not a docx`,

package/dist/files/zip-entry-names.d.ts

@@ -0,0 +1 @@
+export declare function readZipEntryNames(bytes: Uint8Array): readonly string[] | null;

package/dist/files/zip-entry-names.js

@@ -0,0 +1,46 @@
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_HEADER_SIGNATURE = 0x02014b50;
+const EOCD_MIN_LENGTH = 22;
+const EOCD_MAX_COMMENT_LENGTH = 0xffff;
+const CENTRAL_HEADER_FIXED_LENGTH = 46;
+// Entry names from the central directory, which (unlike local headers) always
+// carries sizes and names even for streamed ZIPs written with data descriptors.
+// Returns null when the container is not a readable (non-ZIP64) ZIP.
+export function readZipEntryNames(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const eocdOffset = findEndOfCentralDirectory(view);
+    if (eocdOffset === null)
+        return null;
+    const entryCount = view.getUint16(eocdOffset + 10, true);
+    let offset = view.getUint32(eocdOffset + 16, true);
+    const decoder = new TextDecoder();
+    const names = [];
+    for (let i = 0; i < entryCount; i++) {
+        if (offset + CENTRAL_HEADER_FIXED_LENGTH > view.byteLength)
+            return null;
+        if (view.getUint32(offset, true) !== CENTRAL_HEADER_SIGNATURE)
+            return null;
+        const nameLength = view.getUint16(offset + 28, true);
+        const extraLength = view.getUint16(offset + 30, true);
+        const commentLength = view.getUint16(offset + 32, true);
+        const nameStart = offset + CENTRAL_HEADER_FIXED_LENGTH;
+        if (nameStart + nameLength > view.byteLength)
+            return null;
+        names.push(decoder.decode(bytes.subarray(nameStart, nameStart + nameLength)));
+        offset = nameStart + nameLength + extraLength + commentLength;
+    }
+    return names;
+}
+function findEndOfCentralDirectory(view) {
+    const lowest = Math.max(0, view.byteLength - EOCD_MIN_LENGTH - EOCD_MAX_COMMENT_LENGTH);
+    for (let offset = view.byteLength - EOCD_MIN_LENGTH; offset >= lowest; offset--) {
+        if (view.getUint32(offset, true) !== EOCD_SIGNATURE)
+            continue;
+        // A signature inside the archive comment is skipped: the real record's
+        // comment length reaches exactly to the end of the buffer.
+        const commentLength = view.getUint16(offset + 20, true);
+        if (offset + EOCD_MIN_LENGTH + commentLength === view.byteLength)
+            return offset;
+    }
+    return null;
+}

package/dist/jobs/job-runner.d.ts

@@ -60,6 +60,7 @@ export type JobRunnerOptions = {
     consumerLane?: JobRunIn | undefined;
     queueNamePrefix?: string | undefined;
     bootRedisTimeoutMs?: number | undefined;
+    schedulerSeenRefreshMs?: number | undefined;
     jobRetention?: {
         completedAgeSec?: number | undefined;
         failedAgeSec?: number | undefined;