@geastack/compiler 1.0.15

package/dist/representation/difference.d.ts

@@ -0,0 +1,30 @@
+import type { Representation } from './model.js';
+/**
+ * WHERE two carriers disagree, as a path a person can act on.
+ *
+ * A refusal that says only "writes a function-value-dispatch into a cell placed
+ * as function-value-dispatch, and no conversion is installed between them" names
+ * a contradiction rather than a defect: both sides print the same, so whatever
+ * differs is *inside* the carrier, and the message withheld the one fact that
+ * would say what to fix. The same is true one level up of the field-read
+ * refusal, whose two keys are printed in full and are then several hundred
+ * characters that differ in one nested position.
+ *
+ * So this walks the two carriers together and reports the FIRST position where
+ * they part, spelled as the path that reaches it -- `parameter 1 -> payload:
+ * record(type|2924,...) vs record#type|3604@4627...`. One position is enough:
+ * a carrier mismatch this compiler cannot convert is almost always one
+ * disagreement propagated upward by `nestedKey`'s digest, and a report that
+ * dumped every leaf would bury it.
+ *
+ * ⛔ Not a verdict, and never consulted to DECIDE anything. Two carriers that
+ * differ nowhere this walk can see still are not interchangeable -- the walk
+ * knows the shape of a carrier, not the semantics of a conversion -- so callers
+ * ask it only after they have already refused, to say why.
+ */
+export declare const carrierDifference: (left: Representation, right: Representation) => string;
+/**
+ * A one-line rendering of a carrier for a refusal message: the full key, capped,
+ * so a refusal stays readable next to the difference path that points into it.
+ */
+export declare const shortCarrierText: (representation: Representation) => string;

package/dist/representation/difference.js

