@geastack/compiler 1.0.15

package/dist/semantics/normalize/binding-fixpoint.d.ts

@@ -0,0 +1,36 @@
+import type { ParameterBindingCensus } from './parameter-bindings.js';
+/**
+ * One round's whole output: the parameter census the fixpoint settles on, and
+ * every other artifact that round produced.
+ *
+ * `facts` is generic because this module settles a fixpoint and has no business
+ * knowing which censuses a round happens to build. What matters is that a round
+ * RETURNS them. They used to be published by assigning to `let`s captured from
+ * the enclosing scope, which made `compose` a function that answered one
+ * question and silently republished four more -- so "which round's collection
+ * census does the structural mapper read" was answered by the last write to
+ * survive the loop rather than by anything a reader could see. That is the same
+ * two-authorities shape this refactor removes everywhere else
+ * (the frontend's evidence-policy tables).
+ */
+export interface RoundCensus<Facts> {
+    readonly parameters: ParameterBindingCensus;
+    readonly facts: Facts;
+}
+/** A settled `RoundCensus`, and which round settled it. */
+export interface CensusSnapshot<Facts> extends RoundCensus<Facts> {
+    readonly round: number;
+}
+/**
+ * Count equality cannot establish a fixed point: a cell may change carrier
+ * while another loses its answer. Record the actual census queries a round
+ * depends on, then require its output to answer those queries identically.
+ * Type identity is the checker's identity, never a rendered name or a second
+ * structural-type classifier. Union lists compare their ordered type identities.
+ *
+ * The returned snapshot is the SETTLING round's own, in full -- not merely its
+ * parameter census. Every artifact in it was built by one round from one
+ * upstream view, so a consumer cannot pair a census from one round with a flow
+ * index from another.
+ */
+export declare const settleBindingCensus: <Facts>(compose: (upstream?: ParameterBindingCensus) => RoundCensus<Facts>, limit?: number) => CensusSnapshot<Facts>;

package/dist/semantics/normalize/binding-fixpoint.js

