{"_id":"@ddse/acm-replay","_rev":"3-b590196e9f6cdce189b8f88ec090466b","name":"@ddse/acm-replay","dist-tags":{"latest":"0.5.2"},"versions":{"0.5.0":{"name":"@ddse/acm-replay","version":"0.5.0","keywords":["acm","replay","audit","bundle"],"license":"MIT","_id":"@ddse/acm-replay@0.5.0","maintainers":[{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"}],"dist":{"shasum":"170c23061daaae3a762a7522fd98ce84266353f5","tarball":"https://registry.npmjs.org/@ddse/acm-replay/-/acm-replay-0.5.0.tgz","fileCount":15,"integrity":"sha512-5YrqIKf+np4oZmHDe5eZJNp1DtTATTQipgAM8X1VF2VkDVEHcw1XMvxd6fkTuDFI6WnS67js+k8rKqrbVMz9Ag==","signatures":[{"sig":"MEUCIQCbiZ/4Cli6oA+qIuYzSfGKHg5Buh/PCgCy8aGKpcTxYgIgDC6VRE45vGpaKGB52WeW0VUqpATl03rEF3vvXe3pZpY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":83775},"main":"./dist/index.js","type":"module","_from":"file:ddse-acm-replay-0.5.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist"},"_npmUser":{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"},"_resolved":"/tmp/461de1a3d42049a09d1ff716468f7ea6/ddse-acm-replay-0.5.0.tgz","_integrity":"sha512-5YrqIKf+np4oZmHDe5eZJNp1DtTATTQipgAM8X1VF2VkDVEHcw1XMvxd6fkTuDFI6WnS67js+k8rKqrbVMz9Ag==","_npmVersion":"10.8.2","description":"Replay bundle export and import for ACM","directories":{},"_nodeVersion":"20.19.5","dependencies":{"@ddse/acm-sdk":"0.5.0","@ddse/acm-runtime":"0.5.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/acm-replay_0.5.0_1759748776825_0.7365607223306501","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@ddse/acm-replay","version":"0.5.1","keywords":["acm","replay","audit","bundle"],"author":{"name":"Mahmudur R. Manna","email":"hello@ddse.io"},"license":"MIT","_id":"@ddse/acm-replay@0.5.1","maintainers":[{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"}],"homepage":"https://github.com/ddse-foundation/acm/tree/main/framework/node/packages/acm-replay#readme","bugs":{"url":"https://github.com/ddse-foundation/acm/issues"},"dist":{"shasum":"866f858bd3e63207b60dc4c2bb441b50a32d863e","tarball":"https://registry.npmjs.org/@ddse/acm-replay/-/acm-replay-0.5.1.tgz","fileCount":11,"integrity":"sha512-VuSgaEmbOk3eK8cX7SIJkGMqEbKKBWRmLDY/nDwFxszuBZVriKdh+FSkpCegdR/IWcDXEd09Yo5S7+reRChI2A==","signatures":[{"sig":"MEUCIBR9otAHmvVVcjaZ+9wezifH/SZ/4A9fFNZ1LcysDl/uAiEA7N5yelkgUyrprZvHteotaKW9KBCRD6Mk1jtup1ZQfJE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35388},"main":"./dist/index.js","type":"module","_from":"file:ddse-acm-replay-0.5.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","build":"tsc","clean":"rm -rf dist"},"_npmUser":{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"},"_resolved":"/tmp/b7dff1613a82c65732180b926ae3aac0/ddse-acm-replay-0.5.1.tgz","_integrity":"sha512-VuSgaEmbOk3eK8cX7SIJkGMqEbKKBWRmLDY/nDwFxszuBZVriKdh+FSkpCegdR/IWcDXEd09Yo5S7+reRChI2A==","repository":{"url":"git+https://github.com/ddse-foundation/acm.git","type":"git","directory":"framework/node/packages/acm-replay"},"_npmVersion":"11.0.0","description":"Replay bundle export and import for ACM","directories":{},"_nodeVersion":"22.13.1","dependencies":{"@ddse/acm-sdk":"0.5.1","@ddse/acm-runtime":"0.5.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/acm-replay_0.5.1_1771007376298_0.23868863575825428","host":"s3://npm-registry-packages-npm-production"}},"0.5.2":{"name":"@ddse/acm-replay","version":"0.5.2","description":"Replay bundle export and import for ACM","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"dependencies":{"@ddse/acm-sdk":"0.5.2","@ddse/acm-runtime":"0.5.2"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.3.0"},"keywords":["acm","replay","audit","bundle"],"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/ddse-foundation/acm.git","directory":"framework/node/packages/acm-replay"},"author":{"name":"Mahmudur R. Manna","email":"hello@ddse.io"},"homepage":"https://github.com/ddse-foundation/acm/tree/main/framework/node/packages/acm-replay#readme","scripts":{"build":"tsc","clean":"rm -rf dist","dev":"tsc --watch"},"_id":"@ddse/acm-replay@0.5.2","bugs":{"url":"https://github.com/ddse-foundation/acm/issues"},"_integrity":"sha512-EYjvdFwmTEpxjEpUuI/nuyxNUusFzaNC+iazLsftYIY3TWRaNtuG9fxtBdUZeX8do7IeKYSWlwZC+xoxw4DtHg==","_resolved":"/tmp/898af52220c9e3449b5fd94a80ac92ab/ddse-acm-replay-0.5.2.tgz","_from":"file:ddse-acm-replay-0.5.2.tgz","_nodeVersion":"22.13.1","_npmVersion":"11.0.0","dist":{"integrity":"sha512-EYjvdFwmTEpxjEpUuI/nuyxNUusFzaNC+iazLsftYIY3TWRaNtuG9fxtBdUZeX8do7IeKYSWlwZC+xoxw4DtHg==","shasum":"02a4a5fbaa05e081bf929cfff6ca546db6aef7ec","tarball":"https://registry.npmjs.org/@ddse/acm-replay/-/acm-replay-0.5.2.tgz","fileCount":11,"unpackedSize":35388,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCvj0/xJlwxOYlk8oCn7FXLkG11+BQVMc+lLUepp3LnuAIhAMsDygewSF3DdbnfbWs+jz8Tx6LNgxkZpta46OobmxNo"}]},"_npmUser":{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"},"directories":{},"maintainers":[{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/acm-replay_0.5.2_1771026537388_0.5835590605340313"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-06T11:06:16.707Z","modified":"2026-02-13T23:48:57.648Z","0.5.0":"2025-10-06T11:06:17.091Z","0.5.1":"2026-02-13T18:29:36.464Z","0.5.2":"2026-02-13T23:48:57.536Z"},"bugs":{"url":"https://github.com/ddse-foundation/acm/issues"},"author":{"name":"Mahmudur R. Manna","email":"hello@ddse.io"},"license":"MIT","homepage":"https://github.com/ddse-foundation/acm/tree/main/framework/node/packages/acm-replay#readme","keywords":["acm","replay","audit","bundle"],"repository":{"type":"git","url":"git+https://github.com/ddse-foundation/acm.git","directory":"framework/node/packages/acm-replay"},"description":"Replay bundle export and import for ACM","maintainers":[{"name":"mrmanna","email":"mahmudur.r.manna@gmail.com"}],"readme":"# @ddse/acm-replay\n\nReplay bundle export and import for ACM, providing complete audit trails and reproducibility.\n\n## Overview\n\nThis package enables exporting and importing complete ACM execution bundles. Replay bundles capture all artifacts, decisions, and I/O from an execution run, enabling:\n\n- **Audit & Compliance**: Complete execution history for regulatory review\n- **Debugging**: Understand exactly what happened in a failed run\n- **Reproducibility**: Replay executions for testing or validation\n- **Analysis**: Post-execution analysis of agent behavior\n\n## Features\n\n- Export complete execution bundles to structured JSON files\n- Load and validate existing bundles\n- Comprehensive artifact capture (goals, plans, context, I/O, ledger)\n- JSONL format for streaming logs (ledger, policy records)\n- Metadata tracking for versioning and provenance\n\n## Installation\n\n```bash\npnpm add @ddse/acm-replay\n```\n\n## Usage\n\n### Exporting a Replay Bundle\n\n```typescript\nimport { ReplayBundleExporter } from '@ddse/acm-replay';\n\n// After execution, export the bundle\nconst bundlePath = await ReplayBundleExporter.export({\n  outputDir: './replay/run-12345',\n  goal,\n  context,\n  plans: [planA, planB],\n  selectedPlanId: planA.id,\n  ledger: ledger.entries(),\n  taskIO: [\n    {\n      taskId: 't1',\n      capability: 'search',\n      input: { query: 'test' },\n      output: { results: ['result1'] },\n      ts: '2025-01-15T10:00:00Z',\n    },\n  ],\n  policyRecords: [\n    {\n      id: 'p1',\n      ts: '2025-01-15T10:00:00Z',\n      action: 'search',\n      input: {},\n      decision: true,\n    },\n  ],\n  verificationResults: [],\n  engineTrace: {\n    runId: 'run-12345',\n    engine: 'runtime',\n    startedAt: '2025-01-15T10:00:00Z',\n    completedAt: '2025-01-15T10:05:00Z',\n    status: 'success',\n    tasks: [],\n  },\n});\n\nconsole.log(`Bundle exported to: ${bundlePath}`);\n```\n\n### Loading a Replay Bundle\n\n```typescript\nimport { ReplayBundleExporter } from '@ddse/acm-replay';\n\n// Load bundle\nconst bundle = await ReplayBundleExporter.load('./replay/run-12345');\n\nconsole.log('Goal:', bundle.goal);\nconsole.log('Plans:', bundle.plans.length);\nconsole.log('Ledger entries:', bundle.ledger.length);\nconsole.log('Task I/O records:', bundle.taskIO.length);\n```\n\n### Validating a Bundle\n\n```typescript\nimport { ReplayBundleExporter } from '@ddse/acm-replay';\n\nconst validation = await ReplayBundleExporter.validate('./replay/run-12345');\n\nif (validation.valid) {\n  console.log('Bundle is valid');\n} else {\n  console.error('Bundle validation errors:', validation.errors);\n}\n```\n\n### Integration with CLI\n\nThe replay package integrates seamlessly with the ACM demo CLI:\n\n```bash\n# Run with replay bundle export\npnpm --filter @ddse/acm-examples demo -- --goal refund --save-bundle\n\n# Bundle will be saved to ./replay/<runId>/\n```\n\n## Bundle Structure\n\nA replay bundle has the following directory structure:\n\n```\nreplay/run-12345/\n├── metadata.json                    # Bundle metadata\n├── goal/\n│   └── goal.json                    # Goal definition\n├── context/\n│   └── context.json                 # Context packet\n├── plans/\n│   ├── planA.json                   # Plan A\n│   └── planB.json                   # Plan B (if available)\n├── task-specs/\n│   ├── t1.json                      # Task spec for task t1\n│   └── t2.json                      # Task spec for task t2\n├── policy/\n│   └── requests.jsonl               # Policy decisions (JSONL)\n├── verification/\n│   └── results.json                 # Verification results\n├── memory-ledger/\n│   └── ledger.jsonl                 # Memory ledger entries (JSONL)\n├── engine-trace/\n│   └── run.json                     # Engine execution trace\n├── task-io/\n│   ├── t1.input.json                # Task t1 input\n│   ├── t1.output.json               # Task t1 output\n│   ├── t2.input.json                # Task t2 input\n│   └── t2.output.json               # Task t2 output\n└── planner-prompts/\n    └── messages.json                # Planner LLM messages (optional)\n```\n\n## API Reference\n\n### `ReplayBundleExporter`\n\nMain class for exporting and loading replay bundles.\n\n#### Methods\n\n**`static async export(options: ReplayBundleExportOptions): Promise<string>`**\n\nExport a replay bundle to disk.\n\n**Parameters:**\n- `outputDir`: Output directory path\n- `goal`: Goal object\n- `context`: Context object\n- `plans`: Array of Plan objects\n- `selectedPlanId`: ID of the selected plan\n- `ledger`: Array of ledger entries\n- `taskIO`: Array of task I/O records\n- `policyRecords`: Optional array of policy records\n- `verificationResults`: Optional array of verification results\n- `engineTrace`: Optional engine trace\n- `plannerPrompts`: Optional planner LLM messages\n\n**Returns:** Path to the created bundle\n\n**`static async load(bundleDir: string): Promise<Bundle>`**\n\nLoad a replay bundle from disk.\n\n**Parameters:**\n- `bundleDir`: Path to bundle directory\n\n**Returns:** Bundle object with all artifacts\n\n**`static async validate(bundleDir: string): Promise<ValidationResult>`**\n\nValidate a replay bundle structure.\n\n**Parameters:**\n- `bundleDir`: Path to bundle directory\n\n**Returns:** Validation result with errors if any\n\n### Types\n\n```typescript\ninterface ReplayBundleMetadata {\n  version: string;\n  createdAt: string;\n  runId: string;\n  goalId: string;\n  contextRef: string;\n  planId: string;\n}\n\ninterface PolicyRecord {\n  id: string;\n  ts: string;\n  action: string;\n  input: any;\n  decision: boolean;\n}\n\ninterface VerificationResult {\n  taskId: string;\n  ts: string;\n  expressions: string[];\n  results: boolean[];\n  passed: boolean;\n}\n\ninterface TaskIORecord {\n  taskId: string;\n  capability: string;\n  input: any;\n  output: any;\n  ts: string;\n}\n\ninterface EngineTrace {\n  runId: string;\n  engine: string;\n  startedAt: string;\n  completedAt: string;\n  status: 'success' | 'failed' | 'partial';\n  tasks: Array<{\n    taskId: string;\n    status: string;\n    startedAt: string;\n    completedAt?: string;\n    error?: string;\n  }>;\n}\n```\n\n## ACM v0.5 Compliance\n\nThis package implements the Replay Bundle artifact specification from ACM v0.5:\n\n- ✅ Complete artifact capture (Goal, Context, Plans, Tasks)\n- ✅ Policy decision recording\n- ✅ Verification results\n- ✅ Memory ledger in append-only format (JSONL)\n- ✅ Engine execution trace\n- ✅ Task I/O recording\n- ✅ Optional planner prompts for LLM transparency\n- ✅ Content-addressable references via metadata\n\n## Use Cases\n\n### Compliance & Audit\n\nExport bundles for regulatory compliance, providing complete audit trails:\n\n```typescript\n// Export after each production run\nawait ReplayBundleExporter.export({\n  outputDir: `./audit/runs/${runId}`,\n  // ... all execution data\n});\n```\n\n### Debugging\n\nLoad bundles to understand failures:\n\n```typescript\nconst bundle = await ReplayBundleExporter.load('./replay/failed-run');\nconsole.log('Failed at task:', bundle.ledger.find(e => e.type === 'TASK_ERROR'));\n```\n\n### Testing\n\nUse bundles to verify behavior:\n\n```typescript\nconst bundle = await ReplayBundleExporter.load('./test-fixtures/baseline');\n// Compare with new execution\n```\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}