feat(extensibility): implement Custom Sandbox Strategy Registration via SandboxStrategy Protocol #586

New issue

Closed

opened 2026-03-04 23:46:28 +00:00 by freemo · 0 comments

freemo commented

2026-03-04 23:46:28 +00:00

Owner

Metadata

Field	Value
Commit Message	`feat(extensibility): implement Custom Sandbox Strategy Registration via SandboxStrategy Protocol`
Branch	`feature/m6plus-custom-sandbox-strategy-registration`

Summary

Implement the SandboxStrategy Protocol and config-driven registration mechanism so that custom sandbox isolation strategies can be added for specialized resource types. The spec defines a 9-method Protocol that all sandbox strategies must implement.

Spec Reference

Section: Architecture > Extensibility > Custom Sandbox Strategies
Lines: ~44187-44204

Current State

Built-in sandbox strategies exist (git_worktree, filesystem_copy, etc.) but they are hardcoded.
No SandboxStrategy Protocol definition exists.
No mechanism to register custom strategies via configuration.
Resource type YAML configs reference sandbox_strategy by name but there is no plugin resolution for custom names.

Description

The spec defines a SandboxStrategy Protocol with 9 methods:

class SandboxStrategy(Protocol):
    def create(self, plan_id: str, resource: Resource) -> SandboxRef: ...
    def read(self, ref: SandboxRef, path: str) -> bytes: ...
    def write(self, ref: SandboxRef, path: str, content: bytes) -> Change: ...
    def diff(self, ref: SandboxRef) -> DiffView: ...
    def commit(self, ref: SandboxRef) -> None: ...
    def rollback(self, ref: SandboxRef) -> None: ...
    def checkpoint(self, ref: SandboxRef, checkpoint_id: str) -> None: ...
    def restore_checkpoint(self, ref: SandboxRef, checkpoint_id: str) -> None: ...
    def cleanup(self, ref: SandboxRef) -> None: ...

Custom strategies are mapped to resource types via:

The resource type configuration's sandbox_strategy field
Global sandbox.strategy config key
Plugin resolution via module:ClassName pattern

Use cases:

Database snapshot strategy (not just transaction rollback)
Cloud storage versioning (S3 versioned bucket)
Container-based isolation (Docker snapshot/restore)
Custom CoW implementations for specific filesystems

Acceptance Criteria

SandboxStrategy Protocol defined in domain layer with all 9 methods
SandboxRef model defined (plan_id, resource_id, strategy_name, metadata)
Change and DiffView models defined for write/diff return types
Existing built-in strategies refactored to implement SandboxStrategy Protocol
Config-driven custom strategy registration: sandbox.custom_strategies.<name>.module + .class
Resource type sandbox_strategy field resolves to both built-in and custom strategies
Plugin loader integration: custom strategies loaded via module:ClassName resolution
Protocol validation: verify custom strategy implements all 9 methods before registration
Unit tests for Protocol compliance checking
Integration test: register a mock custom strategy, create sandbox, verify lifecycle

Depends on: Plugin Architecture Framework (for module:ClassName resolution)
Related: Existing sandbox implementations (git_worktree, filesystem_copy, etc.)
Spec defines 6 built-in strategies: git_worktree, copy_on_write, filesystem_copy, overlay, transaction_rollback, none

Suggested Milestone

v3.6.0

Priority

Low

Suggested Assignee

@freemo — Architecture/sandbox system

Subtasks

