@geastack/compiler 1.0.15 → 1.0.17

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

@@ -0,0 +1,37 @@
+/**
+ * How a built-in host adapter loads the package that states its tables.
+ *
+ * Each adapter reads its host's own statement -- gea's `host-shims` and
+ * `cpp-ir`, Apple's SDK fixture and plugin, the ANGLE plugin -- by package
+ * name, which resolves from THIS compiler's `node_modules`. That copy and the
+ * checkout a build names with `--plugin <path>` are two spellings of one
+ * package, and they drift: the compiler's is an `npm pack` snapshot, the path
+ * the build passes is the sibling checkout. A table added to the checkout then
+ * never reached a compile that named the checkout explicitly, and the failure
+ * surfaced far downstream with nothing saying why (an ambient-type
+ * realization stated by the checkout fell through to another host's by-name
+ * protocols; an absent global stated by the checkout stayed live and emitted
+ * lib.dom's whole `Window`).
+ *
+ * The stated path is the authority. When `plugins/load.ts` answers a legacy
+ * package entry with its built-in adapter, the adapter ADOPTS that file:
+ * every later load resolves from the file's own package first -- a package
+ * self-reference through its `exports`, or its own dependencies -- and falls
+ * back to the compiler's copy only for a specifier the stated package cannot
+ * see at all (Apple's SDK is a peer the plugin package does not carry).
+ * `MODULE_NOT_FOUND` is the only failure the fallback absorbs: a package that
+ * resolves and then fails to load is a defect wherever it lives, and the
+ * adapters' own two-failures rule (`gea/host.ts`) still tells it apart.
+ *
+ * Adoption must precede every read. An adapter table computed at module
+ * initialization would freeze the compiler's copy before the CLI ever saw
+ * `--plugin`, so the adapters read their tables lazily and `adopt` resets
+ * whatever they cached.
+ */
+export interface HostPackageLoader {
+    readonly load: (specifier: string) => unknown;
+    readonly resolve: (specifier: string) => string;
+    /** Resolve from this file's package first; the caller resets its own caches. */
+    readonly adopt: (file: string) => void;
+}
+export declare const createHostPackageLoader: (ownUrl: string) => HostPackageLoader;

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/frontend.js

@@ -44,7 +44,7 @@ import { censusRefusalCounts } from './normalize/census-refusal.js';
 import { createCellPolicyRegistry, defaultCellEvidencePolicies, buildCellFactsTable, publishCellFacts } from './normalize/cells/index.js';
 import { settleBindingCensus } from './normalize/binding-fixpoint.js';
 import { withJsDocTypeNames } from './normalize/jsdoc-type-names.js';
-import { censusReachability, moduleEvaluationOrder, nodeIsReachable } from './normalize/reachability.js';
+import { censusReachability, fileEvaluates, moduleEvaluationOrder, nodeIsReachable } from './normalize/reachability.js';
 import { createProgram, defaultCompilerOptions } from './program.js';
 import { createFrontendTiming } from './frontend-timing.js';
 import { classHeritageOf } from './class-heritage.js';
@@ -1105,7 +1105,10 @@ export const runFrontend = (input) => {
         // reachability walk pruned whole, or one whose top level censused nothing,
         // has no region -- and a name in this list that no region answers would be
         // a call to a function nothing defines.
+        // `fileEvaluates` is the reached-statement half of that: a file kept only
+        // for a layout-only class has a region and, by design, no body.
         moduleOrder: moduleEvaluationOrder({ checker: compiled.checker, files: compiled.sourceFiles, entries: compiled.entryFiles })
+            .filter((file) => fileEvaluates(reachable, file))
             .map((file) => regionId(identities.nodeIdOf(file), 'module-body'))
             .filter((region) => normalized.graph.regions.has(region)),
         sourceFileNames: identities.sourceFileNames,

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/flow/callable-reach.js

@@ -5146,9 +5146,7 @@ const closedMemberCallableUses = (checker, flow, member, countedCalls, givenRece
             const origins = key === null ? null : allocationOriginsOf(receiver);
             traceClosedCallee(call, 'invocationTargetsOf/origins', `key=${key ?? 'null'} origins=${origins === null ? 'null' : origins.classes.size}`);
             if (origins !== null) {
-                const privateDeclarations = ts.isPropertyAccessExpression(callee) && ts.isPrivateIdentifier(callee.name)
-                    ? privateMemberDeclarationsOf(callee.name)
-                    : null;
+                const privateDeclarations = ts.isPropertyAccessExpression(callee) && ts.isPrivateIdentifier(callee.name) ? privateMemberDeclarationsOf(callee.name) : null;
                 const selected = new Set();
                 for (const owner of origins.classes) {
                     const slotDeclarations = privateDeclarations ??

package/dist/semantics/normalize/global-host-mutations.js

@@ -4416,7 +4416,7 @@ computedKeysOf = () => null, trustSeed = initialCensusSeed) => {
         // value.
         if ((ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent)) && parent.propertyName === node)
             return true;
-        return (((ts.isVariableDeclaration(parent) ||
+        return ((ts.isVariableDeclaration(parent) ||
             ts.isImportSpecifier(parent) ||
             ts.isExportSpecifier(parent) ||
             ts.isImportClause(parent) ||
@@ -4441,7 +4441,7 @@ computedKeysOf = () => null, trustSeed = initialCensusSeed) => {
             ts.isPropertyAssignment(parent) ||
             ts.isShorthandPropertyAssignment(parent) ||
             ts.isTypeParameterDeclaration(parent)) &&
-            parent.name === node));
+            parent.name === node);
     };
     let globalEscapeAnswer = null;
     const globalObjectEscapesIntoData = () => {

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');