@axiom-lattice/pg-stores 3.2.2 → 3.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/pg-stores@3.2.2 build /home/runner/work/agentic/agentic/packages/pg-stores
+> @axiom-lattice/pg-stores@3.3.0 build /home/runner/work/agentic/agentic/packages/pg-stores
 > tsup src/index.ts --format cjs,esm --dts --sourcemap
 
 CLI Building entry: src/index.ts
@@ -8,13 +8,13 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/index.js     421.08 KB
-CJS dist/index.js.map 767.96 KB
-CJS ⚡️ Build success in 925ms
-ESM dist/index.mjs     412.72 KB
-ESM dist/index.mjs.map 767.62 KB
-ESM ⚡️ Build success in 1051ms
+CJS dist/index.js     433.50 KB
+CJS dist/index.js.map 790.48 KB
+CJS ⚡️ Build success in 806ms
+ESM dist/index.mjs     425.03 KB
+ESM dist/index.mjs.map 790.15 KB
+ESM ⚡️ Build success in 866ms
 DTS Build start
-DTS ⚡️ Build success in 13948ms
-DTS dist/index.d.ts  86.96 KB
-DTS dist/index.d.mts 86.96 KB
+DTS ⚡️ Build success in 13743ms
+DTS dist/index.d.ts  91.36 KB
+DTS dist/index.d.mts 91.36 KB

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @axiom-lattice/pg-stores
 
