@geastack/compiler 1.0.15

package/dist/conversion/derive.d.ts

@@ -0,0 +1,37 @@
+import type { Representation } from '../representation/model.js';
+import type { ConversionCapability, ConversionNodeId } from './algebra.js';
+import type { ConversionRuntimeRegistry } from './registry.js';
+export type { ClassifierMaterializerPair, ConversionRuntimeRegistry } from './registry.js';
+export { validateConversionGraph } from './graph-validation.js';
+/**
+ * Derivation of the dynamic-conversion capability algebra.
+ *
+ * This module answers one question: given a target `Representation`, what is
+ * the capability for converting an already-boxed dynamic value into it? The
+ * answer is read off the normative table in the architecture doc's "Exhaustive
+ * dynamic-conversion capability algebra" section, not re-derived from source
+ * shape or invented per call site. A kind the table marks `Never` returns
+ * `never` unconditionally; a kind the table gates on installed runtime support
+ * consults the registry and returns `never` when nothing is installed, rather
+ * than fabricating a materializer that would turn a missing capability into a
+ * silent miscompile.
+ */
+/**
+ * Recursion state for one derivation.
+ *
+ * `inProgress` maps a `Representation` object -- by reference, not by a
+ * structural key -- to the node id it was assigned when first entered. A
+ * structural key would have to walk the whole shape to compute, which loops
+ * forever on a genuinely cyclic `Representation` graph (the standard way to
+ * express a recursive type without an explicit indirection layer); checking
+ * the exact object reference already on the current path costs nothing and
+ * terminates immediately. A shared, non-cyclic leaf reused at two unrelated
+ * positions is never mistaken for a cycle, because each recursive call only
+ * ever sees the map built along its own ancestor chain, not its siblings'.
+ */
+export interface ConversionDerivationContext {
+    readonly registry: ConversionRuntimeRegistry;
+    readonly inProgress: ReadonlyMap<Representation, ConversionNodeId>;
+}
+export declare const createConversionDerivationContext: (registry: ConversionRuntimeRegistry) => ConversionDerivationContext;
+export declare const deriveConversionCapability: (target: Representation, context: ConversionDerivationContext) => ConversionCapability;

package/dist/conversion/derive.js

