@kalphq/core 0.0.0-dev-20260507190243

package/src/engine/types.ts

@@ -0,0 +1,304 @@
+/**
+ * Core runtime types for the Kalp v2 Orchestration Reactor.
+ *
+ * These types define the execution event model, task primitives, and runtime
+ * event contracts. They are intentionally infrastructure-agnostic — no
+ * Cloudflare, Durable Object, or platform-specific types appear here.
+ *
+ * @module
+ */
+
+import type { IRNodeId } from "@kalphq/sdk";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Execution Model — identity, hierarchy, and observability
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Categories of untracked IO that Kalp can detect (best-effort).
+ *
+ * - `"network"` — bare `globalThis.fetch` or similar outside `actions.fetch`.
+ * - `"timer"` — `setTimeout` / `setInterval` outside `actions.wait`.
+ * - `"fs"` — Node `fs` access (not applicable in all runtimes; kept for portability).
+ * - `"unknown"` — anything else the heuristic can’t classify.
+ */
+export type UntrackedIOSource = "network" | "timer" | "fs" | "unknown";
+
+/**
+ * Execution identity carried through every handler invocation.
+ *
+ * Hierarchy:
+ * ```
+ * thread = actor instance (identified by threadId)
+ *   +-- trace = one handleEvent() call into the actor
+ *         +-- execution = one handler invocation (step/tool/lifecycle run)
+ * ```
+ *
+ * `threadId` is opaque in Core. The adapter maps it to infrastructure
+ * (e.g. Durable Object id, in-memory key). Core never parses or assumes its format.
+ */
+export interface ExecutionContext {
+  /** Unique per handler invocation (UUID). Distinguishes retries, loop iterations. */
+  executionId: string;
+  /** Per `handleEvent()` call. Groups all executions from one external stimulus. */
+  traceId: string;
+  /** Opaque actor identifier. Adapter maps to infrastructure (CF: DO id, tests: in-memory). */
+  threadId: string;
+  /** Total count of detected untracked IO operations. */
+  untrackedIOCount: number;
+  /** Breakdown of untracked IO by source type. */
+  untrackedIOByType: Record<UntrackedIOSource, number>;
+  /** Whether any plugin has been loaded (observability may be incomplete). */
+  hasUntrustedPlugins: boolean;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Execution Events — the system's source of truth
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Union of all structured events emitted during agent execution.
+ *
+ * Every runtime operation MUST emit an event. If it doesn't emit an event,
+ * it doesn't exist in the system. This is the fundamental invariant.
+ *
+ * These events enable: replay, debugging, billing, observability, and
+ * deterministic re-execution.
+ */
+export type ExecutionEvent =
+  | {
+      type: "node.started";
+      nodeId: IRNodeId;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "node.completed";
+      nodeId: IRNodeId;
+      result: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "primitive.invoked";
+      name: string;
+      params: unknown;
+      result: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.run";
+      target: string;
+      input: unknown;
+      idempotencyKey?: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.run.completed";
+      target: string;
+      result: unknown;
+      idempotencyKey?: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.wait";
+      duration: string | number;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.loop.start";
+      loopId: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.loop.iteration";
+      loopId: string;
+      iteration: number;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.loop.end";
+      loopId: string;
+      reason: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.fetch";
+      url: string;
+      method: string;
+      status: number;
+      durationMs: number;
+      idempotencyKey?: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.emit";
+      event: string;
+      payload: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.schedule";
+      at: number;
+      payload: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "state.write";
+      key: string;
+      value: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "state.read";
+      key: string;
+      value: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.ask";
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.approval";
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "action.call";
+      contract: string;
+      input: unknown;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "execution.untracked";
+      source: UntrackedIOSource;
+      location?: string;
+      nodeId?: IRNodeId;
+      action?: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "log";
+      level: "debug" | "info" | "warn" | "error";
+      msg: string;
+      data?: Record<string, unknown>;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    }
+  | {
+      type: "error";
+      nodeId?: IRNodeId;
+      error: string;
+      executionId: string;
+      traceId: string;
+      threadId: string;
+      timestamp: number;
+    };
+
+// ────────────────────────────────────────────────────────────────────────────
+// Runtime Events — external stimuli entering the reactor
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * An external event that enters the reactor from the host adapter.
+ * Each event maps to an entry in the IR via `type` → `ir.entries[type]`.
+ */
+export interface RuntimeEvent {
+  /** Event name matching an IR entry key (e.g. "onMessage", "route:GET:/health"). */
+  type: string;
+  /** Arbitrary payload associated with the event. */
+  payload: unknown;
+  /** Opaque thread identifier. Adapter sets this from infrastructure (DO id, etc.). */
+  threadId?: string;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Execution Tasks — internal work items in the reactor queue
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A task in the reactor's internal execution queue.
+ * Created when a node needs to be processed (entry traversal, handler execution, etc.).
+ */
+export interface ExecutionTask {
+  /** The IR node to process. */
+  nodeId: IRNodeId;
+  /** Context data passed to the handler. */
+  context: unknown;
+  /**
+   * Optional resolve callback for action.run intent pattern.
+   * When a handler calls `actions.run(step, input)`, the reactor creates a
+   * task with a resolve function. The handler's Promise awaits this resolve.
+   */
+  resolve?: (result: unknown) => void;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Handler Module — the shape of a bundled handler
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The runtime representation of a bundled handler module.
+ *
+ * Each handler is an isolated function that receives a {@link HandlerContext}
+ * (from `@kalphq/sdk`) and returns a result. The reactor executes these in a
+ * sandboxed context with intercepted primitives.
+ */
+export interface HandlerModule {
+  /** The handler's entry function. */
+  default: (context: unknown, input?: unknown) => Promise<unknown>;
+}

package/src/env.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Ambient type declarations for the core package.
+ *
+ * Core is infrastructure-agnostic. These declarations provide the minimal
+ * global types required by the engine without pulling in DOM or CF-specific libs.
+ *
+ * These types exist in every JS runtime that Kalp targets
+ * (Cloudflare Workers, Node 18+, Bun, Deno).
+ */
+
+/* eslint-disable no-var */
+
+// ── Crypto ──────────────────────────────────────────────────────────────────
+
+declare var crypto: {
+  randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
+};
+
+// ── Fetch API (WinterCG-compatible subset) ──────────────────────────────────
+
+declare class URL {
+  constructor(input: string, base?: string | URL);
+  readonly href: string;
+  readonly origin: string;
+  readonly protocol: string;
+  readonly host: string;
+  readonly hostname: string;
+  readonly port: string;
+  readonly pathname: string;
+  readonly search: string;
+  readonly searchParams: URLSearchParams;
+  readonly hash: string;
+  toString(): string;
+  toJSON(): string;
+  static createObjectURL(blob: Blob): string;
+  static revokeObjectURL(url: string): void;
+}
+
+declare class URLSearchParams implements Iterable<[string, string]> {
+  constructor(init?: string | Record<string, string> | [string, string][]);
+  append(name: string, value: string): void;
+  delete(name: string): void;
+  get(name: string): string | null;
+  getAll(name: string): string[];
+  has(name: string): boolean;
+  set(name: string, value: string): void;
+  toString(): string;
+  entries(): IterableIterator<[string, string]>;
+  keys(): IterableIterator<string>;
+  values(): IterableIterator<string>;
+  [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+
+declare class Headers implements Iterable<[string, string]> {
+  constructor(init?: HeadersInit);
+  append(name: string, value: string): void;
+  delete(name: string): void;
+  get(name: string): string | null;
+  has(name: string): boolean;
+  set(name: string, value: string): void;
+  entries(): IterableIterator<[string, string]>;
+  keys(): IterableIterator<string>;
+  values(): IterableIterator<string>;
+  forEach(
+    callback: (value: string, key: string, parent: Headers) => void,
+  ): void;
+  [Symbol.iterator](): IterableIterator<[string, string]>;
+}
+
+type HeadersInit = Headers | Record<string, string> | [string, string][];
+
+interface RequestInit {
+  method?: string;
+  headers?: HeadersInit;
+  body?: BodyInit | null;
+  signal?: AbortSignal;
+  redirect?: "follow" | "error" | "manual";
+}
+
+type BodyInit =
+  | string
+  | ArrayBuffer
+  | Uint8Array
+  | ReadableStream
+  | FormData
+  | URLSearchParams
+  | Blob;
+
+declare class Request {
+  constructor(input: string | URL | Request, init?: RequestInit);
+  readonly url: string;
+  readonly method: string;
+  readonly headers: Headers;
+  readonly body: ReadableStream | null;
+  readonly bodyUsed: boolean;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  clone(): Request;
+}
+
+interface ResponseInit {
+  status?: number;
+  statusText?: string;
+  headers?: HeadersInit;
+}
+
+declare class Response {
+  constructor(body?: BodyInit | null, init?: ResponseInit);
+  readonly ok: boolean;
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: Headers;
+  readonly body: ReadableStream | null;
+  readonly bodyUsed: boolean;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  clone(): Response;
+  static json(data: unknown, init?: ResponseInit): Response;
+  static redirect(url: string, status?: number): Response;
+}
+
+declare class Blob {
+  constructor(parts?: BlobPart[], options?: BlobPropertyBag);
+  readonly size: number;
+  readonly type: string;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  slice(start?: number, end?: number, contentType?: string): Blob;
+}
+
+type BlobPart = string | ArrayBuffer | Uint8Array | Blob;
+
+interface BlobPropertyBag {
+  type?: string;
+}
+
+declare function fetch(
+  input: string | URL | Request,
+  init?: RequestInit,
+): Promise<Response>;

package/src/factory.ts

@@ -0,0 +1,69 @@
+/**
+ * Engine factory — the ONLY way to create a reactor instance.
+ *
+ * This file is deliberately separate from the barrel (index.ts) to prevent
+ * coupling between type consumers and runtime consumers.
+ *
+ * Import path: `@kalphq/core/factory`
+ *
+ * This is NOT a composition root. It does NOT create adapters.
+ * Platform packages (cloudflare, node, bun) create adapters in their own
+ * wiring files and pass them here.
+ *
+ * @module
+ */
+
+import type { IRGraph } from "@kalphq/sdk";
+import { OrchestrationReactor } from "@/engine/reactor";
+import type { HandlerModule } from "@/engine/types";
+import type { PersistenceAdapter, SchedulerAdapter } from "@/adapters/interfaces";
+import type { RuntimeProviders } from "@/engine/context-builder";
+
+/**
+ * Configuration for creating a new reactor instance.
+ *
+ * All fields are required. Platform wiring files are responsible for
+ * creating the adapter instances and passing them here.
+ */
+export interface ReactorConfig {
+  /** The compiled IR graph for the agent. */
+  ir: IRGraph;
+  /** Map from moduleRef to bundled handler module. */
+  bundles: Map<string, HandlerModule>;
+  /** Composite persistence adapter (state, events, idempotency, threads). */
+  persistence: PersistenceAdapter;
+  /** Scheduler adapter for deferred wake-ups. */
+  scheduler: SchedulerAdapter;
+  /** External providers for ai, auth, memory, vault. */
+  providers: RuntimeProviders;
+}
+
+/**
+ * Creates a new {@link OrchestrationReactor} instance.
+ *
+ * This is the standard entrypoint for all platform adapters.
+ * The factory performs no validation — callers are responsible for
+ * ensuring the config is complete and correct.
+ *
+ * @param config - The reactor configuration.
+ * @returns A fully initialized reactor ready to handle events.
+ *
+ * @example
+ * ```ts
+ * import { createReactor } from "@kalphq/core/factory";
+ *
+ * const reactor = createReactor({
+ *   ir, bundles, persistence, scheduler, providers,
+ * });
+ * await reactor.handleEvent(event);
+ * ```
+ */
+export function createReactor(config: ReactorConfig): OrchestrationReactor {
+  return new OrchestrationReactor(
+    config.ir,
+    config.bundles,
+    config.persistence,
+    config.scheduler,
+    config.providers,
+  );
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @kalphq/core — Pure orchestration engine (infrastructure-agnostic).
+ *
+ * This barrel exports the engine, adapter interfaces, and primitives.
+ * No implementations, no Cloudflare types, no runtime-specific code.
+ *
+ * For reactor instantiation, use `@kalphq/core/factory`:
+ * ```ts
+ * import { createReactor } from "@kalphq/core/factory";
+ * ```
+ *
+ * @module
+ */
+
+// ────────────────────────────────────────────────────────────────────────────
+// Engine
+// ────────────────────────────────────────────────────────────────────────────
+
+export { OrchestrationReactor } from "@/engine/reactor";
+export { ExecutionLog } from "@/engine/execution-log";
+export { buildHandlerContext } from "@/engine/context-builder";
+export type { RuntimeProviders } from "@/engine/context-builder";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────────────
+
+export type {
+  ExecutionEvent,
+  ExecutionContext,
+  UntrackedIOSource,
+  RuntimeEvent,
+  ExecutionTask,
+  HandlerModule,
+} from "@/engine/types";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Adapter interfaces (contracts only — no implementations)
+// ────────────────────────────────────────────────────────────────────────────
+
+export type {
+  PersistenceAdapter,
+  SchedulerAdapter,
+  TransportAdapter,
+  CrossThreadAdapter,
+  StateStore,
+  EventStore,
+  IdempotencyStore,
+  ThreadStore,
+} from "@/adapters/interfaces";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Primitives
+// ────────────────────────────────────────────────────────────────────────────
+
+export { createAIPrimitive } from "@/engine/primitives/ai";
+export type { AIProvider } from "@/engine/primitives/ai";
+export { createStoragePrimitive } from "@/engine/primitives/storage";
+export { createActionsPrimitive } from "@/engine/primitives/actions";
+export type { DispatchAction } from "@/engine/primitives/actions";
+export { createHttpPrimitive } from "@/engine/primitives/http";

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "../typescript-config/base.json",
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts", "src/factory.ts"],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});