@@ -0,0 +1,140 @@
+import { sameImplicitArgumentsTuple } from './implicit-arguments-tuple.js';
+/** A frame fact is a fresh object each round; it settles when it states the same frame, not when it is the same object. */
+const isFrameFact = (fact) => fact !== null && !Array.isArray(fact) && 'frame' in fact;
+// Derive the keys from the public census interface. A new fact query must be
+// included here or TypeScript rejects the build; it cannot escape convergence.
+const queries = {
+    argumentsAt: (view, node) => view.argumentsAt?.(node) ?? null,
+    callTargetsAt: (view, node) => view.callTargetsAt?.(node) ?? null,
+    callDeclarationAt: (view, node) => view.callDeclarationAt?.(node) ?? null,
+    typeAt: (view, node) => view.typeAt(node),
+    implicitArgumentsTupleAt: (view, node) => view.implicitArgumentsTupleAt?.(node) ?? null,
+    restElementTypeAt: (view, node) => view.restElementTypeAt?.(node) ?? null,
+    statedTypeAt: (view, node) => view.statedTypeAt(node),
+    unionArmsAt: (view, node) => view.unionArmsAt(node),
+    preferredTypeAt: (view, node) => view.preferredTypeAt?.(node) ?? null,
+    patternReadTypeAt: (view, node) => view.patternReadTypeAt?.(node) ?? null
+};
+/**
+ * Count equality cannot establish a fixed point: a cell may change carrier
+ * while another loses its answer. Record the actual census queries a round
+ * depends on, then require its output to answer those queries identically.
+ * Type identity is the checker's identity, never a rendered name or a second
+ * structural-type classifier. Union lists compare their ordered type identities.
+ *
+ * The returned snapshot is the SETTLING round's own, in full -- not merely its
+ * parameter census. Every artifact in it was built by one round from one
+ * upstream view, so a consumer cannot pair a census from one round with a flow
+ * index from another.
+ */
+export const settleBindingCensus = (compose, limit = 64) => {
+    // Carry only the `ParameterBindingCensus` forward between rounds, never the
+    // whole `RoundCensus`. For the real caller (`frontend.ts`) `RoundCensus.facts`
+    // holds that round's `ValueFlowIndex`, and `sourceValueSessionOf`
+    // (flow/source-value-session.ts) memoizes an ~80,000-state, ~14.7M-edge
+    // dependency graph in a WeakMap keyed on that index object -- roughly 1GB
+    // live per session on the three.js app. A `let round: RoundCensus<Facts>` reassigned
+    // only after `compose` returns keeps the PREVIOUS round's index (and its
+    // graph) reachable for the whole duration of the `compose` call that builds
+    // the NEXT round's index, so both graphs are live at once: measured as
+    // the three.js app's ~2.1GB fixpoint peak. Only `.parameters` is ever read back out of
+    // a settled round (to seed the next round's `observed` view and to compare
+    // `boundCount`), so only `.parameters` needs to survive the boundary.
+    let previousCensus = compose().parameters;
+    let unsettled = [];
+    const identities = new Map();
+    const factLabel = (fact) => {
+        if (fact === null)
+            return 'null';
+        if (Array.isArray(fact))
+            return `[${fact.map((type) => factLabel(type)).join(',')}]`;
+        if (isFrameFact(fact)) {
+            return fact.frame === 'array'
+                ? `arguments-array(${factLabel(fact.element)})`
+                : `arguments-tuple(${fact.required}/${fact.elements.map((type) => factLabel(type)).join(',')})`;
+        }
+        if ('kind' in fact)
+            return `declaration:${fact.kind}`;
+        const type = fact;
+        if (!identities.has(type))
+            identities.set(type, identities.size + 1);
+        return `${identities.get(type)}:${type.flags}:${type.symbol?.name ?? '-'}`;
+    };
+    for (let rounds = 2; rounds <= limit; rounds += 1) {
+        const reads = new Map();
+        const read = (name, node, value) => {
+            let nodes = reads.get(name);
+            if (!nodes) {
+                nodes = new Map();
+                reads.set(name, nodes);
+            }
+            nodes.set(node, value);
+            return value;
+        };
+        // Bind THIS round's upstream to a fresh per-iteration const. Every round's
+        // `observed` wrapper closes over the view it forwards to, and those
+        // wrappers outlive their round: a census composed in round N keeps round
+        // N's `observed` as its own upstream, and asks it again whenever a later
+        // round consults round N's answers. Reading the carried `previousCensus`
+        // variable from inside the wrapper instead pointed EVERY round's wrapper
+        // at whatever the variable held last, so once it advanced to round N's
+        // census, round N-1's wrapper forwarded into round N, whose upstream is
+        // that same wrapper -- `statedTypeAt` recursed between the two until the
+        // stack died, 58s into a three.js compile.
+        const upstream = previousCensus;
+        const observed = { ...upstream };
+        // `Object.keys` preserves the closed query table's keys. The wrapper
+        // preserves each method's result kind and normalizes an absent optional
+        // method to the same null answer used when checking the next view.
+        for (const name of Object.keys(queries)) {
+            Object.defineProperty(observed, name, {
+                value: (node) => read(name, node, queries[name](upstream, node)),
+                enumerable: true
+            });
+        }
+        const previousBoundCount = upstream.boundCount;
+        // `compose` is called with nothing in this function's own scope naming the
+        // previous round's `facts` -- `observed` closes over `previousCensus`
+        // (a `ParameterBindingCensus`), never over the `RoundCensus` it came from.
+        const next = compose(observed);
+        let changed = next.parameters.boundCount !== previousBoundCount;
+        unsettled = changed ? [`boundCount ${previousBoundCount} -> ${next.parameters.boundCount}`] : [];
+        // Reads may lazily consult earlier views. Snapshot before querying `next`
+        // so forwarding to `observed` cannot extend the map during iteration.
+        const pending = [...reads].map(([name, nodes]) => [name, [...nodes]]);
+        for (const [name, nodes] of pending) {
+            for (const [node, previous] of nodes) {
+                const answer = queries[name](next.parameters, node);
+                const equal = previous === answer ||
+                    (Array.isArray(previous) &&
+                        Array.isArray(answer) &&
+                        previous.length === answer.length &&
+                        previous.every((type, index) => type === answer[index])) ||
+                    (isFrameFact(previous) && isFrameFact(answer) && sameImplicitArgumentsTuple(previous, answer));
+                if (!equal) {
+                    changed = true;
+                    if (unsettled.length < 8 && typeof node.getSourceFile === 'function') {
+                        const file = node.getSourceFile();
+                        const line = file.getLineAndCharacterOfPosition(node.getStart()).line + 1;
+                        unsettled.push(`${name} ${file.fileName}:${line} ${node.getText().slice(0, 70)}: ${factLabel(previous)} -> ${factLabel(answer)}`);
+                    }
+                }
+            }
+        }
+        if (process.env['GEA_BINDING_CONVERGENCE_DEBUG'])
+            process.stderr.write(`[CONVERGENCE ${rounds}] ${unsettled.join('\n')}\n`);
+        // Return `next` directly rather than stashing it in an outer `round` first:
+        // a settling round's `facts` (this round's `ValueFlowIndex` included) must
+        // reach the caller, but a NON-settling round's `facts` must not survive
+        // this iteration at all -- there is no next reader for them, ever, settled
+        // or not. `next` is a `const` scoped to this iteration; once `previousCensus`
+        // below takes only its `.parameters`, nothing in this function still names
+        // this round's `facts` and the round's index/session graph is free the
+        // moment `next` goes out of scope, unlike the old flow where the outer
+        // `round` binding kept it reachable until being overwritten one line later.
+        if (!changed)
+            return { ...next, round: rounds };
+        previousCensus = next.parameters;
+    }
+    throw new Error(`binding census did not reach a fixed point after ${limit} rounds; refusing to publish unsettled value facts\n${unsettled.join('\n')}`);
+};

