@axiom-lattice/gateway 10.1.0 → 10.2.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, ObservabilityDashboardInput, ObservabilityDashboardResult, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, PlatformSettingsProvider, PlatformSettingsStore, PlatformSettingsSnapshot, PlatformSettingsDocument, EffectivePlatformSettings, PlatformBrandingSettings, ResolvedPlatformBranding, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, ObservabilityDashboardInput, ObservabilityDashboardResult, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
 import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, AgentRunJsonObject, TrustedRunContext, AgentRunRecord, TaskLifecycleService, IAgentRunLedger, ObservabilityProvider, ObservabilityTraceContext, AppendLog, TaskLivenessProbe, TaskRunRegistry, AgentLifecycleTapEvent, AgentLifecycleEventName, AgentThreadInterface, AgentCheckpointTip, ExecuteRunInput, ExecuteRunResult, AgentRunSource, AgentRunStatus, ThreadRunLeaseHandle } from '@axiom-lattice/core';
 export { TaskLivenessProbe } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
@@ -56,6 +56,142 @@ interface ProjectRoomRealtimePublisher {
     }): void;
 }
 
+/** Outbox topic carrying cross-replica platform settings invalidation. */
+declare const PLATFORM_SETTINGS_CHANGED_TOPIC = "platform.settings.changed";
+/** Payload published when the settings document changes. */
+interface PlatformSettingsChangedEvent {
+    topic: typeof PLATFORM_SETTINGS_CHANGED_TOPIC;
+    version: number;
+}
+/** Best-effort publisher for a committed settings change. */
+type PlatformSettingsChangedPublisher = (event: PlatformSettingsChangedEvent) => Promise<void> | void;
+/** Receives a snapshot after a successful local update or reload. */
+type PlatformSettingsChangeListener = (snapshot: PlatformSettingsSnapshot) => void;
+/** Result of an update attempt, distinguishing a committed change from a no-op. */
+interface PlatformSettingsUpdateResult {
+    snapshot: PlatformSettingsSnapshot;
+    /** False when the merged document equals the current sanitized document. */
+    changed: boolean;
+}
+/** Sanitized branding settings plus their document version and audit metadata. */
+interface PlatformBrandingSettingsSnapshot {
+    version: number;
+    branding: PlatformBrandingSettings;
+    updatedBy?: string;
+    updatedAt?: Date;
+}
+/** Dependencies and optional side-effect hooks for the service. */
+interface PlatformSettingsServiceDeps {
+    store: PlatformSettingsStore;
+    env: Record<string, string | undefined>;
+    onChange?: PlatformSettingsChangeListener | PlatformSettingsChangeListener[];
+    publishChanged?: PlatformSettingsChangedPublisher;
+}
+/**
+ * Merges code defaults, environment fallbacks, and the persisted platform
+ * settings document into one cached, versioned effective snapshot.
+ *
+ * The service is the only layer that reads the settings environment variables;
+ * business code consumes the resolved values through the
+ * {@link PlatformSettingsProvider} interface.
+ *
+ * @example
+ * ```ts
+ * const service = new PlatformSettingsService({ store, env: process.env });
+ * await service.load();
+ * service.getEffective().auth.emailCompletionEnabled;
+ * ```
+ *
+ * @remarks
+ * - `load()` is non-throwing and falls back to defaults/env on startup failure.
+ * - `reload()` throws after a store failure but keeps the last good snapshot.
+ * - Writes use the store's version compare-and-swap and validate every field.
+ * - Notifying listeners and publishing the outbox event are best-effort.
+ */
+declare class PlatformSettingsService implements PlatformSettingsProvider {
+    private readonly store;
+    private readonly envLayer;
+    private readonly listeners;
+    private readonly publishChanged?;
+    private rawDocument;
+    private snapshot;
+    private lastError;
+    constructor(deps: PlatformSettingsServiceDeps);
+    /**
+     * Reads the persisted record and caches the effective snapshot.
+     *
+     * Never throws: a failure leaves the defaults/env snapshot in place and is
+     * exposed through {@link getLastError}.
+     */
+    load(): Promise<void>;
+    /**
+     * Reads the persisted record and caches the effective snapshot.
+     *
+     * The previous snapshot and raw document are preserved when the store read
+     * fails; the failure is re-thrown so the caller can log it.
+     */
+    reload(): Promise<void>;
+    /**
+     * Reloads the record, typically after a peer replica publishes a change.
+     */
+    invalidate(): Promise<void>;
+    /**
+     * Merges a patch over the current raw document, validates it, persists it
+     * with version compare-and-swap, then refreshes the cache.
+     *
+     * @param documentPatch Partial document to merge (undefined leaf removes an
+     * override).
+     * @param expectedVersion Version the caller last observed.
+     * @param updatedBy Optional admin identifier recorded on the row.
+     * @returns The new effective snapshot.
+     * @throws {PlatformSettingsValidationError} When a field is invalid.
+     * @throws {PlatformSettingsVersionConflictError} When the version is stale.
+     */
+    update(documentPatch: PlatformSettingsDocument, expectedVersion: number, updatedBy?: string): Promise<PlatformSettingsSnapshot>;
+    /**
+     * Like {@link update} but also reports whether anything was committed.
+     *
+     * A patch that merges back to the current sanitized document is a no-op: the
+     * version is not bumped and no listener, outbox event, or audit row fires.
+     */
+    updateWithResult(documentPatch: PlatformSettingsDocument, expectedVersion: number, updatedBy?: string): Promise<PlatformSettingsUpdateResult>;
+    /** Returns the cached effective settings and provenance. */
+    getSnapshot(): PlatformSettingsSnapshot;
+    /** Returns the cached effective settings. */
+    getEffective(): EffectivePlatformSettings;
+    /** Returns the cached invite defaults. */
+    getInviteDefaults(): EffectivePlatformSettings["invite"];
+    /** Returns the cached rate limit and quota values. */
+    getRateLimits(): EffectivePlatformSettings["rateLimits"];
+    /** Returns sanitized branding settings plus the document version metadata. */
+    getBrandingSettings(): PlatformBrandingSettingsSnapshot;
+    /**
+     * Resolves the branding for a request host.
+     *
+     * The host is normalized (lowercase, no port, no trailing dot) and matched
+     * exactly against configured domains. Domain branding is merged over the
+     * platform default; unknown hosts get the default brand.
+     */
+    getBrandingForHost(host: string): ResolvedPlatformBranding;
+    /** Registers a listener invoked after a successful update or reload. */
+    onChange(listener: PlatformSettingsChangeListener): void;
+    /** Returns the last store failure observed by `load()`, if any. */
+    getLastError(): unknown;
+    private read;
+    /**
+     * Replaces the cache from a store record.
+     *
+     * Never regresses on an older version so a delayed or duplicated outbox
+     * event cannot roll the snapshot (or raw document) backwards.
+     *
+     * @returns Whether the effective version changed.
+     */
+    private applyRecord;
+    private buildSnapshot;
+    private notify;
+    private publish;
+}
+
 declare class ChannelAdapterRegistry {
     private adapters;
     register(adapter: ChannelAdapter): void;
@@ -1423,6 +1559,14 @@ interface LatticeRouteResult {
     projectRoomRealtimeRuntime?: ProjectRoomRealtimeRuntime;
     /** Always-present controller used by the outbox poller to reconcile foreign changes. */
     modelProviderController: ModelProviderController;
+    /** Process-wide settings service used by the outbox poller to invalidate peers. */
+    platformSettingsService: PlatformSettingsService;
+    /**
+     * Resolves once the deployment-level OIDC guard has evaluated env and
+     * store-backed providers. Callers should await it before listening so a
+     * misconfigured deployment fails startup.
+     */
+    oidcDeploymentGuard?: Promise<void>;
 }
 
 declare const defaultSwaggerConfig: {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, ObservabilityDashboardInput, ObservabilityDashboardResult, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, PlatformSettingsProvider, PlatformSettingsStore, PlatformSettingsSnapshot, PlatformSettingsDocument, EffectivePlatformSettings, PlatformBrandingSettings, ResolvedPlatformBranding, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, ObservabilityDashboardInput, ObservabilityDashboardResult, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
 import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, AgentRunJsonObject, TrustedRunContext, AgentRunRecord, TaskLifecycleService, IAgentRunLedger, ObservabilityProvider, ObservabilityTraceContext, AppendLog, TaskLivenessProbe, TaskRunRegistry, AgentLifecycleTapEvent, AgentLifecycleEventName, AgentThreadInterface, AgentCheckpointTip, ExecuteRunInput, ExecuteRunResult, AgentRunSource, AgentRunStatus, ThreadRunLeaseHandle } from '@axiom-lattice/core';
 export { TaskLivenessProbe } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
@@ -56,6 +56,142 @@ interface ProjectRoomRealtimePublisher {
     }): void;
 }
 