@@ -0,0 +1,240 @@
+import { representationKey } from './model.js';
+/**
+ * WHERE two carriers disagree, as a path a person can act on.
+ *
+ * A refusal that says only "writes a function-value-dispatch into a cell placed
+ * as function-value-dispatch, and no conversion is installed between them" names
+ * a contradiction rather than a defect: both sides print the same, so whatever
+ * differs is *inside* the carrier, and the message withheld the one fact that
+ * would say what to fix. The same is true one level up of the field-read
+ * refusal, whose two keys are printed in full and are then several hundred
+ * characters that differ in one nested position.
+ *
+ * So this walks the two carriers together and reports the FIRST position where
+ * they part, spelled as the path that reaches it -- `parameter 1 -> payload:
+ * record(type|2924,...) vs record#type|3604@4627...`. One position is enough:
+ * a carrier mismatch this compiler cannot convert is almost always one
+ * disagreement propagated upward by `nestedKey`'s digest, and a report that
+ * dumped every leaf would bury it.
+ *
+ * ⛔ Not a verdict, and never consulted to DECIDE anything. Two carriers that
+ * differ nowhere this walk can see still are not interchangeable -- the walk
+ * knows the shape of a carrier, not the semantics of a conversion -- so callers
+ * ask it only after they have already refused, to say why.
+ */
+export const carrierDifference = (left, right) => {
+    const found = differenceAt(left, right, '', new Set());
+    if (found !== null)
+        return found;
+    // Structurally identical by this walk, yet the caller refused. That is worth
+    // saying out loud rather than papering over: it means the two carriers are
+    // distinct OBJECTS with equal shape, which is a monomorphization identity
+    // question, not a conversion one.
+    return `the two carriers differ in no position this walk can see; they are distinct objects of one shape`;
+};
+const differenceAt = (left, right, path, seen) => {
+    if (left === right)
+        return null;
+    const leftShallow = shallowSignature(left);
+    const rightShallow = shallowSignature(right);
+    if (leftShallow !== rightShallow)
+        return report(path, leftShallow, rightShallow);
+    // A carrier graph can be cyclic (`structural-self-reference.ts` closes the
+    // cycles that survive), and this pair has already been entered above.
+    const pair = `${path} :: ${leftShallow}`;
+    if (seen.has(pair))
+        return null;
+    seen.add(pair);
+    const leftChildren = children(left);
+    const rightChildren = children(right);
+    if (leftChildren.length !== rightChildren.length) {
+        return report(path, `${leftChildren.length} position(s)`, `${rightChildren.length} position(s)`);
+    }
+    for (const [index, entry] of leftChildren.entries()) {
+        const other = rightChildren[index];
+        if (other === undefined)
+            continue;
+        const [label, leftChild] = entry;
+        const found = differenceAt(leftChild, other[1], path === '' ? label : `${path} -> ${label}`, seen);
+        if (found !== null)
+            return found;
+    }
+    return null;
+};
+const report = (path, left, right) => `at ${path === '' ? 'the carrier itself' : path}: ${left} vs ${right}`;
+/**
+ * A carrier's OWN identity, with every nested carrier omitted.
+ *
+ * Everything `representationKey` folds in that is not a child: the kind, and
+ * the leaf attributes that make two carriers of that kind different things --
+ * a shape id, a declaration, an ownership, an absence tag, a protocol version.
+ * Comparing these before descending is what lets the walk say "at parameter 1
+ * -> payload" instead of reporting the whole subtree, and it is also what makes
+ * a difference in a leaf attribute (`record(type|2924)` vs `record(type|3038)`)
+ * a first-class answer rather than a silent equality.
+ */
+const shallowSignature = (representation) => {
+    switch (representation.kind) {
+        case 'unresolved':
+            return `unresolved(${representation.reason})`;
+        case 'callable-identity':
+        case 'void':
+        case 'string':
+        case 'symbol':
+        case 'null':
+        case 'undefined':
+            return representation.kind;
+        case 'scalar':
+            return `scalar(${representation.domain})`;
+        case 'class-ref':
+            return `class-ref(${representation.declaration},${representation.shapeId},${representation.ownership})`;
+        case 'native-handle':
+            return `native-handle(${representation.protocol}@${representation.version})`;
+        case 'record':
+            return (`record(${representation.shapeId},${representation.ownership},` +
+                `${representation.fields.map((field) => `${field.key}${field.required ? '' : '?'}`).join(',')};` +
+                `${representation.accessors.map((accessor) => `${accessor.key}=${accessor.getter ?? '-'}/${accessor.setter ?? '-'}`).join(',')})`);
+        case 'record-with-index':
+            return (`record-with-index(${representation.shapeId},${representation.ownership},` +
+                `${representation.fields.map((field) => `${field.key}${field.required ? '' : '?'}`).join(',')};` +
+                `${representation.indexes.map((index) => `index[${index.key}]`).join(',')})`);
+        case 'proxy-object':
+            return 'proxy-object';
+        case 'native-record-ref':
+            return `native-record-ref(${representation.shapeId},${representation.ownership},${representation.native ?? ''})`;
+        case 'borrowed-ref':
+            return 'borrowed-ref';
+        case 'array-object':
+            return `array-object(${representation.ownership})`;
+        case 'dense-buffer':
+            return 'dense-buffer';
+        case 'typed-array':
+            return `typed-array(${representation.element},${representation.buffer},${representation.ownership})`;
+        case 'array-buffer':
+            return `array-buffer(${representation.ownership})`;
+        case 'shared-array-buffer':
+            return `shared-array-buffer(${representation.ownership})`;
+        case 'data-view':
+            return `data-view(${representation.ownership})`;
+        case 'native-sequence':
+            return 'native-sequence';
+        case 'iterator':
+            return 'iterator';
+        case 'promise':
+            return 'promise';
+        case 'keyed-collection':
+            return `keyed-collection(${representation.family},${representation.ownership},${representation.value ? 'keyed' : 'set'})`;
+        case 'dictionary':
+            return `dictionary(${representation.key},${representation.ownership})`;
+        case 'function':
+            return `function(${representation.functionId},${abiSignature(representation.abi)})`;
+        case 'function-family':
+            return `function-family(${[...representation.members].sort().join('+')},${abiSignature(representation.abi)})`;
+        case 'constructor-family':
+            return `constructor-family(${[...representation.members].sort().join('+')},${abiSignature(representation.abi)})`;
+        case 'constructor-value-dispatch':
+            return `constructor-value-dispatch(${abiSignature(representation.abi)})`;
+        case 'function-and-constructor':
+            return `function-and-constructor(${abiSignature(representation.call)};${abiSignature(representation.construct)})`;
+        case 'function-value-family':
+            return (`function-value-family(${[...representation.members].sort().join('+')},` +
+                `${abiSignature(representation.abi)},${representation.optional})`);
+        case 'function-value-dispatch':
+            return `function-value-dispatch(${abiSignature(representation.abi)})`;
+        case 'generic-function-set':
+            return `generic-function-set(${representation.members.join('+')})`;
+        case 'optional':
+            return `optional(${representation.absence})`;
+        case 'tagged-union':
+            return `tagged-union(${representation.arms.map((arm) => arm.tag).join('|')})`;
+        case 'dynamic':
+            return `dynamic(${representation.reason})`;
+    }
+};
+/** An ABI's own identity: arity, ownerships, and where the rest slot starts. */
+const abiSignature = (abi) => `${abi.parameters.map((parameter) => parameter.ownership).join(',')}` +
+    `${abi.restFrom === null ? '' : `|rest@${abi.restFrom}`}${abi.receiver ? '+receiver' : ''}`;
+/**
+ * The nested carriers of one carrier, each with the name of the position it
+ * occupies. The order is fixed per kind, so two carriers with the same shallow
+ * signature always enumerate the same positions in the same order.
+ */
+const children = (representation) => {
+    switch (representation.kind) {
+        case 'callable-identity':
+        case 'unresolved':
+        case 'void':
+        case 'string':
+        case 'symbol':
+        case 'null':
+        case 'undefined':
+        case 'scalar':
+        case 'class-ref':
+        case 'typed-array':
+        case 'array-buffer':
+        case 'shared-array-buffer':
+        case 'data-view':
+        case 'dynamic':
+            return [];
+        case 'native-handle':
+            return [
+                ...(representation.call ? abiChildren('call', representation.call) : []),
+                ...(representation.construct ? abiChildren('construct', representation.construct) : [])
+            ];
+        case 'record':
+            return representation.fields.map((field) => [`field "${field.key}"`, field.value]);
+        case 'record-with-index':
+            return [
+                ...representation.fields.map((field) => [`field "${field.key}"`, field.value]),
+                ...representation.indexes.map((index) => [`${index.key} index`, index.value])
+            ];
+        case 'proxy-object':
+            return [['target', representation.target], ['handler', representation.handler]];
+        case 'native-record-ref':
+            return [];
+        case 'borrowed-ref':
+            return [['referent', representation.referent]];
+        case 'array-object':
+        case 'dense-buffer':
+        case 'native-sequence':
+        case 'iterator':
+            return [['element', representation.element]];
+        case 'promise':
+            return [['value', representation.value]];
+        case 'keyed-collection':
+            return [['key', representation.key], ...(representation.value ? [['value', representation.value]] : [])];
+        case 'dictionary':
+            return [['value', representation.value]];
+        case 'function':
+        case 'function-family':
+        case 'constructor-family':
+        case 'constructor-value-dispatch':
+        case 'function-value-family':
+        case 'function-value-dispatch':
+            return abiChildren('', representation.abi);
+        case 'function-and-constructor':
+            return [...abiChildren('call', representation.call), ...abiChildren('construct', representation.construct)];
+        case 'optional':
+            return [['payload', representation.payload]];
+        case 'tagged-union':
+            return representation.arms.map((arm) => [`arm "${arm.tag}"`, arm.value]);
+        case 'generic-function-set':
+            return [];
+    }
+};
+const abiChildren = (prefix, abi) => {
+    const at = (label) => (prefix === '' ? label : `${prefix} ${label}`);
+    return [
+        ...(abi.receiver ? [[at('receiver'), abi.receiver]] : []),
+        ...abi.parameters.map((parameter, index) => [at(`parameter ${index}`), parameter.value]),
+        [at('result'), abi.result]
+    ];
+};
+/**
+ * A one-line rendering of a carrier for a refusal message: the full key, capped,
+ * so a refusal stays readable next to the difference path that points into it.
+ */
+export const shortCarrierText = (representation) => {
+    const key = representationKey(representation);
+    return key.length <= 160 ? key : `${key.slice(0, 157)}...`;
+};