+## 3.3.0
+
+### Minor Changes
+
+- eafaac8: Multi-gateway (PostgreSQL-only) coordination primitives — Plans 1 & 2.
+
+  **Plan 1 — replica identity + distributed leases**
+
+  - `getReplicaId()` stable per-process replica identity (`AXIOM_REPLICA_ID` or `hostname:pid`).
+  - `LeaseStore` / `LeaseRecord` protocol, `InMemoryLeaseStore` (registered as the default `"lease"` store), and `PostgreSQLLeaseStore` (migration v185 `lattice_leases`; atomic self-expiring upsert).
+  - `withLease(store, key, ownerLabel, fn)` — distributed critical-section helper with a unique per-invocation holder, bounded acquisition, heartbeat, and release-in-finally.
+
+  **Plan 2 — atomic thread-message-queue claim + lease**
+
+  - `ClaimMessagesOptions` and `IMessageQueueStore.claimPendingMessages` / `reclaimExpiredProcessing`.
+  - PostgreSQL migration v186 adds `locked_by` / `locked_at` / `lease_expires_at`; claim is an atomic `UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED)` so concurrent Gateway replicas receive disjoint sets.
+  - In-memory and local SQLite implementations match the same semantics.
+
+  No existing behavior changes: the legacy `markProcessing` path is untouched; `Agent` is not yet rewired to the new claim (that is a follow-up plan).
+
+- 396ad50: Multi-gateway (PostgreSQL-only) Plan 9 — durable outbox + cross-replica task notifications.
+
+  - `OutboxStore` / `OutboxEvent`: append-only durable event log (`append` / `listAfter` / `latestId`), InMemory + PostgreSQL (`lattice_outbox`, migration v187).
+  - `TaskLifecycleNotifier` / `ProjectTaskAdmissionNotifier`: `publish` keeps its existing local delivery and best-effort appends to the outbox (`originReplicaId`); new `setOutbox` + `deliverFromOutbox`.
+  - `OutboxPoller`: per-replica cursor poller that delivers only **foreign** outbox rows to local listeners (skips its own origin), so a peer's task lifecycle/admission events reach every replica.
+  - Gateway startup installs the outbox on both notifiers and starts the poller.
+  - e2e scenario 7: replica A publishes a lifecycle event; replica B receives it via the outbox; A receives its own exactly once (no double delivery). `pnpm e2e:multi-replica` now 7/7.
+
+  Deferred: scheduler startup restore/gating, Project Room realtime backplane, thread→replica streaming affinity.
+
+- 6080389: Scheduler exactly-once across replicas (claim-before-execute).
+
+  - `ScheduleStorage.claimScheduledRun(taskId)` atomically transitions `pending -> running` (Memory/Local/PostgreSQL implementations).
+  - `DefaultScheduleClient.executeTask` claims before running the handler, so a fire armed on multiple replicas executes only once (losers skip). Retry/CRON-rearm paths re-set `PENDING`, so later fires are claimable. See ADR-158.
+
+- 7ecbd01: Recover scheduled tasks stuck `running` after a crash.
+
+  - `ScheduleStorage.requeueStaleRunning(olderThanMs)` requeues `running` tasks older than a threshold back to `pending` (Memory/Local/PostgreSQL).
+  - `DefaultScheduleClient.restore()` requeues stale `running` schedules (30-minute heuristic) before re-arming, so a CRON schedule is no longer permanently stalled by a crash that left an unsettled claim. See ADR-158.
+
+### Patch Changes
+
+- 360f9e9: Age-based retention/pruning for the durable outbox.
+
+  - `OutboxStore.pruneOlderThan(olderThanMs)` (InMemory + PostgreSQL).
+  - Gateway `OutboxRetentionJob` prunes `lattice_outbox` rows older than `AXIOM_OUTBOX_RETENTION_HOURS` (default 24h; `0`/invalid disables), after startup and every 6h. Safe because pollers read only new rows and history is not replayed. See ADR-161.
+
+- b8c4c92: Multi-gateway (PostgreSQL-only) Plan 3 — thread-run ownership lease + JSONB fix.
+
+  - `threadRunLeaseKey` / `tryAcquireThreadRun` (non-blocking, heartbeat, idempotent holder-scoped release): a per-thread run ownership lease keyed `thread-run:<tenant>:<assistant>:<thread>`.
+  - `Agent` now gates its queue processor and `resumeTask()` behind that lease, so at most one Gateway replica processes a given thread at a time. Single-process behavior is unchanged (the default in-memory lease always acquires); multi-replica deployments require the PostgreSQL lease store.
+  - Fix: `ThreadMessageQueueStore.rowToMessage` no longer `JSON.parse`es the already-deserialized JSONB `message_content`, which previously threw for bare-string content.
+
+  Out of scope / follow-ups: cross-replica wakeup (Plan 5) and `ProjectTaskExecutionService.recover()` honoring `resumeTask`'s `settled:false` on lease contention (Plan 4).
+
+- Updated dependencies [6addbbf]
+- Updated dependencies [66e6080]
+- Updated dependencies [360f9e9]
+- Updated dependencies [eafaac8]
+- Updated dependencies [b8c4c92]
+- Updated dependencies [4c99955]
+- Updated dependencies [167620b]
+- Updated dependencies [d3cd2d5]
+- Updated dependencies [396ad50]
+- Updated dependencies [eec9db7]
+- Updated dependencies [d4429f1]
+- Updated dependencies [6080389]
+- Updated dependencies [7ecbd01]
+- Updated dependencies [e5e7b0f]
+- Updated dependencies [00b179d]
+- Updated dependencies [5f3d14b]
+  - @axiom-lattice/core@6.3.0
+  - @axiom-lattice/protocols@4.7.0
+
 ## 3.2.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { Pool, PoolConfig, PoolClient } from 'pg';
 export { Pool, PoolConfig } from 'pg';
