@cadenza.io/service 2.15.0 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,6 +1,7 @@
1
1
  import * as _cadenza_io_core from '@cadenza.io/core';
2
2
  import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, Actor, TaskOptions, ActorSpec, ActorFactoryOptions, ActorDefinition, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
3
3
  export { Actor, ActorConsistencyProfileName, ActorDefinition, ActorFactoryOptions, ActorInvocationOptions, ActorKeyDefinition, ActorKind, ActorLoadPolicy, ActorRuntimeReadGuard, ActorSpec, ActorStateDefinition, ActorStateReducer, ActorStateStore, ActorTaskBindingDefinition, ActorTaskBindingOptions, ActorTaskContext, ActorTaskHandler, ActorTaskMode, ActorWriteContract, AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, IdempotencyPolicy, RetryPolicy, SessionPolicy, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
4
+ import { Pool } from 'pg';
4
5
 
5
6
  /**
6
7
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -201,28 +202,13 @@ type DistributedInquiryOptions = Partial<InquiryOptions> & {
201
202
  * Mainly used by distributed deputy responders.
202
203
  */
203
204
  perResponderTimeoutMs?: number;
205
+ /**
206
+ * Optional hydration cache key used to consume one SSR-provided inquiry result
207
+ * before the live frontend runtime performs normal distributed routing.
208
+ */
209
+ hydrationKey?: string;
204
210
  };
205
211
 
