@ultrst-armada/kloks 1.4.3 → 1.4.5

package/packages/orchestrations/dist/index.d.ts

@@ -1,31 +1,13 @@
-import { CounterState, TelemetryEvents } from '@ultrst-armada/kloks/services';
-import { ExecutableBackendFacade, WorkerExecutionBoundary } from '@ultrst-armada/kloks/backend/execution';
-
-/**
- * @file backendExecutionFacade.ts
- * @description Registers backend services on ExecutableBackendFacade and connects BullMQ workers.
- * Enforces SKIPO::STATE_EXECUTION_ARCHITECTURE (Worker-only access to Backend Facade).
- */
-
-declare class WorkspaceBackendFacade extends ExecutableBackendFacade {
-}
-declare const backendFacade: WorkspaceBackendFacade;
-declare const workerExecutionBoundary: WorkerExecutionBoundary;
+import { OrchestrationDefinition } from '@ultrst-armada/krnl';
 
 /**
  * @file index.ts
- * @description @ultrst-armada/kloks/orchestrations — Canonical Orchestrators A & B built on KrnlTS & @ultrst-armada/kloks/services.
- * Orchestrator A: Service A (Pure) -> Service B (Stateful)
- * Orchestrator B: Service B (Stateful) -> Service C (Event-Emitting)
+ * @description @ultrst-armada/kloks/orchestrations — Canonical pure Orchestration Definitions A & B.
+ * STRICT INVARIANT: Kloks is a pure distribution catalog and NEVER owns execution,
+ * queues, workers, schedulers, or dispatchers. Kloks exports pure serializable definitions
+ * conforming to OrchestrationDefinition<TInput, TOutput>.
  */
 
