@porulle/core 0.35.1 → 0.37.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;AAKpF,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;AA4DD,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,10 +1,34 @@
 import { deferAfterCommit } from "./deferred.js";
+import { reportHookFailure } from "./failures.js";
 export function mergeHookReports(a, b) {
     return {
         errors: [...a.errors, ...b.errors],
         hasErrors: a.hasErrors || b.hasErrors,
     };
 }
+/**
+ * The context a hook marked `inTransaction: true` receives.
+ *
+ * `inTransaction` buys ORDERING on its own — the hook runs inline, before the commit. It does not
+ * make the hook's WRITES part of the transaction: `context.db` is the plugin db handle, and on a
+ * two-connection driver (Neon over HTTP, where every plain query is its own request) a write on
+ * that handle is not in the transaction and survives its rollback. Measured on the deployed Worker
+ * on 2026-09-15: an aborted write left `entity_exists = 0` and `pending_for_aborted = 1` — a row
+ * that rolled back announcing itself in the outbox whose entire purpose is committing with it.
+ *
+ * So the kernel hands such a hook a context it cannot get this wrong from: `db` IS the transaction.
+ * A plugin author writing the obvious thing lands inside the transaction, with nothing to remember.
+ *
+ * `tx` can still be null here — a marked hook also fires for a write performed outside any
+ * transaction, and `catalogHookContext` passes `tx: null` for one. Such a hook keeps the outside
+ * connection, because that is the only connection there is; handing it nothing would silently stop
+ * every non-transactional write from announcing itself, which is worse than the defect above.
+ */
+function inTransactionHookContext(context) {
+    if (context.tx == null)
+        return context;
+    return { ...context, db: context.tx };
+}
 /** Default hook timeout: 20 seconds */
 const HOOK_TIMEOUT_MS = 20_000;
 function withTimeout(promiseOrValue, timeoutMs, hookName) {
@@ -57,7 +81,7 @@ export async function runAfterHooks(hooks, originalData, committedResult, operat
             result: committedResult,
             operation,
             context: runsInTransaction(hook)
-                ? context
+                ? inTransactionHookContext(context)
                 : { ...context, tx: null },
         }), HOOK_TIMEOUT_MS, hookName);
         if (runsInTransaction(hook)) {
@@ -65,10 +89,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 +103,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 +120,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/test-utils/create-two-connection-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A test adapter whose transaction handle and `db` handle are two DIFFERENT connections.
+ *
+ * Every other test adapter in this repo is one PGlite instance, which hands the transaction body
+ * the SAME `db` handle it hands everyone else. That makes a whole class of defect invisible by
+ * construction: a write issued on the `db` handle while a transaction is open rides that open
+ * transaction, so it commits and rolls back with it, and a test asserting "the write rolled back"
+ * passes whether or not the code under test routed the write through `tx` at all.
+ *
+ * On the driver this project actually deploys — Neon over HTTP — every plain query on the `db`
+ * handle is its own request on its own connection. Such a write does NOT join the open transaction
+ * and SURVIVES its rollback. Measured on the deployed Worker, 2026-09-15:
+ *
+ *     POST /api/loom/_proof/abort-after-hook
+ *     committed: false   entity_exists = 0   pending_for_aborted = 1
+ *
+ * This adapter reproduces that property with two PGlite instances: transactions run on one, the
+ * `db` handle is the other. The two do not share data, which a real two-connection driver would —
+ * that is the one way it is unlike Neon, and it is why the assertions below name WHICH connection
+ * a row landed on rather than reading either one alone.
+ */
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+export interface TwoConnectionTestAdapter {
+    adapter: DatabaseAdapter;
+    /** The connection `adapter.transaction` opens its transaction on. */
+    txDb: DrizzleDatabase;
+    /** The connection `adapter.db` points at — the "outside" connection. */
+    outsideDb: DrizzleDatabase;
+    cleanup: () => Promise<void>;
+}
+export declare function createTwoConnectionTestAdapter(): Promise<TwoConnectionTestAdapter>;
+//# sourceMappingURL=create-two-connection-adapter.d.ts.map

package/dist/test-utils/create-two-connection-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-two-connection-adapter.d.ts","sourceRoot":"","sources":["../../src/test-utils/create-two-connection-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAGxE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,eAAe,CAAC;IACzB,qEAAqE;IACrE,IAAI,EAAE,eAAe,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAsB,8BAA8B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAmBxF"}

package/dist/test-utils/create-two-connection-adapter.js

@@ -0,0 +1,40 @@
+/**
+ * A test adapter whose transaction handle and `db` handle are two DIFFERENT connections.
+ *
+ * Every other test adapter in this repo is one PGlite instance, which hands the transaction body
+ * the SAME `db` handle it hands everyone else. That makes a whole class of defect invisible by
+ * construction: a write issued on the `db` handle while a transaction is open rides that open
+ * transaction, so it commits and rolls back with it, and a test asserting "the write rolled back"
+ * passes whether or not the code under test routed the write through `tx` at all.
+ *
+ * On the driver this project actually deploys — Neon over HTTP — every plain query on the `db`
+ * handle is its own request on its own connection. Such a write does NOT join the open transaction
+ * and SURVIVES its rollback. Measured on the deployed Worker, 2026-09-15:
+ *
+ *     POST /api/loom/_proof/abort-after-hook
+ *     committed: false   entity_exists = 0   pending_for_aborted = 1
+ *
+ * This adapter reproduces that property with two PGlite instances: transactions run on one, the
+ * `db` handle is the other. The two do not share data, which a real two-connection driver would —
+ * that is the one way it is unlike Neon, and it is why the assertions below name WHICH connection
+ * a row landed on rather than reading either one alone.
+ */
+import { createPGliteTestAdapter } from "./create-pglite-adapter.js";
+export async function createTwoConnectionTestAdapter() {
+    const transactional = await createPGliteTestAdapter();
+    const outside = await createPGliteTestAdapter();
+    const adapter = {
+        provider: "postgresql",
+        db: outside.db,
+        transaction: transactional.adapter.transaction,
+    };
+    return {
+        adapter,
+        txDb: transactional.db,
+        outsideDb: outside.db,
+        cleanup: async () => {
+            await transactional.cleanup();
+            await outside.cleanup();
+        },
+    };
+}

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.1",
+  "version": "0.37.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -62,8 +62,8 @@
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/kernel/hooks/executor.ts

@@ -1,5 +1,7 @@
 import type { AfterHook, BeforeHook, HookContext, HookOperation } from "./types.js";
+import type { PluginDb } from "../database/plugin-types.js";
 import { deferAfterCommit } from "./deferred.js";
+import { reportHookFailure } from "./failures.js";
 
 export interface HookError {
   hookName: string;
@@ -18,6 +20,29 @@ export function mergeHookReports(a: HookReport, b: HookReport): HookReport {
   };
 }
 
+/**
+ * The context a hook marked `inTransaction: true` receives.
+ *
+ * `inTransaction` buys ORDERING on its own — the hook runs inline, before the commit. It does not
+ * make the hook's WRITES part of the transaction: `context.db` is the plugin db handle, and on a
+ * two-connection driver (Neon over HTTP, where every plain query is its own request) a write on
+ * that handle is not in the transaction and survives its rollback. Measured on the deployed Worker
+ * on 2026-09-15: an aborted write left `entity_exists = 0` and `pending_for_aborted = 1` — a row
+ * that rolled back announcing itself in the outbox whose entire purpose is committing with it.
+ *
+ * So the kernel hands such a hook a context it cannot get this wrong from: `db` IS the transaction.
+ * A plugin author writing the obvious thing lands inside the transaction, with nothing to remember.
+ *
+ * `tx` can still be null here — a marked hook also fires for a write performed outside any
+ * transaction, and `catalogHookContext` passes `tx: null` for one. Such a hook keeps the outside
+ * connection, because that is the only connection there is; handing it nothing would silently stop
+ * every non-transactional write from announcing itself, which is worse than the defect above.
+ */
+function inTransactionHookContext(context: HookContext): HookContext {
+  if (context.tx == null) return context;
+  return { ...context, db: context.tx as PluginDb };
+}
+
 /** Default hook timeout: 20 seconds */
 const HOOK_TIMEOUT_MS = 20_000;
 
@@ -97,7 +122,7 @@ export async function runAfterHooks<T>(
           result: committedResult,
           operation,
           context: runsInTransaction(hook)
-            ? context
+            ? inTransactionHookContext(context)
             : { ...context, tx: null },
         }),
         HOOK_TIMEOUT_MS,
