architecture: converge generic workflow contracts on Agents API without replacing Data Machine durability

[chubes4]

Summary

Converge Data Machine's portable workflow contract, canonical dispatch surface, and generic run envelope on the current Agents API workflow substrate while retaining Data Machine as the durable domain runtime for jobs, packets, retries, recovery, persisted flows, and undo.

This is not a request to replace the Data Machine engine wholesale. A fresh cross-repository audit shows that Agents API has advanced substantially since the original bridge in #2339, but it still does not provide the durability protocol Data Machine requires.

Audited revisions

• Data Machine: 92601c36d (main, current with origin/main)
• Agents API: 5f89329 (main, current with origin/main)

Since June, Agents API added or hardened:

• extracted workflow step execution and consumer step handlers (feat: expose agent memory as global AI tool #335, Agent workspace: managed directory for repos and working files #337, Container compatibility: ensure Data Machine works inside Docker containers #340);
• canonical run control and result envelopes (feat: Inbound webhook trigger for flow execution #343, Rename agent CLI namespace to memory #354, feat: Support pre-authenticated context in PermissionHelper #356);
• generic parallel map/roles contracts (workspace write: support @file syntax for --content flag #389, fix: Multisite activation and new site support (#382) #395);
• suspend/resume and the branch-executor seam (feat: Include post_id, post_type, published_url in agent ping payload (#383) #391);
• Action Scheduler branch execution and reconciliation (feat: Add 'wp datamachine posts recent' CLI command (#384) #392, docs: Add workspace CLI reference to agent skill (#381) #394, fix: Comprehensive uninstall cleanup with multisite support (#382) #396, Analytics tool: Google Analytics (GA4) integration #397);
• scoped draining and run awaiting (fix: memory system improvements #406, Agent file scaffolding should populate useful defaults from WordPress #409, CLI: jobs show displays empty Engine Data for pipeline jobs #422, feat: GitHub integration — fetch handler, abilities, CLI, chat tools #456, Bug: --set-prompt wipes handler_configs when handler step not detected #458);
• request-scoped workflow control (Fix PostTrackingTrait never writing meta to posts #464);
• artifacts, logs, evidence, and replay metadata (feat: agent workspace for managed repo operations #339, docs: Add comprehensive documentation for all analytics tools #405);
• security hardening around branch reconciliation (Internal crosslinker has template title bias — links unrelated posts across the site #479).

The original Data Machine bridge predates most of that substrate.

Current overlap and drift

Duplicate workflow execution entry points

Data Machine exposes datamachine/execute-agent-workflow in:

• inc/Abilities/Job/ExecuteAgentWorkflowAbility.php:28-87

Agents API already owns canonical workflow dispatch through agents/run-workflow and the wp_agent_workflow_handler runtime seam:

• Agents API src/Workflows/register-agents-workflow-abilities.php:207-266

Data Machine currently does not register that runtime seam. Consumers must know which of two workflow abilities to call.

The bridge subset is stale

ExecuteAgentWorkflowAbility accepts only top-level ability and agent steps:

• inc/Abilities/Job/ExecuteAgentWorkflowAbility.php:21
• inc/Abilities/Job/ExecuteAgentWorkflowAbility.php:189-229

Current Agents API ships ability, agent, foreach, and parallel, supports consumer step types, and includes real asynchronous suspension/resume.

The bridge's restriction was correct when #2339 shipped, but it no longer describes the substrate.

Recorder wiring is request-local

Data Machine has the right persistence seam:

• inc/Core/AgentsApiWorkflowJobRecorder.php:17-235

It records Agents API runs in the Jobs table and implements start, update, find, and recent. However, ExecuteAgentWorkflowAbility constructs it locally at :130-152; it is not registered through the global recorder/resume seam used by asynchronous branch reconciliation.

Consequently, simply allowing parallel in the current bridge would be unsafe: a later Action Scheduler process could not reliably resolve the same recorder and resume the suspended run.

Parallel contract ownership is split

ParallelMapFanoutAdapter explicitly says Agents API owns the parallel contract while Data Machine reconstructs the gate and output envelope and dispatches through PipelineBatchScheduler:

• inc/Abilities/Engine/ParallelMapFanoutAdapter.php:7-63
• inc/Abilities/Engine/ParallelMapFanoutAdapter.php:120-160
• inc/Abilities/Engine/ParallelMapFanoutAdapter.php:182-247

This is the clearest long-term convergence candidate, but the current Data Machine backend also owns packet claims, child jobs, durable worklists, and terminal rollup. Those semantics must not be discarded to remove an adapter.

Generic-looking runtime surface is large, but not generically removable

The following current files alone are about 5,100 lines:

• ExecuteStepAbility.php — 1,563
• ScheduleNextStepAbility.php — 350
• PipelineBatchScheduler.php — 734
• BatchScheduler.php — 1,077
• JobRetryPolicy.php — 781
• DirectJobEnqueuer.php — 282
• RunLifecycleStore.php — 340

Most of those lines enforce Data Machine domain durability, not generic workflow syntax. The goal is to delete duplicated contracts and dispatch surfaces while preserving that behavior.

Target ownership

Agents API owns

• portable WP_Agent_Workflow_Spec syntax and structural validation;
• ${inputs.*}, ${steps.*}, and ${vars.*} bindings;
• canonical agents/run-workflow dispatch;
• generic step-handler and executor extension seams;
• canonical run statuses and result envelope;
• generic foreach and parallel orchestration contracts;
• run-control, suspension/resume, and evidence/replay carrier contracts;
• substrate-level Action Scheduler execution when its guarantees are sufficient.

Data Machine owns

• persisted pipelines and flows as product/domain configuration;
• datamachine_jobs as the authoritative operational ledger and workflow recorder;
• user/agent authority, idempotency keys, parent-child jobs, and operation generations;
• per-step durable Action Scheduler receipts and stale-generation fencing;
• DataPacket persistence and processed-item claim/disposition accounting;
• retries, backoff, poison-item isolation, checkpoint recovery, and stuck-job repair;
• waiting/webhook/backpressure semantics;
• durable leased batch worklists, packet fanout ownership transfer, and child rollup;
• terminal accounting, metrics, notifications, artifacts, retention, and operator tooling;
• system-task effect ledgers and undo.

Agents API deliberately leaves stores and recorders to consumers. Data Machine's tables are therefore the correct consumer backend, not duplication to remove.

Why wholesale replacement is unsafe

Current Agents API ordinary steps run in one PHP request; only parallel branches cross an Action Scheduler boundary. Data Machine schedules each step durably and persists ownership before and after effects.

Agents API currently lacks equivalents for:

• delayed whole-run enqueue with Data Machine's idempotency and operation-generation protocol;
• general per-step retry/backoff/checkpoint semantics;
• general durable waits beyond the parallel suspension shape;
• DataPacket storage and processed-item dispositions;
• parent/child pipeline job rollup;
• durable leased batch worklists;
• flow admission, pause, queue, and backpressure policy;
• terminal accounting and undo.

Migrating those responsibilities directly would be a correctness regression, not simplification.

Upstream blockers discovered by the fresh audit

Before Data Machine uses the Agents API Action Scheduler executor for side-effecting packet workflows, these current substrate issues must be resolved:

• fix: make parallel branch admission all-or-nothing Automattic/agents-api#531 — partial fanout admission can leave already-enqueued sibling branches live.
• fix: prevent reconcile lock expiry during aggregation Automattic/agents-api#532 — the 60-second reconcile lock can expire while an arbitrary aggregator still runs.
• fix: retry branch reconciliation without re-executing completed effects Automattic/agents-api#533 — reconcile lock retries enqueue the original branch action and can execute completed branch effects twice.

Further gaps that should be tracked separately before broad convergence:

• general generation-bound park/resume independent of parallel aggregation;
• versioned/atomic recorder mutation requirements for resumable workflows;
• async cancellation propagation and terminal fencing;
• durable per-step execution/receipt primitives;
• step-type validation schemas paired with consumer handlers.

Migration plan

Phase 1: canonical dispatch, existing simple subset

• Register Data Machine as a runtime handler behind agents/run-workflow using wp_agent_workflow_handler.
• Route the currently supported simple ability/agent subset through WP_Agent_Workflow_Runner.
• Resolve a Jobs-backed recorder through the canonical recorder seam rather than constructing an isolated request-local instance.
• Preserve Data Machine job provenance and authority checks.
• Inventory actual consumers of datamachine/execute-agent-workflow; migrate them to agents/run-workflow, then remove the duplicate ability rather than retaining an indefinite alias.

Phase 2: canonical result projection

• Store and return the Agents API canonical run-result envelope directly.
• Keep Data Machine status projection only at the Jobs boundary.
• Remove duplicate result/status carriers that become unreachable, with grep and test evidence.
• Coordinate with Expose workflow run observability for frontend brain operations dashboards #2564 so frontend observability reads one stable projection.

Phase 3: explicit Data Machine step integration

• Define a narrow Data Machine custom step handler/backend for domain execution rather than teaching Agents API about DataPackets, flows, or jobs.
• Add a matching validation contract upstream before accepting custom Data Machine step specs as portable workflows.
• Keep persisted flow configuration in Data Machine and compile a portable projection only where semantics are lossless.

Phase 4: evaluate fanout backend convergence

Only after #531, #532, and #533 are resolved:

• compare Agents API branch execution against PipelineBatchScheduler under realistic Events workloads;
• preserve Data Machine child jobs, packet claim transfer, worklist durability, cancellation, and terminal rollup;
• either register Data Machine's durable pipeline backend behind the Agents API executor contract or adopt the substrate backend where measured semantics match;
• remove ParallelMapFanoutAdapter only when no behavior is lost.

Phase 5: delete proven duplication

Delete only code made unreachable by the converged path. Do not measure success by replacing Data Machine domain behavior with weaker generic behavior.

Acceptance criteria

• One canonical portable workflow entry point: agents/run-workflow.
• Data Machine registers as a consumer runtime rather than exposing a competing generic workflow ability.
• Data Machine Jobs remain the authoritative recorder and can resolve runs across requests/processes.
• Simple ability and agent workflows execute through the canonical path with preserved job provenance.
• Suspended/resumed runs use a globally resolvable, durable recorder before parallel support is enabled.
• Persisted flows, packets, claims, retries, recovery, waiting states, batching, and undo retain current semantics.
• No in-flight legacy job is switched to a different execution model.
• Every deletion is backed by consumer inventory, grep evidence, and regression coverage.
• Architecture tests enforce that Agents API remains domain-agnostic and Data Machine-specific names do not move upstream.
• The issue is split into bounded implementation issues/PRs by phase; no all-at-once runtime rewrite.

Non-goals

• Replacing datamachine_jobs with Agents API's option-backed run control.
• Converting all persisted flows into plain workflow specs.
• Moving DataPacket, claim, retry, recovery, batching, or undo behavior into Agents API.
• Enabling Agents API parallel execution for side-effecting Data Machine workloads before the upstream blockers are fixed.
• Maintaining two permanent public workflow abilities for compatibility without an identified consumer.

Related

• Bridge simple Agents API workflows into Data Machine jobs #2339
• Complete Agents API workflow recorder lookup support #2524
• Expose workflow run observability for frontend brain operations dashboards #2564
• Resume-from-checkpoint retry for multi-step ephemeral workflows (follow-up to #2810) #2811
• Add a generic parallel workflow step handler (agent fanout) Automattic/agents-api#389
• Suspendable workflow run model + branch-executor seam (Phase 1) Automattic/agents-api#391
• Action Scheduler branch executor for async parallel branches (Phase 2) Automattic/agents-api#392
• Add request-scoped workflow controller Automattic/agents-api#464
• fix: make parallel branch admission all-or-nothing Automattic/agents-api#531
• fix: prevent reconcile lock expiry during aggregation Automattic/agents-api#532
• fix: retry branch reconciliation without re-executing completed effects Automattic/agents-api#533

AI assistance

• AI assistance: Yes
• Tool: OpenCode (GPT-5.6)
• Used for: Fresh cross-repository architecture audit, current-source verification, migration boundary design, and issue drafting. Chris remains responsible for prioritization and implementation review.