@geastack/compiler 1.0.15

package/dist/conversion/record-view.js

@@ -0,0 +1,273 @@
+import { representationKey } from '../representation/model.js';
+/**
+ * An OWNED record (a value, not a handle) materialized as a refcounted or
+ * owned record of another shape, or as the one arm of a sum that shape fits:
+ * every field required on both sides and itself materializable.
+ */
+export const ownedRecordMaterializationPlan = (source, target, layouts) => {
+    if (representationKey(source) === representationKey(target))
+        return { kind: 'identity', target };
+    if (source.kind === 'record' &&
+        target.kind === 'native-record-ref' &&
+        target.native === null &&
+        source.shapeId === target.shapeId &&
+        source.ownership === target.ownership)
+        return { kind: 'identity', target };
+    if (source.kind !== 'record')
+        return null;
+    if (target.kind === 'tagged-union') {
+        const arms = target.arms.flatMap((arm, index) => {
+            const payload = ownedRecordMaterializationPlan(source, arm.value, layouts);
+            return payload === null ? [] : [{ kind: 'arm', target, index, payload }];
+        });
+        return arms.length === 1 ? (arms[0] ?? null) : null;
+    }
+    if (source.ownership !== 'owned' || source.accessors.length !== 0)
+        return null;
+    if (target.kind !== 'record' && target.kind !== 'native-record-ref')
+        return null;
+    if (target.ownership === 'borrowed')
+        return null;
+    if (target.kind === 'native-record-ref' && target.native !== null)
+        return null;
+    if (target.kind === 'record' && target.accessors.length !== 0)
+        return null;
+    const fields = target.kind === 'record' ? target.fields : (layouts.plainFieldsForShape?.(target.shapeId) ?? null);
+    if (fields === null || fields.length !== source.fields.length)
+        return null;
+    const planned = [];
+    for (const field of fields) {
+        const held = source.fields.find((candidate) => candidate.key === field.key);
+        if (!held || !held.required || !field.required)
+            return null;
+        const value = ownedRecordMaterializationPlan(held.value, field.value, layouts);
+        if (value === null)
+            return null;
+        planned.push({ key: field.key, value });
+    }
+    return { kind: 'record', source, target, fields: planned };
+};
+/**
+ * Effects of an already-admitted view, not another conversion predicate.
+ * Copying a held carrier (including an already-dynamic cell) reads native
+ * storage directly. A converted field, bound method or expando needs its own
+ * transport contract before this view can dispense with dynamic field hooks.
+ */
+export const recordViewUsesOnlyDirectFields = (plan) => {
+    switch (plan.kind) {
+        case 'owned':
+            return true;
+        case 'optional':
+        case 'assert':
+            return recordViewUsesOnlyDirectFields(plan.payload);
+        case 'arm': {
+            const arm = plan.target.arms[plan.index];
+            return plan.payload !== null
+                ? recordViewUsesOnlyDirectFields(plan.payload)
+                : arm !== undefined && representationKey(plan.source) === representationKey(arm.value);
+        }
+        case 'recast-union':
+            return plan.arms.every((arm) => arm.via === 'exact' || (arm.via !== 'convert' && recordViewUsesOnlyDirectFields(arm.via)));
+        case 'fields':
+            return (!plan.expando &&
+                plan.indexes.length === 0 &&
+                plan.fields.every(({ field, read }) => read.kind === 'absent' || (read.kind === 'held' && representationKey(read.held.value) === representationKey(field.value))));
+    }
+};
+const abiOf = (member) => 'abi' in member && member.abi !== null && typeof member.abi === 'object' ? member.abi : null;
+/** Whether viewing `source` as `arm` puts a non-dynamic source field into a `dynamic` (or `dynamic | undefined`) target field. */
+const widensFieldIntoDynamic = (layouts, source, arm) => {
+    const sourceFields = source.kind === 'record' || source.kind === 'record-with-index'
+        ? source.fields
+        : source.kind === 'native-record-ref'
+            ? layouts.forShape(source.shapeId)
+            : null;
+    const armFields = arm.kind === 'record' ? arm.fields : arm.kind === 'native-record-ref' ? layouts.forShape(arm.shapeId) : null;
+    if (sourceFields === null || armFields === null)
+        return false;
+    const isDynamic = (value) => value.kind === 'dynamic' || (value.kind === 'optional' && value.payload.kind === 'dynamic');
+    return sourceFields.some((held) => {
+        const field = armFields.find((candidate) => candidate.key === held.key);
+        return field !== undefined && isDynamic(field.value) && !isDynamic(held.value);
+    });
+};
+export const structuralRecordViewPlan = (layouts, source, target, convertible) => {
+    if (source.kind === 'record' && target.kind === 'tagged-union') {
+        const plan = ownedRecordMaterializationPlan(source, target, layouts);
+        if (plan !== null)
+            return { kind: 'owned', plan };
+    }
+    const sourceCanViewRecord = source.kind === 'record' ||
+        source.kind === 'record-with-index' ||
+        source.kind === 'native-record-ref' ||
+        (source.kind === 'class-ref' && source.ownership === 'shared-refcount');
+    // A shared record can be narrower than the record arm selected for a
+    // field's physical union; the ordinary sum widener preserves identity and
+    // cannot re-layout it. Exactly one arm the source can become is the answer.
+    if (sourceCanViewRecord && target.kind === 'tagged-union') {
+        const homes = [];
+        for (const [index, arm] of target.arms.entries()) {
+            if (convertible(source, arm.value)) {
+                homes.push({ index, payload: null });
+                continue;
+            }
+            const payload = structuralRecordViewPlan(layouts, source, arm.value, convertible);
+            if (payload !== null)
+                homes.push({ index, payload });
+        }
+        // Two arms can both accept the record and still not be equal answers:
+        // `IteratorResult<number>` is `IteratorYieldResult<number> |
+        // IteratorReturnResult<any>`, and `{ value: i++, done: false }` fits the
+        // yield arm as written and the return arm only by BOXING `value` into its
+        // `any`. Boxing is a widening the program never asked for -- the record
+        // is already a value of the arm that holds its fields as they are -- so
+        // when exactly one home takes the record without widening a field into
+        // `dynamic`, that home is the answer, and the ambiguity guard below is
+        // reserved for arms that genuinely tie.
+        const exact = homes.length > 1 ? homes.filter((candidate) => !widensFieldIntoDynamic(layouts, source, target.arms[candidate.index].value)) : homes;
+        const home = exact.length === 1 ? exact[0] : undefined;
+        return home === undefined ? null : { kind: 'arm', source, target, index: home.index, payload: home.payload };
+    }
+    // The optional wrapper is peeled on both sides first: the question is about
+    // the two RECORD carriers, and an absence is answered by the optional's own
+    // presence flag either way.
+    if (target.kind === 'optional') {
+        const inner = source.kind === 'optional' ? source.payload : source;
+        const payload = structuralRecordViewPlan(layouts, inner, target.payload, convertible);
+        return payload === null ? null : { kind: 'optional', target, sourceOptional: source.kind === 'optional', payload };
+    }
+    // The mirror case: the TARGET has already had its optional erased by a `!`
+    // assertion (a declared return like `PropertyDescriptor | undefined`, read
+    // past a non-null assertion into a bare-record slot), but the source is
+    // still `optional(...)`. `narrowing`'s present-optional unwrap
+    // (`targets/cpp/conversions.ts`) only installs when the payload's own
+    // shape already equals the target's -- exactly the case that does NOT need
+    // a view. When the payload is a differently-interned shape (a per-overload
+    // host record vs. the canonical layout the binding declares) the unwrap has
+    // nothing to chain to, so the view has to reach past the optional itself.
+    if (source.kind === 'optional' && (target.kind === 'record' || target.kind === 'native-record-ref')) {
+        const payload = structuralRecordViewPlan(layouts, source.payload, target, convertible);
+        return payload === null ? null : { kind: 'assert', target, payload };
+    }
+    if (source.kind === 'tagged-union' && target.kind === 'tagged-union')
+        return recastUnionPlan(layouts, source, target, convertible);
+    const sourceIsRecord = source.kind === 'record' || source.kind === 'record-with-index' || source.kind === 'native-record-ref';
+    if (!sourceIsRecord && (source.kind !== 'class-ref' || source.ownership !== 'shared-refcount'))
+        return null;
+    if (source.kind === 'native-record-ref' && source.native !== null)
+        return null;
+    if (target.kind !== 'native-record-ref' && target.kind !== 'record')
+        return null;
+    if (target.kind === 'native-record-ref' && target.native !== null)
+        return null;
+    const targetIndexes = target.kind === 'record' ? [] : (layouts.indexesForShape?.(target.shapeId) ?? []);
+    if (targetIndexes.length > 0) {
+        if (source.kind !== 'record-with-index' ||
+            source.indexes.length !== targetIndexes.length ||
+            !targetIndexes.every((targetIndex, index) => {
+                const sourceIndex = source.indexes[index];
+                return (sourceIndex !== undefined &&
+                    sourceIndex.key === targetIndex.key &&
+                    representationKey(sourceIndex.value) === representationKey(targetIndex.value));
+            }))
+            return null;
+    }
+    else if (source.kind === 'record-with-index')
+        return null;
+    if (target.kind === 'native-record-ref' && (layouts.accessorsForShape?.(target.shapeId) ?? []).length > 0)
+        return null;
+    const targetFields = target.kind === 'record' ? target.fields : layouts.forShape(target.shapeId);
+    const sourceFields = source.kind === 'record' || source.kind === 'record-with-index' ? source.fields : layouts.forShape(source.shapeId);
+    if (targetFields === null || sourceFields === null)
+        return null;
+    // A record asserted to a wider shape that only adds members (`m[method] as
+    // HandlerSet<T> & { params }`, whose program writes `params` next) holds
+    // nothing a required added member could be read from: the language leaves
+    // it undefined until the write, and the view starts it value-initialized.
+    const onlyAdds = (source.kind === 'record' || source.kind === 'native-record-ref') &&
+        sourceFields.length < targetFields.length &&
+        sourceFields.every((held) => targetFields.some((field) => field.key === held.key));
+    const fields = [];
+    for (const field of targetFields) {
+        // A class method appears in the checker's structural field list, but it
+        // is not physical storage in the emitted class: the projected class
+        // member is the authority, and its receiver is bound into the callable
+        // member the interface record stores.
+        const abi = abiOf(field.value);
+        if (source.kind === 'class-ref' &&
+            abi !== null &&
+            abi.receiver === null &&
+            abi.restFrom === null &&
+            layouts.classMethodFor?.(source.declaration, field.key) === true) {
+            fields.push({ field, read: { kind: 'bound-method' } });
+            continue;
+        }
+        // Same fact one member kind over: `layouts.forShape` names a class's
+        // PHYSICAL storage, so a member backed by a getter is absent from it
+        // although every read of the class answers. Calling the getter is the
+        // read -- and asking before the field lookup is safe because a class
+        // never declares a key as both storage and an accessor.
+        if (source.kind === 'class-ref') {
+            const accessor = layouts.classAccessorFor?.(source.declaration, field.key) ?? null;
+            if (accessor !== null) {
+                if (!convertible(accessor, field.value))
+                    return null;
+                fields.push({ field, read: { kind: 'class-accessor', value: accessor } });
+                continue;
+            }
+        }
+        const held = sourceFields.find((candidate) => candidate.key === field.key);
+        if (!held) {
+            if (field.required && !onlyAdds)
+                return null;
+            fields.push({ field, read: { kind: 'absent' } });
+            continue;
+        }
+        if (!convertible(held.value, field.value))
+            return null;
+        fields.push({ field, read: { kind: 'held', held } });
+    }
+    const indexes = [];
+    if (targetIndexes.length > 0 && source.kind === 'record-with-index') {
+        for (const targetIndex of targetIndexes) {
+            const sourceIndex = source.indexes.find((index) => index.key === targetIndex.key);
+            if (!sourceIndex)
+                return null;
+            indexes.push({ target: targetIndex, source: sourceIndex });
+        }
+    }
+    const expando = targetIndexes.length === 0 &&
+        target.kind === 'native-record-ref' &&
+        source.kind === 'record-with-index' &&
+        source.indexes.length === 1 &&
+        source.indexes[0]?.key === 'string' &&
+        source.indexes[0]?.value.kind === 'dynamic';
+    return { kind: 'fields', source, target, fields, indexes, expando };
+};
+const recastUnionPlan = (layouts, source, target, convertible) => {
+    const arms = [];
+    for (const arm of source.arms) {
+        const key = representationKey(arm.value);
+        const exact = target.arms.findIndex((candidate) => representationKey(candidate.value) === key);
+        if (exact >= 0) {
+            arms.push({ index: exact, via: 'exact' });
+            continue;
+        }
+        let home = null;
+        for (const [index, candidate] of target.arms.entries()) {
+            if (convertible(arm.value, candidate.value)) {
+                home = { index, via: 'convert' };
+                break;
+            }
+            const viewed = structuralRecordViewPlan(layouts, arm.value, candidate.value, convertible);
+            if (viewed !== null) {
+                home = { index, via: viewed };
+                break;
+            }
+        }
+        if (home === null)
+            return null;
+        arms.push(home);
+    }
+    return { kind: 'recast-union', source, target, arms };
+};

