@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/jobs/job-runner.js

@@ -1,4 +1,5 @@
 import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
@@ -24,12 +25,11 @@ import { cronRepeatOptions } from "./cron-repeat-options.js";
 // run proceeds without it rather than failing over what would be a framework
 // bug, not untrusted input.
 function isJobTriggerEvent(value) {
-    if (typeof value !== "object" || value === null)
+    if (!isPlainObject(value))
         return false;
-    const candidate = value;
-    if (typeof candidate["id"] !== "string")
+    if (typeof value["id"] !== "string")
         return false;
-    const headers = candidate["headers"];
+    const headers = value["headers"];
     if (typeof headers !== "object" || headers === null)
         return false;
     return Object.values(headers).every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean");
@@ -611,12 +611,16 @@ export function createJobRunner(options) {
             });
         }
     }
-    async function announceDropped(jobName, jobDef, bullJobId) {
+    async function announceDropped(jobName, jobDef, bullJobId, data) {
         // skip: job did not opt in or no logger wired
         if (!jobDef.tenantVisibleRun || !options.onJobDropped)
             return;
+        const tenantId = tenantIdOfJobData(data);
+        // skip: tenant-less run — announceQueued never recorded a row for it
+        if (tenantId === SYSTEM_TENANT_ID)
+            return;
         try {
-            await options.onJobDropped(jobName, bullJobId);
+            await options.onJobDropped(jobName, bullJobId, { tenantId });
         }
         catch (err) {
             errorLogger.warn("tenant-visible queued state not cleared", {
@@ -732,7 +736,7 @@ export function createJobRunner(options) {
                     ...buildRetryBullOpts(jobDef, priorAttempts),
                 });
                 if (bullJob.id !== undefined && bullJob.id !== requeued.id) {
-                    await announceDropped(jobName, jobDef, bullJob.id);
+                    await announceDropped(jobName, jobDef, bullJob.id, bullJob.data);
                 }
                 await announceQueued(jobName, jobDef, requeued.id, requeuedData);
                 // skip: lock taken, work re-enqueued with delay, current invocation done
@@ -834,7 +838,7 @@ export function createJobRunner(options) {
         // must resolve for jobs the same way they do for write-handlers, or an
         // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
         // at runtime the write-handler path never would (framework#1532).
-        const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner);
+        const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner, undefined, context._fileProviderResolver);
         const configDb = context.db; // @cast-boundary db-operator
         // Shared by the config accessor and ctx.derivatives below — both need the
         // same tenant-scoped db, and building it twice would let the two calls
@@ -1298,7 +1302,7 @@ export function createJobRunner(options) {
                     for (const j of waiting) {
                         if (j.name === jobName && j.id) {
                             await j.remove();
-                            await announceDropped(jobName, jobDef, j.id);
+                            await announceDropped(jobName, jobDef, j.id, j.data);
                         }
                     }
                     break;

package/dist/observability/escape-hatch-report.d.ts

@@ -11,7 +11,7 @@ export declare function createEscapeHatchReportWindow(opts?: {
 }): EscapeHatchReportWindow;
 export type EscapeHatchProcessDedup = {
     readonly kinds: ReadonlySet<EscapeHatchKind>;
-    readonly seen: Set<string>;
+    readonly lastAuditedAt: Map<string, number>;
 };
 export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function withEscapeHatchAuditScope<T>(run: () => Promise<T>): Promise<T>;

package/dist/observability/escape-hatch-report.js

@@ -27,8 +27,11 @@ export function createEscapeHatchReportWindow(opts) {
         },
     };
 }
+// A long-lived worker must leave an audit event inside every retention window
+// (90 days), or its crons vanish from the log once the first event is pruned.
+const PROCESS_REAUDIT_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export function createEscapeHatchProcessDedup(kinds) {
-    return { kinds: new Set(kinds), seen: new Set() };
+    return { kinds: new Set(kinds), lastAuditedAt: new Map() };
 }
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
@@ -105,11 +108,20 @@ export function createEscapeHatchReporter(opts) {
             emitEscapeHatchUse(opts.meter, opts.handler, kind);
         const { processDedup } = opts;
         if (processDedup?.kinds.has(kind)) {
-            const processKey = JSON.stringify([opts.handler, kind, opts.tenantId]);
-            // skip: this (handler, kind, tenant) was already audited by this process
-            if (processDedup.seen.has(processKey))
+            const processKey = JSON.stringify([
+                opts.handler,
+                kind,
+                opts.tenantId,
+                target?.id ?? null,
+                target?.tenantId ?? null,
+            ]);
+            const nowMs = now();
+            const lastAuditedAt = processDedup.lastAuditedAt.get(processKey);
+            // skip: audited by this process within the re-audit interval
+            if (lastAuditedAt !== undefined && nowMs - lastAuditedAt < PROCESS_REAUDIT_INTERVAL_MS) {
                 return;
-            processDedup.seen.add(processKey);
+            }
+            processDedup.lastAuditedAt.set(processKey, nowMs);
             reportEscapeHatchUse(eventFor(kind, reason, target), deps);
             // skip: audited above, the window dedup below only serves the other kinds
             return;

package/dist/pipeline/cascade-handler.js

@@ -52,10 +52,13 @@ export function createCascadeDeleteHook(registry, tables) {
                     // block the parent delete here instead of changing with it. The error names
                     // the parent only: the caller may delete the parent without reading the child.
                     if (strategy === OnDeleteStrategies.cascade || strategy === OnDeleteStrategies.setNull) {
-                        const childLock = registry.getEntity(relation.target)?.lockedWhen;
-                        if (childLock !== undefined) {
+                        const childEntity = registry.getEntity(relation.target);
+                        const childLock = childEntity?.lockedWhen;
+                        if (childLock !== undefined && payload.lockGuardBypassed !== true) {
+                            // A soft-deleted child is invisible to the caller and must not block.
                             const children = await selectMany(db, targetTable, {
                                 [relation.foreignKey]: payload.id,
+                                ...(childEntity?.softDelete === true && { isDeleted: false }),
                             });
                             if (children.some((child) => isRecordLocked(childLock, child))) {
                                 throw new RecordLockedError({ entityName, entityId: payload.id });

package/dist/pipeline/dispatch-batch.js

@@ -1,10 +1,10 @@
 import { requestContext, runWithWriteOrigin } from "../api/request-context.js";
 import { transaction } from "../db/query.js";
-import { InternalError, toWriteErrorInfo, writeFailure } from "../errors/index.js";
+import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
 import { resolveDbSource } from "./dispatch-shared.js";
-import { executeNestedWrite } from "./dispatch-write.js";
+import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
 import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
@@ -22,15 +22,44 @@ function toReservedScope(reservations, index, cmd) {
     const reservation = reservations.reservedCommands.get(index);
     return reservation && { type: cmd.type, reservation };
 }
+function isPerCommandHandler(ctx, type) {
+    return ctx.registry.getWriteHandler(type)?.transaction === "perCommand";
+}
 async function runReservedCommand(scope, cmd, index, tx) {
     const { ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks } = scope;
     const origin = effectiveWriteOrigin(rootWriteOrigin(ctx.registry, cmd.type, user), inheritedOrigin);
     origins.push(origin);
     const hookStart = afterCommitHooks.length;
-    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
+    // Nested-write children would run inline with the in-transaction scope, so a perCommand command skips the expansion.
+    const execute = isPerCommandHandler(ctx, cmd.type) ? executeWrite : executeNestedWrite;
+    const res = await runAsCommand(toReservedScope(reservations, index, cmd), () => runWithWriteOrigin(origin, () => execute(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks)));
     rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
     return res;
 }
+// Sequential fallback without an outer transaction. A failure result and a throw both end the
+// batch, so both give the reserved capacity back.
+async function runCommandsWithoutTransaction(scope, commands, results) {
+    try {
+        for (let i = 0; i < commands.length; i++) {
+            const cmd = commands[i];
+            if (!cmd)
+                continue;
+            const res = await runReservedCommand(scope, cmd, i, undefined);
+            results.push(res);
+            if (!res.isSuccess) {
+                // No tx means no rollback — but we still drop afterCommit hooks,
+                // matching the semantic "failure = side-effects don't fire".
+                await scope.reservations.releaseAll();
+                return { index: i, error: res.error };
+            }
+        }
+    }
+    catch (e) {
+        await scope.reservations.releaseAll();
+        throw e;
+    }
+    return undefined;
+}
 // Core batch logic extracted so write() and command() can reuse it
 // (a single write = batch of one, running in its own transaction).
 export async function runBatch(ctx, commands, user, requestId, inheritedOrigin) {
@@ -43,6 +72,30 @@ export async function runBatch(ctx, commands, user, requestId, inheritedOrigin)
     const { signal: _signal, ...withoutSignal } = current;
     return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId, inheritedOrigin));
 }
+function perCommandBatchRejection(ctx, commands) {
+    const index = commands.findIndex((cmd) => isPerCommandHandler(ctx, cmd.type));
+    const command = commands[index];
+    if (!command || commands.length < 2)
+        return undefined;
+    return {
+        isSuccess: false,
+        error: toWriteErrorInfo(new UnprocessableError("per_command_handler_in_batch", {
+            message: `handler "${command.type}" runs without a transaction (transaction: "perCommand") and cannot be part of a multi-command batch`,
+        })),
+        failedIndex: index,
+        results: [],
+    };
+}
+async function checkBatchIdempotency(ctx, user, requestId) {
+    if (!requestId || !ctx.idempotency)
+        return {};
+    const checked = await ctx.idempotency.check(user.tenantId, user.id, requestId);
+    if (checked.status !== "cached")
+        return { token: checked.token };
+    const parsed = parseJsonSafe(checked.result, null);
+    // corrupted cache entry — treat as miss, let the request re-run
+    return parsed ? { cached: parsed } : {};
+}
 async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     const { idempotency, lifecycle, appContext: context } = ctx;
     if (commands.length === 0) {
@@ -53,19 +106,10 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     // idempotencyToken is only set when we actually acquired the lock — the
     // corrupted-cache fallthrough below leaves it unset, so finalize() skips
     // store() rather than writing over an entry it never owned.
-    let idempotencyToken;
-    if (requestId && idempotency) {
-        const checked = await idempotency.check(user.tenantId, user.id, requestId);
-        if (checked.status === "cached") {
-            const parsed = parseJsonSafe(checked.result, null);
-            if (parsed)
-                return parsed;
-            // corrupted cache entry — treat as miss, let the request re-run
-        }
-        else {
-            idempotencyToken = checked.token;
-        }
-    }
+    const idempotencyCheck = await checkBatchIdempotency(ctx, user, requestId);
+    if (idempotencyCheck.cached)
+        return idempotencyCheck.cached;
+    const idempotencyToken = idempotencyCheck.token;
     // Hooks already ran on the plaintext results; what is returned and cached
     // for retries must not carry writeOnly values.
     const maskForClient = (result) => maskBatchResultForClient(ctx.registry, commands, result);
@@ -148,6 +192,10 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             return;
         await runWithWriteOrigin(strictest, flushBatchHooksInner);
     };
+    const perCommandRejection = perCommandBatchRejection(ctx, commands);
+    if (perCommandRejection)
+        return releaseOrFinalize(perCommandRejection, false);
+    const runsWithoutTransaction = commands.some((cmd) => isPerCommandHandler(ctx, cmd.type));
     // Reserve before the transaction opens so no extra connection is held while the handler tx is
     // open; the release below runs only after that tx has ended without committing.
     const reservations = await reserveBeforeTransaction(ctx, commands, user, inheritedOrigin);
@@ -162,25 +210,24 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     // batch() opens its own outer transaction — needs the top-level
     // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
     const db = resolveDbSource(ctx, undefined);
-    if (!db) {
-        // Without a DB connection there is no transaction to open. Fall back to
+    if (!db || runsWithoutTransaction) {
+        // Without a DB connection (or for a perCommand handler, whose writes open their own transactions)
+        // there is no transaction to open. Fall back to
         // sequential execution — useful for unit tests that don't touch the DB.
         // Each command runs independently; a failure stops the batch.
-        for (let i = 0; i < commands.length; i++) {
-            const cmd = commands[i];
-            if (!cmd)
-                continue;
-            const res = await runReservedCommand({ ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks }, cmd, i, undefined);
-            results.push(res);
-            if (!res.isSuccess) {
-                // No tx means no rollback — but we still drop afterCommit hooks,
-                // matching the semantic "failure = side-effects don't fire".
-                await reservations.releaseAll();
-                return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
-            }
+        const failed = await runCommandsWithoutTransaction({ ctx, user, inheritedOrigin, reservations, origins, afterCommitHooks }, commands, results);
+        if (failed) {
+            return finalize({
+                isSuccess: false,
+                error: failed.error,
+                failedIndex: failed.index,
+                results,
+            });
         }
         await flushAfterCommit();
-        await flushBatchHooks();
+        // The inner commands of a perCommand handler already fired their own batch hooks.
+        if (!runsWithoutTransaction)
+            await flushBatchHooks();
         return finalize({ isSuccess: true, results });
     }
     let transactionCallbackCompleted = false;
@@ -201,6 +248,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     }
     catch (e) {
         // Rollback or failed COMMIT: the transaction is over, so the reserved capacity goes back.
+        // The release is outcome-safe: it only gives back a reservation row the handler tx did not delete.
         await reservations.releaseAll();
         if (e instanceof BatchRollback) {
             // Thrown inside the callback, so the tx rolled back. A 4xx is

package/dist/pipeline/dispatch-query.js

@@ -1,3 +1,4 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
@@ -49,9 +50,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     // schema (and custom query schemas that opt in) carries `includeDeleted`,
     // so other handlers never see the flag. Visibility filters still apply
     // downstream (see HandlerContext.includeDeleted) — safe from raw input.
-    const includeDeleted = typeof parsed.data === "object" &&
-        parsed.data !== null &&
-        parsed.data["includeDeleted"] === true; // @cast-boundary validated-payload
+    const includeDeleted = propertyOf(parsed.data, "includeDeleted") === true;
     // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
     return isMemberResolutionPrincipal(user)
         ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))

package/dist/pipeline/dispatch-shared.d.ts

@@ -6,7 +6,7 @@ import type { defineTransitions } from "../engine/state-machine.js";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension.js";
 import type { TenantId } from "../engine/types/identifiers.js";
 import type { AppContext, HandlerContext, JobRunnerRef, PayloadRateLimitOption, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
-import { type WriteErrorInfo } from "../errors/index.js";
+import { InternalError, type WriteErrorInfo } from "../errors/index.js";
 import { type EscapeHatchReportWindow, type getFallbackMeter, getFallbackTracer } from "../observability/index.js";
 import { type AfterCommitHook } from "./dispatcher-utils.js";
 import type { IdempotencyGuard } from "./idempotency.js";
@@ -53,7 +53,12 @@ export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
 export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
-export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean, isPostCommit?: boolean): Promise<HandlerContext>;
+export declare function perCommandNestedDenied(targetType: string): InternalError;
+export declare function denyTransactionBoundSurfaces(handlerContext: HandlerContext): HandlerContext;
+export declare function applyBeforeTransactionReadOnly(handlerContext: HandlerContext): HandlerContext;
+export type HandlerTransactionScope = "inTransaction" | "withoutTransaction" | "postCommit";
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean, transactionScope?: HandlerTransactionScope): Promise<HandlerContext>;
+export declare function createHandlerBoundDigest(digest: (value: string) => string, handlerName: string): (value: string) => string;
 export declare function runHandlerInstrumented<T>(ctx: DispatchContext, type: string, operation: "query" | "write" | "stream", user: SessionUser, inner: () => Promise<T>): Promise<T>;
 export declare function runStreamInstrumented<T>(ctx: DispatchContext, type: string, user: SessionUser, inner: () => AsyncGenerator<T>): AsyncGenerator<T>;
 export declare function checkFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<import("../errors/index.js").FeatureDisabledError | undefined>;