@ddse/acm-runtime 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DDSE Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,393 @@
+# @ddse/acm-runtime
+
+ACM v0.5 execution engine with guards, retries, policy hooks, and memory ledger.
+
+## Overview
+
+The runtime package provides deterministic plan execution with full ACM v0.5 semantics including guard evaluation, retry logic, policy enforcement, verification, and decision logging.
+
+## Installation
+
+```bash
+pnpm add @ddse/acm-runtime @ddse/acm-sdk
+```
+
+## Features
+
+- ✅ Task graph execution with topological ordering
+- ✅ Guard expression evaluation
+- ✅ Configurable retry with exponential backoff
+- ✅ Policy pre/post hooks
+- ✅ Verification assertions
+- ✅ Memory ledger (append-only decision log)
+- ✅ Streaming progress updates
+- ✅ Error handling and compensation
+- ✅ **Resumable execution with checkpointing** (NEW in Phase 2)
+
+## Usage
+
+### Basic Execution
+
+```typescript
+import { executePlan, MemoryLedger } from '@ddse/acm-runtime';
+import type { Goal, Context, Plan } from '@ddse/acm-sdk';
+
+const result = await executePlan({
+  goal: { id: 'g1', intent: 'Process order' },
+  context: { id: 'ctx1', facts: { orderId: 'O123' } },
+  plan: myPlan,
+  capabilityRegistry: myCapabilities,
+  toolRegistry: myTools,
+});
+
+const taskRecord = result.outputsByTask['task-1'];
+console.log('Task output:', taskRecord?.output);
+console.log('Narrative:', taskRecord?.narrative);
+console.log('Ledger entries:', result.ledger.length);
+```
+
+### With Policy Enforcement
+
+```typescript
+import { PolicyEngine, type PolicyDecision } from '@ddse/acm-sdk';
+
+class MyPolicyEngine implements PolicyEngine {
+  async evaluate(action: string, payload: any): Promise<PolicyDecision> {
+    if (action === 'task.pre' && payload.riskLevel === 'HIGH') {
+      return { allow: false, reason: 'Risk too high' };
+    }
+    return { allow: true };
+  }
+}
+
+const result = await executePlan({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  policy: new MyPolicyEngine(),
+});
+```
+
+### With Verification
+
+```typescript
+const verify = async (taskId: string, output: any, expressions: string[]): Promise<boolean> => {
+  for (const expr of expressions) {
+    const func = new Function('output', `return ${expr};`);
+    if (!func(output)) {
+      console.error(`Verification failed: ${expr}`);
+      return false;
+    }
+  }
+  return true;
+};
+
+const result = await executePlan({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  verify,
+});
+```
+
+### With Streaming
+
+```typescript
+import { DefaultStreamSink } from '@ddse/acm-sdk';
+
+const stream = new DefaultStreamSink();
+
+stream.attach('task', (update) => {
+  console.log(`[${update.taskId}] ${update.status}`);
+});
+
+const result = await executePlan({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  stream,
+});
+```
+
+### Memory Ledger
+
+```typescript
+import { MemoryLedger } from '@ddse/acm-runtime';
+
+const ledger = new MemoryLedger();
+
+const result = await executePlan({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  ledger,
+});
+
+// Inspect decisions
+for (const entry of ledger.getEntries()) {
+  console.log(`${entry.type} at ${entry.ts}:`, entry.details);
+}
+```
+
+### Resumable Execution (Phase 2)
+
+Execute plans with automatic checkpointing and resume support:
+
+```typescript
+import { executeResumablePlan, FileCheckpointStore } from '@ddse/acm-runtime';
+
+// Setup checkpoint storage
+const checkpointStore = new FileCheckpointStore('./checkpoints');
+const runId = 'my-run-123';
+
+// Execute with checkpointing
+const result = await executeResumablePlan({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  runId,
+  checkpointStore,
+  checkpointInterval: 1, // Checkpoint after each task
+});
+```
+
+Resume from a previous execution:
+
+```typescript
+// Resume from checkpoint
+const result = await executeResumablePlan({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  runId: 'my-run-123',
+  resumeFrom: 'checkpoint-xyz', // Resume from specific checkpoint
+  checkpointStore,
+});
+```
+
+Using the ResumableExecutor class:
+
+```typescript
+import { ResumableExecutor, FileCheckpointStore } from '@ddse/acm-runtime';
+
+const executor = new ResumableExecutor(
+  new FileCheckpointStore('./checkpoints')
+);
+
+// Execute with checkpointing
+const result = await executor.execute({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  runId: 'my-run-123',
+});
+
+// List checkpoints
+const checkpoints = await executor.listCheckpoints('my-run-123');
+console.log(`Available checkpoints: ${checkpoints.length}`);
+
+// Resume from latest checkpoint
+const latest = await executor.getCheckpoint('my-run-123');
+const resumed = await executor.execute({
+  goal,
+  context,
+  plan,
+  capabilityRegistry,
+  toolRegistry,
+  runId: 'my-run-123',
+  resumeFrom: latest?.id,
+});
+```
+
+## API Reference
+
+### executePlan(options)
+
+Execute a plan with full ACM v0.5 semantics.
+
+**Options:**
+
+- `goal: Goal` - The goal being pursued
+- `context: Context` - Immutable context packet
+- `plan: Plan` - The plan to execute
+- `capabilityRegistry: CapabilityRegistry` - Task registry
+- `toolRegistry: ToolRegistry` - Tool registry
+- `policy?: PolicyEngine` - Optional policy enforcement
+- `verify?: (taskId, output, expressions) => Promise<boolean>` - Optional verification
+- `stream?: StreamSink` - Optional streaming sink
+- `ledger?: MemoryLedger` - Optional ledger (created if not provided)
+
+**Returns:**
+
+```typescript
+{
+  outputsByTask: Record<string, TaskExecutionRecord>;
+  ledger: readonly LedgerEntry[];
+}
+```
+
+Each `TaskExecutionRecord` captures:
+
+- `taskId: string` – Identifier for the executed task.
+- `title: string` – Task title from the structured plan.
+- `objective?: string` – Optional objective provided by the planner.
+- `successCriteria?: string[]` – Optional success criteria checklist.
+- `metadata?: TaskMetadata` – Arbitrary TaskSpec metadata.
+- `narrative?: TaskNarrative` – { start, checkpoints, completion } narrative emitted by the Nucleus.
+- `output?: unknown` – The task's output payload, when present.
+
+### evaluateGuard(expr, context)
+
+Evaluate a guard expression.
+
+**Parameters:**
+
+- `expr: string` - JavaScript boolean expression
+- `context: { context, outputs, policy }` - Evaluation context
+
+**Returns:** `boolean`
+
+### withRetry(fn, config)
+
+Execute a function with retry logic.
+
+**Parameters:**
+
+- `fn: () => Promise<T>` - Function to retry
+- `config: { attempts, backoff, baseMs?, jitter? }` - Retry configuration
+
+**Returns:** `Promise<T>`
+
+### MemoryLedger
+
+Append-only decision log.
+
+**Methods:**
+
+- `append(type, details)` - Add entry
+- `getEntries()` - Get all entries
+- `clear()` - Clear ledger (for testing)
+
+### executeResumablePlan(options)
+
+Execute a plan with checkpoint and resume support.
+
+**Additional Options (extends executePlan):**
+
+- `runId?: string` - Unique run identifier (generated if not provided)
+- `checkpointStore?: CheckpointStore` - Storage backend (default: MemoryCheckpointStore)
+- `checkpointInterval?: number` - Checkpoint after N tasks (default: 1)
+- `resumeFrom?: string` - Checkpoint ID to resume from
+
+**Returns:** Same as `executePlan`
+
+### CheckpointStore
+
+Interface for checkpoint storage backends.
+
+**Implementations:**
+
+- `MemoryCheckpointStore` - In-memory storage (for testing)
+- `FileCheckpointStore(basePath)` - File-based storage
+
+**Methods:**
+
+- `put(runId, checkpoint)` - Store a checkpoint
+- `get(runId, checkpointId?)` - Retrieve checkpoint (latest if no ID)
+- `list(runId)` - List all checkpoints for a run
+- `prune(runId, keepLast)` - Remove old checkpoints
+
+### ResumableExecutor
+
+High-level class for managing resumable executions.
+
+**Constructor:**
+
+- `new ResumableExecutor(checkpointStore?)` - Create executor with optional store
+
+**Methods:**
+
+- `execute(options)` - Execute with checkpointing
+- `listCheckpoints(runId)` - List available checkpoints
+- `getCheckpoint(runId, checkpointId?)` - Get specific checkpoint
+- `pruneCheckpoints(runId, keepLast)` - Clean up old checkpoints
+
+## Guard Expressions
+
+Guards are JavaScript boolean expressions evaluated with:
+
+- `context`: The Context Packet facts
+- `outputs`: Task outputs so far
+- `policy`: Policy decisions
+
+Examples:
+
+```javascript
+// Simple fact check
+'context.region === "EU"'
+
+// Output dependency
+'outputs.t1.riskTier !== "HIGH"'
+
+// Policy check
+'policy.t1.allow === true'
+
+// Combined
+'context.amount > 100 && outputs.t2.approved === true'
+```
+
+## Retry Configuration
+
+```typescript
+{
+  attempts: 3,
+  backoff: 'exp',  // or 'fixed'
+  baseMs: 1000,
+  jitter: true
+}
+```
+
+Backoff strategies:
+
+- **fixed**: Always wait `baseMs`
+- **exp**: Wait `baseMs * 2^attempt`
+- **jitter**: Add random variation (50-100% of delay)
+
+## Ledger Entry Types
+
+- `PLAN_SELECTED` - Plan chosen for execution
+- `GUARD_EVAL` - Guard evaluation result
+- `TASK_START` - Task execution started
+- `TASK_END` - Task execution completed
+- `POLICY_PRE` - Policy pre-check
+- `POLICY_POST` - Policy post-check
+- `VERIFICATION` - Verification result
+- `ERROR` - Error occurred
+- `COMPENSATION` - Compensation triggered
+
+## ACM v0.5 Compliance
+
+- ✅ Section 6.1: Task execution ordering
+- ✅ Section 6.2: Guard evaluation (deterministic)
+- ✅ Section 6.3: Retry and backoff
+- ✅ Section 6.4: Policy enforcement hooks
+- ✅ Section 6.5: Verification hooks
+- ✅ Section 5.8: Memory Ledger
+
+## License
+
+Apache-2.0

