Let a manifest declare the schema it was written against

[timlichtenberg]

Closes #6 is not intended here; this addresses the manifest-schema marker discussed alongside #32.

What this does

A manifest that fails to load is currently diagnosed by guesswork. An unknown field has two readings, a misspelling and a field belonging to a schema this fwl-io does not implement, and the error has to offer both because nothing in the file says which applies. Since a model ships its manifest with its own code, the newer-manifest case is real rather than hypothetical.

An optional root manifest_schema = <n> settles it.

Why

The two-reading message was the loose end left by #32. That change made a manifest disagreeing with the installed fwl-io say so, but it could only describe the disagreement, not resolve it: without a declaration there is no way to tell a typo from a file written against a schema this code has never seen.

Changes

• manifest.py: read an optional root manifest_schema, and thread the result through the table walk so every unknown-field message can use it.
  • Above the implemented schema: refused, saying to upgrade fwl-io, with the spelling reading dropped.
  • Equal to it: an unknown field is reported as a misspelling, with the upgrade advice dropped.
  • Below it: refused, with a message naming the schema the manifest declares, the schema this code implements, and the schema versions table. The number rises when a manifest written for the previous one stops loading, so a manifest declaring an older schema is one that has already stopped loading; reading it best-effort only defers the failure to some individual field further in. Incrementing the schema is therefore a breaking change for every manifest that declares the old number, which is the intent.
  • Read before any of this code's own rules are applied, since a manifest above this schema cannot be judged by them.
  • A table named manifest_schema stays an ordinary directory level, the rule subdir already follows.
  • The key written inside a dataset or grouping table is reported as misplaced, not misspelt: the name is right and the level is wrong.
• Docs: the field list and schema-versions table in Explanations/manifests.md, the module docstring example, and the How-to/add_dataset.md template.
• data/shared_manifest.toml declares it, so the shipped reference example shows the intended shape.

Manifests that declare nothing behave exactly as before.

Testing

macOS 15, Python 3.12. Full suite: 264 passed, 1 skipped. Ruff clean.

• Back-compatibility checked against real manifests rather than fixtures only: the shipped proteus_manifest.toml loads unchanged (2 datasets), the shared manifest loads with its own new declaration, and entry-point discovery still returns all 3 datasets.
• New tests cover the future-schema refusal, the sharpened message at root, nested and grouping levels, the value validation including true (rejected rather than read as 1, since Python treats bool as an int), a table named for the key, the key written below the root, and the ordering against the subdir rule.
• Both threading call sites are mutation-verified: removing declared_schema from the grouping-level call, and from the recursion, each fails a test. Without those cases both mutations survived the whole suite.