@porulle/core 0.36.0 → 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;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"}
+{"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

@@ -6,6 +6,29 @@ export function mergeHookReports(a, b) {
         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) {
@@ -58,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)) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.36.0",
+  "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,4 +1,5 @@
 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";
 
@@ -19,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;
 
@@ -98,7 +122,7 @@ export async function runAfterHooks<T>(
           result: committedResult,
           operation,
           context: runsInTransaction(hook)
-            ? context
+            ? inTransactionHookContext(context)
             : { ...context, tx: null },
         }),
         HOOK_TIMEOUT_MS,

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();
+    },
+  };
+}