package/dist/semantics/normalize/callback-parameter-contracts.d.ts

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+import type { ValueFlowIndex } from './flow/model.js';
+export interface CallbackParameterContract {
+    readonly signature: ts.Signature;
+    readonly location: ts.CallExpression | ts.NewExpression;
+}
+/** Resolve at the receiving call so instantiated generic contracts stay instantiated. */
+export declare const callbackContractParameterType: (checker: ts.TypeChecker, contract: CallbackParameterContract, position: number) => ts.Type | null;
+/**
+ * Every stated callback input contract receiving a local named function.
+ * These signatures are additional caller evidence, never a substitute for
+ * its direct calls. Unknown escapes fail closed. In particular a receiving
+ * `(value: any) => void` signature is retained so the parameter join sees the
+ * open input rather than inferring from only the convenient typed boundary.
+ */
+export declare const callbackParameterContractsFor: (checker: ts.TypeChecker, flow: ValueFlowIndex, declaration: ts.SignatureDeclaration, countedCalls: ReadonlySet<ts.CallExpression | ts.NewExpression>) => readonly CallbackParameterContract[] | null;

package/dist/semantics/normalize/callback-parameter-contracts.js

@@ -0,0 +1,91 @@
+import ts from 'typescript';
+import { classifyCallableMention } from './flow/callable-reach.js';
+import { isModuleExportedDeclaration } from './flow/targets.js';
+/** Resolve at the receiving call so instantiated generic contracts stay instantiated. */
+export const callbackContractParameterType = (checker, contract, position) => {
+    const parameter = contract.signature.parameters[position];
+    const declaration = parameter?.valueDeclaration ?? parameter?.declarations?.[0];
+    if (!parameter || !declaration || !ts.isParameter(declaration) || declaration.dotDotDotToken)
+        return null;
+    return checker.getTypeOfSymbolAtLocation(parameter, contract.location);
+};
+/**
+ * Every stated callback input contract receiving a local named function.
+ * These signatures are additional caller evidence, never a substitute for
+ * its direct calls. Unknown escapes fail closed. In particular a receiving
+ * `(value: any) => void` signature is retained so the parameter join sees the
+ * open input rather than inferring from only the convenient typed boundary.
+ */
+export const callbackParameterContractsFor = (checker, flow, declaration, countedCalls) => {
+    if (!ts.isFunctionDeclaration(declaration) || !declaration.name || !declaration.body)
+        return null;
+    if ((ts.getCombinedModifierFlags(declaration) & (ts.ModifierFlags.Export | ts.ModifierFlags.Default)) !== 0)
+        return null;
+    const symbol = checker.getSymbolAtLocation(declaration.name);
+    if (!symbol || symbol.declarations?.length !== 1)
+        return null;
+    const signatures = [];
+    const acceptedArguments = new Set();
+    const flows = new Set([...flow.flowsFromDeclaration(declaration), ...flow.flowsFromSymbol(symbol)]);
+    const contractAt = (write) => {
+        if (write.edge !== 'call-argument' || write.slot !== 'whole' || !write.value)
+            return null;
+        const call = write.value.parent;
+        if (!ts.isCallExpression(call) && !ts.isNewExpression(call))
+            return null;
+        const args = call.arguments;
+        if (!args || args.some(ts.isSpreadElement))
+            return null;
+        const position = args.indexOf(write.value);
+        if (position < 0)
+            return null;
+        const signature = checker.getResolvedSignature(call);
+        const parameter = signature?.parameters[position];
+        if (!parameter)
+            return null;
+        const parameterDeclaration = parameter.valueDeclaration ?? parameter.declarations?.[0];
+        if (!parameterDeclaration || !ts.isParameter(parameterDeclaration) || parameterDeclaration.dotDotDotToken)
+            return null;
+        const type = checker.getTypeOfSymbolAtLocation(parameter, call);
+        // An optional callable is still a stated contract; any other alternative
+        // is an open destination, not permission to discard that incoming use.
+        const arms = type.isUnion() ? type.types : [type];
+        const result = [];
+        for (const arm of arms) {
+            if ((arm.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Never)) !== 0)
+                continue;
+            if ((arm.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter)) !== 0)
+                return null;
+            const calls = checker.getSignaturesOfType(arm, ts.SignatureKind.Call);
+            if (calls.length === 0)
+                return null;
+            result.push(...calls.map((signature) => ({ signature, location: call })));
+        }
+        return result.length === 0 ? null : result;
+    };
+    for (const write of flows) {
+        const contracts = contractAt(write);
+        if (contracts === null || write.value === null)
+            return null;
+        acceptedArguments.add(write.value);
+        signatures.push(...contracts);
+    }
+    if (signatures.length === 0)
+        return null;
+    // An export-list alias is not an expression reference in the value-flow
+    // index. Its checker identity still publishes this callable to open callers.
+    if (isModuleExportedDeclaration(checker, declaration, symbol))
+        return null;
+    const references = new Set([...flow.referencesToDeclaration(declaration), ...flow.referencesToSymbol(symbol)]);
+    for (const reference of references) {
+        if (acceptedArguments.has(reference))
+            continue;
+        const mention = classifyCallableMention(checker, reference, declaration.name);
+        if (mention.kind === 'inert')
+            continue;
+        if (mention.kind === 'call' && countedCalls.has(mention.call))
+            continue;
+        return null;
+    }
+    return signatures;
+};