@@ -0,0 +1,260 @@
+import { representationKey } from '../representation/model.js';
+import { classRefDomainsOverlap, classifierDomainsOverlap, never } from './algebra.js';
+export { validateConversionGraph } from './graph-validation.js';
+export const createConversionDerivationContext = (registry) => ({
+    registry,
+    inProgress: new Map()
+});
+/** Wraps an installed pair as `Atom`, or `never` when nothing is installed or the pair disagrees on domain. */
+const atomFrom = (pair, missingReason) => {
+    if (!pair)
+        return never(missingReason);
+    if (pair.classifier.domain !== pair.materializer.domain) {
+        return never(`installed classifier domain "${pair.classifier.domain}" does not equal installed materializer domain "${pair.materializer.domain}"`);
+    }
+    return { kind: 'atom', classifier: pair.classifier, materializer: pair.materializer };
+};
+/** An installed pair as `Atom`, or `null` so the caller can state its own refusal. */
+const maybeAtom = (pair) => pair === null ? null : { kind: 'atom', classifier: pair.classifier, materializer: pair.materializer };
+export const deriveConversionCapability = (target, context) => 
+// A recursive reference must name the graph node that actually owns this
+// carrier. `buildConversionGraph` keys nodes by `representationKey`, not by
+// a derivation-local path such as "root".
+deriveAt(target, context, representationKey(target));
+const deriveAt = (target, context, path) => {
+    const enclosing = context.inProgress.get(target);
+    if (enclosing !== undefined)
+        return { kind: 'recursive-ref', node: enclosing };
+    // `path` describes a capability location for diagnostics; recursive refs
+    // name graph nodes. Keep those namespaces separate so a nested recurrence
+    // points to `representationKey(target)`, the id buildConversionGraph emits.
+    const nested = {
+        registry: context.registry,
+        inProgress: new Map(context.inProgress).set(target, representationKey(target))
+    };
+    switch (target.kind) {
+        case 'unresolved':
+            // Lattice bottom: selection never happened, so there is no physical target to convert into.
+            return never(`no physical target exists (unresolved: ${target.reason})`);
+        case 'void':
+            return never('void is not a runtime value carrier');
+        case 'scalar':
+            // A TypeScript annotation does not perform ToNumber. Dynamic values
+            // reaching a scalar slot are assertions and require the slot's exact
+            // runtime tag/range materializer. Explicit ToNumber lives at its own
+            // semantic operation.
+            return atomFrom(context.registry.scalarMaterializer(target.domain), `no installed exact tag/range materializer for scalar domain "${target.domain}"`);
+        case 'string': {
+            // A `string` annotation is an exact String-tag assertion, not implicit
+            // ToString. String(value), templates, and property keys request that
+            // abstract operation at their own semantic sites.
+            return atomFrom(context.registry.stringMaterializer(), 'no installed exact string-tag materializer');
+        }
+        case 'symbol':
+            return atomFrom(context.registry.symbolMaterializer(), 'no installed exact symbol-tag materializer');
+        case 'null':
+            return atomFrom(context.registry.nullMaterializer(), 'the runtime does not distinguish null with an exact tag');
+        case 'undefined':
+            return atomFrom(context.registry.undefinedMaterializer(), 'the runtime does not distinguish undefined with an exact tag');
+        case 'class-ref':
+            return atomFrom(context.registry.classRefMaterializer(target.declaration, target.ownership), `no installed nominal-token materializer for class ${target.declaration} (${target.ownership}); structural object tests do not qualify`);
+        case 'native-handle':
+            return atomFrom(context.registry.nativeHandleMaterializer(target.protocol, target.version, target.native), `no versioned host-protocol materializer installed for ${target.protocol}@${target.version}`);
+        case 'record':
+            // A record assertion is an object product: every required key and every
+            // typed field must be checked from the dynamic object.  The emitter may
+            // keep an exact boxed payload as a fast path, but that optimization does
+            // not change the conversion capability into an identity-only claim -- an
+            // arbitrary dynamic object still has to materialize the declared shape.
+            if (target.accessors.length !== 0)
+                return never('a record with accessors has no pure dynamic product materializer');
+            return deriveRecord(target, nested, path);
+        case 'record-with-index':
+            // The algebra has no shape for this carrier's open half for the same
+            // reason it has none for `dictionary` (below): Product needs a complete
+            // frozen field list, and the index signature is deliberately open. A
+            // materializer that only populated the named fields and left the
+            // sidecar empty would silently drop every dynamic-keyed property a
+            // dynamic value actually carried, which is a worse answer than refusing.
+            return (maybeAtom(context.registry.boxedIdentityMaterializer(target)) ??
+                never(`record-with-index shape "${target.shapeId}" has an open dictionary sidecar; no checked, semantics-preserving ` +
+                    'object/dictionary view exists for it, and a snapshot cast is forbidden'));
+        case 'proxy-object':
+            return never('a Proxy cannot be reconstructed from an arbitrary object value');
+        case 'native-record-ref':
+            // The same round trip a `record` gets immediately above, and available
+            // for exactly the same reason: `Value::box` records the payload's own
+            // C++ type whoever owns the layout, so a `gea::Ref<gea::runtime::Date>`
+            // this program boxed is recognized and handed back by the identical
+            // primitive. The refusal below is the honest answer only for the
+            // ownerships no round trip exists for -- a `borrowed` reference has no
+            // lifetime to hand back, and the registry says so by answering `null`.
+            return atomFrom(context.registry.recordRefMaterializer(target.shapeId, target.ownership), `an erased or borrowed native reference to shape "${target.shapeId}" (${target.ownership}) is not recoverable from a dynamic value`);
+        case 'borrowed-ref':
+            return never('lifetime and alias authority cannot be synthesized');
+        case 'array-object':
+            return deriveArrayObject(target, nested, path);
+        case 'dense-buffer':
+            // Compiler/runtime-private storage per representation/model.ts; no JavaScript value is ever observed as one.
+            return never('a dense buffer is compiler/runtime-private storage, never a JavaScript-observable value');
+        case 'typed-array':
+            // ECMA-262 23.2's typed array views have no generic "wrap this dynamic
+            // value" constructor: `new Uint8Array(dynamicValue)` dispatches on
+            // `dynamicValue`'s own runtime shape (a length, an ArrayBuffer, an
+            // iterable) rather than performing one uniform conversion, so there is
+            // no single materializer this algebra could name for a fixed target
+            // element width.
+            return (maybeAtom(context.registry.boxedIdentityMaterializer(target)) ??
+                never('a typed array cannot be reconstructed from an arbitrary dynamic value; no single ECMAScript operation produces one that way'));
+        case 'array-buffer':
+        case 'shared-array-buffer':
+            // The same refusal one level down, and for a stronger reason: an
+            // ArrayBuffer is an OBJECT IDENTITY over a block of bytes, so the only
+            // way to obtain one from a dynamic value is to unwrap the identity the
+            // value already holds -- which is a brand check this algebra has no
+            // shape for -- and the alternative, copying the bytes, would produce a
+            // buffer no view of the original aliases.
+            return (maybeAtom(context.registry.boxedIdentityMaterializer(target)) ??
+                never('an ArrayBuffer is an object identity over a byte block; no pure projection reconstructs one from a dynamic value'));
+        case 'data-view':
+            return never('a DataView is an object identity over a byte block; no pure projection reconstructs one from a dynamic value');
+        case 'native-sequence':
+            return never('a storage snapshot is not an ECMAScript Array identity');
+        case 'iterator':
+            return never('iterator acquisition is an effectful semantic protocol, not a pure projection');
+        case 'promise':
+            return never('promise assimilation is an effectful semantic protocol, not a pure projection');
+        case 'dictionary':
+            // The round trip first, the same order and for the same reason `record`
+            // above takes it: a `gea::Dictionary<V>` THIS program boxed comes back
+            // as itself, recognized by the payload type `Value::box` recorded, with
+            // no key walk and no reconstruction.
+            //
+            // The refusal below is about RECONSTRUCTION and stays exactly right for
+            // it: the algebra has no shape for an open string-keyed view -- Product
+            // needs a complete frozen field list, Collection's domain is
+            // Array-shaped -- so building a dictionary out of an arbitrary dynamic
+            // value would be the fabricated materializer this module must not
+            // produce. Handing back the object that was boxed is not that: it is a
+            // tag check, an address check and a handle copy.
+            return (maybeAtom(context.registry.boxedIdentityMaterializer(target)) ??
+                never('no checked, semantics-preserving object/dictionary view exists; a snapshot cast is forbidden'));
+        case 'keyed-collection':
+            // Same gap as `dictionary` above, one step further out. Recovering a
+            // `Map<K, V>` from a box would need a runtime brand check plus a
+            // per-entry checked conversion of BOTH positions, and this registry
+            // installs no such classifier -- v1 spelled that route as
+            // `gea_cpp_typed_js_map::from_dynamic_checked`, which is exactly the
+            // boxed round trip this compiler declines to build.
+            return never('no checked Map/Set materializer is installed; recovering a keyed collection from a dynamic value needs a runtime ' +
+                'brand check plus a per-entry checked conversion of both key and value');
+        case 'function':
+            return atomFrom(context.registry.functionMaterializer(target.functionId, target.abi), `category-only function checks are insufficient; no authenticated callable-identity materializer installed for ${target.functionId}`);
+        case 'function-family':
+            return never('a closed authenticated family tag and ABI join are required, and family authority is not a runtime classifier/materializer');
+        case 'constructor-family':
+        case 'constructor-value-dispatch':
+        case 'function-and-constructor':
+            return never('constructor identity is nominal authority; no runtime materializer can rediscover it from a dynamic value');
+        case 'function-value-family':
+            return never('family membership and optional absence require exact tag authority that no runtime materializer can supply');
+        case 'generic-function-set':
+            return never('a generic function set is a compile-time choice among source declarations; no runtime value materializes one');
+        case 'callable-identity':
+            // A boxed value that IS a function does carry one of these, but reading
+            // it back needs an authenticated callable classifier, and this registry
+            // installs none -- the same gap `function` above states.
+            return never('no installed classifier recovers a function identity from a dynamic value');
+        case 'function-value-dispatch':
+            return atomFrom(context.registry.functionValueDispatchMaterializer(target.abi), 'no checked dynamic Function adapter is installed for this evaluated dispatch ABI');
+        case 'optional':
+            return deriveOptional(target, nested, path);
+        case 'tagged-union':
+            return deriveTaggedUnion(target, nested, path);
+        case 'dynamic':
+            return { kind: 'identity' };
+    }
+};
+const deriveRecord = (target, context, path) => {
+    const materializer = context.registry.recordMaterializer(target.shapeId, target.ownership);
+    if (!materializer)
+        return never(`no installed product materializer for record shape "${target.shapeId}" (${target.ownership})`);
+    const fields = target.fields.map((field) => ({
+        key: field.key,
+        required: field.required,
+        capability: deriveAt(field.value, context, `${path}.${field.key}`)
+    }));
+    return { kind: 'product', fields, materializer };
+};
+const deriveArrayObject = (target, context, path) => {
+    // The fields an extended interface adds have no dynamic source: a boxed
+    // value materialized element by element is a plain array, and reading it
+    // as one with fields would hand back defaults for data the value never
+    // carried.
+    if (target.extension !== null)
+        return never("an Array carrying an extended interface's typed fields has no dynamic source for those fields");
+    const domain = context.registry.arrayObjectDomain(target.ownership);
+    if (!domain)
+        return never(`no installed materializable-ordinary-Array domain for ownership "${target.ownership}"`);
+    if (!domain.preservesHoles || !domain.preservesIdentity) {
+        // The table requires hole/present-undefined preservation and shared Array identity outright; an
+        // installed domain that drops either is not the domain the architecture calls for, so it fails closed.
+        return never('installed array domain does not preserve hole and shared-identity semantics required for array-object');
+    }
+    const element = deriveAt(target.element, context, `${path}[]`);
+    return { kind: 'collection', element, domain };
+};
+const deriveOptional = (target, context, path) => {
+    // `target.absence` names WHICH of the two absent values this optional means --
+    // passing it through is what lets a backend answer `Null` for one and
+    // `Undefined` for the other rather than being forced to pick one tag for both
+    // (see `optionalAbsenceTag`'s own doc: `gea::Optional<T>` records only
+    // presence/absence, so a single fixed tag would silently mismatch whichever
+    // spelling it did not choose).
+    const absenceTag = context.registry.optionalAbsenceTag(target.absence);
+    if (absenceTag === null)
+        return never("no exact absence tag is installed to distinguish an optional's absent case");
+    const payload = deriveAt(target.payload, context, `${path}.payload`);
+    return { kind: 'optional', payload, absenceTag };
+};
+const deriveTaggedUnion = (target, context, path) => {
+    const seenTags = new Set();
+    for (const arm of target.arms) {
+        if (seenTags.has(arm.tag))
+            return never(`tagged-union arms are not a complete unique-tag census: duplicate tag "${arm.tag}"`);
+        seenTags.add(arm.tag);
+    }
+    // Nominal family tests admit descendants.  Consequently `Base | Derived`
+    // has no unique dynamic arm for a Derived allocation: both projections are
+    // true, and choosing by declaration order would silently change the union's
+    // stored identity.  Sibling program classes remain disjoint under the
+    // single-inheritance class table; only an ancestor relation is overlap.
+    for (let left = 0; left < target.arms.length; left++) {
+        const leftValue = target.arms[left].value;
+        if (leftValue.kind !== 'class-ref')
+            continue;
+        for (let right = left + 1; right < target.arms.length; right++) {
+            const rightValue = target.arms[right].value;
+            if (rightValue.kind === 'class-ref' && classRefDomainsOverlap(leftValue, rightValue))
+                return never('tagged-union nominal arms overlap through a base/derived class family and have no unique dynamic member');
+        }
+    }
+    // Collect every arm's classifier before deriving any payload capability, so disjointness is proved
+    // from the classifiers' own domains -- never inferred from the order the arms happen to be declared in.
+    const classified = [];
+    for (const arm of target.arms) {
+        const classifier = context.registry.taggedUnionArmClassifier(arm);
+        if (!classifier)
+            return never(`no installed disjointness-proving classifier for tagged-union arm "${arm.tag}"`);
+        classified.push({ tag: arm.tag, classifier, value: arm.value });
+    }
+    if (classified.some((entry, index) => classified.slice(index + 1).some((other) => classifierDomainsOverlap(entry.classifier, other.classifier)))) {
+        return never('tagged-union arm classifiers share a runtime domain and are therefore not pairwise disjoint');
+    }
+    const arms = classified.map((entry) => ({
+        tag: entry.tag,
+        classifier: entry.classifier,
+        capability: deriveAt(entry.value, context, `${path}#${entry.tag}`)
+    }));
+    return { kind: 'sum', arms };
+};