-interface OrchestratorFacade<TInput = unknown, TOutput = unknown> {
-    readonly id: string;
-    readonly name: string;
-    readonly version: string;
-    readonly dependencies: string[];
-    execute(input: TInput): Promise<TOutput>;
-}
 interface OrchestratorAInput {
     a: number;
     b: number;
@@ -33,23 +15,43 @@ interface OrchestratorAInput {
 }
 interface OrchestratorAOutput {
     computed: number;
-    state: CounterState;
+    state: {
+        count: number;
+    };
 }
 /**
- * Orchestrator A: Sequences Service A (Pure Math) -> Service B (Stateful Counter)
+ * Pure serializable definition for Orchestrator A.
+ * Sequences Service A (Pure Math) -> Service B (Stateful Counter).
+ * Free from execution machinery. To be instantiated and executed by Skipo/runtime.
  */
-declare const OrchestratorAFacade: OrchestratorFacade<OrchestratorAInput, OrchestratorAOutput>;
+declare const OrchestratorADefinition: OrchestrationDefinition<OrchestratorAInput, OrchestratorAOutput>;
 interface OrchestratorBInput {
     delta?: number;
     metricName?: string;
 }
 interface OrchestratorBOutput {
-    state: CounterState;
-    emitted: TelemetryEvents['reading'];
+    state: {
+        count: number;
+    };
+    emitted: {
+        metric: string;
+        value: number;
+        timestamp: number;
+    };
 }
 /**
- * Orchestrator B: Sequences Service B (Stateful Counter) -> Service C (Event-Emitting Telemetry)
+ * Pure serializable definition for Orchestrator B.
+ * Sequences Service B (Stateful Counter) -> Service C (Event-Emitting Telemetry).
+ * Free from execution machinery. To be instantiated and executed by Skipo/runtime.
+ */
+declare const OrchestratorBDefinition: OrchestrationDefinition<OrchestratorBInput, OrchestratorBOutput>;
+/**
+ * Pure serializable definition for Audio-Midi Orchestrator.
+ * Sequences MidiService -> AudioHardwareService.
  */
-declare const OrchestratorBFacade: OrchestratorFacade<OrchestratorBInput, OrchestratorBOutput>;
+declare const AudioMidiOrchestratorDefinition: OrchestrationDefinition;
+declare const krnlOrchestratorADefinition: OrchestrationDefinition<OrchestratorAInput, OrchestratorAOutput>;
+declare const krnlOrchestratorBDefinition: OrchestrationDefinition<OrchestratorBInput, OrchestratorBOutput>;
+declare const krnlAudioMidiOrchestratorDefinition: OrchestrationDefinition<unknown, unknown>;
 
-export { OrchestratorAFacade, type OrchestratorAInput, type OrchestratorAOutput, OrchestratorBFacade, type OrchestratorBInput, type OrchestratorBOutput, type OrchestratorFacade, WorkspaceBackendFacade, backendFacade, workerExecutionBoundary };
+export { AudioMidiOrchestratorDefinition, OrchestratorADefinition, type OrchestratorAInput, type OrchestratorAOutput, OrchestratorBDefinition, type OrchestratorBInput, type OrchestratorBOutput, krnlAudioMidiOrchestratorDefinition, krnlOrchestratorADefinition, krnlOrchestratorBDefinition };

package/packages/orchestrations/dist/index.js

@@ -1,214 +1,92 @@
 // src/index.ts
-import {
-  ServiceAFacade,
-  ServiceBFacade,
-  ServiceCFacade
-} from "@ultrst-armada/kloks/services";
-
-// src/worker-facade/backendExecutionFacade.ts
-import {
-  ExecutableBackendFacade,
-  WorkerExecutionBoundary,
-  ServiceDispatcher,
-  createOperationComponent
-} from "@ultrst-armada/kloks/backend/execution";
-import { SKIPO_EXECUTION } from "@ultrst-armada/kloks/state-graph";
-var WorkspaceBackendFacade = class extends ExecutableBackendFacade {
-};
-var backendFacade = new WorkspaceBackendFacade("WorkspaceBackendFacade");
-var projectService = new ServiceDispatcher("project");
-projectService.registerOperation(
-  "list",
-  createOperationComponent("list", async (input) => {
-    const wsId = input && typeof input === "object" && "workspaceId" in input ? input.workspaceId : void 0;
-    const url = wsId ? `/api/workspaces/${encodeURIComponent(wsId)}/graphs` : "/api/projects";
-    const res = await fetch(url);
-    return await res.json();
-  })
-);
-projectService.registerOperation(
-  "get",
-  createOperationComponent("get", async (input) => {
-    const url = input.workspaceId ? `/api/workspaces/${encodeURIComponent(input.workspaceId)}/graphs/${encodeURIComponent(input.id)}` : `/api/projects/${input.id}`;
-    const res = await fetch(url);
-    return await res.json();
-  })
-);
-projectService.registerOperation(
-  "save",
-  createOperationComponent("save", async (input) => {
-    const url = input.workspaceId ? `/api/workspaces/${encodeURIComponent(input.workspaceId)}/graphs/${encodeURIComponent(input.id)}` : `/api/projects/${input.id}`;
-    const res = await fetch(url, {
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input.projectData)
-    });
-    return await res.json();
-  })
-);
-projectService.registerOperation(
-  "create",
-  createOperationComponent("create", async (input) => {
-    const wsId = input?.workspaceId;
-    const url = wsId ? `/api/workspaces/${encodeURIComponent(wsId)}/graphs` : "/api/projects";
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
-    });
-    return await res.json();
-  })
-);
-projectService.registerOperation(
-  "delete",
-  createOperationComponent("delete", async (input) => {
-    const url = input.workspaceId ? `/api/workspaces/${encodeURIComponent(input.workspaceId)}/graphs/${encodeURIComponent(input.id)}` : `/api/projects/${input.id}`;
-    const res = await fetch(url, {
-      method: "DELETE"
-    });
-    return await res.json();
-  })
-);
-var sampleService = new ServiceDispatcher("sample");
-sampleService.registerOperation(
-  "list",
-  createOperationComponent("list", async (input) => {
-    const projectId = input && typeof input === "object" && "projectId" in input ? input.projectId : null;
-    const globalRes = await fetch("/api/samples/global");
-    const globalData = await globalRes.json();
-    let projectSamples = [];
-    if (projectId) {
-      try {
-        const projRes = await fetch(`/api/samples/projects/${encodeURIComponent(projectId)}/samples`);
-        const projData = await projRes.json();
-        projectSamples = projData.samples || [];
-      } catch (err) {
-        console.error("Failed to fetch project samples in facade:", err);
-      }
-    }
-    return {
-      globalSamples: globalData.samples || [],
-      projectSamples
-    };
-  })
-);
-sampleService.registerOperation(
-  "upload",
-  createOperationComponent("upload", async (input) => {
-    const res = await fetch("/api/samples", {
-      method: "POST",
-      body: input
-    });
-    return await res.json();
-  })
-);
-sampleService.registerOperation(
-  "delete",
-  createOperationComponent("delete", async (input) => {
-    const res = await fetch(`/api/samples/${input.id}`, {
-      method: "DELETE"
-    });
-    return await res.json();
-  })
-);
-var assetPoolService = new ServiceDispatcher("asset");
-assetPoolService.registerOperation(
-  "listPool",
-  createOperationComponent("listPool", async (input) => {
-    const params = new URLSearchParams();
-    if (input?.scope) params.set("scope", input.scope);
-    if (input?.projectId) params.set("projectId", input.projectId);
-    const res = await fetch(`/api/assets/pools?${params.toString()}`);
-    return await res.json();
-  })
-);
-assetPoolService.registerOperation(
-  "createFolder",
-  createOperationComponent(
-    "createFolder",
-    async (input) => {
-      const res = await fetch("/api/assets/folder", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(input)
-      });
-      return await res.json();
-    }
-  )
-);
-assetPoolService.registerOperation(
-  "upload",
-  createOperationComponent("upload", async (input) => {
-    const res = await fetch("/api/assets/upload", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(input)
-    });
-    return await res.json();
-  })
-);
-assetPoolService.registerOperation(
-  "delete",
-  createOperationComponent("delete", async (input) => {
-    const params = new URLSearchParams(input);
-    const res = await fetch(`/api/assets/file?${params.toString()}`, {
-      method: "DELETE"
-    });
-    return await res.json();
-  })
-);
-backendFacade.registerService(projectService);
-backendFacade.registerService(sampleService);
-backendFacade.registerService(assetPoolService);
-var workerExecutionBoundary = new WorkerExecutionBoundary("workspace_worker_pool_1", backendFacade);
-SKIPO_EXECUTION.registerWorkerHandler?.(async (command) => {
-  return await workerExecutionBoundary.processJob(command);
-});
-
-// src/index.ts
-var OrchestratorAFacade = {
+var OrchestratorADefinition = {
   id: "kloks.orchestrator.a",
   name: "OrchestratorA",
   version: "1.0.0",
-  dependencies: [ServiceAFacade.id, ServiceBFacade.id],
-  execute: async (input) => {
-    const op = input.operation ?? "add";
-    const mathOut = await ServiceAFacade.execute(op, {
-      a: input.a,
-      b: input.b
-    });
-    const stateOut = await ServiceBFacade.execute("increment", {
-      delta: mathOut.result
-    });
-    return {
-      computed: mathOut.result,
-      state: stateOut
-    };
-  }
+  description: "Pure serializable orchestration definition: Service A -> Service B",
+  scope: "service",
+  dependencies: ["kloks.service.a", "kloks.service.b"],
+  steps: [
+    {
+      id: "step_math",
+      name: "Execute Math Operation",
+      type: "task",
+      target: "kloks.service.a",
+      operation: "add",
+      retryPolicy: {
+        maxAttempts: 2,
+        backoff: "exponential",
+        backoffMs: 50
+      }
+    },
+    {
+      id: "step_counter",
+      name: "Increment Counter",
+      type: "task",
+      target: "kloks.service.b",
+      operation: "increment",
+      dependsOn: ["step_math"]
+    }
+  ]
 };
-var OrchestratorBFacade = {
+var OrchestratorBDefinition = {
   id: "kloks.orchestrator.b",
   name: "OrchestratorB",
   version: "1.0.0",
-  dependencies: [ServiceBFacade.id, ServiceCFacade.id],
-  execute: async (input = {}) => {
-    const state = await ServiceBFacade.execute("increment", {
-      delta: input.delta ?? 1
-    });
-    const emitted = await ServiceCFacade.execute("publishReading", {
-      metric: input.metricName ?? "counter.value",
-      value: state.count
-    });
-    return {
-      state,
-      emitted
-    };
-  }
+  description: "Pure serializable orchestration definition: Service B -> Service C",
+  scope: "service",
+  dependencies: ["kloks.service.b", "kloks.service.c"],
+  steps: [
+    {
+      id: "step_counter",
+      name: "Increment Counter",
+      type: "task",
+      target: "kloks.service.b",
+      operation: "increment"
+    },
+    {
+      id: "step_telemetry",
+      name: "Publish Telemetry Reading",
+      type: "task",
+      target: "kloks.service.c",
+      operation: "publishReading",
+      dependsOn: ["step_counter"]
+    }
+  ]
+};
+var AudioMidiOrchestratorDefinition = {
+  id: "kloks.orchestrator.audioMidi",
+  name: "AudioMidiOrchestrator",
+  version: "1.0.0",
+  description: "Pure serializable orchestration definition: Midi -> AudioHardware",
+  scope: "service",
+  dependencies: ["kloks.midi.subsystem", "kloks.audio.hardware"],
+  steps: [
+    {
+      id: "step_midi",
+      name: "Emit Virtual MIDI",
+      type: "task",
+      target: "kloks.midi.subsystem",
+      operation: "emitVirtualMidi"
+    },
+    {
+      id: "step_audio",
+      name: "Get Audio Hardware State",
+      type: "task",
+      target: "kloks.audio.hardware",
+      operation: "getState",
+      dependsOn: ["step_midi"]
+    }
+  ]
 };
+var krnlOrchestratorADefinition = OrchestratorADefinition;
+var krnlOrchestratorBDefinition = OrchestratorBDefinition;
+var krnlAudioMidiOrchestratorDefinition = AudioMidiOrchestratorDefinition;
 export {
-  OrchestratorAFacade,
-  OrchestratorBFacade,
-  WorkspaceBackendFacade,
-  backendFacade,
-  workerExecutionBoundary
+  AudioMidiOrchestratorDefinition,
+  OrchestratorADefinition,
+  OrchestratorBDefinition,
+  krnlAudioMidiOrchestratorDefinition,
+  krnlOrchestratorADefinition,
+  krnlOrchestratorBDefinition
 };

package/packages/orchestrations/kloks.manifest.json

@@ -8,7 +8,7 @@
       "name": "Orchestrator A (Service A -> Service B)",
       "version": "1.0.0",
       "package": "@kloks/orchestrations",
-      "export": "OrchestratorAFacade",
+      "export": "OrchestratorADefinition",
       "targetTypes": ["BackendFacade.orchestrations"]
     },
     {
@@ -16,7 +16,15 @@
       "name": "Orchestrator B (Service B -> Service C)",
       "version": "1.0.0",
       "package": "@kloks/orchestrations",
-      "export": "OrchestratorBFacade",
+      "export": "OrchestratorBDefinition",
+      "targetTypes": ["BackendFacade.orchestrations"]
+    },
+    {
+      "id": "orchestrator-audio-midi",
+      "name": "Audio-Midi Orchestrator (Midi -> AudioHardware)",
+      "version": "1.0.0",
+      "package": "@kloks/orchestrations",
+      "export": "AudioMidiOrchestratorDefinition",
       "targetTypes": ["BackendFacade.orchestrations"]
     }
   ]

