@cadenza.io/service 2.12.0 → 2.15.0

package/dist/index.mjs

@@ -5195,6 +5195,9 @@ function normalizeIntentToken(value) {
   }
   return normalized;
 }
+function buildPostgresActorName(name) {
+  return `${String(name ?? "").trim()}PostgresActor`;
+}
 function validateIntentName(intentName) {
   if (!intentName || typeof intentName !== "string") {
     throw new Error("Intent name must be a non-empty string");
@@ -5332,7 +5335,8 @@ function resolveDataRows(data) {
 }
 var DatabaseController = class _DatabaseController {
   constructor() {
-    this.registrationsByService = /* @__PURE__ */ new Map();
+    this.registrationsByActorName = /* @__PURE__ */ new Map();
+    this.registrationsByActorToken = /* @__PURE__ */ new Map();
     this.adminDbClient = new Pool({
       connectionString: process.env.DATABASE_ADDRESS ?? "",
       database: "postgres",
@@ -5343,15 +5347,11 @@ var DatabaseController = class _DatabaseController {
     CadenzaService.createMetaTask(
       "Route PostgresActor setup requests",
       (ctx) => {
-        const serviceName = String(ctx.options?.serviceName ?? ctx.serviceName ?? "");
-        if (!serviceName) {
-          return ctx;
-        }
-        const registration = this.registrationsByService.get(serviceName);
+        const registration = this.resolveRegistration(ctx);
         if (!registration) {
           return ctx;
         }
-        CadenzaService.emit(`meta.postgres_actor.setup_requested.${registration.actorToken}`, ctx);
+        this.requestPostgresActorSetup(registration, ctx);
         return ctx;
       },
       "Routes generic database init requests to actor-scoped setup signal.",
@@ -5363,23 +5363,25 @@ var DatabaseController = class _DatabaseController {
     return this._instance;
   }
   reset() {
-    for (const registration of this.registrationsByService.values()) {
+    for (const registration of this.registrationsByActorName.values()) {
       const runtimeState = registration.actor.getRuntimeState(registration.actorKey);
       if (runtimeState?.pool) {
         runtimeState.pool.end().catch(() => void 0);
       }
     }
-    this.registrationsByService.clear();
+    this.registrationsByActorName.clear();
+    this.registrationsByActorToken.clear();
     this.adminDbClient.end().catch(() => void 0);
   }
-  createPostgresActor(serviceName, schema, options) {
-    const existing = this.registrationsByService.get(serviceName);
+  createPostgresActor(name, schema, description, options) {
+    const actorName = buildPostgresActorName(name);
+    const existing = this.registrationsByActorName.get(actorName);
     if (existing) {
       return existing;
     }
-    const actorName = `${serviceName}PostgresActor`;
     const actorToken = normalizeIntentToken(actorName);
-    const actorKey = String(options.databaseName ?? snakeCase(serviceName));
+    const actorKey = String(options.databaseName ?? snakeCase(name));
+    const ownerServiceName = options.ownerServiceName ?? CadenzaService.serviceRegistry?.serviceName ?? null;
     const optionTimeout = typeof options.timeoutMs === "number" ? Number(options.timeoutMs) : Number(options.timeout);
     const safetyPolicy = {
       statementTimeoutMs: normalizePositiveInteger(
@@ -5397,7 +5399,7 @@ var DatabaseController = class _DatabaseController {
     const actor = CadenzaService.createActor(
       {
         name: actorName,
-        description: "Specialized PostgresActor owning pool runtime state and schema-driven DB task generation.",
+        description: description || "Specialized PostgresActor owning pool runtime state and schema-driven DB task generation.",
         defaultKey: actorKey,
         keyResolver: (input) => typeof input.databaseName === "string" ? input.databaseName : void 0,
         loadPolicy: "eager",
@@ -5405,7 +5407,7 @@ var DatabaseController = class _DatabaseController {
         initState: {
           actorName,
           actorToken,
-          serviceName,
+          ownerServiceName,
           databaseName: actorKey,
           status: "idle",
           schemaVersion: Number(schema.version ?? 1),
@@ -5420,23 +5422,99 @@ var DatabaseController = class _DatabaseController {
       { isMeta: Boolean(options.isMeta) }
     );
     const registration = {
-      serviceName,
+      ownerServiceName,
       databaseName: actorKey,
       actorName,
       actorToken,
       actorKey,
+      setupSignal: `meta.postgres_actor.setup_requested.${actorToken}`,
+      setupDoneSignal: `meta.postgres_actor.setup_done.${actorToken}`,
+      setupFailedSignal: `meta.postgres_actor.setup_failed.${actorToken}`,
       actor,
       schema,
+      description,
       options,
       tasksGenerated: false,
       intentNames: /* @__PURE__ */ new Set()
     };
-    this.registrationsByService.set(serviceName, registration);
+    this.registrationsByActorName.set(actorName, registration);
+    this.registrationsByActorToken.set(actorToken, registration);
     this.registerSetupTask(registration);
     return registration;
   }
+  requestPostgresActorSetup(registrationOrName, ctx = {}) {
+    const registration = typeof registrationOrName === "string" ? this.resolveRegistration({
+      actorName: registrationOrName
+    }) : registrationOrName;
+    if (!registration) {
+      return void 0;
+    }
+    const payload = {
+      ...ctx,
+      actorName: registration.actorName,
+      actorToken: registration.actorToken,
+      databaseName: registration.databaseName,
+      ownerServiceName: registration.ownerServiceName,
+      options: {
+        ...ctx.options ?? {},
+        actorName: registration.actorName,
+        actorToken: registration.actorToken,
+        ownerServiceName: registration.ownerServiceName,
+        databaseName: registration.databaseName
+      }
+    };
+    const runtimeState = registration.actor.getRuntimeState(registration.actorKey);
+    if (runtimeState?.ready) {
+      this.emitSetupDone(registration, payload);
+      return registration;
+    }
+    CadenzaService.emit(registration.setupSignal, payload);
+    return registration;
+  }
+  resolveRegistration(ctx) {
+    const rawActorToken = String(
+      ctx.options?.actorToken ?? ctx.actorToken ?? ""
+    ).trim();
+    if (rawActorToken) {
+      const actorToken = normalizeIntentToken(rawActorToken);
+      const registration = this.registrationsByActorToken.get(actorToken);
+      if (registration) {
+        return registration;
+      }
+    }
+    const rawActorName = String(
+      ctx.options?.actorName ?? ctx.actorName ?? ctx.options?.postgresActorName ?? ctx.postgresActorName ?? ""
+    ).trim();
+    if (rawActorName) {
+      const registration = this.registrationsByActorName.get(rawActorName) ?? this.registrationsByActorName.get(buildPostgresActorName(rawActorName));
+      if (registration) {
+        return registration;
+      }
+    }
+    const legacyServiceName = String(
+      ctx.options?.serviceName ?? ctx.serviceName ?? ""
+    ).trim();
+    if (legacyServiceName) {
+      return this.registrationsByActorName.get(
+        buildPostgresActorName(legacyServiceName)
+      );
+    }
+    return void 0;
+  }
+  emitSetupDone(registration, payload) {
+    const resolvedPayload = {
+      ...payload,
+      actorName: registration.actorName,
+      actorToken: registration.actorToken,
+      databaseName: registration.databaseName,
+      ownerServiceName: registration.ownerServiceName,
+      __success: true
+    };
+    CadenzaService.emit(registration.setupDoneSignal, resolvedPayload);
+    CadenzaService.emit("meta.postgres_actor.setup_done", resolvedPayload);
+    CadenzaService.emit("meta.database.setup_done", resolvedPayload);
+  }
   registerSetupTask(registration) {
-    const setupSignal = `meta.postgres_actor.setup_requested.${registration.actorToken}`;
     CadenzaService.createMetaTask(
       `Setup ${registration.actorName}`,
       registration.actor.task(
@@ -5496,17 +5574,15 @@ var DatabaseController = class _DatabaseController {
               lastError: null,
               tables: Object.keys(registration.schema.tables ?? {})
             });
-            emit("meta.database.setup_done", {
-              serviceName: registration.serviceName,
-              databaseName: registration.databaseName,
-              actorName: registration.actorName,
-              __success: true
+            this.emitSetupDone(registration, {
+              ...input
             });
             return {
               ...input,
               __success: true,
               actorName: registration.actorName,
-              databaseName: registration.databaseName
+              databaseName: registration.databaseName,
+              ownerServiceName: registration.ownerServiceName
             };
           } catch (error) {
             const message = errorMessage(error);
@@ -5530,7 +5606,11 @@ var DatabaseController = class _DatabaseController {
       ),
       "Initializes PostgresActor runtime pool, applies schema, and generates CRUD tasks/intents.",
       { isMeta: true }
-    ).doOn(setupSignal);
+    ).doOn(registration.setupSignal).emitsOnFail(
+      registration.setupFailedSignal,
+      "meta.postgres_actor.setup_failed",
+      "meta.database.setup_failed"
+    );
   }
   createTargetPool(databaseName, statementTimeoutMs) {
     const connectionString = this.buildDatabaseConnectionString(databaseName);
@@ -8554,87 +8634,52 @@ var CadenzaService = class {
     this.createCadenzaService(serviceName, description, options);
   }
   /**
-   * Creates and initializes a PostgresActor-backed database service.
-   * This is the canonical API for schema-driven postgres setup in cadenza-service.
+   * Creates and initializes a specialized PostgresActor.
+   * This is actor-only and does not create or register a network service.
    *
-   * @param {string} name - Logical actor/service name.
+   * @param {string} name - Logical PostgresActor name.
    * @param {DatabaseSchemaDefinition} schema - Database schema definition.
-   * @param {string} [description=""] - Optional human-readable description.
-   * @param {ServerOptions & DatabaseOptions} [options={}] - Server/database runtime options.
+   * @param {string} [description=""] - Optional human-readable actor description.
+   * @param {ServerOptions & DatabaseOptions} [options={}] - Actor/database runtime options.
    * @return {void}
    */
   static createPostgresActor(name, schema, description = "", options = {}) {
     if (isBrowser) {
       console.warn(
-        "Database service creation is not supported in the browser. Use the CadenzaDB service instead."
+        "PostgresActor creation is not supported in the browser."
       );
       return;
     }
-    if (this.serviceCreated) return;
     this.bootstrap();
-    this.serviceRegistry.serviceName = name;
+    this.validateName(name);
     const databaseController = DatabaseController.instance;
-    options = {
-      loadBalance: true,
-      useSocket: true,
-      displayName: void 0,
-      isMeta: false,
-      port: parseInt(process.env.HTTP_PORT ?? "3000"),
-      securityProfile: process.env.SECURITY_PROFILE ?? "medium",
-      networkMode: process.env.NETWORK_MODE ?? "dev",
-      retryCount: 3,
-      cadenzaDB: {
-        connect: true,
-        address: process.env.CADENZA_DB_ADDRESS ?? "localhost",
-        port: parseInt(process.env.CADENZA_DB_PORT ?? "5000")
-      },
-      databaseType: "postgres",
-      databaseName: snakeCase2(name),
-      poolSize: parseInt(process.env.DATABASE_POOL_SIZE ?? "10"),
-      isDatabase: true,
-      ...options
-    };
+    const normalizedOptions = this.normalizePostgresActorOptions(name, options);
     const registration = databaseController.createPostgresActor(
       name,
       schema,
-      options
+      description,
+      normalizedOptions
     );
     console.log("Creating PostgresActor", {
-      serviceName: name,
+      name,
       actorName: registration.actorName,
-      options
+      ownerServiceName: normalizedOptions.ownerServiceName ?? null,
+      options: normalizedOptions
     });
-    this.emit("meta.database_init_requested", {
-      schema,
-      databaseName: options.databaseName,
-      options
+    databaseController.requestPostgresActorSetup(registration, {
+      actorName: registration.actorName,
+      actorToken: registration.actorToken,
+      databaseName: normalizedOptions.databaseName,
+      ownerServiceName: normalizedOptions.ownerServiceName ?? null
     });
-    this.createMetaTask("Set database connection", () => {
-      this.createMetaTask("Insert database service bridge", (_, emit) => {
-        emit("global.meta.created_database_service", {
-          data: {
-            service_name: name,
-            description,
-            schema,
-            is_meta: options.isMeta
-          }
-        });
-        this.log("Database service created", {
-          name,
-          isMeta: options.isMeta,
-          actorName: registration.actorName
-        });
-      }).doOn("meta.service_registry.service_inserted");
-      this.createCadenzaService(name, description, options);
-    }).doOn("meta.database.setup_done");
   }
   /**
-   * Creates a meta PostgresActor service.
+   * Creates a meta PostgresActor.
    *
-   * @param {string} name - Logical actor/service name.
+   * @param {string} name - Logical PostgresActor name.
    * @param {DatabaseSchemaDefinition} schema - Database schema definition.
    * @param {string} [description=""] - Optional description.
-   * @param {ServerOptions & DatabaseOptions} [options={}] - Optional server/database options.
+   * @param {ServerOptions & DatabaseOptions} [options={}] - Optional actor/database options.
    * @return {void}
    */
   static createMetaPostgresActor(name, schema, description = "", options = {}) {
@@ -8643,10 +8688,84 @@ var CadenzaService = class {
     this.createPostgresActor(name, schema, description, options);
   }
   /**
-   * Legacy compatibility wrapper. Prefer {@link createPostgresActor}.
+   * Creates a dedicated database service by composing a PostgresActor and a Cadenza service.
    */
   static createDatabaseService(name, schema, description = "", options = {}) {
-    this.createPostgresActor(name, schema, description, options);
+    if (isBrowser) {
+      console.warn(
+        "Database service creation is not supported in the browser. Use the CadenzaDB service instead."
+      );
+      return;
+    }
+    if (this.serviceCreated) return;
+    this.bootstrap();
+    this.validateName(name);
+    this.validateServiceName(name);
+    const databaseController = DatabaseController.instance;
+    const actorOptions = this.normalizePostgresActorOptions(name, {
+      ...options,
+      ownerServiceName: options.ownerServiceName ?? name
+    });
+    const serviceOptions = this.normalizeDatabaseServiceOptions(name, {
+      ...options,
+      ownerServiceName: actorOptions.ownerServiceName
+    });
+    const registration = databaseController.createPostgresActor(
+      name,
+      schema,
+      description,
+      actorOptions
+    );
+    this.registerDatabaseServiceBridgeTask(
+      name,
+      description,
+      schema,
+      Boolean(serviceOptions.isMeta),
+      registration.actorName
+    );
+    const createServiceTaskName = `Create database service ${name} after ${registration.actorName} setup`;
+    if (!this.get(createServiceTaskName)) {
+      this.createMetaTask(
+        createServiceTaskName,
+        () => {
+          this.createCadenzaService(name, description, serviceOptions);
+          return true;
+        },
+        "Creates the networked database service after PostgresActor setup completes."
+      ).doOn(registration.setupDoneSignal);
+    }
+    const setupFailureTaskName = `Handle database service ${name} bootstrap failure`;
+    if (!this.get(setupFailureTaskName)) {
+      this.createMetaTask(
+        setupFailureTaskName,
+        (ctx) => {
+          this.log(
+            "Database service bootstrap failed before service creation.",
+            {
+              serviceName: name,
+              actorName: registration.actorName,
+              databaseName: registration.databaseName,
+              error: ctx.__error
+            },
+            "error"
+          );
+          return true;
+        },
+        "Logs PostgresActor setup failures for database service bootstrap."
+      ).doOn(registration.setupFailedSignal);
+    }
+    console.log("Creating database service wrapper", {
+      serviceName: name,
+      actorName: registration.actorName,
+      actorOptions,
+      serviceOptions
+    });
+    databaseController.requestPostgresActorSetup(registration, {
+      actorName: registration.actorName,
+      actorToken: registration.actorToken,
+      databaseName: actorOptions.databaseName,
+      ownerServiceName: actorOptions.ownerServiceName ?? name
+    });
   }
   /**
    * Creates a meta database service with the specified configuration.
@@ -8658,7 +8777,73 @@ var CadenzaService = class {
    * @return {void} - This method does not return a value.
    */
   static createMetaDatabaseService(name, schema, description = "", options = {}) {
-    this.createMetaPostgresActor(name, schema, description, options);
+    this.createDatabaseService(name, schema, description, {
+      ...options,
+      isMeta: true
+    });
+  }
+  static normalizePostgresActorOptions(name, options = {}) {
+    return {
+      isMeta: false,
+      retryCount: 3,
+      databaseType: "postgres",
+      databaseName: snakeCase2(name),
+      poolSize: parseInt(process.env.DATABASE_POOL_SIZE ?? "10"),
+      ownerServiceName: options.ownerServiceName ?? this.serviceRegistry?.serviceName ?? null,
+      ...options
+    };
+  }
+  static normalizeDatabaseServiceOptions(name, options = {}) {
+    return {
+      loadBalance: true,
+      useSocket: true,
+      displayName: void 0,
+      isMeta: false,
+      port: parseInt(process.env.HTTP_PORT ?? "3000"),
+      securityProfile: process.env.SECURITY_PROFILE ?? "medium",
+      networkMode: process.env.NETWORK_MODE ?? "dev",
+      retryCount: 3,
+      cadenzaDB: {
+        connect: true,
+        address: process.env.CADENZA_DB_ADDRESS ?? "localhost",
+        port: parseInt(process.env.CADENZA_DB_PORT ?? "5000")
+      },
+      databaseType: "postgres",
+      databaseName: snakeCase2(name),
+      poolSize: parseInt(process.env.DATABASE_POOL_SIZE ?? "10"),
+      isDatabase: true,
+      ownerServiceName: options.ownerServiceName ?? name,
+      ...options
+    };
+  }
+  static registerDatabaseServiceBridgeTask(serviceName, description, schema, isMeta, actorName) {
+    const taskName = `Insert database service bridge ${serviceName}`;
+    if (this.get(taskName)) {
+      return;
+    }
+    this.createMetaTask(
+      taskName,
+      (ctx, emit) => {
+        if (ctx.__serviceName && ctx.__serviceName !== serviceName) {
+          return false;
+        }
+        emit("global.meta.created_database_service", {
+          data: {
+            service_name: serviceName,
+            description,
+            schema,
+            is_meta: isMeta
+          }
+        });
+        this.log("Database service created", {
+          name: serviceName,
+          isMeta,
+          actorName
+        });
+        return true;
+      },
+      "Bridges database service creation into the global metadata signal."
+    ).doOn("meta.service_registry.service_inserted");
   }
   static createActor(spec, options = {}) {
     this.bootstrap();
@@ -9011,14 +9196,14 @@ var CadenzaService = class {
     return Cadenza.createEphemeralTask(name, func, description, options);
   }
   /**
-   * Creates an ephemeral meta task with the specified name, function, description, and options.
+   * Creates an ephemeral meta-task with the specified name, function, description, and options.
    * See {@link createEphemeralTask} and {@link createMetaTask} for more details.
    *
    * @param {string} name - The name of the task to be created.
    * @param {TaskFunction} func - The function to be executed as part of the task.
    * @param {string} [description] - An optional description of the task.
    * @param {TaskOptions & EphemeralTaskOptions} [options={}] - Additional options for configuring the task.
-   * @return {EphemeralTask} The created ephemeral meta task.
+   * @return {EphemeralTask} The created ephemeral meta-task.
    */
   static createEphemeralMetaTask(name, func, description, options = {}) {
     this.bootstrap();