package/dist/conversion/graph-validation.d.ts

@@ -0,0 +1,8 @@
+import type { ConversionNode } from './algebra.js';
+/**
+ * Validates a whole conversion graph: every node's internal shape via
+ * `validateCapability`, plus the one defect a single node can never see on its
+ * own -- a `recursive-ref` chain that loops through other nodes forever
+ * without ever reaching a materializer.
+ */
+export declare const validateConversionGraph: (nodes: readonly ConversionNode[]) => void;

package/dist/conversion/graph-validation.js

@@ -0,0 +1,97 @@
+import { validateCapability } from './algebra.js';
+/**
+ * Whether a conversion graph's `recursive-ref` sites actually close.
+ *
+ * `isMaterializable` in algebra.ts treats every `recursive-ref` as trivially
+ * materializable, because a single capability in isolation has no other node
+ * to consult. That is correct for that question, but it means a set of nodes
+ * that only ever refer to each other -- with no node in the cycle ever
+ * reaching a real `Atom`, `Identity`, or a `Product`/`Collection`/`Sum` whose
+ * every branch bottoms out -- would still read as materializable. This module
+ * is the whole-graph check that catches that: it resolves every node's
+ * materializability by consulting the nodes its `recursive-ref`s point to, and
+ * rejects a reference into a cycle that never reaches a base case.
+ */
+const capabilityReachesMaterializer = (capability, resolved) => {
+    switch (capability.kind) {
+        case 'never':
+            return false;
+        case 'identity':
+        case 'atom':
+        case 'coercion':
+        case 'static':
+        case 'class-family':
+            return true;
+        case 'optional':
+            return capabilityReachesMaterializer(capability.payload, resolved);
+        case 'product':
+            return capability.fields.every((field) => capabilityReachesMaterializer(field.capability, resolved));
+        case 'collection':
+            return capabilityReachesMaterializer(capability.element, resolved);
+        case 'sum':
+            return capability.arms.length > 0 && capability.arms.every((arm) => capabilityReachesMaterializer(arm.capability, resolved));
+        case 'recursive-ref':
+            return resolved.get(capability.node) ?? false;
+    }
+};
+/**
+ * Least fixed point over "does this node's capability reach a materializer".
+ * The relation only ever flips a node from `false` to `true`, so it is
+ * monotone and converges in at most `nodes.length` passes.
+ */
+const resolveMaterializability = (nodes) => {
+    const resolved = new Map(nodes.map((node) => [node.id, false]));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const node of nodes) {
+            if (resolved.get(node.id))
+                continue;
+            if (capabilityReachesMaterializer(node.capability, resolved)) {
+                resolved.set(node.id, true);
+                changed = true;
+            }
+        }
+    }
+    return resolved;
+};
+const collectRecursiveRefs = (capability) => {
+    switch (capability.kind) {
+        case 'never':
+        case 'identity':
+        case 'atom':
+        case 'coercion':
+        case 'static':
+        case 'class-family':
+            return [];
+        case 'recursive-ref':
+            return [capability.node];
+        case 'optional':
+            return collectRecursiveRefs(capability.payload);
+        case 'product':
+            return capability.fields.flatMap((field) => collectRecursiveRefs(field.capability));
+        case 'collection':
+            return collectRecursiveRefs(capability.element);
+        case 'sum':
+            return capability.arms.flatMap((arm) => collectRecursiveRefs(arm.capability));
+    }
+};
+/**
+ * Validates a whole conversion graph: every node's internal shape via
+ * `validateCapability`, plus the one defect a single node can never see on its
+ * own -- a `recursive-ref` chain that loops through other nodes forever
+ * without ever reaching a materializer.
+ */
+export const validateConversionGraph = (nodes) => {
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    for (const node of nodes)
+        validateCapability(node.capability, nodeIds, node.id);
+    const resolved = resolveMaterializability(nodes);
+    for (const node of nodes) {
+        for (const ref of collectRecursiveRefs(node.capability)) {
+            if (!resolved.get(ref)) {
+                throw new Error(`conversion node "${node.id}": recursive reference to "${ref}" never reaches a materializer (unclosed cycle)`);
+            }
+        }
+    }
+};