@@ -108,10 +133,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 +147,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 +164,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/test-utils/create-two-connection-adapter.ts

@@ -0,0 +1,55 @@
+/**
+ * A test adapter whose transaction handle and `db` handle are two DIFFERENT connections.
+ *
+ * Every other test adapter in this repo is one PGlite instance, which hands the transaction body
+ * the SAME `db` handle it hands everyone else. That makes a whole class of defect invisible by
+ * construction: a write issued on the `db` handle while a transaction is open rides that open
+ * transaction, so it commits and rolls back with it, and a test asserting "the write rolled back"
+ * passes whether or not the code under test routed the write through `tx` at all.
+ *
+ * On the driver this project actually deploys — Neon over HTTP — every plain query on the `db`
+ * handle is its own request on its own connection. Such a write does NOT join the open transaction
+ * and SURVIVES its rollback. Measured on the deployed Worker, 2026-09-15:
+ *
+ *     POST /api/loom/_proof/abort-after-hook
+ *     committed: false   entity_exists = 0   pending_for_aborted = 1
+ *
+ * This adapter reproduces that property with two PGlite instances: transactions run on one, the
+ * `db` handle is the other. The two do not share data, which a real two-connection driver would —
+ * that is the one way it is unlike Neon, and it is why the assertions below name WHICH connection
+ * a row landed on rather than reading either one alone.
+ */
+
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+import { createPGliteTestAdapter } from "./create-pglite-adapter.js";
+
+export interface TwoConnectionTestAdapter {
+  adapter: DatabaseAdapter;
+  /** The connection `adapter.transaction` opens its transaction on. */
+  txDb: DrizzleDatabase;
+  /** The connection `adapter.db` points at — the "outside" connection. */
+  outsideDb: DrizzleDatabase;
+  cleanup: () => Promise<void>;
+}
+
+export async function createTwoConnectionTestAdapter(): Promise<TwoConnectionTestAdapter> {
+  const transactional = await createPGliteTestAdapter();
+  const outside = await createPGliteTestAdapter();
+
+  const adapter: DatabaseAdapter = {
+    provider: "postgresql",
+    db: outside.db,
+    transaction: transactional.adapter.transaction,
+  };
+
+  return {
+    adapter,
+    txDb: transactional.db,
+    outsideDb: outside.db,
+    cleanup: async () => {
+      await transactional.cleanup();
+      await outside.cleanup();
+    },
+  };
+}

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