Repository navigation
Check every page the family edits against the schema of its type #192
Description
Story
As a family member who edits the family's pages by hand (Forgejo, Obsidian, stack memory write), I want every page checked against the schema of its type, so that a mistake is named with its path instead of silently read as an empty page.
Context
lib/stack/frontmatter.py holds the format's parser and a schema per type (SCHEMAS, and DECLARED_SCHEMAS for the person files from #191). Two gaps remain:
-
Types and fields without a schema.
todos(a state document,docs/design/brain/vault-format.md§7) has none, so it cannot be validated at all. The validator knows required, list and single-value fields, but not allowed values:relation_kindlists nine values in vault-format §5 and anything passes. -
Readers that bypass the validator. They parse frontmatter on their own and turn an error into an empty dict, so a broken page reads as a page without metadata:
stacklets/memory/lib.py_parse_frontmatterwraps the strict parser and returns{}on any exception (search).stacklets/memory/bot/cli/diary.py:388andstacklets/docs/bot/vault_entry.py:668parse with PyYAML and return{}on a YAML error.stacklets/memory/bot/cli/wiki.py:164uses PyYAML to decide whether a page's frontmatter is broken.
PyYAML accepts more than the format allows, so these readers and the validator can disagree about the same file.
The person files in #191 show the pattern: one reader, strict parse plus validate(), a broken file passed to a report callback with its path and left out, and nothing destructive done while one is broken.
Proposal
- Add a schema for
todos, and allowed values for enum fields (relation_kindfirst), inlib/stack/frontmatter.py, with vault-format.md updated in the same change. - Move the four readers above onto
stack.frontmatter.parseandvalidate(). A page that fails is reported by path where the reader's operator looks (curator log,stack memory prompt, archivist log) and left out, never read as empty. - Drop PyYAML from the frontmatter paths it then no longer serves.
Out of scope: new page types, the dream cycle, changing the format itself.
Definition of done
- A
todos.mdwith a field outside its schema is reported by path by the curator, and its todos are left untouched. - A person page with
relation_kind: cousinfailsvalidate()with a message naming the allowed values. - A vault entry with frontmatter outside the format is named by path in the archivist log, instead of surfacing in search without metadata.
- Caller-side tests pin each of the three, against the format in vault-format.md, not against the implementation.
- No frontmatter is parsed with PyYAML outside
lib/stack/frontmatter.py; the archivist's message catalogue (archivist.py:190) is not frontmatter and stays. -
docs/design/brain/vault-format.mdlists every schema the validator enforces.
Activity