Protocol

Protocol owns Homeostat's process-minimum JSON Schemas, compatibility declarations, migrations, and conformance fixtures. It does not own consumer architecture, commands, persona substance, or definitions of correctness.

The initial schemas make the functional control model concrete:

• an invocation receives an assignment and trusted inputs;
• a result returns human-readable output, evidence, findings, mutations, and typed continuations;
• a continuation names a declared capability rather than executable workflow text;
• a reading is observation only;
• a finding is an evaluator's interpretation;
• an invocation carries a budget that bounds the graph it belongs to; and
• compatibility declares readable and writable schema versions.

Conformance

Fixtures are discovered by name, so a schema and its worked examples stay together:

• fixtures/valid/<schema>.<variant>.json is a document the schema accepts. Every schema carries at least one, and the validator fails when one does not.
• fixtures/invalid/<schema>.<variant>.json wraps a rejected document beside the expect clause naming the rejection it proves. A rejecting fixture that stops being rejected, or that fails for a different reason than it claims, fails the suite.

The validator also enforces the referential rules JSON Schema cannot express: a continuation orders itself only after a sibling that exists, a set of continuations contains no ordering cycle, a mutation reports only an effect that was declared, and an invocation's lineage matches the budget it carries. Interpreters persist an ordered continuation as deferred_dependency; it opens only after every reserved descendant of each prerequisite branch is terminal.

Install and run:

python3 -m pip install .
python3 tools/validate.py

Python 3.11+. The package requests jsonschema's format extra; the validator also registers deterministic date-time and uri fallbacks for supported jsonschema installations where those optional checkers are absent.

Versions

docs/versioning.md defines the wire version and the component release, what separates a minor from a major wire change, and the order in which readers and writers move. migrations/ records every transition.

NOTES.md carries open items this repository has identified but not closed.

Consumer-facing schemas

Consumers pin a Protocol checkout and read schemas directly from schemas/. Composite schemas are therefore self-contained single files: their repository owned part schemas are copied under $defs and referenced with local $ref fragments. Run python3 tools/bundle.py after changing a composite or one of its part schemas. The normal validator runs the same command with --check, so stale bundles cannot pass validation.