Adds ADR-0002, the document's JSON Schema

[johnnyt]

Summary

Proposes ADR-0002: the datamodel document ships a JSON Schema - draft-07, hand-written, advisory, never the admission rule. The record merges at proposed; its acceptance is the operator's.

• docs/adr/0002-datamodel-document-json-schema.md (new): Context, Decision, the typespecs section, a worked example and Consequences. The Decision names the file (priv/schemas/datamodel-document.schema.json, added to the Hex files: list), the reader (StatifierDatamodel.Schema.path/0 and json/0, embedded at compile time), draft-07 with ex_json_schema ~> 0.11 test-only, hand-written with a drift test on the nine closed type spellings, advisory not admission (index/1 stays the total normalizer and nothing in the package calls the schema), open objects, the $id keyed on the document version, and the versioning rule (a version bump ships a second file).
• docs/adr/0001-datamodel-document.md: a dated Note appended at the foot pointing at ADR-0002. It changes no decision; the Status line and every existing line are unchanged.
• docs/adr/README.md: one index row for ADR-0002 at proposed.

Documentation only: no code, no changelog fragment (changelog.d/README.md excludes ADRs).

Direction check

Checked in turn, against origin/main at 7ede3a2: every code claim in the record by anchor. StatifierDatamodel.Index.index/1 admits any map with a list under "scopes" and returns nil otherwise (lib/statifier_datamodel/index.ex, index/1); an unknown scope name indexes with scope: nil (scope_name/1); sensitive? reads true only for the boolean (normalize/5); a declaration whose kind is neither record nor shape declares nothing (lib/statifier_datamodel/declarations.ex, declared_name/1); an entry type resolves against the private @types map first and then the document's declarations, and a spelling naming neither is nil (index.ex, entry_type/2); Index.type/2 takes an index and a path; a non-integer version indexes as 1 and an integer one is kept (index.ex, version/1); the Hex files: list lacks priv today (mix.exs, package/0); the comment above deps/0 makes a runtime dependency a decision to record; changelog.d/README.md names a change to what the document admits as breaking. Each row of the worked-example table was checked against those functions over ADR-0001's worked shape (nine declared paths; eight without the event scope). ADR-0001 decisions 3-6, 12, 13, its flip Note (the declaration label reading) and its inline-shape amendment arm (c) (no document spelling for an inline shape) were read whole for the schema's requirements. git diff origin/main -- docs/adr/ shows zero removed lines; git diff origin/main --stat -- lib test is empty.

Gate

Full mix quality, quoted whole:

✓ Format: No changes needed (229ms)
✓ Compile: dev + test compiled (warnings as errors) (3.9s)

Running analysis stages in parallel...

○ Doctor: skipped (:doctor not installed)
○ Gettext: skipped (:gettext not installed)
○ Sobelow: skipped (:sobelow not installed)
✓ Doc links: 1 link checked (11ms)
✓ Dependencies: No unused dependencies (391ms)
✓ Credo: No issues (787ms)
✓ Tests: 127 of 127 passed, 99.1% coverage (826ms)
✓ Docs: No warnings (856ms)
⋯ Dialyzer: building PLT (this is a one-time cost)
✓ Dialyzer: No warnings (PLT built this run) (33.7s)

✓ All quality checks passed!

The commit's tree is byte-identical to the tree this run was green on.

Provenance

Ruled by the operator, 2026-09-26: draft-07 with ex_json_schema, hand-written with a drift test, and a record at proposed with the schema code built under it. Engineering choices this record makes where the ruling was silent: json/0 returns the JSON text rather than a decoded map (the package decodes no JSON); the $id spelling; the version-2 file's name and reader are left to the bump that needs them.