package/dist/semantics/normalize/cells/agreement.d.ts

@@ -0,0 +1,46 @@
+import type { StructuralMapper } from '../structural.js';
+import type { CellFactsTable } from './model.js';
+/**
+ * The instrument phase 4.1 asks for: per program, how many declarations the
+ * new table answers IDENTICALLY to `structural.ts`'s existing `typeAt` chain,
+ * how many DIFFERENTLY, and how many this table has no opinion on at all.
+ *
+ * Compared as interned `StructuralTypeId`s, not as `ts.Type`s: two checker
+ * types the mapper's own `typeOf` collapses onto one structural shape (a
+ * literal and its widened form, say) are the SAME answer for every purpose
+ * downstream of `structural.ts`, and comparing raw `ts.Type` identity would
+ * report disagreement `structural.ts` itself does not have.
+ *
+ * This is diagnostic only -- nothing downstream reads it, and it changes
+ * nothing about what `types.typeAt` returns. `bagShape`/`collectionArguments`
+ * facts count as NOT COMPARABLE rather than as an unanswered cell: the table
+ * did answer, just not in the `ts.Type` language `typeAt` speaks, and folding
+ * that into "unanswered" would make phase 4.2's two-owner audit undercount
+ * how much of the table this instrument can actually check today.
+ */
+export interface CellFactsAgreement {
+    readonly total: number;
+    readonly identical: number;
+    readonly different: number;
+    readonly unanswered: number;
+    readonly notComparable: number;
+}
+/**
+ * What `FrontendResult.cellFacts` actually publishes: the table, plus the
+ * agreement instrument when it was asked for.
+ *
+ * `agreement` is `null` unless a caller asked to measure, and that is not a
+ * convenience: `cellFactsAgreementOf` asks `types.typeAt` about declarations
+ * the compilation itself never asks about, and `typeAt` MINTS -- it interns a
+ * `StructuralTypeId` on first sight. Interning an id nobody needed shifts every
+ * later id, which renumbers the derived representations, which renumbers
+ * `gea_record_type_N` in the emitted C++. Measuring 68 corpus programs
+ * renumbered exactly that way is what found this. An instrument that changes
+ * the artifact it measures is not an instrument, so it runs only when asked.
+ */
+export interface CellFactsPublication {
+    readonly table: CellFactsTable;
+    readonly agreement: CellFactsAgreement | null;
+}
+export declare const publishCellFacts: (table: CellFactsTable, types: StructuralMapper, measure: boolean) => CellFactsPublication;
+export declare const cellFactsAgreementOf: (table: CellFactsTable, types: StructuralMapper) => CellFactsAgreement;

