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.)