@ultrst-armada/krnl 1.0.7 → 1.0.9

package/packages/core/dist/index.js

@@ -26,35 +26,6 @@ var ServiceStateStore = class {
   }
 };
 
-// src/events/ServiceEventBus.ts
-var ServiceEventBus = class {
-  handlers = /* @__PURE__ */ new Map();
-  on(event, handler) {
-    if (!this.handlers.has(event)) {
-      this.handlers.set(event, /* @__PURE__ */ new Set());
-    }
-    const set = this.handlers.get(event);
-    set.add(handler);
-    return () => {
-      set.delete(handler);
-    };
-  }
-  emit(event, payload) {
-    const set = this.handlers.get(event);
-    if (!set) return;
-    for (const handler of Array.from(set)) {
-      try {
-        handler(payload);
-      } catch (err) {
-        console.error(`[ServiceEventBus] Handler error for '${event}':`, err);
-      }
-    }
-  }
-  clear() {
-    this.handlers.clear();
-  }
-};
-
 // src/lifecycle/LifecycleManager.ts
 var TRANSITIONS = {
   uninitialized: ["initializing"],
@@ -91,6 +62,227 @@ var LifecycleManager = class {
   }
 };
 
+// src/telemetry/TelemetryController.ts
+import { randomUUID } from "crypto";
+
+// src/telemetry/TelemetryResources.ts
+var runtimeProcess = typeof globalThis !== "undefined" ? globalThis.process : void 0;
+var runtimePerformance = typeof globalThis !== "undefined" ? globalThis.performance : void 0;
+function telemetryNow() {
+  return runtimePerformance?.now ? runtimePerformance.now() : Date.now();
+}
+function sampleResources() {
+  const memory = runtimeProcess?.memoryUsage?.();
+  const cpu = runtimeProcess?.cpuUsage?.();
+  const eventLoop = runtimePerformance?.eventLoopUtilization?.();
+  return {
+    cpuUserMicros: cpu?.user,
+    cpuSystemMicros: cpu?.system,
+    heapUsedBytes: memory?.heapUsed,
+    heapTotalBytes: memory?.heapTotal,
+    rssBytes: memory?.rss,
+    externalBytes: memory?.external,
+    arrayBuffersBytes: memory?.arrayBuffers,
+    eventLoopUtilization: eventLoop?.utilization,
+    scope: memory || cpu || eventLoop ? "process" : "runtime"
+  };
+}
+function deltaResources(start, end) {
+  const delta = (a, b) => a === void 0 || b === void 0 ? void 0 : b - a;
+  return {
+    cpuUserMicros: delta(start.cpuUserMicros, end.cpuUserMicros),
+    cpuSystemMicros: delta(start.cpuSystemMicros, end.cpuSystemMicros),
+    heapUsedBytes: delta(start.heapUsedBytes, end.heapUsedBytes),
+    heapTotalBytes: delta(start.heapTotalBytes, end.heapTotalBytes),
+    rssBytes: delta(start.rssBytes, end.rssBytes),
+    externalBytes: delta(start.externalBytes, end.externalBytes),
+    arrayBuffersBytes: delta(start.arrayBuffersBytes, end.arrayBuffersBytes),
+    eventLoopUtilization: delta(start.eventLoopUtilization, end.eventLoopUtilization),
+    scope: start.scope
+  };
+}
+
+// src/telemetry/TelemetryController.ts
+var id = (prefix) => `${prefix}_${randomUUID()}`;
+function percentiles(values) {
+  if (!values.length) return { min: 0, mean: 0, p50: 0, p90: 0, p95: 0, p99: 0, max: 0 };
+  const sorted = [...values].sort((a, b) => a - b);
+  const pick = (p) => sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * p))];
+  return {
+    min: sorted[0],
+    mean: sorted.reduce((sum, value) => sum + value, 0) / sorted.length,
+    p50: pick(0.5),
+    p90: pick(0.9),
+    p95: pick(0.95),
+    p99: pick(0.99),
+    max: sorted[sorted.length - 1]
+  };
+}
+var TelemetryController = class {
+  constructor(serviceId, options = {}) {
+    this.serviceId = serviceId;
+    this.mode = options.mode ?? "off";
+    this.maxSamples = Math.max(1, options.maxSamples ?? 2048);
+    this.maxRecentInvocations = Math.max(1, options.maxRecentInvocations ?? 100);
+  }
+  serviceId;
+  mode;
+  maxSamples;
+  maxRecentInvocations;
+  samples = [];
+  active = /* @__PURE__ */ new Map();
+  totalInvocationCount = 0;
+  totalSuccessCount = 0;
+  totalErrorCount = 0;
+  lastInvocationAt;
+  enable(mode = "standard") {
+    this.mode = mode;
+  }
+  disable() {
+    this.mode = "off";
+    this.active.clear();
+  }
+  setMode(mode) {
+    this.mode = mode;
+    if (mode === "off") this.active.clear();
+  }
+  getMode() {
+    return this.mode;
+  }
+  status() {
+    return {
+      enabled: this.mode !== "off",
+      mode: this.mode,
+      serviceId: this.serviceId,
+      invocationCount: this.totalInvocationCount,
+      activeInvocations: this.active.size,
+      lastInvocationAt: this.lastInvocationAt
+    };
+  }
+  begin(target, kind, correlationId, parentSpanId) {
+    if (this.mode === "off") {
+      return {
+        invocationId: "",
+        traceId: "",
+        spanId: "",
+        parentSpanId,
+        end: () => void 0
+      };
+    }
+    const invocationId = id("inv");
+    const spanId = id("span");
+    const traceId = parentSpanId ? this.findTraceId(parentSpanId) ?? id("trace") : id("trace");
+    const active = {
+      invocationId,
+      traceId,
+      spanId,
+      parentSpanId,
+      serviceId: this.serviceId,
+      target,
+      kind,
+      correlationId,
+      startedAt: telemetryNow(),
+      resourcesStart: this.mode === "standard" ? void 0 : sampleResources()
+    };
+    this.active.set(invocationId, active);
+    return {
+      invocationId,
+      traceId,
+      spanId,
+      parentSpanId,
+      end: (error) => this.finish(active, error)
+    };
+  }
+  reset() {
+    this.samples.length = 0;
+    this.active.clear();
+    this.totalInvocationCount = 0;
+    this.totalSuccessCount = 0;
+    this.totalErrorCount = 0;
+    this.lastInvocationAt = void 0;
+  }
+  snapshot() {
+    const invocations = this.samples.slice();
+    const durations = invocations.map((item) => item.durationMs);
+    const targetMap = /* @__PURE__ */ new Map();
+    for (const invocation of invocations) {
+      const key = `${invocation.kind}:${invocation.target}`;
+      const group = targetMap.get(key) ?? [];
+      group.push(invocation);
+      targetMap.set(key, group);
+    }
+    const targets = [...targetMap.values()].map((group) => ({
+      target: group[0].target,
+      kind: group[0].kind,
+      count: group.length,
+      successCount: group.filter((item) => item.status === "completed").length,
+      errorCount: group.filter((item) => item.status === "failed").length,
+      durationMs: percentiles(group.map((item) => item.durationMs)),
+      lastInvocationAt: group[group.length - 1]?.completedAt
+    }));
+    return {
+      serviceId: this.serviceId,
+      mode: this.mode,
+      capturedAt: Date.now(),
+      status: this.status(),
+      totals: {
+        invocationCount: this.totalInvocationCount,
+        successCount: this.totalSuccessCount,
+        errorCount: this.totalErrorCount,
+        durationMs: percentiles(durations)
+      },
+      targets,
+      activeInvocations: this.active.size,
+      recentInvocations: invocations.slice(-this.maxRecentInvocations)
+    };
+  }
+  functionality(name) {
+    return this.snapshot().targets.find((target) => target.kind === "functionality" && target.target === name);
+  }
+  functionalities() {
+    return this.snapshot().targets.filter((target) => target.kind === "functionality");
+  }
+  findTraceId(parentSpanId) {
+    for (let index = this.samples.length - 1; index >= 0; index -= 1) {
+      if (this.samples[index].spanId === parentSpanId) return this.samples[index].traceId;
+    }
+    for (const active of this.active.values()) {
+      if (active.spanId === parentSpanId) return active.traceId;
+    }
+    return void 0;
+  }
+  finish(active, error) {
+    if (!this.active.delete(active.invocationId)) return;
+    const completedAt = telemetryNow();
+    const resourcesEnd = this.mode === "standard" ? void 0 : sampleResources();
+    const invocation = {
+      invocationId: active.invocationId,
+      traceId: active.traceId,
+      spanId: active.spanId,
+      parentSpanId: active.parentSpanId,
+      serviceId: active.serviceId,
+      target: active.target,
+      kind: active.kind,
+      correlationId: active.correlationId,
+      startedAt: active.startedAt,
+      completedAt,
+      durationMs: Math.max(0, completedAt - active.startedAt),
+      status: error === void 0 ? "completed" : "failed",
+      error: error === void 0 ? void 0 : {
+        name: error instanceof Error ? error.name : "Error",
+        message: error instanceof Error ? error.message : String(error)
+      },
+      resources: active.resourcesStart && resourcesEnd ? { start: active.resourcesStart, end: resourcesEnd, delta: deltaResources(active.resourcesStart, resourcesEnd) } : void 0
+    };
+    this.samples.push(invocation);
+    this.totalInvocationCount += 1;
+    if (invocation.status === "completed") this.totalSuccessCount += 1;
+    else this.totalErrorCount += 1;
+    if (this.samples.length > this.maxSamples) this.samples.splice(0, this.samples.length - this.maxSamples);
+    this.lastInvocationAt = Date.now();
+  }
+};
+
 // src/services/ServiceInstance.ts
 var ServiceInstance = class {
   constructor(definition) {
@@ -98,8 +290,8 @@ var ServiceInstance = class {
     this.id = definition.id;
     this.name = definition.name;
     this.version = definition.version;
+    this.telemetry = new TelemetryController(this.id);
     this.lifecycle = new LifecycleManager();
-    this.eventBus = new ServiceEventBus();
     if (definition.state) {
       this.stateStore = new ServiceStateStore(definition.state.initial);
     }
@@ -108,8 +300,8 @@ var ServiceInstance = class {
   id;
   name;
   version;
+  telemetry;
   stateStore;
-  eventBus;
   lifecycle;
   initialized = false;
   disposed = false;
@@ -173,7 +365,19 @@ var ServiceInstance = class {
     if (!operation) {
       throw new Error("[Service:" + this.name + "] Operation '" + op + "' not found.");
     }
-    return await operation.handler(input, ctx);
+    if (ctx.metadata?.__krnlTelemetryInternal === true) {
+      return await operation.handler(input, ctx);
+    }
+    const parentSpanId = typeof ctx.metadata?.__krnlTelemetryParentSpanId === "string" ? ctx.metadata.__krnlTelemetryParentSpanId : void 0;
+    const handle = this.telemetry.begin(op, "service", ctx.correlationId, parentSpanId);
+    try {
+      const output = await operation.handler(input, ctx);
+      handle.end();
+      return output;
+    } catch (error) {
+      handle.end(error);
+      throw error;
+    }
   }
   getState() {
     return this.stateStore?.getState() ?? Object.freeze({});
@@ -185,12 +389,6 @@ var ServiceInstance = class {
     }
     this.stateStore.setState(mutation);
   }
-  on(event, handler) {
-    return this.eventBus.on(event, handler);
-  }
-  emit(event, payload) {
-    this.eventBus.emit(event, payload);
-  }
 };
 
 // src/services/ServiceProxy.ts
@@ -211,6 +409,7 @@ var ServiceProxy = class {
     this.id = definition.id;
     this.name = definition.name;
     this.version = definition.version;
+    this.telemetry = new TelemetryController(this.id);
     this.stateCache = { ...definition.state?.initial ?? {} };
   }
   definition;
@@ -219,6 +418,7 @@ var ServiceProxy = class {
   id;
   name;
   version;
+  telemetry;
   stateCache;
   eventHandlers = /* @__PURE__ */ new Map();
   lifecycle = new LifecycleManager();
@@ -276,11 +476,21 @@ var ServiceProxy = class {
       payload: input,
       timestamp: Date.now()
     };
-    const response = await this.adapter.send(this.endpoint, envelope);
-    if (response.error) {
-      throw new Error("[ServiceProxy:" + this.name + "] Remote error: " + response.error);
+    const parentSpanId = typeof ctx.metadata?.__krnlTelemetryParentSpanId === "string" ? ctx.metadata.__krnlTelemetryParentSpanId : void 0;
+    const handle = this.telemetry.begin(op, "service", ctx.correlationId, parentSpanId);
+    try {
+      const response = await this.adapter.send(this.endpoint, envelope);
+      if (response.error) {
+        const error = new Error("[ServiceProxy:" + this.name + "] Remote error: " + response.error);
+        handle.end(error);
+        throw error;
+      }
+      handle.end();
+      return response.payload;
+    } catch (error) {
+      handle.end(error);
+      throw error;
     }
-    return response.payload;
   }
   getState() {
     return Object.freeze({ ...this.stateCache });
@@ -340,12 +550,6 @@ function validateServiceDefinition(definition) {
       throw new Error("[Service:" + definition.name + "] Operation '" + key + "' must define a handler.");
     }
   }
-  for (const [key, event] of Object.entries(definition.events ?? {})) {
-    if (!event || typeof event !== "object") {
-      throw new Error("[Service:" + definition.name + "] Invalid event '" + key + "'.");
-    }
-    assertNonEmptyString(event.name, "events." + key + ".name");
-  }
   for (const [key, schema] of Object.entries(definition.inputs ?? {})) assertRecord(schema, "inputs." + key);
   for (const [key, schema] of Object.entries(definition.outputs ?? {})) assertRecord(schema, "outputs." + key);
   if (definition.state?.schema !== void 0) assertRecord(definition.state.schema, "state.schema");
@@ -378,6 +582,137 @@ function createServiceProxy(definition, adapter, endpoint) {
   return new ServiceProxy(definition, adapter, endpoint);
 }
 
+// src/events/EventBus.ts
+var EventBus = class {
+  handlers = /* @__PURE__ */ new Map();
+  subscribe(event, handler) {
+    let listeners = this.handlers.get(event);
+    if (!listeners) {
+      listeners = /* @__PURE__ */ new Set();
+      this.handlers.set(event, listeners);
+    }
+    listeners.add(handler);
+    return {
+      unsubscribe: () => {
+        listeners?.delete(handler);
+        if (listeners && listeners.size === 0) this.handlers.delete(event);
+      }
+    };
+  }
+  on(event, handler) {
+    return this.subscribe(event, handler).unsubscribe;
+  }
+  emit(event, payload) {
+    const listeners = this.handlers.get(event);
+    if (!listeners) return;
+    for (const listener of Array.from(listeners)) {
+      try {
+        listener(payload);
+      } catch (error) {
+        console.error(`[EventBus] Handler error for '${event}':`, error);
+      }
+    }
+  }
+  clear() {
+    this.handlers.clear();
+  }
+};
+function createEventChannels(bus, names) {
+  const channels = {};
+  for (const name of names) {
+    channels[name] = {
+      name,
+      subscribe: (handler) => bus.subscribe(name, handler),
+      on: (handler) => bus.on(name, handler)
+    };
+  }
+  return channels;
+}
+
+// src/functionalities/FunctionalityFacade.ts
+var FunctionalityFacade = class {
+  id;
+  name;
+  description;
+  bubbleEvents;
+  definition;
+  eventBus;
+  events;
+  constructor(id2, definition, options = {}) {
+    if (!id2 || typeof id2 !== "string") {
+      throw new Error("[FunctionalityFacade] Functionality id must be a non-empty string.");
+    }
+    if (!definition || typeof definition.execute !== "function") {
+      throw new Error(`[FunctionalityFacade:${id2}] Functionality must define execute().`);
+    }
+    this.id = id2;
+    this.name = definition.name || id2;
+    this.description = definition.description || "";
+    this.bubbleEvents = options.bubbleEvents ?? definition.bubbleEvents ?? true;
+    this.definition = definition;
+    this.eventBus = new EventBus();
+    for (const reserved of ["triggered", "completed", "failed"]) {
+      if (definition.events && reserved in definition.events) {
+        throw new Error(`[FunctionalityFacade:${id2}] Event '${reserved}' is reserved for functionality lifecycle.`);
+      }
+    }
+    const eventNames = [
+      "triggered",
+      "completed",
+      "failed",
+      ...Object.keys(definition.events ?? {})
+    ];
+    this.events = createEventChannels(this.eventBus, eventNames);
+  }
+  getEventDefinitions() {
+    return {
+      triggered: { name: "triggered", description: "Functionality execution started." },
+      completed: { name: "completed", description: "Functionality execution completed successfully." },
+      failed: { name: "failed", description: "Functionality execution failed." },
+      ...this.definition.events ?? {}
+    };
+  }
+  subscribe(event, handler) {
+    return this.eventBus.on(event, handler);
+  }
+  emit(event, payload) {
+    this.eventBus.emit(event, payload);
+  }
+  async execute(input, context) {
+    const lifecycle = {
+      serviceId: context.serviceId,
+      functionalityId: this.id,
+      functionalityName: this.name,
+      correlationId: context.correlationId,
+      timestamp: Date.now(),
+      input
+    };
+    this.emit("triggered", lifecycle);
+    try {
+      const output = await this.definition.execute(input, {
+        ...context,
+        emit: (event, payload) => this.emit(event, payload)
+      });
+      this.emit("completed", {
+        ...lifecycle,
+        timestamp: Date.now(),
+        output
+      });
+      return output;
+    } catch (error) {
+      this.emit("failed", {
+        ...lifecycle,
+        timestamp: Date.now(),
+        error: error?.message || String(error)
+      });
+      throw error;
+    }
+  }
+  clearEventSubscriptions() {
+    this.eventBus.clear();
+  }
+};
+
 // ../../node_modules/.pnpm/p-queue@10.0.0/node_modules/p-queue/dist/lower-bound.js
 function lowerBound(array, value, comparator) {
   let first = 0;
@@ -432,11 +767,11 @@ var PriorityQueue = class {
     return item.run;
   }
   enqueue(run, options) {
-    const { priority = 0, id } = options ?? {};
+    const { priority = 0, id: id2 } = options ?? {};
     const { size } = this;
     const element = {
       priority,
-      id,
+      id: id2,
       run
     };
     if (size === 0) {
@@ -453,16 +788,16 @@ var PriorityQueue = class {
     const index = lowerBound(this.#queue, element, (a, b) => a.priority === b.priority ? 0 : b.priority - a.priority);
     this.#queue.splice(index, 0, element);
   }
-  setPriority(id, priority) {
-    const index = this.#findIndex((element) => element.id === id);
+  setPriority(id2, priority) {
+    const index = this.#findIndex((element) => element.id === id2);
     if (index === -1) {
-      throw new ReferenceError(`No promise function with the id "${id}" exists in the queue.`);
+      throw new ReferenceError(`No promise function with the id "${id2}" exists in the queue.`);
     }
     if (this.#queue[index].priority === priority) {
       return;
     }
     const [item] = this.#queue.splice(index, 1);
-    this.enqueue(item.run, { priority, id });
+    this.enqueue(item.run, { priority, id: id2 });
   }
   remove(idOrRun) {
     const index = this.#findIndex((element) => (typeof idOrRun === "string" ? element.id : element.run) === idOrRun);
@@ -878,17 +1213,17 @@ var PQueue = class extends EventTarget {
     }
   }
   async #add(function_, options, waitingTask) {
-    const id = options.id ?? (this.#idAssigner++).toString();
+    const id2 = options.id ?? (this.#idAssigner++).toString();
     options = {
       timeout: this.#timeout,
       ...options,
-      id
+      id: id2
     };
     validateTimeout(options.timeout);
     if (options.priority !== void 0 && (typeof options.priority !== "number" || Number.isNaN(options.priority))) {
       throw new TypeError(`Expected \`priority\` to be a number, got \`${String(options.priority)}\` (${typeof options.priority})`);
     }
-    waitingTask.id = id;
+    waitingTask.id = id2;
     waitingTask.priority = options.priority ?? 0;
     return new Promise((resolve, reject) => {
       if (options.signal?.aborted) {
@@ -905,7 +1240,7 @@ var PQueue = class extends EventTarget {
         }
         this.#pending++;
         const runningTask = {
-          id,
+          id: id2,
           priority: waitingTask.priority,
           startTime: Date.now(),
           timeout: options.timeout
@@ -972,7 +1307,7 @@ var PQueue = class extends EventTarget {
           if (this.#queue instanceof PriorityQueue) {
             this.#queue.remove(run);
           } else {
-            this.#queue.remove(id);
+            this.#queue.remove(id2);
           }
           reject(signal.reason);
           this.#processQueue();
@@ -1048,18 +1383,18 @@ var PQueue = class extends EventTarget {
       // '🦀' runs last
       ```
       */
-  setPriority(id, priority) {
+  setPriority(id2, priority) {
     if (typeof priority !== "number" || !Number.isFinite(priority)) {
       throw new TypeError(`Expected \`priority\` to be a finite number, got \`${priority}\` (${typeof priority})`);
     }
     for (const waitingTask of this.#waitingTasks) {
-      if (waitingTask.id === id) {
-        this.#queue.setPriority(id, priority);
+      if (waitingTask.id === id2) {
+        this.#queue.setPriority(id2, priority);
         waitingTask.priority = priority;
         return;
       }
     }
-    throw new ReferenceError(`No promise function with the id "${id}" exists in the queue.`);
+    throw new ReferenceError(`No promise function with the id "${id2}" exists in the queue.`);
   }
   /**
       Adds a sync or async task to the queue.
@@ -1402,7 +1737,7 @@ var TimeoutError = class extends DOMException {
 };
 
 // src/orchestration/canonical/KrnlQ.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 
 // src/orchestration/canonical/model.ts
 function validateOrchestrationDAG(steps) {
@@ -1469,8 +1804,8 @@ function validateOrchestrationDAG(steps) {
     }
   }
   const queue = [];
-  for (const [id, deg] of inDegree.entries()) {
-    if (deg === 0) queue.push(id);
+  for (const [id2, deg] of inDegree.entries()) {
+    if (deg === 0) queue.push(id2);
   }
   const order = [];
   while (queue.length > 0) {
@@ -1606,7 +1941,7 @@ var KrnlWorkerPool = class {
 // src/orchestration/canonical/KrnlQ.ts
 function generateSecureId(prefix) {
   try {
-    return `${prefix}_${randomUUID()}`;
+    return `${prefix}_${randomUUID2()}`;
   } catch {
     return `${prefix}_${Math.random().toString(36).substring(2, 11)}_${Date.now()}`;
   }
@@ -1674,9 +2009,9 @@ var KrnlQueue = class {
     if (this.jobs.size <= this.maxRetainedJobs) return;
     const excess = this.jobs.size - this.maxRetainedJobs;
     let pruned = 0;
-    for (const [id, record] of this.jobs.entries()) {
+    for (const [id2, record] of this.jobs.entries()) {
       if (record.status === "completed" || record.status === "failed" || record.status === "cancelled") {
-        this.jobs.delete(id);
+        this.jobs.delete(id2);
         pruned++;
         if (pruned >= excess) break;
       }
@@ -2290,6 +2625,7 @@ var ServiceFacade = class {
   defaultFrontend;
   instance;
   queue;
+  telemetry;
   constructor(config) {
     if (!config || !config.id || typeof config.id !== "string") {
       throw new Error("[ServiceFacade] ServiceFacade requires a valid id.");
@@ -2298,7 +2634,10 @@ var ServiceFacade = class {
     this.name = config.name || config.id;
     this.version = config.version || "1.0.0";
     this.description = config.description || "";
-    this.functionalities = config.functionalities ? { ...config.functionalities } : {};
+    this.functionalities = {};
+    for (const [name, functionality] of Object.entries(config.functionalities ?? {})) {
+      this.registerFunctionality(name, functionality);
+    }
     this.functionalityOrchestrations = config.functionalityOrchestrations ? { ...config.functionalityOrchestrations } : config.orchestrations ? { ...config.orchestrations } : {};
     this.libraries = config.libraries ? { ...config.libraries } : {};
     this.dependencies = Object.freeze(config.dependencies ? [...config.dependencies] : []);
@@ -2316,6 +2655,7 @@ var ServiceFacade = class {
         operations: {}
       });
     }
+    this.telemetry = this.instance.telemetry;
     this.queue = new KrnlQueue({
       queueName: `krnl_queue_${this.id}`,
       concurrency: config.concurrency ?? config.queueOptions?.concurrency ?? 10,
@@ -2359,6 +2699,8 @@ var ServiceFacade = class {
    */
   async call(op, input, ctx) {
     const correlationId = ctx?.correlationId || `corr_${Math.random().toString(36).substring(2, 11)}`;
+    const telemetryParent = typeof ctx?.metadata?.__krnlTelemetryParentSpanId === "string" ? ctx.metadata.__krnlTelemetryParentSpanId : void 0;
+    const telemetryHandle = this.telemetry.begin(op, "service", correlationId, telemetryParent);
     const commandId = `cmd_${this.id}_${op}_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`;
     const command = {
       id: commandId,
@@ -2368,23 +2710,48 @@ var ServiceFacade = class {
       idempotencyKey: ctx?.idempotencyKey,
       createdAt: Date.now()
     };
-    const result = await this.queue.executeCommand(command, async (payload, workerCtx) => {
-      WorkerExecutionBoundary.assertWorkerContext(workerCtx);
-      if (this.functionalities[op] && typeof this.functionalities[op].execute === "function") {
-        return await this.functionalities[op].execute(payload, {
+    try {
+      const result = await this.queue.executeCommand(command, async (payload, workerCtx) => {
+        WorkerExecutionBoundary.assertWorkerContext(workerCtx);
+        const functionality = this.functionalities[op];
+        if (functionality) {
+          const functionalityTelemetry = this.telemetry.begin(
+            functionality.name,
+            "functionality",
+            workerCtx.correlationId,
+            telemetryHandle.spanId
+          );
+          try {
+            return await functionality.execute(payload, {
+              serviceId: this.id,
+              functionalityId: functionality.id,
+              correlationId: workerCtx.correlationId,
+              state: this.instance.getState()
+            });
+          } catch (error) {
+            functionalityTelemetry.end(error);
+            throw error;
+          } finally {
+            functionalityTelemetry.end();
+          }
+        }
+        return await this.instance.call(op, payload, {
           correlationId: workerCtx.correlationId,
-          state: this.instance.getState()
+          idempotencyKey: command.idempotencyKey,
+          metadata: { __krnlTelemetryInternal: true }
         });
-      }
-      return await this.instance.call(op, payload, {
-        correlationId: workerCtx.correlationId,
-        idempotencyKey: command.idempotencyKey
       });
-    });
-    if (result.status === "FAILED") {
-      throw new Error(result.error || `[ServiceFacade:${this.id}] Operation '${op}' execution failed.`);
+      if (result.status === "FAILED") {
+        const error = new Error(result.error || `[ServiceFacade:${this.id}] Operation '${op}' execution failed.`);
+        telemetryHandle.end(error);
+        throw error;
+      }
+      telemetryHandle.end();
+      return result.data;
+    } catch (error) {
+      telemetryHandle.end(error);
+      throw error;
     }
-    return result.data;
   }
   /**
    * External caller callable boundary for functionality orchestration execution.
@@ -2398,6 +2765,18 @@ var ServiceFacade = class {
       );
     }
     const correlationId = options.correlationId || `corr_${Math.random().toString(36).substring(2, 11)}`;
+    const serviceTelemetryHandle = this.telemetry.begin(
+      `orchestrate:${orchestrationName}`,
+      "service",
+      correlationId,
+      typeof options.metadata?.__krnlTelemetryParentSpanId === "string" ? options.metadata.__krnlTelemetryParentSpanId : void 0
+    );
+    const telemetryHandle = this.telemetry.begin(
+      orchestrationName,
+      "orchestration",
+      correlationId,
+      serviceTelemetryHandle.spanId
+    );
     const commandId = `cmd_orch_${this.id}_${orchestrationName}_${Date.now()}`;
     const command = {
       id: commandId,
@@ -2407,6 +2786,13 @@ var ServiceFacade = class {
       idempotencyKey: options.idempotencyKey,
       createdAt: Date.now()
     };
+    orch.events.emit("triggered", {
+      serviceId: this.id,
+      orchestrationId: orch.id,
+      orchestrationName: orch.name,
+      correlationId,
+      timestamp: Date.now()
+    });
     const cmdResult = await this.queue.executeCommand(
       command,
       async (payload, workerCtx) => {
@@ -2438,7 +2824,8 @@ var ServiceFacade = class {
               ...s.compensation,
               handler: async (compCtx) => {
                 await this.call(s.compensation.target, compCtx.results[s.id], {
-                  correlationId: compCtx.correlationId
+                  correlationId: compCtx.correlationId,
+                  metadata: { __krnlTelemetryParentSpanId: telemetryHandle.spanId }
                 });
               }
             };
@@ -2454,7 +2841,8 @@ var ServiceFacade = class {
                   stepPayload.input = stepCtx.results.input;
                 }
                 return await this.call(s.target, stepPayload, {
-                  correlationId: stepCtx.correlationId
+                  correlationId: stepCtx.correlationId,
+                  metadata: { __krnlTelemetryParentSpanId: telemetryHandle.spanId }
                 });
               }
             };
@@ -2474,7 +2862,8 @@ var ServiceFacade = class {
           const nestedResult = await this.orchestrate(childOrchId, childInput, {
             correlationId: childCtx.correlationId,
             timeoutMs: childOrch.timeoutMs,
-            abortSignal: options.abortSignal
+            abortSignal: options.abortSignal,
+            metadata: { __krnlTelemetryParentSpanId: telemetryHandle.spanId }
           });
           if (nestedResult.status !== "COMPLETED") {
             throw new Error(nestedResult.error || `Nested orchestration "${childOrchId}" failed.`);
@@ -2496,9 +2885,39 @@ var ServiceFacade = class {
         );
       }
     );
-    if (cmdResult.status === "FAILED") {
-      throw new Error(cmdResult.error || `[ServiceFacade:${this.id}] Orchestration failed.`);
+    const orchestrationResult = cmdResult.data;
+    if (cmdResult.status === "COMPLETED" && orchestrationResult) {
+      const lifecycleEvent = orchestrationResult.status === "COMPLETED" ? "completed" : "failed";
+      orch.events.emit(lifecycleEvent, {
+        serviceId: this.id,
+        orchestrationId: orch.id,
+        orchestrationName: orch.name,
+        correlationId,
+        executionId: String(orchestrationResult.executionMetadata.executionId ?? ""),
+        timestamp: Date.now(),
+        status: orchestrationResult.status,
+        output: orchestrationResult.output,
+        error: orchestrationResult.error
+      });
+    } else {
+      orch.events.emit("failed", {
+        serviceId: this.id,
+        orchestrationId: orch.id,
+        orchestrationName: orch.name,
+        correlationId,
+        timestamp: Date.now(),
+        status: cmdResult.status,
+        error: cmdResult.error
+      });
     }
+    if (cmdResult.status === "FAILED" || orchestrationResult?.status === "FAILED") {
+      const error = new Error(orchestrationResult?.error || cmdResult.error || `[ServiceFacade:${this.id}] Orchestration failed.`);
+      telemetryHandle.end(error);
+      serviceTelemetryHandle.end(error);
+      throw error;
+    }
+    telemetryHandle.end();
+    serviceTelemetryHandle.end();
     return cmdResult.data;
   }
   /**
@@ -2525,17 +2944,29 @@ var ServiceFacade = class {
   setState(mutation) {
     this.instance.setState(mutation);
   }
-  on(event, handler) {
-    return this.instance.on(event, handler);
-  }
-  emit(event, payload) {
-    this.instance.emit(event, payload);
+  getFunctionality(name) {
+    const functionality = this.functionalities[name];
+    if (!functionality) {
+      throw new Error(`[ServiceFacade:${this.id}] Functionality "${name}" not found.`);
+    }
+    return functionality;
   }
-  registerFunctionality(name, functionality) {
+  registerFunctionality(name, functionality, options = {}) {
     if (!name || typeof name !== "string") {
       throw new Error("[ServiceFacade] Functionality name must be a non-empty string.");
     }
-    this.functionalities[name] = functionality;
+    if (functionality instanceof FunctionalityFacade) {
+      this.functionalities[name] = functionality;
+      return this;
+    }
+    if (!functionality || typeof functionality !== "object" || typeof functionality.execute !== "function") {
+      throw new Error(`[ServiceFacade:${this.id}] Functionality "${name}" must define execute().`);
+    }
+    this.functionalities[name] = new FunctionalityFacade(
+      name,
+      functionality,
+      options
+    );
     return this;
   }
   registerFunctionalityOrchestration(name, orchestration) {
@@ -2573,14 +3004,22 @@ var ServiceFacade = class {
     return this.getNamespace();
   }
   getNamespace() {
+    const bubbledFunctionalities = {};
+    for (const [name, functionality] of Object.entries(this.functionalities)) {
+      if (functionality.bubbleEvents) bubbledFunctionalities[name] = functionality;
+    }
+    const bubbledOrchestrations = {};
+    for (const [name, orchestration] of Object.entries(this.functionalityOrchestrations)) {
+      if (orchestration.bubbleEvents) bubbledOrchestrations[name] = orchestration;
+    }
     return {
       serviceId: this.id,
       serviceName: this.name,
       version: this.version,
       description: this.description,
       libraries: { ...this.libraries },
-      functionalities: { ...this.functionalities },
-      functionalityOrchestrations: { ...this.functionalityOrchestrations },
+      functionalities: bubbledFunctionalities,
+      functionalityOrchestrations: bubbledOrchestrations,
       capabilities: this.capabilities,
       dependencies: this.dependencies
     };
@@ -3137,9 +3576,9 @@ var ServiceRuntime = class {
 // src/discovery/ServiceDiscovery.ts
 var ServiceDiscovery = class {
   peers = /* @__PURE__ */ new Map();
-  registerPeer(id, name, endpoints) {
-    this.peers.set(id, {
-      id,
+  registerPeer(id2, name, endpoints) {
+    this.peers.set(id2, {
+      id: id2,
       name,
       endpoints,
       lastSeen: Date.now()
@@ -3148,8 +3587,8 @@ var ServiceDiscovery = class {
   getPeers() {
     return Array.from(this.peers.values());
   }
-  findPeer(id) {
-    return this.peers.get(id);
+  findPeer(id2) {
+    return this.peers.get(id2);
   }
 };
 
@@ -3277,6 +3716,34 @@ var KrnlPackageReconciler = class {
   }
 };
 
+// src/events/ServiceEventBus.ts
+var ServiceEventBus = class extends EventBus {
+};
+
+// src/events/OrchestrationEventFacade.ts
+var OrchestrationEventFacade = class {
+  eventBus = new EventBus();
+  events;
+  constructor() {
+    this.events = createEventChannels(this.eventBus, ["triggered", "completed", "failed"]);
+  }
+  get triggered() {
+    return this.events.triggered;
+  }
+  get completed() {
+    return this.events.completed;
+  }
+  get failed() {
+    return this.events.failed;
+  }
+  emit(event, payload) {
+    this.eventBus.emit(event, payload);
+  }
+  clear() {
+    this.eventBus.clear();
+  }
+};
+
 // src/connectivity/ProtocolResolver.ts
 var ProtocolResolver = class {
   static selectProtocol(requiredCapabilities, availableEndpoints) {
@@ -3297,6 +3764,8 @@ var FunctionalityOrchestration = class {
   description;
   timeoutMs;
   scope = "functionality";
+  bubbleEvents;
+  events;
   steps = [];
   flows = /* @__PURE__ */ new Map();
   constructor(descriptor) {
@@ -3308,6 +3777,8 @@ var FunctionalityOrchestration = class {
     this.version = descriptor.version || "1.0.0";
     this.description = descriptor.description || "";
     this.timeoutMs = descriptor.timeoutMs;
+    this.bubbleEvents = descriptor.bubbleEvents ?? true;
+    this.events = new OrchestrationEventFacade();
   }
   /**
    * Adds a sequential functionality step to the DAG.
@@ -3468,6 +3939,7 @@ var FunctionalityOrchestration = class {
       description: this.description,
       timeoutMs: this.timeoutMs,
       scope: "functionality",
+      bubbleEvents: this.bubbleEvents,
       dependencies: [],
       steps: this.steps.map((s) => ({
         id: s.id,
@@ -3571,6 +4043,8 @@ var FunctionalityOrchestration = class {
 // src/index.ts
 import * as gutts from "@dinilmusick/gutts";
 export {
+  EventBus,
+  FunctionalityFacade,
   FunctionalityOrchestration,
   HttpProtocolAdapter,
   KrnlPackageReconciler,
@@ -3578,6 +4052,7 @@ export {
   KrnlWorkerPool,
   LifecycleManager,
   MemoryTransport,
+  OrchestrationEventFacade,
   P2PProtocolAdapter,
   ProtocolResolver,
   ServiceDiscovery,
@@ -3588,14 +4063,19 @@ export {
   ServiceRegistry,
   ServiceRuntime,
   ServiceStateStore,
+  TelemetryController,
   UdpProtocolAdapter,
   WebSocketProtocolAdapter,
   WorkerExecutionBoundary,
+  createEventChannels,
   createService,
   createServiceDefinition,
   createServiceFacade,
   createServiceProxy,
+  deltaResources,
   gutts,
+  sampleResources,
+  telemetryNow,
   validateOrchestrationDAG,
   validateServiceDefinition
 };