package/dist/semantics/normalize/cells/agreement.js

@@ -0,0 +1,34 @@
+export const publishCellFacts = (table, types, measure) => ({
+    table,
+    agreement: measure ? cellFactsAgreementOf(table, types) : null
+});
+export const cellFactsAgreementOf = (table, types) => {
+    let identical = 0;
+    let different = 0;
+    let unanswered = 0;
+    let notComparable = 0;
+    for (const facts of table.all) {
+        if (facts.resolved === null) {
+            unanswered++;
+            continue;
+        }
+        if (facts.resolved.kind !== 'type') {
+            notComparable++;
+            continue;
+        }
+        let chainAnswer;
+        try {
+            chainAnswer = types.typeAt(facts.declaration);
+        }
+        catch {
+            unanswered++;
+            continue;
+        }
+        const cellAnswer = types.typeOf(facts.resolved.type);
+        if (cellAnswer === chainAnswer)
+            identical++;
+        else
+            different++;
+    }
+    return { total: table.all.length, identical, different, unanswered, notComparable };
+};

package/dist/semantics/normalize/cells/candidates.d.ts

@@ -0,0 +1,17 @@
+import ts from 'typescript';
+import { type ProgramReachability } from '../reachability.js';
+/**
+ * Every reachable node in the program that `test` admits -- one walk shared
+ * by every domain's `candidatesOf`, instead of the six private walks
+ * the value-flow survey measured (9, 4, 6, 7, 6 and 8 of them). A policy states
+ * WHAT shape of declaration it is looking for; it never re-derives which part
+ * of the program it is allowed to look at.
+ *
+ * Mirrors `census.ts`'s own walk: an ambient module's body describes host
+ * values none of which execute, a type annotation contains no operations
+ * (except the one a heritage clause's expression really evaluates), and a
+ * class member the program never names is exactly as dead as an unreferenced
+ * top-level declaration -- `reachability.ts` is the one authority on the
+ * latter two, asked here for the identical reason `census.ts` asks it.
+ */
+export declare const cellCandidatesOf: <T extends ts.Node>(reachable: ProgramReachability, files: readonly ts.SourceFile[], test: (node: ts.Node) => node is T) => T[];

package/dist/semantics/normalize/cells/candidates.js

