@geastack/compiler 1.0.16 → 1.0.18

package/dist/plugins/host-package.js

@@ -0,0 +1,28 @@
+import { createRequire } from 'node:module';
+const absent = (error) => error.code === 'MODULE_NOT_FOUND';
+export const createHostPackageLoader = (ownUrl) => {
+    const own = createRequire(ownUrl);
+    let adopted = null;
+    const attempt = (run) => {
+        const bases = adopted === null ? [own] : [adopted, own];
+        let missing = null;
+        for (const base of bases) {
+            try {
+                return run(base);
+            }
+            catch (error) {
+                if (!absent(error))
+                    throw error;
+                missing = error;
+            }
+        }
+        throw missing;
+    };
+    return {
+        load: (specifier) => attempt((base) => base(specifier)),
+        resolve: (specifier) => attempt((base) => base.resolve(specifier)),
+        adopt: (file) => {
+            adopted = createRequire(file);
+        }
+    };
+};

package/dist/plugins/load.js

@@ -4,6 +4,12 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { installedPlugins } from './installed.js';
 import { noPluginCapabilities } from './model.js';
+import { adoptApplePackage } from './apple/host.js';
+import { applePlugin } from './apple/plugin.js';
+import { adoptGeaPackage } from './gea/host.js';
+import { geaPlugin } from './gea/plugin.js';
+import { adoptWebglPackage } from './webgl/host.js';
+import { webglPlugin } from './webgl/plugin.js';
 const isRecord = (value) => typeof value === 'object' && value !== null;
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
 const resolvePlugin = (specifier) => {
@@ -172,6 +178,15 @@ export const loadCliPlugins = async (specifiers) => {
                 const adapter = typeof plugin['configure'] === 'function' ? await legacyAdapter(file, name, exported) : undefined;
                 if (!adapter)
                     throw new Error(`plugin "${name}" is incompatible: expected instantiate(options); legacy hooks are not supported`);
+                // The adapter's tables come from the package's own statement, and the
+                // statement must be the package this path names -- not the copy the
+                // compiler's own `node_modules` happens to hold (`host-package.ts`).
+                if (adapter === webglPlugin)
+                    adoptWebglPackage(file);
+                else if (adapter === geaPlugin)
+                    adoptGeaPackage(file);
+                else if (adapter === applePlugin)
+                    adoptApplePackage(file);
                 process.stderr.write(`compile: --plugin ${specifier}: using built-in "${adapter.name}" adapter for the legacy package\n`);
                 loadedPaths.add(file);
                 continue;

package/dist/plugins/webgl/host.d.ts

@@ -1,5 +1,7 @@
 import type { AmbientTypeRealization } from '../../semantics/ambient-type-realization-transform.js';
 import type { PluginSourceFile } from '../model.js';
+/** The package entry the CLI loaded is the one this host's tables come from -- see `plugins/host-package.ts`. */
+export declare const adoptWebglPackage: (file: string) => void;
 /**
  * The ambient free functions this host defines, to the C++ each is.
  *
@@ -54,10 +56,14 @@ export declare const webglSourceTransform: (input: PluginSourceFile) => string |
  *   for programs that use it to detect WebGL 2. The WebGL 1 constructor is
  *   absent: this host only creates NativeWebGL2RenderingContext. In three's
  *   WebGL 1 rejection guard, absence correctly skips the rejected path.
- * - `self`, `postMessage`, `importScripts`: worker globals, and whether this
- *   target has workers is not a fact about its GL context.
+ * - `postMessage`, `importScripts`: worker globals, and whether this target
+ *   has workers is not a fact about its GL context. `self` IS stated -- by the
+ *   package, in its own `absentGlobals` -- because the package ships the
+ *   `self`-less animation driver three's renderer is aliased to
+ *   (`nativeWebGLAnimation.ts`): the one fact the package does know about
+ *   `self` is that three's only use of it has already been answered natively.
  */
-export declare const webglAbsentGlobals: ReadonlySet<string>;
+export declare const webglAbsentGlobals: () => ReadonlySet<string>;
 /**
  * The ambient WebGL context names three's own source (and `@types/three`'s
  * mirrored declarations) states, to the concrete class

package/dist/plugins/webgl/host.js

@@ -1,5 +1,5 @@
-import { createRequire } from 'node:module';
-const require_ = createRequire(import.meta.url);
+import { createHostPackageLoader } from '../host-package.js';
+const packageLoader = createHostPackageLoader(import.meta.url);
 let loaded;
 /**
  * The package's own statement, loaded once.
@@ -18,7 +18,7 @@ const shims = () => {
     const specifier = requested ?? '@geastack/native-webgl-angle/geatsc-plugin';
     let module_;
     try {
-        module_ = require_(specifier);
+        module_ = packageLoader.load(specifier);
     }
     catch (error) {
         const absent = error.code === 'MODULE_NOT_FOUND';
@@ -39,6 +39,11 @@ const shims = () => {
     loaded = configured;
     return configured;
 };
+/** The package entry the CLI loaded is the one this host's tables come from -- see `plugins/host-package.ts`. */
+export const adoptWebglPackage = (file) => {
+    packageLoader.adopt(file);
+    loaded = undefined;
+};
 /**
  * The ambient free functions this host defines, to the C++ each is.
  *
@@ -108,10 +113,14 @@ export const webglSourceTransform = (input) => shims()?.transformSource?.(input)
  *   for programs that use it to detect WebGL 2. The WebGL 1 constructor is
  *   absent: this host only creates NativeWebGL2RenderingContext. In three's
  *   WebGL 1 rejection guard, absence correctly skips the rejected path.
- * - `self`, `postMessage`, `importScripts`: worker globals, and whether this
- *   target has workers is not a fact about its GL context.
+ * - `postMessage`, `importScripts`: worker globals, and whether this target
+ *   has workers is not a fact about its GL context. `self` IS stated -- by the
+ *   package, in its own `absentGlobals` -- because the package ships the
+ *   `self`-less animation driver three's renderer is aliased to
+ *   (`nativeWebGLAnimation.ts`): the one fact the package does know about
+ *   `self` is that three's only use of it has already been answered natively.
  */
-export const webglAbsentGlobals = new Set([
+export const webglAbsentGlobals = () => new Set([
     ...(shims()?.absentGlobals ?? []),
     'WebGLRenderingContext',
     'ImageData',

package/dist/plugins/webgl/plugin.js

@@ -65,7 +65,10 @@ export const webglPlugin = {
             hostNamespaceRootTypes: new Map(),
             hostSingletons: new Set(),
             hostSingletonsByDeclaration: new Map(),
-            absentGlobals: webglAbsentGlobals,
+            // Read at instantiate, never at import: the package's statement is the
+            // one `plugins/load.ts` adopted from `--plugin`, and adoption happens
+            // after this module is loaded.
+            absentGlobals: webglAbsentGlobals(),
             hostPreambles: webglHostPreambles(),
             nativeBases: new Map(),
             // Declarations arrive per spelling through `hostPreambles`, not per

package/dist/representation/embedded-carriers.d.ts

@@ -0,0 +1,22 @@
+import type { Representation } from './model.js';
+/**
+ * Every carrier a representation embeds, visited once each, depth first.
+ *
+ * A carrier is not only its own kind: a `record` renders as a struct whose
+ * every field is a carrier of its own, a `tagged-union` as an alternative of
+ * each arm's, a callable as a signature spelling each parameter's. What the
+ * emitted C++ names is the whole tree, so a fact that must hold of every
+ * carrier the program spells -- that a `native-handle` names a protocol the
+ * host registered -- has to be asked of the whole tree, not of its root. A
+ * census that stopped at the root let lib.dom's `Window` reach clang as a
+ * struct whose `Navigator`/`History`/`ScreenOrientation` fields named tag
+ * types no host had declared: a certified program that did not compile.
+ *
+ * The walk mirrors what the backend renders (`targets/cpp/records.ts`'s
+ * `visitRepresentation`): `native-record-ref` names a struct defined
+ * elsewhere and carries no fields, `class-ref` names a class whose layout
+ * is censused with the class, and a callable contributes its ABI carriers.
+ * A representation tree is finite -- recursion is broken by
+ * `native-record-ref` -- but each node is visited once regardless.
+ */
+export declare const forEachEmbeddedRepresentation: (root: Representation, visit: (carrier: Representation) => void) => void;

package/dist/representation/embedded-carriers.js

@@ -0,0 +1,105 @@
+/**
+ * Every carrier a representation embeds, visited once each, depth first.
+ *
+ * A carrier is not only its own kind: a `record` renders as a struct whose
+ * every field is a carrier of its own, a `tagged-union` as an alternative of
+ * each arm's, a callable as a signature spelling each parameter's. What the
+ * emitted C++ names is the whole tree, so a fact that must hold of every
+ * carrier the program spells -- that a `native-handle` names a protocol the
+ * host registered -- has to be asked of the whole tree, not of its root. A
+ * census that stopped at the root let lib.dom's `Window` reach clang as a
+ * struct whose `Navigator`/`History`/`ScreenOrientation` fields named tag
+ * types no host had declared: a certified program that did not compile.
+ *
+ * The walk mirrors what the backend renders (`targets/cpp/records.ts`'s
+ * `visitRepresentation`): `native-record-ref` names a struct defined
+ * elsewhere and carries no fields, `class-ref` names a class whose layout
+ * is censused with the class, and a callable contributes its ABI carriers.
+ * A representation tree is finite -- recursion is broken by
+ * `native-record-ref` -- but each node is visited once regardless.
+ */
+export const forEachEmbeddedRepresentation = (root, visit) => {
+    const seen = new Set([root]);
+    const abi = (value) => {
+        if (value === null)
+            return;
+        for (const parameter of value.parameters)
+            walk(parameter.value);
+        walk(value.result);
+        if (value.receiver !== null)
+            walk(value.receiver);
+    };
+    const walk = (value) => {
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        visit(value);
+        children(value);
+    };
+    const children = (value) => {
+        switch (value.kind) {
+            case 'record':
+                for (const field of value.fields)
+                    walk(field.value);
+                for (const accessor of value.accessors)
+                    walk(accessor.value);
+                return;
+            case 'record-with-index':
+                for (const field of value.fields)
+                    walk(field.value);
+                for (const index of value.indexes)
+                    walk(index.value);
+                return;
+            case 'proxy-object':
+                walk(value.target);
+                walk(value.handler);
+                return;
+            case 'borrowed-ref':
+                walk(value.referent);
+                return;
+            case 'array-object':
+            case 'dense-buffer':
+            case 'native-sequence':
+                walk(value.element);
+                return;
+            case 'iterator':
+                walk(value.element);
+                walk(value.resume);
+                walk(value.completion);
+                return;
+            case 'promise':
+                walk(value.value);
+                return;
+            case 'keyed-collection':
+                walk(value.key);
+                if (value.value !== null)
+                    walk(value.value);
+                return;
+            case 'dictionary':
+                walk(value.value);
+                return;
+            case 'optional':
+                walk(value.payload);
+                return;
+            case 'tagged-union':
+                for (const arm of value.arms)
+                    walk(arm.value);
+                return;
+            case 'function':
+            case 'function-family':
+            case 'constructor-family':
+            case 'constructor-value-dispatch':
+            case 'function-value-family':
+            case 'function-value-dispatch':
+                abi(value.abi);
+                return;
+            case 'function-and-constructor':
+                abi(value.call);
+                abi(value.construct);
+                return;
+            default:
+                return;
+        }
+    };
+    children(root);
+};

package/dist/semantics/model/operands.d.ts

@@ -98,6 +98,23 @@ export interface SemanticOperand {
      * (`spread-arguments.ts`). Absent means 0, the whole source.
      */
     readonly from?: number;
+    /**
+     * The program's own type assertion (`x as T`, `<T>x`) wraps the expression
+     * this operand cites. The assertion is erased -- it evaluates nothing and
+     * changes no value, which is why the operand cites the wrapped expression's
+     * result and carries its type -- but it is also the author STATING which
+     * arm of a union the value holds here, the same promise `@gea-exact-arms`
+     * makes for a whole body (`ConversionRoleTarget.owner`'s `exact-arm`). A
+     * lowering that must put the value into a slot that is exactly one arm of
+     * its union, and that the census has no sound per-arm answer for, may take
+     * the stated arm -- checked at runtime, a `TypeError` when the assertion
+     * was false. hono's `Context.executionCtx` returns `this.#executionCtx as
+     * ExecutionContext` off a `FetchEventLike | ExecutionContext` field: the
+     * class arm has no view as the interface, so without the assertion the
+     * store is refused, and with it the store is the projection the author
+     * wrote. An assertion to `any`/`unknown` states no arm and is not marked.
+     */
+    readonly asserted?: true;
 }
 /** One result an operation publishes, keyed by the role it fills. */
 export interface SemanticResult {

package/dist/semantics/model/operations.d.ts

@@ -17,7 +17,17 @@ import type { HostMethodBinding } from '../host-methods.js';
 export interface ConversionRoleTarget {
     readonly role: string;
     readonly ordinal: number;
-    readonly owner: 'parameter-slot' | 'array-element' | 'declared-field';
+    /**
+     * `exact-arm` is the caller's half of `AllocationOperation.exactArms`: for
+     * an argument into an `@gea-exact-arms` implementation, `type` is the
+     * parameter type of the overload the checker RESOLVED, not the
+     * implementation's union slot the `parameter-slot` role names. The lowering
+     * enters that arm of the union and no other, so the arm the body projects
+     * is the arm the checker chose -- without it a `() => 2` under `Typed |
+     * Generic` widens into whichever arm can adapt it first, and the body's
+     * projection then throws on a call the checker accepted.
+     */
+    readonly owner: 'parameter-slot' | 'array-element' | 'declared-field' | 'exact-arm';
     readonly type: StructuralTypeId;
 }
 /**
@@ -311,6 +321,23 @@ export interface AllocationOperation extends SemanticOperationBase {
      * the same condition as `functionSource`.
      */
     readonly generatorFunction?: boolean;
+    /**
+     * Whether the declaration carries `@gea-exact-arms`: inside this body, a
+     * tagged-union value entering a slot that is EXACTLY one of its arms
+     * projects that arm and throws a `TypeError` on any other, instead of the
+     * per-arm dispatch that converts every arm into the target.
+     *
+     * A fact of the declaration because the checker cannot state it. TS
+     * function assignability makes any two callable arms convertible in at
+     * least one direction, so `fn as RequestListener` over `EventHandler |
+     * RequestListener` always installs an adapter for the catch-all arm -- and
+     * that adapter publishes the typed arm's parameters to a dynamic listener,
+     * which is precisely what an overload implementation keeping typed and
+     * generic listeners in separate storage never does. Only the author knows
+     * the branch guarding the cast makes the other arms unreachable, so the
+     * author states it, per body, and pays with a runtime check.
+     */
+    readonly exactArms?: boolean;
     /**
      * Whether the declaration performs ECMA-262 10.2.5 `MakeConstructor` and so
      * owns a `prototype` object -- true for an ordinary `function` declaration

package/dist/semantics/normalize/producers/allocations.js

@@ -1,6 +1,7 @@
 import ts from 'typescript';
 import { operationId, semanticResultId } from '../../../identity/ids.js';
 import { bindingKindOf } from './binding-kind.js';
+import { declaresExactArms } from './exact-arms.js';
 import { blocked, mintOperationId, mintResult, operand } from './mint.js';
 import { citeExpressionResult } from './references.js';
 import { sourceForValue, valueEdgesInto, hasNativeIterationCursor, staticPropertyKeyTextOf, isRuntimeSymbolMember, staticSpreadMembersOf, staticFunctionNameOf, staticClassNameOf, staticClassLengthOf, expectedParameterCountOf, ownPrototypePropertyOf } from './shared.js';
@@ -797,6 +798,7 @@ export const createAllocationProducer = (context) => ({
                     functionName: staticFunctionNameOf(node),
                     functionLength: expectedParameterCountOf(node),
                     generatorFunction: 'asteriskToken' in node && node.asteriskToken !== undefined,
+                    ...(declaresExactArms(node) ? { exactArms: true } : {}),
                     ...(ownPrototypePropertyOf(node) === null ? {} : { ownPrototypeProperty: ownPrototypePropertyOf(node) === true })
                 }
                 : {}),

package/dist/semantics/normalize/producers/bindings.js

@@ -6,6 +6,7 @@ import { normalCompletion, pureEffects } from '../../model/operands.js';
 import { blocked, mintOperationId, mintResult, operand } from './mint.js';
 import { bindingKindOf, bindingKindOfElement } from './binding-kind.js';
 import { boundElementType, citeBoundElementValue } from './destructuring.js';
+import { assertsType } from './erasure.js';
 import { citeExpressionResult } from './references.js';
 import { resultEdge } from './shared.js';
 /**
@@ -643,7 +644,10 @@ const contributeVariableDeclaration = (candidate, node, context) => {
         const cited = citeExpressionResult(initializer, context);
         if (cited.kind === 'unmodelled')
             return { kind: 'blocked', blocker: blocked(candidate.id, 'binding', cited.reason, null) };
-        operands.push(operand('initializer', 0, cited.source, context.types.typeAt(initializer)));
+        operands.push({
+            ...operand('initializer', 0, cited.source, context.types.typeAt(initializer)),
+            ...(assertsType(initializer, context.checker) ? { asserted: true } : {})
+        });
     }
     else if (loopValueResult) {
         operands.push(operand('initializer', 0, { kind: 'result', result: loopValueResult }, context.types.typeAt(node)));

package/dist/semantics/normalize/producers/boundary.d.ts

@@ -21,6 +21,7 @@ import type { ProducerContext } from '../producer-context.js';
 export declare const resolveExpressionOperand: (context: ProducerContext, node: ts.Node) => {
     readonly source: OperandSource;
     readonly type: StructuralTypeId;
+    readonly asserted?: true;
 } | null;
 /**
  * Catch clauses: the one candidate family `'boundary'` receives from the

package/dist/semantics/normalize/producers/boundary.js

@@ -1,6 +1,6 @@
 import ts from 'typescript';
 import { normalCompletion, pureEffects } from '../../model/operands.js';
-import { unwrapErased } from './erasure.js';
+import { assertsType, unwrapErased } from './erasure.js';
 import { blocked, mintOperationId, mintResult, operand } from './mint.js';
 import { citeExpressionResult } from './references.js';
 import { valueEdgesInto } from './shared.js';
@@ -25,7 +25,11 @@ export const resolveExpressionOperand = (context, node) => {
     const cited = citeExpressionResult(node, context);
     if (cited.kind === 'unmodelled')
         return null;
-    return { source: cited.source, type: context.types.typeAt(unwrapErased(node)) };
+    return {
+        source: cited.source,
+        type: context.types.typeAt(unwrapErased(node)),
+        ...(assertsType(node, context.checker) ? { asserted: true } : {})
+    };
 };
 /**
  * Catch clauses: the one candidate family `'boundary'` receives from the

package/dist/semantics/normalize/producers/class-lifecycle.js

@@ -4,6 +4,7 @@ import { normalCompletion, pureEffects, throwingCompletion } from '../../model/o
 import { isParameterProperty } from '../census.js';
 import { parameterBindingResultOf } from './bindings.js';
 import { parameterSlotTypeOf } from '../parameter-slot.js';
+import { declaresExactArms } from './exact-arms.js';
 import { mintOperationId, mintResult, operand } from './mint.js';
 import { resultOf } from '../../model/operands.js';
 import { asBlocked, resultEdge, uniqueSymbolKeyTextOf, staticFunctionNameOf, staticClassNameOf, staticClassLengthOf, expectedParameterCountOf, ownPrototypePropertyOf } from './shared.js';
@@ -209,6 +210,7 @@ export const createClassLifecycleProducer = (context) => {
                 ? {
                     functionSource: callable.getText(),
                     generatorFunction: 'asteriskToken' in callable && callable.asteriskToken !== undefined,
+                    ...(declaresExactArms(callable) ? { exactArms: true } : {}),
                     ...(ownPrototypePropertyOf(callable) === null ? {} : { ownPrototypeProperty: ownPrototypePropertyOf(callable) === true }),
                     ...(isNamedCallableMember(callable)
                         ? { functionName: staticFunctionNameOf(callable), functionLength: expectedParameterCountOf(callable) }
@@ -301,6 +303,7 @@ export const createClassLifecycleProducer = (context) => {
                 classConstructorBodyOf: context.identities.declarationIdOf(node),
                 functionSource: written.getText(),
                 generatorFunction: 'asteriskToken' in written && written.asteriskToken !== undefined,
+                ...(declaresExactArms(written) ? { exactArms: true } : {}),
                 ...(ownPrototypePropertyOf(written) === null ? {} : { ownPrototypeProperty: ownPrototypePropertyOf(written) === true }),
                 caller: candidate.caller,
                 operands: [],

package/dist/semantics/normalize/producers/control.js

@@ -436,7 +436,7 @@ const contributeReturn = (context, candidate, node) => {
         const resolved = resolveExpressionOperand(context, node.expression);
         if (!resolved)
             return blockedContribution(candidate, 'no normalized operation identifies the returned value');
-        valueOperand = operand('value', 0, resolved.source, resolved.type);
+        valueOperand = { ...operand('value', 0, resolved.source, resolved.type), ...(resolved.asserted ? { asserted: true } : {}) };
     }
     else {
         const undefinedType = context.table.intern({ kind: 'primitive', primitive: 'undefined' });
@@ -487,7 +487,7 @@ const contributeImplicitReturn = (context, candidate, node) => {
         id,
         form: 'return',
         caller: candidate.caller,
-        operands: [operand('value', 0, resolved.source, resolved.type)],
+        operands: [{ ...operand('value', 0, resolved.source, resolved.type), ...(resolved.asserted ? { asserted: true } : {}) }],
         results: [mintResult(id, 'completion', resolved.type)],
         completion: { canThrow: false, canReturn: true, canBreak: false, canContinue: false, canSuspend: false },
         effects: pureEffects,

package/dist/semantics/normalize/producers/erasure.d.ts

@@ -18,6 +18,13 @@ import ts from 'typescript';
 export declare const unwrapErased: (node: ts.Node) => ts.Node;
 /** The same rule where the caller already knows it holds an expression. */
 export declare const unwrapErasedExpression: (expression: ts.Expression) => ts.Expression;
+/**
+ * Whether one of the erased wrappers around `expression` is a type assertion
+ * that names a type -- `SemanticOperand.asserted`. `as any`/`as unknown`
+ * assert nothing about which arm a value holds, so they do not count; `!` and
+ * `satisfies` are not assertions of a type at all.
+ */
+export declare const assertsType: (expression: ts.Expression, checker: ts.TypeChecker) => boolean;
 /**
  * The node whose PARENT decides this expression's syntactic position.
  *

package/dist/semantics/normalize/producers/erasure.js

@@ -31,6 +31,25 @@ export const unwrapErased = (node) => {
 };
 /** The same rule where the caller already knows it holds an expression. */
 export const unwrapErasedExpression = (expression) => unwrapErased(expression);
+/**
+ * Whether one of the erased wrappers around `expression` is a type assertion
+ * that names a type -- `SemanticOperand.asserted`. `as any`/`as unknown`
+ * assert nothing about which arm a value holds, so they do not count; `!` and
+ * `satisfies` are not assertions of a type at all.
+ */
+export const assertsType = (expression, checker) => {
+    let current = expression;
+    for (;;) {
+        if (ts.isAsExpression(current) || ts.isTypeAssertionExpression(current)) {
+            if ((checker.getTypeFromTypeNode(current.type).flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) === 0)
+                return true;
+        }
+        else if (!ts.isParenthesizedExpression(current) && !ts.isNonNullExpression(current) && !ts.isSatisfiesExpression(current)) {
+            return false;
+        }
+        current = current.expression;
+    }
+};
 /**
  * The node whose PARENT decides this expression's syntactic position.
  *

package/dist/semantics/normalize/producers/exact-arms.d.ts

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+/**
+ * Whether a callable declaration states `@gea-exact-arms` -- see
+ * `AllocationOperation.exactArms` for what the tag promises and why only the
+ * author can promise it.
+ *
+ * Read off the declaration that owns the body, which for an overloaded method
+ * is the implementation signature: the overloads are types, and the tag
+ * changes how the one body lowers, so the one body's own JSDoc is where it
+ * belongs.
+ */
+export declare const declaresExactArms: (node: ts.Node) => boolean;

package/dist/semantics/normalize/producers/exact-arms.js

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+/**
+ * Whether a callable declaration states `@gea-exact-arms` -- see
+ * `AllocationOperation.exactArms` for what the tag promises and why only the
+ * author can promise it.
+ *
+ * Read off the declaration that owns the body, which for an overloaded method
+ * is the implementation signature: the overloads are types, and the tag
+ * changes how the one body lowers, so the one body's own JSDoc is where it
+ * belongs.
+ */
+export const declaresExactArms = (node) => ts.getJSDocTags(node).some((tag) => tag.tagName.text === 'gea-exact-arms');

package/dist/semantics/normalize/producers/invocations.js

@@ -8,6 +8,7 @@ import { implementationSignatureOf } from '../structural-declarations.js';
 import { physicalGeneratorOverloadResultAt } from '../physical-overload-result.js';
 import { regionId, semanticResultId } from '../../../identity/ids.js';
 import { bindingKindOf } from './binding-kind.js';
+import { declaresExactArms } from './exact-arms.js';
 import { blocked, mintOperationId, mintResult, operand } from './mint.js';
 import { calleeAwareTypeAt, objectDescriptorReturnTypeAt, resolvedCalleeSignatureType, sourceForValue, unwrapErased, valueEdgesInto } from './shared.js';
 import { isShortCircuitingCall, optionalChainGuardOf, optionalCallGuardOf, presentReturnTypeOf } from './optional-chain.js';
@@ -152,6 +153,34 @@ const argumentConversionRolesOf = (selected, operands) => {
     }
     return roles;
 };
+/**
+ * The `exact-arm` roles of a call into an `@gea-exact-arms` implementation
+ * (`ConversionRoleTarget.owner`): each argument's type under the overload the
+ * checker resolved. Published beside the implementation's own
+ * `parameter-slot` roles rather than instead of them, because the slot is
+ * still the implementation's union -- this only says which arm of it the
+ * argument enters. Nothing for a call that resolved straight to the body
+ * (no overload was chosen, so there is no arm to name) or to a generic
+ * overload (the instantiated parameter types are not public, exactly as
+ * `argumentConversionRolesOf` refuses them).
+ */
+const exactArmArgumentRolesOf = (context, node, resolved, implementation, operands) => {
+    if (!resolved || !implementation?.declaration || !declaresExactArms(implementation.declaration))
+        return [];
+    const selected = buildSelectedSignature(context, node, resolved);
+    if (!selected || selected.typeArguments.kind !== 'none')
+        return [];
+    const roles = [];
+    for (const argument of operands) {
+        if (argument.role !== 'argument')
+            continue;
+        const parameter = selected.parameters[argument.ordinal];
+        if (!parameter || parameter.rest)
+            continue;
+        roles.push({ role: 'argument', ordinal: argument.ordinal, owner: 'exact-arm', type: parameter.slot });
+    }
+    return roles;
+};
 const buildSelectedSignature = (context, node, signature) => {
     const declaration = signature.declaration;
     // No declaration node (the implicit constructor of a class with no written
@@ -1740,7 +1769,10 @@ export const createInvocationProducer = (context) => ({
                 ? { intrinsicReflection: intrinsicPropertyCall }
                 : {}),
             operands,
-            conversionRoles: argumentConversionRolesOf(selectedSignature, operands),
+            conversionRoles: [
+                ...argumentConversionRolesOf(selectedSignature, operands),
+                ...exactArmArgumentRolesOf(context, node, resolvedSignature, implementationSignature, operands)
+            ],
             // Two results, and they are different values. `value` is what the call
             // returned, which exists only on the branch where the guard was present;
             // `short-circuit` is what the *expression* evaluates to, which is that

package/dist/targets/cpp/class-properties/emit-class-properties.js

@@ -3,7 +3,7 @@ import { abiKey, representationKey } from '../../../representation/model.js';
 import { abiOfCallee } from '../../../projection/callee.js';
 import { runtimeClassLayoutsOf } from '../../../projection/classes.js';
 import { classMethodOverrideOf, classPrototypeMethodMutableOf } from '../../../projection/fields.js';
-import { bindingReference, captureFieldText, cppEnvironmentStructName, cppThunkName, createCppEmitBlockedError, operandText } from '../emit-context.js';
+import { bindingReference, captureFieldText, cppEnvironmentStructName, cppThunkEntryText, createCppEmitBlockedError, operandText } from '../emit-context.js';
 import { classFamilyOverridesOf, classMemberOf, dispatchesStatically, reachableClassMethodsOf, classStaticFieldStorageOf, classStaticMemberOf } from '../class-layout.js';
 import { cppVirtualMemberName, virtualDispatchKey } from '../virtual-methods.js';
 import { cppAbiParameterType, cppBodyName, cppCallableDeclarationTagName, cppClassName, cppConstructName, cppRecordFieldName, cppRecordFieldPresenceName, cppResultTypeOf, cppStringLiteral, cppTypeOf, cppUndefinedIn } from '../types.js';
@@ -160,7 +160,7 @@ valueRepresentation = boundMethodValueRepresentation(operation), receiverText =
     const owner = [...ctx.classes.values()].find((layout) => layout.methods.some((entry) => entry.callable === method.callable && entry.key === key));
     if (owner === undefined)
         throw createCppEmitBlockedError('call-abi:class-method-owner', `method "${key}" has no declaring prototype`);
-    const payload = `${cppTypeOf(bodyRepresentation)}{&${cppThunkName(method.callable)}, ${environment}}`;
+    const payload = `${cppTypeOf(bodyRepresentation)}{${cppThunkEntryText(ctx, method.callable)}, ${environment}}`;
     const override = receiverRepresentation.kind === 'class-ref' && !dispatchesStatically(ctx, operation.receiver)
         ? classMethodOverrideOf(ctx.classes, receiverRepresentation.declaration, key)
         : null;
@@ -813,7 +813,7 @@ receiverText) => {
                 throw createCppEmitBlockedError('property-access:class-prototype:method-abi', 'prototype method has no native convention');
             const representation = { kind: 'function-value-dispatch', abi };
             const environment = methodEnvironmentText(ctx, method.callable, `prototype method ${method.key}`);
-            const payload = `${cppTypeOf(representation)}{&${cppThunkName(method.callable)}, ${environment}}`;
+            const payload = `${cppTypeOf(representation)}{${cppThunkEntryText(ctx, method.callable)}, ${environment}}`;
             return {
                 representation,
                 text: `gea::nativeClassMethodValue<${cppClassName(owner.declaration)}, &${cppCallableDeclarationTagName(method.callable)}>(${state}, ${payload})`
@@ -869,7 +869,7 @@ receiverText) => {
         // `gea::Value{&thunk, env}` for a computed read, which is not a boxed
         // callable at all.
         const methodAbi = ctx.abiOfCallable(site.method.callable);
-        const object = `{&${cppThunkName(site.method.callable)}, ${methodEnvironmentText(ctx, site.method.callable, `a "get" of static "${key}"`)}}`;
+        const object = `{${cppThunkEntryText(ctx, site.method.callable)}, ${methodEnvironmentText(ctx, site.method.callable, `a "get" of static "${key}"`)}}`;
         if (methodAbi === null)
             return `${cppTypeOf(result)}${object}`;
         const methodRepresentation = { kind: 'function-value-dispatch', abi: methodAbi };