Skip to content

TDL Implementation Plan v3.0

Schema 2.0 Source Toolchain and LoaderRefRep Fidelity

Purpose

This plan owns TDL as a source toolchain for Schema 2.0. It accepts TDL and MAP JSON, produces the common schema-backed LoaderRefRep graph, renders either syntax from that graph, and retains bounded source provenance for diagnostics.

The delivered proof that the Schema 2.0 TDL corpus can compile and load establishes the source toolchain's handoff boundary. After a graph crosses that boundary and becomes staged holons, descriptor runtime, default population, validation, and commit are not TDL work.

This plan therefore does not deliver descriptor-aware validation. It also does not own the Holon Loader lifecycle merely because TDL is one possible source of a loader graph.

Architecture Boundary

TDL source ------------------+
                             +--> LoaderRefRep --> canonical TDL or MAP JSON
MAP JSON source -------------+          |
                                        | source-toolchain boundary
                                        v
                              Holon Loading and staged holons
                                -> reference resolution
                                -> default population
                                -> Descriptor-Aware Holon Validation
                                -> commit or block

LoaderRefRep is the existing transient holon graph rooted at HolonLoadSet, including HolonLoaderBundle, LoaderHolon, LoaderRelationshipReference, and LoaderHolonReference. It is not a Rust DTO family, a semantic IR, or a second mutable model of MAP semantics.

TDL-to-JSON, JSON-to-TDL, and fidelity comparison operate entirely on LoaderRefRep. A load operation submits that graph to Holon Loading. The fact that the load eventually invokes a validator does not make validation part of parsing or lowering.

Ownership

Concern Owner TDL-track role
TDL grammar, parser, lowering, rendering, source spans, and source diagnostics TDL source toolchain Owns implementation and tests
LoaderRefRep source representation and JSON/TDL equivalence TDL source toolchain Owns implementation and tests
Holon staging, reference resolution, construction-scoped writes, default population, and commit wiring Holon Loading Consumer of LoaderRefRep
Effective specification, instance contract, conformance predicates, endpoint compatibility, and inheritance semantics Descriptor Runtime / HolonDescriptor Source toolchain preserves inputs; it does not compute them
Constraints / ValidationRule / ValidationBindings discovery, dispatch, results, and DS-* enforcement Validation track TDL lowers Core constraint and validation vocabulary as ordinary content; it does not execute it
Descriptor-independent integrity checks PVL No dependency on TDL descriptor semantics

The Commit Validation Implementation Plan owns all Descriptor-Aware Holon Validation capabilities. The Descriptor-Kernel Semantic Rules own the meaning of Schema 2.0 descriptor semantics. The runtime descriptor subsystem exposes those products through HolonDescriptor. This plan must neither duplicate nor become an alternative execution path for any of them.

Source-Toolchain Rules

  • Parse and lower authored syntax; do not execute descriptor semantics.
  • Preserve explicit type, extends, properties, relationships, named constraint instances and attachments, schema dependencies, keys, and literals as authored loader-graph content.
  • Do not infer type categories, effective members, enum membership, defaults, relationship endpoints, key values, or validation applicability from declaration spelling or local names.
  • Keep host-side diagnostics limited to syntax and source-to-LoaderRefRep lowering failures.
  • Preserve source spans in a bounded sidecar keyed to loader-graph identities. Source provenance is not semantic equality and does not require another mutable semantic representation.
  • Compile Core constraint and validation vocabulary exactly as ordinary TDL. Constraints, ValidationRule, and ValidationBindings receive no compiler-specific execution behavior. A cardinality clause lowers only bound properties of an explicitly authored compatible CardinalityConstraint instance; it never synthesizes a constraint identity, ownership fact, or Constraints occurrence. Active binding occurrences are ordinary type-definition relationships and are introduced only with their compatible rule implementations.
  • Loader, materialization, or validation failures may be presented with source provenance when it is available, but remain lifecycle diagnostics rather than TDL compiler errors.

Baseline

Schema 2.0 TDL-driven holon loading is already proven. The source toolchain has demonstrated that the Schema 2.0 corpus can become LoaderRefRep, traverse the ordinary loading path, and produce a holonic graph suitable for runtime processing.

That proof is intentionally narrower than descriptor-aware validation. It proves source conversion and loadability; it does not claim that DS-* rules execute while parsing or that all post-resolution validation has been delivered.

Delivery Sequence

T1 — Preserve Schema 2.0 Source Fidelity

Maintain and complete parsing/lowering support for every Schema 2.0 construct used by the active corpus.

