@axiom-lattice/gateway 4.1.0 → 4.1.2

package/dist/index.d.mts

@@ -1,50 +1,40 @@
 import * as http from 'http';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, ProjectRoomRealtimeActor, ProjectRoomSseWritable, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
-import { ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
 
-declare const defaultSwaggerConfig: {
-    openapi: {
-        openapi: string;
-        info: {
-            title: string;
-            description: string;
-            version: string;
-            contact: {
-                name: string;
-                email: string;
-            };
-        };
-        servers: {
-            url: string;
-            description: string;
-        }[];
-        components: {
-            securitySchemes: {
-                bearerAuth: {
-                    type: "http";
-                    scheme: "bearer";
-                    bearerFormat: string;
-                };
-            };
-        };
-        security: {
-            bearerAuth: never[];
-        }[];
-        tags: {
-            name: string;
-            description: string;
-        }[];
-    };
-};
-declare const defaultSwaggerUiConfig: {
-    routePrefix: string;
-    uiConfig: {
-        docExpansion: "full";
-        deepLinking: boolean;
-    };
-    staticCSP: boolean;
-    transformStaticCSP: (header: string) => string;
-};
+/** Public publisher surface for committed Project Room business facts. */
+interface ProjectRoomRealtimePublisher {
+    /** Publishes a newly committed room message. */
+    messageCreated(message: ProjectRoomMessage): void;
+    /** Publishes a committed bot roster mutation. */
+    rosterChanged(input: {
+        tenantId: string;
+        roomId: string;
+        membership: ProjectBotMembership;
+        change: "added" | "updated" | "paused" | "resumed" | "removed";
+        sourceKey: string;
+    }): void;
+    /** Publishes a committed human membership mutation. */
+    membershipChanged(input: {
+        tenantId: string;
+        roomId: string;
+        membership: ProjectMembership;
+        change: "added" | "role_changed" | "removed";
+        sourceKey: string;
+    }): void;
+    /** Publishes a committed Project Task fact using the caller's event key. */
+    taskChanged(input: {
+        tenantId: string;
+        roomId: string;
+        projectId: string;
+        taskId: string;
+        status: TaskItem["status"];
+        ownerMembershipId: string;
+        updatedAt: string;
+        sourceKey: string;
+    }): void;
+}
 
 declare class ChannelAdapterRegistry {
     private adapters;
@@ -62,6 +52,13 @@ interface MessageContext {
 }
 type MessageMiddleware = (ctx: MessageContext, next: () => Promise<void>) => Promise<void>;
 
+/** Non-serializable host capability required to enter internal Room routing. */
+declare const INTERNAL_ROOM_DISPATCH: unique symbol;
+/** Host-derived Room presence thread identity carried only under the symbol capability. */
+interface InternalRoomDispatchAuthority {
+    expectedRoomThreadId: string;
+}
+
 /**
  * Configuration for {@link MessageRouter}.
  *
@@ -75,6 +72,12 @@ interface MessageRouterConfig {
     bindingRegistry: BindingRegistry;
     adapterRegistry: ChannelAdapterRegistry;
     installationStore: ChannelInstallationStore;
+    trustedDispatcher?: TrustedAgentMessageDispatcher;
+}
+/** Host-trusted options for internal orchestration only. Public routes must not provide these. */
+interface InternalMessageDispatchOptions {
+    trustedMessageOptions?: TrustedMessageOptions;
+    [INTERNAL_ROOM_DISPATCH]?: InternalRoomDispatchAuthority;
 }
 /**
  * Core message router for external channel integration.
@@ -86,21 +89,10 @@ interface MessageRouterConfig {
  *
  * ## Reply flow
  *
- * The router uses a counter-based deduplication scheme on the internal
- * {@link Agent.reply:ready} event:
- *
- * 1. Before `agent.addMessage()`, it subscribes to `reply:ready` on the agent.
- * 2. Multiple concurrent dispatches on the same thread increment a counter;
- *    only the first registers the `EventEmitter.once` listener.
- * 3. When `reply:ready` fires, the callback extracts the last AI message from
- *    the LangGraph state and sends it via `ChannelAdapter.sendReply`.
- * 4. The counter is decremented; the subscription is only removed when the
- *    counter reaches 0.
- * 5. Stale subscriptions are cleaned up after a 1-hour timeout.
- *
- * The `replyTarget` is carried through by injecting `_replyTarget` into
- * `custom_run_config` on {@link Agent.addMessage}, and retrieved from the
- * `reply:ready` event payload.
+ * Each inbound input gets a unique ID before enqueue and an independent
+ * `reply:ready` subscription. Events are filtered by that ID, so concurrent
+ * inputs on one thread can complete in either order without cross-delivery.
+ * Subscriptions are removed on a matching event, enqueue failure, or timeout.
  *
  * @see {@link ChannelAdapter.sendReply}
  * @see {@link InboundMessage.replyTarget}
@@ -110,13 +102,8 @@ declare class MessageRouter {
     private bindingRegistry;
     private adapterRegistry;
     private installationStore;
-    /**
-     * Tracks reply subscriptions per thread+channel to avoid duplicate
-     * `subscribeOnce` registrations and ensure proper cleanup.
-     *
-     * Key format: `{threadId}:{adapterChannel}:reply`
-     */
-    private _replySubs;
+    private trustedDispatcher?;
+    private replySubscriptions;
     constructor(config: MessageRouterConfig);
     /**
      * Register an additional middleware at the end of the chain.
@@ -124,6 +111,15 @@ declare class MessageRouter {
      * @param middleware - A {@link MessageMiddleware} function
      */
     use(middleware: MessageMiddleware): void;
+    /**
+     * Releases every pending reply subscription owned by this router.
+     *
+     * Safe to call repeatedly during Gateway shutdown. Each subscription removes its exact Agent
+     * callback and timeout; in-flight Agent execution is not aborted.
+     *
+     * @returns Nothing.
+     */
+    dispose(): void;
     /**
      * Dispatch an inbound channel message to the bound agent.
      *
@@ -137,10 +133,381 @@ declare class MessageRouter {
      * @param message - Normalized inbound message from a channel adapter
      * @returns {@link DispatchResult} with success status, bindingId, and threadId
      */
-    dispatch(message: InboundMessage): Promise<DispatchResult>;
+    dispatch(message: InboundMessage, options?: InternalMessageDispatchOptions): Promise<DispatchResult>;
+    private dispatchInternal;
     private runMiddlewares;
 }
 
+type Listener = (event: ProjectRoomBusinessEvent) => void | Promise<void>;
+/** Construction options for the bounded process-local Project Room event broker. */
+interface ProjectRoomEventBrokerOptions {
+    epoch?: string;
+    now?: () => number;
+    maxEventsPerRoom?: number;
+    maxEventAgeMs?: number;
+    maxRooms?: number;
+    maxGlobalEvents?: number;
+    maxGlobalBytes?: number;
+    initialSequence?: number;
+    log?: {
+        warn(message: string, context: Record<string, unknown>): void;
+    };
+}
+/**
+ * Process-local, bounded Project Room replay and detached notification broker.
+ *
+ * Retention is intentionally ephemeral. Public operations perform maintenance;
+ * no room owns a timer or other background resource.
+ */
+declare class ProjectRoomEventBroker {
+    readonly epoch: string;
+    private readonly now;
+    private readonly maxEventsPerRoom;
+    private readonly maxEventAgeMs;
+    private readonly maxRooms;
+    private readonly maxGlobalEvents;
+    private readonly maxGlobalBytes;
+    private readonly log;
+    private readonly rooms;
+    private readonly sequenceScopes;
+    private sequence;
+    private eventCount;
+    private byteCount;
+    private subscriberCount;
+    private usageClock;
+    private closed;
+    constructor(options?: ProjectRoomEventBrokerOptions);
+    /** Number of currently registered subscriptions across all rooms. */
+    get activeSubscriberCount(): number;
+    /** Exact UTF-8 byte count of all retained serialized scoped events. */
+    get retainedBytes(): number;
+    /** Atomically stores an immutable event before queueing detached listener callbacks. */
+    publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft): ProjectRoomScopedBusinessEvent;
+    /** Atomically resolves replay and registers a distinct subscription for live events. */
+    subscribe(scope: ProjectRoomEventScope, afterEventId: string | undefined, listener: Listener): ProjectRoomEventSubscription;
+    /** Clears retained state, marks every subscription closed, and permanently closes the broker. */
+    close(): void;
+    private unsubscribe;
+    private queueCallback;
+    private planMaintenance;
+    private planRoomCapacity;
+    private planGlobalCapacity;
+    private inactiveRoomsByLru;
+    private inactiveRoomsForRoomEviction;
+    private remainingRoomCount;
+    private remainingEvents;
+    private planEventRemoval;
+    private planRoomRemoval;
+    private applyPlan;
+    private resolveCursor;
+    private currentTime;
+    private assertOpen;
+    private createRoom;
+    private touch;
+}
+
+/** Dependencies for a Project Room realtime connection. */
+interface ProjectRoomRealtimeServiceDependencies {
+    broker: ProjectRoomEventBroker;
+    requireReadAccess: (actor: ProjectRoomRealtimeActor, signal: AbortSignal) => Promise<void>;
+    log: {
+        warn(message: string, context: Record<string, unknown>): void;
+    };
+    now?: () => number;
+    authRecheckMs?: number;
+    heartbeatMs?: number;
+    maxTimerDelay?: number;
+    maxConnectionsPerUserProject?: number;
+}
+/** Orchestrates authenticated, resumable, bounded Project Room SSE connections. */
+declare class ProjectRoomRealtimeService {
+    private readonly deps;
+    private readonly connections;
+    private readonly now;
+    private readonly authRecheckMs;
+    private readonly heartbeatMs;
+    private closed;
+    private readonly activeConnections;
+    /** Creates a service using one process-local broker and read-only authorizer. */
+    constructor(deps: ProjectRoomRealtimeServiceDependencies);
+    /** Returns whether the actor's tenant/user/project stream quota has capacity. */
+    canConnect(actor: ProjectRoomRealtimeActor): boolean;
+    /** Starts a connection; authorization is assumed to have been performed by the route. */
+    connect(input: {
+        actor: ProjectRoomRealtimeActor;
+        roomId: string;
+        lastEventId?: string;
+        raw: ProjectRoomSseWritable;
+    }): void;
+    /** Closes every connection and prevents new connections. */
+    close(): void;
+}
+
+/**
+ * Publishes the sole realtime task invalidation for committed Project lifecycle notifications.
+ *
+ * Notifications are admitted synchronously into bounded, scope-keyed FIFO queues. Store work is
+ * detached from the Core lifecycle notifier and all failures are warning-only.
+ */
+declare class ProjectRoomTaskEventSubscriber {
+    private readonly deps;
+    private readonly queues;
+    private pendingCount;
+    private accepting;
+    private closed;
+    private readonly maxPending;
+    private readonly accepted;
+    /** Creates a bounded Project task lifecycle observer. */
+    constructor(deps: {
+        tasks: Pick<TaskStore, "getById">;
+        rooms: Pick<ProjectRoomStore, "getMainRoom">;
+        memberships: Pick<ProjectBotMembershipStore, "findByAssistant">;
+        realtime: Pick<ProjectRoomRealtimePublisher, "taskChanged">;
+        log: {
+            warn(message: string, context: Record<string, unknown>): void;
+        };
+        maxPending?: number;
+    });
+    /** Admits one notification without awaiting any store operation. */
+    handle(value: unknown): Promise<void>;
+    /** Closes admission without interrupting accepted work. */
+    closeAdmission(): void;
+    /** Drains accepted work, closing permanently if the bound expires. */
+    drain(timeoutMs?: number): Promise<void>;
+    /** Closes admission and drains accepted work. */
+    dispose(): Promise<void>;
+    private processQueue;
+    private publish;
+    private parse;
+    private warn;
+    private overflow;
+}
+
+/** App-owned Project Room realtime resources and lifecycle subscription. */
+declare class ProjectRoomRealtimeRuntime {
+    private readonly deps;
+    readonly broker: ProjectRoomEventBroker;
+    readonly publisher: ProjectRoomRealtimePublisher;
+    readonly service: ProjectRoomRealtimeService;
+    private readonly accepted;
+    private readonly unsubscribe;
+    private readonly shutdownTimeoutMs;
+    private closing?;
+    constructor(deps: {
+        broker: ProjectRoomEventBroker;
+        publisher: ProjectRoomRealtimePublisher;
+        service: ProjectRoomRealtimeService;
+        subscriber: Pick<ProjectRoomTaskEventSubscriber, "handle" | "closeAdmission" | "drain">;
+        subscribe(listener: TaskLifecycleListener): () => void;
+        log: {
+            warn(message: string, context: Record<string, unknown>): void;
+        };
+        shutdownTimeoutMs?: number;
+    });
+    /** Stops admission, drains accepted work, and closes transport resources exactly once. */
+    close(): Promise<void>;
+    private dispose;
+}
+
+/** Identifies one tenant-scoped Project task machine. */
+interface ProjectTaskMachineScope {
+    tenantId: string;
+    assistantId: string;
+    projectId: string;
+}
+/**
+ * Serializes Project task machine operations by tenant, Assistant, and Project.
+ *
+ * This mutex is process-local: callers must share one instance, and deployments
+ * with multiple Gateway processes need an external lease for cross-process
+ * exclusion. Acquisition is FIFO and intentionally non-reentrant; an operation
+ * must not await another acquisition of its own machine key. When an operation
+ * also needs the Project mutation mutex, it must acquire this machine mutex first.
+ */
+declare class ProjectTaskExecutionMutex {
+    private readonly queues;
+    private readonly active;
+    /**
+     * Runs an operation after all earlier operations for the same machine finish.
+     * A queued operation can be cancelled with `signal`; cancellation never aborts
+     * an operation that has already acquired the machine.
+     */
+    runExclusive<T>(scope: ProjectTaskMachineScope, operation: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Returns the number of operations waiting behind the current holder. */
+    pending(scope: ProjectTaskMachineScope): number;
+    private acquire;
+    private release;
+}
+
+/** Input required to resolve a canonical Project Task execution Thread. */
+interface EnsureProjectTaskThreadInput {
+    task: TaskItem;
+    room: ProjectRoom;
+    membership: ProjectBotMembership;
+    mode: "current_owner" | "reassignment";
+}
+/** Result of resolving or creating a canonical Project Task execution Thread. */
+interface EnsuredProjectTaskThread {
+    thread: Thread;
+    created: boolean;
+    /** True when a later task CAS loser can identify this newly created retained Thread as an orphan candidate. */
+    orphanCandidate: boolean;
+}
+/** Dependencies needed to resolve Project Task Threads. */
+interface ProjectTaskThreadServiceDependencies {
+    threads: Pick<ThreadStore, "getThreadById" | "createThread">;
+    idFactory: () => string;
+}
+/**
+ * Resolves an exact current-owner Thread or creates a new target-owned reassignment Thread.
+ *
+ * Generated IDs are read before creation because Thread stores may implement creation as an
+ * upsert. Every create is read back and validated; newly created Threads are intentionally retained.
+ */
+declare class ProjectTaskThreadService {
+    private readonly deps;
+    /** @param deps Thread persistence and unique-ID generation dependencies. */
+    constructor(deps: ProjectTaskThreadServiceDependencies);
+    /**
+     * Ensures a canonical Task execution Thread for the requested ownership mode.
+     *
+     * @param input Exact Task, room, membership, and ownership mode.
+     * @returns The validated canonical Thread and creation/orphan disposition.
+     */
+    ensure(input: EnsureProjectTaskThreadInput): Promise<EnsuredProjectTaskThread>;
+    private assertScope;
+    private assertThread;
+}
+
+/** Aggregate result of one bounded deterministic startup reconciliation. */
+interface ProjectTaskReconciliationResult {
+    inspected: number;
+    taskTruncated: boolean;
+    projectEnumerationTruncated: boolean;
+    projectionTruncated: boolean;
+    projectionWarnings: number;
+}
+
+/** Bounds applied while starting and stopping the process-owned Project Task runtime. */
+interface ProjectTaskRuntimeLifecycleOptions {
+    /** Soft admission deadline that aborts new reconciliation work while initiated work drains. */
+    deadlineMs?: number;
+}
+/** Process-owned Project Task observer, recovery, and execution lifecycle. */
+interface ProjectTaskRuntimeDisposal {
+    /** Whether every initiated operation drained before the bounded shutdown deadline. */
+    readonly drained: boolean;
+    /** Actual completion of every initiated operation, including work beyond the shutdown deadline. */
+    readonly drainPromise: Promise<void>;
+}
+/** Process-owned Project Task observer, recovery, and execution lifecycle. */
+interface ProjectTaskRuntime {
+    /** Shared process-local execution mutex used by HTTP reassignment and observer work. */
+    readonly mutex: ProjectTaskExecutionMutex;
+    /** Shared canonical Task Thread service. */
+    readonly threads: ProjectTaskThreadService;
+    /** Shared canonical Task lifecycle service. */
+    readonly lifecycle: TaskLifecycleService;
+    /** Starts or joins one bounded startup reconciliation. */
+    prepareReconciliation(options?: ProjectTaskRuntimeLifecycleOptions): Promise<ProjectTaskReconciliationResult>;
+    /** Aborts runtime work and returns bounded status plus the actual drain promise. */
+    dispose(): Promise<ProjectTaskRuntimeDisposal>;
+}
+/** Reference-counted handle to one process-owned Project Task runtime. */
+interface ProjectTaskRuntimeLease {
+    /** Shared runtime instance. */
+    readonly runtime: ProjectTaskRuntime;
+    /** Starts or joins the registry's single startup reconciliation. */
+    prepare(options?: ProjectTaskRuntimeLifecycleOptions): Promise<ProjectTaskReconciliationResult>;
+    /** Releases this handle; the final release disposes the runtime. */
+    release(): Promise<void>;
+}
+
+/**
+ * Channel infrastructure shared by inbound routing and internal room binding provisioning.
+ *
+ * @remarks All fields must reference the objects created by gateway startup; room provisioning
+ * must not construct a second registry or installation store.
+ */
+interface ChannelDependencies {
+    /** Message router used by channel ingress. */
+    router: MessageRouter;
+    /** Adapter registry used by channel ingress and installation lifecycle management. */
+    adapterRegistry: ChannelAdapterRegistry;
+    /** Tenant-scoped installation persistence used by routing and room provisioning. */
+    installationStore: ChannelInstallationStore;
+    /** Tenant-scoped binding persistence shared by routing and room provisioning. */
+    bindingRegistry: BindingRegistry;
+    /** Shared process-local Project Room realtime publisher. */
+    realtime?: ProjectRoomRealtimePublisher;
+    /** Structured warning sink for safe post-commit realtime callback failures. */
+    warn?: (message: string, context: Record<string, unknown>) => void;
+}
+/** Options controlling optional route-owned runtime composition. */
+interface LatticeRouteOptions {
+    /** Enables Project Task execution, notification observation, and startup recovery. */
+    projectTaskEnabled: boolean;
+    /** Structured warning sink used by background observation and projection repair. */
+    projectTaskLog: {
+        warn: (message: string, context: Record<string, unknown>) => void;
+    };
+    /** Optional app-owned runtime created before channel and route composition. */
+    projectRoomRealtimeRuntime: ProjectRoomRealtimeRuntime;
+}
+/** Optional runtime resources returned while registering the always-available HTTP routes. */
+interface LatticeRouteResult {
+    /** Present only when execution is enabled and every runtime dependency is available. */
+    projectTaskRuntime?: ProjectTaskRuntimeLease;
+    /** Stable missing capability or incompatible-runtime reason. */
+    projectTaskUnavailableReason?: string;
+    /** Present only in exact single-Gateway realtime mode. */
+    projectRoomRealtimeRuntime?: ProjectRoomRealtimeRuntime;
+}
+
+declare const defaultSwaggerConfig: {
+    openapi: {
+        openapi: string;
+        info: {
+            title: string;
+            description: string;
+            version: string;
+            contact: {
+                name: string;
+                email: string;
+            };
+        };
+        servers: {
+            url: string;
+            description: string;
+        }[];
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: "http";
+                    scheme: "bearer";
+                    bearerFormat: string;
+                };
+            };
+        };
+        security: {
+            bearerAuth: never[];
+        }[];
+        tags: {
+            name: string;
+            description: string;
+        }[];
+    };
+};
+declare const defaultSwaggerUiConfig: {
+    routePrefix: string;
+    uiConfig: {
+        docExpansion: "full";
+        deepLinking: boolean;
+    };
+    staticCSP: boolean;
+    transformStaticCSP: (header: string) => string;
+};
+
 type QueueServiceType = "memory" | "redis";
 
 interface AgentTaskRequest {
@@ -223,10 +590,7 @@ interface LatticeGatewayConfig {
 declare const LatticeGateway: {
     startAsHttpEndpoint: (config?: LatticeGatewayConfig) => Promise<void>;
     configureSwagger: (app: fastify.FastifyInstance, customSwaggerConfig?: Partial<typeof defaultSwaggerConfig>, customSwaggerUiConfig?: Partial<typeof defaultSwaggerUiConfig>) => Promise<void>;
-    registerLatticeRoutes: (app: fastify.FastifyInstance, channelDeps?: {
-        router: MessageRouter;
-        installationStore: ChannelInstallationStore;
-    }) => void;
+    registerLatticeRoutes: (app: fastify.FastifyInstance, channelDeps?: ChannelDependencies, options?: Partial<LatticeRouteOptions>) => LatticeRouteResult;
     app: fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault> & PromiseLike<fastify.FastifyInstance<http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>, http.IncomingMessage, http.ServerResponse<http.IncomingMessage>, fastify.FastifyBaseLogger, fastify.FastifyTypeProviderDefault>> & {
         __linterBrands: "SafePromiseLike";
     };