206
- type RuntimeStatusState = "healthy" | "degraded" | "overloaded" | "unavailable";
207
-
208
- interface ServiceInstanceDescriptor {
209
- uuid: string;
210
- address: string;
211
- port: number;
212
- serviceName: string;
213
- numberOfRunningGraphs?: number;
214
- isPrimary: boolean;
215
- isActive: boolean;
216
- isNonResponsive: boolean;
217
- isBlocked: boolean;
218
- runtimeState?: RuntimeStatusState;
219
- acceptingWork?: boolean;
220
- reportedAt?: string;
221
- health: AnyObject;
222
- exposed: boolean;
223
- clientCreated?: boolean;
224
- isFrontend: boolean;
225
- }
226
212
  interface DeputyDescriptor {
227
213
  serviceName: string;
228
214
  remoteRoutineName?: string;
@@ -265,7 +251,9 @@ declare class ServiceRegistry {
265
251
  numberOfRunningGraphs: number;
266
252
  useSocket: boolean;
267
253
  retryCount: number;
254
+ isFrontend: boolean;
268
255
  handleInstanceUpdateTask: Task;
256
+ handleTransportUpdateTask: Task;
269
257
  handleGlobalSignalRegistrationTask: Task;
270
258
  handleGlobalIntentRegistrationTask: Task;
271
259
  handleSocketStatusUpdateTask: Task;
@@ -280,6 +268,7 @@ declare class ServiceRegistry {
280
268
  getStatusTask: Task;
281
269
  insertServiceTask: Task;
282
270
  insertServiceInstanceTask: Task;
271
+ insertServiceTransportTask: Task;
283
272
  handleServiceNotRespondingTask: Task;
284
273
  handleServiceHandshakeTask: Task;
285
274
  collectTransportDiagnosticsTask: Task;
@@ -291,6 +280,12 @@ declare class ServiceRegistry {
291
280
  getInquiryResponderDescriptor(task: Task): InquiryResponderDescriptor;
292
281
  private getInstance;
293
282
  private getLocalInstance;
283
+ private getRoutingTransportRole;
284
+ private getTransportById;
285
+ private getRouteableTransport;
286
+ private getTransportClientKey;
287
+ private hasTransportClientCreated;
288
+ private markTransportClientCreated;
294
289
  private registerDependee;
295
290
  private unregisterDependee;
296
291
  private getHeartbeatMisses;
@@ -481,6 +476,44 @@ interface DatabaseSchemaDefinition {
481
476
  };
482
477
  }
483
478
 
479
+ interface BootstrapOptions {
480
+ url?: string;
481
+ injectedGlobalKey?: string;
482
+ }
483
+ interface HydrationOptions {
484
+ initialInquiryResults?: Record<string, unknown>;
485
+ }
486
+ interface ResolvedBootstrapEndpoint {
487
+ url: string;
488
+ protocol: "http" | "https";
489
+ address: string;
490
+ port: number;
491
+ exposed: boolean;
492
+ injectedGlobalKey: string;
493
+ }
494
+
495
+ type ServiceTransportRole = "internal" | "public";
496
+ type ServiceTransportProtocol = "rest" | "socket";
497
+ type ServiceTransportSecurityProfile = "low" | "medium" | "high";
498
+ interface ServiceTransportConfig {
499
+ role: ServiceTransportRole;
500
+ origin: string;
501
+ protocols?: ServiceTransportProtocol[];
502
+ securityProfile?: ServiceTransportSecurityProfile | null;
503
+ authStrategy?: string | null;
504
+ }
505
+ interface ServiceTransportDescriptor {
506
+ uuid: string;
507
+ serviceInstanceId: string;
508
+ role: ServiceTransportRole;
509
+ origin: string;
510
+ protocols: ServiceTransportProtocol[];
511
+ securityProfile: ServiceTransportSecurityProfile | null;
512
+ authStrategy: string | null;
513
+ deleted?: boolean;
514
+ clientCreated?: boolean;
515
+ }
516
+
484
517
  type SecurityProfile = "low" | "medium" | "high";
485
518
  type NetworkMode = "internal" | "exposed" | "exposed-high-sec" | "auto" | "dev";
486
519
  type ServerOptions = {
@@ -499,6 +532,9 @@ type ServerOptions = {
499
532
  address?: string;
500
533
  port?: number;
501
534
  };
535
+ bootstrap?: BootstrapOptions;
536
+ hydration?: HydrationOptions;
537
+ transports?: ServiceTransportConfig[];
502
538
  relatedServices?: string[][];
503
539
  isDatabase?: boolean;
504
540
  isFrontend?: boolean;
@@ -523,6 +559,8 @@ declare class CadenzaService {
523
559
  protected static isBootstrapped: boolean;
524
560
  protected static serviceCreated: boolean;
525
561
  protected static warnedInvalidMetaIntentResponderKeys: Set<string>;
562
+ protected static hydratedInquiryResults: Map<string, AnyObject>;
563
+ protected static frontendSyncScheduled: boolean;
526
564
  /**
527
565
  * Initializes the application by setting up necessary components and configurations.
528
566
  * This method ensures the initialization process is only executed once throughout the application lifecycle.
@@ -530,6 +568,12 @@ declare class CadenzaService {
530
568
  * @return {void} This method does not return any value.
531
569
  */
532
570
  static bootstrap(): void;
571
+ private static ensureTransportControllers;
572
+ private static setHydrationResults;
573
+ private static consumeHydratedInquiryResult;
574
+ private static ensureFrontendSyncLoop;
575
+ private static normalizeDeclaredTransports;
576
+ private static createBootstrapTransport;
533
577
  /**
534
578
  * Validates the provided service name based on specific rules.
535
579
  *
@@ -22915,7 +22959,6 @@ declare class SocketController {
22915
22959
  private registerSocketClientTasks;
22916
22960
  private resolveSocketServerKey;
22917
22961
  private resolveSocketClientFetchId;
22918
- private resolveServicePort;
22919
22962
  private createSocketServerRuntimeHandleFromContext;
22920
22963
  private destroySocketServerRuntimeHandle;
22921
22964
  private createSocketClientRuntimeHandle;
@@ -22965,4 +23008,135 @@ declare class SignalController {
22965
23008
  constructor();
22966
23009
  }
22967
23010
 
22968
- export { type AggregateDefinition, type AggregateFunction, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };
23011
+ interface PostgresActorSafetyPolicy {
23012
+ statementTimeoutMs: number;
23013
+ retryCount: number;
23014
+ retryDelayMs: number;
23015
+ retryDelayMaxMs: number;
23016
+ retryDelayFactor: number;
23017
+ }
23018
+ interface PostgresActorDurableState {
23019
+ actorName: string;
23020
+ actorToken: string;
23021
+ ownerServiceName: string | null;
23022
+ databaseName: string;
23023
+ status: "idle" | "initializing" | "ready" | "error";
23024
+ schemaVersion: number;
23025
+ setupStartedAt: string | null;
23026
+ setupCompletedAt: string | null;
23027
+ lastHealthCheckAt: string | null;
23028
+ lastError: string | null;
23029
+ tables: string[];
23030
+ safetyPolicy: PostgresActorSafetyPolicy;
23031
+ }
23032
+ interface PostgresActorRuntimeState {
23033
+ pool: Pool | null;
23034
+ ready: boolean;
23035
+ pendingQueries: number;
23036
+ lastHealthCheckAt: number | null;
23037
+ lastError: string | null;
23038
+ }
23039
+ interface PostgresActorRegistration {
23040
+ ownerServiceName: string | null;
23041
+ databaseName: string;
23042
+ actorName: string;
23043
+ actorToken: string;
23044
+ actorKey: string;
23045
+ setupSignal: string;
23046
+ setupDoneSignal: string;
23047
+ setupFailedSignal: string;
23048
+ actor: Actor<PostgresActorDurableState, PostgresActorRuntimeState>;
23049
+ schema: DatabaseSchemaDefinition;
23050
+ description: string;
23051
+ options: ServerOptions & DatabaseOptions;
23052
+ tasksGenerated: boolean;
23053
+ intentNames: Set<string>;
23054
+ }
23055
+ /**
23056
+ * DatabaseController now acts as a PostgresActor plugin coordinator.
23057
+ *
23058
+ * Runtime ownership lives in actor runtime state (Pool + runtime health counters).
23059
+ * Durable actor state stores setup/configuration/health snapshots.
23060
+ */
23061
+ declare class DatabaseController {
23062
+ private static _instance;
23063
+ static get instance(): DatabaseController;
23064
+ private readonly registrationsByActorName;
23065
+ private readonly registrationsByActorToken;
23066
+ private readonly adminDbClient;
23067
+ constructor();
23068
+ reset(): void;
23069
+ createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description: string, options: ServerOptions & DatabaseOptions): PostgresActorRegistration;
23070
+ requestPostgresActorSetup(registrationOrName: PostgresActorRegistration | string, ctx?: AnyObject): PostgresActorRegistration | undefined;
23071
+ private resolveRegistration;
23072
+ private emitSetupDone;
23073
+ private registerSetupTask;
23074
+ private createTargetPool;
23075
+ private buildDatabaseConnectionString;
23076
+ private createDatabaseIfMissing;
23077
+ private checkPoolHealth;
23078
+ private getPoolOrThrow;
23079
+ private withTimeout;
23080
+ private runWithRetries;
23081
+ private executeWithTransaction;
23082
+ private queryFunction;
23083
+ private insertFunction;
23084
+ private updateFunction;
23085
+ private deleteFunction;
23086
+ private resolveSafetyPolicy;
23087
+ private buildOnConflictClause;
23088
+ /**
23089
+ * Validates database schema structure and content.
23090
+ */
23091
+ validateSchema(ctx: AnyObject): true;
23092
+ sortTablesByReferences(ctx: AnyObject): AnyObject;
23093
+ private buildSchemaDdlStatements;
23094
+ private fieldDefinitionToSql;
23095
+ private applyDdlStatements;
23096
+ private generateDatabaseTasks;
23097
+ private createDatabaseMacroTasks;
23098
+ private createDatabaseTask;
23099
+ private validateOperationPayload;
23100
+ private validateJoinPayload;
23101
+ toCamelCase(rows: any[]): any[];
23102
+ buildWhereClause(filter: AnyObject, params: any[]): string;
23103
+ buildJoinClause(joins: Record<string, JoinDefinition>): string;
23104
+ resolveNestedData(registration: PostgresActorRegistration, data: any, tableName: string): Promise<any>;
23105
+ executeSubOperation(registration: PostgresActorRegistration, operation: SubOperation): Promise<any>;
23106
+ private getInputSchema;
23107
+ }
23108
+
23109
+ interface SSRInquiryBridgeOptions {
23110
+ bootstrap?: BootstrapOptions;
23111
+ cadenzaDB?: {
23112
+ address?: string;
23113
+ port?: number;
23114
+ };
23115
+ }
23116
+ interface SSRInquiryBridge {
23117
+ inquire: (inquiry: string, context?: AnyObject, options?: DistributedInquiryOptions) => Promise<AnyObject>;
23118
+ dehydrate: () => HydrationOptions;
23119
+ }
23120
+ declare function createSSRInquiryBridge(options?: SSRInquiryBridgeOptions): SSRInquiryBridge;
23121
+
23122
+ type RuntimeStatusState = "healthy" | "degraded" | "overloaded" | "unavailable";
23123
+
23124
+ interface ServiceInstanceDescriptor {
23125
+ uuid: string;
23126
+ serviceName: string;
23127
+ numberOfRunningGraphs?: number;
23128
+ isPrimary: boolean;
23129
+ isActive: boolean;
23130
+ isNonResponsive: boolean;
23131
+ isBlocked: boolean;
23132
+ runtimeState?: RuntimeStatusState;
23133
+ acceptingWork?: boolean;
23134
+ reportedAt?: string;
23135
+ health: AnyObject;
23136
+ isFrontend: boolean;
23137
+ isDatabase?: boolean;
23138
+ transports: ServiceTransportDescriptor[];
23139
+ clientCreatedTransportIds?: string[];
23140
+ }
23141
+
23142
+ export { type AggregateDefinition, type AggregateFunction, type BootstrapOptions, DatabaseController, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type HydrationOptions, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, type ResolvedBootstrapEndpoint, RestController, type SSRInquiryBridge, type SSRInquiryBridgeOptions, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, type ServiceTransportConfig, type ServiceTransportDescriptor, type ServiceTransportProtocol, type ServiceTransportRole, type ServiceTransportSecurityProfile, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, createSSRInquiryBridge, CadenzaService as default };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import * as _cadenza_io_core from '@cadenza.io/core';
2
2
  import { Task, ThrottleTagGetter, Schema, GraphContext, AnyObject, InquiryOptions, TaskResult, GraphRoutine, SchemaDefinition, SignalBroker, InquiryBroker, GraphRunner, GraphRegistry, EmitOptions, CadenzaMode, Intent, Actor, TaskOptions, ActorSpec, ActorFactoryOptions, ActorDefinition, TaskFunction, DebounceOptions, DebounceTask, EphemeralTaskOptions, EphemeralTask } from '@cadenza.io/core';
3
3
  export { Actor, ActorConsistencyProfileName, ActorDefinition, ActorFactoryOptions, ActorInvocationOptions, ActorKeyDefinition, ActorKind, ActorLoadPolicy, ActorRuntimeReadGuard, ActorSpec, ActorStateDefinition, ActorStateReducer, ActorStateStore, ActorTaskBindingDefinition, ActorTaskBindingOptions, ActorTaskContext, ActorTaskHandler, ActorTaskMode, ActorWriteContract, AnyObject, DebounceOptions, DebounceTask, EphemeralTask, EphemeralTaskOptions, GraphRoutine, IdempotencyPolicy, RetryPolicy, SessionPolicy, Task, TaskFunction, TaskOptions, ThrottleTagGetter } from '@cadenza.io/core';
4
+ import { Pool } from 'pg';
4
5
 
5
6
  /**
6
7
  * Represents a task that delegates execution of a routine to a remote system or service.
@@ -201,28 +202,13 @@ type DistributedInquiryOptions = Partial<InquiryOptions> & {
201
202
  * Mainly used by distributed deputy responders.
202
203
  */
203
204
  perResponderTimeoutMs?: number;
205
+ /**
206
+ * Optional hydration cache key used to consume one SSR-provided inquiry result
207
+ * before the live frontend runtime performs normal distributed routing.
208
+ */
209
+ hydrationKey?: string;
204
210
  };
205
211
 
206
- type RuntimeStatusState = "healthy" | "degraded" | "overloaded" | "unavailable";
207
-
208
- interface ServiceInstanceDescriptor {
209
- uuid: string;
210
- address: string;
211
- port: number;
212
- serviceName: string;
213
- numberOfRunningGraphs?: number;
214
- isPrimary: boolean;
215
- isActive: boolean;
216
- isNonResponsive: boolean;
217
- isBlocked: boolean;
218
- runtimeState?: RuntimeStatusState;
219
- acceptingWork?: boolean;
220
- reportedAt?: string;
221
- health: AnyObject;
222
- exposed: boolean;
223
- clientCreated?: boolean;
224
- isFrontend: boolean;
225
- }
226
212
  interface DeputyDescriptor {
227
213
  serviceName: string;
228
214
  remoteRoutineName?: string;
@@ -265,7 +251,9 @@ declare class ServiceRegistry {
265
251
  numberOfRunningGraphs: number;
266
252
  useSocket: boolean;
267
253
  retryCount: number;
254
+ isFrontend: boolean;
268
255
  handleInstanceUpdateTask: Task;
256
+ handleTransportUpdateTask: Task;
269
257
  handleGlobalSignalRegistrationTask: Task;
270
258
  handleGlobalIntentRegistrationTask: Task;
271
259
  handleSocketStatusUpdateTask: Task;
@@ -280,6 +268,7 @@ declare class ServiceRegistry {
280
268
  getStatusTask: Task;
281
269
  insertServiceTask: Task;
282
270
  insertServiceInstanceTask: Task;
271
+ insertServiceTransportTask: Task;
283
272
  handleServiceNotRespondingTask: Task;
284
273
  handleServiceHandshakeTask: Task;
285
274
  collectTransportDiagnosticsTask: Task;
@@ -291,6 +280,12 @@ declare class ServiceRegistry {
291
280
  getInquiryResponderDescriptor(task: Task): InquiryResponderDescriptor;
292
281
  private getInstance;
293
282
  private getLocalInstance;
283
+ private getRoutingTransportRole;
284
+ private getTransportById;
285
+ private getRouteableTransport;
286
+ private getTransportClientKey;
287
+ private hasTransportClientCreated;
288
+ private markTransportClientCreated;
294
289
  private registerDependee;
295
290
  private unregisterDependee;
296
291
  private getHeartbeatMisses;
@@ -481,6 +476,44 @@ interface DatabaseSchemaDefinition {
481
476
  };
482
477
  }
483
478
 
479
+ interface BootstrapOptions {
480
+ url?: string;
481
+ injectedGlobalKey?: string;
482
+ }
483
+ interface HydrationOptions {
484
+ initialInquiryResults?: Record<string, unknown>;
485
+ }
486
+ interface ResolvedBootstrapEndpoint {
487
+ url: string;
488
+ protocol: "http" | "https";
489
+ address: string;
490
+ port: number;
491
+ exposed: boolean;
492
+ injectedGlobalKey: string;
493
+ }
494
+
495
+ type ServiceTransportRole = "internal" | "public";
496
+ type ServiceTransportProtocol = "rest" | "socket";
497
+ type ServiceTransportSecurityProfile = "low" | "medium" | "high";
498
+ interface ServiceTransportConfig {
499
+ role: ServiceTransportRole;
500
+ origin: string;
501
+ protocols?: ServiceTransportProtocol[];
502
+ securityProfile?: ServiceTransportSecurityProfile | null;
503
+ authStrategy?: string | null;
504
+ }
505
+ interface ServiceTransportDescriptor {
506
+ uuid: string;
507
+ serviceInstanceId: string;
508
+ role: ServiceTransportRole;
509
+ origin: string;
510
+ protocols: ServiceTransportProtocol[];
511
+ securityProfile: ServiceTransportSecurityProfile | null;
512
+ authStrategy: string | null;
513
+ deleted?: boolean;
514
+ clientCreated?: boolean;
515
+ }
516
+
484
517
  type SecurityProfile = "low" | "medium" | "high";
485
518
  type NetworkMode = "internal" | "exposed" | "exposed-high-sec" | "auto" | "dev";
486
519
  type ServerOptions = {
@@ -499,6 +532,9 @@ type ServerOptions = {
499
532
  address?: string;
500
533
  port?: number;
501
534
  };
535
+ bootstrap?: BootstrapOptions;
536
+ hydration?: HydrationOptions;
537
+ transports?: ServiceTransportConfig[];
502
538
  relatedServices?: string[][];
503
539
  isDatabase?: boolean;
504
540
  isFrontend?: boolean;
@@ -523,6 +559,8 @@ declare class CadenzaService {
523
559
  protected static isBootstrapped: boolean;
524
560
  protected static serviceCreated: boolean;
525
561
  protected static warnedInvalidMetaIntentResponderKeys: Set<string>;
562
+ protected static hydratedInquiryResults: Map<string, AnyObject>;
563
+ protected static frontendSyncScheduled: boolean;
526
564
  /**
527
565
  * Initializes the application by setting up necessary components and configurations.
528
566
  * This method ensures the initialization process is only executed once throughout the application lifecycle.
@@ -530,6 +568,12 @@ declare class CadenzaService {
530
568
  * @return {void} This method does not return any value.
531
569
  */
532
570
  static bootstrap(): void;
571
+ private static ensureTransportControllers;
572
+ private static setHydrationResults;
573
+ private static consumeHydratedInquiryResult;
574
+ private static ensureFrontendSyncLoop;
575
+ private static normalizeDeclaredTransports;
576
+ private static createBootstrapTransport;
533
577
  /**
534
578
  * Validates the provided service name based on specific rules.
535
579
  *
@@ -22915,7 +22959,6 @@ declare class SocketController {
22915
22959
  private registerSocketClientTasks;
22916
22960
  private resolveSocketServerKey;
22917
22961
  private resolveSocketClientFetchId;
22918
- private resolveServicePort;
22919
22962
  private createSocketServerRuntimeHandleFromContext;
22920
22963
  private destroySocketServerRuntimeHandle;
22921
22964
  private createSocketClientRuntimeHandle;
@@ -22965,4 +23008,135 @@ declare class SignalController {
22965
23008
  constructor();
22966
23009
  }
22967
23010
 
22968
- export { type AggregateDefinition, type AggregateFunction, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, RestController, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, CadenzaService as default };
23011
+ interface PostgresActorSafetyPolicy {
23012
+ statementTimeoutMs: number;
23013
+ retryCount: number;
23014
+ retryDelayMs: number;
23015
+ retryDelayMaxMs: number;
23016
+ retryDelayFactor: number;
23017
+ }
23018
+ interface PostgresActorDurableState {
23019
+ actorName: string;
23020
+ actorToken: string;
23021
+ ownerServiceName: string | null;
23022
+ databaseName: string;
23023
+ status: "idle" | "initializing" | "ready" | "error";
23024
+ schemaVersion: number;
23025
+ setupStartedAt: string | null;
23026
+ setupCompletedAt: string | null;
23027
+ lastHealthCheckAt: string | null;
23028
+ lastError: string | null;
23029
+ tables: string[];
23030
+ safetyPolicy: PostgresActorSafetyPolicy;
23031
+ }
23032
+ interface PostgresActorRuntimeState {
23033
+ pool: Pool | null;
23034
+ ready: boolean;
23035
+ pendingQueries: number;
23036
+ lastHealthCheckAt: number | null;
23037
+ lastError: string | null;
23038
+ }
23039
+ interface PostgresActorRegistration {
23040
+ ownerServiceName: string | null;
23041
+ databaseName: string;
23042
+ actorName: string;
23043
+ actorToken: string;
23044
+ actorKey: string;
23045
+ setupSignal: string;
23046
+ setupDoneSignal: string;
23047
+ setupFailedSignal: string;
23048
+ actor: Actor<PostgresActorDurableState, PostgresActorRuntimeState>;
23049
+ schema: DatabaseSchemaDefinition;
23050
+ description: string;
23051
+ options: ServerOptions & DatabaseOptions;
23052
+ tasksGenerated: boolean;
23053
+ intentNames: Set<string>;
23054
+ }
23055
+ /**
23056
+ * DatabaseController now acts as a PostgresActor plugin coordinator.
23057
+ *
23058
+ * Runtime ownership lives in actor runtime state (Pool + runtime health counters).
23059
+ * Durable actor state stores setup/configuration/health snapshots.
23060
+ */
23061
+ declare class DatabaseController {
23062
+ private static _instance;
23063
+ static get instance(): DatabaseController;
23064
+ private readonly registrationsByActorName;
23065
+ private readonly registrationsByActorToken;
23066
+ private readonly adminDbClient;
23067
+ constructor();
23068
+ reset(): void;
23069
+ createPostgresActor(name: string, schema: DatabaseSchemaDefinition, description: string, options: ServerOptions & DatabaseOptions): PostgresActorRegistration;
23070
+ requestPostgresActorSetup(registrationOrName: PostgresActorRegistration | string, ctx?: AnyObject): PostgresActorRegistration | undefined;
23071
+ private resolveRegistration;
23072
+ private emitSetupDone;
23073
+ private registerSetupTask;
23074
+ private createTargetPool;
23075
+ private buildDatabaseConnectionString;
23076
+ private createDatabaseIfMissing;
23077
+ private checkPoolHealth;
23078
+ private getPoolOrThrow;
23079
+ private withTimeout;
23080
+ private runWithRetries;
23081
+ private executeWithTransaction;
23082
+ private queryFunction;
23083
+ private insertFunction;
23084
+ private updateFunction;
23085
+ private deleteFunction;
23086
+ private resolveSafetyPolicy;
23087
+ private buildOnConflictClause;
23088
+ /**
23089
+ * Validates database schema structure and content.
23090
+ */
23091
+ validateSchema(ctx: AnyObject): true;
23092
+ sortTablesByReferences(ctx: AnyObject): AnyObject;
23093
+ private buildSchemaDdlStatements;
23094
+ private fieldDefinitionToSql;
23095
+ private applyDdlStatements;
23096
+ private generateDatabaseTasks;
23097
+ private createDatabaseMacroTasks;
23098
+ private createDatabaseTask;
23099
+ private validateOperationPayload;
23100
+ private validateJoinPayload;
23101
+ toCamelCase(rows: any[]): any[];
23102
+ buildWhereClause(filter: AnyObject, params: any[]): string;
23103
+ buildJoinClause(joins: Record<string, JoinDefinition>): string;
23104
+ resolveNestedData(registration: PostgresActorRegistration, data: any, tableName: string): Promise<any>;
23105
+ executeSubOperation(registration: PostgresActorRegistration, operation: SubOperation): Promise<any>;
23106
+ private getInputSchema;
23107
+ }
23108
+
23109
+ interface SSRInquiryBridgeOptions {
23110
+ bootstrap?: BootstrapOptions;
23111
+ cadenzaDB?: {
23112
+ address?: string;
23113
+ port?: number;
23114
+ };
23115
+ }
23116
+ interface SSRInquiryBridge {
23117
+ inquire: (inquiry: string, context?: AnyObject, options?: DistributedInquiryOptions) => Promise<AnyObject>;
23118
+ dehydrate: () => HydrationOptions;
23119
+ }
23120
+ declare function createSSRInquiryBridge(options?: SSRInquiryBridgeOptions): SSRInquiryBridge;
23121
+
23122
+ type RuntimeStatusState = "healthy" | "degraded" | "overloaded" | "unavailable";
23123
+
23124
+ interface ServiceInstanceDescriptor {
23125
+ uuid: string;
23126
+ serviceName: string;
23127
+ numberOfRunningGraphs?: number;
23128
+ isPrimary: boolean;
23129
+ isActive: boolean;
23130
+ isNonResponsive: boolean;
23131
+ isBlocked: boolean;
23132
+ runtimeState?: RuntimeStatusState;
23133
+ acceptingWork?: boolean;
23134
+ reportedAt?: string;
23135
+ health: AnyObject;
23136
+ isFrontend: boolean;
23137
+ isDatabase?: boolean;
23138
+ transports: ServiceTransportDescriptor[];
23139
+ clientCreatedTransportIds?: string[];
23140
+ }
23141
+
23142
+ export { type AggregateDefinition, type AggregateFunction, type BootstrapOptions, DatabaseController, DatabaseTask, type DbOperationPayload, type DbOperationType$1 as DbOperationType, type DeputyDescriptor, DeputyTask, type DistributedInquiryMeta, type DistributedInquiryOptions, GraphMetadataController, type HydrationOptions, type InquiryResponderDescriptor, type InquiryResponderStatus, type JoinDefinition, type NetworkMode, type OpEffect, type QueryMode, type ResolvedBootstrapEndpoint, RestController, type SSRInquiryBridge, type SSRInquiryBridgeOptions, type SecurityProfile, type ServerOptions, type ServiceInstanceDescriptor, ServiceRegistry, type ServiceTransportConfig, type ServiceTransportDescriptor, type ServiceTransportProtocol, type ServiceTransportRole, type ServiceTransportSecurityProfile, SignalController, SignalTransmissionTask, SocketController, type SortDirection, type SubOperation, type SubOperationType, type ValueOrSubOp, createSSRInquiryBridge, CadenzaService as default };