Workflow Schemas and Starter

Contracts live under schemas/ and are loaded by SchemaStore in src/rimthan_workflow_registry/schemas.py. They are used by authoring validation, compilers, MCP tool schemas, release loading, tests, and Studio TypeScript model shapes.

SchemaStore policy

SchemaStore loads schemas only from a configured local schema directory. schema(name) rejects path separators and special names, then loads {name}.schema.json, validates it as Draft 2020-12, and rejects non-bundled references. _validate_reference_policy permits only local fragment references (# or #/...) for $ref, $dynamicRef, and $recursiveRef. This prevents schema loading from reaching the network or unrelated files.

validate(name, instance) uses Draft202012Validator with FormatChecker and returns structured SchemaValidationError details with JSON pointer-like paths.

Current workflow-engine schema family

The step-gate workflow engine uses these central schemas:

Schema	Owner/use
workflow-engine-draft	Complete authoring envelope containing workflow_id, revision, definition, steps, assets, and validators.
workflow-definition	Workflow ID/version/title, aliases, entry_step, step list, terminal steps, confirmed-state schema, and required adapter capabilities.
workflow-step	Step instructions, inputs, outputs, workspace directories, host assets, validators, linear or branch transition, and terminal marker.
registry-asset	Versioned step instructions, validator instructions, prompts, skills, subagent definitions, JSON schemas, and host adapters with digest/byte length.
validator-definition	Versioned native-subagent validator contract: inputs, capabilities, isolation/tool mode, output schema, and required flag.
confirmed-state-projection	Participant-provided state plus field confirmations.
workspace-manifest	Setup artifact proving declared workspace directories and paths.
step-output-attestation and host-setup-attestation	Harness readback and host setup binding.
validation-bundle and validation-report	Signed semantic validation bundle and native-subagent report.
workflow-checkpoint-envelope	Client-carried checkpoint envelope returned by progression tools.

The MCP tool schemas in workflow_engine_tool_contracts embed these schemas into closed JSON Schema input/output contracts, so clients can discover the public protocol from the MCP tool list. Studio mirrors the major shapes in apps/admin-web/lib/types.ts.

Authoring semantic validation

rimthan_workflow_registry.workflow_engine.validate_engine_draft validates a complete authoring snapshot:

1. validate the draft envelope and definition;
2. require draft and definition workflow IDs to agree;
3. validate every step, reject duplicate step IDs;
4. validate every registry asset, recompute asset content digest/length, require canonical JSON for JSON assets, lint non-schema instructions, and validate host adapter contracts;
5. validate every validator definition and reject duplicates;
6. call validate_workflow_catalogue for cross-reference and graph invariants.

Important catalogue invariants include:

• entry step must be setup-workspace;
• terminal steps must exist and match each step's terminal marker;
• non-terminal steps must have exactly one transition form, next or branches;
• graph must be acyclic and every declared step reachable;
• branch predicates must be provably exclusive;
• setup owns workspace_directories for workflow versions 1.2.0 and newer;
• outputs must have one owner, safe relative paths, no path prefix conflicts, and JSON outputs must reference a schema asset;
• outputs must live under declared workspace directories for strict versions;
• setup must deliver required prompt, skill, and subagent definitions;
• validator instruction and output schema assets must exist;
• validator inputs must be available on the current step and dominated by prior owners on every incoming path.

semantic_engine_draft sorts steps, assets, and validators and excludes revision/layout. semantic_engine_draft_sha256 is the stored and published source digest used to prove exact revision publication.

Packaged research-decision starter

starter/workflow-engine/research-decision.draft.json is the current authoring fixture returned by Admin API /admin/v1/workflows/starter through builtin_engine_draft_path(). The tests show the packaged research-decision@1.2.0 workflow has an 11-step MVP path. It exercises setup, interview, contract confirmation, context installation, route selection, research production, semantic validation, failed-validator retry, explicit human review, and accepted terminal.

The starter carries versioned assets for step instructions, validator instructions, host adapters, prompts, skills, subagents, JSON schemas, and validators. Publication compiles those into manifest v2 aggregate sections as documented in Publication Pipeline.

Change recipe: add or change a workflow step

1. Add or version-bump the step instruction registry-asset.
2. Add or edit the workflow-step with safe output paths, owner step, write policy, validators, and exactly one transition form unless terminal.
3. Add the step ID to workflow-definition.steps; update terminal_steps if needed.
4. Ensure any input artifacts are owned by dominator predecessor steps.
5. Add/update output schemas or validator definitions as versioned assets.
6. Run authoring validation and publication tests.
7. Update Studio UI only if the schema shape changed.

Focused validation

• Schema validity: uv run pytest tests/test_schema_validation.py
• Engine draft semantics: uv run pytest tests/test_workflow_engine.py -k "engine_draft_validates or packaged_engine_draft"
• Starter fixture: uv run pytest tests/test_starter.py tests/test_workflow_engine.py -k packaged_research_workflow