Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/canon-boundary-guard-for-gpt-project/llms.txt

Use this file to discover all available pages before exploring further.

validate_state.py performs mechanical schema checks on SESSION_STATE.json and CANON_STATE_DELTA.json files. It verifies structure, types, required keys, and cross-file constraints — but it does not decide provenance. Determining whether a piece of content is L0, L1, or L1A remains the operator’s responsibility. The script is an optional helper; the protocol does not depend on it being present.

​
Prerequisites

  • Python 3 (no third-party packages required for basic use)
  • jsonschema (optional) — when installed, the script uses Draft202012Validator for full schema validation. When not available, it automatically falls back to a strict manual validator that covers the same schema keywords used in the Canon Boundary Guard schemas.
Install the optional dependency with: 
pip install jsonschema

​
Usage

# Validate a SESSION_STATE file only
python scripts/validate_state.py --state /path/to/SESSION_STATE.json

# Validate a CANON_STATE_DELTA file only
python scripts/validate_state.py --delta /path/to/CANON_STATE_DELTA.json

# Validate both files together
python scripts/validate_state.py --state /path/to/SESSION_STATE.json --delta /path/to/CANON_STATE_DELTA.json

# Emit a machine-readable JSON report
python scripts/validate_state.py --state /path/to/SESSION_STATE.json --json

​
Arguments

​
--state
Path
Path to the SESSION_STATE.json file to validate.
​
--delta
Path
Path to the CANON_STATE_DELTA.json file to validate. Can be combined with --state to validate both files in a single run.
If both --state and --delta are omitted, the script calls parser.error() and exits immediately with a usage error. At least one of the two flags must be supplied.
​
--json
flag
Emit a JSON validation report to stdout instead of the default plain-text output. Useful for piping results into other tools or storing the report as an artifact.

​
Output

​
Plain text (default)

When validation passes, the script prints valid and exits with code 0. When validation fails, it prints invalid followed by a bullet list of error messages, and exits with code 1. 
valid

invalid
- SESSION_STATE: missing required key: state_seq
- SESSION_STATE: unexpected key: legacy_field

​
JSON report (--json)

The JSON report always contains valid (boolean) and errors (array of strings). When there are no errors, errors is an empty array. 
{
  "valid": true,
  "errors": []
}

{
  "valid": false,
  "errors": [
    "SESSION_STATE: missing required key: state_seq",
    "CANON_STATE_DELTA: current_state.state_seq should equal delta.seq (4 != 5)"
  ]
}

​
Validation logic

​
Schema resolver

validate_state.py resolves schemas automatically relative to its own file location. It looks for:
  • ../schemas/SESSION_STATE.schema.json — used when --state is provided
  • ../schemas/CANON_STATE_DELTA.schema.json — used when --delta is provided
No environment variables or configuration files are required.

​
jsonschema (preferred)

When jsonschema is importable, the script constructs a Draft202012Validator and iterates all validation errors, reporting each with its dot-notation path and message.

​
Strict manual fallback

When jsonschema is not available, the script runs its own recursive validator. The full set of accepted schema keywords is $schema, title, description, type, required, properties, additionalProperties, const, enum, minimum, and items. Keywords not in this set cause the validator to fail closed immediately. Of the accepted keywords, the following are actively enforced:
KeywordWhat is checked
typePython-level type check; boolean is kept separate from integer
constExact value equality
enumValue membership in the allowed list
minimumNumeric lower bound
requiredAll listed keys are present in the object
additionalProperties: falseNo keys outside properties are allowed
propertiesRecursively validates each present property
itemsRecursively validates each element in an array
The keywords $schema, title, and description are accepted (not treated as unsupported) but no validation logic is applied to them — they are structural annotations only. If the schema contains a keyword outside the accepted set, the validator returns an unsupported schema keyword error and fails closed — it does not silently skip unknown constraints.

​
Delta cross-file check

When --delta is provided, the script applies one additional constraint beyond the schema: it checks that current_state.state_seq equals delta.seq. A mismatch indicates the embedded snapshot does not match the delta’s own sequence number, which would be an inconsistent delta file.

​
Encoding

All JSON files are read with utf-8-sig encoding, which transparently strips a UTF-8 BOM if present.
These scripts are optional mechanical helpers. They do not make provenance decisions — that remains the operator’s responsibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us