@molecule/api-instance-leadership-postgresql 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,287 @@
-# Temporary Holding Version
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-10-19T22:02:10.972Z
+-->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @molecule/api-instance-leadership-postgresql
+
+PostgreSQL provider for `@molecule/api-instance-leadership`: elect ONE API
+instance to run platform-wide singleton work, using a PostgreSQL SESSION
+advisory lock held on a dedicated connection.
+
+```typescript
+import { acquireLeadership, setProvider } from '@molecule/api-instance-leadership'
+import { provider } from '@molecule/api-instance-leadership-postgresql'
+
+setProvider(provider) // reads DATABASE_URL lazily; nothing connects here
+acquireLeadership({
+  onAcquired: () => startPoolManager(),
+  onLost: () => stopPoolManager(),
+})
+```
+
+Use this bond whenever the API runs as more than one process or Machine: a
+host-local lock (a loopback port, a file) elects one leader PER HOST, so
+every singleton — pool managers, hibernation, retention sweeps, status
+recorders — runs once per Machine instead of once per platform.
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-instance-leadership-postgresql @molecule/api-bond @molecule/api-instance-leadership pg
+npm install -D @types/pg
+```
+
+## API
+
+### Interfaces
+
+#### `PostgresLeaderLockOptions`
+
+How to open the dedicated leadership connection.
+
+```typescript
+interface PostgresLeaderLockOptions {
+  /**
+   * The lock id to hold. This is an arbitrary 64-bit integer that must be
+   * unique across everything sharing the database: leadership must never
+   * contend with a migration lock or another feature's advisory lock.
+   */
+  lockId: number
+
+  /** Connection string. Defaults to `process.env.DATABASE_URL`. */
+  connectionString?: string
+
+  /**
+   * TLS configuration passed to `pg`. Omit to let the driver decide from the
+   * connection string (`sslmode=require` still enables TLS).
+   */
+  ssl?: pg.ConnectionConfig['ssl']
+
+  /**
+   * Open a connected client. Injected by a host that owns its own connection
+   * settings (e.g. a platform API with a shared SSL derivation helper); the
+   * default creates a `pg.Client` from {@link PostgresLeaderLockOptions.connectionString}.
+   *
+   * @param connectionString - The resolved connection string.
+   * @param ssl - The configured TLS options.
+   * @returns A connected `pg.Client`.
+   */
+  connect?: (connectionString: string, ssl: pg.ConnectionConfig['ssl']) => Promise<pg.Client>
+}
+```
+
+#### `PostgresLeadershipProviderOptions`
+
+How to build a leadership provider.
+
+```typescript
+interface PostgresLeadershipProviderOptions {
+  /**
+   * Opens one dedicated lock session per attempt. Use
+   * {@link createPostgresLockFactory} for the production PostgreSQL session,
+   * or a fake that shares one "held by" flag in tests.
+   */
+  createSession: LeaderLockFactory
+
+  /**
+   * How often a follower retries, in milliseconds. A function keeps the value
+   * lazy so a host can read it from configuration after import. Defaults to
+   * 2000; values below 50 are clamped so a misconfiguration cannot spin.
+   */
+  retryMs?: number | (() => number)
+
+  /**
+   * The advisory lock id, used only in log lines (the factory owns the actual
+   * lock). Defaults to 0 when omitted.
+   */
+  lockId?: number
+}
+```
+
+### Classes
+
+#### `PgLeaderLockSession`
+
+The production session: one `pg.Client`, one advisory lock.
+
+Exported so a host that owns its own connection settings (the platform API's
+SSL derivation, a Vault-backed URL resolver) can build a session directly and
+pass it to the provider as its `createSession` factory.
+
+```typescript
+class PgLeaderLockSession implements LeaderLockSession {
+  private lostHandler: (() => void) | null = null
+  private lost = false
+
+  /**
+   * Track the connection's lifecycle so a lost session demotes the leader.
+   *
+   * @param client - A connected client owned exclusively by this session.
+   * @param lockId - The advisory lock id to hold.
+   */
+  constructor(
+    private readonly client: pg.Client,
+    private readonly lockId: number,
+  ) {
+    const lost = (): void => {
+      if (this.lost) return
+      this.lost = true
+      this.lostHandler?.()
+    }
+    // `error` covers a socket/network failure; `end` covers the backend ending
+    // the session (a server restart, an idle-session kill). Either way the lock
+    // is gone.
+    this.client.on('error', (error) => {
+      getLogger().warn('Leadership lock connection error', { error })
+      lost()
+    })
+    this.client.on('end', lost)
+  }
+
+  /** {@inheritDoc LeaderLockSession.tryLock} */
+  async tryLock(): Promise<boolean> {
+    const { rows } = await this.client.query<{ locked: boolean }>(
+      'SELECT pg_try_advisory_lock($1) AS locked',
+      [this.lockId],
+    )
+    return rows[0]?.locked === true
+  }
+
+  /** {@inheritDoc LeaderLockSession.release} */
+  async release(): Promise<void> {
+    if (!this.lost) {
+      try {
+        await this.client.query('SELECT pg_advisory_unlock($1)', [this.lockId])
+      } catch (error) {
+        // The session is ending either way, and a session lock is released by
+        // the backend when it ends — an unlock failure changes nothing.
+        getLogger().debug('Leadership advisory unlock failed; the session end releases it', {
+          error,
+        })
+      }
+    }
+    try {
+      await this.client.end()
+    } catch (_error) {
+      // Already ended.
+    }
+  }
+
+  /** {@inheritDoc LeaderLockSession.onLost} */
+  onLost(handler: () => void): void {
+    this.lostHandler = handler
+  }
+}
+```
+
+### Functions
+
+#### `createPostgresLockFactory(options)`
+
+Builds a {@link LeaderLockFactory} that opens PostgreSQL session locks.
+
+Each call to the factory opens a NEW dedicated connection — a follower
+retries on its own connection, and a leader reconnects on a fresh one after
+losing the old.
+
+```typescript
+function createPostgresLockFactory(options: PostgresLeaderLockOptions): LeaderLockFactory
+```
+
+- `options` — The lock id, connection settings and optional connect hook.
+
+**Returns:** A factory the leadership provider calls to open each session.
+
+#### `createProvider(options)`
+
+Creates an instance-leadership provider.
+
+```typescript
+function createProvider(options: PostgresLeadershipProviderOptions): InstanceLeadershipProvider
+```
+
+- `options` — The lock-session factory and retry interval.
+
+**Returns:** A provider implementing the core `InstanceLeadershipProvider` contract.
+
+### Constants
+
+#### `provider`
+
+A provider that reads its connection settings from `DATABASE_URL`.
+
+Its lock session is opened lazily, so importing (and bonding) this provider
+never connects. The lock id is the same one the API platform API has used
+for its singleton work; an app that shares a database with another
+leadership user must pass its OWN `lockId`.
+
+```typescript
+const provider: InstanceLeadershipProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-instance-leadership` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-instance-leadership'
+import { provider } from '@molecule/api-instance-leadership-postgresql'
+
+export function setupInstanceLeadershipPostgresql(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-instance-leadership` ^1.0.0
+
+### Environment Variables
+
+- `DATABASE_URL` _(required)_ — PostgreSQL connection string
+  - Setup: Use a direct connection or a session-mode pooler; transaction-mode pooling cannot retain advisory locks.
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-instance-leadership`
+- `pg`
+
+- **A session lock dies with its connection.** The holder's process exiting,
+  crashing, or losing the network ends the backend session and PostgreSQL
+  releases the lock — no TTL to tune, no lock row left stale.
+- **A leader that loses its connection demotes itself.** The provider stops
+  treating itself as leader and calls `onLost`; a follower retries every
+  `retryMs` (default 2 s) and takes over within seconds.
+- **`prepareThreshold`/pooling caveat.** The lock MUST be taken on a direct
+  client connection, never through a transaction-mode pooler (PgBouncer in
+  transaction mode), which multiplexes statements from many clients onto a
+  session: a lock "held" there is held by an unrelated session. Use a
+  session-mode pooler or a direct connection.
+- **Pick a lock id nobody else uses.** Advisory locks share one namespace per
+  database. The exported `provider` uses `8675310`; a second application
+  sharing the same database must pass its own id to
+  `createPostgresLockFactory`.
+- **This bond runs no singleton work itself.** It only tells the application
+  which instance leads; the loops belong to the app (`onAcquired`/`onLost`).

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-instance-leadership-postgresql` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-instance-leadership-postgresql is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * PostgreSQL provider for `@molecule/api-instance-leadership`: elect ONE API
+ * instance to run platform-wide singleton work, using a PostgreSQL SESSION
+ * advisory lock held on a dedicated connection.
+ *
+ * ```typescript
+ * import { acquireLeadership, setProvider } from '@molecule/api-instance-leadership'
+ * import { provider } from '@molecule/api-instance-leadership-postgresql'
+ *
+ * setProvider(provider) // reads DATABASE_URL lazily; nothing connects here
+ * acquireLeadership({
+ *   onAcquired: () => startPoolManager(),
+ *   onLost: () => stopPoolManager(),
+ * })
+ * ```
+ *
+ * Use this bond whenever the API runs as more than one process or Machine: a
+ * host-local lock (a loopback port, a file) elects one leader PER HOST, so
+ * every singleton — pool managers, hibernation, retention sweeps, status
+ * recorders — runs once per Machine instead of once per platform.
+ *
+ * @remarks
+ * - **A session lock dies with its connection.** The holder's process exiting,
+ *   crashing, or losing the network ends the backend session and PostgreSQL
+ *   releases the lock — no TTL to tune, no lock row left stale.
+ * - **A leader that loses its connection demotes itself.** The provider stops
+ *   treating itself as leader and calls `onLost`; a follower retries every
+ *   `retryMs` (default 2 s) and takes over within seconds.
+ * - **`prepareThreshold`/pooling caveat.** The lock MUST be taken on a direct
+ *   client connection, never through a transaction-mode pooler (PgBouncer in
+ *   transaction mode), which multiplexes statements from many clients onto a
+ *   session: a lock "held" there is held by an unrelated session. Use a
+ *   session-mode pooler or a direct connection.
+ * - **Pick a lock id nobody else uses.** Advisory locks share one namespace per
+ *   database. The exported `provider` uses `8675310`; a second application
+ *   sharing the same database must pass its own id to
+ *   `createPostgresLockFactory`.
+ * - **This bond runs no singleton work itself.** It only tells the application
+ *   which instance leads; the loops belong to the app (`onAcquired`/`onLost`).
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './lock.js';
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,45 @@
+/**
+ * PostgreSQL provider for `@molecule/api-instance-leadership`: elect ONE API
+ * instance to run platform-wide singleton work, using a PostgreSQL SESSION
+ * advisory lock held on a dedicated connection.
+ *
+ * ```typescript
+ * import { acquireLeadership, setProvider } from '@molecule/api-instance-leadership'
+ * import { provider } from '@molecule/api-instance-leadership-postgresql'
+ *
+ * setProvider(provider) // reads DATABASE_URL lazily; nothing connects here
+ * acquireLeadership({
+ *   onAcquired: () => startPoolManager(),
+ *   onLost: () => stopPoolManager(),
+ * })
+ * ```
+ *
+ * Use this bond whenever the API runs as more than one process or Machine: a
+ * host-local lock (a loopback port, a file) elects one leader PER HOST, so
+ * every singleton — pool managers, hibernation, retention sweeps, status
+ * recorders — runs once per Machine instead of once per platform.
+ *
+ * @remarks
+ * - **A session lock dies with its connection.** The holder's process exiting,
+ *   crashing, or losing the network ends the backend session and PostgreSQL
+ *   releases the lock — no TTL to tune, no lock row left stale.
+ * - **A leader that loses its connection demotes itself.** The provider stops
+ *   treating itself as leader and calls `onLost`; a follower retries every
+ *   `retryMs` (default 2 s) and takes over within seconds.
+ * - **`prepareThreshold`/pooling caveat.** The lock MUST be taken on a direct
+ *   client connection, never through a transaction-mode pooler (PgBouncer in
+ *   transaction mode), which multiplexes statements from many clients onto a
+ *   session: a lock "held" there is held by an unrelated session. Use a
+ *   session-mode pooler or a direct connection.
+ * - **Pick a lock id nobody else uses.** Advisory locks share one namespace per
+ *   database. The exported `provider` uses `8675310`; a second application
+ *   sharing the same database must pass its own id to
+ *   `createPostgresLockFactory`.
+ * - **This bond runs no singleton work itself.** It only tells the application
+ *   which instance leads; the loops belong to the app (`onAcquired`/`onLost`).
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './lock.js';
+export * from './provider.js';

package/dist/lock.d.ts

@@ -0,0 +1,86 @@
+/**
+ * PostgreSQL session-advisory-lock sessions for instance leadership.
+ *
+ * A session is one dedicated `pg.Client` (never a pool: a session lock is owned
+ * by its backend connection, and returning it to a pool would let unrelated
+ * queries run inside the lock's session) holding one advisory lock id.
+ *
+ * @module
+ */
+import pg from 'pg';
+import type { LeaderLockFactory, LeaderLockSession } from '@molecule/api-instance-leadership';
+/**
+ * How to open the dedicated leadership connection.
+ */
+export interface PostgresLeaderLockOptions {
+    /**
+     * The lock id to hold. This is an arbitrary 64-bit integer that must be
+     * unique across everything sharing the database: leadership must never
+     * contend with a migration lock or another feature's advisory lock.
+     */
+    lockId: number;
+    /** Connection string. Defaults to `process.env.DATABASE_URL`. */
+    connectionString?: string;
+    /**
+     * TLS configuration passed to `pg`. Omit to let the driver decide from the
+     * connection string (`sslmode=require` still enables TLS).
+     */
+    ssl?: pg.ConnectionConfig['ssl'];
+    /**
+     * Open a connected client. Injected by a host that owns its own connection
+     * settings (e.g. a platform API with a shared SSL derivation helper); the
+     * default creates a `pg.Client` from {@link PostgresLeaderLockOptions.connectionString}.
+     *
+     * @param connectionString - The resolved connection string.
+     * @param ssl - The configured TLS options.
+     * @returns A connected `pg.Client`.
+     */
+    connect?: (connectionString: string, ssl: pg.ConnectionConfig['ssl']) => Promise<pg.Client>;
+}
+/**
+ * The production session: one `pg.Client`, one advisory lock.
+ *
+ * Exported so a host that owns its own connection settings (the platform API's
+ * SSL derivation, a Vault-backed URL resolver) can build a session directly and
+ * pass it to the provider as its `createSession` factory.
+ */
+export declare class PgLeaderLockSession implements LeaderLockSession {
+    private readonly client;
+    private readonly lockId;
+    private lostHandler;
+    private lost;
+    /**
+     * Track the connection's lifecycle so a lost session demotes the leader.
+     *
+     * @param client - A connected client owned exclusively by this session.
+     * @param lockId - The advisory lock id to hold.
+     */
+    constructor(client: pg.Client, lockId: number);
+    /** {@inheritDoc LeaderLockSession.tryLock} */
+    tryLock(): Promise<boolean>;
+    /** {@inheritDoc LeaderLockSession.release} */
+    release(): Promise<void>;
+    /** {@inheritDoc LeaderLockSession.onLost} */
+    onLost(handler: () => void): void;
+}
+/**
+ * Builds a {@link LeaderLockFactory} that opens PostgreSQL session locks.
+ *
+ * Each call to the factory opens a NEW dedicated connection — a follower
+ * retries on its own connection, and a leader reconnects on a fresh one after
+ * losing the old.
+ *
+ * @param options - The lock id, connection settings and optional connect hook.
+ * @returns A factory the leadership provider calls to open each session.
+ * @throws {Error} When no connection string is configured (at factory-call
+ * time, so a boot fails with an actionable message rather than hanging).
+ *
+ * @example
+ * ```typescript
+ * import { createProvider } from '@molecule/api-instance-leadership-postgresql'
+ *
+ * const leadership = createProvider({ createSession: createPostgresLockFactory({ lockId: 8675310 }) })
+ * ```
+ */
+export declare function createPostgresLockFactory(options: PostgresLeaderLockOptions): LeaderLockFactory;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAA;AAGnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAE7F;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAA;IAEhC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAA;CAC5F;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAWzD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAXzB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,IAAI,CAAQ;IAEpB;;;;;OAKG;gBAEgB,MAAM,EAAE,EAAE,CAAC,MAAM,EACjB,MAAM,EAAE,MAAM;IAiBjC,8CAA8C;IACxC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAQjC,8CAA8C;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB9B,6CAA6C;IAC7C,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;CAGlC;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,iBAAiB,CAa/F"}