package/packages/orchestrations/package.json

@@ -20,7 +20,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --external @kloks/services --external @kloks/state-graph --external @kloks/backend --external @kloks/backend/execution --external ws",
+    "build": "tsup src/index.ts --format esm --dts --clean --external @kloks/services --external @kloks/state-graph --external @kloks/backend --external ws",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
@@ -30,6 +30,6 @@
     "@kloks/backend": "workspace:*"
   },
   "devDependencies": {
-    "@ultrst-armada/krnl": "^1.0.2"
+    "@ultrst-armada/krnl": "^1.0.3"
   }
 }

package/packages/services/dist/index.d.ts

@@ -315,6 +315,45 @@ declare const SystemDbClientServiceFacade: {
     createInstance: () => _ultrst_armada_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
     execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
 };
+declare const krnlAuthClientServiceDefinition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlAuthClientServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    service: AuthService;
+    ui: _kloks_contracts.ServiceUISchema;
+    createInstance: () => _ultrst_armada_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+declare const krnlStorageClientServiceDefinition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlStorageClientServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    service: StorageService;
+    ui: _kloks_contracts.ServiceUISchema;
+    createInstance: () => _ultrst_armada_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
+declare const krnlSystemDbClientServiceDefinition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlSystemDbClientServiceFacade: {
+    id: string;
+    name: string;
+    version: string;
+    runtime: "client";
+    deployment: "local";
+    definition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+    service: SystemDbService;
+    ui: _kloks_contracts.ServiceUISchema;
+    createInstance: () => _ultrst_armada_krnl.ServiceInstance<Record<string, unknown>, Record<string, unknown>>;
+    execute: <TIn = unknown, TOut = unknown>(op: string, input?: TIn) => Promise<TOut>;
+};
 
 /**
  * @file index.ts
@@ -366,5 +405,16 @@ interface ProtocolExposureHandle {
 }
 declare function exposeServiceD(adapter?: ProtocolAdapter, port?: number): Promise<ProtocolExposureHandle>;
 declare const ServiceDFacade: ServiceFacade;
+declare const krnlServiceADefinition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlServiceAFacade: ServiceFacade<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlServiceBDefinition: ServiceDefinition<CounterState, Record<string, unknown>>;
+declare const krnlServiceBFacade: ServiceFacade<CounterState, Record<string, unknown>>;
+declare const krnlCreateServiceB: typeof createServiceB;
+declare const krnlServiceCDefinition: ServiceDefinition<Record<string, unknown>, TelemetryEvents>;
+declare const krnlServiceCFacade: ServiceFacade<Record<string, unknown>, TelemetryEvents>;
+declare const krnlCreateServiceC: typeof createServiceC;
+declare const krnlServiceDDefinition: ServiceDefinition<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlServiceDFacade: ServiceFacade<Record<string, unknown>, Record<string, unknown>>;
+declare const krnlExposeServiceD: typeof exposeServiceD;
 
-export { AuthClientServiceDefinition, AuthClientServiceFacade, type AuthListener, AuthService, AuthServiceUISchema, CLEAN_DATABASE_CLUSTER, type CounterState, DEFAULT_CONNECTIONS, type IAuthStore, type MathInput, type ProtocolExposureHandle, STORAGE_KEY_CONNECTIONS, ServiceADefinition, ServiceAFacade, ServiceBDefinition, ServiceBFacade, ServiceCDefinition, ServiceCFacade, ServiceDDefinition, ServiceDFacade, type ServiceFacade, StorageClientServiceDefinition, StorageClientServiceFacade, StorageService, StorageServiceUISchema, SystemDbClientServiceDefinition, SystemDbClientServiceFacade, SystemDbService, SystemDbServiceUISchema, type SystemEnvironmentStatus, type SystemTelemetry, type TelemetryEvents, authService, clearSession, createServiceB, createServiceC, createWorkspace, deleteWorkspace, exposeServiceD, fetchWorkspaces, loadDatabase, loginAdmin, loginUser, persistDatabase, register, restoreSession, setActiveWorkspace, setSession, storageService, systemDbService, updateWorkspace, verifyPassword };
+export { AuthClientServiceDefinition, AuthClientServiceFacade, type AuthListener, AuthService, AuthServiceUISchema, CLEAN_DATABASE_CLUSTER, type CounterState, DEFAULT_CONNECTIONS, type IAuthStore, type MathInput, type ProtocolExposureHandle, STORAGE_KEY_CONNECTIONS, ServiceADefinition, ServiceAFacade, ServiceBDefinition, ServiceBFacade, ServiceCDefinition, ServiceCFacade, ServiceDDefinition, ServiceDFacade, type ServiceFacade, StorageClientServiceDefinition, StorageClientServiceFacade, StorageService, StorageServiceUISchema, SystemDbClientServiceDefinition, SystemDbClientServiceFacade, SystemDbService, SystemDbServiceUISchema, type SystemEnvironmentStatus, type SystemTelemetry, type TelemetryEvents, authService, clearSession, createServiceB, createServiceC, createWorkspace, deleteWorkspace, exposeServiceD, fetchWorkspaces, krnlAuthClientServiceDefinition, krnlAuthClientServiceFacade, krnlCreateServiceB, krnlCreateServiceC, krnlExposeServiceD, krnlServiceADefinition, krnlServiceAFacade, krnlServiceBDefinition, krnlServiceBFacade, krnlServiceCDefinition, krnlServiceCFacade, krnlServiceDDefinition, krnlServiceDFacade, krnlStorageClientServiceDefinition, krnlStorageClientServiceFacade, krnlSystemDbClientServiceDefinition, krnlSystemDbClientServiceFacade, loadDatabase, loginAdmin, loginUser, persistDatabase, register, restoreSession, setActiveWorkspace, setSession, storageService, systemDbService, updateWorkspace, verifyPassword };