@cadenza.io/service 2.9.0 → 2.11.0

package/dist/index.mjs

@@ -1,7 +1,5 @@
 // src/Cadenza.ts
-import Cadenza, {
-  Actor
-} from "@cadenza.io/core";
+import Cadenza from "@cadenza.io/core";
 
 // src/graph/definition/DeputyTask.ts
 import { v4 as uuid } from "uuid";
@@ -3299,6 +3297,44 @@ var SocketController = class _SocketController {
     this.diagnosticsMaxClientEntries = 500;
     this.destroyedDiagnosticsTtlMs = 15 * 6e4;
     this.socketServerDefaultKey = "socket-server-default";
+    this.socketServerInitialSessionState = {
+      serverKey: this.socketServerDefaultKey,
+      useSocket: false,
+      status: "inactive",
+      securityProfile: "medium",
+      networkType: "internal",
+      connectionCount: 0,
+      lastStartedAt: null,
+      lastConnectedAt: null,
+      lastDisconnectedAt: null,
+      lastShutdownAt: null,
+      updatedAt: 0
+    };
+    this.socketClientInitialSessionState = {
+      fetchId: "",
+      serviceInstanceId: "",
+      communicationTypes: [],
+      serviceName: "",
+      serviceAddress: "",
+      servicePort: 0,
+      protocol: "http",
+      url: "",
+      socketId: null,
+      connected: false,
+      handshake: false,
+      pendingDelegations: 0,
+      pendingTimers: 0,
+      reconnectAttempts: 0,
+      connectErrors: 0,
+      reconnectErrors: 0,
+      socketErrors: 0,
+      errorCount: 0,
+      destroyed: false,
+      lastHandshakeAt: null,
+      lastHandshakeError: null,
+      lastDisconnectAt: null,
+      updatedAt: 0
+    };
     this.socketServerActor = CadenzaService.createActor(
       {
         name: "SocketServerActor",
@@ -3307,9 +3343,7 @@ var SocketController = class _SocketController {
         keyResolver: (input) => this.resolveSocketServerKey(input),
         loadPolicy: "lazy",
         writeContract: "overwrite",
-        initState: this.createInitialSocketServerSessionState(
-          this.socketServerDefaultKey
-        )
+        initState: this.socketServerInitialSessionState
       },
       { isMeta: true }
     );
@@ -3321,7 +3355,7 @@ var SocketController = class _SocketController {
         keyResolver: (input) => this.resolveSocketClientFetchId(input),
         loadPolicy: "lazy",
         writeContract: "overwrite",
-        initState: this.createInitialSocketClientSessionState()
+        initState: this.socketClientInitialSessionState
       },
       { isMeta: true }
     );
@@ -4402,48 +4436,6 @@ var SocketController = class _SocketController {
       "Connects to a specified socket server and wires runtime tasks."
     ).doOn("meta.fetch.handshake_complete").emitsOnFail("meta.socket_client.connect_failed");
   }
-  createInitialSocketServerSessionState(serverKey) {
-    return {
-      serverKey,
-      useSocket: false,
-      status: "inactive",
-      securityProfile: "medium",
-      networkType: "internal",
-      connectionCount: 0,
-      lastStartedAt: null,
-      lastConnectedAt: null,
-      lastDisconnectedAt: null,
-      lastShutdownAt: null,
-      updatedAt: 0
-    };
-  }
-  createInitialSocketClientSessionState() {
-    return {
-      fetchId: "",
-      serviceInstanceId: "",
-      communicationTypes: [],
-      serviceName: "",
-      serviceAddress: "",
-      servicePort: 0,
-      protocol: "http",
-      url: "",
-      socketId: null,
-      connected: false,
-      handshake: false,
-      pendingDelegations: 0,
-      pendingTimers: 0,
-      reconnectAttempts: 0,
-      connectErrors: 0,
-      reconnectErrors: 0,
-      socketErrors: 0,
-      errorCount: 0,
-      destroyed: false,
-      lastHandshakeAt: null,
-      lastHandshakeError: null,
-      lastDisconnectAt: null,
-      updatedAt: 0
-    };
-  }
   resolveSocketServerKey(input) {
     return String(input.serverKey ?? input.__socketServerKey ?? this.socketServerDefaultKey).trim() || this.socketServerDefaultKey;
   }