package/dist/representation/field-descriptor-policy.d.ts

@@ -0,0 +1,19 @@
+import type { Representation } from './model.js';
+/**
+ * The source-level absence admissions a native dynamic-field descriptor
+ * adapter must preserve. A native Optional has one absence bit, so an outer
+ * Optional around another absence-bearing carrier is deliberately unsupported
+ * here: lowering it without a recursive policy could collapse two distinct
+ * source states. Tagged unions retain their arm discriminator and can publish
+ * direct absence arms safely.
+ */
+export interface DynamicFieldAbsencePolicy {
+    readonly allowsNull: boolean;
+    readonly allowsUndefined: boolean;
+}
+/**
+ * Describe the null/undefined admissions of a representation tree, or return
+ * null when the tree needs a richer recursive policy and must remain on the
+ * existing descriptor route.
+ */
+export declare const dynamicFieldAbsencePolicy: (representation: Representation) => DynamicFieldAbsencePolicy | null;

package/dist/representation/field-descriptor-policy.js

@@ -0,0 +1,39 @@
+/**
+ * Describe the null/undefined admissions of a representation tree, or return
+ * null when the tree needs a richer recursive policy and must remain on the
+ * existing descriptor route.
+ */
+export const dynamicFieldAbsencePolicy = (representation) => {
+    switch (representation.kind) {
+        case 'optional': {
+            if (representation.payload.kind === 'optional')
+                return null;
+            const nested = dynamicFieldAbsencePolicy(representation.payload);
+            if (nested === null || nested.allowsNull || nested.allowsUndefined)
+                return null;
+            return { allowsNull: representation.absence === 'null', allowsUndefined: representation.absence === 'undefined' };
+        }
+        case 'tagged-union': {
+            let allowsNull = false;
+            let allowsUndefined = false;
+            for (const arm of representation.arms) {
+                if (arm.value.kind === 'optional' && arm.value.absence === 'null')
+                    return null;
+                const nested = dynamicFieldAbsencePolicy(arm.value);
+                if (nested === null)
+                    return null;
+                allowsNull = allowsNull || nested.allowsNull;
+                allowsUndefined = allowsUndefined || nested.allowsUndefined;
+            }
+            return { allowsNull, allowsUndefined };
+        }
+        case 'undefined':
+            return { allowsNull: false, allowsUndefined: true };
+        case 'null':
+            return { allowsNull: true, allowsUndefined: false };
+        case 'dynamic':
+            return null;
+        default:
+            return { allowsNull: false, allowsUndefined: false };
+    }
+};