+/** Outbox topic carrying cross-replica platform settings invalidation. */
+declare const PLATFORM_SETTINGS_CHANGED_TOPIC = "platform.settings.changed";
+/** Payload published when the settings document changes. */
+interface PlatformSettingsChangedEvent {
+    topic: typeof PLATFORM_SETTINGS_CHANGED_TOPIC;
+    version: number;
+}
+/** Best-effort publisher for a committed settings change. */
+type PlatformSettingsChangedPublisher = (event: PlatformSettingsChangedEvent) => Promise<void> | void;
+/** Receives a snapshot after a successful local update or reload. */
+type PlatformSettingsChangeListener = (snapshot: PlatformSettingsSnapshot) => void;
+/** Result of an update attempt, distinguishing a committed change from a no-op. */
+interface PlatformSettingsUpdateResult {
+    snapshot: PlatformSettingsSnapshot;
+    /** False when the merged document equals the current sanitized document. */
+    changed: boolean;
+}
+/** Sanitized branding settings plus their document version and audit metadata. */
+interface PlatformBrandingSettingsSnapshot {
+    version: number;
+    branding: PlatformBrandingSettings;
+    updatedBy?: string;
+    updatedAt?: Date;
+}
+/** Dependencies and optional side-effect hooks for the service. */
+interface PlatformSettingsServiceDeps {
+    store: PlatformSettingsStore;
+    env: Record<string, string | undefined>;
+    onChange?: PlatformSettingsChangeListener | PlatformSettingsChangeListener[];
+    publishChanged?: PlatformSettingsChangedPublisher;
+}
+/**
+ * Merges code defaults, environment fallbacks, and the persisted platform
+ * settings document into one cached, versioned effective snapshot.
+ *
+ * The service is the only layer that reads the settings environment variables;
+ * business code consumes the resolved values through the
+ * {@link PlatformSettingsProvider} interface.
+ *
+ * @example
+ * ```ts
+ * const service = new PlatformSettingsService({ store, env: process.env });
+ * await service.load();
+ * service.getEffective().auth.emailCompletionEnabled;
+ * ```
+ *
+ * @remarks
+ * - `load()` is non-throwing and falls back to defaults/env on startup failure.
+ * - `reload()` throws after a store failure but keeps the last good snapshot.
+ * - Writes use the store's version compare-and-swap and validate every field.
+ * - Notifying listeners and publishing the outbox event are best-effort.
+ */
+declare class PlatformSettingsService implements PlatformSettingsProvider {
+    private readonly store;
+    private readonly envLayer;
+    private readonly listeners;
+    private readonly publishChanged?;
+    private rawDocument;
+    private snapshot;
+    private lastError;
+    constructor(deps: PlatformSettingsServiceDeps);
+    /**
+     * Reads the persisted record and caches the effective snapshot.
+     *
+     * Never throws: a failure leaves the defaults/env snapshot in place and is
+     * exposed through {@link getLastError}.
+     */
+    load(): Promise<void>;
+    /**
+     * Reads the persisted record and caches the effective snapshot.
+     *
+     * The previous snapshot and raw document are preserved when the store read
+     * fails; the failure is re-thrown so the caller can log it.
+     */
+    reload(): Promise<void>;
+    /**
+     * Reloads the record, typically after a peer replica publishes a change.
+     */
+    invalidate(): Promise<void>;
+    /**
+     * Merges a patch over the current raw document, validates it, persists it
+     * with version compare-and-swap, then refreshes the cache.
+     *
+     * @param documentPatch Partial document to merge (undefined leaf removes an
+     * override).
+     * @param expectedVersion Version the caller last observed.
+     * @param updatedBy Optional admin identifier recorded on the row.
+     * @returns The new effective snapshot.
+     * @throws {PlatformSettingsValidationError} When a field is invalid.
+     * @throws {PlatformSettingsVersionConflictError} When the version is stale.
+     */
+    update(documentPatch: PlatformSettingsDocument, expectedVersion: number, updatedBy?: string): Promise<PlatformSettingsSnapshot>;
+    /**
+     * Like {@link update} but also reports whether anything was committed.
+     *
+     * A patch that merges back to the current sanitized document is a no-op: the
+     * version is not bumped and no listener, outbox event, or audit row fires.
+     */
+    updateWithResult(documentPatch: PlatformSettingsDocument, expectedVersion: number, updatedBy?: string): Promise<PlatformSettingsUpdateResult>;
+    /** Returns the cached effective settings and provenance. */
+    getSnapshot(): PlatformSettingsSnapshot;
+    /** Returns the cached effective settings. */
+    getEffective(): EffectivePlatformSettings;
+    /** Returns the cached invite defaults. */
+    getInviteDefaults(): EffectivePlatformSettings["invite"];
+    /** Returns the cached rate limit and quota values. */
+    getRateLimits(): EffectivePlatformSettings["rateLimits"];
+    /** Returns sanitized branding settings plus the document version metadata. */
+    getBrandingSettings(): PlatformBrandingSettingsSnapshot;
+    /**
+     * Resolves the branding for a request host.
+     *
+     * The host is normalized (lowercase, no port, no trailing dot) and matched
+     * exactly against configured domains. Domain branding is merged over the
+     * platform default; unknown hosts get the default brand.
+     */
+    getBrandingForHost(host: string): ResolvedPlatformBranding;
+    /** Registers a listener invoked after a successful update or reload. */
+    onChange(listener: PlatformSettingsChangeListener): void;
+    /** Returns the last store failure observed by `load()`, if any. */
+    getLastError(): unknown;
+    private read;
+    /**
+     * Replaces the cache from a store record.
+     *
+     * Never regresses on an older version so a delayed or duplicated outbox
+     * event cannot roll the snapshot (or raw document) backwards.
+     *
+     * @returns Whether the effective version changed.
+     */
+    private applyRecord;
+    private buildSnapshot;
+    private notify;
+    private publish;
+}
+
 declare class ChannelAdapterRegistry {
     private adapters;
     register(adapter: ChannelAdapter): void;
@@ -1423,6 +1559,14 @@ interface LatticeRouteResult {
     projectRoomRealtimeRuntime?: ProjectRoomRealtimeRuntime;
     /** Always-present controller used by the outbox poller to reconcile foreign changes. */
     modelProviderController: ModelProviderController;
+    /** Process-wide settings service used by the outbox poller to invalidate peers. */
+    platformSettingsService: PlatformSettingsService;
+    /**
+     * Resolves once the deployment-level OIDC guard has evaluated env and
+     * store-backed providers. Callers should await it before listening so a
+     * misconfigured deployment fails startup.
+     */
+    oidcDeploymentGuard?: Promise<void>;
 }
 
 declare const defaultSwaggerConfig: {