@geastack/compiler 1.0.15

package/dist/semantics/normalize/host-effect-contracts.d.ts

@@ -0,0 +1,77 @@
+import ts from 'typescript';
+/**
+ * The host effect contract: what a BODILESS host declaration states about the
+ * native implementation behind it.
+ *
+ * A `declare function` has no body for the host-mutation census to read, so
+ * a call to one was an unknown callee, and handing it any value the census
+ * could not prove non-global wildcarded every host binding and every
+ * intrinsic prototype. The native WebGL upload functions only read the bytes
+ * of the typed array they are given; nothing in the program could say so.
+ *
+ * `@gea-host-inert` on the declaration says so. It states, for the native
+ * implementation, all of:
+ *
+ * - it does not retain any argument, or anything reachable from one, past
+ *   the call;
+ * - it does not write, define, delete or re-prototype a property of any
+ *   JavaScript object -- the global object, an intrinsic, or an argument;
+ * - it does not invoke program code (no callbacks, no accessors).
+ *
+ * Only the declaration can carry it, and only a declaration with no body:
+ * a body is censused like any other code, and a contract beside one would be
+ * a second, unverifiable authority. It is trusted the way every native
+ * declaration's signature is trusted -- which is exactly why it is narrow,
+ * explicit per declaration, and never inferred.
+ */
+export declare const hostInertTagName = "gea-host-inert";
+/** This one declaration states the inert host contract. */
+export declare const declarationStatesHostInert: (declaration: ts.Declaration) => boolean;
+/**
+ * Every declaration of the symbol states the contract. An overload or merged
+ * declaration without it is a callee the contract does not cover, and a
+ * single uncovered declaration refuses the whole symbol.
+ */
+export declare const symbolStatesHostInert: (symbol: ts.Symbol | undefined) => boolean;
+/**
+ * The SECOND, narrower host effect contract: `@gea-host-no-property-writes`.
+ *
+ * `@gea-host-inert` states three things at once, and a native that breaks any
+ * one of them can carry none of it. Measured on `hono-hello`: of the natives
+ * whose calls hold the global host-mutation census open, every single one
+ * breaks a clause the census was not asking about --
+ * `__gea_node_timer_start_timeout` and `__gea_http_serve` retain a callback
+ * and later run it, `__gea_node_net_read` returns a fresh Buffer -- while none
+ * of them writes a property on anything.
+ *
+ * So this states ONLY the middle clause: the native does not write, define,
+ * delete or re-prototype a property of any JavaScript object -- the global
+ * object, an intrinsic, an argument, or anything reachable from one. It says
+ * nothing about retention, and nothing about invoking program code: a native
+ * MAY store an argument and MAY call back into the program, because the
+ * writes that callback performs are censused where that callback is WRITTEN,
+ * which is the whole argument the argument stamp rests on.
+ *
+ * Building and returning a NEW object is not a write under this contract: the
+ * object did not exist for the program to observe, and installing its own
+ * initial keys changes nothing the program already held. `__gea_node_net_read`
+ * returning a Buffer and `__gea_node_process_env` returning a fresh record
+ * both qualify.
+ *
+ * Consumed at exactly one place -- the census's unknown-callee ARGUMENT stamp,
+ * whose only question is which keys a callee can put on the intrinsics its
+ * arguments reach. Every other consumer of a host contract keeps asking for
+ * the full `@gea-host-inert`, because retention and re-entry matter to them.
+ */
+export declare const hostNoPropertyWritesTagName = "gea-host-no-property-writes";
+/** This one declaration states the no-property-writes contract. */
+export declare const declarationStatesNoPropertyWrites: (declaration: ts.Declaration) => boolean;
+/**
+ * Every declaration states one of the two contracts. `@gea-host-inert` is
+ * strictly stronger, so a symbol whose declarations mix the two still writes
+ * no property; one declaration carrying neither refuses the whole symbol, for
+ * the same reason it does above.
+ */
+export declare const symbolWritesNoHostProperty: (symbol: ts.Symbol | undefined) => boolean;
+/** Does this symbol name one of those? Asked of every declaration: one match is enough. */
+export declare const symbolIsStandardLibraryMutator: (symbol: ts.Symbol | undefined) => boolean;