package/dist/conversion/registry.d.ts

@@ -0,0 +1,217 @@
+import type { DeclarationId, FunctionId } from '../identity/ids.js';
+import type { CallableAbi, Ownership, Representation, ScalarDomain, TaggedUnionArm } from '../representation/model.js';
+import type { ClassifierContract, CoercionOperation, CollectionDomain, MaterializerContract } from './algebra.js';
+export type { CoercionOperation } from './algebra.js';
+/**
+ * The runtime's installed conversion primitives.
+ *
+ * Derivation never invents a classifier or a materializer. It only asks this
+ * registry whether one is installed for the exact identity a `Representation`
+ * carries -- a scalar domain, a class declaration, a function/ABI pair -- and
+ * reports `never` with a stated reason when the answer is no. Without this
+ * boundary, "the runtime does not have this yet" would silently become a
+ * fabricated `Atom` instead of an honest gap.
+ *
+ * Every lookup answers only "is one installed", never "would one be correct".
+ * Domain-equality and disjointness are proved by the caller from what comes
+ * back, not asserted by the registry.
+ */
+/** A classifier paired with the materializer whose acceptance domain it must equal. */
+export interface ClassifierMaterializerPair {
+    readonly classifier: ClassifierContract;
+    readonly materializer: MaterializerContract;
+}
+export interface ConversionRuntimeRegistry {
+    /**
+     * The exact JS tag/range materializer for one scalar domain, or `null` if
+     * none is installed. `boolean` and `number` must be backed only by an exact
+     * `typeof` tag check, never a coercive cast; the registry, not this module,
+     * owns that discipline -- derivation only ever forwards what comes back.
+     */
+    readonly scalarMaterializer: (domain: ScalarDomain) => ClassifierMaterializerPair | null;
+    /** The exact string-tag materializer. Never a `ToString` coercion. */
+    readonly stringMaterializer: () => ClassifierMaterializerPair | null;
+    /**
+     * The exact symbol-tag materializer.
+     *
+     * `typeof x === 'symbol'` is the only test there is: a symbol carries no
+     * structure to inspect, so classifying one out of a box is a tag check and
+     * nothing else. Installed only by a runtime whose box can report that tag.
+     */
+    readonly symbolMaterializer: () => ClassifierMaterializerPair | null;
+    /** The exact null-tag materializer, installed only when the runtime distinguishes `null` from `undefined`. */
+    readonly nullMaterializer: () => ClassifierMaterializerPair | null;
+    /** The exact undefined-tag materializer, installed only when the runtime distinguishes `undefined` from `null`. */
+    readonly undefinedMaterializer: () => ClassifierMaterializerPair | null;
+    /** The nominal-token materializer for one exact class and ownership. There is no structural fallback. */
+    readonly classRefMaterializer: (declaration: DeclarationId, ownership: Ownership) => ClassifierMaterializerPair | null;
+    /**
+     * A versioned host-protocol materializer -- the only admissible route for a
+     * native handle. `native === null` means the compiler's opaque
+     * `NativeHandle<protocol>` carrier; a native spelling is host-owned and
+     * needs an explicit host identity contract rather than inference from text.
+     */
+    readonly nativeHandleMaterializer: (protocol: string, version: number, native: string | null) => ClassifierMaterializerPair | null;
+    /**
+     * The materializer that allocates one exact frozen record shape. Required-
+     * presence checking and per-field recursion are the materializer's recipe;
+     * this registry only answers whether the shape and ownership are installed.
+     */
+    readonly recordMaterializer: (shapeId: string, ownership: Ownership) => MaterializerContract | null;
+    /**
+     * The IDENTITY-token materializer for one exact record shape and ownership
+     * -- reading back the very object a box already holds, rather than
+     * reconstructing one field by field the way `recordMaterializer` above does.
+     *
+     * A distinct entry because it is a distinct claim. `recordMaterializer`
+     * says "this runtime can BUILD a value of this shape from an arbitrary
+     * dynamic object, checking every required field"; this one says "a value of
+     * this shape that THIS program boxed can be recognized and handed back
+     * unchanged". The second is what a program that boxes its own typed record
+     * and reads it out again needs, it preserves identity where a rebuild would
+     * not, and it is available for shapes the first will never be available for
+     * -- so collapsing them into one entry would either over-claim the rebuild
+     * or lose the round trip.
+     *
+     * Serves `native-record-ref`. Compiler-owned `record` values use the
+     * distinct product materializer above: an exact boxed payload is only that
+     * product's identity-preserving fast path, not its capability claim.
+     */
+    readonly recordRefMaterializer: (shapeId: string, ownership: Ownership) => ClassifierMaterializerPair | null;
+    /**
+     * The installed materializable-ordinary-Array domain, narrower than a bare
+     * `IsArray` test. `null` when no such domain is installed for this ownership,
+     * for instance because materializing a fresh value as `borrowed` is
+     * incoherent -- a materialized value cannot borrow lifetime it never had.
+     */
+    readonly arrayObjectDomain: (ownership: Ownership) => CollectionDomain | null;
+    /** The authenticated callable-identity materializer for one exact function and ABI. Category-only checks do not qualify. */
+    readonly functionMaterializer: (functionId: FunctionId, abi: CallableAbi) => ClassifierMaterializerPair | null;
+    /**
+     * A checked adapter from a dynamic Function value to one evaluated callable
+     * ABI. Unlike `functionMaterializer`, this does not claim a declaration's
+     * identity: the Function tag authenticates only callability, and the
+     * materializer must perform the target ABI's argument/result conversions at
+     * each call.
+     */
+    readonly functionValueDispatchMaterializer: (abi: CallableAbi) => ClassifierMaterializerPair | null;
+    /**
+     * The exact runtime tag that marks an `Optional`'s absent case as `absence`,
+     * or `null` if none is installed.
+     *
+     * Takes the absence spelling rather than answering one fixed tag for both:
+     * `gea::Optional<T>` records ONLY presence/absence, not which of JavaScript's
+     * two absent values a caller meant, so a single program-wide tag would have
+     * to pick one spelling and would silently take the wrong branch reading the
+     * other -- `string | null` and `string | undefined` would become
+     * indistinguishable the moment either one round-trips through a dynamic
+     * value.
+     */
+    readonly optionalAbsenceTag: (absence: 'null' | 'undefined') => string | null;
+    /**
+     * Reading a carrier THIS PROGRAM BOXED back out of the box by identity, for
+     * a carrier whose whole value is one C++ object.
+     *
+     * A different claim from `recordMaterializer`'s: that one RECONSTRUCTS a
+     * value field by field from an arbitrary dynamic value, which for an open
+     * shape (a `dictionary`'s string keys, a `record-with-index`'s sidecar) has
+     * no semantics-preserving answer and is correctly refused. This one performs
+     * no walk at all -- `Value::box` recorded the payload's exact C++ type, so
+     * the round trip is a tag check plus an address check plus a handle copy,
+     * the identical primitive `recordRefMaterializer` already installs for a
+     * named record shape.
+     *
+     * Keyed on the whole `Representation` because these carriers have no shape
+     * id to key on: `gea::Dictionary<V>` and `gea::TypedArray<T>` are named by
+     * their element/value carrier, not by a layout in the sealed table.
+     */
+    readonly boxedIdentityMaterializer: (target: Representation) => ClassifierMaterializerPair | null;
+    /**
+     * The executable discriminator that selects one dynamic tagged-union arm.
+     * Its domain must name the same tag, payload type, or class-family test the
+     * emitter will execute; checker-only identities are not runtime evidence.
+     */
+    readonly taggedUnionArmClassifier: (arm: TaggedUnionArm) => ClassifierContract | null;
+    /**
+     * The test and load a *narrowing* read needs, for one exact source and target
+     * carrier -- or `null` when the runtime installs none.
+     *
+     * This is the one entry that does not start from the dynamic carrier, and it
+     * is here because the same discipline applies. `if (tag)` narrows a cell
+     * holding `Optional<string>` to a read typed `string`; `if (typeof x ===
+     * 'string')` narrows one holding a tagged union to a single arm. Both are
+     * real loads with real recipes -- a presence flag and a payload, a
+     * discriminant and an arm -- and neither is a cast. Without an installed pair
+     * the load has no meaning and preflight says so, which is why this asks the
+     * runtime instead of assuming every backend can do it.
+     *
+     * Both carriers are the key because a runtime may manage some pairs and not
+     * others: a `borrowed` payload has no lifetime an unwrap could hand back, and
+     * a target that matches no arm of the source union is not a narrowing at all.
+     * Answering `null` is the honest refusal in each case.
+     */
+    readonly narrowing: (source: Representation, target: Representation) => ClassifierMaterializerPair | null;
+    /**
+     * The construction a *widening* store needs, for one exact source and target
+     * carrier -- or `null` when the runtime installs none.
+     *
+     * This is `narrowing`'s mirror image, and it exists for the identical reason:
+     * `const x: boolean | number = someBoolean` puts a plain value where a
+     * `TaggedUnion` is declared, and the language really does widen there. A
+     * control-flow merge does the same thing when its branches carry different
+     * concrete carriers and the plan gives the merge itself a union -- neither
+     * branch's value ever passed through the dynamic carrier, so `narrowing`'s
+     * sibling in the dynamic-conversion algebra (`derive.ts`) has nothing to say
+     * about it; this is the entry that does.
+     *
+     * There is no membership test to make -- which arm is being constructed is
+     * already known statically, from the source's own carrier -- but the pair
+     * shape is kept the same as `narrowing`'s so both live in one conversion
+     * graph under one capability shape, and a `null` here refuses the same way
+     * `narrowing`'s does: cleanly, with the gap enumerated rather than papered
+     * over with an invented recipe.
+     */
+    readonly widening: (source: Representation, target: Representation) => ClassifierMaterializerPair | null;
+    /**
+     * Rebuilding one tagged union as another, for one exact source and target
+     * union -- or `null` when the runtime installs none.
+     *
+     * Two declared unions with the same member set do not have to agree on tag
+     * order -- `boolean | number` and `number | boolean` are two unrelated C++
+     * template instantiations -- which is exactly what a merge produces when its
+     * two branches arrive through independently-declared unions. Neither
+     * `narrowing` nor `widening` covers it: the target is not one arm of the
+     * source, and the source is not one arm of the target. Every value the
+     * source can hold must have a same-typed home among the target's arms, or
+     * the target is missing a member the source can actually carry -- a real
+     * hole, refused rather than dropped.
+     */
+    readonly recasting: (source: Representation, target: Representation) => ClassifierMaterializerPair | null;
+    /**
+     * The recipe for a pair none of the three above admit, decided from the
+     * two carriers alone: an upcast, a callable prefix drop, a record or union
+     * recast, a promise whose payload converts, an optional wrapped around a
+     * converting payload. No classifier, because no value can fail it. This is
+     * the whole of what the printer's ordered conversion chain answers beyond
+     * the three registered pairs, exposed so the conversion census
+     * (`conversion/nodes.ts`) can mint one node per pair from the same table
+     * the printer renders from, instead of a second predicate list that has to
+     * be kept in step with it by hand.
+     */
+    readonly staticRecipe: (source: Representation, target: Representation) => MaterializerContract | null;
+    /**
+     * An ECMAScript abstract operation over one exact source carrier --
+     * `ToNumber` for ApplyStringOrNumericBinaryOperator's ToNumeric and
+     * IsLessThan's numeric branch, `ToString` for concatenation and the
+     * string branch -- or `null` when the runtime installs none (a BigInt into
+     * a Number, a Date's `valueOf`-first ToPrimitive, an object whose own
+     * `toString` would have to be called). Distinct from the three pair tables
+     * above and from `staticRecipe`: those answer "how does a value of X get
+     * STORED as Y", which for a `string` into a `number` is an exact tag read
+     * that refuses `"3"`; a coercion answers "what is ToNumber of this value",
+     * which accepts it and yields `3`. One (source, target) pair, two different
+     * conversions -- so the slot census names the operation, never just the
+     * target, and the census node carries it in its id.
+     */
+    readonly coercion: (source: Representation, operation: CoercionOperation) => MaterializerContract | null;
+}

