@geastack/compiler 1.0.15

package/dist/semantics/frontend.d.ts

@@ -0,0 +1,504 @@
+import type { PackageSource } from './package-sources.js';
+import type { CommonJsWrapperDeclaration, HostNativeTypeDeclaration, HostOwnedDeclaration } from '../plugins/model.js';
+import { type HostMethodBindingTable } from './host-methods.js';
+import type { DeclarationId, FunctionId, NodeId, OperationFamily, RegionId, StructuralTypeId } from '../identity/ids.js';
+import type { DiagnosticEvidence, DiagnosticLocation } from '../diagnostics/model.js';
+import type { TypedArrayElementDomain } from '../representation/model.js';
+import type { KeyedCollectionFamily, RegExpDeclarationKind, StandardBufferKind } from '../representation/policies.js';
+import type { SemanticGraph } from './model/graph.js';
+import type { FamilyProducer } from './normalize/contribution.js';
+import type { ProducerContext } from './normalize/producer-context.js';
+import { type ClassCopyKey } from './normalize/structural.js';
+import { type DeadTypeofGuardCensus } from './normalize/dead-typeof-guards.js';
+import { type CensusRefusal } from './normalize/census-refusal.js';
+import type { CellFactsPublication } from './normalize/cells/index.js';
+import type { StructuralDisagreement, StructuralFormViolation } from './normalize/structural-rules.js';
+import type { DiagnosticSourcePreparationAudit } from './diagnostic-source-preparation.js';
+import type { HostProtocolBinding } from './host-protocols.js';
+/**
+ * The frontend boundary.
+ *
+ * This is the last place a TypeScript AST exists. Everything it returns is
+ * target-neutral and sealed, so no later layer can reach back and answer a
+ * question the frontend already answered differently.
+ *
+ * Producers are supplied by the caller rather than imported here, so installing
+ * or withholding a family is an explicit decision visible at the call site --
+ * and so a family with no producer is reported by the census instead of quietly
+ * contributing nothing.
+ */
+export interface FrontendInput {
+    /** Package checkouts prepared by the project loader; the compiler discovers their implementation entries. */
+    readonly packageSources?: readonly PackageSource[];
+    readonly declarationModules?: ReadonlySet<string>;
+    readonly dynamicFallback?: boolean;
+    readonly hostMethodBindings?: HostMethodBindingTable;
+    /** Exact host declarations eligible for checker-derived TypedArray inheritance. */
+    readonly hostTypedArrayDeclarations?: readonly HostOwnedDeclaration[];
+    readonly rootFileNames: readonly string[];
+    /** The project file defining this program, or `null` to use this compiler's defaults alone. */
+    readonly projectFileName?: string | null;
+    /** Built from the context once the program exists, so producers share one counter. */
+    readonly producers: (context: ProducerContext) => readonly FamilyProducer[];
+    /**
+     * The declared type names the installed hosts own, to the type their runtime
+     * carries values of each in (`PluginCapabilities.nativeTypes`).
+     *
+     * Supplied rather than known, for the same reason `producers` is: a compiler
+     * that carried this table itself would be hand-maintaining one library's
+     * object model inside a language compiler. Absent, nothing binds by name and
+     * this file behaves exactly as it did.
+     */
+    readonly nativeTypes?: ReadonlyMap<string, string>;
+    /** Exact host-owned native type declarations; see `PluginCapabilities.nativeTypesByDeclaration`. */
+    readonly nativeTypesByDeclaration?: ReadonlyMap<string, HostNativeTypeDeclaration>;
+    /** Exact host-owned singleton declarations; see `PluginCapabilities.hostSingletonDeclarations`. */
+    readonly hostSingletonDeclarations?: ReadonlyMap<string, HostOwnedDeclaration>;
+    /**
+     * The ambient global names the installed hosts declare they do NOT provide
+     * (`PluginCapabilities.absentGlobals`, unioned).
+     *
+     * Supplied rather than known, for exactly the reason `nativeTypes` is: which
+     * globals a target lacks is a fact about that target, and a compiler that
+     * carried the list itself would be asserting something about the program's
+     * environment that nothing in the program says. Absent, every ambient
+     * declaration keeps the treatment it has today. See `absent-globals.ts` for
+     * the silent miscompile this exists to stop.
+     */
+    readonly absentGlobals?: ReadonlySet<string>;
+    /**
+     * The standard library class names the backend implements natively, whose
+     * carrier it states in `nativeTypes` above -- see `bindStandardClasses`
+     * (semantics/host-protocols.ts) and `coreNativeTypes`
+     * (targets/cpp/host/core-globals.ts). Empty means the target implements no
+     * standard-library class of its own, which is the honest default: nothing
+     * here is derived from a name this file knows.
+     */
+    readonly standardClasses?: ReadonlySet<string>;
+    /**
+     * Class member names an installed host reaches without the program spelling
+     * them -- see `PluginCapabilities.reachedMemberKeys`, and
+     * `reachability.ts`'s `hostReachedMemberKeys` for what the walk does with
+     * them.
+     */
+    readonly hostReachedMemberKeys?: ReadonlySet<string>;
+    /**
+     * The `hostFunctions` of every installed host whose programs take the host
+     * mutation census's wildcard (`PluginCapabilities.refusesObjectPrototypeAbsenceProofs`).
+     * When reachable code names one of them, the two absence proofs that rest
+     * on an `Object.prototype` key obligation refuse up front, and the read
+     * stays boxed instead of costing the program its certificate. Carried on
+     * the deferred ledger, which is what both proofs consult.
+     */
+    readonly hostFunctionsRefusingObjectPrototypeAbsenceProofs?: ReadonlySet<string>;
+    /**
+     * The global names the installed hosts own as PATHS rather than as values
+     * (`PluginCapabilities.hostNamespaces.roots`). Nothing about one is a host
+     * protocol: `Window@1` for `window` demands a native boundary no plugin can
+     * state, because there is no value to carry.
+     */
+    readonly hostNamespaceRoots?: ReadonlySet<string>;
+    /** Exact declaration-owned namespace roots; configured names mask name-only admission. */
+    readonly hostNamespaceRootDeclarations?: readonly HostOwnedDeclaration[];
+    /**
+     * Every dotted path an installed host states a member under
+     * (`PluginCapabilities.hostNamespaces.methods`/`.properties`' own keys, e.g.
+     * `navigator.mediaDevices.getUserMedia`), so a path with one of these as a
+     * prefix is itself a namespace SEGMENT and not a value either -- the same
+     * fact `hostNamespaceRoots` states for a bare top-level name, one level
+     * deeper. Without this, a member reached only as `navigator.mediaDevices`
+     * (never spelled by the program, only implied by `Navigator`'s own
+     * declaration) was admitted as an ordinary host protocol needing its own
+     * native boundary -- `MediaDevices@1` -- when the host states no carrier for
+     * it and never will: `navigator.mediaDevices.getUserMedia(...)` is a path to
+     * one free function, the same shape `Display.getBrightness()` already is,
+     * and the emitter's own `isHostNamespacePath` (`targets/cpp/host-members.ts`)
+     * already resolves an arbitrarily long path this way -- this is the frontend
+     * learning the identical fact so preflight stops demanding a boundary the
+     * path never needed.
+     */
+    readonly hostNamespacePaths?: ReadonlySet<string>;
+    /**
+     * The type an installed host carries the one object behind each of its
+     * namespace roots in (`PluginCapabilities.hostNamespaceRootTypes`), keyed by
+     * the root's own name -- `window` -> `gea::host::WindowFacade`.
+     *
+     * `hostNamespaceRoots` above says a root has no value to carry *as a cell*:
+     * nothing named `window` is materialized, and every use of it resolves to a
+     * spelling. It does not say the root is nothing -- `gea::host::window` is one
+     * real object the host holds -- and a carrier still has to be selected for
+     * the reference and the binding read the program publishes for it. Without
+     * this, the only answer available is the root's ambient DOM declaration, and
+     * `Window & typeof globalThis` flattens into a struct no host implements.
+     * Absent, nothing is recorded and every root derives exactly as it did.
+     */
+    readonly hostNamespaceRootTypes?: ReadonlyMap<string, string>;
+    /** Exact host-owned declarations that authenticate CommonJS wrapper state. */
+    readonly commonJsGlobals?: ReadonlyMap<string, CommonJsWrapperDeclaration>;
+    /** Exact loader spellings a host build maps into its native builtin registry. */
+    readonly commonJsBuiltinModules?: ReadonlyMap<string, string>;
+    /** Exact source implementation for each canonical runtime builtin. */
+    readonly commonJsBuiltinModuleSources?: ReadonlyMap<string, string>;
+    /**
+     * Rewrites the installed plugins perform on a file's text before this program
+     * parses it (`PluginInstance.transformSource`), in installation order.
+     *
+     * Threaded rather than known, like `producers` and `nativeTypes`: what a
+     * library's own syntax means is the library's to say, and the one place
+     * saying it can still change what the checker sees is before the parse.
+     */
+    readonly sourceTransforms?: readonly ((input: {
+        readonly fileName: string;
+        readonly text: string;
+    }) => string | null)[];
+    /**
+     * Whether the roots are JavaScript that carries its own types in JSDoc.
+     *
+     * Stated as a fact about the INPUT, not as a compiler-options passthrough:
+     * `allowJs`/`checkJs` is how TypeScript spells it, and that spelling belongs
+     * here, in the one layer allowed to name `typescript` at all. A caller
+     * outside `semantics/` can say what its sources are; it cannot say how the
+     * checker should be configured, because then two authorities would decide
+     * what a program means.
+     *
+     * `checkJs` travels with `allowJs` and is not separable. Admitting a `.js`
+     * root without checking it makes every JSDoc annotation invisible: the file
+     * still compiles, every function becomes implicitly `any`, and a program that
+     * is fully typed at its source turns into a boxed one with no diagnostic
+     * saying why. The gea build pipeline's vite bundle is exactly this shape --
+     * plain JS whose types are JSDoc plus a generated `.d.ts` reference -- so the
+     * unchecked reading is never the one a caller wants.
+     */
+    readonly javaScriptSources?: boolean;
+    /** File text this compilation uses instead of what is on disk -- see `ProgramInput.sourceOverlay`. */
+    readonly sourceOverlay?: ReadonlyMap<string, string>;
+    /** How each file's own import specifiers resolve -- see `ProgramInput.moduleResolution`. */
+    readonly moduleResolution?: ReadonlyMap<string, ReadonlyMap<string, string>>;
+    /** Whether the caller stated the module set -- see `ProgramInput.statedModuleSet`. */
+    readonly statedModuleSet?: boolean;
+    /** Caller-stated classic-script lexical realm boundary; see `ProgramInput.closedScriptScope`. */
+    readonly closedScriptScope?: boolean;
+}
+export interface FrontendResult {
+    readonly dynamicFallbackTypes: ReadonlySet<StructuralTypeId>;
+    /** Object types written with values their declared fields cannot hold (`anyKeyedWriteTypes`); boxed in every mode. */
+    readonly dynamicWrittenTypes: ReadonlySet<StructuralTypeId>;
+    /** Exact source functions whose own mutable Function-object table requires fallback storage. */
+    readonly dynamicFallbackCallables: ReadonlySet<FunctionId>;
+    readonly graph: SemanticGraph;
+    readonly sourcePreparations: readonly DiagnosticSourcePreparationAudit[];
+    /**
+     * Declared types that are host handles rather than program-defined records.
+     *
+     * Only the frontend can answer this, because only the frontend can ask the
+     * checker. It is not a lookup table of known names: `JSX.Element` is
+     * whatever the checked program's own JSX namespace resolves it to, and the
+     * checker is what resolves it -- exactly as it decides intrinsic-vs-component
+     * from a tag's first character. A different program declaring a different
+     * `JSX` namespace binds a different declaration, and a program with no JSX
+     * binds nothing.
+     */
+    readonly hostProtocols: ReadonlyMap<DeclarationId, HostProtocolBinding>;
+    /** Standard well-known symbols, kept by declaration identity after their keys normalize to `sym(declaration)`. */
+    readonly wellKnownSymbols: ReadonlyMap<DeclarationId, string>;
+    /**
+     * The ABI name a host defines a cell under, for every ambient value this
+     * program reads but never introduces -- an imported `mount`, a global
+     * `Math`, a `declare const` in a framework's declaration file.
+     *
+     * `projectBindingPlacements` turns these into `BindingStorage.kind ===
+     * 'external'`, which is the same placement an in-file `declare const`
+     * already gets through `BindingOperation.external`. The two routes exist
+     * because only one of them can: an in-file declaration is a census
+     * candidate and publishes an introduction, while a declaration in a
+     * declaration file is never walked at all, so nothing publishes one for it.
+     */
+    readonly externalBindings: ReadonlyMap<DeclarationId, string>;
+    /** Ambient declarations the installed host authenticated as CommonJS wrapper parameters. */
+    readonly commonJsBindings: ReadonlyMap<DeclarationId, 'require' | 'exports' | 'module'>;
+    /** Ambient values authenticated as host singletons by complete declaration identity. */
+    readonly hostSingletonBindings: ReadonlySet<DeclarationId>;
+    /** Namespace roots authenticated by their complete checker declaration identity. */
+    readonly hostNamespaceBindings: ReadonlySet<DeclarationId>;
+    /**
+     * Which of those an installed host declared it does NOT provide, so the
+     * projection places a cell rather than an `extern`. See `absent-globals.ts`.
+     */
+    readonly absentBindings: ReadonlySet<DeclarationId>;
+    /**
+     * Operations that sit inside a `typeof X !== 'undefined' && x instanceof X`
+     * guard's consequent, where `X` resolves by symbol to a host-declared-absent
+     * ambient value. See `dead-typeof-guards.ts` for the exact shape matched and
+     * why this cannot be answered from any operand's type.
+     */
+    readonly deadTypeofGuards: DeadTypeofGuardCensus;
+    /**
+     * Where a node identity is in the source, or `null` for one this program
+     * has no node for.
+     *
+     * ⛔ DISPLAY ONLY, and the reason it lives here rather than being recomputed
+     * by a reporter: identities are ORDINALS from `identities.ts`'s own
+     * deterministic walk, not positions, so the only honest way back to a line
+     * number is that same walk -- and this is the layer that has it. A reporter
+     * that guessed would print a plausible file and line for the wrong node,
+     * which is worse than printing none.
+     *
+     * The index is built on the FIRST call and only then: a compilation with a
+     * clean sweep never asks, and pays nothing.
+     */
+    readonly locationOfNode: (node: NodeId) => DiagnosticLocation | null;
+    /**
+     * `locationOfNode`'s twin for a DeclarationId (and so, through
+     * `declarationOfFunction`, a FunctionId) -- a stage past the frontend that
+     * never had a `ts.Node` to mint a NodeId from, only the identity a
+     * `function-object` allocation or a declaration census already published.
+     * ⛔ DISPLAY ONLY, for the same reason `locationOfNode` is: resolved through
+     * the SAME position index, never a second one.
+     */
+    readonly locationOfDeclaration: (declaration: DeclarationId) => DiagnosticLocation | null;
+    /** The source text of a node identity, through the same walk as `locationOfNode`, for display only. */
+    readonly textOfNode: (node: NodeId) => string | null;
+    /**
+     * The file each of those declarations lives in.
+     *
+     * The name a host defines a cell under is not always enough to say *which*
+     * cell: one host can declare the same name in two of its own files, meaning
+     * two different things by it (Apple's `installRootView`, in UIKit and in
+     * AppKit). The declaration is what tells them apart, and the file is the
+     * coordinate a host states its own tables in -- so this carries it, and a host
+     * with no such pair never looks at it.
+     */
+    readonly externalBindingFiles: ReadonlyMap<DeclarationId, string>;
+    /**
+     * Which of those declarations the STANDARD LIBRARY declares, from
+     * `SourceFile.hasNoDefaultLib` -- see `HostCensus.standardLibrary` for the
+     * whole of why the distinction is needed and why that flag is the authority
+     * rather than a file-path match.
+     */
+    readonly standardLibraryBindings: ReadonlySet<DeclarationId>;
+    /**
+     * This program's module bodies, in the order ECMA-262 evaluates them.
+     *
+     * A module body is a region like any other, but unlike a function it is not
+     * called by anything in the program: it RUNS, once, when the module graph is
+     * evaluated. Nothing downstream of here could recover the order -- the graph
+     * records each body's contents and its identity, not the import edges that
+     * decide which runs first -- so the frontend, which has the checker and can
+     * resolve a specifier to a file, is the only place that can state it.
+     *
+     * A target needs it to emit a program ENTRY: a `main`-shaped function that
+     * runs the modules in order. Without one an emitted program is a set of
+     * bodies nothing calls.
+     */
+    readonly moduleOrder: readonly RegionId[];
+    /**
+     * The file each identity segment names, for every compiled (non-declaration)
+     * source file: `f12` -> its `fileName`.
+     *
+     * Display evidence, not authority. The identities themselves carry only the
+     * index (`identities.ts`), and nothing downstream may decide anything from
+     * the name -- it exists so a target that lays a program out as one
+     * translation unit per source file can NAME those units after the files
+     * whose bodies they hold, which is the one thing an index cannot do.
+     */
+    readonly sourceFileNames: ReadonlyMap<string, string>;
+    /**
+     * Declared types that are one of the eight standard TypedArray view
+     * interfaces, keyed by the *instance* type's declaration and valued by the
+     * element width/encoding that view stores -- `Uint8Array`'s declaration
+     * maps to `'uint8'`, `Int32Array`'s to `'int32'`, and so on. See
+     * `typedArrayElementBindings` for how this is found.
+     */
+    readonly typedArrayElements: ReadonlyMap<DeclarationId, TypedArrayElementDomain>;
+    /**
+     * The declaration identity of the standard library's own `Promise<T>`
+     * interface, or `null` if this compilation's `lib` does not install one.
+     * See `promiseDeclarationOf` for how this is found independent of whether
+     * the program's own text ever names `Promise`.
+     */
+    readonly promiseDeclaration: DeclarationId | null;
+    /**
+     * The declaration identity of the standard library's own `Date` interface,
+     * or `null` if this compilation's `lib` does not install one. See
+     * `dateDeclarationOf`; resolved for the same reason `promiseDeclaration` is.
+     */
+    readonly dateDeclaration: DeclarationId | null;
+    /**
+     * The declaration identity of the standard library's own `String` WRAPPER
+     * OBJECT interface (`new String(x)`), or `null` if this compilation's `lib`
+     * does not install one. See `stringObjectDeclarationOf`; resolved for the
+     * same reason `dateDeclaration` is.
+     */
+    readonly stringObjectDeclaration: DeclarationId | null;
+    readonly errorDeclarations: ReadonlySet<DeclarationId>;
+    /**
+     * The declaration identity of the bare `Function` interface -- what
+     * `typeof x === 'function'` narrows to and what `Object.prototype.constructor`
+     * is declared as -- or `null` if this compilation's `lib` does not install
+     * one. See `functionDeclarationOf`, and `FunctionDeclarationPolicy`
+     * (representation/policies.ts) for why it is carried dynamically rather than
+     * as a host handle.
+     */
+    readonly functionDeclaration: DeclarationId | null;
+    /**
+     * Which classes each class inherits from, transitively. See
+     * `classHeritageOf` (class-heritage.ts) and `ClassHeritagePolicy`
+     * (representation/policies.ts) for the two carrier questions that need it.
+     */
+    readonly classHeritage: ReadonlyMap<DeclarationId, readonly DeclarationId[]>;
+    /**
+     * The derived classes the program stores into each base class's constructor
+     * slot -- see `constructorSlotSubclassesOf` (constructor-slot-subclasses.ts).
+     */
+    readonly constructorSlotSubclasses: ReadonlyMap<DeclarationId, readonly DeclarationId[]>;
+    /** The classes no evaluation can instantiate -- see `uninstantiableClassesOf` (uninstantiable-classes.ts). */
+    readonly uninstantiableClasses: ReadonlySet<DeclarationId>;
+    /**
+     * The one class this program declares as each interface's implementation --
+     * see `interfaceImplementorsOf` (interface-implementors.ts) and
+     * `InterfaceImplementorPolicy` (representation/policies.ts). Resolved here,
+     * beside `classHeritage`, for the same reason: it reads `implements`
+     * clauses, and nothing below the semantic layer may import `typescript`.
+     */
+    readonly interfaceImplementors: ReadonlyMap<DeclarationId, readonly DeclarationId[]>;
+    /**
+     * The declaration identity of the standard library's own `Generator<T,
+     * TReturn, TNext>` interface -- what a `function*` returns -- or `null` if
+     * this compilation's `lib` does not install one. See
+     * `generatorDeclarationOf`, and `GeneratorDeclarationPolicy`
+     * (representation/policies.ts) for why only this one interface and not
+     * `IterableIterator`/`Iterator`.
+     */
+    readonly generatorDeclaration: DeclarationId | null;
+    /**
+     * The declaration identity of the standard `AsyncGenerator<T, TReturn,
+     * TNext>` interface -- what an `async function*` returns. Carried as the
+     * same cursor `generatorDeclaration` is; see `asyncGeneratorDeclarationOf`.
+     */
+    readonly asyncGeneratorDeclaration: DeclarationId | null;
+    /** The standard `MapIterator<T>` returned by `Map.prototype.entries()`. */
+    readonly mapIteratorDeclaration: DeclarationId | null;
+    /**
+     * The declaration identity of each standard `Map`/`Set`/`WeakMap`/`WeakSet`
+     * interface this compilation's `lib` installs, valued by which family it is.
+     * See `keyedCollectionDeclarationsOf` for why this is resolved by name
+     * lookup rather than through the ambient-value census -- and for why the
+     * census's own `Map` protocol binding is not the answer.
+     */
+    readonly keyedCollections: ReadonlyMap<DeclarationId, KeyedCollectionFamily>;
+    /**
+     * The declaration identity of each standard `RegExp`/`RegExpExecArray`/
+     * `RegExpMatchArray` interface this compilation's `lib` installs, valued by
+     * which role it plays. See `regexpDeclarationsOf` for why this is resolved by
+     * name lookup rather than through the ambient-value census -- a regexp
+     * LITERAL names `RegExp` nowhere -- and for why the census's own `RegExp`
+     * protocol binding is not the answer.
+     */
+    readonly regexpDeclarations: ReadonlyMap<DeclarationId, RegExpDeclarationKind>;
+    /**
+     * The declaration identity of the standard `ArrayBuffer` and `DataView`
+     * interfaces this compilation's `lib` installs -- see
+     * `standardBufferDeclarationsOf` for why this is resolved by name against
+     * the standard library rather than found through the ambient-value census
+     * (which reaches `ArrayBuffer` and binds it as an OPAQUE host protocol).
+     */
+    readonly standardBuffers: ReadonlyMap<DeclarationId, StandardBufferKind>;
+    /**
+     * The structural type of every host namespace ROOT this program names, to
+     * the C++ type the host carries that root's object in -- see
+     * `HostCensus.namespaceRoots` for why this one census answer is keyed by
+     * structural type rather than by declaration, and
+     * `representation/policies.ts`'s `HostNamespaceRootPolicy` for what reads it.
+     */
+    readonly hostNamespaceRoots: ReadonlyMap<StructuralTypeId, string>;
+    /** Errors TypeScript itself reports, translated out of the checker's vocabulary. */
+    readonly checkerDiagnostics: readonly DiagnosticEvidence[];
+    /** Conditional inference requirements rejected by the final shared host census. */
+    readonly intrinsicProtocolDiagnostics: readonly DiagnosticEvidence[];
+    readonly uninstalledFamilies: readonly OperationFamily[];
+    /**
+     * What each write-discovery census bound and why it refused the rest.
+     *
+     * Every one of the six censuses already keeps this accounting -- each states
+     * `boundCount` and a `refusals` map over its own reason vocabulary -- and
+     * until now none of it left `semantics/`. The consequence was measurable: a
+     * campaign whose whole object is "which cell had no answer" could see only
+     * the SYNTACTIC shape of a boxed carrier from outside, and had to re-derive
+     * the census's reason by rebuilding a `ts.Program` beside the compiler and
+     * guessing. Ranking work by a guessed root is how two rounds went to the
+     * wrong place (`docs/DEFECT-PATTERNS.md` section 8).
+     *
+     * Reported, not judged: a refusal is often the CORRECT answer (a cell whose
+     * write set is genuinely open must stay dynamic), so a count here is a
+     * question to ask, never a defect by itself.
+     */
+    readonly censusAccounting: ReadonlyMap<string, CensusAccounting>;
+    /**
+     * The frontend's evidence-policy tables: the six write-discovery
+     * censuses above (`parameters`/`returns`/`local`/`field` bindings, plus
+     * `collections` and `bags`), restated as evidence policies over one shared
+     * `CellFacts` table -- see `normalize/cells/`. Computed alongside the
+     * existing composition from the SAME inputs (`identities`, the settled
+     * `valueFlow`, the reachable program), published here, and read by NOTHING
+     * downstream yet: `structural.ts`'s `typeAt` chain still answers every
+     * question above exactly as it does today. `agreement` is the instrument
+     * this phase's gate needs -- per program, how many declarations this table
+     * answers identically to that chain, how many differently, and how many
+     * neither answers nor can be compared (a collection/bag fact, whose domains
+     * are not yet ported -- see `normalize/cells/policies/index.ts`'s own
+     * header for exactly why). Phase 4.2: `table.refusals` restates each
+     * `twoOwnerClaims` row as a typed `CellRefusal` (`normalize/cells/model.ts`)
+     * -- still read by nothing downstream, same as the rest of this table.
+     */
+    readonly cellFacts: CellFactsPublication;
+    /**
+     * Nodes for which two of `normalize/structural.ts`'s rules both had an
+     * answer -- the frontend's own finding channel.
+     *
+     * Empty unless `GEA_STRUCTURAL_DISAGREEMENT` is set. Forwarded here rather
+     * than left on the mapper for the same reason `cellFacts` is: a script that
+     * only wants to know what the rule set disagrees about should not have to
+     * reach into a specialization view to find out.
+     */
+    readonly structuralDisagreements: readonly StructuralDisagreement[];
+    /**
+     * The copies of every generic class whose copies can differ in layout --
+     * `StructuralMapper.classCopies`, read once typing is done and forwarded
+     * to the deriver as its `ClassCopyPolicy`.
+     */
+    readonly classCopies: ReadonlyMap<DeclarationId, readonly ClassCopyKey[]>;
+    /**
+     * Rules that answered outside their declared forms -- the 4.3 port's own
+     * gate. Empty unless `GEA_STRUCTURAL_FORM_AUDIT` is set; non-empty means a
+     * `forms` list is a false claim and some rule is being skipped for a form it
+     * can really answer for.
+     */
+    readonly structuralFormViolations: readonly StructuralFormViolation[];
+    /**
+     * Every write-discovery refusal, typed and carrying the cell it is about.
+     *
+     * `parameters` is the COMPOSED view, so its list already carries the return,
+     * local, field and JSDoc layers it wraps; only the two censuses that are not
+     * in that chain are concatenated beside it. `compiler.ts` folds this into
+     * `CompileResult.refusals`, which is the point of the exercise: until now a
+     * census refusal was a number in a side table, and no caller asking "what did
+     * this compilation refuse" could see one (the frontend is replaced, not instrumented).
+     */
+    readonly censusRefusals: readonly CensusRefusal[];
+}
+/** One census's own accounting of what it answered and what it declined. */
+export interface CensusAccounting {
+    /** Declarations this census gave a type to. */
+    readonly bound: number;
+    /**
+     * Why the rest were declined, counted by refusal ROOT.
+     *
+     * DERIVED from the census's typed refusal list rather than maintained beside
+     * it (`censusRefusalCounts`). A count kept in parallel with the refusals it
+     * counts is free to drift from them, which is the two-authorities defect this
+     * refactor removes, in miniature. Read `FrontendResult.censusRefusals` when
+     * the question is WHICH cell rather than how many.
+     */
+    readonly refusals: ReadonlyMap<string, number>;
+}
+export declare const runFrontend: (input: FrontendInput) => FrontendResult;