package/dist/representation/function-constructor.d.ts

@@ -0,0 +1,13 @@
+import type { Representation } from './model.js';
+/**
+ * The only argument carriers the Function constructor can transport without
+ * turning a native value into the dynamic evaluator carrier. A string is
+ * already its own ToString result; a dynamic value is already owned by the
+ * evaluator boundary and must retain its runtime coercion behaviour.
+ */
+export type FunctionConstructorArgumentKind = 'native-string' | 'dynamic-value';
+/**
+ * This is a generic ECMAScript boundary, not a guessed callable ABI. The
+ * returned Function remains dynamic because its source controls its frame.
+ */
+export declare const functionConstructorArgumentKindOf: (representation: Representation) => FunctionConstructorArgumentKind | null;

package/dist/representation/function-constructor.js

@@ -0,0 +1,9 @@
+/**
+ * This is a generic ECMAScript boundary, not a guessed callable ABI. The
+ * returned Function remains dynamic because its source controls its frame.
+ */
+export const functionConstructorArgumentKindOf = (representation) => {
+    if (representation.kind === 'string')
+        return 'native-string';
+    return representation.kind === 'dynamic' ? 'dynamic-value' : null;
+};

package/dist/representation/host-abi.d.ts

@@ -0,0 +1,32 @@
+import type { CallableAbi } from './model.js';
+/**
+ * The convention that subsumes every ABI in a host handle's own overload set,
+ * when one exists.
+ *
+ * `derive.ts`'s `sharedAbiOf` requires every overload to share one identical
+ * frame, which is correct for an ordinary program-defined callable: a caller
+ * reaching one overload through another's frame passes the wrong arguments.
+ * A host handle's overload set is commonly shaped differently: TypeScript's
+ * own `ErrorConstructor` carries `new(message?: string): Error` from
+ * `lib.es5.d.ts` AND `new(message?: string, options?: ErrorOptions): Error`
+ * from `lib.es2022.error.d.ts`'s declaration merge, kept side by side rather
+ * than replaced. These are not two incompatible frames -- they are one frame
+ * with a trailing optional parameter, spelled as two overloads instead of
+ * one signature -- so the WIDEST overload's own ABI already accepts every
+ * call the narrower ones do: an absent trailing optional argument is exactly
+ * what a shorter call site passes. The join is position-wise: at each slot
+ * every overload must carry the same representation, except that one may
+ * spell it optional (or, past its own length, omit it) where another
+ * requires it, and the joined slot is then the optional one; the results
+ * must agree, and no overload may have a receiver or a rest parameter. A
+ * genuine incompatibility -- a different parameter type at a shared
+ * position, not just a different presence -- still refuses: this is a
+ * widening test, never a coercion this layer invents.
+ *
+ * A refusal is returned as the REASON rather than as `null`, because
+ * "no primitive joining 4 overload signatures into one calling convention"
+ * names a count and not a defect: four different walls read as one family and
+ * the next lever cannot be ranked from it. The reason text is deliberately
+ * short and free of carrier keys so equal walls group together.
+ */
+export declare const widestSubsumingAbi: (abis: readonly CallableAbi[]) => CallableAbi | string;