-import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, ConnectionStore, ConnectionEntry, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, ProjectFilter, Project, CreateProjectRequest, UpdateProjectRequest, UpdateProjectCapabilityBundlesResult, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, QueryWorkflowRunsOptions, QueryWorkflowRunsResult, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, BindingMutablePatch, BindingListParams, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationInput, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, UpdateA2AApiKeyInput, A2AApiKeyEntry, OpenAuditStore, OpenAuditQuery, OpenAuditRecord, OpenAuditAppendInput, AgentWebAppStore, AgentWebApp, CreateAgentWebAppInput, AgentWebAppStorePatch, AgentWebAppUpdateOptions, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, TaskDependentListQuery, UpdateTaskRequest, TaskMutationSnapshot, TaskWorkItemStore, CreateWorkItemRequest, TaskWorkItem, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, CollectionStore, Collection, CreateCollectionRequest, UpdateCollectionRequest, VectorStoreProvider, VectorStoreCreateParams, CapabilityBundleStore, CapabilityBundle, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput, CapabilityBundleDeleteResult, ProjectRoomStore, ProjectRoom, ProjectMembershipStore, ProjectMembership, ProjectHumanRole, ProjectMembershipMutationResult, ProjectBotMembershipStore, ProjectBotMembership, ProjectRoomMessageStore, ProjectRoomMessage, ProjectRoomReadStateStore, ProjectRoomReadState, UserPushSubscriptionStore, UserPushSubscription, ModelProviderStore, ModelProviderEntry, CreateModelProviderRequest, UpdateModelProviderRequest, ModelProviderStatus, ModelProviderModelEntry, ProviderModelInput, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
+import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, ConnectionStore, ConnectionEntry, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, ProjectFilter, Project, CreateProjectRequest, UpdateProjectRequest, UpdateProjectCapabilityBundlesResult, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, QueryWorkflowRunsOptions, QueryWorkflowRunsResult, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, BindingMutablePatch, BindingListParams, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationInput, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, UpdateA2AApiKeyInput, A2AApiKeyEntry, OpenAuditStore, OpenAuditQuery, OpenAuditRecord, OpenAuditAppendInput, AgentWebAppStore, AgentWebApp, CreateAgentWebAppInput, AgentWebAppStorePatch, AgentWebAppUpdateOptions, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, TaskDependentListQuery, UpdateTaskRequest, TaskMutationSnapshot, TaskWorkItemStore, CreateWorkItemRequest, TaskWorkItem, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, CollectionStore, Collection, CreateCollectionRequest, UpdateCollectionRequest, VectorStoreProvider, VectorStoreCreateParams, CapabilityBundleStore, CapabilityBundle, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput, CapabilityBundleDeleteResult, ProjectRoomStore, ProjectRoom, ProjectMembershipStore, ProjectMembership, ProjectHumanRole, ProjectMembershipMutationResult, ProjectBotMembershipStore, ProjectBotMembership, ProjectRoomMessageStore, ProjectRoomMessage, ProjectRoomReadStateStore, ProjectRoomReadState, UserPushSubscriptionStore, UserPushSubscription, ModelProviderStore, ModelProviderEntry, CreateModelProviderRequest, UpdateModelProviderRequest, ModelProviderStatus, ModelProviderModelEntry, ProviderModelInput, LeaseStore, LeaseRecord, OutboxStore, OutboxEvent, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
 export { AgentWebApp, AgentWebAppAppearance, AgentWebAppFeatures, AgentWebAppScope, AgentWebAppStatus, AgentWebAppStore, Assistant, AssistantStore, Binding, BindingRegistry, CapabilityBundle, CapabilityBundleStore, ChannelInstallation, ChannelInstallationStore, ConnectionEntry, ConnectionStore, CreateAgentWebAppInput, CreateAssistantRequest, CreateBindingInput, CreateCapabilityBundleInput, CreateChannelInstallationInput, CreateChannelInstallationRequest, CreateDatabaseConfigRequest, CreateEvalCaseRequest, CreateEvalProjectRequest, CreateEvalRunRequest, CreateEvalSuiteRequest, CreateMcpServerConfigRequest, CreateMenuItemInput, CreateMetricsServerConfigRequest, CreateProjectRequest, CreateRunStepRequest, CreateShareRequest, CreateSkillRequest, CreateTenantRequest, CreateThreadRequest, CreateUserRequest, CreateUserTenantLinkRequest, CreateWorkflowRunRequest, CreateWorkspaceRequest, DatabaseConfig, DatabaseConfigEntry, DatabaseConfigStore, DatabaseType, EvalCase, EvalProject, EvalProjectReport, EvalRun, EvalRunResult, EvalStore, EvalSuite, LarkChannelInstallationConfig, McpServerConfigEntry, McpServerConfigStore, MenuItem, MenuRegistry, MetricsServerConfig, MetricsServerConfigEntry, MetricsServerConfigStore, Project, ProjectStore, ResourceAddress, RunStep, ScheduleExecutionType, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ShareRecord, ShareResult, ShareVisibility, SharedResourceStore, Skill, SkillStore, StorageType, Tenant, TenantStatus, TenantStore, Thread, ThreadStore, UpdateAgentWebAppInput, UpdateCapabilityBundleInput, UpdateChannelInstallationRequest, UpdateDatabaseConfigRequest, UpdateMcpServerConfigRequest, UpdateMetricsServerConfigRequest, UpdateProjectRequest, UpdateRunStepRequest, UpdateTenantRequest, UpdateUserRequest, UpdateUserTenantLinkRequest, UpdateWorkflowRunRequest, UpdateWorkspaceRequest, User, UserStore, UserTenantLink, UserTenantLinkStore, UserTenantRole, WorkflowRun, WorkflowTrackingStore, Workspace, WorkspaceStore } from '@axiom-lattice/protocols';
