dacp-interpreter

---
name: dacp-interpreter
description: "Load, validate, and use DACP bundles as structured execution context. Detects .bundle/ companion directories, validates integrity (manifest schema, fidelity, provenance), loads typed data, and builds ExecutionContext for receiving agents. Scripts are NEVER auto-executed. Use when processing incoming DACP bundles, interpreting .bundle/ directories alongside .msg files, validating bundle integrity, or building execution context from bundle payloads."
---

# DACP Interpreter

Scripts in bundles are **review-only references** — the interpreter NEVER auto-executes any script (SAFE-01).

## Summary

The DACP Interpreter handles receiving-side bundle processing. When a `.bundle/` directory appears alongside a `.msg` file, the interpreter detects, validates, loads, and integrates the bundle into a structured `ExecutionContext`.

### Fidelity Level Guide

| Level | Contents | What to Do |
|-------|----------|------------|
| 0 | Intent markdown only | Read intent.md, proceed with instructions |
| 1 | Intent + structured data | Access `typedData` for structured parameters |
| 2 | Intent + data + schemas | Validate your understanding against schemas |
| 3 | Intent + data + code | Review scripts, decide whether to execute or reference |
| 4 | Intent + data + code + tests | Verify with provided test fixtures before proceeding |

### Interpretation Pipeline

```
DETECT -> VALIDATE -> LOAD -> INTEGRATE
  |          |         |         |
  |          |         |         +-- buildExecutionContext()
  |          |         +-- loadBundle()
  |          +-- validateBundle()
  +-- Check for .bundle/ directory
```

## Workflow

### Step 1: Detect Bundle Companion

Look for a `.bundle/` directory alongside the `.msg` file. If found, prefer the bundle over raw `.msg` content.

### Step 2: Validate Bundle

Call `validateBundle(bundlePath)` to check:
   - `.complete` marker exists (atomicity guarantee)
   - `manifest.json` parses and validates against Zod schema
   - Fidelity level matches actual directory contents
   - All referenced data and code files exist on disk
   - Size limits respected (50KB data, 10KB per script, 100KB total)
   - Data payloads validate against referenced JSON schemas
   - All scripts have provenance (source skill attribution)

### Step 3: Load Bundle

Call `loadBundle(bundlePath)` to get a typed `LoadedBundle` with:
   - Parsed manifest object
   - Raw intent markdown
   - JSON data payloads as typed objects
   - Schema definitions
   - Script content loaded for review

### Step 4: Build Execution Context

Call `buildExecutionContext(loadedBundle)` to get:
   - `intentSummary` -- what the sender wants done
   - `intentMarkdown` -- full instructions
   - `typedData` -- structured parameters you can use directly
   - `scriptReferences` -- scripts to review (NOT execute blindly)
   - `assemblyRationale` -- why the bundle was composed this way

### Step 5: Review Scripts Before Use

For each script in `scriptReferences`:
   - Read the script content
   - Understand what it does
   - Decide: execute it, reference its logic, or skip it
   - NEVER execute without reviewing first

### Step 6: Report Outcome

After completing the work, report the handoff outcome (intent alignment, rework needed, verification status) for drift tracking.

## Error Handling

### Invalid Bundles

If `validateBundle()` returns `valid: false`:
- Check if a `.msg` fallback file exists alongside the bundle
- If yes: fall back to `.msg` content (backward compatibility)
- If no: report the validation errors and request a re-send

### Provenance Failures

Scripts without a valid `source_skill` in the manifest are rejected. This ensures
every executable artifact traces back to a known, versioned skill. If provenance
validation fails:
- Do NOT use the script
- Report which scripts failed provenance
- Request a corrected bundle from the sender

## References

- `src/interpreter/validator.ts` -- bundle validation pipeline
- `src/interpreter/loader.ts` -- bundle loading into typed structures
- `src/interpreter/context-builder.ts` -- execution context assembly
- `src/interpreter/provenance-guard.ts` -- deep provenance validation
- `src/interpreter/types.ts` -- type definitions (LoadedBundle, ExecutionContext, etc.)
- `src/dacp/types.ts` -- DACP type system (BundleManifest, FidelityLevel, etc.)