Preserve typed dispatch preconditions through package and loader contracts

Start by reading docs/REFLECTION_JSON_SCHEMA.md and runtime/README.md at the cited compiler revision to understand the current reflection and metadata-only loader contracts. Then trace package verify/inspect and source-free loader plan entry points for the Metal, DirectX, OpenGL, and Vulkan metadata paths. Done means a versioned contract, round-trip coverage, boundary and compatibility tests, and a source-free consumer fixture demonstrate outstanding runtime obligations and rejected invalid payloads.

Problem

Repository ports need to carry typed host-metadata preconditions alongside generated kernels. A source-to-target conversion may be legal only when an immutable dispatch scalar, metadata element or record field lies in a checked range. Package admission alone cannot establish that a future caller will supply values in that range.

At compiler dev revision d43047c2a407a9bd1a90f21d1df0dd94507a698d, reflection retains source resource identities, target bindings and layouts, but its versioned schema has no dispatch-value-precondition record. The loader contract is explicitly metadata-only and does not consume actual dispatch values. That boundary is useful and should remain explicit.

Please add a versioned metadata contract that a compiler can emit or preserve and a downstream runtime can enforce. This is not a request to add device execution to the compiler package reader or to treat existing package loadable status as numerical/runtime validation.

Concrete Consumer

CrossGL/crosstl#2179 distinguishes caller-trusted index assertions from runtime-enforced metadata bounds. Its minimal case reads index = indices[0] from a uint64 resource and uses it to address a four-element uint32 resource. A declared [0, 3] assertion currently authorizes index conversion, but the application remains responsible for enforcing it. A runtime-owned dispatch contract needs to reject payloads 4 and 4294967296 before execution, without truncating or clamping them.

The same requirement appears in the MLX port at pin 9c3d35571ac450a8ecf5c17b4d0e3fac52c08bc8: reverse scans compose a row origin, axis size and block offset; GEMM forms batch-stride pointers from metadata. These are integration examples, not repository-specific schema requirements. The contract must work for arbitrary source repositories and target backends.

Requested Contract

• Identify the source entry, resource and optional immutable element/record-field path independently of generated helper names. Connect them to reflected target bindings and physical layout.
• Preserve integer width, signedness, byte offset, element stride and inclusive bounds. Define overflow and unit semantics for composed offset constraints rather than checking independent values whose sum may overflow.
• Distinguish statically proven facts, caller-trusted assertions and requirements that must be checked against actual dispatch values. Metadata presence or a package hash must never promote the latter to an already-enforced fact.
• Bind the contract to the appropriate artifact, entry and layout identities. Inspect/verify and loader plans must retain it and reject malformed, stale or unsupported mandatory contracts with structured diagnostics.
• Let metadata-only loader admission report outstanding runtime obligations without claiming to evaluate host payloads. A consuming runtime must explicitly support and enforce those obligations before dispatch. Unknown obligations must not be silently discarded.
• Mark the supported immutability boundary. A host snapshot must not authorize GPU-produced or subsequently mutated metadata; those require a separate validation strategy.
• Define backward compatibility for packages without the new optional contract and explicit version handling for packages that require it.

Acceptance

1. Document and schema-test source identity, scalar/field paths, type/layout information, bound semantics, trust classification and enforcement state.
2. Round-trip the contract through reflection or a declared sidecar, package verify/inspect and source-free loader plans on Metal, DirectX, OpenGL and Vulkan metadata paths.
3. Test renamed resources, duplicate/unknown identities, type and layout drift, unsupported versions, offset views, negative/oversized boundaries and integer-overflow constraints. Admission must not reinterpret trusted assertions as enforced preconditions.
4. Supply a small source-free consumer fixture demonstrating the separation between a valid package contract, a valid dispatch payload and a rejected payload. Device execution need not be implemented in this repository for this contract to be useful.

CrossTL can implement its runtime enforcement independently and align with this schema when available. No compiler release or stable published dependency is required to continue the translator work.