@@ -0,0 +1,35 @@
+import ts from 'typescript';
+import { isAmbientDeclaration } from '../../ambient.js';
+import { forEachReachableStatement } from '../reachability.js';
+/**
+ * Every reachable node in the program that `test` admits -- one walk shared
+ * by every domain's `candidatesOf`, instead of the six private walks
+ * the value-flow survey measured (9, 4, 6, 7, 6 and 8 of them). A policy states
+ * WHAT shape of declaration it is looking for; it never re-derives which part
+ * of the program it is allowed to look at.
+ *
+ * Mirrors `census.ts`'s own walk: an ambient module's body describes host
+ * values none of which execute, a type annotation contains no operations
+ * (except the one a heritage clause's expression really evaluates), and a
+ * class member the program never names is exactly as dead as an unreferenced
+ * top-level declaration -- `reachability.ts` is the one authority on the
+ * latter two, asked here for the identical reason `census.ts` asks it.
+ */
+export const cellCandidatesOf = (reachable, files, test) => {
+    const found = [];
+    for (const file of files) {
+        const visit = (node) => {
+            if (ts.isModuleDeclaration(node) && isAmbientDeclaration(node))
+                return;
+            if (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node))
+                return;
+            if (reachable.memberIsPruned(node))
+                return;
+            if (test(node))
+                found.push(node);
+            ts.forEachChild(node, visit);
+        };
+        forEachReachableStatement(reachable, file, visit);
+    }
+    return found;
+};

package/dist/semantics/normalize/cells/facts.d.ts

@@ -0,0 +1,19 @@
+import ts from 'typescript';
+import type { IdentityTable } from '../identities.js';
+import type { ValueFlowIndex } from '../flow/model.js';
+import type { CellFactsTable } from './model.js';
+import type { CellPolicyRegistry } from './registry.js';
+/**
+ * The engine every evidence policy runs through: for each candidate
+ * declaration, read the shared flow index's writes to it, let the policy's
+ * per-edge rules decide which ones are evidence, join what is admitted, and
+ * resolve `stated ?? writeJoin ?? checker` -- the one join
+ * the single-census frontend asks for, computed once here instead
+ * of once per domain.
+ *
+ * This function is the whole of what used to be six private compositions. A
+ * policy states WHAT counts as evidence and how to join it; this states HOW
+ * a cell's three primitives combine into one answer, and it is the only place
+ * that does.
+ */
+export declare const buildCellFactsTable: (identities: IdentityTable, flow: ValueFlowIndex, files: readonly ts.SourceFile[], registry: CellPolicyRegistry) => CellFactsTable;

package/dist/semantics/normalize/cells/facts.js

@@ -0,0 +1,90 @@
+import ts from 'typescript';
+/**
+ * The engine every evidence policy runs through: for each candidate
+ * declaration, read the shared flow index's writes to it, let the policy's
+ * per-edge rules decide which ones are evidence, join what is admitted, and
+ * resolve `stated ?? writeJoin ?? checker` -- the one join
+ * the single-census frontend asks for, computed once here instead
+ * of once per domain.
+ *
+ * This function is the whole of what used to be six private compositions. A
+ * policy states WHAT counts as evidence and how to join it; this states HOW
+ * a cell's three primitives combine into one answer, and it is the only place
+ * that does.
+ */
+export const buildCellFactsTable = (identities, flow, files, registry) => {
+    const all = [];
+    const byId = new Map();
+    for (const policy of registry.policies) {
+        for (const declaration of policy.candidatesOf(files)) {
+            const writes = policy.writesOf ? policy.writesOf(declaration, flow) : flow.writesToDeclaration(declaration);
+            const admitted = [];
+            for (const write of writes) {
+                const rule = policy.rules[write.edge];
+                if (!rule)
+                    continue;
+                const value = rule(write, declaration);
+                if (value !== null)
+                    admitted.push({ write, value });
+            }
+            const writeJoin = admitted.length > 0 ? policy.combine(admitted) : null;
+            const stated = policy.statedAt(declaration);
+            const checkerValue = policy.checkerAt(declaration);
+            const resolved = stated ?? writeJoin ?? checkerValue;
+            // A declaration this program's identity table refuses (an uninstantiated
+            // generic's own body, walked by nothing) is not a cell any consumer can
+            // NAME either -- `identities.ts` is the one authority on that, and a cell
+            // census asking it a second time would be exactly the two-authorities
+            // defect this table exists to end.
+            let id;
+            try {
+                id = identities.declarationIdOf(declaration);
+            }
+            catch {
+                continue;
+            }
+            const facts = { domain: policy.domain, declaration, id, stated, writeJoin, checker: checkerValue, resolved };
+            all.push(facts);
+            const bucket = byId.get(id);
+            if (bucket)
+                bucket.push(facts);
+            else
+                byId.set(id, [facts]);
+        }
+    }
+    const twoOwnerClaims = [];
+    const refusals = [];
+    for (const [id, facts] of byId) {
+        const domains = [...new Set(facts.map((fact) => fact.domain))];
+        if (domains.length <= 1)
+            continue;
+        twoOwnerClaims.push({ id, domains });
+        refusals.push(cellOwnerRefusal(id, domains, facts));
+    }
+    return { all, byId, twoOwnerClaims, refusals };
+};
+/**
+ * Builds the typed refusal for one collision. `facts` all share `id`, and
+ * `identities.declarationIdOf` names one declaration node -- every entry's
+ * `declaration` is the same node, so the first is as good as any for the
+ * `SyntaxKind`/location the reason and key report.
+ */
+const cellOwnerRefusal = (id, domains, facts) => {
+    const sortedDomains = [...domains].sort();
+    const [first] = facts;
+    const declaration = first ? first.declaration : null;
+    const kindName = declaration ? ts.SyntaxKind[declaration.kind] : 'unknown';
+    const where = declaration
+        ? (() => {
+            const sourceFile = declaration.getSourceFile();
+            const { line } = sourceFile.getLineAndCharacterOfPosition(declaration.getStart(sourceFile));
+            return `${sourceFile.fileName}:${line + 1}`;
+        })()
+        : String(id);
+    return {
+        stage: 'cells',
+        key: `cell-owner:${sortedDomains.join('+')}:${kindName}`,
+        reason: `${kindName} at ${where} is claimed by ${sortedDomains.length} cell-evidence domains (${sortedDomains.join(', ')}); a two-owner claim is a census disagreement, not a precedence question`,
+        owner: String(id)
+    };
+};