@@ -4776,6 +4768,7 @@ var SignalController = class _SignalController {
 };
 
 // src/graph/controllers/GraphMetadataController.ts
+import { META_ACTOR_SESSION_STATE_PERSIST_INTENT } from "@cadenza.io/core";
 var GraphMetadataController = class _GraphMetadataController {
   static get instance() {
     if (!this._instance) this._instance = new _GraphMetadataController();
@@ -4993,6 +4986,139 @@ var GraphMetadataController = class _GraphMetadataController {
       "Handles task execution relationship creation",
       { concurrency: 100, isSubMeta: true }
     ).doOn("meta.node.mapped", "meta.node.detected_previous_task_execution").emits("global.meta.graph_metadata.relationship_executed");
+    CadenzaService.createMetaTask("Handle actor creation", (ctx) => {
+      return {
+        data: {
+          ...ctx.data,
+          service_name: CadenzaService.serviceRegistry.serviceName
+        }
+      };
+    }).doOn("meta.actor.created").emits("global.meta.graph_metadata.actor_created");
+    CadenzaService.createMetaTask("Handle actor task association", (ctx) => {
+      return {
+        data: {
+          ...ctx.data,
+          service_name: CadenzaService.serviceRegistry.serviceName
+        }
+      };
+    }).doOn("meta.actor.task_associated").emits("global.meta.graph_metadata.actor_task_associated");
+    const actorSessionStateInsertTask = CadenzaService.get("dbInsertActorSessionState") ?? CadenzaService.get("Insert actor_session_state in CadenzaDB") ?? CadenzaService.createCadenzaDBInsertTask(
+      "actor_session_state",
+      {},
+      { concurrency: 100, isSubMeta: true }
+    );
+    const validateActorSessionStatePersistenceTask = CadenzaService.createMetaTask(
+      "Validate actor session state persistence",
+      (ctx) => {
+        if (ctx.errored || ctx.failed || ctx.__success !== true) {
+          throw new Error(
+            String(
+              ctx.__error ?? ctx.error ?? "actor_session_state persistence query failed"
+            )
+          );
+        }
+        const rowCount = Number(ctx.rowCount ?? 0);
+        if (!Number.isFinite(rowCount) || rowCount <= 0) {
+          throw new Error(
+            "actor_session_state persistence did not affect any rows (possible stale durable_version)"
+          );
+        }
+        return {
+          __success: true,
+          persisted: true,
+          actor_name: ctx.actor_name,
+          actor_version: ctx.actor_version,
+          actor_key: ctx.actor_key,
+          service_name: ctx.service_name,
+          durable_version: ctx.durable_version
+        };
+      },
+      "Enforces strict actor session persistence success contract.",
+      { isSubMeta: true, concurrency: 100 }
+    );
+    const insertAndValidateActorSessionStateTask = actorSessionStateInsertTask.then(
+      validateActorSessionStatePersistenceTask
+    );
+    CadenzaService.createMetaTask(
+      "Persist actor session state",
+      (ctx) => {
+        const actorName = typeof ctx.actor_name === "string" ? ctx.actor_name.trim() : "";
+        const actorKey = typeof ctx.actor_key === "string" ? ctx.actor_key.trim() : "";
+        const actorVersion = Number(ctx.actor_version ?? 1);
+        const durableVersion = Number(ctx.durable_version);
+        if (!actorName) {
+          throw new Error("actor_name is required for actor session persistence");
+        }
+        if (!actorKey) {
+          throw new Error("actor_key is required for actor session persistence");
+        }
+        if (!Number.isInteger(actorVersion) || actorVersion < 1) {
+          throw new Error("actor_version must be a positive integer");
+        }
+        if (!Number.isInteger(durableVersion) || durableVersion < 0) {
+          throw new Error("durable_version must be a non-negative integer");
+        }
+        if (typeof ctx.durable_state !== "object" || ctx.durable_state === null || Array.isArray(ctx.durable_state)) {
+          throw new Error("durable_state must be a non-null object");
+        }
+        const serviceName = CadenzaService.serviceRegistry.serviceName;
+        if (!serviceName) {
+          throw new Error("service_name is not available for actor session persistence");
+        }
+        let expiresAt = null;
+        if (ctx.expires_at !== void 0 && ctx.expires_at !== null) {
+          if (ctx.expires_at instanceof Date) {
+            expiresAt = ctx.expires_at.toISOString();
+          } else if (typeof ctx.expires_at === "string" && ctx.expires_at.trim().length > 0) {
+            expiresAt = ctx.expires_at;
+          } else {
+            throw new Error("expires_at must be null, Date, or non-empty string");
+          }
+        }
+        const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        return {
+          ...ctx,
+          actor_name: actorName,
+          actor_key: actorKey,
+          actor_version: actorVersion,
+          durable_version: durableVersion,
+          expires_at: expiresAt,
+          service_name: serviceName,
+          queryData: {
+            data: {
+              actor_name: actorName,
+              actor_version: actorVersion,
+              actor_key: actorKey,
+              service_name: serviceName,
+              durable_state: ctx.durable_state,
+              durable_version: durableVersion,
+              expires_at: expiresAt,
+              updated: updatedAt
+            },
+            onConflict: {
+              target: [
+                "actor_name",
+                "actor_version",
+                "actor_key",
+                "service_name"
+              ],
+              action: {
+                do: "update",
+                set: {
+                  durable_state: "excluded",
+                  durable_version: "excluded",
+                  expires_at: "excluded",
+                  updated: "excluded"
+                },
+                where: "actor_session_state.durable_version <= excluded.durable_version"
+              }
+            }
+          }
+        };
+      },
+      "Validates and prepares actor_session_state payload for strict write-through persistence.",
+      { isSubMeta: true, concurrency: 100 }
+    ).then(insertAndValidateActorSessionStateTask).respondsTo(META_ACTOR_SESSION_STATE_PERSIST_INTENT);
     CadenzaService.createMetaTask("Handle Intent Creation", (ctx) => {
       const intentName = ctx.data?.name;
       return {
@@ -6664,8 +6790,69 @@ function tableFieldTypeToSchemaType(type) {
 import { v4 as uuid3 } from "uuid";
 
 // src/graph/controllers/GraphSyncController.ts
+var ACTOR_TASK_METADATA = /* @__PURE__ */ Symbol.for("@cadenza.io/core/actor-task-meta");
+function getActorTaskRuntimeMetadata(taskFunction) {
+  if (typeof taskFunction !== "function") {
+    return void 0;
+  }
+  return taskFunction[ACTOR_TASK_METADATA];
+}
+function sanitizeActorMetadataValue(value) {
+  if (value === null) {
+    return null;
+  }
+  if (value === void 0 || typeof value === "function") {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    const items = [];
+    for (const item of value) {
+      const sanitizedItem = sanitizeActorMetadataValue(item);
+      if (sanitizedItem !== void 0) {
+        items.push(sanitizedItem);
+      }
+    }
+    return items;
+  }
+  if (typeof value === "object") {
+    const output = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+      const sanitizedNestedValue = sanitizeActorMetadataValue(nestedValue);
+      if (sanitizedNestedValue !== void 0) {
+        output[key] = sanitizedNestedValue;
+      }
+    }
+    return output;
+  }
+  return value;
+}
+function buildActorRegistrationData(actor) {
+  const definition = sanitizeActorMetadataValue(
+    typeof actor?.toDefinition === "function" ? actor.toDefinition() : {}
+  );
+  const stateDefinition = definition?.state && typeof definition.state === "object" ? definition.state : {};
+  const actorKind = typeof definition?.kind === "string" ? definition.kind : actor?.kind;
+  return {
+    name: definition?.name ?? actor?.spec?.name ?? "",
+    description: definition?.description ?? actor?.spec?.description ?? "",
+    default_key: definition?.defaultKey ?? actor?.spec?.defaultKey ?? "default",
+    load_policy: definition?.loadPolicy ?? actor?.spec?.loadPolicy ?? "eager",
+    write_contract: definition?.writeContract ?? actor?.spec?.writeContract ?? "overwrite",
+    runtime_read_guard: definition?.runtimeReadGuard ?? actor?.spec?.runtimeReadGuard ?? "none",
+    consistency_profile: definition?.consistencyProfile ?? actor?.spec?.consistencyProfile ?? null,
+    key_definition: definition?.key ?? null,
+    state_definition: stateDefinition,
+    retry_policy: definition?.retry ?? {},
+    idempotency_policy: definition?.idempotency ?? {},
+    session_policy: definition?.session ?? {},
+    is_meta: actorKind === "meta",
+    version: 1
+  };
+}
 var GraphSyncController = class _GraphSyncController {
   constructor() {
+    this.registeredActors = /* @__PURE__ */ new Set();
+    this.registeredActorTaskMaps = /* @__PURE__ */ new Set();
     this.isCadenzaDBReady = false;
   }
   static get instance() {
@@ -6923,6 +7110,120 @@ var GraphSyncController = class _GraphSyncController {
         )
       )
     );
+    this.splitActorsForRegistration = CadenzaService.createMetaTask(
+      "Split actors for registration",
+      function* (ctx) {
+        CadenzaService.debounce("meta.sync_controller.synced_resource", {
+          delayMs: 3e3
+        });
+        const actors = ctx.actors ?? [];
+        for (const actor of actors) {
+          const data = {
+            ...buildActorRegistrationData(actor),
+            service_name: CadenzaService.serviceRegistry.serviceName
+          };
+          if (!data.name) {
+            continue;
+          }
+          const registrationKey = `${data.name}|${data.version}|${data.service_name}`;
+          if (this.registeredActors.has(registrationKey)) {
+            continue;
+          }
+          yield {
+            data,
+            __actorRegistrationKey: registrationKey
+          };
+        }
+      }.bind(this)
+    ).then(
+      (this.isCadenzaDBReady ? CadenzaService.createCadenzaDBInsertTask(
+        "actor",
+        {
+          onConflict: {
+            target: ["name", "service_name", "version"],
+            action: {
+              do: "nothing"
+            }
+          }
+        },
+        { concurrency: 30 }
+      ) : CadenzaService.get("dbInsertActor"))?.then(
+        CadenzaService.createMetaTask("Record actor registration", (ctx) => {
+          if (!ctx.__syncing) {
+            return;
+          }
+          CadenzaService.debounce("meta.sync_controller.synced_resource", {
+            delayMs: 3e3
+          });
+          this.registeredActors.add(ctx.__actorRegistrationKey);
+          return true;
+        }).then(
+          CadenzaService.createUniqueMetaTask(
+            "Gather actor registration",
+            () => true
+          ).emits("meta.sync_controller.synced_actors")
+        )
+      )
+    );
+    this.registerActorTaskMapTask = CadenzaService.createMetaTask(
+      "Split actor task maps",
+      function* (ctx) {
+        const task = ctx.task;
+        if (task.hidden || !task.register) {
+          return;
+        }
+        const metadata = getActorTaskRuntimeMetadata(task.taskFunction);
+        if (!metadata?.actorName) {
+          return;
+        }
+        const registrationKey = `${metadata.actorName}|${task.name}|${task.version}|${CadenzaService.serviceRegistry.serviceName}`;
+        if (this.registeredActorTaskMaps.has(registrationKey)) {
+          return;
+        }
+        yield {
+          data: {
+            actor_name: metadata.actorName,
+            actor_version: 1,
+            task_name: task.name,
+            task_version: task.version,
+            service_name: CadenzaService.serviceRegistry.serviceName,
+            mode: metadata.mode,
+            description: task.description ?? metadata.actorDescription ?? "",
+            is_meta: metadata.actorKind === "meta" || task.isMeta === true
+          },
+          __actorTaskMapRegistrationKey: registrationKey
+        };
+      }.bind(this)
+    ).then(
+      (this.isCadenzaDBReady ? CadenzaService.createCadenzaDBInsertTask(
+        "actor_task_map",
+        {
+          onConflict: {
+            target: [
+              "actor_name",
+              "actor_version",
+              "task_name",
+              "task_version",
+              "service_name"
+            ],
+            action: {
+              do: "nothing"
+            }
+          }
+        },
+        { concurrency: 30 }
+      ) : CadenzaService.get("dbInsertActorTaskMap"))?.then(
+        CadenzaService.createMetaTask("Record actor task map registration", (ctx) => {
+          if (!ctx.__syncing) {
+            return;
+          }
+          CadenzaService.debounce("meta.sync_controller.synced_resource", {
+            delayMs: 3e3
+          });
+          this.registeredActorTaskMaps.add(ctx.__actorTaskMapRegistrationKey);
+        })
+      )
+    );
     const registerSignalTask = CadenzaService.createMetaTask(
       "Record signal registration",
       (ctx) => {
@@ -7164,12 +7465,19 @@ var GraphSyncController = class _GraphSyncController {
     ).then(this.splitSignalsTask);
     CadenzaService.registry.getAllTasks.clone().doOn("meta.sync_controller.synced_signals").then(this.splitTasksForRegistration);
     CadenzaService.registry.getAllRoutines.clone().doOn("meta.sync_controller.synced_tasks").then(this.splitRoutinesTask);
+    CadenzaService.createMetaTask("Get all actors", (ctx) => {
+      return {
+        ...ctx,
+        actors: CadenzaService.getAllActors()
+      };
+    }).doOn("meta.sync_controller.synced_tasks").then(this.splitActorsForRegistration);
     CadenzaService.registry.doForEachTask.clone().doOn("meta.sync_controller.synced_tasks").then(
       this.registerTaskMapTask,
       this.registerSignalToTaskMapTask,
       this.registerIntentToTaskMapTask,
       this.registerDeputyRelationshipTask
     );
+    CadenzaService.registry.doForEachTask.clone().doOn("meta.sync_controller.synced_tasks", "meta.sync_controller.synced_actors").then(this.registerActorTaskMapTask);
     CadenzaService.registry.getAllRoutines.clone().doOn("meta.sync_controller.synced_routines").then(this.splitTasksInRoutines);
     CadenzaService.createMetaTask("Finish sync", (ctx, emit) => {
       emit("global.meta.sync_controller.synced", {
@@ -7556,6 +7864,14 @@ var CadenzaService = class {
   static get(taskName) {
     return Cadenza.get(taskName);
   }
+  static getActor(actorName) {
+    const cadenzaWithActors = Cadenza;
+    return cadenzaWithActors.getActor?.(actorName);
+  }
+  static getAllActors() {
+    const cadenzaWithActors = Cadenza;
+    return cadenzaWithActors.getAllActors?.() ?? [];
+  }
   static getRoutine(routineName) {
     return Cadenza.getRoutine(routineName);
   }
@@ -8123,7 +8439,7 @@ var CadenzaService = class {
   }
   static createActor(spec, options = {}) {
     this.bootstrap();
-    return new Actor(spec, options);
+    return Cadenza.createActor(spec, options);
   }
   static createActorFromDefinition(definition, options = {}) {
     this.bootstrap();