@geastack/compiler 1.0.15

package/dist/conversion/native-selection.js

@@ -0,0 +1,135 @@
+import { representationKey } from '../representation/model.js';
+import { nativeSumPlan } from './native-sum.js';
+/**
+ * These carriers have distinct native runtime categories. A structural object,
+ * host handle or dynamic value cannot be excluded merely because its carrier
+ * key differs: it might require a view, host conversion or checked unbox.
+ */
+const categoryOf = (value) => {
+    switch (value.kind) {
+        case 'scalar':
+            return value.domain;
+        case 'string':
+        case 'symbol':
+        case 'null':
+        case 'undefined':
+        case 'class-ref':
+        case 'array-object':
+        case 'typed-array':
+            return value.kind;
+        default:
+            return null;
+    }
+};
+const disjoint = (source, target, sourcePresent = false) => {
+    if (target.kind === 'optional')
+        return disjoint(source, target.payload, sourcePresent) && disjoint(source, { kind: target.absence }, sourcePresent);
+    if (target.kind === 'tagged-union')
+        return target.arms.every((arm) => disjoint(source, arm.value, sourcePresent));
+    if (source.kind === 'class-ref' && target.kind === 'class-ref')
+        return (source.declaration !== target.declaration &&
+            !source.ancestors.includes(target.declaration) &&
+            !target.ancestors.includes(source.declaration));
+    // A shared class handle can carry the collapsed class|null representation.
+    if (source.kind === 'class-ref' && target.kind === 'null')
+        return sourcePresent;
+    if (source.kind === 'null' && target.kind === 'class-ref')
+        return false;
+    const from = categoryOf(source);
+    const to = categoryOf(target);
+    return from !== null && to !== null && from !== to;
+};
+const select = (source, target) => {
+    if (representationKey(source) === representationKey(target))
+        return { kind: 'identity' };
+    const transfer = nativeSumPlan(source, target);
+    if (transfer)
+        return { kind: 'transfer', plan: transfer };
+    if (source.kind === 'optional') {
+        const present = select(source.payload, target);
+        const absent = select({ kind: source.absence }, target);
+        if (present === 'unknown' || absent === 'unknown')
+            return 'unknown';
+        if (present === 'disjoint' && absent === 'disjoint')
+            return 'disjoint';
+        return {
+            kind: 'optional',
+            absence: source.absence,
+            present: present === 'disjoint' ? null : present,
+            absent: absent === 'disjoint' ? null : absent
+        };
+    }
+    if (source.kind === 'tagged-union') {
+        const arms = source.arms.map((arm) => select(arm.value, target));
+        if (arms.includes('unknown'))
+            return 'unknown';
+        if (arms.every((arm) => arm === 'disjoint'))
+            return 'disjoint';
+        return { kind: 'dispatch', arms: arms.map((arm) => (typeof arm === 'string' ? null : arm)) };
+    }
+    if (source.kind === 'class-ref' && target.kind === 'class-ref' && source.ownership === target.ownership) {
+        // Shape aliases do not mint a new class allocation or C++ class type.
+        if (source.declaration === target.declaration)
+            return { kind: 'identity' };
+        if (source.ownership === 'shared-refcount') {
+            if (target.ancestors.includes(source.declaration))
+                return { kind: 'class-cast', target, down: true };
+            if (source.ancestors.includes(target.declaration))
+                return { kind: 'class-cast', target, down: false };
+            return { kind: 'reference-null', absent: { kind: 'null' } };
+        }
+    }
+    if (source.kind === 'null' && target.kind === 'class-ref' && target.ownership === 'shared-refcount')
+        return { kind: 'null' };
+    if (source.kind === 'class-ref' && source.ownership === 'shared-refcount') {
+        if (target.kind === 'null')
+            return { kind: 'reference-null', absent: { kind: 'null' } };
+        const absent = nativeSumPlan({ kind: 'null' }, target);
+        if (absent && disjoint(source, target, true))
+            return { kind: 'reference-null', absent: { kind: 'transfer', plan: absent } };
+    }
+    return disjoint(source, target) ? 'disjoint' : 'unknown';
+};
+/**
+ * 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 const nativeSelectionRecipeOf = (source, target) => {
+    if (source.kind !== 'optional' && source.kind !== 'tagged-union')
+        return null;
+    const step = select(source, target);
+    return typeof step === 'string' ? null : { source: representationKey(source), target: representationKey(target), step };
+};
+const total = (step) => {
+    if (step === null)
+        return false;
+    switch (step.kind) {
+        case 'dispatch':
+            return step.arms.every(total);
+        case 'optional':
+            return total(step.present) && total(step.absent);
+        case 'class-cast':
+            return !step.down;
+        case 'reference-null':
+            return false;
+        default:
+            return true;
+    }
+};
+/** Widening may not discard an alternative or require a successful downcast. */
+export const nativeTotalSelectionRecipeOf = (source, target) => {
+    const recipe = nativeSelectionRecipeOf(source, target);
+    return recipe && total(recipe.step) ? recipe : 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 const nativeTotalSelectionStepOf = (source, target) => {
+    const step = select(source, target);
+    return typeof step === 'string' || !total(step) ? null : step;
+};

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

@@ -0,0 +1,42 @@
+import type { Representation } from '../representation/model.js';
+type Sum = Extract<Representation, {
+    kind: 'optional' | 'tagged-union';
+}>;
+export type NativeSumPlan = {
+    readonly kind: 'identity';
+} | {
+    readonly kind: 'class-upcast';
+    readonly target: Extract<Representation, {
+        kind: 'class-ref';
+    }>;
+} | {
+    readonly kind: 'null-reference';
+    readonly target: Extract<Representation, {
+        kind: 'class-ref';
+    }>;
+} | {
+    readonly kind: 'empty';
+    readonly target: Sum;
+} | {
+    readonly kind: 'wrap';
+    readonly target: Sum;
+    readonly payload: NativeSumPlan;
+    readonly index: number | null;
+} | {
+    readonly kind: 'optional';
+    readonly target: Representation;
+    readonly absence: 'null' | 'undefined';
+    readonly present: NativeSumPlan;
+    readonly absent: NativeSumPlan;
+} | {
+    readonly kind: 'dispatch';
+    readonly target: Representation;
+    readonly arms: readonly NativeSumPlan[];
+} | {
+    readonly kind: 'nullable-reference';
+    readonly present: NativeSumPlan;
+    readonly absent: NativeSumPlan;
+};
+export declare const nativeSumPlan: (source: Representation, target: Representation) => NativeSumPlan | null;
+export declare const nativeSumWidenable: (source: Representation, target: Representation) => boolean;
+export {};

package/dist/conversion/native-sum.js

@@ -0,0 +1,115 @@
+import { representationKey } from '../representation/model.js';
+const isSum = (value) => value.kind === 'optional' || value.kind === 'tagged-union';
+const plans = new WeakMap();
+const absences = { null: { kind: 'null' }, undefined: { kind: 'undefined' } };
+const plan = (source, target, sourcePresent = false) => {
+    let targets = plans.get(source);
+    if (!targets)
+        plans.set(source, (targets = new WeakMap()));
+    let states = targets.get(target);
+    if (!states)
+        targets.set(target, (states = {}));
+    const key = sourcePresent ? 'present' : 'ordinary';
+    const known = states[key];
+    if (known !== undefined)
+        return known;
+    const result = computePlan(source, target, sourcePresent);
+    states[key] = result;
+    return result;
+};
+const computePlan = (source, target, sourcePresent) => {
+    if (representationKey(source) === representationKey(target))
+        return { kind: 'identity' };
+    // Ref<T> also carries the collapsed T|null representation. A destination
+    // that represents null separately, even under nested sums, must inspect
+    // that state before wrapping T in a present arm.
+    if (!sourcePresent && source.kind === 'class-ref' && source.ownership === 'shared-refcount' && isSum(target)) {
+        const present = plan(source, target, true);
+        const absent = present ? plan(absences.null, target, true) : null;
+        if (present && absent)
+            return { kind: 'nullable-reference', present, absent };
+    }
+    if (source.kind === 'optional') {
+        const present = plan(source.payload, target);
+        if (!present)
+            return null;
+        const absent = plan(absences[source.absence], target);
+        return present && absent ? { kind: 'optional', target, absence: source.absence, present, absent } : null;
+    }
+    if (source.kind === 'tagged-union') {
+        const arms = [];
+        for (const arm of source.arms) {
+            const converted = plan(arm.value, target);
+            if (!converted)
+                return null;
+            arms.push(converted);
+        }
+        return arms.length > 0 ? { kind: 'dispatch', target, arms } : null;
+    }
+    // A sum's leaf can still need the ordinary nominal widening a bare class
+    // value already supports. Three's `light.shadow && light.shadow.map` reads
+    // two WebGLRenderTarget descendants on the evaluated arm and merges them
+    // into the declared base-class arm beside null/undefined. Exact carrier-key
+    // matching cannot find that home, but the source class names its complete
+    // ancestry and ownership, so this is the same unambiguous upcast
+    // `convertedValueText` performs for a bare Ref rather than a new coercion.
+    if (source.kind === 'class-ref' &&
+        target.kind === 'class-ref' &&
+        source.ownership === target.ownership &&
+        source.ancestors.includes(target.declaration)) {
+        return { kind: 'class-upcast', target };
+    }
+    // The same Ref<T> carrier used for T|null represents null by its empty
+    // handle. This stores the null value; it neither constructs T nor changes
+    // null into the enclosing optional's (possibly undefined) absence.
+    if (source.kind === 'null' && target.kind === 'class-ref' && target.ownership === 'shared-refcount')
+        return { kind: 'null-reference', target };
+    if (target.kind === 'optional') {
+        if (source.kind === target.absence)
+            return { kind: 'empty', target };
+        const payload = plan(source, target.payload, sourcePresent);
+        return payload ? { kind: 'wrap', target, payload, index: null } : null;
+    }
+    if (target.kind === 'tagged-union') {
+        const index = armIndexOf(target);
+        const exact = index.firstByKey.get(representationKey(source)) ?? -1;
+        if (exact >= 0)
+            return { kind: 'wrap', target, payload: { kind: 'identity' }, index: exact };
+        const homes = index.recursiveArms.flatMap((armIndex) => {
+            const arm = target.arms[armIndex];
+            if (arm === undefined)
+                return [];
+            const payload = plan(source, arm.value, sourcePresent);
+            return payload ? [{ kind: 'wrap', target, payload, index: armIndex }] : [];
+        });
+        // Null has no nominal object identity: all proven null homes store the
+        // same JS value. Canonicalize its physical home in representation order,
+        // after the exact null arm above. Non-null alternatives still require a
+        // unique home; choosing an arbitrary base would lose their identity/tag.
+        if (source.kind === 'null')
+            return homes[0] ?? null;
+        // An ambiguous non-null alternative cannot be selected by declaration order.
+        return homes.length === 1 ? (homes[0] ?? null) : null;
+    }
+    return null;
+};
+const armIndexes = new WeakMap();
+const armIndexOf = (union) => {
+    const remembered = armIndexes.get(union);
+    if (remembered !== undefined)
+        return remembered;
+    const firstByKey = new Map();
+    const recursiveArms = [];
+    union.arms.forEach((arm, index) => {
+        const key = representationKey(arm.value);
+        if (!firstByKey.has(key))
+            firstByKey.set(key, index);
+        if (isSum(arm.value) || arm.value.kind === 'class-ref')
+            recursiveArms.push(index);
+    });
+    const built = { firstByKey, recursiveArms };
+    armIndexes.set(union, built);
+    return built;
+};
+export const nativeSumPlan = (source, target) => isSum(target) ? plan(source, target) : null;
+export const nativeSumWidenable = (source, target) => nativeSumPlan(source, target) !== null;

package/dist/conversion/nodes.d.ts

@@ -0,0 +1,55 @@
+import type { Representation } from '../representation/model.js';
+import type { ConversionNode, ConversionNodeId } from './algebra.js';
+import type { CoercionOperation, ConversionRuntimeRegistry } from './registry.js';
+/**
+ * The conversion census: ONE node per (source, target) pair, minted on
+ * demand and remembered.
+ *
+ * `buildConversionGraph` mints eagerly the pairs it can enumerate from the
+ * plan -- dynamic into every referenced carrier, and the narrowing, widening
+ * and recasting pairs its closures propose. Every other pair the program
+ * needs was answered nowhere until the printer ran its ordered chain over
+ * the two carriers at the site, which is how a program certified against
+ * one authority and refused under another. This census is the single
+ * question `slotOf` answers lead to: the lowering asks `nodeFor(source,
+ * slot)` when an operand's carrier differs from its slot's, records the
+ * node on the `convert` instruction, and the printer renders THAT node's
+ * recipe. A pair with no recipe is a `never` node here, before the IR is
+ * built, and the certificate refuses it by name.
+ *
+ * Order of authority for a pair, first answer wins:
+ *   1. identity -- the same carrier;
+ *   2. the eager graph's node, when it minted one;
+ *   3. dynamic source -- the derivation over the target (what the eager
+ *      graph would have minted had the target been referenced);
+ *   4. the registry's narrowing, widening, recasting pair, in that order;
+ *   5. the registry's static recipe;
+ *   6. `never`, with the reason stated.
+ * Steps 4 and 5 are the same two tables the eager graph and the printer
+ * already read; nothing here decides a pair on its own.
+ */
+export interface ConversionCensus {
+    readonly nodeFor: (source: Representation, target: Representation) => ConversionNode;
+    /**
+     * The node for an abstract operation over a source: `ToNumber` lands on
+     * `scalar(number)`, `ToString` on `string`. Not `nodeFor(source, number)`,
+     * which is the STORE of a source into a number cell -- an exact tag read
+     * for a dynamic source, `never` for a string -- where the coercion accepts
+     * every value the carrier holds and computes the language's answer. The
+     * two share a (source, target) pair and nothing else, so the coercion
+     * node's id carries the operation's name and lives in its own table.
+     */
+    readonly coercionFor: (source: Representation, operation: CoercionOperation) => ConversionNode;
+    /** The node a `convert` instruction names, from whichever table minted it; `null` for an id no census minted. */
+    readonly nodeById: (id: ConversionNodeId) => ConversionNode | null;
+    /** Every node minted through `nodeFor` that the eager graph did not already hold. */
+    readonly minted: ReadonlyMap<ConversionNodeId, ConversionNode>;
+}
+export interface ConversionCensusInput {
+    readonly registry: ConversionRuntimeRegistry;
+    readonly nodes: ReadonlyMap<ConversionNodeId, ConversionNode>;
+}
+export declare const conversionNodeIdOf: (source: Representation, target: Representation) => ConversionNodeId;
+/** The carrier each abstract operation lands on. */
+export declare const coercionTargetOf: (operation: CoercionOperation) => Representation;
+export declare const createConversionNodes: (input: ConversionCensusInput) => ConversionCensus;

package/dist/conversion/nodes.js

@@ -0,0 +1,91 @@
+import { representationKey } from '../representation/model.js';
+import { validateCapability } from './algebra.js';
+import { createConversionDerivationContext, deriveConversionCapability } from './derive.js';
+import { narrowingCapabilityFor } from './build.js';
+export const conversionNodeIdOf = (source, target) => `${representationKey(source)}->${representationKey(target)}`;
+/** The carrier each abstract operation lands on. */
+export const coercionTargetOf = (operation) => operation === 'ToNumber' ? { kind: 'scalar', domain: 'number' } : { kind: 'string' };
+const containsUnresolved = (representation) => representationKey(representation).includes('unresolved');
+export const createConversionNodes = (input) => {
+    const minted = new Map();
+    const context = createConversionDerivationContext(input.registry);
+    const capabilityOf = (source, target, sourceKey, targetKey) => {
+        if (sourceKey === targetKey)
+            return { kind: 'identity' };
+        if (target.kind === 'void') {
+            return { kind: 'static', materializer: { id: 'chain:discard-into-void', domain: 'static:discard-into-void', allocates: false } };
+        }
+        if (source.kind === 'void')
+            return { kind: 'never', reason: `a void source has no value to convert into ${targetKey}` };
+        if (containsUnresolved(source) || containsUnresolved(target)) {
+            return { kind: 'never', reason: `an unresolved carrier in ${sourceKey} -> ${targetKey} names no conversion` };
+        }
+        if (source.kind === 'dynamic') {
+            // The eager graph keys its dynamic-source nodes by the target alone and
+            // mints them from one generic dynamic carrier; a dynamic source with a
+            // different reason is the same conversion, so the same node answers.
+            const eager = input.nodes.get(targetKey);
+            if (eager !== undefined)
+                return eager.capability;
+            return deriveConversionCapability(target, context);
+        }
+        // `narrowing` asked first and on its own, never folded into the generic
+        // loop below: its pair can need `class-family` rather than a plain
+        // `atom` (`build.ts`'s `narrowingCapabilityFor` says why), a distinction
+        // only meaningful for a narrowing answer -- widening and recasting pairs
+        // never reach a base-class-narrowed-to-descendant-union shape.
+        const narrowed = input.registry.narrowing(source, target);
+        if (narrowed)
+            return narrowingCapabilityFor(source, target, narrowed);
+        for (const table of [input.registry.widening, input.registry.recasting]) {
+            const installed = table(source, target);
+            if (installed)
+                return { kind: 'atom', classifier: installed.classifier, materializer: installed.materializer };
+        }
+        const recipe = input.registry.staticRecipe(source, target);
+        if (recipe)
+            return { kind: 'static', materializer: recipe };
+        return { kind: 'never', reason: `no runtime conversion is installed from ${sourceKey} to ${targetKey}` };
+    };
+    const nodeFor = (source, target) => {
+        const sourceKey = representationKey(source);
+        const targetKey = representationKey(target);
+        const id = `${sourceKey}->${targetKey}`;
+        const eager = input.nodes.get(id);
+        if (eager !== undefined)
+            return eager;
+        const remembered = minted.get(id);
+        if (remembered !== undefined)
+            return remembered;
+        const capability = capabilityOf(source, target, sourceKey, targetKey);
+        validateCapability(capability, new Set([...input.nodes.keys(), ...minted.keys(), id]));
+        const node = { id, source, target, capability };
+        minted.set(id, node);
+        return node;
+    };
+    const coercions = new Map();
+    const coercionFor = (source, operation) => {
+        const target = coercionTargetOf(operation);
+        const sourceKey = representationKey(source);
+        const targetKey = representationKey(target);
+        const id = `${sourceKey}->${targetKey}#${operation}`;
+        const remembered = coercions.get(id);
+        if (remembered !== undefined)
+            return remembered;
+        // A source already in the operation's carrier is the identity: ToNumber
+        // of a Number and ToString of a String are the value itself (7.1.4, 7.1.17).
+        const capability = sourceKey === targetKey
+            ? { kind: 'identity' }
+            : (() => {
+                const installed = input.registry.coercion(source, operation);
+                return installed
+                    ? { kind: 'coercion', operation, materializer: installed }
+                    : { kind: 'never', reason: `no ${operation} is installed for ${sourceKey}` };
+            })();
+        const node = { id, source, target, capability };
+        coercions.set(id, node);
+        return node;
+    };
+    const nodeById = (id) => input.nodes.get(id) ?? minted.get(id) ?? coercions.get(id) ?? null;
+    return { nodeFor, coercionFor, nodeById, minted };
+};

package/dist/conversion/operand-view.d.ts

@@ -0,0 +1,14 @@
+import type { RepresentationDeriver } from '../representation/derive.js';
+import { type Representation } from '../representation/model.js';
+import type { SemanticOperand } from '../semantics/model/operands.js';
+/**
+ * A use can narrow a published sum without changing what its producer returns.
+ * In `(query() as string[]).join(',')`, erasure correctly cites the call's
+ * result, but the receiver operand still states the asserted array type. The
+ * load of that arm must be explicit before invoking its native internal method.
+ * Only an existing payload can be selected here: this never boxes, reconstructs
+ * a table, changes a call ABI, or treats an unrelated assertion as a cast.
+ * Preflight checks the resulting pair against the conversion graph; lowering
+ * emits the same pair as an IR conversion.
+ */
+export declare const narrowedOperandView: (source: Representation, operand: SemanticOperand, deriver: RepresentationDeriver) => Representation;

package/dist/conversion/operand-view.js

@@ -0,0 +1,20 @@
+import { representationKey } from '../representation/model.js';
+import { narrowingReachesTarget } from './build.js';
+/**
+ * A use can narrow a published sum without changing what its producer returns.
+ * In `(query() as string[]).join(',')`, erasure correctly cites the call's
+ * result, but the receiver operand still states the asserted array type. The
+ * load of that arm must be explicit before invoking its native internal method.
+ * Only an existing payload can be selected here: this never boxes, reconstructs
+ * a table, changes a call ABI, or treats an unrelated assertion as a cast.
+ * Preflight checks the resulting pair against the conversion graph; lowering
+ * emits the same pair as an IR conversion.
+ */
+export const narrowedOperandView = (source, operand, deriver) => {
+    if (source.kind !== 'optional' && source.kind !== 'tagged-union')
+        return source;
+    const target = deriver.derive(operand.type);
+    if (representationKey(source) === representationKey(target))
+        return source;
+    return narrowingReachesTarget(source, target) ? target : source;
+};

package/dist/conversion/record-view.d.ts

@@ -0,0 +1,157 @@
+import type { RecordField, RecordIndexSidecar, Representation } from '../representation/model.js';
+import type { RecordLayoutPolicy } from '../representation/policies.js';
+/**
+ * One record viewed as another whose declared shape it satisfies -- the
+ * decision, without any spelling.
+ *
+ * `type A = Named & { age: number }` and `({ ...base, ...extra })` describe
+ * one shape and intern as two, so they derive two record carriers under two
+ * shape ids; a class instance handed to a parameter typed by an interface it
+ * implements is the same pair one level up. The C++ backend spells each as a
+ * struct, and a value of one is not a value of the other, so the view REBUILDS
+ * the target from the source's members: field by field, a class method bound
+ * into the callable member the interface record stores, an optional peeled on
+ * both sides, a sum entered at the one arm the source can become.
+ *
+ * This used to be decided where it was spelled (`targets/cpp/emit-callable.ts`'s
+ * `structuralRecordViewText`), which left the conversion census unable to
+ * answer the pair: lowering recorded drift for every initializer that viewed
+ * a record, and the printer converted on its own path. The plan below is
+ * what the registry's `staticRecipe` answers (`targets/cpp/conversions.ts`)
+ * and what the printer renders from, so the two cannot disagree about which
+ * pairs are views.
+ *
+ * `convertible(from, to)` is the registry's own answer for a field or arm
+ * pair that is NOT a view -- a widening, a narrowing, an identity -- and is
+ * the one thing this module does not decide itself: it belongs to the chain
+ * the backend installs, and the plan only asks it.
+ */
+export type OwnedRecordPlan = {
+    readonly kind: 'identity';
+    readonly target: Representation;
+} | {
+    readonly kind: 'arm';
+    readonly target: Representation;
+    readonly index: number;
+    readonly payload: OwnedRecordPlan;
+} | {
+    readonly kind: 'record';
+    readonly source: Extract<Representation, {
+        kind: 'record';
+    }>;
+    readonly target: Extract<Representation, {
+        kind: 'record' | 'native-record-ref';
+    }>;
+    readonly fields: readonly {
+        readonly key: string;
+        readonly value: OwnedRecordPlan;
+    }[];
+};
+/**
+ * An OWNED record (a value, not a handle) materialized as a refcounted or
+ * owned record of another shape, or as the one arm of a sum that shape fits:
+ * every field required on both sides and itself materializable.
+ */
+export declare const ownedRecordMaterializationPlan: (source: Representation, target: Representation, layouts: RecordLayoutPolicy) => OwnedRecordPlan | null;
+export type RecordViewSource = Extract<Representation, {
+    kind: 'record' | 'record-with-index' | 'native-record-ref' | 'class-ref';
+}>;
+export type RecordViewTarget = Extract<Representation, {
+    kind: 'record' | 'native-record-ref';
+}>;
+type TaggedUnion = Extract<Representation, {
+    kind: 'tagged-union';
+}>;
+/** Where one target field's value comes from. */
+export type RecordFieldRead = 
+/** A class method the target stores as a callable member: bound to the instance being viewed. */
+{
+    readonly kind: 'bound-method';
+}
+/**
+ * A class ACCESSOR the target stores as a plain field: read by calling the
+ * getter. `value` is the carrier the getter publishes, which the field is
+ * built from.
+ */
+ | {
+    readonly kind: 'class-accessor';
+    readonly value: Representation;
+}
+/** An optional field the source does not carry: default-constructed, presence false. */
+ | {
+    readonly kind: 'absent';
+}
+/** The source's own field, converted by the registry's pair answer. */
+ | {
+    readonly kind: 'held';
+    readonly held: RecordField;
+};
+export interface RecordFieldPlan {
+    readonly field: RecordField;
+    readonly read: RecordFieldRead;
+}
+/** One source arm's home in the target sum: the same carrier, a pair the registry converts, or a nested view. */
+export interface RecastArmPlan {
+    readonly index: number;
+    readonly via: 'exact' | 'convert' | RecordViewPlan;
+}
+export type RecordViewPlan = {
+    readonly kind: 'owned';
+    readonly plan: OwnedRecordPlan;
+}
+/** The one arm of a sum the source can become; `payload` null when the registry converts the pair without a view. */
+ | {
+    readonly kind: 'arm';
+    readonly source: Representation;
+    readonly target: TaggedUnion;
+    readonly index: number;
+    readonly payload: RecordViewPlan | null;
+} | {
+    readonly kind: 'optional';
+    readonly target: Extract<Representation, {
+        kind: 'optional';
+    }>;
+    readonly sourceOptional: boolean;
+    readonly payload: RecordViewPlan;
+}
+/**
+ * A `!`-asserted optional payload viewed onto a non-optional record-shaped
+ * target: the source carrier is still `optional(...)` (the checker's
+ * declared return type, e.g. `PropertyDescriptor | undefined`), but the
+ * language-level `!` erased it, so the target the binding actually needs is
+ * bare. `payload` is the view from the optional's payload onto `target`.
+ */
+ | {
+    readonly kind: 'assert';
+    readonly target: Extract<Representation, {
+        kind: 'record' | 'native-record-ref';
+    }>;
+    readonly payload: RecordViewPlan;
+} | {
+    readonly kind: 'recast-union';
+    readonly source: TaggedUnion;
+    readonly target: TaggedUnion;
+    readonly arms: readonly RecastArmPlan[];
+} | {
+    readonly kind: 'fields';
+    readonly source: RecordViewSource;
+    readonly target: RecordViewTarget;
+    readonly fields: readonly RecordFieldPlan[];
+    /** Index sidecars carried over, in the target's order. */
+    readonly indexes: readonly {
+        readonly target: RecordIndexSidecar;
+        readonly source: RecordIndexSidecar;
+    }[];
+    /** A string-keyed dynamic sidecar the source carries and the target's shape does not declare: re-attached, not dropped. */
+    readonly expando: boolean;
+};
+export type PairConvertible = (source: Representation, target: Representation) => boolean;
+/**
+ * Effects of an already-admitted view, not another conversion predicate.
+ * Copying a held carrier (including an already-dynamic cell) reads native
+ * storage directly. A converted field, bound method or expando needs its own
+ * transport contract before this view can dispense with dynamic field hooks.
+ */
+export declare const recordViewUsesOnlyDirectFields: (plan: RecordViewPlan) => boolean;
+export declare const structuralRecordViewPlan: (layouts: RecordLayoutPolicy, source: Representation, target: Representation, convertible: PairConvertible) => RecordViewPlan | null;
+export {};