package/dist/semantics/normalize/cells/index.d.ts

@@ -0,0 +1,10 @@
+export type { CellDomain, CellFacts, CellFactsTable, CellOwnerClaim, CellRefusal, CellRefusalKey, CellValue } from './model.js';
+export { cellType } from './model.js';
+export type { CellEvidenceContribution, CellEvidencePolicy, CellEvidenceRule } from './policy.js';
+export { rulesFor } from './policy.js';
+export type { CellPolicyRegistry } from './registry.js';
+export { createCellPolicyRegistry } from './registry.js';
+export { buildCellFactsTable } from './facts.js';
+export type { CellFactsAgreement, CellFactsPublication } from './agreement.js';
+export { cellFactsAgreementOf, publishCellFacts } from './agreement.js';
+export { defaultCellEvidencePolicies } from './policies/index.js';

package/dist/semantics/normalize/cells/index.js

@@ -0,0 +1,6 @@
+export { cellType } from './model.js';
+export { rulesFor } from './policy.js';
+export { createCellPolicyRegistry } from './registry.js';
+export { buildCellFactsTable } from './facts.js';
+export { cellFactsAgreementOf, publishCellFacts } from './agreement.js';
+export { defaultCellEvidencePolicies } from './policies/index.js';

package/dist/semantics/normalize/cells/model.d.ts

