Categories
Five canonical categories ship in the substrate. Each maps to a stable slug used by the runtime API.
A sixth category,
outcomes, exists for closing the loop on past decisions and is created automatically when a decision is marked resolved.
File shape
Every entry is a markdown file with a frontmatter block:valid_from and valid_to are the bi-temporal anchors used by the resolver to answer “what was the rule on this date?”.
Validation
Each category has a JSON Schema in the substrate atschemas/<category>.schema.json. The schema declares required frontmatter fields and the body’s section structure. Writes through the runtime API validate against the schema and reject anything malformed with a 422.
Schema evolution rules:
- Add fields freely (default to null or empty).
- Removing a field requires a migration script that runs against existing entries.
- Changing a field’s type is a breaking change and requires a new schema version.
Storage
Entries live on disk undervaults/<tenant_id>/<Category>/<YYYY>/<YYYY-MM-DD>-<slug>.md. A SHA-8 of the file path becomes the entry’s stable id for API operations. The disk format is plain markdown so vaults remain readable, greppable, and git-versionable without the runtime running.