@porulle/core 0.35.0 → 0.36.0

package/dist/kernel/hooks/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGpF,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAKzE;AAqCD,wBAAsB,cAAc,CAAC,CAAC,EACpC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EACrB,YAAY,EAAE,CAAC,GAAG,IAAI,EACtB,eAAe,EAAE,CAAC,EAClB,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,iBAAiB,GAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,OAAqB,GAC/D,OAAO,CAAC,UAAU,CAAC,CA6DrB"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIpF,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAKzE;AAqCD,wBAAsB,cAAc,CAAC,CAAC,EACpC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,IAAI,EAAE,CAAC,EACP,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EACrB,YAAY,EAAE,CAAC,GAAG,IAAI,EACtB,eAAe,EAAE,CAAC,EAClB,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,iBAAiB,GAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,OAAqB,GAC/D,OAAO,CAAC,UAAU,CAAC,CAkErB"}

package/dist/kernel/hooks/executor.js

@@ -1,4 +1,5 @@
 import { deferAfterCommit } from "./deferred.js";
+import { reportHookFailure } from "./failures.js";
 export function mergeHookReports(a, b) {
     return {
         errors: [...a.errors, ...b.errors],
@@ -65,10 +66,9 @@ export async function runAfterHooks(hooks, originalData, committedResult, operat
                 await runHook();
             }
             catch (error) {
-                errors.push({
-                    hookName,
-                    message: error instanceof Error ? error.message : String(error),
-                });
+                const message = error instanceof Error ? error.message : String(error);
+                errors.push({ hookName, message });
+                reportHookFailure({ hookName, message, deferred: false });
                 context.logger.error(`After-hook "${hookName}" failed`, {
                     error,
                 });
@@ -80,6 +80,13 @@ export async function runAfterHooks(hooks, originalData, committedResult, operat
                 await runHook();
             }
             catch (error) {
+                // Reported rather than collected: this runs after the commit, so the HookReport below has
+                // already been returned to the caller and there is nowhere else for this failure to go.
+                reportHookFailure({
+                    hookName,
+                    message: error instanceof Error ? error.message : String(error),
+                    deferred: true,
+                });
                 context.logger.error(`After-commit hook "${hookName}" failed`, {
                     error,
                 });
@@ -90,10 +97,9 @@ export async function runAfterHooks(hooks, originalData, committedResult, operat
                 await runHook();
             }
             catch (error) {
-                errors.push({
-                    hookName,
-                    message: error instanceof Error ? error.message : String(error),
-                });
+                const message = error instanceof Error ? error.message : String(error);
+                errors.push({ hookName, message });
+                reportHookFailure({ hookName, message, deferred: false });
                 context.logger.error(`After-hook "${hookName}" failed`, {
                     error,
                 });

package/dist/kernel/hooks/failures.d.ts

@@ -0,0 +1,27 @@
+import type { HookError } from "./executor.js";
+/**
+ * Where after-hook failures go when nobody is listening.
+ *
+ * An after-hook must never fail the write it is announcing, so `runAfterHooks` collects failures
+ * into a `HookReport` and the after-COMMIT path cannot even do that — by the time a deferred hook
+ * runs, the service method has already returned its Result. The consequence measured on 2026-09-15:
+ * removing the after-commit boundary from the plugin db path made four connector suites take
+ * 578.23 s instead of 27.29 s and log 51 `Hook "deliverWebhooks" timed out after 20000ms`, with
+ * exit 0 and 22 of 22 tests passing. The only thing that disagreed was the wall clock.
+ *
+ * So failures are reported here as well as logged. Production installs no observer and pays one
+ * undefined check; a test harness installs one and can fail the test that caused it.
+ */
+export interface HookFailure extends HookError {
+    /** True when the hook had been deferred to after the commit, so no `HookReport` can carry it. */
+    deferred: boolean;
+}
+export type HookFailureObserver = (failure: HookFailure) => void;
+/** Install the observer, or pass `undefined` to remove it. Returns the previous one. */
+export declare function observeHookFailures(next: HookFailureObserver | undefined): HookFailureObserver | undefined;
+/**
+ * Report one after-hook failure. Never throws: an observer that throws would turn a swallowed hook
+ * failure into a failed write, which is the behaviour this whole path exists to prevent.
+ */
+export declare function reportHookFailure(failure: HookFailure): void;
+//# sourceMappingURL=failures.d.ts.map

package/dist/kernel/hooks/failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/failures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,iGAAiG;IACjG,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;AAcjE,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAK1G;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAQ5D"}

package/dist/kernel/hooks/failures.js

@@ -0,0 +1,31 @@
+/**
+ * The observer lives on `globalThis`, not in a module-level binding, because this module is loaded
+ * TWICE in a monorepo test run and a module-level one would be two unrelated variables. Vitest
+ * resolves `@porulle/core` through the package's `import` condition to `dist/`, so a plugin suite
+ * runs the built executor; core's own suites and any vitest setup file import the source by
+ * relative path. An observer installed on the source copy is invisible to the built one, which is
+ * exactly how the first version of this instrument reported nothing while 51 hook timeouts went by.
+ */
+const OBSERVER_KEY = Symbol.for("@porulle/core:hook-failure-observer");
+/** Install the observer, or pass `undefined` to remove it. Returns the previous one. */
+export function observeHookFailures(next) {
+    const holder = globalThis;
+    const previous = holder[OBSERVER_KEY];
+    holder[OBSERVER_KEY] = next;
+    return previous;
+}
+/**
+ * Report one after-hook failure. Never throws: an observer that throws would turn a swallowed hook
+ * failure into a failed write, which is the behaviour this whole path exists to prevent.
+ */
+export function reportHookFailure(failure) {
+    const observer = globalThis[OBSERVER_KEY];
+    if (!observer)
+        return;
+    try {
+        observer(failure);
+    }
+    catch {
+        // An observer is an instrument. It does not get to change the outcome it is measuring.
+    }
+}

package/dist/kernel/hooks/registry.d.ts

@@ -1,4 +1,8 @@
 export type HookHandler = (...args: never[]) => unknown;
+/** Declare that this handler must run inside the writing transaction. Called by the manifest merge. */
+export declare function markHookInTransaction(handler: unknown): void;
+/** Whether a plugin asked for this handler to run in-transaction. Read by the kernel at boot. */
+export declare function isHookMarkedInTransaction(handler: unknown): boolean;
 export declare class HookRegistry {
     private registry;
     private inTransactionHandlers;

package/dist/kernel/hooks/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/registry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAQxD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,qBAAqB,CAA8B;IAC3D,OAAO,CAAC,MAAM,CAAC,CAAiE;IAEhF,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAKpE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKpD,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKjE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKrD,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKlE,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO;IAIhD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAMxC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI;IAIjF,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD,OAAO,CAAC,WAAW;CASpB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/hooks/registry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAgBxD,uGAAuG;AACvG,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE5D;AAED,iGAAiG;AACjG,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEnE;AAQD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,qBAAqB,CAA8B;IAC3D,OAAO,CAAC,MAAM,CAAC,CAAiE;IAEhF,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAKpE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKpD,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKjE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKrD,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAKlE,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO;IAIhD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE;IAMxC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI;IAIjF,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD,OAAO,CAAC,WAAW;CASpB"}

package/dist/kernel/hooks/registry.js

@@ -1,3 +1,25 @@
+/**
+ * Handlers a PLUGIN asked to run inside the writing transaction.
+ *
+ * Module-level rather than per-registry because a plugin's declaration and its registration are
+ * separated by the manifest merge: `manifest.hooks()` returns `{ key, handler, inTransaction }`
+ * records, which are flattened into `config.hooks` as a bare `key -> handler[]` map long before any
+ * HookRegistry exists. Marking the function itself is the only channel that survives that.
+ *
+ * Shipped in 0.35.1 because 0.35.0 made after-commit the default with no way for a plugin to opt
+ * out, which silently moved `loom_projection_pending` — a transactional outbox whose whole point is
+ * committing with the write it records — to after the commit.
+ */
+const pluginInTransactionHandlers = new WeakSet();
+/** Declare that this handler must run inside the writing transaction. Called by the manifest merge. */
+export function markHookInTransaction(handler) {
+    if (typeof handler === "function")
+        pluginInTransactionHandlers.add(handler);
+}
+/** Whether a plugin asked for this handler to run in-transaction. Read by the kernel at boot. */
+export function isHookMarkedInTransaction(handler) {
+    return typeof handler === "function" && pluginInTransactionHandlers.has(handler);
+}
 export class HookRegistry {
     registry = new Map();
     inTransactionHandlers = new WeakSet();

package/dist/kernel/plugin/manifest.d.ts

@@ -28,6 +28,15 @@ export type PluginRouteRegistration = {
 export interface PluginHookRegistration {
     key: string;
     handler: (...args: unknown[]) => unknown;
+    /**
+     * Run this hook INSIDE the writing transaction instead of after it commits.
+     *
+     * The default is after-commit and is correct for anything with an external effect — a webhook, a
+     * search-index write, an email — none of which may announce a write that can still roll back.
+     * Set this only for an OUTBOX WRITER: a hook whose own write must commit or roll back together
+     * with the row it records. `loom_projection_pending` is the case this exists for.
+     */
+    inTransaction?: boolean;
 }
 export interface PluginContext {
     config: CommerceConfig;

package/dist/kernel/plugin/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/manifest.ts"],"names":[],"mappings":"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"}

package/dist/kernel/plugin/manifest.js

@@ -1,3 +1,4 @@
+import { markHookInTransaction } from "../hooks/registry.js";
 import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import { isRoutePermissionGuard, markRoutePermissionGuard } from "../../interfaces/rest/utils.js";
 import { createScopedDb } from "../database/scoped-db.js";
@@ -141,6 +142,10 @@ export function defineCommercePlugin(manifest) {
                 ...(result.hooks ?? {}),
             };
             for (const reg of registrations) {
+                // The marker rides on the function because this map is a bare key -> handler[] and cannot
+                // carry it; the kernel reads it back when it registers these at boot.
+                if (reg.inTransaction)
+                    markHookInTransaction(reg.handler);
                 hookMap[reg.key] = [...(hookMap[reg.key] ?? []), reg.handler];
             }
             result = { ...result, hooks: hookMap };

package/dist/runtime/kernel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAqBzD,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAE7B,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA0I3D"}
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/runtime/kernel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAqBzD,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,sBAAsB,EAC5B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EACL,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAE7B,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAiJ3D"}

package/dist/runtime/kernel.js

@@ -1,4 +1,4 @@
-import { HookRegistry } from "../kernel/hooks/registry.js";
+import { HookRegistry, isHookMarkedInTransaction } from "../kernel/hooks/registry.js";
 import { createDatabaseConnection } from "../kernel/database/adapter.js";
 import { topoSortModules } from "../kernel/module/index.js";
 import { WebhookDeliveryWorker } from "../modules/webhooks/worker.js";
@@ -115,7 +115,15 @@ export function createKernel(config) {
     };
     for (const [key, handlers] of Object.entries(config.hooks ?? {})) {
         for (const handler of handlers) {
-            hooks.append(key, handler);
+            // A plugin that declared `inTransaction` gets appendInTransaction, so its hook runs inside
+            // the writing transaction rather than in the after-commit drain. Everything else defaults to
+            // after-commit, which is what 0.35.0 established.
+            if (isHookMarkedInTransaction(handler)) {
+                hooks.appendInTransaction(key, handler);
+            }
+            else {
+                hooks.append(key, handler);
+            }
         }
     }
     for (const model of config.analytics?.models ?? []) {

package/dist/test-utils/hook-failure-setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hook-failure-setup.d.ts.map

package/dist/test-utils/hook-failure-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-failure-setup.d.ts","sourceRoot":"","sources":["../../src/test-utils/hook-failure-setup.ts"],"names":[],"mappings":""}

package/dist/test-utils/hook-failure-setup.js

@@ -0,0 +1,23 @@
+import { afterEach, beforeEach } from "vitest";
+import { armHookFailureCollector, resetHookFailures, unallowedHookFailureMessage, } from "./hook-failures.js";
+/**
+ * A vitest setup file, wired once in `vitest.shared.js` so every package in the monorepo inherits
+ * it. It is a setup file rather than something `createPluginTestApp` installs because the check has
+ * to be a default nobody remembers to ask for: the case it exists to catch is precisely a suite
+ * nobody thought to instrument.
+ *
+ * Measured 2026-09-15 on the connector suites with the after-commit boundary removed from the
+ * plugin db path: 578.23 s instead of 27.29 s, 51 `Hook "deliverWebhooks" timed out after 20000ms`,
+ * and exit 0 with every test passing. After-hook failures are collected into a `HookReport` and
+ * never thrown, so the run was green; nothing in the monorepo asked whether the report was clean.
+ */
+armHookFailureCollector();
+beforeEach(() => {
+    resetHookFailures();
+});
+afterEach(() => {
+    const message = unallowedHookFailureMessage();
+    resetHookFailures();
+    if (message)
+        throw new Error(message);
+});

package/dist/test-utils/hook-failures.d.ts

@@ -0,0 +1,22 @@
+import { type HookFailure } from "../kernel/hooks/failures.js";
+/**
+ * Permit one named hook to fail during the current test without failing it.
+ *
+ * Per test and per hook on purpose: a suite that deliberately throws from `myBrokenHook` still
+ * fails if `deliverWebhooks` deadlocks alongside it, which a global mute would hide. The allowance
+ * is cleared before every test, so it has to be asked for where it is meant.
+ */
+export declare function allowHookFailure(hookName: string): void;
+/** Every failure recorded for the current test, allowed or not. */
+export declare function recordedHookFailures(): readonly HookFailure[];
+export declare function resetHookFailures(): void;
+export declare function armHookFailureCollector(): void;
+/**
+ * The message for an unallowed failure, or undefined when there is nothing to report.
+ *
+ * A hook TIMEOUT is called out separately: a hook that throws is usually the suite's own doing,
+ * while a hook that times out is almost always deadlocked against the transaction holding its
+ * connection — a defect in the code under test, not in the test.
+ */
+export declare function unallowedHookFailureMessage(): string | undefined;
+//# sourceMappingURL=hook-failures.d.ts.map

package/dist/test-utils/hook-failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-failures.d.ts","sourceRoot":"","sources":["../../src/test-utils/hook-failures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,6BAA6B,CAAC;AA2BpF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,IAAI,SAAS,WAAW,EAAE,CAE7D;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAuBhE"}

package/dist/test-utils/hook-failures.js

@@ -0,0 +1,71 @@
+import { observeHookFailures } from "../kernel/hooks/failures.js";
+/**
+ * Collected after-hook failures for the test currently running, and the per-test allowance for the
+ * ones a suite causes on purpose.
+ *
+ * The state lives here rather than in the vitest setup file so that a suite importing
+ * `allowHookFailure` from `@porulle/core/testing` and the setup file that reads it resolve to the
+ * same module instance.
+ */
+/**
+ * On `globalThis` for the same reason the observer is: this module is loaded once as source (by the
+ * vitest setup file) and once as `dist/` (by anything importing `@porulle/core/testing`), so a
+ * suite calling `allowHookFailure` would otherwise be writing to a different Set from the one the
+ * setup file reads.
+ */
+const STATE_KEY = Symbol.for("@porulle/core:hook-failure-state");
+function state() {
+    const holder = globalThis;
+    holder[STATE_KEY] ??= { seen: [], allowed: new Set() };
+    return holder[STATE_KEY];
+}
+/**
+ * Permit one named hook to fail during the current test without failing it.
+ *
+ * Per test and per hook on purpose: a suite that deliberately throws from `myBrokenHook` still
+ * fails if `deliverWebhooks` deadlocks alongside it, which a global mute would hide. The allowance
+ * is cleared before every test, so it has to be asked for where it is meant.
+ */
+export function allowHookFailure(hookName) {
+    state().allowed.add(hookName);
+}
+/** Every failure recorded for the current test, allowed or not. */
+export function recordedHookFailures() {
+    return state().seen;
+}
+export function resetHookFailures() {
+    const current = state();
+    current.seen.length = 0;
+    current.allowed.clear();
+}
+export function armHookFailureCollector() {
+    observeHookFailures((failure) => state().seen.push(failure));
+}
+/**
+ * The message for an unallowed failure, or undefined when there is nothing to report.
+ *
+ * A hook TIMEOUT is called out separately: a hook that throws is usually the suite's own doing,
+ * while a hook that times out is almost always deadlocked against the transaction holding its
+ * connection — a defect in the code under test, not in the test.
+ */
+export function unallowedHookFailureMessage() {
+    const { seen, allowed } = state();
+    const unallowed = seen.filter((failure) => !allowed.has(failure.hookName));
+    if (unallowed.length === 0)
+        return undefined;
+    const timeouts = unallowed.filter((failure) => / timed out after \d+ms$/.test(failure.message));
+    const lines = unallowed.map((failure) => `  ${failure.deferred ? "after-commit" : "after"}-hook "${failure.hookName}": ${failure.message}`);
+    return [
+        `${unallowed.length} after-hook failure(s) during this test:`,
+        ...lines,
+        "",
+        timeouts.length > 0
+            ? `${timeouts.length} of them TIMED OUT. A hook that times out is almost always blocked on the ` +
+                "connection held by the transaction it was fired from — check that the write path establishes " +
+                "an after-commit boundary rather than running the hook inside the transaction."
+            : "An after-hook failure never fails the write it announces, so without this check the test " +
+                "passes and the failure is only visible in a log.",
+        "",
+        "If the suite causes this on purpose, call allowHookFailure(\"<hookName>\") in that test.",
+    ].join("\n");
+}

package/dist/testing.d.ts

@@ -12,5 +12,8 @@ export { createPluginTestApp, type PluginTestApp, type TestAppEnv } from "./test
 export { TEST_ORG_ID, testAdminActor, testStaffActor, testCustomerActor, testNoPermActor, jsonHeaders, } from "./test-utils/test-actors.js";
 export { beforeHook, afterHook } from "./test-utils/typed-hooks.js";
 export { markOrderPaidForTest } from "./test-utils/order-test-helpers.js";
+export { isInsideTransaction } from "./kernel/hooks/deferred.js";
+export { allowHookFailure, recordedHookFailures } from "./test-utils/hook-failures.js";
+export type { HookFailure } from "./kernel/hooks/failures.js";
 export type { Actor } from "./auth/types.js";
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAClH,OAAO,EACL,WAAW,EACX,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAClE,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAG1E,YAAY,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAClH,OAAO,EACL,WAAW,EACX,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAClE,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAQ1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAMjE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACvF,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAG9D,YAAY,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/testing.js

@@ -12,3 +12,15 @@ export { createPluginTestApp } from "./test-utils/create-plugin-test-app.js";
 export { TEST_ORG_ID, testAdminActor, testStaffActor, testCustomerActor, testNoPermActor, jsonHeaders, } from "./test-utils/test-actors.js";
 export { beforeHook, afterHook } from "./test-utils/typed-hooks.js";
 export { markOrderPaidForTest } from "./test-utils/order-test-helpers.js";
+// The after-commit boundary predicate, so a suite can assert that the code under test really is
+// inside one. A plugin reaches the database through the `ctx.db` HANDLE, not the adapter, and the
+// boundary on that path comes from the proxy in `normalizeExecuteShape`; without it an after-hook
+// runs INSIDE the open transaction and deadlocks on its own connection. That regression is silent
+// — after-hook failures are collected into a HookReport and never thrown — so a suite has to ask
+// the question directly rather than wait for a symptom.
+export { isInsideTransaction } from "./kernel/hooks/deferred.js";
+// A hook that fails is announced to nobody: an after-hook must not fail the write it records, so
+// `runAfterHooks` collects failures into a HookReport and the after-commit path cannot even do
+// that. The vitest setup file wired in vitest.shared.js turns them into a test failure; this is the
+// escape hatch for a suite that causes one deliberately.
+export { allowHookFailure, recordedHookFailures } from "./test-utils/hook-failures.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/kernel/hooks/executor.ts

@@ -1,5 +1,6 @@
 import type { AfterHook, BeforeHook, HookContext, HookOperation } from "./types.js";
 import { deferAfterCommit } from "./deferred.js";
+import { reportHookFailure } from "./failures.js";
 
 export interface HookError {
   hookName: string;
@@ -108,10 +109,9 @@ export async function runAfterHooks<T>(
       try {
         await runHook();
       } catch (error) {
-        errors.push({
-          hookName,
-          message: error instanceof Error ? error.message : String(error),
-        });
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push({ hookName, message });
+        reportHookFailure({ hookName, message, deferred: false });
         context.logger.error(`After-hook "${hookName}" failed`, {
           error,
         });
@@ -123,6 +123,13 @@ export async function runAfterHooks<T>(
       try {
         await runHook();
       } catch (error) {
+        // Reported rather than collected: this runs after the commit, so the HookReport below has
+        // already been returned to the caller and there is nowhere else for this failure to go.
+        reportHookFailure({
+          hookName,
+          message: error instanceof Error ? error.message : String(error),
+          deferred: true,
+        });
         context.logger.error(`After-commit hook "${hookName}" failed`, {
           error,
         });
@@ -133,10 +140,9 @@ export async function runAfterHooks<T>(
       try {
         await runHook();
       } catch (error) {
-        errors.push({
-          hookName,
-          message: error instanceof Error ? error.message : String(error),
-        });
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push({ hookName, message });
+        reportHookFailure({ hookName, message, deferred: false });
         context.logger.error(`After-hook "${hookName}" failed`, {
           error,
         });

package/src/kernel/hooks/failures.ts

@@ -0,0 +1,55 @@
+import type { HookError } from "./executor.js";
+
+/**
+ * Where after-hook failures go when nobody is listening.
+ *
+ * An after-hook must never fail the write it is announcing, so `runAfterHooks` collects failures
+ * into a `HookReport` and the after-COMMIT path cannot even do that — by the time a deferred hook
+ * runs, the service method has already returned its Result. The consequence measured on 2026-09-15:
+ * removing the after-commit boundary from the plugin db path made four connector suites take
+ * 578.23 s instead of 27.29 s and log 51 `Hook "deliverWebhooks" timed out after 20000ms`, with
+ * exit 0 and 22 of 22 tests passing. The only thing that disagreed was the wall clock.
+ *
+ * So failures are reported here as well as logged. Production installs no observer and pays one
+ * undefined check; a test harness installs one and can fail the test that caused it.
+ */
+export interface HookFailure extends HookError {
+  /** True when the hook had been deferred to after the commit, so no `HookReport` can carry it. */
+  deferred: boolean;
+}
+
+export type HookFailureObserver = (failure: HookFailure) => void;
+
+/**
+ * The observer lives on `globalThis`, not in a module-level binding, because this module is loaded
+ * TWICE in a monorepo test run and a module-level one would be two unrelated variables. Vitest
+ * resolves `@porulle/core` through the package's `import` condition to `dist/`, so a plugin suite
+ * runs the built executor; core's own suites and any vitest setup file import the source by
+ * relative path. An observer installed on the source copy is invisible to the built one, which is
+ * exactly how the first version of this instrument reported nothing while 51 hook timeouts went by.
+ */
+const OBSERVER_KEY = Symbol.for("@porulle/core:hook-failure-observer");
+
+type ObserverHolder = { [OBSERVER_KEY]?: HookFailureObserver | undefined };
+
+/** Install the observer, or pass `undefined` to remove it. Returns the previous one. */
+export function observeHookFailures(next: HookFailureObserver | undefined): HookFailureObserver | undefined {
+  const holder = globalThis as ObserverHolder;
+  const previous = holder[OBSERVER_KEY];
+  holder[OBSERVER_KEY] = next;
+  return previous;
+}
+
+/**
+ * Report one after-hook failure. Never throws: an observer that throws would turn a swallowed hook
+ * failure into a failed write, which is the behaviour this whole path exists to prevent.
+ */
+export function reportHookFailure(failure: HookFailure): void {
+  const observer = (globalThis as ObserverHolder)[OBSERVER_KEY];
+  if (!observer) return;
+  try {
+    observer(failure);
+  } catch {
+    // An observer is an instrument. It does not get to change the outcome it is measuring.
+  }
+}

package/src/kernel/hooks/registry.ts

@@ -1,5 +1,29 @@
 export type HookHandler = (...args: never[]) => unknown;
 
+/**
+ * Handlers a PLUGIN asked to run inside the writing transaction.
+ *
+ * Module-level rather than per-registry because a plugin's declaration and its registration are
+ * separated by the manifest merge: `manifest.hooks()` returns `{ key, handler, inTransaction }`
+ * records, which are flattened into `config.hooks` as a bare `key -> handler[]` map long before any
+ * HookRegistry exists. Marking the function itself is the only channel that survives that.
+ *
+ * Shipped in 0.35.1 because 0.35.0 made after-commit the default with no way for a plugin to opt
+ * out, which silently moved `loom_projection_pending` — a transactional outbox whose whole point is
+ * committing with the write it records — to after the commit.
+ */
+const pluginInTransactionHandlers = new WeakSet<object>();
+
+/** Declare that this handler must run inside the writing transaction. Called by the manifest merge. */
+export function markHookInTransaction(handler: unknown): void {
+  if (typeof handler === "function") pluginInTransactionHandlers.add(handler as object);
+}
+
+/** Whether a plugin asked for this handler to run in-transaction. Read by the kernel at boot. */
+export function isHookMarkedInTransaction(handler: unknown): boolean {
+  return typeof handler === "function" && pluginInTransactionHandlers.has(handler as object);
+}
+
 type HookEntry = {
   prepended: HookHandler[];
   configured: HookHandler[];

package/src/kernel/plugin/manifest.ts

@@ -1,4 +1,5 @@
 import type { Hono } from "hono";
+import { markHookInTransaction } from "../hooks/registry.js";
 import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
 import type { PluginDb } from "../database/plugin-types.js";
 import type { DatabaseAdapter } from "../database/adapter.js";
@@ -43,6 +44,15 @@ export type PluginRouteRegistration =
 export interface PluginHookRegistration {
   key: string;
   handler: (...args: unknown[]) => unknown;
+  /**
+   * Run this hook INSIDE the writing transaction instead of after it commits.
+   *
+   * The default is after-commit and is correct for anything with an external effect — a webhook, a
+   * search-index write, an email — none of which may announce a write that can still roll back.
+   * Set this only for an OUTBOX WRITER: a hook whose own write must commit or roll back together
+   * with the row it records. `loom_projection_pending` is the case this exists for.
+   */
+  inTransaction?: boolean;
 }
 
 // ─── Plugin Context (available to routes at boot time) ───────
@@ -294,6 +304,9 @@ export function defineCommercePlugin(
         ...(result.hooks ?? {}),
       };
       for (const reg of registrations) {
+        // The marker rides on the function because this map is a bare key -> handler[] and cannot
+        // carry it; the kernel reads it back when it registers these at boot.
+        if (reg.inTransaction) markHookInTransaction(reg.handler);
         hookMap[reg.key] = [...(hookMap[reg.key] ?? []), reg.handler];
       }
       result = { ...result, hooks: hookMap };

package/src/runtime/kernel.ts

@@ -1,5 +1,5 @@
 import type { CommerceConfig } from "../config/types.js";
-import { HookRegistry, type HookHandler } from "../kernel/hooks/registry.js";
+import { HookRegistry, isHookMarkedInTransaction, type HookHandler } from "../kernel/hooks/registry.js";
 import { createDatabaseConnection } from "../kernel/database/adapter.js";
 import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
 import type { AppModule } from "../kernel/module/index.js";
@@ -162,7 +162,14 @@ export function createKernel(config: CommerceConfig): Kernel {
 
   for (const [key, handlers] of Object.entries(config.hooks ?? {})) {
     for (const handler of handlers) {
-      hooks.append(key, handler as HookHandler);
+      // A plugin that declared `inTransaction` gets appendInTransaction, so its hook runs inside
+      // the writing transaction rather than in the after-commit drain. Everything else defaults to
+      // after-commit, which is what 0.35.0 established.
+      if (isHookMarkedInTransaction(handler)) {
+        hooks.appendInTransaction(key, handler as HookHandler);
+      } else {
+        hooks.append(key, handler as HookHandler);
+      }
     }
   }
 

package/src/test-utils/hook-failure-setup.ts

@@ -0,0 +1,29 @@
+import { afterEach, beforeEach } from "vitest";
+import {
+  armHookFailureCollector,
+  resetHookFailures,
+  unallowedHookFailureMessage,
+} from "./hook-failures.js";
+
+/**
+ * A vitest setup file, wired once in `vitest.shared.js` so every package in the monorepo inherits
+ * it. It is a setup file rather than something `createPluginTestApp` installs because the check has
+ * to be a default nobody remembers to ask for: the case it exists to catch is precisely a suite
+ * nobody thought to instrument.
+ *
+ * Measured 2026-09-15 on the connector suites with the after-commit boundary removed from the
+ * plugin db path: 578.23 s instead of 27.29 s, 51 `Hook "deliverWebhooks" timed out after 20000ms`,
+ * and exit 0 with every test passing. After-hook failures are collected into a `HookReport` and
+ * never thrown, so the run was green; nothing in the monorepo asked whether the report was clean.
+ */
+armHookFailureCollector();
+
+beforeEach(() => {
+  resetHookFailures();
+});
+
+afterEach(() => {
+  const message = unallowedHookFailureMessage();
+  resetHookFailures();
+  if (message) throw new Error(message);
+});

package/src/test-utils/hook-failures.ts

@@ -0,0 +1,84 @@
+import { observeHookFailures, type HookFailure } from "../kernel/hooks/failures.js";
+
+/**
+ * Collected after-hook failures for the test currently running, and the per-test allowance for the
+ * ones a suite causes on purpose.
+ *
+ * The state lives here rather than in the vitest setup file so that a suite importing
+ * `allowHookFailure` from `@porulle/core/testing` and the setup file that reads it resolve to the
+ * same module instance.
+ */
+/**
+ * On `globalThis` for the same reason the observer is: this module is loaded once as source (by the
+ * vitest setup file) and once as `dist/` (by anything importing `@porulle/core/testing`), so a
+ * suite calling `allowHookFailure` would otherwise be writing to a different Set from the one the
+ * setup file reads.
+ */
+const STATE_KEY = Symbol.for("@porulle/core:hook-failure-state");
+
+type State = { seen: HookFailure[]; allowed: Set<string> };
+type StateHolder = { [STATE_KEY]?: State };
+
+function state(): State {
+  const holder = globalThis as StateHolder;
+  holder[STATE_KEY] ??= { seen: [], allowed: new Set<string>() };
+  return holder[STATE_KEY];
+}
+
+/**
+ * Permit one named hook to fail during the current test without failing it.
+ *
+ * Per test and per hook on purpose: a suite that deliberately throws from `myBrokenHook` still
+ * fails if `deliverWebhooks` deadlocks alongside it, which a global mute would hide. The allowance
+ * is cleared before every test, so it has to be asked for where it is meant.
+ */
+export function allowHookFailure(hookName: string): void {
+  state().allowed.add(hookName);
+}
+
+/** Every failure recorded for the current test, allowed or not. */
+export function recordedHookFailures(): readonly HookFailure[] {
+  return state().seen;
+}
+
+export function resetHookFailures(): void {
+  const current = state();
+  current.seen.length = 0;
+  current.allowed.clear();
+}
+
+export function armHookFailureCollector(): void {
+  observeHookFailures((failure) => state().seen.push(failure));
+}
+
+/**
+ * The message for an unallowed failure, or undefined when there is nothing to report.
+ *
+ * A hook TIMEOUT is called out separately: a hook that throws is usually the suite's own doing,
+ * while a hook that times out is almost always deadlocked against the transaction holding its
+ * connection — a defect in the code under test, not in the test.
+ */
+export function unallowedHookFailureMessage(): string | undefined {
+  const { seen, allowed } = state();
+  const unallowed = seen.filter((failure) => !allowed.has(failure.hookName));
+  if (unallowed.length === 0) return undefined;
+
+  const timeouts = unallowed.filter((failure) => / timed out after \d+ms$/.test(failure.message));
+  const lines = unallowed.map(
+    (failure) => `  ${failure.deferred ? "after-commit" : "after"}-hook "${failure.hookName}": ${failure.message}`,
+  );
+
+  return [
+    `${unallowed.length} after-hook failure(s) during this test:`,
+    ...lines,
+    "",
+    timeouts.length > 0
+      ? `${timeouts.length} of them TIMED OUT. A hook that times out is almost always blocked on the ` +
+        "connection held by the transaction it was fired from — check that the write path establishes " +
+        "an after-commit boundary rather than running the hook inside the transaction."
+      : "An after-hook failure never fails the write it announces, so without this check the test " +
+        "passes and the failure is only visible in a log.",
+    "",
+    "If the suite causes this on purpose, call allowHookFailure(\"<hookName>\") in that test.",
+  ].join("\n");
+}

package/src/testing.ts

@@ -18,5 +18,20 @@ export {
 export { beforeHook, afterHook } from "./test-utils/typed-hooks.js";
 export { markOrderPaidForTest } from "./test-utils/order-test-helpers.js";
 
+// The after-commit boundary predicate, so a suite can assert that the code under test really is
+// inside one. A plugin reaches the database through the `ctx.db` HANDLE, not the adapter, and the
+// boundary on that path comes from the proxy in `normalizeExecuteShape`; without it an after-hook
+// runs INSIDE the open transaction and deadlocks on its own connection. That regression is silent
+// — after-hook failures are collected into a HookReport and never thrown — so a suite has to ask
+// the question directly rather than wait for a symptom.
+export { isInsideTransaction } from "./kernel/hooks/deferred.js";
+
+// A hook that fails is announced to nobody: an after-hook must not fail the write it records, so
+// `runAfterHooks` collects failures into a HookReport and the after-commit path cannot even do
+// that. The vitest setup file wired in vitest.shared.js turns them into a test failure; this is the
+// escape hatch for a suite that causes one deliberately.
+export { allowHookFailure, recordedHookFailures } from "./test-utils/hook-failures.js";
+export type { HookFailure } from "./kernel/hooks/failures.js";
+
 // Actor type re-export for plugin tests that build custom test actors.
 export type { Actor } from "./auth/types.js";