[Forge] Automatic runtime environment capture for analysis capsules

Goal

Implement automatic environment pinning when analysis capsules are created. Capture pip/conda/nix dependencies, container image digests, and compute a deterministic environment_digest so capsules can be reproduced months or years later.

Acceptance Criteria

☐ forge/runtime_capture.py module with environment discovery functions

☐ capture_python_environment() -> Dict captures pip packages, Python version, conda env

☐ capture_container_environment() -> Dict captures Docker image digest, runtime info

☐ compute_environment_digest(env: Dict) -> str generates deterministic SHA256

☐ Agent and post_process automatically capture environment on analysis completion

☐ Capsules are auto-registered with captured environment metadata

☐ Verification endpoint checks if captured environment still matches available runtime

Approach

Create forge/runtime_capture.py with:

def capture_python_environment() -> Dict:
       """Capture Python packages, version, and virtual environment."""
       # Use importlib.metadata to get installed packages
       # Include Python version, pip version, conda environment if active
       # Return dict sorted for deterministic hashing

   def capture_container_environment() -> Dict:
       """Capture container image digest if running in Docker."""
       # Check /proc/self/cgroup for container ID
       # Query Docker daemon for image digest
       # Return container metadata or None if not in container

   def compute_environment_digest(env: Dict) -> str:
       """Generate deterministic SHA256 hash of environment."""
       # Sort keys recursively, canonicalize JSON
       # Return hex digest

   def verify_environment_match(capsule_env: Dict) -> Dict:
       """Check if current environment matches capsule's captured environment."""
       # Re-capture current environment
       # Compare with capsule's environment_digest
       # Return match status with diff

Integrate with agent.py:

- After analysis completes, capture environment
- Register capsule with captured metadata
- Store environment_digest in capsule manifest

Integrate with post_process.py:

- Add --capture-capsule flag to generate capsule after analysis
- Auto-register capsule with environment digest

Extend artifact_registry.py capsule functions:

- register_capsule() accepts environment_capture: Dict parameter
- verify_capsule() calls verify_environment_match()

Add API endpoint to api.py:

- GET /api/capsules/{capsule_id}/environment-verify - check environment match

Dependencies

docs/planning/specs/quest_reproducible_analysis_capsules_spec.md — parent quest
artifact_registry.py — capsule registration functions (already exists)
agent.py — analysis execution (already exists)

Dependents

All future capsules will have automatic environment capture
Verification workflows can check if environment still matches

Work Log

2026-04-11 08:00 PT — glm-4.5

Spec created as part of capsule quest gap analysis.
High-priority (84) - foundational for capsule reproducibility.
Independent of blob storage - can be implemented in parallel.
Ready to be spawned as one-shot task.

File: runtime_capture_spec.md

Modified: 2026-04-25 17:55

Size: 3.5 KB