KODAX_PARITY.md

KodaX workflow parity contract

This document is the acceptance matrix for @dsh-external/workflow. It records behavior, not copied implementation. KodaX is the design reference; the plugin is an independent DSH/Cordis implementation.

Capability family	KodaX reference behavior	DSH plugin contract
Workflow module	Metadata plus run(wf, args)	Same authoring model for restricted capsules and trusted-local modules
Capsule	Versioned JSON, source, manifest, intent, inputs, requirements, provenance	dsh.workflow v1 with the same information classes and DSH version provenance
Restricted runner	Static host-API policy, isolated capability RPC, sync/wall timeout, JSON boundary, deterministic clock/randomness	QuickJS/WASM separate heap, JSON-only host bridge, CPU/wall/memory/stack limits, deterministic guards, and bridge shutdown on timeout
Trusted-local runner	.ts/.mjs/.js, distinct trust class, confirmation	Same suffixes and explicit one-shot DSH approval before host execution
WorkflowApi identity	runId, args, budget view	Same
Agent task API	spawn, run, wait, snapshot/output, send, stop	Same, adapted to ctx.subagents; runAgent isolates ordinary terminal failure as null, while handle-based wait retains the complete result; unsupported provider features fail before launch
Agent request metadata	name/phase/prompt/scope/constraints/readOnly/type/target/model hint/isolation/effort/evidence/verification/schema/terse result	Same contract. Native provider/model/toolFilter/outputSchema/maxTokens fields map directly; command-authored source smoke-validates the same dispatch contract before consuming its one-shot grant; deployment dispatch and isolation adapters provide DSH-dependent target/effort/worktree seams and otherwise fail loud
Coordination	phase, concurrency-limited parallel, item-streaming pipeline, ordinary-failure isolation	Same
Synthesis	Dedicated synthesizer child	Same, routed through configurable DSH provider/model tier
Nesting	Named nested workflow, maximum one level	Same
Artifacts/logs	Named JSON artifacts and progress events	Same, durable in run graph
Limits	Planned/max agents, max concurrency, token budget	Same; DSH token allocation is reserved before start and reconciled from local Session usage when available
Read-only policy	Child write capabilities restricted	Fail-closed DSH toolFilter allow-list dynamically intersected with the actual parent catalog; unknown, platform-specific, and newly introduced mutation tools cannot leak through
Worktree isolation	Shared cwd or isolated git worktree	Shared cwd is native. Worktree requests pass only when a configured DSH-capable isolation adapter is available; otherwise preflight rejects rather than sharing cwd silently
Verification	Mutation/read-path/final-text postconditions, warn or hard, bounded repair	Built-in read evidence, successful mutation tool plus Git workspace fingerprint change, per-required-path before/after fingerprints, structured result, completed_unverified, and up to two same-actor hard repairs; versioned optional adapter adds non-Git or stronger workspace evidence
Structured output	Object JSON Schema, captured structured result, bounded format repair	DSH outputSchema capability plus exactly one same-route, tool-free repair for absent/invalid capture (including rc.2's error-with-report shape); a schema-invalid repair fails the task, and unsupported providers fail loud
Model routing	fast/balanced/deep hints and explicit target	Configured tier map keeps the DSH subagent transport distinct from the LLM provider/model route; exact subagent/provider/model overrides remain available
Events/process	Workflow, phase, agent, message, synthesis, artifact, terminal events and process snapshots	Stable phase/agent/step/artifact ProcessSnapshot items with counts, progress, last text and replay origin; domain events plus native tool-workflow/* Session records reuse the existing DSH UI. Dynamic starts are explicitly Session-scoped so a background run outlives the launching step and remains live until its terminal event
Run lifecycle	list/get/subscribe, pause/resume/stop	Same. Pause gates future launches; stop aborts and disposes active children
Durable graph	run.json, append-only events, artifacts, snapshots, cost report	Same classes of records under the configured DSH run directory
Resume/rerun	Run-id snapshot rerun, saved-name current rerun, successful result cache replay	Same distinction; only completed and verification-clean effects are cached, effective read-only policy/runtime/verification identity participates in cache keys, and replay retains the original result status with explicit replay origin
Retention	Delete, force stale deletion, prune preview/execute	Same with containment/path checks
Identity	Resolve run id, display alias, saved name; report ambiguity	Same
Discovery	Built-in + project/personal saved; capsule preferred; project shadows personal; trusted-local suffixes	Same priority model under .dsh/workflows and $DSH_HOME/workflows
Save/rename/revise	Save generated run, rename, archive-on-replace, provenance	Same, with atomic exclusive publication and canonical-root junction/symlink rejection
Generation	Scout-then-author, structured capsule, validation, quality lint, bounded repair and smoke execution	Same, using DSH subagents, structured output, semantic checks, three author attempts, and isolated fake-capability smoke execution
Preflight	Environment/tools/MCP/skills/model tiers/user interaction, approval summary	Same requirement vocabulary with DSH capability inventory config and service checks
Approval	Generated and trusted-local execution governed before launch	DSH ctx.approval, fail closed without a grant when policy requires it; a /workflow handoff grant is consumed only by the first inline capsule that passes pre-launch smoke validation
Built-ins	Parameterized parallel investigation and immutable-packet scoped review	Parallel investigation honors rubric/agent/concurrency bounds. Public packet input/writer freezes explicitly captured diff/requirements/test evidence into path-contained, budgeted, content-addressed, non-overwriting manifests and chunks. Scoped review enforces packet metadata, strict schemas/read contracts, a second high-risk primary, deterministic finding IDs, exact per-finding disposition, reason-gated severity changes, and audit artifact
Patterns	classify-and-act, fan-out-and-synthesize, adversarial-verification, generate-and-filter, tournament, loop-until-done	Independent templates with identical orchestration shapes
Human UX	/workflow list/create/run/runs/show/pause/resume/stop/delete/prune/rerun/save/rename/revise/help and Git review bridge	Same command surface via ctx.commands; free-text/create immediately hand Worker-owned scout-then-author work to the current Agent. The original query is a visible human Session message that feeds DSH title and Workspace surfaces, while authoring instructions remain separate plugin context. /workflow review captures default/base/commit diffs, requirements and reported test evidence into immutable packets before starting the built-in (no DSH core patch required). Starts return immediately by default; commands that support terminal waiting expose --wait, show defaults to latest, and stop defaults to the active run
Model UX	Inline run_workflow authoring/execution and process visibility	run_workflow, workflow_list, and workflow_manage, backed by the same service and immediate durable-process defaults
Outcome/cost	Stable workflow outcome, results, coverage/unresolved/errors, artifacts and aggregate usage	Same independent WorkflowOutcome result projection plus DSH wall time, peak concurrency, measured Session/dispatch usage, and requested/resolved route/fallback telemetry without inventing absent remote usage

DSH-specific compatibility rules

1. DSH remains the authority for agents, provider capabilities, tool visibility, approval, user questions, cancellation, Session events, and background job ownership.
2. A parity capability that cannot be honored by the selected DSH provider is rejected during preflight or task start. No request field is accepted and ignored.
3. Existing DSH ctx.workflows and the model-facing workflow tool remain available. This plugin is the reusable/process layer; it does not patch the agent loop or replace the native foreground script engine.
4. KodaX capsule files are not declared wire-compatible because their runtime/version provenance names KodaX. A migration command may translate data explicitly in a future version; the v0.1 line never executes a foreign capsule by accident.
5. target, effort, and worktree semantics are part of the public API. Because rc.2 has no universal host seam for them, the plugin requires an authority adapter registered before the first run; lack of that authority is a preflight error, never an ignored downgrade.