Repository navigation
feat(workflow): declarative shelf-key schema contract + contract-driven debug probes - #1
Merged
Merged
Conversation
…en debug probes Add a declarative, per-shelf-key type contract to the workflow engine and wire it through the debug viewer's probe forms. A shelf key (e.g. input.job, read by 11 actions) is declared ONCE and shared — the contract lives with the key, not the action. Engine (foundation/workflow): - schema.py: ShelfSchema/FieldSchema — a self-defined type spec (no jsonschema dependency, keeps the package a leaf) with validate() + to_dict(). - loader.py: load_schemas() resolves a `schemas:` include (file globs or inline) into WorkflowNode.schemas; wired through both the normal and overlay paths. - graph.py: emit graph["schemas"] so any UI gets the contract for free. - visitor.py: opt-in enforcement in _write_outputs, gated by DISPATCH_ENFORCE_SCHEMA (OFF by default) — a violation fails the step cleanly via SchemaContractError, with zero change to live-pipeline behavior when unset. Contract: - app/config/schemas/baseworkflow.yml: types for all 17 input-read shelf refs (required, enum, numeric bounds, descriptions, prefill examples), referenced from baseworkflow.yml via `schemas: [../config/schemas/*.yml]`. Debug viewer (tools/debugviewer): - server.py: probe validates inputs against the contract, returns field errors. - viewer.html: probe forms render typed controls from the DECLARED schema (enum -> dropdown, required markers, numeric bounds, prefill), with client + server validation. Also: Cirrus CSS framework, centered graph, draggable inspector resize (persisted), collapsible attributes, light/dark toggle (persisted), color-scheme for native controls, and fixes for Cirrus global class collisions (button/select overflow, .row spacing). Tests: foundation/workflow/test_schema.py (8 cases). Full workflow + baseworkflow suites green; workflow validation unchanged (4 phases).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a declarative, per-shelf-key type contract to the workflow engine and drives the debug viewer's probe forms from it. A shelf key (e.g.
input.job, read by 11 actions) is declared once and shared — the contract lives with the key, not the action.Why
The debug viewer's probe previously used a single freeform textarea per input, with no type information anywhere in the model (
IORefcarried onlyalias/shelf/key; shelves are untypedAnystores). This introduces a real, single-source contract that both drives typed tooling and can enforce shape at runtime.Changes
Engine (
foundation/workflow/)schema.py—ShelfSchema/FieldSchema: a self-defined type spec (nojsonschemadep, keeps the package a leaf) withvalidate()+to_dict().loader.py—load_schemas()resolves aschemas:include (file globs or inline) intoWorkflowNode.schemas; wired through the normal and overlay paths.graph.py— emitsgraph["schemas"]so any UI gets the contract.visitor.py— opt-in enforcement in_write_outputs, gated byDISPATCH_ENFORCE_SCHEMA(off by default); a violation fails the step cleanly viaSchemaContractError.Contract
app/config/schemas/baseworkflow.yml— types for all 17 input-read shelf refs (required, enum, numeric bounds, descriptions, prefill examples), referenced frombaseworkflow.ymlviaschemas: [../config/schemas/*.yml].Debug viewer (
tools/debugviewer/)server.py— probe validates inputs against the contract, returns per-field errors.viewer.html— probe forms render typed controls from the declared schema (enum → dropdown, required markers, numeric bounds, prefill) with client + server validation. Also: Cirrus CSS, centered graph, draggable inspector resize, collapsible attributes, light/dark toggle, native-control theming, and fixes for Cirrus global class collisions.Verification
foundation/workflow+baseworkflowtest suites greenfoundation/workflow/test_schema.py(8 cases)[PASS] … (4 phases)run_mockgreen with enforcement off and on — the contract matches real data (no false positives)SchemaContractErrorSafety
Enforcement ships off (
DISPATCH_ENFORCE_SCHEMAunset) — zero change to live-pipeline behavior. Recommend a shadow/log-only pass across a few live ticks before enabling it.