Code: Define SandboxStrategy Protocol with all 9 methods and SandboxRef, Change, DiffView models
Code: Refactor existing built-in sandbox strategies to implement the SandboxStrategy Protocol
Code: Implement config-driven custom strategy registration (sandbox.custom_strategies.<name>.module + .class) with Protocol validation
Code: Integrate with plugin loader for module:ClassName resolution; wire into resource type sandbox_strategy field
Docs: Document the SandboxStrategy Protocol, registration mechanism, and extension patterns
Behave tests: Add BDD feature file features/extensibility/custom_sandbox_strategy.feature covering Protocol compliance and custom strategy registration
Robot tests: Add Robot Framework integration test: register mock custom strategy, create sandbox, verify lifecycle
ASV benchmarks: Add ASV benchmark for sandbox strategy resolution overhead (benchmarks/bench_sandbox_strategy.py)
Quality: coverage ≥97%: Verify via nox -s coverage_report
Quality: nox full suite: Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks below are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |-------|-------| | **Commit Message** | `feat(extensibility): implement Custom Sandbox Strategy Registration via SandboxStrategy Protocol` | | **Branch** | `feature/m6plus-custom-sandbox-strategy-registration` | ## Summary Implement the `SandboxStrategy` Protocol and config-driven registration mechanism so that custom sandbox isolation strategies can be added for specialized resource types. The spec defines a 9-method Protocol that all sandbox strategies must implement. ## Spec Reference **Section**: Architecture > Extensibility > Custom Sandbox Strategies **Lines**: ~44187-44204 ## Current State - Built-in sandbox strategies exist (git_worktree, filesystem_copy, etc.) but they are hardcoded. - No `SandboxStrategy` Protocol definition exists. - No mechanism to register custom strategies via configuration. - Resource type YAML configs reference `sandbox_strategy` by name but there is no plugin resolution for custom names. ## Description The spec defines a `SandboxStrategy` Protocol with 9 methods: ```python class SandboxStrategy(Protocol): def create(self, plan_id: str, resource: Resource) -> SandboxRef: ... def read(self, ref: SandboxRef, path: str) -> bytes: ... def write(self, ref: SandboxRef, path: str, content: bytes) -> Change: ... def diff(self, ref: SandboxRef) -> DiffView: ... def commit(self, ref: SandboxRef) -> None: ... def rollback(self, ref: SandboxRef) -> None: ... def checkpoint(self, ref: SandboxRef, checkpoint_id: str) -> None: ... def restore_checkpoint(self, ref: SandboxRef, checkpoint_id: str) -> None: ... def cleanup(self, ref: SandboxRef) -> None: ... ``` Custom strategies are mapped to resource types via: - The resource type configuration's `sandbox_strategy` field - Global `sandbox.strategy` config key - Plugin resolution via `module:ClassName` pattern ### Use cases: - Database snapshot strategy (not just transaction rollback) - Cloud storage versioning (S3 versioned bucket) - Container-based isolation (Docker snapshot/restore) - Custom CoW implementations for specific filesystems ## Acceptance Criteria - [ ] `SandboxStrategy` Protocol defined in domain layer with all 9 methods - [ ] `SandboxRef` model defined (plan_id, resource_id, strategy_name, metadata) - [ ] `Change` and `DiffView` models defined for write/diff return types - [ ] Existing built-in strategies refactored to implement `SandboxStrategy` Protocol - [ ] Config-driven custom strategy registration: `sandbox.custom_strategies.<name>.module` + `.class` - [ ] Resource type `sandbox_strategy` field resolves to both built-in and custom strategies - [ ] Plugin loader integration: custom strategies loaded via `module:ClassName` resolution - [ ] Protocol validation: verify custom strategy implements all 9 methods before registration - [ ] Unit tests for Protocol compliance checking - [ ] Integration test: register a mock custom strategy, create sandbox, verify lifecycle ## Related Issues - Depends on: Plugin Architecture Framework (for module:ClassName resolution) - Related: Existing sandbox implementations (git_worktree, filesystem_copy, etc.) - Spec defines 6 built-in strategies: git_worktree, copy_on_write, filesystem_copy, overlay, transaction_rollback, none ## Suggested Milestone v3.6.0 ## Priority Low ## Suggested Assignee @freemo — Architecture/sandbox system ## Subtasks - [ ] **Code**: Define `SandboxStrategy` Protocol with all 9 methods and `SandboxRef`, `Change`, `DiffView` models - [ ] **Code**: Refactor existing built-in sandbox strategies to implement the `SandboxStrategy` Protocol - [ ] **Code**: Implement config-driven custom strategy registration (`sandbox.custom_strategies.<name>.module` + `.class`) with Protocol validation - [ ] **Code**: Integrate with plugin loader for `module:ClassName` resolution; wire into resource type `sandbox_strategy` field - [ ] **Docs**: Document the SandboxStrategy Protocol, registration mechanism, and extension patterns - [ ] **Behave tests**: Add BDD feature file `features/extensibility/custom_sandbox_strategy.feature` covering Protocol compliance and custom strategy registration - [ ] **Robot tests**: Add Robot Framework integration test: register mock custom strategy, create sandbox, verify lifecycle - [ ] **ASV benchmarks**: Add ASV benchmark for sandbox strategy resolution overhead (`benchmarks/bench_sandbox_strategy.py`) - [ ] **Quality: coverage ≥97%**: Verify via `nox -s coverage_report` - [ ] **Quality: nox full suite**: Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks below are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

freemo self-assigned this

2026-03-05 00:30:27 +00:00

freemo added this to the v3.6.0 milestone

2026-03-05 00:30:28 +00:00

freemo added the