package/dist/representation/host-abi.js

@@ -0,0 +1,97 @@
+import { passingOf, representationKey } from './model.js';
+import { optionalOf } from './optional.js';
+/**
+ * The convention that subsumes every ABI in a host handle's own overload set,
+ * when one exists.
+ *
+ * `derive.ts`'s `sharedAbiOf` requires every overload to share one identical
+ * frame, which is correct for an ordinary program-defined callable: a caller
+ * reaching one overload through another's frame passes the wrong arguments.
+ * A host handle's overload set is commonly shaped differently: TypeScript's
+ * own `ErrorConstructor` carries `new(message?: string): Error` from
+ * `lib.es5.d.ts` AND `new(message?: string, options?: ErrorOptions): Error`
+ * from `lib.es2022.error.d.ts`'s declaration merge, kept side by side rather
+ * than replaced. These are not two incompatible frames -- they are one frame
+ * with a trailing optional parameter, spelled as two overloads instead of
+ * one signature -- so the WIDEST overload's own ABI already accepts every
+ * call the narrower ones do: an absent trailing optional argument is exactly
+ * what a shorter call site passes. The join is position-wise: at each slot
+ * every overload must carry the same representation, except that one may
+ * spell it optional (or, past its own length, omit it) where another
+ * requires it, and the joined slot is then the optional one; the results
+ * must agree, and no overload may have a receiver or a rest parameter. A
+ * genuine incompatibility -- a different parameter type at a shared
+ * position, not just a different presence -- still refuses: this is a
+ * widening test, never a coercion this layer invents.
+ *
+ * A refusal is returned as the REASON rather than as `null`, because
+ * "no primitive joining 4 overload signatures into one calling convention"
+ * names a count and not a defect: four different walls read as one family and
+ * the next lever cannot be ranked from it. The reason text is deliberately
+ * short and free of carrier keys so equal walls group together.
+ */
+export const widestSubsumingAbi = (abis) => {
+    const first = abis[0];
+    if (!first)
+        return 'the set is empty';
+    if (abis.some((abi) => abi.receiver !== null))
+        return 'an overload declares a receiver';
+    if (abis.some((abi) => abi.restFrom !== null))
+        return 'an overload is variadic';
+    const resultKey = representationKey(first.result);
+    if (abis.some((abi) => representationKey(abi.result) !== resultKey))
+        return 'the overloads disagree about the result';
+    const length = Math.max(...abis.map((abi) => abi.parameters.length));
+    const parameters = [];
+    for (let position = 0; position < length; position += 1) {
+        // The one carrier every overload agrees on at this position, widened to
+        // its optional form when any overload spells it optional -- or omits it,
+        // since a shorter overload's absent trailing parameter is the same
+        // "the caller did not supply it" the optional carrier already holds.
+        // `test: (node: Node) => node is TOut` beside `test?: (node: Node) =>
+        // boolean` (TypeScript's own `NodeVisitor`) is one slot, not two frames:
+        // every call through the set that omits it reaches the value through the
+        // optional slot, and every call that passes it fills the same slot.
+        let joined = null;
+        let omitted = false;
+        for (const abi of abis) {
+            const own = abi.parameters[position];
+            if (own === undefined) {
+                omitted = true;
+                continue;
+            }
+            if (joined === null || sameCarrier(own.value, joined.value)) {
+                joined ??= own;
+                continue;
+            }
+            if (widensTo(joined.value, own.value)) {
+                joined = own;
+                continue;
+            }
+            if (!widensTo(own.value, joined.value))
+                return `the overloads disagree at parameter ${position}`;
+        }
+        if (joined === null)
+            return `parameter ${position} is declared by no overload`;
+        // A position some overload OMITS is optional in the physical sense even
+        // where the overload that declares it spells it required. The set is one
+        // runtime function and the declaration itself says a call without this
+        // argument is legal, so the convention that holds both calls is the
+        // widened one -- `realpathSync(path)` beside `realpathSync(path, options)`
+        // is node's own spelling of a single entry point, and refusing it left
+        // every value read of such a set with no calling convention at all (288
+        // rows in tsc's self-compile, concentrated in `sys.ts`, `checker.ts` and
+        // `tracing.ts`). Only the ARITY widens: every shared position must already
+        // agree, and so must the result, which the checks above enforce.
+        if (omitted && joined.value.kind !== 'optional') {
+            const widened = optionalOf(joined.value, 'undefined');
+            parameters.push(widened === joined.value ? joined : { value: widened, ownership: 'owned', passing: passingOf(widened, 'owned') });
+            continue;
+        }
+        parameters.push(joined);
+    }
+    return { ...first, parameters };
+};
+const sameCarrier = (left, right) => representationKey(left) === representationKey(right);
+/** Whether `wider` is exactly `narrower` behind an optional -- the one widening this layer admits. */
+const widensTo = (narrower, wider) => wider.kind === 'optional' && wider.absence === 'undefined' && sameCarrier(wider.payload, narrower);

