ADR-0028: Schema construction enforces its grammar at the Add site

[pavlovtech]

ADR-0028 — Schema invariants move from the fold to the construction site

The Schema is the user-facing DSL — the very first thing every consumer constructs. Its grammar rules (Field non-empty, leaf Selector non-empty, list-container Selector non-empty) lived in the fold (SchemaContentParser), so an invalid Schema constructed cleanly and failed only at parse time, asymmetrically: a leaf-list with no Selector got swallowed by the per-leaf catch (Exception) and silently dropped the field; an object-list with no Selector aborted the whole parse. The pre-0028 test ListSchemaWithoutSelectorThrows documented the symptom — its name said Throws and its body asserted silent unset.

Moved enforcement to Schema.Add(SchemaElement) — validates Field non-empty, leaf Selector non-empty, list-container Selector non-empty (a non-list nested Schema is exempt; the fold never reads its own Selector by design). The throw site is the exact line the user wrote the bad element — best possible error location.

Added Schema.ListOf(string field, string selector, params SchemaElement[] children) static factory that bundles the IsList + Selector + Children triple in one call, with construction-time validation of field+selector. The old shape (new Schema(field) { Selector = ..., IsList = true, Children = { ... } }) keeps working; the factory is the recommended path going forward.

The fold's existing Field is null guard and three RequireSelector calls stay in place, annotated as belt-and-suspenders for the one remaining path (mutation of a SchemaElement after Add — records here use { get; set; }, not init-only). They are no longer the primary line of defence.

Design, the five rejected alternatives (fluent-builder DSL replacement / init-only properties / sibling-type model split / parameterless-ctor internalisation / documentation-not-enforcement) with load-bearing reasons, and the implementation status: docs/adr/0028-schema-construction-guards.md.

Narrowly breaking

• Constructing a pathological Schema (leaf or list container with empty Selector, child with empty Field) now throws ArgumentException at the Add call instead of failing at parse time (or silently). The ListSchemaWithoutSelectorThrows test was changed to assert the construction-time throw (ConstructingALeafListWithoutASelectorThrowsAtTheAddSite); a sibling pins the same for the object-list arm.
• Surface-additive: Schema.ListOf is purely new; no public method removed.
• The non-list nested Schema (an object container that uses the parent scope) is exempt from the Selector rule — by design. ADR-0002's missing-selector unified across single-value vs list paths update becomes structural at construction, not just at the fold.

Guardrail

Whole-solution build 0 errors · 107 unit tests (94 pre-0028 + 1 replaced + 1 new sibling + 12 new SchemaConstructionTests) · 19 satellite tests (Sqlite/Puppeteer/Mongo/Cosmos/AzureServiceBus) · Native-AOT smoke ALL PASS. Integration tests deferred to CI (live alexpavlov.dev + real Puppeteer, slow by design).

🤖 Generated with Claude Code