Automattic / Automattic/wp-codebox
Collapse execution surfaces into one canonical request and result
- Dominant language
- TypeScript
- Stars
- 16
- Forks
- 4
- Avg merge
- 59m
- Merged PRs (30d)
- 131
Description
Parent: #2429
## Problem
WP Codebox exposes overlapping execution concepts across runtime requests, recipes, tasks, workloads, packages, run plans, episodes, batch, and fanout. Each adds validation, status projection, artifact projection, CLI routing, PHP adaptation, and documentation.
The result is not merely a large API. Multiple layers can own planning and lifecycle for the same run, which creates translation code and divergent failure semantics. #1827 documents the downstream consequence: Codebox and Homeboy both own task translation, workspace snapshots, application, verification, publication, and terminal projection.
## Desired shape
Define one canonical versioned execution request and one canonical versioned result at the Codebox boundary.
The request should describe:
- runtime backend/profile requirements;
- mounts and materialized inputs;
- execution policy;
- ordered or bounded execution steps;
- required artifact/evidence classes;
- caller correlation metadata.
The result should describe:
- terminal execution status and normalized failure;
- runtime and input provenance;
- command/step results;
- workspace delta;
- artifact and evidence references;
- cleanup outcome.
Recipes, agent tasks, workloads, packages, batch, and fanout may remain authoring or orchestration helpers, but they must compile to the canonical request before entering Codebox and consume the canonical result after execution. They are not independent runtime protocols.
## Acceptance criteria
- One public request schema enters the runtime execution engine and one public result schema leaves it.
- Every higher-level helper has a deterministic compiler to that request rather than a separate executor.
- Backend implementations receive the same request contract and return backend evidence through the same result contract.
- Status and failure taxonomy are defined once.
- Homeboy uses the canonical boundary described by #1827 and owns retries, verification, apply, promotion, and publication.
- Known consumers are migrated and obsolete execution protocols are removed.
- Contract tests cover success, no-op, policy rejection, malformed input, runtime failure, timeout/interruption, partial evidence, and cleanup failure.
## AI assistance
- **Model:** OpenAI gpt-5.6-sol
- **Tool:** OpenCode
- **Used for:** Mapped overlapping execution surfaces and drafted a single request/result consolidation contract under Chris Huber's direction.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at the Codebox boundary and runtime execution engine, then map the recipes, agent tasks, workloads, packages, batch, and fanout helpers described here. Review issue #1827 for the Homeboy boundary and identify how each helper currently enters and leaves execution. Done means one versioned request and result contract, migrated consumers, removed obsolete protocols, and contract coverage for every listed outcome.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, typescript
- Domain
- backend, backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100