package/dist/conversion/native-callable-adapter.d.ts

@@ -0,0 +1,13 @@
+import type { ConversionNode } from './algebra.js';
+import { type Representation } from '../representation/model.js';
+/** A selected native adapter ignores only an added receiver. The ordinary
+ * frame is unchanged, so callable provenance may enter the original body
+ * with those arguments and no receiver, retaining the same Function identity.
+ */
+export declare const nativeReceiverIgnoringCallableAdapterMatches: (source: Representation, target: Representation, node: ConversionNode | null | undefined) => boolean;
+/** A cited identity-preserving native adapter can also discard a fixed
+ * trailing argument suffix. Only the source prefix reaches its body; result
+ * and prefix carriers stay identical. Receiver adaptation is licensed by the
+ * same selected conversion, never inferred from class spellings here.
+ */
+export declare const nativeCallablePrefixAdapterMatches: (source: Representation, target: Representation, node: ConversionNode | null | undefined) => boolean;

package/dist/conversion/native-callable-adapter.js

@@ -0,0 +1,53 @@
+import { abiOfCallee } from '../projection/callee.js';
+import { abiKey, representationKey } from '../representation/model.js';
+/** A selected native adapter ignores only an added receiver. The ordinary
+ * frame is unchanged, so callable provenance may enter the original body
+ * with those arguments and no receiver, retaining the same Function identity.
+ */
+export const nativeReceiverIgnoringCallableAdapterMatches = (source, target, node) => {
+    if (!node || representationKey(node.source) !== representationKey(source) || representationKey(node.target) !== representationKey(target))
+        return false;
+    const from = abiOfCallee(source);
+    const to = abiOfCallee(target);
+    if (!from || !to || from.receiver !== null || to.receiver === null || abiKey({ ...from, receiver: to.receiver }) !== abiKey(to))
+        return false;
+    const capability = node.capability;
+    if (capability.kind !== 'atom' && capability.kind !== 'static')
+        return false;
+    const materializer = capability.materializer;
+    const adapter = materializer.callableAdapter;
+    return (materializer.nativeFieldProtocol === 'unused' &&
+        materializer.callableIdentityTransport === 'preserved' &&
+        adapter !== undefined &&
+        abiKey(adapter.from) === abiKey(from) &&
+        abiKey(adapter.to) === abiKey(to));
+};
+/** A cited identity-preserving native adapter can also discard a fixed
+ * trailing argument suffix. Only the source prefix reaches its body; result
+ * and prefix carriers stay identical. Receiver adaptation is licensed by the
+ * same selected conversion, never inferred from class spellings here.
+ */
+export const nativeCallablePrefixAdapterMatches = (source, target, node) => {
+    if (!node || representationKey(node.source) !== representationKey(source) || representationKey(node.target) !== representationKey(target))
+        return false;
+    const from = abiOfCallee(source);
+    const to = abiOfCallee(target);
+    if (!from || !to || from.restFrom !== null || to.restFrom !== null || from.parameters.length > to.parameters.length)
+        return false;
+    if (from.receiver !== null && to.receiver === null)
+        return false;
+    if (abiKey({ ...from, receiver: to.receiver, parameters: to.parameters.slice(0, from.parameters.length) }) !==
+        abiKey({ ...from, receiver: to.receiver }))
+        return false;
+    if (representationKey(from.result) !== representationKey(to.result))
+        return false;
+    const capability = node.capability;
+    if (capability.kind !== 'atom' && capability.kind !== 'static')
+        return false;
+    const materializer = capability.materializer;
+    return (materializer.nativeFieldProtocol === 'unused' &&
+        materializer.callableIdentityTransport === 'preserved' &&
+        materializer.callableAdapter !== undefined &&
+        abiKey(materializer.callableAdapter.from) === abiKey(from) &&
+        abiKey(materializer.callableAdapter.to) === abiKey(to));
+};

