@geastack/compiler 1.0.16 → 1.0.17

package/dist/conversion/nodes.d.ts

@@ -40,6 +40,28 @@ export interface ConversionCensus {
      * node's id carries the operation's name and lives in its own table.
      */
     readonly coercionFor: (source: Representation, operation: CoercionOperation) => ConversionNode;
+    /**
+     * The exact-arm projection of a tagged union into the one arm whose carrier
+     * IS the target: `get<k>()` guarded by `is<k>()`, a `TypeError` otherwise.
+     * `null` where the source is not a tagged union or the target is not
+     * exactly one of its arms -- the pair then belongs to `nodeFor`.
+     *
+     * Its own table for the same reason coercions have one: the pair
+     * `tagged-union(...) -> arm` already names `nodeFor`'s dispatch node, which
+     * converts EVERY arm into the target (a callable arm through an adapter, a
+     * class arm through an upcast), and only the instruction's own node id says
+     * which of the two runs. Minted only for an owner whose declaration states
+     * `@gea-exact-arms` (`LoweringContext.exactArmNarrowing`): the projection
+     * trades a conversion the checker proved total for a runtime check the
+     * author vouched for, so nothing mints it on its own initiative.
+     *
+     * A `static` capability with `nativeFieldProtocol: 'unused'` and every
+     * transport preserved: the value handed on is the arm's own payload,
+     * untouched, so no field protocol, adapter or fresh alias is involved --
+     * which is exactly the proof the reflection census needs to leave the
+     * arm's parameters un-promoted.
+     */
+    readonly exactArmFor: (source: Representation, target: Representation) => ConversionNode | null;
     /** The node a `convert` instruction names, from whichever table minted it; `null` for an id no census minted. */
     readonly nodeById: (id: ConversionNodeId) => ConversionNode | null;
     /** Every node minted through `nodeFor` that the eager graph did not already hold. */
@@ -53,3 +75,12 @@ export declare const conversionNodeIdOf: (source: Representation, target: Repres
 /** The carrier each abstract operation lands on. */
 export declare const coercionTargetOf: (operation: CoercionOperation) => Representation;
 export declare const createConversionNodes: (input: ConversionCensusInput) => ConversionCensus;
+/** The materializer id every exact-arm node carries; the printer dispatches its recipe on it. */
+export declare const EXACT_ARM_MATERIALIZER = "gea::host::exactArm";
+/**
+ * Which arm of `source` the target IS, by carrier key, or `null` when the
+ * source is not a tagged union or no single arm matches. A union's arms are
+ * pairwise disjoint at runtime, so two arms never share a key; the
+ * exactly-one test still guards the answer rather than trusting that.
+ */
+export declare const exactArmIndexOf: (source: Representation, target: Representation) => number | null;

package/dist/conversion/nodes.js

@@ -86,6 +86,50 @@ export const createConversionNodes = (input) => {
         coercions.set(id, node);
         return node;
     };
-    const nodeById = (id) => input.nodes.get(id) ?? minted.get(id) ?? coercions.get(id) ?? null;
-    return { nodeFor, coercionFor, nodeById, minted };
+    const exactArms = new Map();
+    const exactArmFor = (source, target) => {
+        const index = exactArmIndexOf(source, target);
+        if (index === null)
+            return null;
+        const id = `${representationKey(source)}->${representationKey(target)}#exact-arm`;
+        const remembered = exactArms.get(id);
+        if (remembered !== undefined)
+            return remembered;
+        const node = {
+            id,
+            source,
+            target,
+            capability: {
+                kind: 'static',
+                materializer: {
+                    id: EXACT_ARM_MATERIALIZER,
+                    domain: `static:exact-arm:${index}`,
+                    allocates: false,
+                    nativeFieldProtocol: 'unused',
+                    nativePayloadTransport: 'preserved',
+                    nativeClassReferenceIdentity: 'preserved',
+                    callableIdentityTransport: 'preserved'
+                }
+            }
+        };
+        exactArms.set(id, node);
+        return node;
+    };
+    const nodeById = (id) => input.nodes.get(id) ?? minted.get(id) ?? coercions.get(id) ?? exactArms.get(id) ?? null;
+    return { nodeFor, coercionFor, exactArmFor, nodeById, minted };
+};
+/** The materializer id every exact-arm node carries; the printer dispatches its recipe on it. */
+export const EXACT_ARM_MATERIALIZER = 'gea::host::exactArm';
+/**
+ * Which arm of `source` the target IS, by carrier key, or `null` when the
+ * source is not a tagged union or no single arm matches. A union's arms are
+ * pairwise disjoint at runtime, so two arms never share a key; the
+ * exactly-one test still guards the answer rather than trusting that.
+ */
+export const exactArmIndexOf = (source, target) => {
+    if (source.kind !== 'tagged-union')
+        return null;
+    const targetKey = representationKey(target);
+    const matches = source.arms.flatMap((arm, index) => (representationKey(arm.value) === targetKey ? [index] : []));
+    return matches.length === 1 ? (matches[0] ?? null) : null;
 };

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

@@ -95,6 +95,13 @@ export interface RecastArmPlan {
     readonly index: number;
     readonly via: 'exact' | 'convert' | RecordViewPlan;
 }
+/** One source arm of a `dispatch` plan, in the source's own arm order. */
+export interface DispatchArmPlan {
+    readonly via: 'exact' | 'convert' | 'absent' | RecordViewPlan;
+}
+export declare const isRecordViewTarget: (value: Representation) => value is RecordViewTarget;
+/** Whether this view dispatches on a sum's live arm somewhere along its spine (`dispatch`, possibly under an optional or an assert). */
+export declare const recordViewDispatchesArms: (plan: RecordViewPlan) => boolean;
 export type RecordViewPlan = {
     readonly kind: 'owned';
     readonly plan: OwnedRecordPlan;
@@ -132,6 +139,23 @@ export type RecordViewPlan = {
     readonly source: TaggedUnion;
     readonly target: TaggedUnion;
     readonly arms: readonly RecastArmPlan[];
+}
+/**
+ * A sum every arm of which reaches ONE record-shaped target: dispatched on
+ * the live arm, never selected. `const ctx: AudioContextLike | null = Ctor ?
+ * new Ctor() : createNativeAudioContext()` stores a `record | class` into
+ * the interface's slot; the class arm is a structural view of the record
+ * and the record arm is itself. Selecting the exact arm (`get<k>()`) read
+ * the class instance's bytes as the record whenever the native host was the
+ * live one. An `absent` arm is the target optional's own absence.
+ */
+ | {
+    readonly kind: 'dispatch';
+    readonly source: TaggedUnion;
+    readonly target: RecordViewTarget | Extract<Representation, {
+        kind: 'optional';
+    }>;
+    readonly arms: readonly DispatchArmPlan[];
 } | {
     readonly kind: 'fields';
     readonly source: RecordViewSource;

package/dist/conversion/record-view.js

@@ -47,6 +47,9 @@ export const ownedRecordMaterializationPlan = (source, target, layouts) => {
     }
     return { kind: 'record', source, target, fields: planned };
 };
+export const isRecordViewTarget = (value) => value.kind === 'record' || (value.kind === 'native-record-ref' && value.native === null);
+/** Whether this view dispatches on a sum's live arm somewhere along its spine (`dispatch`, possibly under an optional or an assert). */
+export const recordViewDispatchesArms = (plan) => plan.kind === 'dispatch' || ((plan.kind === 'optional' || plan.kind === 'assert') && recordViewDispatchesArms(plan.payload));
 /**
  * Effects of an already-admitted view, not another conversion predicate.
  * Copying a held carrier (including an already-dynamic cell) reads native
@@ -68,6 +71,8 @@ export const recordViewUsesOnlyDirectFields = (plan) => {
         }
         case 'recast-union':
             return plan.arms.every((arm) => arm.via === 'exact' || (arm.via !== 'convert' && recordViewUsesOnlyDirectFields(arm.via)));
+        case 'dispatch':
+            return plan.arms.every((arm) => arm.via === 'exact' || arm.via === 'absent' || (arm.via !== 'convert' && recordViewUsesOnlyDirectFields(arm.via)));
         case 'fields':
             return (!plan.expando &&
                 plan.indexes.length === 0 &&
@@ -128,6 +133,14 @@ export const structuralRecordViewPlan = (layouts, source, target, convertible) =
         const home = exact.length === 1 ? exact[0] : undefined;
         return home === undefined ? null : { kind: 'arm', source, target, index: home.index, payload: home.payload };
     }
+    // A bare sum carrying the target optional's absence as an ARM: the absent
+    // arm is the optional's empty state and every other arm dispatches into
+    // the payload, so the optional cannot be peeled first here.
+    if (target.kind === 'optional' && source.kind === 'tagged-union' && isRecordViewTarget(target.payload)) {
+        const dispatched = dispatchUnionPlan(layouts, source, target, convertible);
+        if (dispatched !== null)
+            return dispatched;
+    }
     // The optional wrapper is peeled on both sides first: the question is about
     // the two RECORD carriers, and an absence is answered by the optional's own
     // presence flag either way.
@@ -151,6 +164,8 @@ export const structuralRecordViewPlan = (layouts, source, target, convertible) =
     }
     if (source.kind === 'tagged-union' && target.kind === 'tagged-union')
         return recastUnionPlan(layouts, source, target, convertible);
+    if (source.kind === 'tagged-union' && isRecordViewTarget(target))
+        return dispatchUnionPlan(layouts, source, target, convertible);
     const sourceIsRecord = source.kind === 'record' || source.kind === 'record-with-index' || source.kind === 'native-record-ref';
     if (!sourceIsRecord && (source.kind !== 'class-ref' || source.ownership !== 'shared-refcount'))
         return null;
@@ -244,6 +259,45 @@ export const structuralRecordViewPlan = (layouts, source, target, convertible) =
         source.indexes[0]?.value.kind === 'dynamic';
     return { kind: 'fields', source, target, fields, indexes, expando };
 };
+/**
+ * Every arm of `source` reaching the one record-shaped `target` (or the
+ * payload of an optional one), in the source's own arm order.
+ *
+ * Answered only when some arm reaches the target through a VIEW: a sum whose
+ * arms are all exact or chain-convertible is the printer chain's own dispatch
+ * (`emit-narrowing.ts`'s `taggedUnionArmText`), and repeating that answer
+ * here would move every such program for nothing. An arm with no way to the
+ * target refuses the whole plan: a dispatch that skipped an arm would be the
+ * unchecked selection this plan exists to replace.
+ */
+const dispatchUnionPlan = (layouts, source, target, convertible) => {
+    const payload = target.kind === 'optional' ? target.payload : target;
+    if (!isRecordViewTarget(payload))
+        return null;
+    const key = representationKey(payload);
+    const arms = [];
+    let viewed = false;
+    for (const arm of source.arms) {
+        if (representationKey(arm.value) === key) {
+            arms.push({ via: 'exact' });
+            continue;
+        }
+        if (target.kind === 'optional' && arm.value.kind === target.absence) {
+            arms.push({ via: 'absent' });
+            continue;
+        }
+        if (convertible(arm.value, payload)) {
+            arms.push({ via: 'convert' });
+            continue;
+        }
+        const view = structuralRecordViewPlan(layouts, arm.value, payload, convertible);
+        if (view === null)
+            return null;
+        viewed = true;
+        arms.push({ via: view });
+    }
+    return viewed ? { kind: 'dispatch', source, target, arms } : null;
+};
 const recastUnionPlan = (layouts, source, target, convertible) => {
     const arms = [];
     for (const arm of source.arms) {

package/dist/ir/certify.js

@@ -1,4 +1,5 @@
 import { operationOfResult } from '../identity/ids.js';
+import { forEachEmbeddedRepresentation } from '../representation/embedded-carriers.js';
 import { captureCapabilityOf, representationKey } from '../representation/model.js';
 import { propertyAccessKeysOf } from './certify/property-access.js';
 import { runtimeHelperKeysOf } from './certify/runtime-helper.js';
@@ -64,6 +65,24 @@ const physicalTypeDemand = (manifest, representation) => {
 const nativeBoundaryDemand = (representation) => representation.kind === 'native-handle'
     ? { key: `native-boundary:${representation.native ?? representation.protocol}@${representation.version}` }
     : null;
+/**
+ * The native-boundary demands of every carrier a representation EMBEDS. The
+ * root's own demand is `nativeBoundaryDemand`; this is the rest of the tree
+ * -- the fields of a record, the arms of a union, a callable's signature --
+ * because the emitted C++ spells all of it, and a `native-handle` a struct
+ * field names must be as authenticated as one an SSA value holds. Asked of
+ * the root alone, lib.dom's `Window` certified with `Navigator`/`History`
+ * fields whose tag types no host declared, and clang was the first to say so.
+ */
+const embeddedNativeBoundaryDemands = (representation) => {
+    const demands = [];
+    forEachEmbeddedRepresentation(representation, (carrier) => {
+        const boundary = nativeBoundaryDemand(carrier);
+        if (boundary)
+            demands.push(boundary);
+    });
+    return demands;
+};
 const abiDemands = (manifest, abi) => {
     if (abi === null)
         return [];
@@ -72,7 +91,8 @@ const abiDemands = (manifest, abi) => {
         carriers.push(abi.receiver);
     return carriers.flatMap((carrier) => {
         const boundary = nativeBoundaryDemand(carrier);
-        return boundary ? [physicalTypeDemand(manifest, carrier), boundary] : [physicalTypeDemand(manifest, carrier)];
+        const embedded = embeddedNativeBoundaryDemands(carrier);
+        return boundary ? [physicalTypeDemand(manifest, carrier), boundary, ...embedded] : [physicalTypeDemand(manifest, carrier), ...embedded];
     });
 };
 /**
@@ -462,6 +482,8 @@ export const certifyIr = (input) => {
             const boundary = nativeBoundaryDemand(representation);
             if (boundary)
                 decide(owner, boundary, ctx);
+            for (const demand of embeddedNativeBoundaryDemands(representation))
+                decide(owner, demand, ctx);
         }
         for (const blockId of body.blockOrder) {
             const block = body.blocks.get(blockId);

package/dist/ir/lower-operands.d.ts

@@ -8,7 +8,7 @@ import { type CallableAbi, type RecordField, type Representation } from '../repr
 import type { SealedRepresentationPlan } from '../representation/plan.js';
 import type { SemanticGraph } from '../semantics/model/graph.js';
 import { type SemanticOperand } from '../semantics/model/operands.js';
-import type { SemanticOperation } from '../semantics/model/operations.js';
+import { type SemanticOperation } from '../semantics/model/operations.js';
 import type { IrBodyBuilder } from './build.js';
 import type { PendingShortCircuit } from './lower-short-circuit.js';
 import type { IrBlockId, IrOperand } from './model.js';
@@ -139,6 +139,15 @@ export interface LoweringContext {
     readonly values: Map<SemanticResultId, IrValueId>;
     /** Optional-chain expressions whose merge is recorded but not yet closed (`lower-short-circuit.ts`). */
     readonly shortCircuits: Map<SemanticResultId, PendingShortCircuit>;
+    /**
+     * Whether this owner's declaration states `@gea-exact-arms`
+     * (`AllocationOperation.exactArms`): a tagged-union operand entering a slot
+     * that is exactly one of its arms takes the census's exact-arm projection
+     * instead of `nodeFor`'s per-arm dispatch. Per owner rather than per site
+     * because the tag is a statement about the body's own guards, which the
+     * lowering has no way to evaluate site by site.
+     */
+    readonly exactArmNarrowing: boolean;
 }
 export declare const describeOperand: (operand: SemanticOperand) => string;
 /** A published result's carrier plus the SSA id already minted for it -- the only legal source for an operand that names a prior result. */

package/dist/ir/lower-operands.js

@@ -2,6 +2,7 @@ import { detachedMethodAbiOf, isClosedContiguousTupleRecord } from '../projectio
 import { classMemberOf } from '../projection/fields.js';
 import { representationKey } from '../representation/model.js';
 import { operandOf, resultOf } from '../semantics/model/operands.js';
+import { conversionRoleTargetOf } from '../semantics/model/operations.js';
 import { anchorResultOf, IrLoweringBlockedError, requireRepresentation } from './lower-graph.js';
 /**
  * Whether a property read's receiver+key names a field an installed plugin
@@ -181,7 +182,10 @@ export const requireResultRepresentation = (ctx, operation, role, describe) => {
 export const convertTo = (ctx, block, lineage, operand, slot, via = 'slot') => {
     if (representationKey(operand.representation) === representationKey(slot))
         return operand;
-    const node = ctx.program.conversions.nodeFor(operand.representation, slot);
+    // The owner's own declaration asked for the projection; where the slot is
+    // not exactly one arm the census answers `null` and the ordinary pair runs.
+    const exact = ctx.exactArmNarrowing ? ctx.program.conversions.exactArmFor(operand.representation, slot) : null;
+    const node = exact ?? ctx.program.conversions.nodeFor(operand.representation, slot);
     if (node.capability.kind === 'never')
         return null;
     const value = ctx.builder.convert(block, lineage, node.id, operand, slot);
@@ -233,12 +237,64 @@ export const enter = (ctx, block, lineage, operation, operand, resolved) => {
     // value it then re-viewed.
     if (answer.source === 'alias')
         return resolved;
-    const entered = convertTo(ctx, block, lineage, resolved, answer.representation);
+    const entered = exactArmEntry(ctx, block, lineage, operation, operand, resolved, answer.representation) ??
+        convertTo(ctx, block, lineage, resolved, answer.representation) ??
+        assertedArmEntry(ctx, block, lineage, operand, resolved, answer.representation);
     if (entered !== null)
         return entered;
     recordDrift(ctx, block, operation.id, operand.role, operand.ordinal, resolved.representation, answer.representation);
     return resolved;
 };
+/**
+ * An argument entering an `@gea-exact-arms` callee's union slot through the
+ * arm the resolved overload named (`ConversionRoleTarget.owner`'s
+ * `exact-arm`): the value converted into THAT arm's carrier, then wrapped --
+ * an exact wrap, since the arm's own key is one of the union's. `null` where
+ * the call published no such role, the slot is not a union, or the named
+ * type is not an arm of it, and the ordinary slot conversion runs instead.
+ *
+ * Two `convert`s rather than one so each names a census node the certificate
+ * already knows how to read: source-into-arm is the same pair a direct call
+ * of the overload would mint, and arm-into-union is the identity wrap.
+ */
+const exactArmEntry = (ctx, block, lineage, operation, operand, resolved, slot) => {
+    if (slot.kind !== 'tagged-union' || operand.role !== 'argument')
+        return null;
+    const target = conversionRoleTargetOf(operation, 'argument', operand.ordinal, 'exact-arm');
+    if (target === undefined)
+        return null;
+    const arm = slot.arms.find((candidate) => candidate.semanticType === target.type) ??
+        (() => {
+            const key = representationKey(ctx.constantDeriver.layoutOf(target.type));
+            return slot.arms.find((candidate) => representationKey(candidate.value) === key);
+        })();
+    if (arm === undefined)
+        return null;
+    const held = convertTo(ctx, block, lineage, resolved, arm.value, 'exact-arm');
+    return held === null ? null : convertTo(ctx, block, lineage, held, slot, 'exact-arm');
+};
+/**
+ * A value the program's own type assertion states the arm of
+ * (`SemanticOperand.asserted`), entering a slot that is exactly one arm of
+ * its union, where the ordinary pair has no recipe: the census's exact-arm
+ * projection, checked at runtime. Asked only AFTER `convertTo` declined, so
+ * a pair the census answers soundly for every arm keeps that answer and the
+ * assertion changes nothing -- exactly as it changes nothing in JavaScript.
+ * The pair the census declines is the one where an arm has no home in the
+ * slot at all (`conversions.ts`'s `classArmWithoutHome`): there the only
+ * alternatives are refusing the program or reading the wrong arm's bytes,
+ * and the author has written which arm it is.
+ */
+const assertedArmEntry = (ctx, block, lineage, operand, resolved, slot) => {
+    if (operand.asserted !== true)
+        return null;
+    const node = ctx.program.conversions.exactArmFor(resolved.representation, slot);
+    if (node === null)
+        return null;
+    const value = ctx.builder.convert(block, lineage, node.id, resolved, slot);
+    traceSpeculativeLoad(lineage, 'asserted-arm', node, value);
+    return { value, representation: slot };
+};
 /** The row `LoweringProgram.drift` keeps for a pair the census has no recipe for. */
 const recordDrift = (ctx, block, operation, role, ordinal, source, slot, node = ctx.program.conversions.nodeFor(source, slot)) => {
     ctx.program.drift.push({

package/dist/ir/lower.js

@@ -1050,7 +1050,9 @@ const iteratorCloseRegionsOf = (graph, membership, order, blockStarts, flow, ctx
 };
 const lowerOwner = (graph, plan, constantDeriver, program, abi, construct, abiRefusal, owner, operationIds, plugins, ownerEdges, regionParts, deferredIteratorCloses, 
 /** Whether this owner is a `function*` -- see `generatorPrologueBoundary` below. */
-isGenerator) => {
+isGenerator, 
+/** Whether this owner's declaration states `@gea-exact-arms` -- see `LoweringContext.exactArmNarrowing`. */
+exactArmNarrowing) => {
     // Membership first: the execution order below keeps each branch's operations
     // contiguous, which it can only do once every operation's scope chain is
     // known. Nothing in the membership reads a position from the list it is
@@ -1067,7 +1069,8 @@ isGenerator) => {
         abiRefusal,
         builder,
         values: new Map(),
-        shortCircuits: new Map()
+        shortCircuits: new Map(),
+        exactArmNarrowing
     };
     const blockStarts = new Map();
     const finiteCloseStarts = new Map();
@@ -1265,6 +1268,10 @@ export const lowerToIr = (input) => {
     const bodies = new Map();
     const blocked = [];
     const functionFacts = new Map();
+    // Owners whose declaration states `@gea-exact-arms`. Kept apart from
+    // `functionFacts`, which is spread onto the emitted body: the tag changes
+    // how the body LOWERS and is nothing the body needs to carry afterwards.
+    const exactArmOwners = new Set();
     // The graph is sealed: its loop-owned closes are identical for every body.
     // Collect once instead of scanning the entire program for each function.
     const deferredIteratorCloses = new Set();
@@ -1278,6 +1285,8 @@ export const lowerToIr = (input) => {
                 functionLength: operation.functionLength ?? 0,
                 generator: operation.generatorFunction === true
             });
+            if (operation.exactArms === true)
+                exactArmOwners.add(operation.callable);
         }
     }
     // A function whose body is empty owns no operations, so grouping the graph by
@@ -1333,7 +1342,7 @@ export const lowerToIr = (input) => {
             const construct = input.constructs.get(owner) ?? null;
             const abiRefusal = input.abiBlockers.get(owner) ?? null;
             const facts = functionFacts.get(owner);
-            const body = lowerOwner(input.graph, input.plan, constantDeriver, program, abi, construct, abiRefusal, owner, operationIds, input.plugins, edgesByOwner.get(owner) ?? noEdges, regionParts, deferredIteratorCloses, facts?.generator === true);
+            const body = lowerOwner(input.graph, input.plan, constantDeriver, program, abi, construct, abiRefusal, owner, operationIds, input.plugins, edgesByOwner.get(owner) ?? noEdges, regionParts, deferredIteratorCloses, facts?.generator === true, exactArmOwners.has(owner));
             bodies.set(body.owner, facts === undefined ? body : { ...body, ...facts });
         }
         catch (error) {

package/dist/ir/reflection-demand.js

@@ -1219,6 +1219,11 @@ export const reflectionExposureOf = (bodies, classes, deriver, options) => {
             // publish those inputs to a dynamic source listener. That publication
             // happens inside generated adapter code, not in a separate IR call.
             const targetAbi = unwrappedCallableAbi(operation.result.representation);
+            // Under `GEA_REFLECTION_DEBUG`, the site too: a row's reasons say WHAT
+            // was promoted, and an adapter's cost is only removable at the
+            // conversion that installs it.
+            if (reflectionWatch !== undefined && targetAbi !== null)
+                console.error(`[REFLECTION-ADAPTER] lineage=${String(operation.lineage)} node=${operation.conversionUse} capability=${node?.capability.kind ?? 'none'}`);
             if (targetAbi !== null) {
                 if (targetAbi.receiver !== null)
                     promoteFull(targetAbi.receiver, 'callable-adapter-input');

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

@@ -113,6 +113,8 @@ export declare const appleNativeTypes: () => ReadonlyMap<string, string>;
 export declare const appleMemberTables: () => AppleHostShimSlice | null;
 /** The SDK's own platform description, one step upstream of the shim tables; empty when the packages are not installed. */
 export declare const appleBridgeMetadata: () => AppleBridgeMetadataSlice;
+/** The package entry the CLI loaded is the one this host's tables come from -- see `plugins/host-package.ts`. */
+export declare const adoptApplePackage: (file: string) => void;
 /**
  * Each declaration file of the Apple SDK package, to the native-only marker the
  * module implementing that same subpath calls.

package/dist/plugins/apple/host.js

@@ -1,7 +1,7 @@
-import { createRequire } from 'node:module';
+import { createHostPackageLoader } from '../host-package.js';
 import { readFileSync } from 'node:fs';
 import { dirname, resolve as resolvePath } from 'node:path';
-const require_ = createRequire(import.meta.url);
+const packageLoader = createHostPackageLoader(import.meta.url);
 /**
  * `nativeTypes`, narrowed at the boundary.
  *
@@ -66,8 +66,8 @@ const appleHostShims = () => {
     let sdk;
     let plugin;
     try {
-        sdk = require_(sdkSpecifier);
-        plugin = require_(pluginSpecifier);
+        sdk = packageLoader.load(sdkSpecifier);
+        plugin = packageLoader.load(pluginSpecifier);
     }
     catch (error) {
         const requested = process.env.GEATSC2_APPLE_SDK !== undefined || process.env.GEATSC2_APPLE_PLUGIN !== undefined;
@@ -104,6 +104,13 @@ export const appleBridgeMetadata = () => {
     return loadedMetadata ?? {};
 };
 let loadedMarkers = null;
+/** The package entry the CLI loaded is the one this host's tables come from -- see `plugins/host-package.ts`. */
+export const adoptApplePackage = (file) => {
+    packageLoader.adopt(file);
+    loaded = undefined;
+    loadedMetadata = null;
+    loadedMarkers = null;
+};
 /** The directory of the package a resolved entry point belongs to, by its own manifest. */
 const packageRootOf = (entry, name) => {
     let directory = dirname(entry);
@@ -159,7 +166,7 @@ export const appleModuleMarkers = () => {
     if (used.size === 0)
         return markers;
     const specifier = process.env.GEATSC2_APPLE_SDK ?? '@geastack/apple';
-    const root = packageRootOf(require_.resolve(specifier), specifier);
+    const root = packageRootOf(packageLoader.resolve(specifier), specifier);
     if (root === null)
         return markers;
     const manifest = JSON.parse(readFileSync(resolvePath(root, 'package.json'), 'utf8'));
@@ -243,7 +250,7 @@ export const appleClassConstructorParameters = (className) => {
  */
 export const writeAppleBridgeArtifacts = (metadataPath, outDir) => {
     const pluginSpecifier = process.env.GEATSC2_APPLE_PLUGIN ?? '@geastack/geatsc-plugin-apple-native';
-    const plugin = require_(pluginSpecifier);
+    const plugin = packageLoader.load(pluginSpecifier);
     const factory = plugin.appleNativePlugin;
     if (typeof factory !== 'function')
         throw new Error(`'${pluginSpecifier}' exports no appleNativePlugin function`);

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

@@ -145,6 +145,8 @@ export interface GeaHostClass {
     readonly construct?: string;
     readonly factory?: string;
 }
+/** The package entry the CLI loaded is the one this host's tables come from -- see `plugins/host-package.ts`. */
+export declare const adoptGeaPackage: (file: string) => void;
 /**
  * The host type table, from the package that owns it.
  *

package/dist/plugins/gea/host.js

@@ -1,6 +1,6 @@
-import { createRequire } from 'node:module';
+import { createHostPackageLoader } from '../host-package.js';
 import { templateArity } from '../../targets/cpp/host/host-members.js';
-const require_ = createRequire(import.meta.url);
+const packageLoader = createHostPackageLoader(import.meta.url);
 /**
  * `nativeTypes`, narrowed at the boundary.
  *
@@ -22,6 +22,13 @@ const nativeTypesOf = (value) => {
 let loaded;
 let loadedSlice = null;
 let loadedInterop = null;
+/** The package entry the CLI loaded is the one this host's tables come from -- see `plugins/host-package.ts`. */
+export const adoptGeaPackage = (file) => {
+    packageLoader.adopt(file);
+    loaded = undefined;
+    loadedSlice = null;
+    loadedInterop = null;
+};
 /**
  * The host type table, from the package that owns it.
  *
@@ -62,7 +69,7 @@ export const geaNativeTypes = () => {
     const specifier = requested ?? '@geastack/geatsc-plugin-gea/host-shims';
     let shims;
     try {
-        shims = require_(specifier);
+        shims = packageLoader.load(specifier);
     }
     catch (error) {
         // Not installed is a configuration; anything else is a defect. The
@@ -375,7 +382,7 @@ export const geaCanvasInterop = () => {
         : requested.endsWith(shimSuffix)
             ? `${requested.slice(0, requested.length - shimSuffix.length)}cpp-ir`
             : requested;
-    const loaded = require_(specifier);
+    const loaded = packageLoader.load(specifier);
     const generate = loaded
         .directCanvasInteropSource;
     if (typeof generate !== 'function') {

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);
+        }
+    };
+};