package/dist/lock.js

@@ -0,0 +1,128 @@
+/**
+ * PostgreSQL session-advisory-lock sessions for instance leadership.
+ *
+ * A session is one dedicated `pg.Client` (never a pool: a session lock is owned
+ * by its backend connection, and returning it to a pool would let unrelated
+ * queries run inside the lock's session) holding one advisory lock id.
+ *
+ * @module
+ */
+import pg from 'pg';
+import { getLogger } from '@molecule/api-bond';
+/**
+ * The production session: one `pg.Client`, one advisory lock.
+ *
+ * Exported so a host that owns its own connection settings (the platform API's
+ * SSL derivation, a Vault-backed URL resolver) can build a session directly and
+ * pass it to the provider as its `createSession` factory.
+ */
+export class PgLeaderLockSession {
+    client;
+    lockId;
+    lostHandler = null;
+    lost = false;
+    /**
+     * Track the connection's lifecycle so a lost session demotes the leader.
+     *
+     * @param client - A connected client owned exclusively by this session.
+     * @param lockId - The advisory lock id to hold.
+     */
+    constructor(client, lockId) {
+        this.client = client;
+        this.lockId = lockId;
+        const lost = () => {
+            if (this.lost)
+                return;
+            this.lost = true;
+            this.lostHandler?.();
+        };
+        // `error` covers a socket/network failure; `end` covers the backend ending
+        // the session (a server restart, an idle-session kill). Either way the lock
+        // is gone.
+        this.client.on('error', (error) => {
+            getLogger().warn('Leadership lock connection error', { error });
+            lost();
+        });
+        this.client.on('end', lost);
+    }
+    /** {@inheritDoc LeaderLockSession.tryLock} */
+    async tryLock() {
+        const { rows } = await this.client.query('SELECT pg_try_advisory_lock($1) AS locked', [this.lockId]);
+        return rows[0]?.locked === true;
+    }
+    /** {@inheritDoc LeaderLockSession.release} */
+    async release() {
+        if (!this.lost) {
+            try {
+                await this.client.query('SELECT pg_advisory_unlock($1)', [this.lockId]);
+            }
+            catch (error) {
+                // The session is ending either way, and a session lock is released by
+                // the backend when it ends — an unlock failure changes nothing.
+                getLogger().debug('Leadership advisory unlock failed; the session end releases it', {
+                    error,
+                });
+            }
+        }
+        try {
+            await this.client.end();
+        }
+        catch (_error) {
+            // Already ended.
+        }
+    }
+    /** {@inheritDoc LeaderLockSession.onLost} */
+    onLost(handler) {
+        this.lostHandler = handler;
+    }
+}
+/**
+ * Opens a dedicated PostgreSQL session for leadership.
+ *
+ * The connect timeout bounds a hung database: without it a boot could sit in
+ * `acquire()` forever with no leader and no log line.
+ *
+ * @param connectionString - The connection string to dial.
+ * @param ssl - TLS options for the client.
+ * @returns A connected client.
+ */
+async function defaultConnect(connectionString, ssl) {
+    const client = new pg.Client({
+        connectionString,
+        ssl,
+        connectionTimeoutMillis: 10_000,
+    });
+    await client.connect();
+    return client;
+}
+/**
+ * Builds a {@link LeaderLockFactory} that opens PostgreSQL session locks.
+ *
+ * Each call to the factory opens a NEW dedicated connection — a follower
+ * retries on its own connection, and a leader reconnects on a fresh one after
+ * losing the old.
+ *
+ * @param options - The lock id, connection settings and optional connect hook.
+ * @returns A factory the leadership provider calls to open each session.
+ * @throws {Error} When no connection string is configured (at factory-call
+ * time, so a boot fails with an actionable message rather than hanging).
+ *
+ * @example
+ * ```typescript
+ * import { createProvider } from '@molecule/api-instance-leadership-postgresql'
+ *
+ * const leadership = createProvider({ createSession: createPostgresLockFactory({ lockId: 8675310 }) })
+ * ```
+ */
+export function createPostgresLockFactory(options) {
+    const connect = options.connect ?? defaultConnect;
+    return async () => {
+        const connectionString = options.connectionString ?? process.env.DATABASE_URL;
+        if (!connectionString) {
+            throw new Error('Instance leadership needs DATABASE_URL (or an explicit connectionString): a PostgreSQL ' +
+                'session advisory lock is how one API instance is elected leader across every Machine.');
+        }
+        const client = await connect(connectionString, options.ssl);
+        return new PgLeaderLockSession(client, options.lockId);
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The instance-leadership state machine.
+ *
+ * One leader across every API instance, elected by a shared lock session, with
+ * demotion when the holder loses its connection and background re-acquisition
+ * (a follower retries every `retryMs`, default 2 s).
+ *
+ * The state is per-provider, never module-global, so a host process can create
+ * several providers (its server test suite boots multiple apps in one process)
+ * without them sharing a leader flag.
+ *
+ * @module
+ */
+import type { InstanceLeadershipProvider, LeaderLockFactory } from '@molecule/api-instance-leadership';
+/**
+ * How to build a leadership provider.
+ */
+export interface PostgresLeadershipProviderOptions {
+    /**
+     * Opens one dedicated lock session per attempt. Use
+     * {@link createPostgresLockFactory} for the production PostgreSQL session,
+     * or a fake that shares one "held by" flag in tests.
+     */
+    createSession: LeaderLockFactory;
+    /**
+     * How often a follower retries, in milliseconds. A function keeps the value
+     * lazy so a host can read it from configuration after import. Defaults to
+     * 2000; values below 50 are clamped so a misconfiguration cannot spin.
+     */
+    retryMs?: number | (() => number);
+    /**
+     * The advisory lock id, used only in log lines (the factory owns the actual
+     * lock). Defaults to 0 when omitted.
+     */
+    lockId?: number;
+}
+/**
+ * Creates an instance-leadership provider.
+ *
+ * @param options - The lock-session factory and retry interval.
+ * @returns A provider implementing the core `InstanceLeadershipProvider` contract.
+ *
+ * @example
+ * ```typescript
+ * import { createProvider, createPostgresLockFactory } from '@molecule/api-instance-leadership-postgresql'
+ * import { setProvider, acquireLeadership } from '@molecule/api-instance-leadership'
+ *
+ * const leadership = createProvider({
+ *   createSession: createPostgresLockFactory({ lockId: 8675310 }),
+ * })
+ * setProvider(leadership)
+ *
+ * acquireLeadership({
+ *   onAcquired: () => startPeriodicSweeps(),
+ *   onLost: () => stopPeriodicSweeps(),
+ * })
+ * ```
+ */
+export declare function createProvider(options: PostgresLeadershipProviderOptions): InstanceLeadershipProvider;
+/**
+ * A provider that reads its connection settings from `DATABASE_URL`.
+ *
+ * Its lock session is opened lazily, so importing (and bonding) this provider
+ * never connects. The lock id is the same one the API platform API has used
+ * for its singleton work; an app that shares a database with another
+ * leadership user must pass its OWN `lockId`.
+ */
+export declare const provider: InstanceLeadershipProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAEV,0BAA0B,EAC1B,iBAAiB,EAGlB,MAAM,mCAAmC,CAAA;AAI1C;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD;;;;OAIG;IACH,aAAa,EAAE,iBAAiB,CAAA;IAEhC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;IAEjC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,iCAAiC,GACzC,0BAA0B,CA+G5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,0BAGrB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,167 @@
+/**
+ * The instance-leadership state machine.
+ *
+ * One leader across every API instance, elected by a shared lock session, with
+ * demotion when the holder loses its connection and background re-acquisition
+ * (a follower retries every `retryMs`, default 2 s).
+ *
+ * The state is per-provider, never module-global, so a host process can create
+ * several providers (its server test suite boots multiple apps in one process)
+ * without them sharing a leader flag.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { createPostgresLockFactory } from './lock.js';
+/** The clamped, lazily-resolved retry interval. */
+function resolveRetryMs(retryMs) {
+    const raw = typeof retryMs === 'function' ? retryMs() : (retryMs ?? 2000);
+    return Math.max(50, Number.isFinite(raw) ? raw : 2000);
+}
+/**
+ * Creates an instance-leadership provider.
+ *
+ * @param options - The lock-session factory and retry interval.
+ * @returns A provider implementing the core `InstanceLeadershipProvider` contract.
+ *
+ * @example
+ * ```typescript
+ * import { createProvider, createPostgresLockFactory } from '@molecule/api-instance-leadership-postgresql'
+ * import { setProvider, acquireLeadership } from '@molecule/api-instance-leadership'
+ *
+ * const leadership = createProvider({
+ *   createSession: createPostgresLockFactory({ lockId: 8675310 }),
+ * })
+ * setProvider(leadership)
+ *
+ * acquireLeadership({
+ *   onAcquired: () => startPeriodicSweeps(),
+ *   onLost: () => stopPeriodicSweeps(),
+ * })
+ * ```
+ */
+export function createProvider(options) {
+    const logger = getLogger();
+    let leader = false;
+    let session = null;
+    let retryTimer = null;
+    let released = false;
+    let attemptInFlight = false;
+    let acquireOptions = null;
+    /** Schedule the next acquisition attempt, never keeping the process alive for it. */
+    const scheduleRetry = () => {
+        if (released || retryTimer)
+            return;
+        retryTimer = setTimeout(() => {
+            retryTimer = null;
+            void tryAcquire();
+        }, resolveRetryMs(options.retryMs));
+        retryTimer.unref?.();
+    };
+    /**
+     * One acquisition attempt: open a session (if needed) and ask for the lock.
+     *
+     * Serialized by `attemptInFlight` — a retry tick landing while a slow connect
+     * is in flight must not open a second connection.
+     */
+    const tryAcquire = async () => {
+        if (released || leader || attemptInFlight || !acquireOptions)
+            return;
+        attemptInFlight = true;
+        try {
+            if (!session) {
+                session = await options.createSession();
+                session.onLost(() => {
+                    // The connection is gone, so the store has released the lock.
+                    // Demote FIRST, then let the operator-facing stop run; a new leader
+                    // may already be starting its own copy of every singleton.
+                    const wasLeader = leader;
+                    leader = false;
+                    session = null;
+                    if (wasLeader) {
+                        logger.warn('Lost platform leadership — stopping singleton subsystems', {
+                            retryMs: resolveRetryMs(options.retryMs),
+                        });
+                        Promise.resolve()
+                            .then(() => acquireOptions?.onLost?.())
+                            .catch((error) => logger.error('Leader-lost shutdown failed', { error }));
+                    }
+                    scheduleRetry();
+                });
+            }
+            const acquired = await session.tryLock();
+            if (!acquired) {
+                scheduleRetry();
+                return;
+            }
+            leader = true;
+            if (retryTimer) {
+                clearTimeout(retryTimer);
+                retryTimer = null;
+            }
+            logger.info('Acquired platform leadership — starting singleton subsystems', {
+                lockId: options.lockId ?? 0,
+            });
+            Promise.resolve()
+                .then(() => acquireOptions?.onAcquired())
+                .catch((error) => {
+                logger.error('Leader-only startup failed', { error });
+            });
+        }
+        catch (error) {
+            // Store unreachable or the connect timed out. Drop the session (a
+            // half-open one would keep retrying against a dead socket) and try again.
+            logger.warn('Leadership lock attempt failed (will retry)', {
+                error,
+                retryMs: resolveRetryMs(options.retryMs),
+            });
+            const stale = session;
+            session = null;
+            void stale?.release().catch(() => undefined);
+            scheduleRetry();
+        }
+        finally {
+            attemptInFlight = false;
+        }
+    };
+    return {
+        isLeader() {
+            return leader;
+        },
+        state() {
+            if (released)
+                return 'stopped';
+            return leader ? 'leader' : 'follower';
+        },
+        acquire(nextOptions) {
+            if (leader || session || released)
+                return;
+            acquireOptions = nextOptions;
+            void tryAcquire();
+        },
+        async release() {
+            released = true;
+            if (retryTimer) {
+                clearTimeout(retryTimer);
+                retryTimer = null;
+            }
+            leader = false;
+            const current = session;
+            session = null;
+            if (current)
+                await current.release();
+        },
+    };
+}
+/**
+ * A provider that reads its connection settings from `DATABASE_URL`.
+ *
+ * Its lock session is opened lazily, so importing (and bonding) this provider
+ * never connects. The lock id is the same one the API platform API has used
+ * for its singleton work; an app that shares a database with another
+ * leadership user must pass its OWN `lockId`.
+ */
+export const provider = createProvider({
+    createSession: createPostgresLockFactory({ lockId: 8675310 }),
+    lockId: 8675310,
+});

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@molecule/api-instance-leadership-postgresql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "PostgreSQL provider for @molecule/api-instance-leadership: one leader across every API instance via a session advisory lock on a dedicated connection, with demotion when the connection is lost.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "molecule",
+    "leadership",
+    "leader election",
+    "advisory lock",
+    "postgresql",
+    "multi-instance"
+  ],
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "pg": "8.22.0"
+  },
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-instance-leadership": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.2",
+    "@molecule/api-instance-leadership": "1.1.0",
+    "@types/node": "26.1.2",
+    "@types/pg": "8.20.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/instance-leadership/postgresql"
+  },
+  "homepage": "https://www.molecule.dev/packages/api-instance-leadership-postgresql",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}