package/dist/conversion/native-class-reference.d.ts

@@ -0,0 +1,12 @@
+import type { ConversionNode, MaterializerContract } from './algebra.js';
+import { type Representation } from '../representation/model.js';
+/** Called by materializer producers only after selecting an identity-preserving native operation. */
+export declare const nativeClassReferenceIdentityOf: (source: Representation, target: Representation) => Pick<MaterializerContract, "nativeClassReferenceIdentity">;
+/**
+ * A native reference can change its nullable/union envelope without exposing
+ * another route to its fields. Structural records and containers are excluded:
+ * their conversion can publish nested aliases that a class-slot census has not
+ * indexed. The installed conversion must independently certify preservation of
+ * reference identity; absence of boxing or allocation alone is not that proof.
+ */
+export declare const nativeClassReferenceTransportMatches: (source: Representation, target: Representation, node: ConversionNode | null | undefined) => boolean;

package/dist/conversion/native-class-reference.js

@@ -0,0 +1,39 @@
+import { representationKey } from '../representation/model.js';
+const referenceEnvelope = (value) => {
+    switch (value.kind) {
+        case 'class-ref':
+            return value.ownership === 'shared-refcount';
+        case 'null':
+        case 'undefined':
+            return true;
+        case 'optional':
+            return referenceEnvelope(value.payload);
+        case 'tagged-union':
+            return value.arms.length > 0 && value.arms.every((arm) => referenceEnvelope(arm.value));
+        default:
+            return false;
+    }
+};
+/** Called by materializer producers only after selecting an identity-preserving native operation. */
+export const nativeClassReferenceIdentityOf = (source, target) => referenceEnvelope(source) && referenceEnvelope(target) ? { nativeClassReferenceIdentity: 'preserved' } : {};
+/**
+ * A native reference can change its nullable/union envelope without exposing
+ * another route to its fields. Structural records and containers are excluded:
+ * their conversion can publish nested aliases that a class-slot census has not
+ * indexed. The installed conversion must independently certify preservation of
+ * reference identity; absence of boxing or allocation alone is not that proof.
+ */
+export const nativeClassReferenceTransportMatches = (source, target, node) => {
+    if (!node ||
+        representationKey(node.source) !== representationKey(source) ||
+        representationKey(node.target) !== representationKey(target) ||
+        !referenceEnvelope(source) ||
+        !referenceEnvelope(target))
+        return false;
+    const capability = node.capability;
+    return (capability.kind === 'identity' ||
+        ((capability.kind === 'atom' || capability.kind === 'static' || capability.kind === 'class-family') &&
+            !capability.materializer.allocates &&
+            capability.materializer.nativeFieldProtocol === 'unused' &&
+            capability.materializer.nativeClassReferenceIdentity === 'preserved'));
+};