package/dist/representation/host-templates.d.ts

@@ -0,0 +1,67 @@
+import type { Representation } from './model.js';
+/**
+ * The host templates whose native frame the IR states
+ * (`ir/call-entry.ts`'s `hostTemplateFrameOf`), and the one authority for when
+ * the printer spells a call from one of them and what each accepts.
+ *
+ * Every predicate here has exactly two kinds of caller: the C++ printer, which
+ * routes a call to the template and renders it (`emit-host-properties.ts`'s
+ * `hostMemberReadsOf`, `emit-host-invoke.ts`'s `isArrayText`,
+ * `emit-host-object.ts`'s `objectMemberText`, `emit-buffers.ts`'s
+ * `typedArrayCallText`), and the IR, which records the template on the call
+ * (`ir/lower-invocation.ts`) and states its frame. A rule that lived on only
+ * one side could drift from the other, and the frame would then describe C++
+ * the printer no longer emits.
+ */
+export type HostTemplate = 'object-assign' | 'array-is-array' | 'typed-array-set';
+/**
+ * The host protocol a member read off this receiver is looked up on, or `null`.
+ *
+ * A non-null native name can only enter a `native-record-ref` through the
+ * declaration-authenticated host-type seam. The compiler does not lay that
+ * record out, so a host member table is the only authority allowed to spell
+ * one of its properties.
+ */
+export declare const hostReceiverProtocolOf: (representation: Representation) => {
+    readonly protocol: string;
+    readonly strict: boolean;
+} | null;
+/**
+ * Whether a host method read whose row is spelled at the call site is deferred
+ * to that call. A read held `dynamic` has no native convention to fuse with and
+ * is boxed as a function value instead (`dynamicHostFunctionValueText`).
+ */
+export declare const callSiteHostReadIsDeferred: (read: Representation) => boolean;
+/** The template a deferred host member's call is spelled from, for the members this file names. */
+export declare const hostMemberTemplateOf: (protocol: string, member: string) => HostTemplate | null;
+/** A union whose every arm is a typed array: one `%TypedArray%.prototype` receiver whose arm the invoker dispatches. */
+export declare const typedArrayUnionOnly: (representation: Representation) => boolean;
+/** The template a deferred `%TypedArray%.prototype` member's call is spelled from, for the members this file names. */
+export declare const typedArrayMemberTemplateOf: (member: string) => HostTemplate | null;
+/**
+ * Which template here prints a call through `member` read off `receiver`, the
+ * read itself held as `read`; `null` for every other call.
+ *
+ * The receiver is the read's proven-present view, as both deferral walks take
+ * it: an `optional` receiver's payload.
+ */
+export declare const hostTemplateOfRead: (receiver: Representation, member: string, read: Representation) => HostTemplate | null;
+/**
+ * What `Array.isArray` -- ECMA-262 23.1.2.2 -- answers for a carrier of this
+ * kind from the kind alone, or `null` for a kind that states neither that it is
+ * an Array nor that it cannot be one (`dynamic`, whose box carries the answer,
+ * and the wrappers `optional`/`tagged-union`, answered per state and per arm).
+ *
+ * `false` is stated by KIND rather than as a default, so a carrier nobody has
+ * thought about refuses instead of being answered wrongly. A typed array is
+ * one of the `false`s on purpose: a `Uint8Array` is not an Array exotic object.
+ */
+export declare const isArrayConstantOf: (kind: Representation["kind"]) => boolean | null;
+/**
+ * A single `%TypedArray%.prototype.set` source: a typed array, read through its
+ * own element type, or an Array of numbers, whose holes read as `undefined`
+ * (ECMA-262 23.2.3.26 steps 5 and 6). `null` for anything else.
+ */
+export declare const typedArraySetSourceOf: (carrier: Representation) => "typed-array" | "number-array" | null;
+/** Whether `set` copies from this source: a single source, or a union whose every arm is one. */
+export declare const typedArraySetSourceAccepted: (carrier: Representation) => boolean;

