@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/dist/observability/index.js

@@ -5,7 +5,7 @@ export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeH
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";
-export { createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, createUnboundMetricsHandle, } from "./metrics-handle.js";
+export { createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, createUnboundMetricsHandle, } from "./metrics-handle.js";
 export { prometheusMetricsEnvSchema, resolveObservabilityWiring, } from "./metrics-wiring.js";
 export { createNoopProvider } from "./noop-provider.js";
 export { createPrometheusMeter, serializeOpenMetrics, } from "./prometheus-meter.js";

package/dist/observability/metrics-handle.d.ts

@@ -3,3 +3,4 @@ export declare function createMetricsHandle(meter: Meter, featureName: string):
 export declare function createSafeMetricsHandle(meter: Meter, featureName: string): MetricsHandle;
 export declare function createUnboundMetricsHandle(meter: Meter): MetricsHandle;
 export declare function createNoopMetricsHandle(): MetricsHandle;
+export declare function createMetricsForFactory(meter: Meter | undefined): (featureName: string) => MetricsHandle;

package/dist/observability/metrics-handle.js

@@ -100,3 +100,10 @@ export function createNoopMetricsHandle() {
         set(_name, _value, _labels) { },
     };
 }
+// Shared factory behind ctx.metricsFor for handler and job contexts, so both
+// keep the same no-op-on-unregistered contract (framework#1844).
+export function createMetricsForFactory(meter) {
+    return meter
+        ? (featureName) => createSafeMetricsHandle(meter, featureName)
+        : () => createNoopMetricsHandle();
+}

package/dist/observability/standard-metrics.js

@@ -62,15 +62,15 @@ export const STANDARD_METRIC_DEFS = [
     // Prometheus collapses per-instance shards into last-writer-wins and
     // per-instance lag is invisible to alerting.
     {
-        name: "kumiko_event_consumer_pending_gaps",
+        name: "kumiko_event_consumer_lag_events",
         type: "gauge",
-        description: "Number of unresolved id ranges below the consumer's cursor (ids not yet visible or proven rolled back).",
+        description: "Number of events between the consumer's cursor and the events head.",
         labels: ["consumer", "instance_id"],
     },
     {
-        name: "kumiko_event_consumer_lag_events",
+        name: "kumiko_event_consumer_pending_gaps",
         type: "gauge",
-        description: "Number of events between the consumer's cursor and the events head.",
+        description: "Number of unresolved id ranges below the consumer's cursor (ids not yet visible or proven rolled back).",
         labels: ["consumer", "instance_id"],
     },
     {

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.d.ts

@@ -1,4 +1,5 @@
 import type { DbTx } from "../db/connection.js";
 import type { SessionUser } from "../engine/types/index.js";
 import { type DispatchContext, type WriteOrigin } from "./dispatch-shared.js";
-export declare function executeQuery(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx?: DbTx): Promise<unknown>;
+import type { AfterCommitHook } from "./dispatcher-utils.js";
+export declare function executeQuery(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx?: DbTx, outerNotifySink?: AfterCommitHook[]): Promise<unknown>;

package/dist/pipeline/dispatch-query.js

@@ -10,10 +10,10 @@ import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.j
 // Standalone query execution — used by the public dispatcher.query() and
 // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
 // field-level read filters for the given user, logs the event.
-export async function executeQuery(ctx, type, payload, user, origin, tx) {
-    return runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx));
+export async function executeQuery(ctx, type, payload, user, origin, tx, outerNotifySink) {
+    return runHandlerInstrumented(ctx, type, "query", user, () => executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink));
 }
-async function executeQueryInner(ctx, type, payload, user, origin, tx) {
+async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNotifySink) {
     const { registry } = ctx;
     const handler = registry.getQueryHandler(type);
     if (!handler)
@@ -54,11 +54,11 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     // 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))
-        : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx);
+        : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx, outerNotifySink);
 }
-async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user, origin, tx) {
+async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user, origin, tx, outerNotifySink) {
     const { registry } = ctx;
-    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, undefined, includeDeleted);
+    const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, undefined, includeDeleted, undefined, outerNotifySink);
     let result = await handler.handler({ type, payload, user }, handlerContext);
     // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
     // and can merge custom-fields/computed-counts/tags/etc. Each hook is

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, outerNotifySink?: AfterCommitHook[], readOnlyForTenant?: boolean): 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>;