package/dist/conversion/native-payload-transport.d.ts

@@ -0,0 +1,25 @@
+import type { ConversionNode } from './algebra.js';
+import { type Representation } from '../representation/model.js';
+/** Consume the selected materializer's payload proof. The existence of a
+ * different native recipe for this pair cannot certify the installed one.
+ *
+ * `class-family` joins `atom`/`static` here, not beside them by coincidence:
+ * `conversion/build.ts`'s `narrowingCapabilityFor` wraps the IDENTICAL
+ * `installed.materializer` a plain narrowing `atom` would get, reaching for
+ * `class-family` only because a base handle narrowed to a union of
+ * descendants needs the class-table-aware cascade
+ * `targets/cpp/emit-narrowing.ts`'s `classFamilyLoadText` renders, not
+ * because the runtime proof about the value differs -- `algebra.ts`'s own
+ * `transfersNativeStorage` already treats `atom`/`static`/`class-family`
+ * identically for exactly this reason. Refusing the capability kind here
+ * while accepting it two lines up (for `atom`) meant a class field read back
+ * through a narrowing/widening class-family conversion -- a base field typed
+ * `Object3D` resolved at one call site to a closed union of its own
+ * descendants, or the reverse -- could never be `exact` even when the cited
+ * materializer proved the identical non-allocating, field-protocol-free,
+ * payload-preserving transfer an `atom` pair proves for the same shape of
+ * conversion. The materializer conditions below are UNCHANGED from the
+ * `atom`/`static` case; only which `capability.kind` may present one is
+ * widened.
+ */
+export declare const nativePayloadTransportMatches: (source: Representation, target: Representation, node: ConversionNode | null | undefined) => boolean;