package/dist/representation/host-templates.js

@@ -0,0 +1,94 @@
+/**
+ * The host protocol a member read off this receiver is looked up on, or `null`.
+ *
+ * A non-null native name can only enter a `native-record-ref` through the
+ * declaration-authenticated host-type seam. The compiler does not lay that
+ * record out, so a host member table is the only authority allowed to spell
+ * one of its properties.
+ */
+export const hostReceiverProtocolOf = (representation) => {
+    if (representation.kind === 'native-handle')
+        return { protocol: representation.native ?? representation.protocol, strict: true };
+    if (representation.kind === 'native-record-ref' && representation.native !== null)
+        return { protocol: representation.native, strict: false };
+    return null;
+};
+/**
+ * Whether a host method read whose row is spelled at the call site is deferred
+ * to that call. A read held `dynamic` has no native convention to fuse with and
+ * is boxed as a function value instead (`dynamicHostFunctionValueText`).
+ */
+export const callSiteHostReadIsDeferred = (read) => read.kind !== 'dynamic';
+/** The template a deferred host member's call is spelled from, for the members this file names. */
+export const hostMemberTemplateOf = (protocol, member) => protocol === 'ArrayConstructor' && member === 'isArray'
+    ? 'array-is-array'
+    : protocol === 'ObjectConstructor' && member === 'assign'
+        ? 'object-assign'
+        : null;
+/** A union whose every arm is a typed array: one `%TypedArray%.prototype` receiver whose arm the invoker dispatches. */
+export const typedArrayUnionOnly = (representation) => representation.kind === 'tagged-union' && representation.arms.every((arm) => arm.value.kind === 'typed-array');
+/** The template a deferred `%TypedArray%.prototype` member's call is spelled from, for the members this file names. */
+export const typedArrayMemberTemplateOf = (member) => (member === 'set' ? 'typed-array-set' : null);
+/**
+ * Which template here prints a call through `member` read off `receiver`, the
+ * read itself held as `read`; `null` for every other call.
+ *
+ * The receiver is the read's proven-present view, as both deferral walks take
+ * it: an `optional` receiver's payload.
+ */
+export const hostTemplateOfRead = (receiver, member, read) => {
+    const present = receiver.kind === 'optional' ? receiver.payload : receiver;
+    const host = hostReceiverProtocolOf(present);
+    if (host !== null)
+        return callSiteHostReadIsDeferred(read) ? hostMemberTemplateOf(host.protocol, member) : null;
+    return present.kind === 'typed-array' || typedArrayUnionOnly(present) ? typedArrayMemberTemplateOf(member) : null;
+};
+/** The kinds `Array.isArray` answers `false` for from the kind alone: each states it is not an Array exotic object. */
+const notArrayKinds = new Set([
+    'record',
+    'record-with-index',
+    'dictionary',
+    'class-ref',
+    'native-record-ref',
+    'native-handle',
+    'keyed-collection',
+    'dense-buffer',
+    'typed-array',
+    'array-buffer',
+    'shared-array-buffer',
+    'data-view',
+    'promise',
+    'scalar',
+    'string',
+    'symbol',
+    'null',
+    'undefined',
+    'function',
+    'function-family',
+    'function-value-family',
+    'function-value-dispatch'
+]);
+/**
+ * What `Array.isArray` -- ECMA-262 23.1.2.2 -- answers for a carrier of this
+ * kind from the kind alone, or `null` for a kind that states neither that it is
+ * an Array nor that it cannot be one (`dynamic`, whose box carries the answer,
+ * and the wrappers `optional`/`tagged-union`, answered per state and per arm).
+ *
+ * `false` is stated by KIND rather than as a default, so a carrier nobody has
+ * thought about refuses instead of being answered wrongly. A typed array is
+ * one of the `false`s on purpose: a `Uint8Array` is not an Array exotic object.
+ */
+export const isArrayConstantOf = (kind) => kind === 'array-object' ? true : notArrayKinds.has(kind) ? false : null;
+/**
+ * A single `%TypedArray%.prototype.set` source: a typed array, read through its
+ * own element type, or an Array of numbers, whose holes read as `undefined`
+ * (ECMA-262 23.2.3.26 steps 5 and 6). `null` for anything else.
+ */
+export const typedArraySetSourceOf = (carrier) => carrier.kind === 'typed-array'
+    ? 'typed-array'
+    : carrier.kind === 'array-object' && carrier.element.kind === 'scalar' && carrier.element.domain === 'number'
+        ? 'number-array'
+        : null;
+/** Whether `set` copies from this source: a single source, or a union whose every arm is one. */
+export const typedArraySetSourceAccepted = (carrier) => typedArraySetSourceOf(carrier) !== null ||
+    (carrier.kind === 'tagged-union' && carrier.arms.every((arm) => typedArraySetSourceOf(arm.value) !== null));