-import { IMessageQueueStore, AddMessageParams, PendingMessage, QueueScope, ThreadInfo } from '@axiom-lattice/core';
+import { IMessageQueueStore, AddMessageParams, PendingMessage, QueueScope, ClaimMessagesOptions, ThreadInfo } from '@axiom-lattice/core';
 export { AddMessageParams, PendingMessage, ThreadInfo } from '@axiom-lattice/core';
 import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 import { DocumentInterface } from '@langchain/core/documents';
@@ -925,6 +925,14 @@ declare class ThreadMessageQueueStore implements IMessageQueueStore {
      * Get pending messages for thread
      */
     getPendingMessages(threadId: string, scope?: QueueScope): Promise<PendingMessage[]>;
+    /**
+     * Atomically claims pending messages for a replica, stamping a lease.
+     */
+    claimPendingMessages(threadId: string, scope: QueueScope | undefined, options: ClaimMessagesOptions): Promise<PendingMessage[]>;
+    /**
+     * Returns expired processing rows to pending and clears their lease.
+     */
+    reclaimExpiredProcessing(threadId: string, scope?: QueueScope): Promise<number>;
     /**
      * Get processing messages for a thread
      */
@@ -1159,6 +1167,25 @@ declare class PostgreSQLScheduleStorage implements ScheduleStorage {
      * Update task
      */
     update(taskId: string, updates: Partial<ScheduledTaskDefinition>): Promise<void>;
+    /**
+     * Atomically claims one due fire by transitioning the task `pending -> running`.
+     *
+     * Only one caller wins the `UPDATE ... WHERE status = 'pending'`; all others
+     * observe zero affected rows and must skip execution.
+     *
+     * @param taskId Task to claim.
+     * @returns True when this caller won the claim (task was `pending`); false if
+     *   another replica already claimed it or it is not pending.
+     */
+    claimScheduledRun(taskId: string): Promise<boolean>;
+    /**
+     * Requeues `running` tasks whose `updated_at` is older than `olderThanMs` back
+     * to `pending` (recovery after a crash that left a claim unsettled).
+     *
+     * @param olderThanMs Age threshold in milliseconds.
+     * @returns The number of tasks requeued.
+     */
+    requeueStaleRunning(olderThanMs: number): Promise<number>;
     /**
      * Delete task
      */
@@ -1811,6 +1838,84 @@ declare class PostgreSQLModelProviderStore implements ModelProviderStore {
     private mapRowToModel;
 }
 
+interface PostgreSQLLeaseStoreOptions {
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL {@link LeaseStore}: cross-replica exclusion with self-expiring rows.
+ *
+ * @remarks `tryAcquire` is a single atomic upsert guarded by `expires_at`; no
+ * external lock manager is required. Uses the shared `lattice_leases` table.
+ */
+declare class PostgreSQLLeaseStore implements LeaseStore {
+    private pool;
+    private ownsPool;
+    private initialized;
+    private initPromise;
+    private migrationManager;
+    /** @param options An externally managed pool, or a pool config/URL. */
+    constructor(options: PostgreSQLLeaseStoreOptions);
+    /** Runs pending migrations once. */
+    initialize(): Promise<void>;
+    /** Ends the pool when this store owns it. */
+    dispose(): Promise<void>;
+    /** Atomically acquires a free/expired key (or re-acquires the caller's own). */
+    tryAcquire(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Extends a lease only while `holder` still owns it. */
+    renew(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Deletes a lease only when `holder` owns it. */
+    release(key: string, holder: string): Promise<boolean>;
+    /** Returns the live lease, or `null` when free/expired/absent. */
+    get(key: string): Promise<LeaseRecord | null>;
+}
+
+interface PostgreSQLOutboxStoreOptions {
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL {@link OutboxStore}: an append-only, cross-replica notification log.
+ *
+ * @remarks Ids come from a `BIGSERIAL`, giving a total order across replicas.
+ * Callers poll with a cursor (`listAfter`) and skip their own `originReplicaId`;
+ * delivery is therefore at-least-once. Uses the shared `lattice_outbox` table.
+ */
+declare class PostgreSQLOutboxStore implements OutboxStore {
+    private pool;
+    private ownsPool;
+    private initialized;
+    private initPromise;
+    private migrationManager;
+    /** @param options An externally managed pool, or a pool config/URL. */
+    constructor(options: PostgreSQLOutboxStoreOptions);
+    /** Runs pending migrations once. */
+    initialize(): Promise<void>;
+    /** Ends the pool when this store owns it. */
+    dispose(): Promise<void>;
+    /** Appends one event and returns it with its assigned id. */
+    append(input: {
+        topic: string;
+        payload: unknown;
+        originReplicaId: string;
+    }): Promise<OutboxEvent>;
+    /** Lists up to `limit` events with `id > cursor`, ascending. */
+    listAfter(cursor: string | null, limit: number): Promise<OutboxEvent[]>;
+    /** Returns the newest id, or `null` when the log is empty. */
+    latestId(): Promise<string | null>;
+    /**
+     * Deletes events older than `olderThanMs` (evaluated against the database clock).
+     *
+     * @param olderThanMs Age threshold in milliseconds.
+     * @returns The number of rows deleted.
+     */
+    pruneOlderThan(olderThanMs: number): Promise<number>;
+    /** Maps a `lattice_outbox` row to an {@link OutboxEvent}. */
+    private rowToEvent;
+}
+
 declare function createPgStoreConfig(connectionString: string): Promise<{
     workspace: PostgreSQLWorkspaceStore;
     project: PostgreSQLProjectStore;
@@ -1845,6 +1950,8 @@ declare function createPgStoreConfig(connectionString: string): Promise<{
     projectRoomMessage: PostgreSQLProjectRoomMessageStore;
     projectRoomReadState: PostgreSQLProjectRoomReadStateStore;
     userPushSubscription: PostgreSQLUserPushSubscriptionStore;
+    lease: PostgreSQLLeaseStore;
+    outbox: PostgreSQLOutboxStore;
     vectorStoreProvider: PGVectorStoreProvider;
     checkpoint: PostgresSaver;
 }>;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Pool, PoolConfig, PoolClient } from 'pg';
 export { Pool, PoolConfig } from 'pg';
-import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, ConnectionStore, ConnectionEntry, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, ProjectFilter, Project, CreateProjectRequest, UpdateProjectRequest, UpdateProjectCapabilityBundlesResult, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, QueryWorkflowRunsOptions, QueryWorkflowRunsResult, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, BindingMutablePatch, BindingListParams, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationInput, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, UpdateA2AApiKeyInput, A2AApiKeyEntry, OpenAuditStore, OpenAuditQuery, OpenAuditRecord, OpenAuditAppendInput, AgentWebAppStore, AgentWebApp, CreateAgentWebAppInput, AgentWebAppStorePatch, AgentWebAppUpdateOptions, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, TaskDependentListQuery, UpdateTaskRequest, TaskMutationSnapshot, TaskWorkItemStore, CreateWorkItemRequest, TaskWorkItem, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, CollectionStore, Collection, CreateCollectionRequest, UpdateCollectionRequest, VectorStoreProvider, VectorStoreCreateParams, CapabilityBundleStore, CapabilityBundle, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput, CapabilityBundleDeleteResult, ProjectRoomStore, ProjectRoom, ProjectMembershipStore, ProjectMembership, ProjectHumanRole, ProjectMembershipMutationResult, ProjectBotMembershipStore, ProjectBotMembership, ProjectRoomMessageStore, ProjectRoomMessage, ProjectRoomReadStateStore, ProjectRoomReadState, UserPushSubscriptionStore, UserPushSubscription, ModelProviderStore, ModelProviderEntry, CreateModelProviderRequest, UpdateModelProviderRequest, ModelProviderStatus, ModelProviderModelEntry, ProviderModelInput, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
+import { ThreadStore, Thread, CreateThreadRequest, AssistantStore, Assistant, CreateAssistantRequest, DatabaseConfigStore, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, ConnectionStore, ConnectionEntry, MetricsServerConfigStore, MetricsServerConfigEntry, CreateMetricsServerConfigRequest, UpdateMetricsServerConfigRequest, McpServerConfigStore, McpServerConfigEntry, CreateMcpServerConfigRequest, UpdateMcpServerConfigRequest, WorkspaceStore, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, ProjectStore, ProjectFilter, Project, CreateProjectRequest, UpdateProjectRequest, UpdateProjectCapabilityBundlesResult, UserStore, User, CreateUserRequest, UpdateUserRequest, TenantStore, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLinkStore, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, WorkflowTrackingStore, CreateWorkflowRunRequest, WorkflowRun, UpdateWorkflowRunRequest, QueryWorkflowRunsOptions, QueryWorkflowRunsResult, CreateRunStepRequest, RunStep, UpdateRunStepRequest, StepType, EvalStore, EvalProject, CreateEvalProjectRequest, EvalSuite, CreateEvalSuiteRequest, EvalCase, CreateEvalCaseRequest, EvalRun, CreateEvalRunRequest, EvalRunResult, EvalProjectReport, BindingRegistry, Binding, CreateBindingInput, BindingMutablePatch, BindingListParams, ChannelInstallationStore, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationInput, UpdateChannelInstallationRequest, A2AApiKeyStore, A2AApiKeyRecord, CreateA2AApiKeyInput, UpdateA2AApiKeyInput, A2AApiKeyEntry, OpenAuditStore, OpenAuditQuery, OpenAuditRecord, OpenAuditAppendInput, AgentWebAppStore, AgentWebApp, CreateAgentWebAppInput, AgentWebAppStorePatch, AgentWebAppUpdateOptions, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, TaskStore, CreateTaskRequest, TaskItem, TaskListFilter, TaskDependentListQuery, UpdateTaskRequest, TaskMutationSnapshot, TaskWorkItemStore, CreateWorkItemRequest, TaskWorkItem, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter, ProjectLifecycleEventQuery, MenuRegistry, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, SharedResourceStore, ShareRecord, CollectionStore, Collection, CreateCollectionRequest, UpdateCollectionRequest, VectorStoreProvider, VectorStoreCreateParams, CapabilityBundleStore, CapabilityBundle, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput, CapabilityBundleDeleteResult, ProjectRoomStore, ProjectRoom, ProjectMembershipStore, ProjectMembership, ProjectHumanRole, ProjectMembershipMutationResult, ProjectBotMembershipStore, ProjectBotMembership, ProjectRoomMessageStore, ProjectRoomMessage, ProjectRoomReadStateStore, ProjectRoomReadState, UserPushSubscriptionStore, UserPushSubscription, ModelProviderStore, ModelProviderEntry, CreateModelProviderRequest, UpdateModelProviderRequest, ModelProviderStatus, ModelProviderModelEntry, ProviderModelInput, LeaseStore, LeaseRecord, OutboxStore, OutboxEvent, SkillStore, Skill, CreateSkillRequest } from '@axiom-lattice/protocols';
 export { AgentWebApp, AgentWebAppAppearance, AgentWebAppFeatures, AgentWebAppScope, AgentWebAppStatus, AgentWebAppStore, Assistant, AssistantStore, Binding, BindingRegistry, CapabilityBundle, CapabilityBundleStore, ChannelInstallation, ChannelInstallationStore, ConnectionEntry, ConnectionStore, CreateAgentWebAppInput, CreateAssistantRequest, CreateBindingInput, CreateCapabilityBundleInput, CreateChannelInstallationInput, CreateChannelInstallationRequest, CreateDatabaseConfigRequest, CreateEvalCaseRequest, CreateEvalProjectRequest, CreateEvalRunRequest, CreateEvalSuiteRequest, CreateMcpServerConfigRequest, CreateMenuItemInput, CreateMetricsServerConfigRequest, CreateProjectRequest, CreateRunStepRequest, CreateShareRequest, CreateSkillRequest, CreateTenantRequest, CreateThreadRequest, CreateUserRequest, CreateUserTenantLinkRequest, CreateWorkflowRunRequest, CreateWorkspaceRequest, DatabaseConfig, DatabaseConfigEntry, DatabaseConfigStore, DatabaseType, EvalCase, EvalProject, EvalProjectReport, EvalRun, EvalRunResult, EvalStore, EvalSuite, LarkChannelInstallationConfig, McpServerConfigEntry, McpServerConfigStore, MenuItem, MenuRegistry, MetricsServerConfig, MetricsServerConfigEntry, MetricsServerConfigStore, Project, ProjectStore, ResourceAddress, RunStep, ScheduleExecutionType, ScheduleStorage, ScheduledTaskDefinition, ScheduledTaskStatus, ShareRecord, ShareResult, ShareVisibility, SharedResourceStore, Skill, SkillStore, StorageType, Tenant, TenantStatus, TenantStore, Thread, ThreadStore, UpdateAgentWebAppInput, UpdateCapabilityBundleInput, UpdateChannelInstallationRequest, UpdateDatabaseConfigRequest, UpdateMcpServerConfigRequest, UpdateMetricsServerConfigRequest, UpdateProjectRequest, UpdateRunStepRequest, UpdateTenantRequest, UpdateUserRequest, UpdateUserTenantLinkRequest, UpdateWorkflowRunRequest, UpdateWorkspaceRequest, User, UserStore, UserTenantLink, UserTenantLinkStore, UserTenantRole, WorkflowRun, WorkflowTrackingStore, Workspace, WorkspaceStore } from '@axiom-lattice/protocols';
-import { IMessageQueueStore, AddMessageParams, PendingMessage, QueueScope, ThreadInfo } from '@axiom-lattice/core';
+import { IMessageQueueStore, AddMessageParams, PendingMessage, QueueScope, ClaimMessagesOptions, ThreadInfo } from '@axiom-lattice/core';
 export { AddMessageParams, PendingMessage, ThreadInfo } from '@axiom-lattice/core';
 import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 import { DocumentInterface } from '@langchain/core/documents';
@@ -925,6 +925,14 @@ declare class ThreadMessageQueueStore implements IMessageQueueStore {
      * Get pending messages for thread
      */
     getPendingMessages(threadId: string, scope?: QueueScope): Promise<PendingMessage[]>;
+    /**
+     * Atomically claims pending messages for a replica, stamping a lease.
+     */
+    claimPendingMessages(threadId: string, scope: QueueScope | undefined, options: ClaimMessagesOptions): Promise<PendingMessage[]>;
+    /**
+     * Returns expired processing rows to pending and clears their lease.
+     */
+    reclaimExpiredProcessing(threadId: string, scope?: QueueScope): Promise<number>;
     /**
      * Get processing messages for a thread
      */
@@ -1159,6 +1167,25 @@ declare class PostgreSQLScheduleStorage implements ScheduleStorage {
      * Update task
      */
     update(taskId: string, updates: Partial<ScheduledTaskDefinition>): Promise<void>;
+    /**
+     * Atomically claims one due fire by transitioning the task `pending -> running`.
+     *
+     * Only one caller wins the `UPDATE ... WHERE status = 'pending'`; all others
+     * observe zero affected rows and must skip execution.
+     *
+     * @param taskId Task to claim.
+     * @returns True when this caller won the claim (task was `pending`); false if
+     *   another replica already claimed it or it is not pending.
+     */
+    claimScheduledRun(taskId: string): Promise<boolean>;
+    /**
+     * Requeues `running` tasks whose `updated_at` is older than `olderThanMs` back
+     * to `pending` (recovery after a crash that left a claim unsettled).
+     *
+     * @param olderThanMs Age threshold in milliseconds.
+     * @returns The number of tasks requeued.
+     */
+    requeueStaleRunning(olderThanMs: number): Promise<number>;
     /**
      * Delete task
      */
@@ -1811,6 +1838,84 @@ declare class PostgreSQLModelProviderStore implements ModelProviderStore {
     private mapRowToModel;
 }
 
+interface PostgreSQLLeaseStoreOptions {
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL {@link LeaseStore}: cross-replica exclusion with self-expiring rows.
+ *
+ * @remarks `tryAcquire` is a single atomic upsert guarded by `expires_at`; no
+ * external lock manager is required. Uses the shared `lattice_leases` table.
+ */
+declare class PostgreSQLLeaseStore implements LeaseStore {
+    private pool;
+    private ownsPool;
+    private initialized;
+    private initPromise;
+    private migrationManager;
+    /** @param options An externally managed pool, or a pool config/URL. */
+    constructor(options: PostgreSQLLeaseStoreOptions);
+    /** Runs pending migrations once. */
+    initialize(): Promise<void>;
+    /** Ends the pool when this store owns it. */
+    dispose(): Promise<void>;
+    /** Atomically acquires a free/expired key (or re-acquires the caller's own). */
+    tryAcquire(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Extends a lease only while `holder` still owns it. */
+    renew(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Deletes a lease only when `holder` owns it. */
+    release(key: string, holder: string): Promise<boolean>;
+    /** Returns the live lease, or `null` when free/expired/absent. */
+    get(key: string): Promise<LeaseRecord | null>;
+}
+
+interface PostgreSQLOutboxStoreOptions {
+    pool?: Pool;
+    poolConfig?: string | PoolConfig;
+    autoMigrate?: boolean;
+}
+/**
+ * PostgreSQL {@link OutboxStore}: an append-only, cross-replica notification log.
+ *
+ * @remarks Ids come from a `BIGSERIAL`, giving a total order across replicas.
+ * Callers poll with a cursor (`listAfter`) and skip their own `originReplicaId`;
+ * delivery is therefore at-least-once. Uses the shared `lattice_outbox` table.
+ */
+declare class PostgreSQLOutboxStore implements OutboxStore {
+    private pool;
+    private ownsPool;
+    private initialized;
+    private initPromise;
+    private migrationManager;
+    /** @param options An externally managed pool, or a pool config/URL. */
+    constructor(options: PostgreSQLOutboxStoreOptions);
+    /** Runs pending migrations once. */
+    initialize(): Promise<void>;
+    /** Ends the pool when this store owns it. */
+    dispose(): Promise<void>;
+    /** Appends one event and returns it with its assigned id. */
+    append(input: {
+        topic: string;
+        payload: unknown;
+        originReplicaId: string;
+    }): Promise<OutboxEvent>;
+    /** Lists up to `limit` events with `id > cursor`, ascending. */
+    listAfter(cursor: string | null, limit: number): Promise<OutboxEvent[]>;
+    /** Returns the newest id, or `null` when the log is empty. */
+    latestId(): Promise<string | null>;
+    /**
+     * Deletes events older than `olderThanMs` (evaluated against the database clock).
+     *
+     * @param olderThanMs Age threshold in milliseconds.
+     * @returns The number of rows deleted.
+     */
+    pruneOlderThan(olderThanMs: number): Promise<number>;
+    /** Maps a `lattice_outbox` row to an {@link OutboxEvent}. */
+    private rowToEvent;
+}
+
 declare function createPgStoreConfig(connectionString: string): Promise<{
     workspace: PostgreSQLWorkspaceStore;
     project: PostgreSQLProjectStore;
@@ -1845,6 +1950,8 @@ declare function createPgStoreConfig(connectionString: string): Promise<{
     projectRoomMessage: PostgreSQLProjectRoomMessageStore;
     projectRoomReadState: PostgreSQLProjectRoomReadStateStore;
     userPushSubscription: PostgreSQLUserPushSubscriptionStore;
+    lease: PostgreSQLLeaseStore;
+    outbox: PostgreSQLOutboxStore;
     vectorStoreProvider: PGVectorStoreProvider;
     checkpoint: PostgresSaver;
 }>;