Work:

  • Parse declaration and clause forms used by the Schema 2.0 corpus.
  • Lower directly into schema-backed LoaderRefRep holons and relationships.
  • Preserve authored reference keys without host-side ID or symbol resolution.
  • Preserve separate property and relationship namespaces, ordering, literal values, quoted keys, explicit cardinality-constraint bounds, and explicit versus omitted values.
  • Render MAP JSON directly from LoaderRefRep.
  • Retain syntax and lowering diagnostics with actionable spans.

Exit condition:

  • The active Schema 2.0 corpus parses into LoaderRefRep, and its emitted MAP JSON represents an equivalent graph accepted by the ordinary loader client.

T2 — Canonical Rendering and Round-Trip Fidelity

Make TDL and MAP JSON alternate renderings of the same LoaderRefRep content.

Work:

  • Parse MAP JSON into the same LoaderRefRep used by TDL.
  • Render canonical TDL from loader holons, explicit properties, and keyed relationships.
  • Collapse TDL shorthand only when recompilation preserves loader-graph content.
  • Derive immutable comparison signatures from LoaderRefRep.
  • Keep source-only residue local to fidelity reporting where TDL cannot represent it losslessly.

Exit condition:

  • JSON → TDL → JSON and TDL → JSON → TDL preserve equivalent LoaderRefRep graphs across the Core corpus, including its Commit-validation vocabulary, and the Validation Schema extension corpus, plus focused fixtures.

T3 — Retire Transitional Source Representations

Remove source-tooling representations that duplicate the loader graph after all source-tooling consumers use LoaderRefRep.

Work:

  • Remove SemanticModel, tool-local loader_ir, their compatibility adapters, and duplicate conformance paths.
  • Replace their indexes with immutable LoaderRefRep-derived tooling indexes or move bounded source utilities into an appropriately named tooling crate.
  • Remove stale comments and vocabulary that imply a TDL-owned semantic runtime.
  • Do not replace a retired IR check with TDL-owned descriptor validation.

Exit condition:

  • No production source-tooling path maintains a mutable copy of holonic semantic state outside LoaderRefRep and Holons Core.

T4 — Derived Source Tooling

Code generation, diffing, CI support, editor services, and contributor workflow tooling may consume LoaderRefRep and immutable derived indexes after T1–T3 provide stable boundaries.

Exit condition:

  • Derived tooling does not introduce a third semantic authority or take ownership of runtime descriptor validation.

Loader and Validation Integration Contract

The TDL toolchain has one integration contract with Holon Loading:

An equivalent TDL and MAP JSON input must produce equivalent LoaderRefRep graphs. When each graph is submitted to the same loader lifecycle, it must receive the same lifecycle outcome.

This contract permits an end-to-end smoke test, but assigns the work correctly:

Step after LoaderRefRep submission Responsible track
Stage holons and resolve references Holon Loading
Compute descriptor products Descriptor Runtime
Populate applicable defaults Holon Loading
Select and execute descriptor-aware rules Validation
Convert blocking results into loader failure and prevent persistence Holon Loading, consuming Validation

The TDL test proves equivalence of source paths. It must not assert a separate TDL-specific rule, produce a separate validation outcome, or make source compilation depend on a descriptor-aware validator.

Commit-Validation Vocabulary and Extension Corpus

Core owns the Commit-validation vocabulary, including ValidationRule, the Commit rule families, the four metadata enums and six rule properties, and the ValidationBindings / ValidationBindingFor pair. The type-system Core vocabulary separately owns Constraint, ConstraintType, Constraints, constraint applicability, and Core constraint types. Both relationships are licensed through MetaTypeDescriptor's inherited InstanceRelationships; VAL0b does not repeat local ComponentOf declarations to license them.

The Core TDL migration must declare the constraint meta-model as actual Core content, not merely add the generic relationship name. It includes abstract Rule, the Constraint instance family, ConstraintType / MetaConstraintType descriptor families, the authored RuleOf / materialized Rules pair, the Constraints / Constrains pair, and the authored ApplicableToDescriptorTypes / materialized HasApplicableConstraintTypes pair. Each concrete constraint type declares its configuration members through InstanceProperties, its applicability, and its ordinary family extends lineage.

The initial Core declarations are:

Concrete type declaration Required Core configuration contract
StringLengthConstraint.ConstraintType independently optional Minimum and Maximum, plus MinimumIsInclusive / MaximumIsInclusive exactly when the corresponding bound is present; measures Unicode grapheme clusters
BytesLengthConstraint.ConstraintType the same normalized bound contract; measures bytes
NumericRangeConstraint.ConstraintType the same normalized bound contract
ItemCountConstraint.ConstraintType the same normalized bound contract
UniqueItemsConstraint.ConstraintType no enable flag; the attached constraint instance itself requires uniqueness
CardinalityConstraint.ConstraintType required inclusive Minimum, optional inclusive Maximum, and no inclusivity flags; applies to RelationshipType.TypeDescriptor

