@makaio/storage-pg 1.0.0-dev-1786014320559 → 1.0.0-dev-1788511348215

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { postgresStorageEngine } from './engine.js';
 export { isPostgresDuplicateObjectError, isPostgresUniqueViolationError } from './errors.js';
 export { postgresFtsSearchStrategy } from './fts-strategy.js';
 export { buildPostgresLedgerDdl, migrationAdvisoryLockKey, POSTGRES_MIGRATION_BEGIN } from './migrations.js';
+export { postgresTransactionLockExpressions, postgresTransactionLockKey, postgresTransactionLocks, } from './transaction-locks.js';
 /**
  * Well-known engine export consumed by host URL auto-resolve: runtime hosts
  * that recognize a Postgres database URL import this package and register

package/dist/index.mjs

@@ -455,6 +455,61 @@ async function acquirePostgresMigrationLock(session, ledgerTableName) {
 	await session.run(sql`SELECT pg_advisory_xact_lock(CAST(${lockKey} AS bigint))`);
 }
 
+//#endregion
+//#region src/transaction-locks.ts
+/**
+* Postgres implementation of stable transaction-key locks.
+* @packageDocumentation
+*/
+const FNV_64_OFFSET_BASIS = 14695981039346656037n;
+const FNV_64_PRIME = 1099511628211n;
+const UINT_64_MASK = 18446744073709551615n;
+const SIGNED_64_BOUNDARY = 9223372036854775808n;
+const UINT_64_RANGE = 18446744073709551616n;
+const encoder = new TextEncoder();
+/**
+* Write one UTF-8 string in an unambiguous length-prefixed representation.
+* @param value - String to frame.
+* @returns Big-endian length followed by the UTF-8 bytes.
+*/
+function frame(value) {
+	const bytes = encoder.encode(value);
+	const framed = new Uint8Array(4 + bytes.length);
+	new DataView(framed.buffer).setUint32(0, bytes.length, false);
+	framed.set(bytes, 4);
+	return framed;
+}
+/**
+* Derive a signed Postgres advisory key from a stable namespace and identity.
+*
+* Both values are UTF-8 length-framed before FNV-1a is applied, so distinct
+* `(namespace, identity)` pairs cannot collide through concatenation ambiguity.
+* @param lock - Stable lock identity supplied by a storage caller.
+* @returns Signed 64-bit key accepted by `pg_advisory_xact_lock`.
+*/
+function postgresTransactionLockKey(lock) {
+	let hash = FNV_64_OFFSET_BASIS;
+	for (const value of [lock.namespace, lock.identity]) for (const byte of frame(value)) {
+		hash ^= BigInt(byte);
+		hash = hash * FNV_64_PRIME & UINT_64_MASK;
+	}
+	return hash >= SIGNED_64_BOUNDARY ? hash - UINT_64_RANGE : hash;
+}
+/**
+* Build ordered advisory-lock expressions for a stable-key set.
+*
+* Postgres advisory locks are keyed by signed 64-bit integers. Deduplicating
+* and sorting those actual integers, rather than their input strings, gives
+* every transaction that needs the same set one database-level lock order.
+* @param locks - Stable keys the transaction will mutate.
+* @returns One transaction-scoped advisory-lock expression per distinct key.
+*/
+function postgresTransactionLockExpressions(locks) {
+	return [...new Set(locks.map(postgresTransactionLockKey))].sort((left, right) => left < right ? -1 : left > right ? 1 : 0).map((key) => sql`pg_advisory_xact_lock(CAST(${key.toString()} AS bigint))`);
+}
+/** Postgres strategy for the generic transaction-lock acquisition seam. */
+const postgresTransactionLocks = { lockExpressions: postgresTransactionLockExpressions };
+
 //#endregion
 //#region src/engine.ts
 /**
@@ -511,6 +566,7 @@ const postgresStorageEngine = {
 		acquireTransactionLock: acquirePostgresMigrationLock,
 		extensionLedgerName: (sourceHash) => `__makaio_migrations_${sourceHash}`
 	},
+	transactionLocks: postgresTransactionLocks,
 	fts: postgresFtsSearchStrategy
 };
 
@@ -525,4 +581,4 @@ const postgresStorageEngine = {
 const storageEngine = postgresStorageEngine;
 
 //#endregion
-export { POSTGRES_MIGRATION_BEGIN, buildPostgresLedgerDdl, isPostgresDuplicateObjectError, isPostgresUniqueViolationError, migrationAdvisoryLockKey, postgresFtsSearchStrategy, postgresStorageEngine, storageEngine };
+export { POSTGRES_MIGRATION_BEGIN, buildPostgresLedgerDdl, isPostgresDuplicateObjectError, isPostgresUniqueViolationError, migrationAdvisoryLockKey, postgresFtsSearchStrategy, postgresStorageEngine, postgresTransactionLockExpressions, postgresTransactionLockKey, postgresTransactionLocks, storageEngine };

package/dist/transaction-locks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Postgres implementation of stable transaction-key locks.
+ * @packageDocumentation
+ */
+import { type SQL } from 'drizzle-orm';
+import type { StorageEngineTransactionLocks, TransactionLock } from '@makaio/framework/storage/drizzle';
+/**
+ * Derive a signed Postgres advisory key from a stable namespace and identity.
+ *
+ * Both values are UTF-8 length-framed before FNV-1a is applied, so distinct
+ * `(namespace, identity)` pairs cannot collide through concatenation ambiguity.
+ * @param lock - Stable lock identity supplied by a storage caller.
+ * @returns Signed 64-bit key accepted by `pg_advisory_xact_lock`.
+ */
+export declare function postgresTransactionLockKey(lock: TransactionLock): bigint;
+/**
+ * Build ordered advisory-lock expressions for a stable-key set.
+ *
+ * Postgres advisory locks are keyed by signed 64-bit integers. Deduplicating
+ * and sorting those actual integers, rather than their input strings, gives
+ * every transaction that needs the same set one database-level lock order.
+ * @param locks - Stable keys the transaction will mutate.
+ * @returns One transaction-scoped advisory-lock expression per distinct key.
+ */
+export declare function postgresTransactionLockExpressions(locks: readonly TransactionLock[]): readonly SQL[];
+/** Postgres strategy for the generic transaction-lock acquisition seam. */
+export declare const postgresTransactionLocks: StorageEngineTransactionLocks;