package/dist/src/checkpoint.d.ts

@@ -0,0 +1,97 @@
+import type { Goal, Context, Plan, LedgerEntry } from '@ddse/acm-sdk';
+import type { TaskExecutionRecord } from './executor.js';
+/**
+ * Schema version for checkpoint compatibility
+ */
+export declare const CHECKPOINT_VERSION = "1.0.0";
+/**
+ * Checkpoint represents a snapshot of execution state
+ */
+export interface Checkpoint {
+    id: string;
+    runId: string;
+    ts: number;
+    version: string;
+    state: CheckpointState;
+}
+/**
+ * Execution state captured in a checkpoint
+ */
+export interface CheckpointState {
+    goal: Goal;
+    context: Context;
+    plan: Plan;
+    outputs: Record<string, any>;
+    executionRecords?: Record<string, TaskExecutionRecord>;
+    executed: string[];
+    ledger: LedgerEntry[];
+    metrics: {
+        costUsd: number;
+        elapsedSec: number;
+    };
+}
+/**
+ * Metadata for a checkpoint (lightweight listing)
+ */
+export interface CheckpointMetadata {
+    id: string;
+    runId: string;
+    ts: number;
+    version: string;
+    tasksCompleted: number;
+}
+/**
+ * Storage interface for checkpoints
+ */
+export interface CheckpointStore {
+    /**
+     * Store a checkpoint
+     */
+    put(runId: string, checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Retrieve a checkpoint by ID (or latest if no ID provided)
+     */
+    get(runId: string, checkpointId?: string): Promise<Checkpoint | null>;
+    /**
+     * List all checkpoints for a run
+     */
+    list(runId: string): Promise<CheckpointMetadata[]>;
+    /**
+     * Prune old checkpoints, keeping only the last N
+     */
+    prune(runId: string, keepLast: number): Promise<void>;
+}
+/**
+ * Create a checkpoint from current execution state
+ */
+export declare function createCheckpoint(runId: string, state: CheckpointState): Checkpoint;
+/**
+ * Validate checkpoint compatibility
+ */
+export declare function validateCheckpoint(checkpoint: Checkpoint): boolean;
+/**
+ * In-memory checkpoint store (for testing and simple use cases)
+ */
+export declare class MemoryCheckpointStore implements CheckpointStore {
+    private checkpoints;
+    put(runId: string, checkpoint: Checkpoint): Promise<void>;
+    get(runId: string, checkpointId?: string): Promise<Checkpoint | null>;
+    list(runId: string): Promise<CheckpointMetadata[]>;
+    prune(runId: string, keepLast: number): Promise<void>;
+    /**
+     * Clear all checkpoints (for testing)
+     */
+    clear(): void;
+}
+/**
+ * File-based checkpoint store
+ */
+export declare class FileCheckpointStore implements CheckpointStore {
+    private basePath;
+    constructor(basePath: string);
+    put(runId: string, checkpoint: Checkpoint): Promise<void>;
+    get(runId: string, checkpointId?: string): Promise<Checkpoint | null>;
+    list(runId: string): Promise<CheckpointMetadata[]>;
+    prune(runId: string, keepLast: number): Promise<void>;
+}
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/src/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/checkpoint.ts"],"names":[],"mappings":"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"}