docs(validation): document the NodeValidator hook as an intentional extension point (not dead code)

Closes the last #52-review loose end. The per-type imperative `NodeValidator` hook on the
TypeDefinition is set by no core type, which reads as dead code — but it is deliberate:

- It is an EXTENSION POINT: a downstream provider registers a new type WITH its own
  validator + error codes and it runs via the registry with zero core changes (the ADR-0023
  thesis), proven by the widget.gauge test in validation-registry.test.ts.
- It is the documented escape hatch in the config-driven-validation design (#51) for novel
  cross-field rules that fit no declarative shape.
- Core's per-type validation lives in reference descriptors (live) + declarative rule-shapes
  (#51, planned); a core rule on this imperative hook would contradict that direction — so
  core intentionally does not use it, and dogfooding a rule onto it would be make-work.

Decision: keep the hook, document the intent. Clarifying comments added to the hook
declaration in all four ports (TS/Java/C#/Python; Kotlin shares the JVM type) + a status
note in the validation-architecture design doc. No behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/superpowers/specs/2026-06-19-metadata-validation-architecture-design.md

@@ -90,6 +90,17 @@ carries the type's attrs/constraints/`maxOccurs`. Two tiers:
 2. **Imperative validators** (code) for logic config can't express — a function registered
    per `(type, subType)`, invoked by the recursive walk.
 
+   > **Status note (the `NodeValidator` hook is intentionally unused by core).** The
+   > reference-descriptor half (1) is live in core (relationship `@objectRef`,
+   > identity.reference `@references`). The imperative-validator half (2) is an **extension
+   > point**, not dead code: a downstream provider registers a new type *with* its own
+   > validator and error codes, validating itself with zero core changes (proven by the
+   > `widget.gauge` test). It is also the **escape hatch** in the config-driven-validation
+   > design (issue #51) for novel cross-field rules that fit no declarative shape. Core does
+   > not (and should not) put its own per-type rules here — they belong in reference
+   > descriptors today and declarative rule-shapes under #51; a core rule on the imperative
+   > hook would contradict that direction.
+
 **Dispatch is uniform; the validator *body* is idiomatic per port.** Core's
 `root.validate(ctx)` walks the tree and, per node: *apply declared rules (incl. reference
 descriptors) → invoke `registry.validatorFor(type, subType)` → recurse.*

server/csharp/MetaObjects/Validation/ValidationTypes.cs

@@ -27,5 +27,12 @@ public interface IValidationContext
     void Error(string code, MetaData node, string message);
 }
 
-/// <summary>An imperative validator for a node, carried by its TypeDefinition.</summary>
+/// <summary>
+/// An imperative validator for a node, carried by its TypeDefinition.
+/// INTENTIONALLY UNUSED BY CORE — do not remove as "dead code": it is an extension point
+/// (a downstream provider registers a new type with its own validator + error codes — the
+/// ADR-0023 thesis) and the escape hatch in the config-driven-validation design (#51) for
+/// novel cross-field rules that fit no declarative shape. Core's per-type validation lives
+/// in reference descriptors (live) + declarative rule-shapes (#51), not this hook.
+/// </summary>
 public delegate void NodeValidator(MetaData node, IValidationContext ctx);

server/java/metadata/src/main/java/com/metaobjects/validation/NodeValidator.java

@@ -7,6 +7,13 @@
  * by its provider. In Java/C# this is typically a METHOD REFERENCE (the logic lives on/by
  * the typed node class and uses its typed accessors); dispatch is via the registry, so a
  * downstream provider's validator runs without core changes.
+ *
+ * <p>INTENTIONALLY UNUSED BY CORE — do not remove as "dead code". This is an EXTENSION
+ * POINT (a downstream provider registers a new type WITH its own validator + error codes —
+ * the ADR-0023 thesis) and the documented escape hatch in the config-driven-validation
+ * design (issue #51) for novel cross-field rules that fit no declarative shape. Core's own
+ * per-type validation lives in reference descriptors (live) + declarative rule-shapes
+ * (#51, planned), NOT in this imperative per-node hook.</p>
  */
 @FunctionalInterface
 public interface NodeValidator {

server/python/src/metaobjects/validation_types.py

@@ -30,4 +30,10 @@ class ReferenceDescriptor:
 
 
 # An imperative validator for a node, carried by its TypeDefinition.
+#
+# INTENTIONALLY UNUSED BY CORE — do not remove as "dead code": it is an extension point
+# (a downstream provider registers a new type with its own validator + error codes — the
+# ADR-0023 thesis) and the escape hatch in the config-driven-validation design (#51) for
+# novel cross-field rules that fit no declarative shape. Core's per-type validation lives
+# in reference descriptors (live) + declarative rule-shapes (#51), not this hook.
 NodeValidator = Callable[["MetaData", "ValidationContext"], None]

server/typescript/packages/metadata/src/validation-types.ts

@@ -41,6 +41,17 @@ export interface ValidationContext {
   error(code: LoaderCode, node: MetaData, message: string): void;
 }
 
-/** An imperative validator for a node of a given (type, subType), carried by its
- *  TypeDefinition — the provider that owns the type owns its validation. */
+/**
+ * An imperative validator for a node of a given (type, subType), carried by its
+ * TypeDefinition — the provider that owns the type owns its validation.
+ *
+ * INTENTIONALLY UNUSED BY CORE — do not remove as "dead code". This is an EXTENSION
+ * POINT: a downstream provider registers a new type WITH its own validator (+ its own
+ * error codes) and it runs via the registry with zero core changes — see the
+ * `widget.gauge` proof in test/validation-registry.test.ts (the ADR-0023 thesis). It is
+ * also the documented escape hatch in the config-driven-validation design (issue #51) for
+ * novel cross-field rules that fit no declarative shape. Core's own per-type validation
+ * lives in reference descriptors (live) + declarative rule-shapes (#51, planned), NOT in
+ * this imperative per-node hook — putting a core rule here would contradict #51.
+ */
 export type NodeValidator = (node: MetaData, ctx: ValidationContext) => void;