Config-driven metadata validation — checks as data, one engine per port (write-once across 5 languages)

[dmealing]

Summary

Make metadata validation data, not per-port code: declare each check as data on the type's registration, and give each port one generic interpreter per rule-shape. A rule is then authored once (not re-coded in TS/Java/C#/Python/Kotlin), and a downstream provider's new type validates itself with zero new validation code in any port.

Design doc: docs/superpowers/specs/2026-06-21-config-driven-validation-design.md.

Sibling to #23 (FR-033, "Provider definitions as declarative data") — same philosophy; if provider definitions become declarative data, validation rules are just more fields in that data.

Why

Validation today is split across three mechanisms, inconsistently:

1. Reference descriptors (objectRef/references) — declarative data, but constructed in code per port (same rule written 5×).
2. ~20 free-floating imperative passes — hand-coded per port.
3. A validate hook on the TypeDefinition — invoked in all ports but registered by no core type (an extension point core doesn't use itself).

Net: every rule is implemented N=5 times, and a downstream provider must write validators in every language it targets — contrary to the metadata-is-the-spine thesis and ADR-0023 (providers add types via registered data).

The four closed rule-shapes

Shape	Covers today
reference	objectRef, references, payloadRef/responseRef existence
allowedValues	@format, @kind, @promptStyle (closed sets)
requires	email needs subjectRef+htmlBodyRef; document needs textRef
fieldPathRef	requiredSlots are fields on the payloadRef target

These cover the entire current reference + template corpus. Anything that fits no shape falls back to the validate hook (rare escape hatch). No speculative shapes — a fifth requires a real rule + the ADR-0023 can't-be-computed justification.

Phasing (earn it; conformance-gated; behavior-neutral)

• Phase 0 — cleanup (done, 599a4aed): align all ports' reference validation (revert the TS payloadRef descriptor split).
• Phase 1 — proof slice: move the reference shape from per-port code into shared JSON; one generic interpreter per port; conformance unchanged. De-risks "is config-driven byte-identical across 5 ports" before extending.
• Phase 2 — allowedValues (format/kind/promptStyle).
• Phase 3 — requires + fieldPathRef; delete the bespoke template pass in all ports.
• Phase 4 — opportunistically migrate remaining datafiable passes; keep the validate hook for the rest.

Risks

• 4 interpreters × 5 ports (bounded, fixed-size — not proportional to type count).
• FR5d resolved-source envelope fidelity (template fixtures gate it).
• ADR-0023 strict provenance: rule data is provider data; spec readers must tolerate the new reference/rules fields (guard first).

Open questions

• rules inline-on-type vs a sibling validation block (lean inline for locality).
• Does FR-033 — Provider definitions as declarative data + metamodel docs for LLMs #23 subsume the "data in JSON, reader lowers it" mechanism? Coordinate.
• Kotlin (shared JVM metadata) likely gets the interpreters for free — confirm in Phase 1.

[dmealing]

Phase 1 implementation map (parked — for whenever this is picked up)

Survey of the FR-033 spec-reader pipeline + current reference-validation sites, so Phase 1 (move the reference shape into shared JSON) can start without re-deriving.

Key architectural finding — two reader shapes: only TS lowers the full attr schema from spec/metamodel/*.json (provider-data.ts toAttrSchema). Java/C#/Python readers are doc/extends overlay only — they do NOT build the attr schema from JSON (it's hand-coded), so Phase 1 must add a new "apply reference rules from spec" path in those three, not just extend an existing lowering. Kotlin inherits the Java module for free (resolves the issue's open question). Also: there is no ReferenceDescriptor type yet — today the reference rule is hand-registered attrs + imperative passes; Phase 1 introduces the descriptor as JSON data + one generic interpreter per port.

No tolerance guard needed — every reader (.get()/TryGetProperty/Gson) already silently ignores unknown attr keys; allowedValues is the live optional-field precedent. The issue's "guard first" risk is satisfied structurally.

(a) Add the reference block as a sibling key on the attr object (like allowedValues):

• spec/metamodel/relationship.json — @objectRef repeated on base/association/aggregation/composition
• spec/metamodel/identity.json — subtype reference, @references (line ~28)
• spec/metamodel/field.json — field.object @objectRef (decide if in scope or stays a field-object pass)

(b) Reader hook points: TS provider-data.ts toAttrSchema (~410-432, after the allowedValues spread) + regen embedded via scripts/generate-embedded-metamodel.ts. Java SpecMetamodelReader.parseAttrChildren (~273-294) + new apply path by MetaDataRegistry.applySpecDescriptions (JSON auto-copied to classpath via maven-resources). C# SpecMetamodelReader.ParseAttrChildren (~322-368) + manual cp to server/csharp/MetaObjects/SpecMetamodel/. Python spec_metamodel/__init__.py._parse_attr_children (~228-253) + manual cp.

(c) Hand-construction to remove: Java MetaRelationship.registerTypes/ReferenceIdentity + concrete subtypes; C# RelationshipSchema/IdentitySchema (ReferenceIdentityAttrs); Python core_types.py _RELATIONSHIP_ATTRS/identity.reference; TS imperative passes in validation-passes.ts (objectRef ~494-507, M:N ~1169-1250).

(d) Gates:

• registry-conformance (fixtures/registry-conformance/expected-registry.json, byte-identical 5 ports) — DECISION POINT: the manifest emitter projects only name/valueType/isArray/required/description/rules?/...; it'll drop a new reference block unless extended. Either don't surface reference in the manifest (truly behavior-neutral) OR surface + regenerate the canonical in lockstep (TS-advances-first per the README).
• Spec byte-identity/embed gates (TS regen script; Java auto; C#/Python manual cp).
• Reference-behavior gates: C# IdentityReferenceTests, Java MetaRelationshipTest/Fr5dReferenceResolutionTest, Python test_fr5d_reference_resolution, + FR5d resolved-envelope shape, + M:N + persistence/api-contract corpora.

Recommendation when resumed: keep reference OUT of the registry manifest for Phase 1 (so it stays byte-neutral), prove the JSON-driven interpreter cross-port, then decide on manifest surfacing in a later phase.