package/drizzle-postgres/0024_m_msha1388.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "runtime_instances" (
+	"instance_id" text NOT NULL,
+	"machine_id" text NOT NULL,
+	"incarnation" integer NOT NULL,
+	"started_at" bigint NOT NULL,
+	"retired_at" bigint,
+	CONSTRAINT "runtime_instances_instance_id_machine_id_pk" PRIMARY KEY("instance_id","machine_id")
+);
+--> statement-breakpoint
+ALTER TABLE "adapter_session_claims" ADD COLUMN "owner_instance_id" text;--> statement-breakpoint
+CREATE UNIQUE INDEX "uniq_runtime_instances_incarnation" ON "runtime_instances" USING btree ("machine_id","incarnation");--> statement-breakpoint
+ALTER TABLE "adapter_session_claims" ADD CONSTRAINT "adapter_session_claims_owner_instance_id_machine_id_runtime_instances_instance_id_machine_id_fk" FOREIGN KEY ("owner_instance_id","machine_id") REFERENCES "runtime_instances"("instance_id","machine_id") ON DELETE restrict ON UPDATE no action;

package/drizzle-postgres/0025_m_mshgj6x7.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "agents" ADD COLUMN "owner_machine_id" text;--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "owner_instance_id" text;--> statement-breakpoint
+ALTER TABLE "agents" ADD CONSTRAINT "agents_runtime_owner_pair_check" CHECK (("agents"."owner_machine_id" IS NULL) = ("agents"."owner_instance_id" IS NULL));

package/drizzle-postgres/0026_m_msivwbgm.sql

@@ -0,0 +1 @@
+ALTER TABLE "agents" ADD COLUMN "recovery_attempt_id" text;

package/drizzle-postgres/0027_runtime_instance_incarnation_counter.sql

@@ -0,0 +1,6 @@
+-- Pre-release clean cut: reset existing development databases before applying
+-- this chain. The private allocator intentionally does not backfill prior rows.
+CREATE TABLE "runtime_instance_incarnation_counters" (
+	"machine_id" text PRIMARY KEY NOT NULL,
+	"last_allocated_incarnation" integer NOT NULL
+);

package/drizzle-postgres/meta/_journal.json

@@ -169,6 +169,34 @@
       "when": 1785874382691,
       "tag": "0023_m_msf3hu2s",
       "breakpoints": true
+    },
+    {
+      "idx": 24,
+      "version": "7",
+      "when": 1786006291205,
+      "tag": "0024_m_msha1388",
+      "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1786017213179,
+      "tag": "0025_m_mshgj6x7",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1786103485863,
+      "tag": "0026_m_msivwbgm",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1786383667306,
+      "tag": "0027_runtime_instance_incarnation_counter",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@makaio/storage-pg",
   "description": "Postgres storage engine for the Makaio framework: driver glue, error classification, and migration behavior registered through the storage engine seam.",
-  "version": "1.0.0-dev-1786014320559",
+  "version": "1.0.0-dev-1788511348215",
   "type": "module",
   "repository": {
     "type": "git",