@@ -0,0 +1,98 @@
+import type ts from 'typescript';
+import type { DeclarationId } from '../../../identity/ids.js';
+import type { CollectionTypeArguments } from '../collection-bindings.js';
+import type { ObjectBagShape } from '../object-bag-bindings.js';
+/**
+ * Replaced rather than instrumented: the six private censuses that
+ * answer "what can this storage cell hold" (`parameter-bindings.ts`,
+ * `return-bindings.ts`, `local-bindings.ts`, `field-bindings.ts`,
+ * `collection-bindings.ts`, `object-bag-bindings.ts`) become six evidence
+ * POLICIES over one shared table, keyed by domain the way every other census
+ * in the registry (2.4) is keyed by the question it answers, never by its
+ * position in `structural.ts`'s chain.
+ */
+export type CellDomain = 'parameter' | 'return' | 'local' | 'field' | 'collection' | 'bag';
+/**
+ * One answer language for all six domains, replacing the three the audit in
+ * the value-flow survey found (`ts.Type | null`, an `ObjectBagShape`, a list of
+ * union arms). Four domains (parameter, return, local, field) answer in
+ * `ts.Type`-space and use only `type`; the other two keep their own richer
+ * shape rather than being forced into one that cannot state a key/value pair
+ * or a member map -- a census answers one question program-wide, publishes a sealed table,
+ * entry and this directory's own README-shaped comment in `facts.ts` for why
+ * that is a closed union rather than a fourth private shape.
+ */
+export type CellValue = {
+    readonly kind: 'type';
+    readonly type: ts.Type;
+} | {
+    readonly kind: 'collection-arguments';
+    readonly arguments: CollectionTypeArguments;
+} | {
+    readonly kind: 'bag-shape';
+    readonly shape: ObjectBagShape;
+};
+/** Wraps a `ts.Type` answer -- the language the four ported policies (parameter, return, local, field) speak. */
+export declare const cellType: (type: ts.Type) => CellValue;
+/**
+ * One domain's answer for one declaration, in the three primitives
+ * The value-flow survey's names: `stated` (the program's own annotation),
+ * `writeJoin` (what the evidence policy's admitted writes agree on), and
+ * `checker` (the checker's own answer, always present as the fallback of last
+ * resort). `resolved` is `stated ?? writeJoin ?? checker` -- the one join,
+ * asked once, rather than a position in an ordered chain.
+ */
+export interface CellFacts {
+    readonly domain: CellDomain;
+    readonly declaration: ts.Node;
+    readonly id: DeclarationId;
+    readonly stated: CellValue | null;
+    readonly writeJoin: CellValue | null;
+    readonly checker: CellValue | null;
+    readonly resolved: CellValue | null;
+}
+/**
+ * A declaration two domains both published `CellFacts` for -- recorded here,
+ * not refused. Phase 4.2 turns each of these into a `CellRefusal` below;
+ * this shape stays as the raw evidence (which domains, which id) that the
+ * refusal is built from, the way `ir/certify.ts`'s `CapabilityDemand` stays
+ * separate from the `Refusal` it can produce.
+ */
+export interface CellOwnerClaim {
+    readonly id: DeclarationId;
+    readonly domains: readonly CellDomain[];
+}
+/**
+ * Phase 4.2: a `CellOwnerClaim` restated in the compiler's refusal
+ * vocabulary (`ir/refusal.ts`'s `Refusal`: `stage`, `key`, `reason`,
+ * `owner`) rather than left as a count. Two evidence domains both claiming
+ * one declaration is a census disagreement -- the honest answer names both
+ * domains and the declaration, the way `field-bindings.ts` and
+ * `collection-bindings.ts` disagreeing about one declaration
+ * (`collection-bindings.ts:200-224`) never had a name before.
+ *
+ * `stage: 'cells'` and `key`'s `cell-owner:` prefix are their own namespace,
+ * not a member of `ir/refusal.ts`'s `RefusalStage`/`RefusalKey` unions: a
+ * cell-domain collision is decided before there is a plan to certify
+ * against, and joining `CompileResult.refusals` is a later phase's call
+ * (nothing reads this table yet -- see `agreement.ts`'s header on why this
+ * whole publication is additive-only for now). The key embeds the domain
+ * pair and the declaration's `ts.SyntaxKind` name -- `parameter.ts` and
+ * `local-bindings.ts`'s own refusal-key convention
+ * (`function-escapes:${ts.SyntaxKind[...]}`) -- so grouping refusals by
+ * `key` is grouping by root without parsing `reason`.
+ */
+export type CellRefusalKey = `cell-owner:${string}`;
+export interface CellRefusal {
+    readonly stage: 'cells';
+    readonly key: CellRefusalKey;
+    readonly reason: string;
+    readonly owner: string;
+}
+/** The published table: every fact, indexed by declaration identity, plus every collision found while indexing, typed. */
+export interface CellFactsTable {
+    readonly all: readonly CellFacts[];
+    readonly byId: ReadonlyMap<DeclarationId, readonly CellFacts[]>;
+    readonly twoOwnerClaims: readonly CellOwnerClaim[];
+    readonly refusals: readonly CellRefusal[];
+}

package/dist/semantics/normalize/cells/model.js

@@ -0,0 +1,2 @@
+/** Wraps a `ts.Type` answer -- the language the four ported policies (parameter, return, local, field) speak. */
+export const cellType = (type) => ({ kind: 'type', type });