package/dist/conversion/registry.js

@@ -0,0 +1 @@
+export {};

package/dist/diagnostics/model.d.ts

@@ -0,0 +1,76 @@
+import type { ComponentId, OperationId } from '../identity/ids.js';
+import type { PrimitiveFamily } from '../semantics/model/coverage.js';
+/**
+ * Diagnostics.
+ *
+ * A diagnostic is keyed by semantic identity. A source location may accompany
+ * it for a human to read, but it never flows back into admission: the moment a
+ * location decides whether something compiles, the compiler has started
+ * recognizing programs instead of implementing a language.
+ *
+ * The sweep collects every independently provable failure in an authority
+ * component rather than throwing at the first one, and it marks derived
+ * failures as derived so one missing carrier does not read as fifty unrelated
+ * language defects.
+ */
+export type DiagnosticSeverity = 'root' | 'derived' | 'unsupported';
+export interface DiagnosticLocation {
+    /** Display only. Never an admission input. */
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface Diagnostic {
+    /** Stable identity, so repeated sweeps can be compared row by row. */
+    readonly id: string;
+    readonly severity: DiagnosticSeverity;
+    readonly component: ComponentId;
+    readonly operation: OperationId | null;
+    /** The primitive family whose absence explains this row, when known. */
+    readonly missingPrimitive: PrimitiveFamily | null;
+    readonly message: string;
+    readonly location: DiagnosticLocation | null;
+    /** For a derived row, the root rows it follows from. */
+    readonly causedBy: readonly string[];
+}
+/** Failure evidence produced before the sweep assigns root/derived severity. */
+export type DiagnosticEvidence = Omit<Diagnostic, 'severity' | 'causedBy'>;
+/** A complete sweep result. Bounded views may be derived; this is the whole set. */
+export interface DiagnosticReport {
+    readonly diagnostics: readonly Diagnostic[];
+    readonly components: readonly ComponentId[];
+    /** True only when the transaction proved every obligation it censused. */
+    readonly clean: boolean;
+    /**
+     * True when the frontend, the census and the plan raised nothing, before
+     * preflight's obligations were consulted. This is the gate lowering runs
+     * on: a program whose plan verifies lowers whether or not it certifies, and
+     * what it cannot lower is a refusal row, because certification covers the
+     * lowered IR. `clean` implies `planClean`; the converse is the uncertified,
+     * lowerable program.
+     */
+    readonly planClean: boolean;
+}
+/**
+ * Deterministic ordering: roots first, then by component, then by identity.
+ *
+ * Determinism is what makes two sweeps comparable. Ordering by discovery time
+ * or by source position would make an unchanged compiler produce different
+ * reports on different machines.
+ */
+export declare const orderDiagnostics: (diagnostics: readonly Diagnostic[]) => readonly Diagnostic[];
+/**
+ * Merge exact duplicates by identity while keeping every component they arose
+ * from, so a shared root reported from two components stays one row.
+ */
+export declare const mergeDiagnostics: (diagnostics: readonly Diagnostic[]) => readonly Diagnostic[];
+/** Group a report by authority component for planning. */
+export declare const groupByComponent: (report: DiagnosticReport) => ReadonlyMap<ComponentId, readonly Diagnostic[]>;
+/** A collector that gathers a whole component's failures before aborting. */
+export interface DiagnosticSink {
+    readonly report: (diagnostic: Diagnostic) => void;
+    /** Whether nothing reported so far survives merging -- asked once, between the plan's rows and preflight's, for `DiagnosticReport.planClean`. */
+    readonly cleanSoFar: () => boolean;
+    readonly finish: (components: readonly ComponentId[], planClean?: boolean) => DiagnosticReport;
+}
+export declare const createDiagnosticSink: () => DiagnosticSink;

package/dist/diagnostics/model.js

@@ -0,0 +1,60 @@
+const severityOrder = Object.freeze({ root: 0, unsupported: 1, derived: 2 });
+/**
+ * Deterministic ordering: roots first, then by component, then by identity.
+ *
+ * Determinism is what makes two sweeps comparable. Ordering by discovery time
+ * or by source position would make an unchanged compiler produce different
+ * reports on different machines.
+ */
+export const orderDiagnostics = (diagnostics) => [...diagnostics].sort((left, right) => {
+    const bySeverity = severityOrder[left.severity] - severityOrder[right.severity];
+    if (bySeverity !== 0)
+        return bySeverity;
+    if (left.component !== right.component)
+        return left.component < right.component ? -1 : 1;
+    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+});
+/**
+ * Merge exact duplicates by identity while keeping every component they arose
+ * from, so a shared root reported from two components stays one row.
+ */
+export const mergeDiagnostics = (diagnostics) => {
+    const byId = new Map();
+    for (const diagnostic of diagnostics) {
+        const existing = byId.get(diagnostic.id);
+        if (!existing) {
+            byId.set(diagnostic.id, diagnostic);
+            continue;
+        }
+        byId.set(diagnostic.id, {
+            ...existing,
+            causedBy: [...new Set([...existing.causedBy, ...diagnostic.causedBy])].sort()
+        });
+    }
+    return orderDiagnostics([...byId.values()]);
+};
+/** Group a report by authority component for planning. */
+export const groupByComponent = (report) => {
+    const grouped = new Map();
+    for (const diagnostic of orderDiagnostics(report.diagnostics)) {
+        const bucket = grouped.get(diagnostic.component) ?? [];
+        bucket.push(diagnostic);
+        grouped.set(diagnostic.component, bucket);
+    }
+    return grouped;
+};
+export const createDiagnosticSink = () => {
+    const collected = [];
+    const cleanSoFar = () => mergeDiagnostics(collected).length === 0;
+    return {
+        report: (diagnostic) => {
+            collected.push(diagnostic);
+        },
+        cleanSoFar,
+        finish: (components, planClean) => {
+            const diagnostics = mergeDiagnostics(collected);
+            const clean = diagnostics.length === 0;
+            return { diagnostics, components: [...components].sort(), clean, planClean: planClean ?? clean };
+        }
+    };
+};

package/dist/diagnostics/sweep.d.ts

@@ -0,0 +1,31 @@
+import type { NodeId } from '../identity/ids.js';
+import type { PreflightReport } from '../preflight/run.js';
+import type { RepresentationPublication } from '../representation/publish.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import type { DiagnosticEvidence, DiagnosticLocation, DiagnosticReport } from './model.js';
+export interface SweepInput {
+    readonly graph: SemanticGraph;
+    readonly representations: RepresentationPublication;
+    /** Absent when preflight did not run, which is itself not a failure to report. */
+    readonly preflight: PreflightReport | null;
+    /** Diagnostics the frontend already produced, merged in rather than re-derived. */
+    readonly frontend: readonly DiagnosticEvidence[];
+    /**
+     * Where a node identity is, for display -- `FrontendResult.locationOfNode`.
+     *
+     * Every row below carried `location: null` before this existed, so a build
+     * that failed 334 mandatory obligations printed 334 component ids and named
+     * no file. The component is a semantic identity and cannot be turned into a
+     * place in the program; only the frontend's own identity walk can, which is
+     * why this arrives as a function rather than being derived here.
+     */
+    readonly locationOfNode?: (node: NodeId) => DiagnosticLocation | null;
+}
+/**
+ * Collect every layer's failures into one deterministically ordered report.
+ *
+ * Optional preflight obligations are deliberately absent: an unavailable fast
+ * path is not a defect, and reporting one as a failure would train a reader to
+ * ignore the report.
+ */
+export declare const sweepDiagnostics: (input: SweepInput) => DiagnosticReport;