package/dist/semantics/normalize/host-effect-contracts.js

@@ -0,0 +1,143 @@
+import ts from 'typescript';
+import { isAmbientDeclaration } from '../ambient.js';
+/**
+ * The host effect contract: what a BODILESS host declaration states about the
+ * native implementation behind it.
+ *
+ * A `declare function` has no body for the host-mutation census to read, so
+ * a call to one was an unknown callee, and handing it any value the census
+ * could not prove non-global wildcarded every host binding and every
+ * intrinsic prototype. The native WebGL upload functions only read the bytes
+ * of the typed array they are given; nothing in the program could say so.
+ *
+ * `@gea-host-inert` on the declaration says so. It states, for the native
+ * implementation, all of:
+ *
+ * - it does not retain any argument, or anything reachable from one, past
+ *   the call;
+ * - it does not write, define, delete or re-prototype a property of any
+ *   JavaScript object -- the global object, an intrinsic, or an argument;
+ * - it does not invoke program code (no callbacks, no accessors).
+ *
+ * Only the declaration can carry it, and only a declaration with no body:
+ * a body is censused like any other code, and a contract beside one would be
+ * a second, unverifiable authority. It is trusted the way every native
+ * declaration's signature is trusted -- which is exactly why it is narrow,
+ * explicit per declaration, and never inferred.
+ */
+export const hostInertTagName = 'gea-host-inert';
+const isBodilessCallableDeclaration = (declaration) => ((ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) && declaration.body === undefined) ||
+    ts.isMethodSignature(declaration) ||
+    (ts.isSetAccessorDeclaration(declaration) && declaration.body === undefined);
+/** This one declaration states the inert host contract. */
+export const declarationStatesHostInert = (declaration) => isBodilessCallableDeclaration(declaration) &&
+    isAmbientDeclaration(declaration) &&
+    ts.getJSDocTags(declaration).some((tag) => tag.tagName.text === hostInertTagName);
+/**
+ * Every declaration of the symbol states the contract. An overload or merged
+ * declaration without it is a callee the contract does not cover, and a
+ * single uncovered declaration refuses the whole symbol.
+ */
+export const symbolStatesHostInert = (symbol) => {
+    const declarations = symbol?.declarations ?? [];
+    return declarations.length > 0 && declarations.every(declarationStatesHostInert);
+};
+/**
+ * The SECOND, narrower host effect contract: `@gea-host-no-property-writes`.
+ *
+ * `@gea-host-inert` states three things at once, and a native that breaks any
+ * one of them can carry none of it. Measured on `hono-hello`: of the natives
+ * whose calls hold the global host-mutation census open, every single one
+ * breaks a clause the census was not asking about --
+ * `__gea_node_timer_start_timeout` and `__gea_http_serve` retain a callback
+ * and later run it, `__gea_node_net_read` returns a fresh Buffer -- while none
+ * of them writes a property on anything.
+ *
+ * So this states ONLY the middle clause: the native does not write, define,
+ * delete or re-prototype a property of any JavaScript object -- the global
+ * object, an intrinsic, an argument, or anything reachable from one. It says
+ * nothing about retention, and nothing about invoking program code: a native
+ * MAY store an argument and MAY call back into the program, because the
+ * writes that callback performs are censused where that callback is WRITTEN,
+ * which is the whole argument the argument stamp rests on.
+ *
+ * Building and returning a NEW object is not a write under this contract: the
+ * object did not exist for the program to observe, and installing its own
+ * initial keys changes nothing the program already held. `__gea_node_net_read`
+ * returning a Buffer and `__gea_node_process_env` returning a fresh record
+ * both qualify.
+ *
+ * Consumed at exactly one place -- the census's unknown-callee ARGUMENT stamp,
+ * whose only question is which keys a callee can put on the intrinsics its
+ * arguments reach. Every other consumer of a host contract keeps asking for
+ * the full `@gea-host-inert`, because retention and re-entry matter to them.
+ */
+export const hostNoPropertyWritesTagName = 'gea-host-no-property-writes';
+/** This one declaration states the no-property-writes contract. */
+export const declarationStatesNoPropertyWrites = (declaration) => isBodilessCallableDeclaration(declaration) &&
+    isAmbientDeclaration(declaration) &&
+    ts.getJSDocTags(declaration).some((tag) => tag.tagName.text === hostNoPropertyWritesTagName);
+/**
+ * Every declaration states one of the two contracts. `@gea-host-inert` is
+ * strictly stronger, so a symbol whose declarations mix the two still writes
+ * no property; one declaration carrying neither refuses the whole symbol, for
+ * the same reason it does above.
+ */
+export const symbolWritesNoHostProperty = (symbol) => {
+    const declarations = symbol?.declarations ?? [];
+    return (declarations.length > 0 &&
+        declarations.every((declaration) => declarationStatesHostInert(declaration) || declarationStatesNoPropertyWrites(declaration)));
+};
+/**
+ * The standard-library callables ECMA-262 specifies to create, delete or
+ * redefine a property on an object reachable from their arguments or `this`.
+ *
+ * A library callable that escapes as a VALUE -- `.filter( Boolean )`,
+ * `const decoder = decodeURIComponent`, `emitter.on( 'x', console.error )` --
+ * is not a reason to distrust an intrinsic. These are spec-defined functions
+ * whose behaviour this compiler already relies on everywhere it says
+ * "intrinsic", and outside this list none of them writes a program-visible
+ * key: the most any of them does is RUN program code (a callback, an
+ * accessor, a `toJSON`), which is censused where that code is written. Only
+ * the ones below can install a key themselves, and the census's own
+ * reflection-mutator list is this table's seed.
+ *
+ * Keyed by DECLARING INTERFACE and member so that `Console.error` can never
+ * be confused with a mutator of the same spelling, with `''` for the global
+ * function declarations that have no interface. This is a statement about the
+ * standard library, which is one fixed, versioned text; it is NOT the host
+ * contract. `@gea-host-inert` stays per declaration and never inferred,
+ * because a host native's behaviour is stated by whoever wrote the native.
+ */
+const LIBRARY_MUTATOR_MEMBERS = new Map([
+    ['ObjectConstructor', new Set(['assign', 'defineProperty', 'defineProperties', 'setPrototypeOf', 'freeze', 'seal', 'preventExtensions'])],
+    ['Reflect', new Set(['set', 'defineProperty', 'deleteProperty', 'setPrototypeOf', 'preventExtensions', 'apply', 'construct'])],
+    ['Array', new Set(['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'fill', 'copyWithin'])],
+    ['Function', new Set(['call', 'apply', 'bind'])],
+    ['CallableFunction', new Set(['call', 'apply', 'bind'])],
+    ['NewableFunction', new Set(['call', 'apply', 'bind'])],
+    ['', new Set(['eval', 'Function'])]
+]);
+const TYPED_ARRAY_MUTATORS = new Set(['set', 'sort', 'reverse', 'fill', 'copyWithin']);
+const TYPED_ARRAY_INTERFACE = /^(Int8|Uint8|Uint8Clamped|Int16|Uint16|Int32|Uint32|Float16|Float32|Float64|BigInt64|BigUint64)Array$/;
+const declaringInterfaceName = (declaration) => {
+    const owner = declaration.parent;
+    if (owner && (ts.isInterfaceDeclaration(owner) || ts.isClassDeclaration(owner)))
+        return owner.name?.text ?? '';
+    if (owner && ts.isModuleBlock(owner) && ts.isModuleDeclaration(owner.parent))
+        return owner.parent.name.getText();
+    if (owner && ts.isModuleDeclaration(owner))
+        return owner.name.getText();
+    return '';
+};
+/** Does this symbol name one of those? Asked of every declaration: one match is enough. */
+export const symbolIsStandardLibraryMutator = (symbol) => (symbol?.declarations ?? []).some((declaration) => {
+    const member = declaration.name;
+    const name = member && (ts.isIdentifier(member) || ts.isStringLiteralLike(member)) ? member.text : symbol?.getName();
+    if (name === undefined)
+        return false;
+    const owner = declaringInterfaceName(declaration);
+    if (TYPED_ARRAY_INTERFACE.test(owner))
+        return TYPED_ARRAY_MUTATORS.has(name);
+    return LIBRARY_MUTATOR_MEMBERS.get(owner)?.has(name) === true;
+});

package/dist/semantics/normalize/host-mutation-computed-keys.d.ts

@@ -0,0 +1,38 @@
+import type ts from 'typescript';
+import type { ValueFlowIndex } from './flow/model.js';
+import { type ComputedKeySetAuthority } from './flow/computed-key-set.js';
+import { type IntrinsicProtocolRequirement } from './deferred-intrinsic-protocols.js';
+/**
+ * A computed write key the host-mutation census may narrow from `every` to a
+ * finite set -- three's `this[ key ] = newValue` under `for ( const key in
+ * values )` in `Material.setValues` and `Texture.setValues`.
+ *
+ * `computedKeySetOf` proves the set under intrinsic assumptions. The census
+ * cannot publish those as ledger obligations (a failed one would be a
+ * certification diagnostic, where a refused key set only costs precision),
+ * so it takes them as data and checks them against its own final result:
+ *
+ * - "Object.prototype has no enumerable key" (the `for-in` arm) is an
+ *   INDUCTIVE invariant the census proves itself. The only enumerable keys
+ *   Object.prototype can have are keys this program wrote on it -- through a
+ *   receiver that may be any intrinsic, or on Object.prototype itself -- so
+ *   the census adds every such key to the set, re-running until that set of
+ *   keys stops growing. Nothing here assumes the receiver of the write is
+ *   anything in particular: the census proves that side independently.
+ * - `Object.keys` and the Array iteration protocol are per-key requirements
+ *   the census discharges against its own taint; a failed one re-runs the
+ *   census with every computed key unknown.
+ * - Anything the key-set proof registers on the flow's ledger by itself is
+ *   captured here, never published, and checked the same way.
+ * @semanticCategory generic-primitive
+ */
+export interface CensusComputedKeys {
+    /** Every key the expression can evaluate to, apart from Object.prototype's inherited enumerable keys. */
+    readonly keys: ReadonlySet<string>;
+    /** The set also holds every enumerable key Object.prototype may carry (a `for-in` binding). */
+    readonly inheritsObjectPrototypeKeys: boolean;
+    /** Intrinsic obligations the proof assumed; the census checks them against its own result. */
+    readonly requirements: readonly IntrinsicProtocolRequirement[];
+}
+export type CensusComputedKeysOf = (key: ts.Expression) => CensusComputedKeys | null;
+export declare const createCensusComputedKeysOf: (checker: ts.TypeChecker, flow: ValueFlowIndex, authority: Omit<ComputedKeySetAuthority, "intrinsicIntact">) => CensusComputedKeysOf;

package/dist/semantics/normalize/host-mutation-computed-keys.js

@@ -0,0 +1,26 @@
+import { arrayIterationKeys, computedKeySetOf } from './flow/computed-key-set.js';
+import { deferredIntrinsicProtocolLedgerOf } from './deferred-intrinsic-protocols.js';
+export const createCensusComputedKeysOf = (checker, flow, authority) => {
+    const ledger = deferredIntrinsicProtocolLedgerOf(flow);
+    return (key) => {
+        let inherits = false;
+        const assumed = [];
+        const work = () => computedKeySetOf(checker, flow, key, {
+            ...authority,
+            checker,
+            intrinsicIntact: (intrinsic, member, location) => {
+                if (intrinsic === 'Object' && member === undefined)
+                    inherits = true;
+                else if (intrinsic === 'Object')
+                    assumed.push({ intrinsic, member: member, location });
+                else
+                    assumed.push({ intrinsic, prototypeKeys: arrayIterationKeys, location });
+                return true;
+            }
+        });
+        const run = ledger ? ledger.capture(work) : { value: work(), requirements: [] };
+        if (run.value === null)
+            return null;
+        return { keys: run.value, inheritsObjectPrototypeKeys: inherits, requirements: [...assumed, ...run.requirements] };
+    };
+};

package/dist/semantics/normalize/host-mutation-key-reader.d.ts

@@ -0,0 +1,66 @@
+import ts from 'typescript';
+import { type MutationKey } from './host-mutation-keys.js';
+/** `__proto__` is never an ordinary key: a [[Set]] of it runs the accessor that replaces a prototype. */
+export declare const keyOfName: (name: string) => MutationKey;
+/**
+ * Whether a key expression is a PROGRAM-DECLARED unique symbol -- one this
+ * program made with `Symbol()`, not one the standard library declares on
+ * `SymbolConstructor`.
+ *
+ * Such a key names NOTHING this census models. A symbol is not a string and
+ * never converts to one implicitly, so it can touch no string-named
+ * obligation; and symbol-keyed obligations are spelled `@@iterator` after the
+ * WELL-KNOWN symbols, which a program-declared one can never be. So the write
+ * is invisible to every question the census asks -- which is why
+ * `keysOfKeyExpression` answers it with no keys at all rather than `every`.
+ *
+ * ⛔ Standard-library-declared is the whole guard, in both directions.
+ * `X.prototype[Symbol.iterator] = f` genuinely redefines intrinsic behavior
+ * under a non-string key, so it must stay `every`. A bare `symbol`-typed key
+ * (not `unique`) names an unknown symbol and fails closed the same way.
+ *
+ * The unique-symbol TYPE is sound to trust here in a way a string-literal type
+ * is not (see `createMutationKeyReader`'s own note): a `unique symbol` type is
+ * inhabited by exactly one value by construction, and there is no widening
+ * conversion into it the way an `any` widens into a `'a' | 'b'` slot.
+ */
+export declare const isProgramDeclaredSymbolKey: (type: ts.Type) => boolean;
+/**
+ * Which keys a write names, for the host-mutation census.
+ *
+ * Every answer here is a SUPERSET of the keys the write can reach at run
+ * time; `every` is the answer whenever this reader cannot prove less. Three
+ * sources are trusted and nothing else:
+ *
+ * - the syntax: a property name, a string literal, a numeric literal (whose
+ *   key is its canonical `ToString`, so `o[1.50]` is "1.5");
+ * - the number representation: an expression the checker types as `number`
+ *   (or a number literal type, or a numeric enum) is carried as a native
+ *   double, so its key is some `ToString(Number)` -- the NUMERIC domain, not
+ *   an array index, since `-1`, `1.5` and `NaN` are numbers too.
+ * - the boolean representation: an expression the checker types as `boolean`
+ *   is carried as a native two-state scalar, so its key is exactly "true" or
+ *   "false" (`ToPropertyKey` of a boolean is `ToString(Boolean)`).
+ *
+ * A string-literal TYPE is deliberately not trusted: nothing in the compiled
+ * representation stops an `any` from carrying "zzz" into a cell typed `'a'`.
+ * A caller-supplied `computedKeysOf` authority may prove a finite key set;
+ * that is its claim to justify, and `null` from it keeps the key unknown.
+ * (The census's own authority is `host-mutation-computed-keys.ts`.)
+ */
+export declare const createMutationKeyReader: (checker: ts.TypeChecker, computedKeysOf: (key: ts.Expression) => readonly MutationKey[] | null, publishedTypeAt?: (key: ts.Expression) => ts.Type) => {
+    readonly keysOfKeyExpression: (expression: ts.Expression | undefined) => readonly MutationKey[];
+    readonly keysOfAccess: (access: ts.PropertyAccessExpression | ts.ElementAccessExpression) => readonly MutationKey[];
+    readonly keysOfPropertyName: (name: ts.PropertyName) => readonly MutationKey[];
+};
+/**
+ * Keys a host or library ACCESSOR owns. A write of such a key through an
+ * unknown receiver may run that accessor, whose effect no body states, so
+ * the census treats the key as unknown. `__proto__` is always one: it is
+ * `Object.prototype`'s accessor, which the standard library does not
+ * declare, and running it replaces a prototype.
+ *
+ * A setter covered by `@gea-host-inert` states its effect and is not listed;
+ * a key is listed when ANY declaration of a setter by that name is uncovered.
+ */
+export declare const hostAccessorNamesOf: (declarationFiles: readonly ts.SourceFile[], files: readonly ts.SourceFile[]) => ReadonlySet<string>;

package/dist/semantics/normalize/host-mutation-key-reader.js

@@ -0,0 +1,192 @@
+import ts from 'typescript';
+import { isAmbientDeclaration } from '../ambient.js';
+import { unwrapErasedExpression } from './producers/erasure.js';
+import { declarationStatesHostInert } from './host-effect-contracts.js';
+import { everyKey, namedKey, numericKeys, numericLiteralKey } from './host-mutation-keys.js';
+/** `__proto__` is never an ordinary key: a [[Set]] of it runs the accessor that replaces a prototype. */
+export const keyOfName = (name) => (name === '__proto__' ? everyKey : namedKey(name));
+/**
+ * Whether a key expression is a PROGRAM-DECLARED unique symbol -- one this
+ * program made with `Symbol()`, not one the standard library declares on
+ * `SymbolConstructor`.
+ *
+ * Such a key names NOTHING this census models. A symbol is not a string and
+ * never converts to one implicitly, so it can touch no string-named
+ * obligation; and symbol-keyed obligations are spelled `@@iterator` after the
+ * WELL-KNOWN symbols, which a program-declared one can never be. So the write
+ * is invisible to every question the census asks -- which is why
+ * `keysOfKeyExpression` answers it with no keys at all rather than `every`.
+ *
+ * ⛔ Standard-library-declared is the whole guard, in both directions.
+ * `X.prototype[Symbol.iterator] = f` genuinely redefines intrinsic behavior
+ * under a non-string key, so it must stay `every`. A bare `symbol`-typed key
+ * (not `unique`) names an unknown symbol and fails closed the same way.
+ *
+ * The unique-symbol TYPE is sound to trust here in a way a string-literal type
+ * is not (see `createMutationKeyReader`'s own note): a `unique symbol` type is
+ * inhabited by exactly one value by construction, and there is no widening
+ * conversion into it the way an `any` widens into a `'a' | 'b'` slot.
+ */
+export const isProgramDeclaredSymbolKey = (type) => {
+    const members = type.isUnion() ? type.types : [type];
+    return (members.length > 0 &&
+        members.every((member) => (member.flags & ts.TypeFlags.UniqueESSymbol) !== 0 &&
+            (member.symbol.declarations ?? []).length > 0 &&
+            !(member.symbol.declarations ?? []).some((declaration) => declaration.getSourceFile().hasNoDefaultLib)));
+};
+/**
+ * Which keys a write names, for the host-mutation census.
+ *
+ * Every answer here is a SUPERSET of the keys the write can reach at run
+ * time; `every` is the answer whenever this reader cannot prove less. Three
+ * sources are trusted and nothing else:
+ *
+ * - the syntax: a property name, a string literal, a numeric literal (whose
+ *   key is its canonical `ToString`, so `o[1.50]` is "1.5");
+ * - the number representation: an expression the checker types as `number`
+ *   (or a number literal type, or a numeric enum) is carried as a native
+ *   double, so its key is some `ToString(Number)` -- the NUMERIC domain, not
+ *   an array index, since `-1`, `1.5` and `NaN` are numbers too.
+ * - the boolean representation: an expression the checker types as `boolean`
+ *   is carried as a native two-state scalar, so its key is exactly "true" or
+ *   "false" (`ToPropertyKey` of a boolean is `ToString(Boolean)`).
+ *
+ * A string-literal TYPE is deliberately not trusted: nothing in the compiled
+ * representation stops an `any` from carrying "zzz" into a cell typed `'a'`.
+ * A caller-supplied `computedKeysOf` authority may prove a finite key set;
+ * that is its claim to justify, and `null` from it keeps the key unknown.
+ * (The census's own authority is `host-mutation-computed-keys.ts`.)
+ */
+export const createMutationKeyReader = (checker, computedKeysOf, publishedTypeAt = (key) => checker.getTypeAtLocation(key)) => {
+    const numericType = (type) => type.isUnion()
+        ? type.types.every(numericType)
+        : (type.flags & ts.TypeFlags.NumberLike) !== 0 && (type.flags & ~ts.TypeFlags.NumberLike) === 0;
+    /**
+     * Named keys for a checker type this reader trusts completely: the
+     * boolean domain, and nothing wider. `ToPropertyKey` of `true`/`false` is
+     * exactly the string "true"/"false" (ECMA-262 7.1.14 via
+     * ToString(Boolean)), so a `boolean`-typed key names exactly those two
+     * strings -- not an approximation, the complete set. This is trustworthy
+     * for the same reason the numeric domain above is: `primitiveCarrier`
+     * (`src/representation/primitives.ts`) gives `boolean` its own native
+     * scalar domain, so the COMPILED storage for a boolean-typed cell can only
+     * ever hold one of two bit patterns, independent of whatever TypeScript's
+     * structural assignability allowed elsewhere.
+     *
+     * A string-literal TYPE is deliberately NOT extended the same trust, even
+     * though it looks like the same shape of fact. `primitiveCarrier` gives
+     * `string` -- literal or not -- the one generic `{ kind: 'string' }`
+     * carrier with no narrower storage, and TypeScript lets an `any` flow into
+     * a `'a' | 'b'`-typed slot (a parameter, a field) with zero diagnostic.
+     * Trusting the checker's literal-union TYPE there would let a value the
+     * compiled representation cannot distinguish from "any string" certify as
+     * bounded to `{'a','b'}` -- the exact hole the class doc above already
+     * calls out ("nothing in the compiled representation stops an `any` from
+     * carrying 'zzz' into a cell typed `'a'`"). A `const` bound once to a
+     * literal initializer is a DIFFERENT, sound fact (no other write exists to
+     * contaminate), and it is already covered -- by construction, not by
+     * naming it here -- through the `computedKeysOf` value-flow authority.
+     */
+    const namedKeysOfLiteralType = (type) => {
+        if (type.isUnion()) {
+            const keys = [];
+            for (const member of type.types) {
+                const memberKeys = namedKeysOfLiteralType(member);
+                if (memberKeys === null)
+                    return null;
+                keys.push(...memberKeys);
+            }
+            return keys.some((key) => key.kind === 'every') ? null : keys;
+        }
+        if (type.flags & ts.TypeFlags.BooleanLiteral)
+            return [namedKey(checker.typeToString(type) === 'true' ? 'true' : 'false')];
+        if (type.flags & ts.TypeFlags.Boolean)
+            return [namedKey('true'), namedKey('false')];
+        return null;
+    };
+    const keysOfKeyExpression = (expression) => {
+        if (!expression)
+            return [everyKey];
+        const current = unwrapErasedExpression(expression);
+        if (ts.isStringLiteralLike(current))
+            return [keyOfName(current.text)];
+        if (ts.isNumericLiteral(current)) {
+            const key = numericLiteralKey(current.text);
+            return [key === null ? numericKeys : namedKey(key)];
+        }
+        if (ts.isPrefixUnaryExpression(current) &&
+            current.operator === ts.SyntaxKind.MinusToken &&
+            ts.isNumericLiteral(unwrapErasedExpression(current.operand))) {
+            const key = numericLiteralKey(`-${unwrapErasedExpression(current.operand).text}`);
+            return [key === null ? numericKeys : namedKey(key)];
+        }
+        if (ts.isConditionalExpression(current)) {
+            const keys = [...keysOfKeyExpression(current.whenTrue), ...keysOfKeyExpression(current.whenFalse)];
+            return keys.some((key) => key.kind === 'every') ? [everyKey] : keys;
+        }
+        const type = publishedTypeAt(current);
+        if (numericType(type))
+            return [numericKeys];
+        // NO KEYS, not `every`. A program-declared symbol key names nothing this
+        // census models, so the honest answer is the empty set -- see
+        // `isProgramDeclaredSymbolKey` for why that is sound rather than merely
+        // convenient. `[]` reaches every consumer as "taint nothing", which is the
+        // behaviour: `taintSurfaceKey` is never called, so no wildcard is stamped.
+        //
+        // Measured on hono. `@hono/node-server`'s `request.ts` attaches its private
+        // state with module-level `Symbol()` keys through a `Record<string |
+        // symbol, any>` parameter (`request[bodyConsumedDirectlyKey] = true`), and
+        // hono's routers do the same ~36 times. Each one stamped `*` on the whole
+        // host surface, which poisoned every read of every authenticated host
+        // global -- including all 39 `Buffer.*` reads in node-compat's own
+        // `globals.ts`, whose `Buffer.from(...)` calls then cited results no
+        // producer published. None of that has anything to do with `request.ts`.
+        if (isProgramDeclaredSymbolKey(type))
+            return [];
+        const literalKeys = namedKeysOfLiteralType(type);
+        if (literalKeys)
+            return literalKeys;
+        const computed = computedKeysOf(current);
+        return !computed || computed.some((key) => key.kind === 'every') ? [everyKey] : computed;
+    };
+    const keysOfAccess = (access) => ts.isPropertyAccessExpression(access) ? [keyOfName(access.name.text)] : keysOfKeyExpression(access.argumentExpression);
+    const keysOfPropertyName = (name) => {
+        if (ts.isIdentifier(name) || ts.isStringLiteralLike(name) || ts.isPrivateIdentifier(name))
+            return [keyOfName(name.text)];
+        if (ts.isNumericLiteral(name)) {
+            const key = numericLiteralKey(name.text);
+            return [key === null ? numericKeys : namedKey(key)];
+        }
+        if (ts.isComputedPropertyName(name))
+            return keysOfKeyExpression(name.expression);
+        return [everyKey];
+    };
+    return { keysOfKeyExpression, keysOfAccess, keysOfPropertyName };
+};
+/**
+ * Keys a host or library ACCESSOR owns. A write of such a key through an
+ * unknown receiver may run that accessor, whose effect no body states, so
+ * the census treats the key as unknown. `__proto__` is always one: it is
+ * `Object.prototype`'s accessor, which the standard library does not
+ * declare, and running it replaces a prototype.
+ *
+ * A setter covered by `@gea-host-inert` states its effect and is not listed;
+ * a key is listed when ANY declaration of a setter by that name is uncovered.
+ */
+export const hostAccessorNamesOf = (declarationFiles, files) => {
+    const names = new Set(['__proto__']);
+    const visit = (node, ambientOnly) => {
+        if (ts.isSetAccessorDeclaration(node) && (!ambientOnly || isAmbientDeclaration(node)) && !declarationStatesHostInert(node)) {
+            const name = node.name;
+            if (ts.isIdentifier(name) || ts.isStringLiteralLike(name) || ts.isNumericLiteral(name))
+                names.add(name.text);
+        }
+        ts.forEachChild(node, (child) => visit(child, ambientOnly));
+    };
+    for (const file of declarationFiles)
+        visit(file, false);
+    for (const file of files)
+        if (!file.isDeclarationFile)
+            visit(file, true);
+    return names;
+};