package/dist/conversion/native-payload-transport.js

@@ -0,0 +1,33 @@
+import { representationKey } from '../representation/model.js';
+/** Consume the selected materializer's payload proof. The existence of a
+ * different native recipe for this pair cannot certify the installed one.
+ *
+ * `class-family` joins `atom`/`static` here, not beside them by coincidence:
+ * `conversion/build.ts`'s `narrowingCapabilityFor` wraps the IDENTICAL
+ * `installed.materializer` a plain narrowing `atom` would get, reaching for
+ * `class-family` only because a base handle narrowed to a union of
+ * descendants needs the class-table-aware cascade
+ * `targets/cpp/emit-narrowing.ts`'s `classFamilyLoadText` renders, not
+ * because the runtime proof about the value differs -- `algebra.ts`'s own
+ * `transfersNativeStorage` already treats `atom`/`static`/`class-family`
+ * identically for exactly this reason. Refusing the capability kind here
+ * while accepting it two lines up (for `atom`) meant a class field read back
+ * through a narrowing/widening class-family conversion -- a base field typed
+ * `Object3D` resolved at one call site to a closed union of its own
+ * descendants, or the reverse -- could never be `exact` even when the cited
+ * materializer proved the identical non-allocating, field-protocol-free,
+ * payload-preserving transfer an `atom` pair proves for the same shape of
+ * conversion. The materializer conditions below are UNCHANGED from the
+ * `atom`/`static` case; only which `capability.kind` may present one is
+ * widened.
+ */
+export const nativePayloadTransportMatches = (source, target, node) => {
+    if (!node || representationKey(node.source) !== representationKey(source) || representationKey(node.target) !== representationKey(target))
+        return false;
+    const capability = node.capability;
+    return (capability.kind === 'identity' ||
+        ((capability.kind === 'atom' || capability.kind === 'static' || capability.kind === 'class-family') &&
+            !capability.materializer.allocates &&
+            capability.materializer.nativeFieldProtocol === 'unused' &&
+            capability.materializer.nativePayloadTransport === 'preserved'));
+};