MinimumLength, MaximumLength, MinimumValue, MaximumValue, MinimumItems, and MaximumItems are removed from the active Core constraint-type inventory. The old one-bound configuration properties (ConstraintLength, ConstraintIntegerValue, ConstraintItemCount, ConstraintIsInclusive, and ConstraintEnabled) are removed with them. They must not survive as aliases, descriptor properties, or alternative TDL lowering paths.

For every configured use, the source corpus authors a named instance, explicit rule_of origin, and an explicit attachment; for example, DisplayName.StringLengthConstraint has type StringLengthConstraint.ConstraintType, ConstraintName "DisplayName", rule_of "MAP Core Schema-v0.0.7", its four bound properties, and one DisplayName.StringValueType -[Constraints]-> DisplayName.StringLengthConstraint occurrence. TDL may provide compact source syntax only where the specification defines it. No lowering path creates a constraint identity, its DescribedBy fact, ownership, or attachment implicitly. The Validation Schema extension source corpus is map-holons/schema-src/validation/schema.tdl; its generated loader artifact is map-holons/generated/json-imports/validation/schema.json. The extension depends on Core; Core must source-load without loading it. Strict Core bootstrap is a Commit-validation milestone, not a TDL source-toolchain acceptance criterion.

The TDL toolchain parses and lowers this corpus using ordinary Schema 2.0 facilities. Its package load acceptance is a source and loader compatibility test. Stable constraint and rule identities, effective constraint/binding collection, wrapper dispatch, and DS-* execution are owned by commit-validation-impl-plan.md, not by this plan.

Test Strategy

Source-toolchain tests

  • Grammar and lowering fixtures for every active Schema 2.0 construct, including named StringLengthConstraint, BytesLengthConstraint, NumericRangeConstraint, ItemCountConstraint, and CardinalityConstraint instances with explicit ConstraintName, rule_of, and Constraints attachments.
  • Fixtures proving that rule_of is required for constraint, validation-rule, and configured key-rule instances; that it lowers to RuleOf; and that it is never inferred from the containing file or a consuming type. Concrete KeyRuleType descriptors remain implicit Components rather than RuleOf instances.
  • Applicability fixtures proving forward-authored ApplicableToDescriptorTypes, materialized HasApplicableConstraintTypes, incompatible attachment rejection, reusable dependency-owned constraint adoption, and extension-owned constraint attachment.
  • Cardinality fixtures proving explicit root attachment, inherited effective cardinality, and rejection of relationship-level cardinality syntax or synthesized constraint identity, provenance, or attachment.
  • Key-rule fixtures proving that ConstraintInstanceRule accepts a matching <ConstraintName>.<direct constraint type TypeName> key and rejects missing input, incompatible DescribedBy, and mismatched keys; run those fixtures through TDL/JSON source fidelity and non-strict source-loading paths. Strict Core bootstrap belongs to the Commit-validation plan.
  • Complete Core corpus compilation, including its Commit-validation vocabulary, and Validation Schema extension corpus compilation.
  • TDL-to-JSON emission from LoaderRefRep.
  • JSON-to-TDL rendering and bidirectional fidelity comparison.
  • Focused diagnostic fixtures for syntax and lowering failures.

Boundary smoke tests

  • Submit equivalent TDL- and JSON-originated LoaderRefRep graphs to the same loader ingress.
  • Verify their source-independent lifecycle result is equivalent.
  • Verify loader failures can cite available source provenance without changing their classification into compiler errors.

Descriptor-runtime product tests, default-population tests, validation-rule fixtures, blocked commit tests, and transaction-aware relationship/cardinality tests belong to their owning tracks.

Non-goals

This plan does not include:

  • descriptor-aware validation implementation, rule coverage, or result aggregation;
  • ValidationRule wrapper dispatch, ValidationBindings discovery, or validation profiles;
  • descriptor-kernel algorithms or HolonDescriptor runtime integration;
  • default materialization or validated-commit wiring;
  • descriptor-independent PVL behavior or Integrity callback changes;
  • full incremental semantic validation of syntactically invalid editor documents;
  • migration of persisted Schema 1.2 data; or
  • a new loader JSON format.

Completion Criteria

The TDL source-toolchain migration is complete when:

  1. The active Schema 2.0 Core corpus, including Commit-validation vocabulary, and the Validation Schema extension corpus parse into LoaderRefRep.
  2. TDL and MAP JSON produce equivalent LoaderRefRep graphs.
  3. TDL and MAP JSON round trips preserve that graph content.
  4. Core validation vocabulary and the Validation Schema extension compile as ordinary source content with no TDL-specific semantic behavior.
  5. No retired semantic or loader IR remains a production source-tooling semantic authority.
  6. Equivalent TDL and JSON input can be handed to the ordinary loader path without a TDL-specific lifecycle or validation branch.