@cadenza.io/service 2.4.0 → 2.5.0

package/dist/index.mjs

@@ -247,6 +247,72 @@ var DatabaseTask = class extends DeputyTask {
 var isNode = typeof process !== "undefined" && process.versions?.node != null;
 var isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
 
+// src/utils/inquiry.ts
+var META_INTENT_PREFIX = "meta-";
+var META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT = "meta-runtime-transport-diagnostics";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+function deepMergeDeterministic(left, right) {
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return [...left, ...right];
+  }
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const merged = { ...left };
+    const keys = Array.from(/* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)])).sort();
+    for (const key of keys) {
+      if (!(key in left)) {
+        merged[key] = right[key];
+        continue;
+      }
+      if (!(key in right)) {
+        merged[key] = left[key];
+        continue;
+      }
+      merged[key] = deepMergeDeterministic(left[key], right[key]);
+    }
+    return merged;
+  }
+  return right;
+}
+function mergeInquiryContexts(contexts) {
+  return contexts.reduce((acc, next) => deepMergeDeterministic(acc, next), {});
+}
+function isMetaIntentName(intentName) {
+  return intentName.startsWith(META_INTENT_PREFIX);
+}
+function shouldExecuteInquiryResponder(inquiry, responderIsMeta) {
+  if (!isMetaIntentName(inquiry)) {
+    return true;
+  }
+  return responderIsMeta;
+}
+function compareResponderDescriptors(left, right) {
+  if (left.serviceName !== right.serviceName) {
+    return left.serviceName.localeCompare(right.serviceName);
+  }
+  if (left.taskName !== right.taskName) {
+    return left.taskName.localeCompare(right.taskName);
+  }
+  if (left.taskVersion !== right.taskVersion) {
+    return left.taskVersion - right.taskVersion;
+  }
+  return left.localTaskName.localeCompare(right.localTaskName);
+}
+function summarizeResponderStatuses(statuses) {
+  let responded = 0;
+  let failed = 0;
+  let timedOut = 0;
+  let pending = 0;
+  for (const status of statuses) {
+    if (status.status === "fulfilled") responded++;
+    if (status.status === "failed") failed++;
+    if (status.status === "timed_out") timedOut++;
+  }
+  pending = Math.max(0, statuses.length - responded - failed - timedOut);
+  return { responded, failed, timedOut, pending };
+}
+
 // src/registry/ServiceRegistry.ts
 var ServiceRegistry = class _ServiceRegistry {
   /**
@@ -262,11 +328,47 @@ var ServiceRegistry = class _ServiceRegistry {
     this.instances = /* @__PURE__ */ new Map();
     this.deputies = /* @__PURE__ */ new Map();
     this.remoteSignals = /* @__PURE__ */ new Map();
+    this.remoteIntents = /* @__PURE__ */ new Map();
+    this.remoteIntentDeputiesByKey = /* @__PURE__ */ new Map();
+    this.remoteIntentDeputiesByTask = /* @__PURE__ */ new Map();
     this.serviceName = null;
     this.serviceInstanceId = null;
     this.numberOfRunningGraphs = 0;
     this.useSocket = false;
     this.retryCount = 3;
+    CadenzaService.defineIntent({
+      name: META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT,
+      description: "Gather transport diagnostics across all services and communication clients.",
+      input: {
+        type: "object",
+        properties: {
+          detailLevel: {
+            type: "string",
+            constraints: {
+              oneOf: ["summary", "full"]
+            }
+          },
+          includeErrorHistory: {
+            type: "boolean"
+          },
+          errorHistoryLimit: {
+            type: "number",
+            constraints: {
+              min: 1,
+              max: 200
+            }
+          }
+        }
+      },
+      output: {
+        type: "object",
+        properties: {
+          transportDiagnostics: {
+            type: "object"
+          }
+        }
+      }
+    });
     this.handleInstanceUpdateTask = CadenzaService.createMetaTask(
       "Handle Instance Update",
       (ctx, emit) => {
@@ -306,7 +408,7 @@ var ServiceRegistry = class _ServiceRegistry {
         if (this.serviceName === serviceName) {
           return false;
         }
-        if (!isFrontend && this.deputies.has(serviceName) || this.remoteSignals.has(serviceName)) {
+        if (!isFrontend && (this.deputies.has(serviceName) || this.remoteIntents.has(serviceName)) || this.remoteSignals.has(serviceName)) {
           const clientCreated = instances?.some(
             (i) => i.address === address && i.port === port && i.clientCreated && i.isActive
           );
@@ -356,7 +458,10 @@ var ServiceRegistry = class _ServiceRegistry {
       for (const serviceInstance of ctx.serviceInstances) {
         yield { serviceInstance };
       }
-    }).doOn("meta.service_registry.registered_global_signals").then(this.handleInstanceUpdateTask);
+    }).doOn(
+      "meta.service_registry.registered_global_signals",
+      "meta.service_registry.registered_global_intents"
+    ).then(this.handleInstanceUpdateTask);
     this.handleGlobalSignalRegistrationTask = CadenzaService.createMetaTask(
       "Handle global Signal Registration",
       (ctx) => {
@@ -397,6 +502,32 @@ var ServiceRegistry = class _ServiceRegistry {
       },
       "Handles registration of remote signals"
     ).emits("meta.service_registry.registered_global_signals").doOn("global.meta.cadenza_db.gathered_sync_data");
+    this.handleGlobalIntentRegistrationTask = CadenzaService.createMetaTask(
+      "Handle global intent registration",
+      (ctx) => {
+        const intentToTaskMaps = this.normalizeIntentMaps(ctx);
+        const sorted = intentToTaskMaps.sort((a, b) => {
+          if (a.deleted && !b.deleted) return -1;
+          if (!a.deleted && b.deleted) return 1;
+          return 0;
+        });
+        for (const map of sorted) {
+          if (map.deleted) {
+            this.unregisterRemoteIntentDeputy(map);
+            continue;
+          }
+          CadenzaService.inquiryBroker.addIntent({
+            name: map.intentName
+          });
+          this.registerRemoteIntentDeputy(map);
+        }
+        return true;
+      },
+      "Handles registration of remote inquiry intent responders"
+    ).emits("meta.service_registry.registered_global_intents").doOn(
+      "global.meta.cadenza_db.gathered_sync_data",
+      "global.meta.graph_metadata.task_intent_associated"
+    );
     this.handleServiceNotRespondingTask = CadenzaService.createMetaTask(
       "Handle service not responding",
       (ctx, emit) => {
@@ -510,7 +641,10 @@ var ServiceRegistry = class _ServiceRegistry {
         });
         return joinedContext;
       }
-    ).emits("meta.service_registry.initial_sync_complete").then(this.handleGlobalSignalRegistrationTask);
+    ).emits("meta.service_registry.initial_sync_complete").then(
+      this.handleGlobalSignalRegistrationTask,
+      this.handleGlobalIntentRegistrationTask
+    );
     this.fullSyncTask = CadenzaService.createMetaRoutine("Full sync", [
       CadenzaService.createCadenzaDBQueryTask("signal_to_task_map", {
         filter: {
@@ -518,6 +652,15 @@ var ServiceRegistry = class _ServiceRegistry {
         },
         fields: ["signal_name", "service_name", "deleted"]
       }).then(mergeSyncDataTask),
+      CadenzaService.createCadenzaDBQueryTask("intent_to_task_map", {
+        fields: [
+          "intent_name",
+          "task_name",
+          "task_version",
+          "service_name",
+          "deleted"
+        ]
+      }).then(mergeSyncDataTask),
       CadenzaService.createCadenzaDBQueryTask("service_instance", {
         filter: {
           deleted: false,
@@ -708,6 +851,25 @@ var ServiceRegistry = class _ServiceRegistry {
         __active: self?.isActive ?? false
       };
     }).doOn("meta.socket.status_check_requested");
+    this.collectTransportDiagnosticsTask = CadenzaService.createMetaTask(
+      "Collect transport diagnostics",
+      async (ctx) => {
+        const inquiryResult = await CadenzaService.inquire(
+          META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT,
+          {
+            detailLevel: ctx.detailLevel,
+            includeErrorHistory: ctx.includeErrorHistory,
+            errorHistoryLimit: ctx.errorHistoryLimit
+          },
+          ctx.inquiryOptions ?? ctx.__inquiryOptions ?? {}
+        );
+        return {
+          ...ctx,
+          ...inquiryResult
+        };
+      },
+      "Collects distributed transport diagnostics using inquiry responders."
+    ).doOn("meta.service_registry.transport_diagnostics_requested").emits("meta.service_registry.transport_diagnostics_collected").emitsOnFail("meta.service_registry.transport_diagnostics_failed");
     this.insertServiceTask = CadenzaService.createCadenzaDBInsertTask(
       "service",
       {
@@ -916,8 +1078,125 @@ var ServiceRegistry = class _ServiceRegistry {
     if (!this._instance) this._instance = new _ServiceRegistry();
     return this._instance;
   }
+  buildRemoteIntentDeputyKey(map) {
+    return `${map.intentName}|${map.serviceName}|${map.taskName}|${map.taskVersion ?? 1}`;
+  }
+  normalizeIntentMaps(ctx) {
+    if (Array.isArray(ctx.intentToTaskMaps)) {
+      return ctx.intentToTaskMaps.map((m) => ({
+        intentName: m.intentName ?? m.intent_name,
+        serviceName: m.serviceName ?? m.service_name,
+        taskName: m.taskName ?? m.task_name,
+        taskVersion: m.taskVersion ?? m.task_version ?? 1,
+        deleted: !!m.deleted
+      })).filter((m) => m.intentName && m.serviceName && m.taskName);
+    }
+    const single = ctx.intentToTaskMap ?? ctx.data ?? (ctx.intentName ? ctx : void 0);
+    if (!single) return [];
+    const normalized = {
+      intentName: single.intentName ?? single.intent_name,
+      serviceName: single.serviceName ?? single.service_name,
+      taskName: single.taskName ?? single.task_name,
+      taskVersion: single.taskVersion ?? single.task_version ?? 1,
+      deleted: !!single.deleted
+    };
+    if (!normalized.intentName || !normalized.serviceName || !normalized.taskName)
+      return [];
+    return [normalized];
+  }
+  registerRemoteIntentDeputy(map) {
+    if (!this.serviceName || map.serviceName === this.serviceName) {
+      return;
+    }
+    const key = this.buildRemoteIntentDeputyKey(map);
+    if (this.remoteIntentDeputiesByKey.has(key)) {
+      return;
+    }
+    const deputyTaskName = `Inquire ${map.intentName} via ${map.serviceName} (${map.taskName} v${map.taskVersion})`;
+    const deputyTask = isMetaIntentName(map.intentName) ? CadenzaService.createMetaDeputyTask(map.taskName, map.serviceName, {
+      register: false,
+      isHidden: true,
+      retryCount: 1,
+      retryDelay: 50,
+      retryDelayFactor: 1.2
+    }) : CadenzaService.createDeputyTask(map.taskName, map.serviceName, {
+      register: false,
+      isHidden: true,
+      retryCount: 1,
+      retryDelay: 50,
+      retryDelayFactor: 1.2
+    });
+    deputyTask.respondsTo(map.intentName);
+    if (!this.remoteIntents.has(map.serviceName)) {
+      this.remoteIntents.set(map.serviceName, /* @__PURE__ */ new Set());
+    }
+    this.remoteIntents.get(map.serviceName).add(map.intentName);
+    const descriptor = {
+      key,
+      intentName: map.intentName,
+      serviceName: map.serviceName,
+      remoteTaskName: map.taskName,
+      remoteTaskVersion: map.taskVersion,
+      localTaskName: deputyTask.name || deputyTaskName,
+      localTask: deputyTask
+    };
+    this.remoteIntentDeputiesByKey.set(key, descriptor);
+    this.remoteIntentDeputiesByTask.set(deputyTask, descriptor);
+  }
+  unregisterRemoteIntentDeputy(map) {
+    const key = this.buildRemoteIntentDeputyKey(map);
+    const descriptor = this.remoteIntentDeputiesByKey.get(key);
+    if (!descriptor) {
+      return;
+    }
+    const task = descriptor.localTask;
+    if (task) {
+      CadenzaService.inquiryBroker.unsubscribe(descriptor.intentName, task);
+      task.destroy();
+    }
+    this.remoteIntentDeputiesByTask.delete(descriptor.localTask);
+    this.remoteIntentDeputiesByKey.delete(key);
+    this.remoteIntents.get(descriptor.serviceName)?.delete(descriptor.intentName);
+    if (!this.remoteIntents.get(descriptor.serviceName)?.size) {
+      this.remoteIntents.delete(descriptor.serviceName);
+    }
+    const deputies = this.deputies.get(descriptor.serviceName);
+    if (deputies) {
+      this.deputies.set(
+        descriptor.serviceName,
+        deputies.filter((d) => d.localTaskName !== descriptor.localTaskName)
+      );
+      if (this.deputies.get(descriptor.serviceName)?.length === 0) {
+        this.deputies.delete(descriptor.serviceName);
+      }
+    }
+  }
+  getInquiryResponderDescriptor(task) {
+    const remote = this.remoteIntentDeputiesByTask.get(task);
+    if (remote) {
+      return {
+        isRemote: true,
+        serviceName: remote.serviceName,
+        taskName: remote.remoteTaskName,
+        taskVersion: remote.remoteTaskVersion,
+        localTaskName: remote.localTaskName
+      };
+    }
+    return {
+      isRemote: false,
+      serviceName: this.serviceName ?? "UnknownService",
+      taskName: task.name,
+      taskVersion: task.version,
+      localTaskName: task.name
+    };
+  }
   reset() {
     this.instances.clear();
+    this.deputies.clear();
+    this.remoteSignals.clear();
+    this.remoteIntents.clear();
+    this.remoteIntentDeputiesByKey.clear();
+    this.remoteIntentDeputiesByTask.clear();
   }
 };
 
@@ -1034,6 +1313,8 @@ var RestController = class _RestController {
    * It initializes and configures the REST server tasks.
    */
   constructor() {
+    this.fetchClientDiagnostics = /* @__PURE__ */ new Map();
+    this.diagnosticsErrorHistoryLimit = 100;
     /**
      * Fetches data from the given URL with a specified timeout. This function performs
      * a fetch request with the ability to cancel the request if it exceeds the provided timeout duration.
@@ -1074,6 +1355,11 @@ var RestController = class _RestController {
       "meta.rest.delegation_requested",
       "meta.socket.delegation_requested"
     );
+    CadenzaService.createMetaTask(
+      "Collect fetch transport diagnostics",
+      (ctx) => this.collectFetchTransportDiagnostics(ctx),
+      "Responds to distributed transport diagnostics inquiries with REST/fetch client data."
+    ).respondsTo(META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT);
     CadenzaService.createMetaRoutine(
       "RestServer",
       [
@@ -1404,6 +1690,13 @@ var RestController = class _RestController {
         const port = protocol === "https" ? 443 : servicePort;
         const URL = `${protocol}://${serviceAddress}:${port}`;
         const fetchId = `${serviceAddress}_${port}`;
+        const fetchDiagnostics = this.ensureFetchClientDiagnostics(
+          fetchId,
+          serviceName,
+          URL
+        );
+        fetchDiagnostics.destroyed = false;
+        fetchDiagnostics.updatedAt = Date.now();
         if (CadenzaService.get(`Send Handshake to ${URL}`)) {
           console.error("Fetch client already exists", URL);
           return;
@@ -1425,6 +1718,10 @@ var RestController = class _RestController {
               );
               if (response.__status !== "success") {
                 const error = response.__error ?? `Failed to connect to service ${serviceName} ${ctx2.serviceInstanceId}`;
+                fetchDiagnostics.connected = false;
+                fetchDiagnostics.lastHandshakeError = error;
+                fetchDiagnostics.updatedAt = Date.now();
+                this.recordFetchClientError(fetchId, serviceName, URL, error);
                 CadenzaService.log(
                   "Fetch handshake failed.",
                   { error, serviceName, URL },
@@ -1434,6 +1731,11 @@ var RestController = class _RestController {
                 return { ...ctx2, __error: error, errored: true };
               }
               ctx2.serviceInstanceId = response.__serviceInstanceId;
+              fetchDiagnostics.connected = true;
+              fetchDiagnostics.destroyed = false;
+              fetchDiagnostics.lastHandshakeAt = (/* @__PURE__ */ new Date()).toISOString();
+              fetchDiagnostics.lastHandshakeError = null;
+              fetchDiagnostics.updatedAt = Date.now();
               CadenzaService.log("Fetch client connected.", {
                 response,
                 serviceName,
@@ -1449,6 +1751,10 @@ var RestController = class _RestController {
                 });
               }
             } catch (e) {
+              fetchDiagnostics.connected = false;
+              fetchDiagnostics.lastHandshakeError = this.getErrorMessage(e);
+              fetchDiagnostics.updatedAt = Date.now();
+              this.recordFetchClientError(fetchId, serviceName, URL, e);
               CadenzaService.log(
                 "Error in fetch handshake",
                 { error: e, serviceName, URL, ctx: ctx2 },
@@ -1470,6 +1776,8 @@ var RestController = class _RestController {
             if (ctx2.__remoteRoutineName === void 0) {
               return;
             }
+            fetchDiagnostics.delegationRequests++;
+            fetchDiagnostics.updatedAt = Date.now();
             let resultContext;
             try {
               resultContext = await this.fetchDataWithTimeout(
@@ -1483,8 +1791,21 @@ var RestController = class _RestController {
                 },
                 3e4
               );
+              if (resultContext?.errored || resultContext?.failed) {
+                fetchDiagnostics.delegationFailures++;
+                fetchDiagnostics.updatedAt = Date.now();
+                this.recordFetchClientError(
+                  fetchId,
+                  serviceName,
+                  URL,
+                  resultContext?.__error ?? resultContext?.error ?? "Delegation failed"
+                );
+              }
             } catch (e) {
               console.error("Error in delegation", e);
+              fetchDiagnostics.delegationFailures++;
+              fetchDiagnostics.updatedAt = Date.now();
+              this.recordFetchClientError(fetchId, serviceName, URL, e);
               resultContext = {
                 __error: `Error: ${e}`,
                 errored: true,
@@ -1510,6 +1831,8 @@ var RestController = class _RestController {
             if (ctx2.__signalName === void 0) {
               return;
             }
+            fetchDiagnostics.signalTransmissions++;
+            fetchDiagnostics.updatedAt = Date.now();
             let response;
             try {
               response = await this.fetchDataWithTimeout(
@@ -1526,8 +1849,21 @@ var RestController = class _RestController {
               if (ctx2.__routineExecId) {
                 emit(`meta.fetch.transmitted:${ctx2.__routineExecId}`, response);
               }
+              if (response?.errored || response?.failed) {
+                fetchDiagnostics.signalFailures++;
+                fetchDiagnostics.updatedAt = Date.now();
+                this.recordFetchClientError(
+                  fetchId,
+                  serviceName,
+                  URL,
+                  response?.__error ?? response?.error ?? "Signal transmission failed"
+                );
+              }
             } catch (e) {
               console.error("Error in transmission", e);
+              fetchDiagnostics.signalFailures++;
+              fetchDiagnostics.updatedAt = Date.now();
+              this.recordFetchClientError(fetchId, serviceName, URL, e);
               response = {
                 __error: `Error: ${e}`,
                 errored: true,
@@ -1545,6 +1881,8 @@ var RestController = class _RestController {
         const statusTask = CadenzaService.createMetaTask(
           `Request status from ${URL}`,
           async (ctx2) => {
+            fetchDiagnostics.statusChecks++;
+            fetchDiagnostics.updatedAt = Date.now();
             let status;
             try {
               status = await this.fetchDataWithTimeout(
@@ -1554,7 +1892,20 @@ var RestController = class _RestController {
                 },
                 1e3
               );
+              if (status?.errored || status?.failed) {
+                fetchDiagnostics.statusFailures++;
+                fetchDiagnostics.updatedAt = Date.now();
+                this.recordFetchClientError(
+                  fetchId,
+                  serviceName,
+                  URL,
+                  status?.__error ?? status?.error ?? "Status check failed"
+                );
+              }
             } catch (e) {
+              fetchDiagnostics.statusFailures++;
+              fetchDiagnostics.updatedAt = Date.now();
+              this.recordFetchClientError(fetchId, serviceName, URL, e);
               status = {
                 __error: `Error: ${e}`,
                 errored: true,
@@ -1566,6 +1917,9 @@ var RestController = class _RestController {
           "Requests status"
         ).doOn("meta.fetch.status_check_requested").emits("meta.fetch.status_checked").emitsOnFail("meta.fetch.status_check_failed");
         CadenzaService.createEphemeralMetaTask("Destroy fetch client", () => {
+          fetchDiagnostics.connected = false;
+          fetchDiagnostics.destroyed = true;
+          fetchDiagnostics.updatedAt = Date.now();
           CadenzaService.log("Destroying fetch client", { URL, serviceName });
           handshakeTask.destroy();
           delegateTask.destroy();
@@ -1614,6 +1968,144 @@ var RestController = class _RestController {
     if (!this._instance) this._instance = new _RestController();
     return this._instance;
   }
+  resolveTransportDiagnosticsOptions(ctx) {
+    const detailLevel = ctx.detailLevel === "full" ? "full" : "summary";
+    const includeErrorHistory = Boolean(ctx.includeErrorHistory);
+    const requestedLimit = Number(ctx.errorHistoryLimit);
+    const errorHistoryLimit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(200, Math.trunc(requestedLimit))) : 10;
+    return {
+      detailLevel,
+      includeErrorHistory,
+      errorHistoryLimit
+    };
+  }
+  ensureFetchClientDiagnostics(fetchId, serviceName, url) {
+    let state = this.fetchClientDiagnostics.get(fetchId);
+    if (!state) {
+      state = {
+        fetchId,
+        serviceName,
+        url,
+        connected: false,
+        destroyed: false,
+        lastHandshakeAt: null,
+        lastHandshakeError: null,
+        lastError: null,
+        lastErrorAt: 0,
+        errorHistory: [],
+        delegationRequests: 0,
+        delegationFailures: 0,
+        signalTransmissions: 0,
+        signalFailures: 0,
+        statusChecks: 0,
+        statusFailures: 0,
+        updatedAt: Date.now()
+      };
+      this.fetchClientDiagnostics.set(fetchId, state);
+    } else {
+      state.serviceName = serviceName;
+      state.url = url;
+    }
+    return state;
+  }
+  getErrorMessage(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    if (typeof error === "string") {
+      return error;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  recordFetchClientError(fetchId, serviceName, url, error) {
+    const state = this.ensureFetchClientDiagnostics(fetchId, serviceName, url);
+    const message = this.getErrorMessage(error);
+    const now = Date.now();
+    state.lastError = message;
+    state.lastErrorAt = now;
+    state.updatedAt = now;
+    state.errorHistory.push({ at: new Date(now).toISOString(), message });
+    if (state.errorHistory.length > this.diagnosticsErrorHistoryLimit) {
+      state.errorHistory.splice(
+        0,
+        state.errorHistory.length - this.diagnosticsErrorHistoryLimit
+      );
+    }
+  }
+  collectFetchTransportDiagnostics(ctx) {
+    const { detailLevel, includeErrorHistory, errorHistoryLimit } = this.resolveTransportDiagnosticsOptions(ctx);
+    const serviceName = CadenzaService.serviceRegistry.serviceName ?? "UnknownService";
+    const states = Array.from(this.fetchClientDiagnostics.values()).sort(
+      (a, b) => a.fetchId.localeCompare(b.fetchId)
+    );
+    const summary = {
+      detailLevel,
+      totalClients: states.length,
+      connectedClients: states.filter((state) => state.connected).length,
+      destroyedClients: states.filter((state) => state.destroyed).length,
+      delegationRequests: states.reduce(
+        (acc, state) => acc + state.delegationRequests,
+        0
+      ),
+      delegationFailures: states.reduce(
+        (acc, state) => acc + state.delegationFailures,
+        0
+      ),
+      signalTransmissions: states.reduce(
+        (acc, state) => acc + state.signalTransmissions,
+        0
+      ),
+      signalFailures: states.reduce((acc, state) => acc + state.signalFailures, 0),
+      statusChecks: states.reduce((acc, state) => acc + state.statusChecks, 0),
+      statusFailures: states.reduce((acc, state) => acc + state.statusFailures, 0),
+      latestError: states.slice().sort((a, b) => b.lastErrorAt - a.lastErrorAt).find((state) => state.lastError)?.lastError ?? null
+    };
+    if (detailLevel === "summary") {
+      return {
+        transportDiagnostics: {
+          [serviceName]: {
+            fetchClient: summary
+          }
+        }
+      };
+    }
+    const clients = states.map((state) => {
+      const details = {
+        fetchId: state.fetchId,
+        serviceName: state.serviceName,
+        url: state.url,
+        connected: state.connected,
+        destroyed: state.destroyed,
+        lastHandshakeAt: state.lastHandshakeAt,
+        lastHandshakeError: state.lastHandshakeError,
+        latestError: state.lastError,
+        delegationRequests: state.delegationRequests,
+        delegationFailures: state.delegationFailures,
+        signalTransmissions: state.signalTransmissions,
+        signalFailures: state.signalFailures,
+        statusChecks: state.statusChecks,
+        statusFailures: state.statusFailures
+      };
+      if (includeErrorHistory) {
+        details.errorHistory = state.errorHistory.slice(-errorHistoryLimit);
+      }
+      return details;
+    });
+    return {
+      transportDiagnostics: {
+        [serviceName]: {
+          fetchClient: {
+            ...summary,
+            clients
+          }
+        }
+      }
+    };
+  }
 };
 
 // src/network/SocketController.ts
@@ -1661,10 +2153,6 @@ var waitForSocketConnection = async (socket, timeoutMs, createError) => {
 
 // src/network/SocketController.ts
 var SocketController = class _SocketController {
-  static get instance() {
-    if (!this._instance) this._instance = new _SocketController();
-    return this._instance;
-  }
   /**
    * Constructs the `SocketServer`, setting up a WebSocket server with specific configurations,
    * including connection state recovery, rate limiting, CORS handling, and custom event handling.
@@ -1683,6 +2171,13 @@ var SocketController = class _SocketController {
    * Initializes the `SocketServer` to be ready for WebSocket communication.
    */
   constructor() {
+    this.socketClientDiagnostics = /* @__PURE__ */ new Map();
+    this.diagnosticsErrorHistoryLimit = 100;
+    CadenzaService.createMetaTask(
+      "Collect socket transport diagnostics",
+      (ctx) => this.collectSocketTransportDiagnostics(ctx),
+      "Responds to distributed transport diagnostics inquiries with socket client data."
+    ).respondsTo(META_RUNTIME_TRANSPORT_DIAGNOSTICS_INTENT);
     CadenzaService.createMetaRoutine(
       "SocketServer",
       [
@@ -1910,6 +2405,13 @@ var SocketController = class _SocketController {
         const port = protocol === "https" ? 443 : servicePort;
         const URL = `${socketProtocol}://${serviceAddress}:${port}`;
         const fetchId = `${serviceAddress}_${port}`;
+        const socketDiagnostics = this.ensureSocketClientDiagnostics(
+          fetchId,
+          serviceName,
+          URL
+        );
+        socketDiagnostics.destroyed = false;
+        socketDiagnostics.updatedAt = Date.now();
         let handshake = false;
         let errorCount = 0;
         const ERROR_LIMIT = 5;
@@ -1919,6 +2421,11 @@ var SocketController = class _SocketController {
         }
         const pendingDelegationIds = /* @__PURE__ */ new Set();
         const pendingTimers = /* @__PURE__ */ new Set();
+        const syncPendingCounts = () => {
+          socketDiagnostics.pendingDelegations = pendingDelegationIds.size;
+          socketDiagnostics.pendingTimers = pendingTimers.size;
+          socketDiagnostics.updatedAt = Date.now();
+        };
         let handshakeTask = null;
         let emitWhenReady = null;
         let transmitTask = null;
@@ -1968,6 +2475,12 @@ var SocketController = class _SocketController {
                   { socketId: socket?.id, serviceName, URL, event },
                   "error"
                 );
+                this.recordSocketClientError(
+                  fetchId,
+                  serviceName,
+                  URL,
+                  waitResult.error
+                );
                 resolveWithError(waitResult.error);
                 return;
               }
@@ -1976,6 +2489,7 @@ var SocketController = class _SocketController {
                 timer = setTimeout(() => {
                   if (timer) {
                     pendingTimers.delete(timer);
+                    syncPendingCounts();
                     timer = null;
                   }
                   CadenzaService.log(
@@ -1983,9 +2497,16 @@ var SocketController = class _SocketController {
                     { socketId: socket?.id, serviceName, URL },
                     "error"
                   );
+                  this.recordSocketClientError(
+                    fetchId,
+                    serviceName,
+                    URL,
+                    `Socket event '${event}' timed out`
+                  );
                   resolveWithError(`Socket event '${event}' timed out`);
                 }, timeoutMs + 10);
                 pendingTimers.add(timer);
+                syncPendingCounts();
               }
               const connectedSocket = socket;
               if (!connectedSocket) {
@@ -1998,6 +2519,7 @@ var SocketController = class _SocketController {
                 if (timer) {
                   clearTimeout(timer);
                   pendingTimers.delete(timer);
+                  syncPendingCounts();
                   timer = null;
                 }
                 if (err) {
@@ -2011,6 +2533,12 @@ var SocketController = class _SocketController {
                     },
                     "warning"
                   );
+                  this.recordSocketClientError(
+                    fetchId,
+                    serviceName,
+                    URL,
+                    err
+                  );
                   response = {
                     __error: `Timeout error: ${err}`,
                     errored: true,
@@ -2027,6 +2555,10 @@ var SocketController = class _SocketController {
         };
         socket.on("connect", () => {
           if (handshake) return;
+          socketDiagnostics.connected = true;
+          socketDiagnostics.destroyed = false;
+          socketDiagnostics.socketId = socket?.id ?? null;
+          socketDiagnostics.updatedAt = Date.now();
           CadenzaService.emit(`meta.socket_client.connected:${fetchId}`, ctx);
         });
         socket.on("delegation_progress", (ctx2) => {
@@ -2045,6 +2577,12 @@ var SocketController = class _SocketController {
         });
         socket.on("connect_error", (err) => {
           handshake = false;
+          socketDiagnostics.connected = false;
+          socketDiagnostics.handshake = false;
+          socketDiagnostics.connectErrors++;
+          socketDiagnostics.lastHandshakeError = err.message;
+          socketDiagnostics.updatedAt = Date.now();
+          this.recordSocketClientError(fetchId, serviceName, URL, err);
           CadenzaService.log(
             "Socket connect error",
             { error: err.message, serviceName, socketId: socket?.id, URL },
@@ -2053,9 +2591,16 @@ var SocketController = class _SocketController {
           CadenzaService.emit(`meta.socket_client.connect_error:${fetchId}`, err);
         });
         socket.on("reconnect_attempt", (attempt) => {
+          socketDiagnostics.reconnectAttempts = Math.max(
+            socketDiagnostics.reconnectAttempts,
+            attempt
+          );
+          socketDiagnostics.updatedAt = Date.now();
           CadenzaService.log(`Reconnect attempt: ${attempt}`);
         });
         socket.on("reconnect", (attempt) => {
+          socketDiagnostics.connected = true;
+          socketDiagnostics.updatedAt = Date.now();
           CadenzaService.log(`Socket reconnected after ${attempt} tries`, {
             socketId: socket?.id,
             URL,
@@ -2064,6 +2609,12 @@ var SocketController = class _SocketController {
         });
         socket.on("reconnect_error", (err) => {
           handshake = false;
+          socketDiagnostics.connected = false;
+          socketDiagnostics.handshake = false;
+          socketDiagnostics.reconnectErrors++;
+          socketDiagnostics.lastHandshakeError = err.message;
+          socketDiagnostics.updatedAt = Date.now();
+          this.recordSocketClientError(fetchId, serviceName, URL, err);
           CadenzaService.log(
             "Socket reconnect failed.",
             { error: err.message, serviceName, URL, socketId: socket?.id },
@@ -2072,6 +2623,9 @@ var SocketController = class _SocketController {
         });
         socket.on("error", (err) => {
           errorCount++;
+          socketDiagnostics.socketErrors++;
+          socketDiagnostics.updatedAt = Date.now();
+          this.recordSocketClientError(fetchId, serviceName, URL, err);
           CadenzaService.log(
             "Socket error",
             { error: err, socketId: socket?.id, URL, serviceName },
@@ -2080,6 +2634,11 @@ var SocketController = class _SocketController {
           CadenzaService.emit("meta.socket_client.error", err);
         });
         socket.on("disconnect", () => {
+          const disconnectedAt = (/* @__PURE__ */ new Date()).toISOString();
+          socketDiagnostics.connected = false;
+          socketDiagnostics.handshake = false;
+          socketDiagnostics.lastDisconnectAt = disconnectedAt;
+          socketDiagnostics.updatedAt = Date.now();
           CadenzaService.log(
             "Socket disconnected.",
             { URL, serviceName, socketId: socket?.id },
@@ -2098,6 +2657,8 @@ var SocketController = class _SocketController {
           async (ctx2, emit) => {
             if (handshake) return;
             handshake = true;
+            socketDiagnostics.handshake = true;
+            socketDiagnostics.updatedAt = Date.now();
             await emitWhenReady?.(
               "handshake",
               {
@@ -2109,6 +2670,11 @@ var SocketController = class _SocketController {
               1e4,
               (result) => {
                 if (result.status === "success") {
+                  socketDiagnostics.connected = true;
+                  socketDiagnostics.handshake = true;
+                  socketDiagnostics.lastHandshakeAt = (/* @__PURE__ */ new Date()).toISOString();
+                  socketDiagnostics.lastHandshakeError = null;
+                  socketDiagnostics.updatedAt = Date.now();
                   CadenzaService.log("Socket client connected", {
                     result,
                     serviceName,
@@ -2116,6 +2682,16 @@ var SocketController = class _SocketController {
                     URL
                   });
                 } else {
+                  socketDiagnostics.connected = false;
+                  socketDiagnostics.handshake = false;
+                  socketDiagnostics.lastHandshakeError = result?.__error ?? result?.error ?? "Socket handshake failed";
+                  socketDiagnostics.updatedAt = Date.now();
+                  this.recordSocketClientError(
+                    fetchId,
+                    serviceName,
+                    URL,
+                    socketDiagnostics.lastHandshakeError
+                  );
                   CadenzaService.log(
                     "Socket handshake failed",
                     { result, serviceName, socketId: socket?.id, URL },
@@ -2138,6 +2714,7 @@ var SocketController = class _SocketController {
               delete ctx2.__broadcast;
               const requestSentAt = Date.now();
               pendingDelegationIds.add(ctx2.__metadata.__deputyExecId);
+              syncPendingCounts();
               emitWhenReady?.(
                 "delegation",
                 ctx2,
@@ -2155,6 +2732,15 @@ var SocketController = class _SocketController {
                     }
                   );
                   pendingDelegationIds.delete(ctx2.__metadata.__deputyExecId);
+                  syncPendingCounts();
+                  if (resultContext?.errored || resultContext?.failed) {
+                    this.recordSocketClientError(
+                      fetchId,
+                      serviceName,
+                      URL,
+                      resultContext?.__error ?? resultContext?.error ?? "Socket delegation failed"
+                    );
+                  }
                   resolve(resultContext);
                 }
               );
@@ -2190,6 +2776,10 @@ var SocketController = class _SocketController {
           `Shutdown SocketClient ${URL}`,
           (ctx2, emit) => {
             handshake = false;
+            socketDiagnostics.connected = false;
+            socketDiagnostics.handshake = false;
+            socketDiagnostics.destroyed = true;
+            socketDiagnostics.updatedAt = Date.now();
             CadenzaService.log("Shutting down socket client", { URL, serviceName });
             socket?.close();
             handshakeTask?.destroy();
@@ -2219,10 +2809,12 @@ var SocketController = class _SocketController {
               });
             }
             pendingDelegationIds.clear();
+            syncPendingCounts();
             for (const timer of pendingTimers) {
               clearTimeout(timer);
             }
             pendingTimers.clear();
+            syncPendingCounts();
           },
           "Shuts down the socket client"
         ).doOn(
@@ -2236,6 +2828,157 @@ var SocketController = class _SocketController {
       "Connects to a specified socket server"
     ).doOn("meta.fetch.handshake_complete").emitsOnFail("meta.socket_client.connect_failed");
   }
+  static get instance() {
+    if (!this._instance) this._instance = new _SocketController();
+    return this._instance;
+  }
+  resolveTransportDiagnosticsOptions(ctx) {
+    const detailLevel = ctx.detailLevel === "full" ? "full" : "summary";
+    const includeErrorHistory = Boolean(ctx.includeErrorHistory);
+    const requestedLimit = Number(ctx.errorHistoryLimit);
+    const errorHistoryLimit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(200, Math.trunc(requestedLimit))) : 10;
+    return {
+      detailLevel,
+      includeErrorHistory,
+      errorHistoryLimit
+    };
+  }
+  ensureSocketClientDiagnostics(fetchId, serviceName, url) {
+    let state = this.socketClientDiagnostics.get(fetchId);
+    if (!state) {
+      state = {
+        fetchId,
+        serviceName,
+        url,
+        socketId: null,
+        connected: false,
+        handshake: false,
+        reconnectAttempts: 0,
+        connectErrors: 0,
+        reconnectErrors: 0,
+        socketErrors: 0,
+        pendingDelegations: 0,
+        pendingTimers: 0,
+        destroyed: false,
+        lastHandshakeAt: null,
+        lastHandshakeError: null,
+        lastDisconnectAt: null,
+        lastError: null,
+        lastErrorAt: 0,
+        errorHistory: [],
+        updatedAt: Date.now()
+      };
+      this.socketClientDiagnostics.set(fetchId, state);
+    } else {
+      state.serviceName = serviceName;
+      state.url = url;
+    }
+    return state;
+  }
+  getErrorMessage(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    if (typeof error === "string") {
+      return error;
+    }
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  recordSocketClientError(fetchId, serviceName, url, error) {
+    const state = this.ensureSocketClientDiagnostics(fetchId, serviceName, url);
+    const message = this.getErrorMessage(error);
+    const now = Date.now();
+    state.lastError = message;
+    state.lastErrorAt = now;
+    state.updatedAt = now;
+    state.errorHistory.push({
+      at: new Date(now).toISOString(),
+      message
+    });
+    if (state.errorHistory.length > this.diagnosticsErrorHistoryLimit) {
+      state.errorHistory.splice(
+        0,
+        state.errorHistory.length - this.diagnosticsErrorHistoryLimit
+      );
+    }
+  }
+  collectSocketTransportDiagnostics(ctx) {
+    const { detailLevel, includeErrorHistory, errorHistoryLimit } = this.resolveTransportDiagnosticsOptions(ctx);
+    const serviceName = CadenzaService.serviceRegistry.serviceName ?? "UnknownService";
+    const states = Array.from(this.socketClientDiagnostics.values()).sort(
+      (a, b) => a.fetchId.localeCompare(b.fetchId)
+    );
+    const summary = {
+      detailLevel,
+      totalClients: states.length,
+      connectedClients: states.filter((state) => state.connected).length,
+      activeHandshakes: states.filter((state) => state.handshake).length,
+      pendingDelegations: states.reduce(
+        (acc, state) => acc + state.pendingDelegations,
+        0
+      ),
+      pendingTimers: states.reduce((acc, state) => acc + state.pendingTimers, 0),
+      reconnectAttempts: states.reduce(
+        (acc, state) => acc + state.reconnectAttempts,
+        0
+      ),
+      connectErrors: states.reduce((acc, state) => acc + state.connectErrors, 0),
+      reconnectErrors: states.reduce(
+        (acc, state) => acc + state.reconnectErrors,
+        0
+      ),
+      socketErrors: states.reduce((acc, state) => acc + state.socketErrors, 0),
+      latestError: states.slice().sort((a, b) => b.lastErrorAt - a.lastErrorAt).find((state) => state.lastError)?.lastError ?? null
+    };
+    if (detailLevel === "summary") {
+      return {
+        transportDiagnostics: {
+          [serviceName]: {
+            socketClient: summary
+          }
+        }
+      };
+    }
+    const clients = states.map((state) => {
+      const details = {
+        fetchId: state.fetchId,
+        serviceName: state.serviceName,
+        url: state.url,
+        socketId: state.socketId,
+        connected: state.connected,
+        handshake: state.handshake,
+        reconnectAttempts: state.reconnectAttempts,
+        connectErrors: state.connectErrors,
+        reconnectErrors: state.reconnectErrors,
+        socketErrors: state.socketErrors,
+        pendingDelegations: state.pendingDelegations,
+        pendingTimers: state.pendingTimers,
+        destroyed: state.destroyed,
+        lastHandshakeAt: state.lastHandshakeAt,
+        lastHandshakeError: state.lastHandshakeError,
+        lastDisconnectAt: state.lastDisconnectAt,
+        latestError: state.lastError
+      };
+      if (includeErrorHistory) {
+        details.errorHistory = state.errorHistory.slice(-errorHistoryLimit);
+      }
+      return details;
+    });
+    return {
+      transportDiagnostics: {
+        [serviceName]: {
+          socketClient: {
+            ...summary,
+            clients
+          }
+        }
+      }
+    };
+  }
 };
 
 // src/utils/tools.ts
@@ -2339,25 +3082,8 @@ var GraphMetadataController = class _GraphMetadataController {
       return {
         data: {
           ...ctx.data,
-          serviceName: CadenzaService.serviceRegistry.serviceName,
-          inputContextSchemaId: ctx.data.inputContextSchemaId ? {
-            subOperation: "insert",
-            table: "context_schema",
-            data: {
-              ...ctx.data.inputContextSchemaId
-            },
-            return: "uuid"
-          } : null,
-          outputContextSchemaId: ctx.data.outputContextSchemaId ? {
-            subOperation: "insert",
-            table: "context_schema",
-            data: {
-              ...ctx.data.outputContextSchemaId
-            },
-            return: "uuid"
-          } : null
-        },
-        transaction: true
+          serviceName: CadenzaService.serviceRegistry.serviceName
+        }
       };
     }).doOn("meta.task.created").emits("global.meta.graph_metadata.task_created");
     CadenzaService.createMetaTask("Handle task update", (ctx) => {
@@ -2564,9 +3290,11 @@ var GraphMetadataController = class _GraphMetadataController {
       { concurrency: 100, isSubMeta: true }
     ).doOn("meta.node.mapped", "meta.node.detected_previous_task_execution").emits("global.meta.graph_metadata.relationship_executed");
     CadenzaService.createMetaTask("Handle Intent Creation", (ctx) => {
+      const intentName = ctx.data?.name;
       return {
         data: {
-          ...ctx.data
+          ...ctx.data,
+          isMeta: intentName ? isMetaIntentName(intentName) : false
         }
       };
     }).doOn("meta.inquiry_broker.added").emits("global.meta.graph_metadata.intent_created");
@@ -2598,6 +3326,52 @@ var SCHEMA_TYPES = [
 // src/database/DatabaseController.ts
 import { Pool } from "pg";
 import { camelCase, snakeCase } from "lodash-es";
+function resolveTableQueryIntents(serviceName, tableName, table, defaultInputSchema) {
+  const resolvedServiceName = serviceName ?? "unknown-service";
+  const defaultIntentName = `query-${resolvedServiceName}-${tableName}`;
+  const defaultDescription = `Perform a query operation on the ${tableName} table`;
+  const intents = [
+    {
+      name: defaultIntentName,
+      description: defaultDescription,
+      input: defaultInputSchema
+    }
+  ];
+  const warnings = [];
+  const names = /* @__PURE__ */ new Set([defaultIntentName]);
+  for (const customIntent of table.customIntents?.query ?? []) {
+    const name = typeof customIntent === "string" ? customIntent.trim() : customIntent.intent?.trim();
+    if (!name) {
+      warnings.push(`Skipped empty custom query intent for table '${tableName}'.`);
+      continue;
+    }
+    if (name.length > 100) {
+      warnings.push(
+        `Skipped custom query intent '${name}' for table '${tableName}': name must be <= 100 characters.`
+      );
+      continue;
+    }
+    if (name.includes(" ") || name.includes(".") || name.includes("\\")) {
+      warnings.push(
+        `Skipped custom query intent '${name}' for table '${tableName}': name cannot contain spaces, dots or backslashes.`
+      );
+      continue;
+    }
+    if (names.has(name)) {
+      warnings.push(
+        `Skipped duplicate custom query intent '${name}' for table '${tableName}'.`
+      );
+      continue;
+    }
+    names.add(name);
+    intents.push({
+      name,
+      description: typeof customIntent === "string" ? `Perform a query operation on the ${tableName} table` : customIntent.description ?? defaultDescription,
+      input: typeof customIntent === "string" ? defaultInputSchema : customIntent.input ?? defaultInputSchema
+    });
+  }
+  return { intents, warnings };
+}
 var DatabaseController = class _DatabaseController {
   /**
    * Constructor for initializing the `DatabaseService` class.
@@ -2739,6 +3513,20 @@ var DatabaseController = class _DatabaseController {
                       }
                     }
                   }
+                  if (table.customIntents?.query) {
+                    if (!Array.isArray(table.customIntents.query)) {
+                      throw new Error(
+                        `Invalid customIntents.query for ${tableName}: expected array`
+                      );
+                    }
+                    for (const customIntent of table.customIntents.query) {
+                      if (typeof customIntent !== "string" && (typeof customIntent !== "object" || !customIntent || typeof customIntent.intent !== "string")) {
+                        throw new Error(
+                          `Invalid custom query intent on ${tableName}: expected string or object with intent`
+                        );
+                      }
+                    }
+                  }
                 }
               }
               console.log("SCHEMA VALIDATED");
@@ -3775,13 +4563,30 @@ var DatabaseController = class _DatabaseController {
       }) ?? []
     );
     if (op === "query") {
-      const intentName = `query-${CadenzaService.serviceRegistry.serviceName}-${tableName}`;
-      CadenzaService.defineIntent({
-        name: intentName,
-        description: `Perform a query operation on the ${tableName} table`,
-        input: schema
-      });
-      task.respondsTo(intentName);
+      const { intents, warnings } = resolveTableQueryIntents(
+        CadenzaService.serviceRegistry?.serviceName,
+        tableName,
+        table,
+        schema
+      );
+      for (const warning of warnings) {
+        CadenzaService.log(
+          "Skipped custom query intent registration.",
+          {
+            tableName,
+            warning
+          },
+          "warning"
+        );
+      }
+      for (const intent of intents) {
+        CadenzaService.defineIntent({
+          name: intent.name,
+          description: intent.description,
+          input: intent.input
+        });
+      }
+      task.respondsTo(...intents.map((intent) => intent.name));
     }
   }
   getInputSchema(op, tableName, table) {
@@ -3873,18 +4678,18 @@ function getInsertDataSchemaFromTable(table, tableName) {
         Object.entries(table.fields).map((field) => {
           return [
             field[0],
-            [
-              {
+            {
+              value: {
                 type: tableFieldTypeToSchemaType(field[1].type),
                 description: `Inferred from field '${field[0]}' of type [${field[1].type}] on table ${tableName}.`
               },
-              {
+              effect: {
                 type: "string",
                 constraints: {
                   oneOf: ["increment", "decrement", "set"]
                 }
               },
-              {
+              subOperation: {
                 type: "object",
                 properties: {
                   subOperation: {
@@ -3894,17 +4699,17 @@ function getInsertDataSchemaFromTable(table, tableName) {
                   table: {
                     type: "string"
                   },
-                  data: [
-                    {
+                  data: {
+                    single: {
                       type: "object"
                     },
-                    {
+                    batch: {
                       type: "array",
                       items: {
                         type: "object"
                       }
                     }
-                  ],
+                  },
                   filter: {
                     type: "object"
                   },
@@ -3920,7 +4725,7 @@ function getInsertDataSchemaFromTable(table, tableName) {
                 },
                 required: ["subOperation", "table"]
               }
-            ]
+            }
           ];
         })
       )
@@ -3928,13 +4733,13 @@ function getInsertDataSchemaFromTable(table, tableName) {
     required: Object.entries(table.fields).filter((field) => field[1].required || field[1].primary).map((field) => field[0]),
     strict: true
   };
-  return [
-    dataSchema,
-    {
+  return {
+    single: dataSchema,
+    batch: {
       type: "array",
       items: dataSchema
     }
-  ];
+  };
 }
 function getQueryFilterSchemaFromTable(table, tableName) {
   return {
@@ -3944,24 +4749,24 @@ function getQueryFilterSchemaFromTable(table, tableName) {
         Object.entries(table.fields).map((field) => {
           return [
             field[0],
-            [
-              {
+            {
+              value: {
                 type: tableFieldTypeToSchemaType(field[1].type),
                 description: `Inferred from field '${field[0]}' of type [${field[1].type}] on table ${tableName}.`
               },
-              {
+              in: {
                 type: "array",
                 items: {
                   type: tableFieldTypeToSchemaType(field[1].type)
                 }
               }
-            ]
+            }
           ];
         })
       )
     },
     strict: true,
-    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry.serviceName}.`
+    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry?.serviceName ?? "unknown-service"}.`
   };
 }
 function getQueryFieldsSchemaFromTable(table, tableName) {
@@ -3973,7 +4778,7 @@ function getQueryFieldsSchemaFromTable(table, tableName) {
         oneOf: Object.keys(table.fields)
       }
     },
-    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry.serviceName}.`
+    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry?.serviceName ?? "unknown-service"}.`
   };
 }
 function getQueryJoinsSchemaFromTable(table, tableName) {
@@ -4020,7 +4825,7 @@ function getQueryJoinsSchemaFromTable(table, tableName) {
       )
     },
     strict: true,
-    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry.serviceName}.`
+    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry?.serviceName ?? "unknown-service"}.`
   };
 }
 function getQuerySortSchemaFromTable(table, tableName) {
@@ -4042,7 +4847,7 @@ function getQuerySortSchemaFromTable(table, tableName) {
       )
     },
     strict: true,
-    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry.serviceName}.`
+    description: `Inferred from table '${tableName}' on database service ${CadenzaService.serviceRegistry?.serviceName ?? "unknown-service"}.`
   };
 }
 function getQueryLimitSchemaFromTable() {
@@ -4104,12 +4909,10 @@ function getQueryOnConflictSchemaFromTable(table, tableName) {
                 Object.entries(table.fields).map((field) => {
                   return [
                     field[0],
-                    [
-                      {
-                        type: tableFieldTypeToSchemaType(field[1].type),
-                        description: `Inferred from field '${field[0]}' of type [${field[1].type}] on table ${tableName}.`
-                      }
-                    ]
+                    {
+                      type: tableFieldTypeToSchemaType(field[1].type),
+                      description: `Inferred from field '${field[0]}' of type [${field[1].type}] on table ${tableName}.`
+                    }
                   ];
                 })
               )
@@ -4467,6 +5270,75 @@ var GraphSyncController = class _GraphSyncController {
         { concurrency: 30 }
       ) : CadenzaService.get("dbInsertSignalToTaskMap"))?.then(registerSignalTask)
     );
+    const registerIntentTask = CadenzaService.createMetaTask(
+      "Record intent registration",
+      (ctx) => {
+        if (!ctx.__syncing) {
+          return;
+        }
+        CadenzaService.debounce("meta.sync_controller.synced_resource", {
+          delayMs: 3e3
+        });
+        const task = CadenzaService.get(ctx.__taskName);
+        task.__registeredIntents = task.__registeredIntents ?? /* @__PURE__ */ new Set();
+        task.__registeredIntents.add(ctx.__intent);
+      }
+    );
+    this.registerIntentToTaskMapTask = CadenzaService.createMetaTask(
+      "Split intents of task",
+      function* (ctx) {
+        const task = ctx.task;
+        if (task.hidden || !task.register) return;
+        task.__registeredIntents = task.__registeredIntents ?? /* @__PURE__ */ new Set();
+        task.__invalidMetaIntentWarnings = task.__invalidMetaIntentWarnings ?? /* @__PURE__ */ new Set();
+        for (const intent of task.handlesIntents) {
+          if (task.__registeredIntents.has(intent)) continue;
+          if (isMetaIntentName(intent) && !task.isMeta) {
+            if (!task.__invalidMetaIntentWarnings.has(intent)) {
+              task.__invalidMetaIntentWarnings.add(intent);
+              CadenzaService.log(
+                "Skipping intent-to-task registration: non-meta task cannot handle meta intent.",
+                {
+                  intent,
+                  taskName: task.name,
+                  taskVersion: task.version
+                },
+                "warning"
+              );
+            }
+            continue;
+          }
+          yield {
+            data: {
+              intentName: intent,
+              taskName: task.name,
+              taskVersion: task.version,
+              serviceName: CadenzaService.serviceRegistry.serviceName
+            },
+            __taskName: task.name,
+            __intent: intent
+          };
+        }
+      }
+    ).then(
+      (this.isCadenzaDBReady ? CadenzaService.createCadenzaDBInsertTask(
+        "intent_to_task_map",
+        {
+          onConflict: {
+            target: [
+              "intent_name",
+              "task_name",
+              "task_version",
+              "service_name"
+            ],
+            action: {
+              do: "nothing"
+            }
+          }
+        },
+        { concurrency: 30 }
+      ) : CadenzaService.get("dbInsertIntentToTaskMap"))?.then(registerIntentTask)
+    );
     this.registerTaskMapTask = CadenzaService.createMetaTask(
       "Register task map to DB",
       function* (ctx) {
@@ -4589,6 +5461,7 @@ var GraphSyncController = class _GraphSyncController {
     CadenzaService.registry.doForEachTask.clone().doOn("meta.sync_controller.synced_tasks").then(
       this.registerTaskMapTask,
       this.registerSignalToTaskMapTask,
+      this.registerIntentToTaskMapTask,
       this.registerDeputyRelationshipTask
     );
     CadenzaService.registry.getAllRoutines.clone().doOn("meta.sync_controller.synced_routines").then(this.splitTasksInRoutines);
@@ -4730,11 +5603,192 @@ var CadenzaService = class {
     Cadenza.interval(signal, context, intervalMs, leading, startDateTime);
   }
   static defineIntent(intent) {
-    this.inquiryBroker?.intents.set(intent.name, intent);
+    this.inquiryBroker?.addIntent(intent);
     return intent;
   }
-  static async inquire(inquiry, context, options) {
-    return this.inquiryBroker?.inquire(inquiry, context, options);
+  static getInquiryResponderDescriptor(task) {
+    return this.serviceRegistry.getInquiryResponderDescriptor(task);
+  }
+  static compareInquiryResponders(left, right) {
+    return compareResponderDescriptors(left.descriptor, right.descriptor);
+  }
+  static buildInquirySummary(inquiry, startedAt, statuses, totalResponders) {
+    const counts = summarizeResponderStatuses(statuses);
+    const isMetaInquiry = isMetaIntentName(inquiry);
+    const eligibleResponders = statuses.length;
+    return {
+      inquiry,
+      isMetaInquiry,
+      totalResponders,
+      eligibleResponders,
+      filteredOutResponders: Math.max(0, totalResponders - eligibleResponders),
+      responded: counts.responded,
+      failed: counts.failed,
+      timedOut: counts.timedOut,
+      pending: counts.pending,
+      durationMs: Date.now() - startedAt,
+      responders: statuses
+    };
+  }
+  static async inquire(inquiry, context, options = {}) {
+    this.bootstrap();
+    const observer = this.inquiryBroker?.inquiryObservers.get(inquiry);
+    const allResponders = observer ? Array.from(observer.tasks).map((task) => ({
+      task,
+      descriptor: this.getInquiryResponderDescriptor(task)
+    })) : [];
+    const isMetaInquiry = isMetaIntentName(inquiry);
+    const responders = allResponders.filter(({ task, descriptor }) => {
+      const shouldExecute = shouldExecuteInquiryResponder(inquiry, task.isMeta);
+      if (shouldExecute) {
+        return true;
+      }
+      const warningKey = `${inquiry}|${descriptor.serviceName}|${descriptor.taskName}|${descriptor.taskVersion}|${descriptor.localTaskName}`;
+      if (!this.warnedInvalidMetaIntentResponderKeys.has(warningKey)) {
+        this.warnedInvalidMetaIntentResponderKeys.add(warningKey);
+        this.log(
+          "Skipping non-meta task for meta intent inquiry.",
+          {
+            inquiry,
+            responder: descriptor
+          },
+          "warning",
+          descriptor.serviceName
+        );
+      }
+      return false;
+    });
+    if (responders.length === 0) {
+      return {
+        __inquiryMeta: {
+          inquiry,
+          isMetaInquiry,
+          totalResponders: allResponders.length,
+          eligibleResponders: 0,
+          filteredOutResponders: allResponders.length,
+          responded: 0,
+          failed: 0,
+          timedOut: 0,
+          pending: 0,
+          durationMs: 0,
+          responders: []
+        }
+      };
+    }
+    responders.sort(this.compareInquiryResponders.bind(this));
+    const overallTimeoutMs = options.overallTimeoutMs ?? options.timeout ?? 0;
+    const requireComplete = options.requireComplete ?? false;
+    const perResponderTimeoutMs = options.perResponderTimeoutMs;
+    const startedAt = Date.now();
+    const statuses = [];
+    const statusByTask = /* @__PURE__ */ new Map();
+    for (const responder of responders) {
+      const status = {
+        ...responder.descriptor,
+        status: "timed_out",
+        durationMs: 0
+      };
+      statuses.push(status);
+      statusByTask.set(responder.task, status);
+    }
+    const resultsByTask = /* @__PURE__ */ new Map();
+    const resolverTasks = [];
+    const pending = new Set(responders.map((r) => r.task));
+    const startTimeByTask = /* @__PURE__ */ new Map();
+    this.emit("meta.inquiry_broker.inquire", { inquiry, context });
+    return new Promise((resolve, reject) => {
+      let finalized = false;
+      let timeoutId;
+      const finalize = (timedOut) => {
+        if (finalized) return;
+        finalized = true;
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = void 0;
+        }
+        for (const resolverTask of resolverTasks) {
+          resolverTask.destroy();
+        }
+        if (timedOut && pending.size > 0) {
+          for (const task of pending) {
+            const status = statusByTask.get(task);
+            if (!status) continue;
+            status.status = "timed_out";
+            status.durationMs = Date.now() - (startTimeByTask.get(task) ?? startedAt);
+          }
+        }
+        const fulfilledContexts = responders.filter((responder) => resultsByTask.has(responder.task)).map((responder) => resultsByTask.get(responder.task));
+        const mergedContext = mergeInquiryContexts(fulfilledContexts);
+        const inquiryMeta = this.buildInquirySummary(
+          inquiry,
+          startedAt,
+          statuses,
+          allResponders.length
+        );
+        const responseContext = {
+          ...mergedContext,
+          __inquiryMeta: inquiryMeta
+        };
+        if (requireComplete && (timedOut || inquiryMeta.failed > 0 || inquiryMeta.timedOut > 0 || inquiryMeta.pending > 0)) {
+          reject({
+            ...responseContext,
+            __error: `Inquiry '${inquiry}' did not complete successfully`,
+            errored: true
+          });
+          return;
+        }
+        resolve(responseContext);
+      };
+      if (overallTimeoutMs > 0) {
+        timeoutId = setTimeout(() => finalize(true), overallTimeoutMs);
+      }
+      for (const responder of responders) {
+        const { task, descriptor } = responder;
+        const inquiryId = uuid3();
+        startTimeByTask.set(task, Date.now());
+        const resolverTask = this.createEphemeralMetaTask(
+          `Resolve inquiry ${inquiry} for ${descriptor.localTaskName}`,
+          (resultCtx) => {
+            if (finalized) {
+              return;
+            }
+            pending.delete(task);
+            const status = statusByTask.get(task);
+            if (status) {
+              status.durationMs = Date.now() - (startTimeByTask.get(task) ?? startedAt);
+              if (resultCtx?.errored || resultCtx?.failed) {
+                status.status = "failed";
+                status.error = String(
+                  resultCtx?.__error ?? resultCtx?.error ?? "Inquiry responder failed"
+                );
+              } else {
+                status.status = "fulfilled";
+                resultsByTask.set(task, resultCtx);
+              }
+            }
+            if (pending.size === 0) {
+              finalize(false);
+            }
+          },
+          "Resolves distributed inquiry responder result",
+          { register: false }
+        ).doOn(`meta.node.graph_completed:${inquiryId}`);
+        resolverTasks.push(resolverTask);
+        const executionContext = {
+          ...context,
+          __routineExecId: inquiryId,
+          __isInquiry: true
+        };
+        if (perResponderTimeoutMs !== void 0) {
+          executionContext.__timeout = perResponderTimeoutMs;
+        }
+        if (task.isMeta) {
+          this.metaRunner?.run(task, executionContext);
+        } else {
+          this.runner?.run(task, executionContext);
+        }
+      }
+    });
   }
   /**
    * Executes the given task or graph routine within the provided context using the configured runner.
@@ -5771,6 +6825,7 @@ var CadenzaService = class {
 };
 CadenzaService.isBootstrapped = false;
 CadenzaService.serviceCreated = false;
+CadenzaService.warnedInvalidMetaIntentResponderKeys = /* @__PURE__ */ new Set();
 
 // src/index.ts
 import {