package/dist/conversion/native-selection.d.ts

@@ -0,0 +1,49 @@
+import type { Representation } from '../representation/model.js';
+import { type NativeSumPlan } from './native-sum.js';
+export type NativeSelectionStep = {
+    readonly kind: 'identity';
+} | {
+    readonly kind: 'null';
+} | {
+    readonly kind: 'reference-null';
+    readonly absent: NativeSelectionStep;
+} | {
+    readonly kind: 'transfer';
+    readonly plan: NativeSumPlan;
+} | {
+    readonly kind: 'class-cast';
+    readonly target: Extract<Representation, {
+        kind: 'class-ref';
+    }>;
+    readonly down: boolean;
+} | {
+    readonly kind: 'optional';
+    readonly absence: 'null' | 'undefined';
+    readonly present: NativeSelectionStep | null;
+    readonly absent: NativeSelectionStep | null;
+} | {
+    readonly kind: 'dispatch';
+    readonly arms: readonly (NativeSelectionStep | null)[];
+};
+/** A sealed selection uses only native tags, payload loads and nominal handle casts. */
+export interface NativeSelectionRecipe {
+    readonly source: string;
+    readonly target: string;
+    readonly step: NativeSelectionStep;
+}
+/**
+ * Selection is partial in its runtime domain, never partial in its analysis.
+ * Every excluded alternative must be proven disjoint. An opaque alternative
+ * keeps the general conversion recipe; it cannot be dropped to avoid boxing.
+ * Admission still belongs to the caller's existing narrowing authority.
+ */
+export declare const nativeSelectionRecipeOf: (source: Representation, target: Representation) => NativeSelectionRecipe | null;
+/** Widening may not discard an alternative or require a successful downcast. */
+export declare const nativeTotalSelectionRecipeOf: (source: Representation, target: Representation) => NativeSelectionRecipe | null;
+/**
+ * The same total step for ONE alternative a caller has already proven live
+ * (a merge's live arm, its live absence). Leaves are admitted here too: the
+ * `null -> shared Ref` rule and the nominal upcast are total, and neither
+ * can discard an alternative. A downcast or a collapsed-null test is not.
+ */
+export declare const nativeTotalSelectionStepOf: (source: Representation, target: Representation) => NativeSelectionStep | null;