@scriptc/compiler 0.4.6 → 0.4.7

package/dist/frontend/lowering/expressions/object-literals.js

@@ -10,15 +10,18 @@ import { NARROW_FIRST } from "../surfaces.js";
 import { recordShapeMismatchDiag, unionLiteralMismatchDiag, } from "../../../diagnostics/diagnostic.js";
 import { PoisonError, jsFuncNameOf, neverTaintedJsType } from "../lowerer.js";
 import { lowerIndexMergeHelper } from "../containers/indexed-objects.js";
+import { recordMayKeepSource } from "../record-sources.js";
 import { PERF_ENTRY_MARKER, X509_PUBLIC_KEY_FIELD, isGenericCallableMemberType, jsOpenObjectType, } from "../../type-mapper.js";
 import { isSafeToRepeat } from "./evaluation-safety.js";
 import { tryLowerExpression } from "./try-lower-expression.js";
 import { classSymbolKeyOf, fenceSymbolFieldCopy, symbolFieldDisplayName, } from "../symbol-fields.js";
 import { planUnionRetag } from "../union-retag.js";
+import { literalValues } from "../../literal-values.js";
 import { jsHoldsDynObject, runtimeOptionalStorageOperand } from "../lower-exprs.js";
 import { builtinGlobalValue } from "./property-access.js";
 import { holdsEvolvingArray } from "../lower-stmts.js";
 import { builtinNamespaceValue } from "../builtin-namespaces.js";
+import { tsUntypedGlobalValue } from "../global-values.js";
 /** `{ a: 1, b: "x" }` → recordLit. The record type comes from the
  * contextual type when tsc has one (annotated declarations, arguments,
  * nested literals) and from the literal's own type otherwise — both intern
@@ -154,6 +157,34 @@ function pureKeyExpr(lowerer, expr) {
         return expr.templateSpans.nodes.every((s) => pureKeyExpr(lowerer, s.expression));
     return false;
 }
+/** Whether expr reads no state that evaluating other code could change:
+ * literals, `const` bindings, and unary operators over those. */
+function constantInitializer(lowerer, expr) {
+    if (ts.isParenthesizedExpression(expr) || ts.isNonNullExpression(expr))
+        return constantInitializer(lowerer, expr.expression);
+    if (ts.isAsExpression(expr) || ts.isTypeAssertion(expr))
+        return constantInitializer(lowerer, expr.expression);
+    if (ts.isStringLiteralLike(expr) || ts.isNumericLiteral(expr))
+        return true;
+    if (expr.kind === ts.SyntaxKind.TrueKeyword ||
+        expr.kind === ts.SyntaxKind.FalseKeyword ||
+        expr.kind === ts.SyntaxKind.NullKeyword)
+        return true;
+    if (ts.isPrefixUnaryExpression(expr) &&
+        (expr.operator === ts.SyntaxKind.MinusToken ||
+            expr.operator === ts.SyntaxKind.PlusToken ||
+            expr.operator === ts.SyntaxKind.ExclamationToken ||
+            expr.operator === ts.SyntaxKind.TildeToken))
+        return constantInitializer(lowerer, expr.operand);
+    if (ts.isIdentifier(expr)) {
+        const decls = lowerer.checker.getSymbolAtLocation(expr)?.declarations ?? [];
+        return (decls.length > 0 &&
+            decls.every((d) => ts.isVariableDeclaration(d) &&
+                ts.isVariableDeclarationList(d.parent) &&
+                (ts.getCombinedNodeFlags(d) & ts.NodeFlags.Const) !== 0));
+    }
+    return false;
+}
 /** A property's field name: identifier/string-literal keys directly,
  * foldable computed keys through literalComputedKey (the syntax pass
  * fenced everything else). */
@@ -401,8 +432,11 @@ export function lowerDynObjectLiteral(lowerer, expr, boxValue, conditionalArms =
             // A PURE member read a JS file cannot lower (a namespace object
             // in an export aggregate): the slot takes a boxed fence closure —
             // the diagnostics defer to the runtime-fence ledger, the object
-            // builds, and only USING the member stops the run.
-            const pureMember = ts.isIdentifier(valueExpr);
+            // builds, and only USING the member stops the run. A TypeScript
+            // source keeps the compile-time refusal: the closure would answer
+            // typeof "function" and undefined members where Node reads the
+            // value.
+            const pureMember = ts.isIdentifier(valueExpr) && isJsSourceFile(ts.getSourceFileOfNode(prop));
             if (!(err instanceof PoisonError) || !pureMember)
                 throw err;
             const fence = lowerer.deferToRuntimeFence(propDiagsBefore, prop, {
@@ -493,9 +527,7 @@ function fenceAccessorSpreadSource(lowerer, prop, srcShape) {
 /** Only definitely present later records replace earlier defaults. A
  * callback binding may store undefined despite its checker annotation. */
 function laterSpreadType(lowerer, expr) {
-    let source = expr;
-    while (ts.isParenthesizedExpression(source))
-        source = source.expression;
+    const source = spreadSourceNode(lowerer, expr);
     if (ts.isIdentifier(source))
         return lowerer.lowerExpr(source).type;
     return lowerer.mapTypeOf(lowerer.typeOf(source));
@@ -772,7 +804,11 @@ function lowerOptionalIndexSpreadSource(lowerer, source, loc) {
         ? selected
         : { kind: "seqExpr", stmts: prefix, result: selected, type: recordType, loc };
 }
-export function lowerObjectLiteral(lowerer, expr, expected) {
+export function lowerObjectLiteral(lowerer, expr, expected, 
+/** Build exactly at `expected` (one arm of a distributed union spread,
+ * lowerDistributedUnionSpread): the checker types the literal as the
+ * whole union, so its contextual type cannot choose the layout. */
+exact = false) {
     // A spread of an untyped (`any`) source into a typed slot: TypeScript
     // types such a literal `any`, and the copy holds whatever own properties
     // the source has at runtime. Build it as a checked-dynamic object, then
@@ -861,7 +897,7 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
                 tryLowerExpression(lowerer, property.expression)?.type.kind === "dyn"))) {
         return lowerDynObjectLiteral(lowerer, expr);
     }
-    const unionClone = lowerUnionRecordClone(lowerer, expr);
+    const unionClone = exact ? null : lowerUnionRecordClone(lowerer, expr);
     if (unionClone !== null)
         return unionClone;
     // The RUNTIME-KEYED literal (JS): a computed key that doesn't fold to a
@@ -993,7 +1029,7 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
         ts.constituentTypes(tsType).some((t) => ts.symbolNameOf(t.getSymbol()) === "PromiseLike")) {
         tsType = lowerer.checker.getAwaitedType(tsType) ?? tsType;
     }
-    let mapped = lowerer.mapTypeOf(tsType);
+    let mapped = exact && expected ? expected : lowerer.mapTypeOf(tsType);
     // A checked-dynamic source has runtime keys even when later explicit
     // fields make the literal's inferred type look like a fixed record.
     // Keep a checked-dynamic destination in that representation so copying
@@ -1193,14 +1229,27 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
         lowerer.unsupported("SC1090", deferredConditionalSpread, CONDITIONAL_SPREAD_FENCE);
     }
     if (!mapped || mapped.kind !== "record") {
+        // Distribute against the contextual union when there is one (its arms
+        // carry the discriminants), else against the literal's own union.
+        const ctx = lowerer.mapTypeOf(tsType);
+        const unionCtx = ctx?.kind === "union" ? ctx : mapped;
+        const distributed = exact ? null : lowerDistributedUnionSpread(lowerer, expr, unionCtx);
+        if (distributed)
+            return distributed;
         // A spread merge over UNION-typed sources (`{ ...base, ...override }`
         // with `base`, `override` of arm-union types) has one field set per
         // combination of source arms, so its own type is a union of records.
         // No single arm of the contextual union can hold that value without
         // dropping the fields the other arms contributed (Node keeps them
         // all), and a runtime tag would be a guess about which arm the value
-        // "is". Refuse, naming the candidate arms.
+        // "is". Build the object Node builds instead — the checked-dynamic
+        // copy — and let the union's checked conversion validate it.
         if (mapped?.kind === "union") {
+            if (!exact && unionCtx?.kind === "union") {
+                const merged = lowerUnionSpreadMergeDyn(lowerer, expr, unionCtx);
+                if (merged)
+                    return merged;
+            }
             const members = tsType.isUnionType() ? ts.constituentTypes(tsType) : [tsType];
             const arms = [...new Set(members.map((m) => lowerer.checker.typeToString(m)))];
             lowerer.pushDiag(unionLiteralMismatchDiag(lowerer.checker.typeToString(tsType), arms, locOf(expr)));
@@ -1208,7 +1257,20 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
         }
         lowerer.badType(expr, tsType);
     }
-    let type = mapped;
+    // An enclosing literal that built at its OWN type (its context had no
+    // layout) asks for the matching own layout of this nested literal. When
+    // this literal's contextual layout cannot reach that slot, build at it:
+    // the enclosing literal's coercion then decides, and the width lifts
+    // (the index-signature overflow capture included) carry the whole tree
+    // into the real destination. Otherwise the two layers disagree and the
+    // SC2002 names the source literal's own type as the expected one.
+    const layout = expected &&
+        !typeEquals(mapped, expected) &&
+        lowerer.widthLiftPlan(mapped, expected) === null &&
+        typeEquals(lowerer.mapTypeOf(lowerer.typeOf(expr)) ?? mapped, expected)
+        ? expected
+        : mapped;
+    let type = layout;
     // A fresh, plain literal can construct its fields directly for a known
     // destination with the same field set. This matters for inferred
     // conditional records: an empty array in one arm has no element layout
@@ -1219,15 +1281,31 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
         expr.properties.nodes.every((p) => ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p))) {
         const own = lowerer.shapes.get(type.shapeId);
         const target = lowerer.shapes.get(expected.shapeId);
-        if (!own.tuple &&
+        // The field set to compare is the LITERAL's: its checker type. The
+        // contextual type a few lines up can be wider than what the literal
+        // writes (an unannotated method checked against a generic slot's
+        // signature: `{ content, details }` under a contextual
+        // `AgentToolResult<unknown>` whose optional members the literal never
+        // mentions), and the destination still names the same fields as the
+        // literal, so the build can construct them directly. Only when the
+        // contextual build has no conversion into the destination at all: a
+        // value that converts today keeps its exact construction.
+        const ownType = lowerer.mapTypeOf(lowerer.typeOf(expr));
+        const ownChecked = ownType?.kind === "record" &&
+            ownType.shapeId !== type.shapeId &&
+            lowerer.widthLiftPlan(type, expected) === null
+            ? lowerer.shapes.get(ownType.shapeId)
+            : undefined;
+        const fits = (from) => !from.tuple &&
             !target.tuple &&
-            !own.indexValue &&
+            !from.indexValue &&
             !target.indexValue &&
-            !shapeHasAccessorSlots(own) &&
+            !shapeHasAccessorSlots(from) &&
             !shapeHasAccessorSlots(target) &&
-            target.fields.every((field) => own.fields.some((candidate) => candidate.name === field.name) ||
+            target.fields.every((field) => from.fields.some((candidate) => candidate.name === field.name) ||
                 (field.type.kind === "union" && lowerer.armTag(field.type.unionId, UNDEFINED_T) >= 0)) &&
-            own.fields.every((field) => target.fields.some((candidate) => candidate.name === field.name))) {
+            from.fields.every((field) => target.fields.some((candidate) => candidate.name === field.name));
+        if (fits(own) || (ownChecked !== undefined && fits(ownChecked))) {
             type = { kind: "record", shapeId: expected.shapeId };
         }
     }
@@ -1357,7 +1435,13 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
                         lowerer.badType(valueNode, lowerer.typeOf(valueNode));
                     overrides.push({ name, value });
                 }
-                return { kind: "recordClone", source, overrides, type, loc };
+                return lowerer.keyOrder.clone({
+                    kind: "recordClone",
+                    source,
+                    overrides,
+                    type,
+                    loc,
+                });
             }
             leadingSpreadLowered = source;
         }
@@ -1591,6 +1675,16 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
     const droppedNames = new Set();
     // The order this literal creates its keys in (key-order-witness.ts).
     const orderSegments = [];
+    // The literal's contributors when a spread drops source keys the target
+    // has no slot for (key-order-witness.ts keepWidthSpreads). Conditional
+    // spreads leave the literal to the static copy.
+    const widthSegments = [];
+    let widthDrops = false;
+    let widthBlocked = false;
+    // A checked-dynamic spread source's own keys are a run-time fact: even
+    // when the checker's shape fits the target, the copied object can hold
+    // more (slice 3).
+    let widthDynSource = false;
     for (const prop of expr.properties.nodes) {
         // A later contributor can mutate an earlier source or overwrite a
         // value with effects. Snapshot pending fields at their source position,
@@ -1604,6 +1698,7 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
         if (ts.isSpreadAssignment(prop)) {
             const cs = conditionalSpreadOf(prop.expression) ?? andSpreadOf(lowerer, prop.expression);
             if (cs && cs !== "unsupported") {
+                widthBlocked = true;
                 // `...(c ? { k: v } : {})` — one conditional field per carried
                 // property at the spread's own position: cond evaluates exactly
                 // once (into a hidden local when several fields test it), each
@@ -1676,15 +1771,25 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
             // earlier ones (JS last-write-wins). Evaluate the source exactly
             // once, including empty sources and those whose fields are all
             // overridden. Field snapshots above preserve the copy order.
-            let srcNode = prop.expression;
-            while (ts.isParenthesizedExpression(srcNode))
-                srcNode = srcNode.expression;
+            const srcNode = spreadSourceNode(lowerer, prop.expression);
             const condRecord = conditionalRecordSpreadOf(lowerer, prop.expression);
-            const srcLowered = capture(condRecord !== null
+            let srcLowered = capture(condRecord !== null
                 ? lowerConditionalRecordSpread(lowerer, condRecord, locOf(prop))
                 : prop === expr.properties.nodes[0] && leadingSpreadLowered !== null
                     ? leadingSpreadLowered
-                    : lowerer.lowerExpr(srcNode));
+                    : (lowerer.spreadArmOverrides.get(srcNode) ?? lowerer.lowerExpr(srcNode)));
+            {
+                const narrowed = checkedSpreadSource(lowerer, srcNode, srcLowered);
+                if (narrowed !== null)
+                    srcLowered = capture(narrowed);
+            }
+            if (condRecord !== null || srcLowered.kind !== "varRef")
+                widthBlocked = true;
+            else {
+                widthSegments.push({ kind: "spread", value: srcLowered });
+                if (srcLowered.type.kind === "dyn")
+                    widthDynSource = true;
+            }
             // Array callbacks can receive a record-or-undefined ABI even when
             // TypeScript describes a required record. Select the copy strategy
             // from that stored representation so absent sources copy nothing.
@@ -1704,12 +1809,10 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
                 const def = lowerer.unions.get(srcType.unionId);
                 const recArms = def?.arms.filter((a) => a.kind === "record") ?? [];
                 if (!def ||
-                    recArms.length !== 1 ||
+                    recArms.length === 0 ||
                     !def.arms.every((a) => a.kind === "record" || isUnitType(a))) {
                     lowerer.unsupported("SC1090", prop, `object spread of '${lowerer.fmt(srcType)}' sources (only known record shapes spread — ${NARROW_FIRST})`);
                 }
-                const recArm = recArms[0];
-                const recTag = def.arms.indexOf(recArm);
                 // A checked-dynamic VALUE under the union-mapped checker type
                 // (a JS dyn-holding binding): the present/absent desugar tests
                 // union tags a dyn box does not carry — fence honestly instead
@@ -1718,230 +1821,240 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
                 if (probedSrc?.type.kind === "dyn") {
                     lowerer.unsupported("SC1090", prop, `object spread of a checked-dynamic '${lowerer.fmt(srcType)}' source (${NARROW_FIRST})`);
                 }
-                const srcShape = lowerer.shapes.get(recArm.shapeId);
-                if (!srcShape)
-                    throw new InternalCompilerError(`lowerer bug: spread of unknown shape ${recArm.shapeId}`);
-                fenceAccessorSpreadSource(lowerer, prop, srcShape);
-                if (srcShape.indexValue || shape.indexValue) {
-                    const fallback = dynSpreadLiteral(lowerer, expr, type);
-                    if (fallback)
-                        return fallback;
-                    lowerer.unsupported("SC1090", prop, "object spread involving index-signature shapes (overflow keys are runtime state — copy the fields you need explicitly)");
-                }
-                const laterNames = new Set();
-                for (const later of expr.properties.nodes.slice(expr.properties.nodes.indexOf(prop) + 1)) {
-                    if (ts.isSpreadAssignment(later)) {
-                        if (conditionalSpreadOf(later.expression) || andSpreadOf(lowerer, later.expression))
+                // Several record arms: each arm contributes its own fields behind its
+                // tag test, wrapping the earlier contributor, so a key that arm lacks
+                // keeps the earlier value (JS copies only the arm's own keys).
+                for (const recArmCandidate of recArms) {
+                    const recArm = recArmCandidate;
+                    const recTag = def.arms.indexOf(recArm);
+                    const srcShape = lowerer.shapes.get(recArm.shapeId);
+                    if (!srcShape)
+                        throw new InternalCompilerError(`lowerer bug: spread of unknown shape ${recArm.shapeId}`);
+                    fenceAccessorSpreadSource(lowerer, prop, srcShape);
+                    if (srcShape.indexValue || shape.indexValue) {
+                        const fallback = dynSpreadLiteral(lowerer, expr, type);
+                        if (fallback)
+                            return fallback;
+                        lowerer.unsupported("SC1090", prop, "object spread involving index-signature shapes (overflow keys are runtime state — copy the fields you need explicitly)");
+                    }
+                    const laterNames = new Set();
+                    for (const later of expr.properties.nodes.slice(expr.properties.nodes.indexOf(prop) + 1)) {
+                        if (ts.isSpreadAssignment(later)) {
+                            if (conditionalSpreadOf(later.expression) || andSpreadOf(lowerer, later.expression))
+                                continue;
+                            const lt = laterSpreadType(lowerer, later.expression);
+                            if (lt?.kind === "record") {
+                                // A field the later source may lack defines nothing.
+                                for (const lf of lowerer.shapes.get(lt.shapeId)?.fields ?? [])
+                                    if (!canLackField(lf.type))
+                                        laterNames.add(lf.name);
+                            }
                             continue;
-                        const lt = laterSpreadType(lowerer, later.expression);
-                        if (lt?.kind === "record") {
-                            // A field the later source may lack defines nothing.
-                            for (const lf of lowerer.shapes.get(lt.shapeId)?.fields ?? [])
-                                if (!canLackField(lf.type))
-                                    laterNames.add(lf.name);
                         }
-                        continue;
-                    }
-                    if (later.name &&
-                        (ts.isIdentifier(later.name) ||
-                            ts.isStringLiteral(later.name) ||
-                            ts.isNumericLiteral(later.name) ||
-                            (ts.isComputedPropertyName(later.name) &&
-                                literalComputedKey(lowerer, later.name) !== null))) {
-                        laterNames.add(propNameText(lowerer, later.name));
-                    }
-                }
-                const srcRef = () => srcLowered ?? lowerer.lowerExpr(srcNode);
-                const srcNarrowed = () => ({
-                    kind: "unionNarrow",
-                    unionId: srcType.unionId,
-                    tag: recTag,
-                    value: srcRef(),
-                    type: recArm,
-                    loc: locOf(prop),
-                });
-                // The source PROVEN present: the checked extraction `x!` lowers to
-                // (narrowedArmHelper + checkedNarrowCall). A required target field
-                // with no earlier contributor has no absent representation, so
-                // `{ ...maybeRecord }` into it must find the record: the unit arm
-                // throws the catchable TypeError instead of leaving the slot unset
-                // (divergence 38's lying-assertion stance — the checker typed the
-                // spread's fields optional, so only a cast or an unchecked indexed
-                // read reaches this shape).
-                const srcPresent = () => {
-                    const helper = lowerer.narrowedArmHelper(srcType.unionId, recArm, locOf(prop));
-                    return helper
-                        ? lowerer.checkedNarrowCall(helper, srcRef(), recArm, locOf(prop))
-                        : srcNarrowed();
-                };
-                orderSegments.push({ kind: "spread", shapeId: recArm.shapeId, maybeAbsent: true });
-                for (const f of srcShape.fields) {
-                    if (laterNames.has(f.name))
-                        continue;
-                    const targetType = fieldTypes.get(f.name);
-                    // No slot on the target shape: the copy DROPS the field
-                    // (divergence 36's stance, same as the plain-record spread).
-                    if (!targetType)
-                        continue;
-                    if (conditionalNames.has(f.name)) {
-                        const conditionalDyn = conditionalFallback();
-                        if (conditionalDyn)
-                            return conditionalDyn;
-                        lowerer.unsupported("SC1090", prop, `spread of '${f.name}' over an earlier conditional spread (the desugar keeps one entry per name — restructure so each name has one contributor)`);
+                        if (later.name &&
+                            (ts.isIdentifier(later.name) ||
+                                ts.isStringLiteral(later.name) ||
+                                ts.isNumericLiteral(later.name) ||
+                                (ts.isComputedPropertyName(later.name) &&
+                                    literalComputedKey(lowerer, later.name) !== null))) {
+                            laterNames.add(propNameText(lowerer, later.name));
+                        }
                     }
-                    const fRead = (present = false) => ({
-                        kind: "recordGet",
-                        obj: present ? srcPresent() : srcNarrowed(),
-                        shapeId: recArm.shapeId,
-                        field: f.name,
-                        type: f.type,
-                        loc: locOf(prop),
-                    });
-                    let cond = {
-                        kind: "unionIsTag",
+                    const srcRef = () => srcLowered ?? lowerer.lowerExpr(srcNode);
+                    const srcNarrowed = () => ({
+                        kind: "unionNarrow",
                         unionId: srcType.unionId,
                         tag: recTag,
-                        negated: false,
                         value: srcRef(),
-                        type: BOOL,
+                        type: recArm,
                         loc: locOf(prop),
+                    });
+                    // The source PROVEN present: the checked extraction `x!` lowers to
+                    // (narrowedArmHelper + checkedNarrowCall). A required target field
+                    // with no earlier contributor has no absent representation, so
+                    // `{ ...maybeRecord }` into it must find the record: the unit arm
+                    // throws the catchable TypeError instead of leaving the slot unset
+                    // (divergence 38's lying-assertion stance — the checker typed the
+                    // spread's fields optional, so only a cast or an unchecked indexed
+                    // read reaches this shape).
+                    const srcPresent = () => {
+                        const helper = lowerer.narrowedArmHelper(srcType.unionId, recArm, locOf(prop));
+                        return helper
+                            ? lowerer.checkedNarrowCall(helper, srcRef(), recArm, locOf(prop))
+                            : srcNarrowed();
                     };
-                    let thenVal;
-                    // A source field that can be absent copies only when present.
-                    const fieldPresent = () => ({
-                        kind: "logical",
-                        op: "&&",
-                        left: cond,
-                        right: {
-                            kind: "recordHas",
-                            obj: {
-                                kind: "unionNarrow",
-                                unionId: srcType.unionId,
-                                tag: recTag,
-                                value: srcRef(),
-                                type: recArm,
-                                loc: locOf(prop),
-                            },
+                    orderSegments.push({ kind: "spread", shapeId: recArm.shapeId, maybeAbsent: true });
+                    for (const f of srcShape.fields) {
+                        if (laterNames.has(f.name))
+                            continue;
+                        const targetType = fieldTypes.get(f.name);
+                        // No slot on the target shape: the static copy skips the field,
+                        // and the literal keeps it through a kept source view when the
+                        // program can observe it (keepWidthSpreads).
+                        if (!targetType) {
+                            widthDrops = true;
+                            continue;
+                        }
+                        if (conditionalNames.has(f.name)) {
+                            const conditionalDyn = conditionalFallback();
+                            if (conditionalDyn)
+                                return conditionalDyn;
+                            lowerer.unsupported("SC1090", prop, `spread of '${f.name}' over an earlier conditional spread (the desugar keeps one entry per name — restructure so each name has one contributor)`);
+                        }
+                        const fRead = (present = false) => ({
+                            kind: "recordGet",
+                            obj: present ? srcPresent() : srcNarrowed(),
                             shapeId: recArm.shapeId,
                             field: f.name,
+                            type: f.type,
+                            loc: locOf(prop),
+                        });
+                        let cond = {
+                            kind: "unionIsTag",
+                            unionId: srcType.unionId,
+                            tag: recTag,
+                            negated: false,
+                            value: srcRef(),
                             type: BOOL,
                             loc: locOf(prop),
-                        },
-                        type: BOOL,
-                        loc: locOf(prop),
-                    });
-                    const canBeAbsent = f.type.kind === "union" && lowerer.armTag(f.type.unionId, UNDEFINED_T) >= 0;
-                    if (typeEquals(f.type, targetType)) {
-                        thenVal = fRead();
-                        if (canBeAbsent)
-                            cond = fieldPresent();
-                    }
-                    else if (f.type.kind === "union" &&
-                        lowerer.armTag(f.type.unionId, UNDEFINED_T) >= 0 &&
-                        typeEquals(lowerer.stripUndefinedArm(f.type), targetType)) {
-                        // Optional source field into a required target slot: present
-                        // means the source holds the record AND the field its value
-                        // arm — the spread-override completion, union-source form.
-                        const ftUndef = lowerer.armTag(f.type.unionId, UNDEFINED_T);
-                        cond = {
+                        };
+                        let thenVal;
+                        // A source field that can be absent copies only when present.
+                        const fieldPresent = () => ({
                             kind: "logical",
                             op: "&&",
                             left: cond,
                             right: {
-                                kind: "unionIsTag",
-                                unionId: f.type.unionId,
-                                tag: ftUndef,
-                                negated: true,
-                                value: fRead(),
+                                kind: "recordHas",
+                                obj: {
+                                    kind: "unionNarrow",
+                                    unionId: srcType.unionId,
+                                    tag: recTag,
+                                    value: srcRef(),
+                                    type: recArm,
+                                    loc: locOf(prop),
+                                },
+                                shapeId: recArm.shapeId,
+                                field: f.name,
                                 type: BOOL,
                                 loc: locOf(prop),
                             },
                             type: BOOL,
                             loc: locOf(prop),
-                        };
-                        const ftDef = lowerer.unions.get(f.type.unionId);
-                        if (targetType.kind === "union") {
-                            const retag = lowerer.unionRetagHelper(f.type.unionId, targetType.unionId, locOf(prop));
-                            if (!retag) {
-                                lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' cannot re-tag into '${lowerer.fmt(targetType)}' behind the present-test`));
-                                throw new PoisonError();
-                            }
-                            thenVal = {
-                                kind: "call",
-                                callee: retag,
-                                args: [fRead()],
-                                type: targetType,
-                                loc: locOf(prop),
-                            };
+                        });
+                        const canBeAbsent = f.type.kind === "union" && lowerer.armTag(f.type.unionId, UNDEFINED_T) >= 0;
+                        if (typeEquals(f.type, targetType)) {
+                            thenVal = fRead();
+                            if (canBeAbsent)
+                                cond = fieldPresent();
                         }
-                        else if (ftDef &&
-                            ftDef.arms.length === 2 &&
-                            lowerer.armTag(f.type.unionId, targetType) >= 0) {
-                            thenVal = {
-                                kind: "unionNarrow",
-                                unionId: f.type.unionId,
-                                tag: lowerer.armTag(f.type.unionId, targetType),
-                                value: fRead(),
-                                type: targetType,
+                        else if (f.type.kind === "union" &&
+                            lowerer.armTag(f.type.unionId, UNDEFINED_T) >= 0 &&
+                            typeEquals(lowerer.stripUndefinedArm(f.type), targetType)) {
+                            // Optional source field into a required target slot: present
+                            // means the source holds the record AND the field its value
+                            // arm — the spread-override completion, union-source form.
+                            const ftUndef = lowerer.armTag(f.type.unionId, UNDEFINED_T);
+                            cond = {
+                                kind: "logical",
+                                op: "&&",
+                                left: cond,
+                                right: {
+                                    kind: "unionIsTag",
+                                    unionId: f.type.unionId,
+                                    tag: ftUndef,
+                                    negated: true,
+                                    value: fRead(),
+                                    type: BOOL,
+                                    loc: locOf(prop),
+                                },
+                                type: BOOL,
                                 loc: locOf(prop),
                             };
+                            const ftDef = lowerer.unions.get(f.type.unionId);
+                            if (targetType.kind === "union") {
+                                const retag = lowerer.unionRetagHelper(f.type.unionId, targetType.unionId, locOf(prop));
+                                if (!retag) {
+                                    lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' cannot re-tag into '${lowerer.fmt(targetType)}' behind the present-test`));
+                                    throw new PoisonError();
+                                }
+                                thenVal = {
+                                    kind: "call",
+                                    callee: retag,
+                                    args: [fRead()],
+                                    type: targetType,
+                                    loc: locOf(prop),
+                                };
+                            }
+                            else if (ftDef &&
+                                ftDef.arms.length === 2 &&
+                                lowerer.armTag(f.type.unionId, targetType) >= 0) {
+                                thenVal = {
+                                    kind: "unionNarrow",
+                                    unionId: f.type.unionId,
+                                    tag: lowerer.armTag(f.type.unionId, targetType),
+                                    value: fRead(),
+                                    type: targetType,
+                                    loc: locOf(prop),
+                                };
+                            }
+                            else {
+                                lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' cannot narrow into '${lowerer.fmt(targetType)}' behind the present-test`));
+                                throw new PoisonError();
+                            }
                         }
                         else {
-                            lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' cannot narrow into '${lowerer.fmt(targetType)}' behind the present-test`));
-                            throw new PoisonError();
-                        }
-                    }
-                    else {
-                        // The width-lift fallback (arm wrap, re-tag, nested
-                        // reshape) — the same per-field rule the slot coercion
-                        // applies. Runs AFTER the optional-completion branch: a
-                        // present-test has its own semantics a re-tag's stranded
-                        // undefined trap must not shadow.
-                        const lift = lowerer.widthLiftPlan(f.type, targetType);
-                        if (!lift) {
-                            lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' does not lift into '${lowerer.fmt(targetType)}'`));
-                            throw new PoisonError();
-                        }
-                        thenVal = lowerer.applyWidthLift(lift, fRead(), targetType, locOf(prop));
-                        if (canBeAbsent)
-                            cond = fieldPresent();
-                    }
-                    const at = fields.findIndex((x) => x.name === f.name);
-                    const elseVal = at >= 0 ? fields[at].value : lowerer.absentFieldValue(targetType, locOf(prop));
-                    if (!elseVal) {
-                        if (canBeAbsent) {
-                            // The FIELD itself can be missing from a present source:
-                            // no extraction makes it exist.
-                            lowerer.unsupported("SC1090", prop, `object spread of '${lowerer.fmt(srcType)}' sources where '${f.name}' has no earlier contributor (the absent arm leaves the required field unset — spread defaults first: { ...defaults, ...overrides })`);
-                        }
-                        // No earlier contributor and the target slot cannot be absent:
-                        // the source must be here. Copy through the checked extraction
-                        // (the absent unit arm throws) — the same read the width lift
-                        // below wraps, so a lift still applies.
-                        let strict = fRead(true);
-                        if (!typeEquals(f.type, targetType)) {
+                            // The width-lift fallback (arm wrap, re-tag, nested
+                            // reshape) — the same per-field rule the slot coercion
+                            // applies. Runs AFTER the optional-completion branch: a
+                            // present-test has its own semantics a re-tag's stranded
+                            // undefined trap must not shadow.
                             const lift = lowerer.widthLiftPlan(f.type, targetType);
                             if (!lift) {
                                 lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' does not lift into '${lowerer.fmt(targetType)}'`));
                                 throw new PoisonError();
                             }
-                            strict = lowerer.applyWidthLift(lift, strict, targetType, locOf(prop));
+                            thenVal = lowerer.applyWidthLift(lift, fRead(), targetType, locOf(prop));
+                            if (canBeAbsent)
+                                cond = fieldPresent();
                         }
-                        fields.push({ name: f.name, value: strict });
-                        continue;
+                        const at = fields.findIndex((x) => x.name === f.name);
+                        const elseVal = at >= 0 ? fields[at].value : lowerer.absentFieldValue(targetType, locOf(prop));
+                        if (!elseVal) {
+                            if (canBeAbsent) {
+                                // The FIELD itself can be missing from a present source:
+                                // no extraction makes it exist.
+                                lowerer.unsupported("SC1090", prop, `object spread of '${lowerer.fmt(srcType)}' sources where '${f.name}' has no earlier contributor (the absent arm leaves the required field unset — spread defaults first: { ...defaults, ...overrides })`);
+                            }
+                            // No earlier contributor and the target slot cannot be absent:
+                            // the source must be here. Copy through the checked extraction
+                            // (the absent unit arm throws) — the same read the width lift
+                            // below wraps, so a lift still applies.
+                            let strict = fRead(true);
+                            if (!typeEquals(f.type, targetType)) {
+                                const lift = lowerer.widthLiftPlan(f.type, targetType);
+                                if (!lift) {
+                                    lowerer.pushDiag(recordShapeMismatchDiag(lowerer.fmt(type), lowerer.fmt(recArm), locOf(prop), `spread field '${f.name}': '${lowerer.fmt(f.type)}' does not lift into '${lowerer.fmt(targetType)}'`));
+                                    throw new PoisonError();
+                                }
+                                strict = lowerer.applyWidthLift(lift, strict, targetType, locOf(prop));
+                            }
+                            fields.push({ name: f.name, value: strict });
+                            continue;
+                        }
+                        const merged = {
+                            kind: "ternary",
+                            cond,
+                            then: thenVal,
+                            else_: elseVal,
+                            type: targetType,
+                            loc: locOf(prop),
+                        };
+                        if (at >= 0)
+                            fields[at] = { name: f.name, value: merged };
+                        else
+                            fields.push({ name: f.name, value: merged });
                     }
-                    const merged = {
-                        kind: "ternary",
-                        cond,
-                        then: thenVal,
-                        else_: elseVal,
-                        type: targetType,
-                        loc: locOf(prop),
-                    };
-                    if (at >= 0)
-                        fields[at] = { name: f.name, value: merged };
-                    else
-                        fields.push({ name: f.name, value: merged });
                 }
                 continue;
             }
@@ -2006,13 +2119,15 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
                 if (laterNames.has(f.name))
                     continue;
                 let targetType = fieldTypes.get(f.name);
-                // A source field with NO slot on the target shape: the copy
-                // DROPS it — a spread of a wider record into a narrower literal
-                // is width subtyping in spread clothing, divergence 36's stance
-                // (Node's object would keep the key); the read is pure, so
-                // skipping evaluates nothing.
-                if (!targetType)
+                // A source field with NO slot on the target shape: the static
+                // copy skips it (the read is pure, so skipping evaluates nothing),
+                // and the literal keeps it through a kept source view when the
+                // program can observe the target (keepWidthSpreads).
+                if (!targetType) {
+                    if (srcLowered.type.kind !== "dyn")
+                        widthDrops = true;
                     continue;
+                }
                 // A runtime-optional source field (an unchecked indexed read the
                 // checker calls present) keeps its undefined arm in the copy, as a
                 // property initialized from that read would.
@@ -2251,7 +2366,8 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
                 lowerer.diags.slice(propDiagsBefore).some((d) => d.code === "SC9001")) {
                 throw err;
             }
-            lowerer.runtimeFences.push(...lowerer.diags.splice(propDiagsBefore));
+            for (const d of lowerer.diags.splice(propDiagsBefore))
+                lowerer.runtimeFences.push(d);
             droppedNames.add(name);
             continue;
         }
@@ -2297,6 +2413,7 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
             fields.splice(at, 1);
         fields.push({ name, value });
         orderSegments.push({ kind: "key", name, definite: true });
+        widthSegments.push({ kind: "key", name });
     }
     // Optional fields may be omitted: the field holds its absent state.
     // tsc rejects omission of required fields before lowering.
@@ -2323,10 +2440,46 @@ export function lowerObjectLiteral(lowerer, expr, expected) {
         }
     }
     const result = lowerer.keyOrder.literal({ kind: "recordLit", fields, type, loc }, orderSegments);
+    if (!widthBlocked &&
+        spreadStmts.length > 0 &&
+        type.kind === "record" &&
+        recordMayKeepSource(lowerer, type))
+        lowerer.keyOrder.width(result, widthSegments, widthDrops || widthDynSource);
     return spreadStmts.length === 0
         ? result
         : { kind: "seqExpr", stmts: spreadStmts, result, type, loc };
 }
+/** A spread source whose stored union holds several record arms while the
+ * checker narrowed this site to fewer (`if (b?.type === "tool") ({ ...b })`
+ * on an element read, or a type predicate's arm): extract the narrowed
+ * value through the CHECKED narrowing, so every arm the checker excludes,
+ * including a hidden absence arm, throws the catchable TypeError instead of
+ * being copied. Null when the stored union has at most one record arm (the
+ * present-test desugar owns that case), when the site type is not a
+ * narrowing of the stored union, or in JavaScript files. */
+function checkedSpreadSource(lowerer, node, stored) {
+    if (stored.type.kind !== "union")
+        return null;
+    if (isJsSourceFile(ts.getSourceFileOfNode(node)))
+        return null;
+    const def = lowerer.unions.get(stored.type.unionId);
+    if (!def || def.arms.filter((arm) => arm.kind === "record").length < 2)
+        return null;
+    const site = lowerer.mapTypeOf(lowerer.typeOf(node));
+    if (!site || typeEquals(site, stored.type))
+        return null;
+    const loc = stored.loc;
+    if (site.kind === "record") {
+        if (lowerer.armTag(stored.type.unionId, site) < 0)
+            return null;
+        const helper = lowerer.narrowedArmHelper(stored.type.unionId, site, loc);
+        return helper ? lowerer.checkedNarrowCall(helper, stored, site, loc) : null;
+    }
+    if (site.kind !== "union")
+        return null;
+    const helper = lowerer.narrowedRetagHelper(node, stored.type.unionId, site.unionId, loc);
+    return helper ? { kind: "call", callee: helper, args: [stored], type: site, loc } : null;
+}
 /** The field type is an array, or a union with exactly one array arm. */
 function singleArrayArm(lowerer, type) {
     if (type.kind === "array")
@@ -2342,6 +2495,269 @@ function isEmptyArrayLiteral(node) {
         inner = inner.expression;
     return ts.isArrayLiteralExpression(inner) && inner.elements.nodes.length === 0;
 }
+/** `{ ...u, k: v }` where the spread source `u` is a union of records (and
+ * unit arms): TypeScript types the literal as the union of one spread per
+ * source arm, so it is built that way. The source evaluates once into a
+ * hidden local; a tag dispatch builds the running arm's literal with that
+ * arm as the source, at the destination arm chosen for it:
+ *   1. the arms the discriminant's last writer selects (an explicit
+ *      property, or the source arm when it carries the field);
+ *   2. among those, the source arm itself (`{ ...command, id }`);
+ *   3. else the one arm whose keys are exactly the keys the literal writes.
+ * Every key a contributor may write must be a field of the destination:
+ * the record path's width copy would drop the others, and Node keeps them.
+ * So a genuine merge (`{ ...http, ...patch }` where `patch` may carry a
+ * stdio-only key) stays refused. A stored source the checker narrowed
+ * converts through the checked re-tag first, so an excluded arm (a hidden
+ * absence arm included) throws the catchable TypeError. Null when the
+ * literal is not this shape, before anything is lowered except the
+ * source; the caller keeps its refusal. */
+function lowerDistributedUnionSpread(lowerer, expr, mapped) {
+    if (isJsSourceFile(ts.getSourceFileOfNode(expr)))
+        return null;
+    if (mapped?.kind !== "union")
+        return null;
+    const target = lowerer.unions.get(mapped.unionId);
+    if (!target)
+        return null;
+    const props = expr.properties.nodes;
+    // Exactly one distributed source: a plain spread whose checker type maps
+    // to a union of records and unit arms. Several would be a product.
+    let spreadIndex = -1;
+    let srcNode = null;
+    for (let i = 0; i < props.length; i++) {
+        const prop = props[i];
+        if (!ts.isSpreadAssignment(prop))
+            continue;
+        if (conditionalSpreadOf(prop.expression) !== null ||
+            andSpreadOf(lowerer, prop.expression) !== null ||
+            conditionalRecordSpreadOf(lowerer, prop.expression) !== null)
+            continue;
+        let node = prop.expression;
+        while (ts.isParenthesizedExpression(node))
+            node = node.expression;
+        if (lowerer.mapTypeOf(lowerer.typeOf(node))?.kind !== "union")
+            continue;
+        if (srcNode !== null)
+            return null;
+        spreadIndex = i;
+        srcNode = node;
+    }
+    if (srcNode === null)
+        return null;
+    const site = srcNode;
+    // The source evaluates before the dispatch, so everything written before
+    // it must be free of effects. When the source itself may have effects, an
+    // earlier property may also not read a value they could change: those
+    // properties must be constants.
+    const sourcePure = pureKeyExpr(lowerer, site);
+    for (const prop of props.slice(0, spreadIndex)) {
+        if (sourcePure && ts.isShorthandPropertyAssignment(prop))
+            continue;
+        if (ts.isPropertyAssignment(prop) &&
+            (sourcePure
+                ? pureKeyExpr(lowerer, prop.initializer)
+                : constantInitializer(lowerer, prop.initializer)))
+            continue;
+        return null;
+    }
+    const siteType = lowerer.mapTypeOf(lowerer.typeOf(site));
+    if (siteType?.kind !== "union")
+        return null;
+    const siteDef = lowerer.unions.get(siteType.unionId);
+    if (!siteDef || !siteDef.arms.every((arm) => arm.kind === "record" || isUnitType(arm)))
+        return null;
+    const discField = target.discriminant?.field;
+    // The discriminant values the literal's LAST writer of that field gives
+    // this source arm; null when unknown.
+    const discriminantOf = (tag, arm) => {
+        if (discField === undefined)
+            return null;
+        for (let i = props.length - 1; i >= 0; i--) {
+            const prop = props[i];
+            if (i === spreadIndex) {
+                if (arm.kind !== "record")
+                    continue;
+                if (!lowerer.shapes.get(arm.shapeId)?.fields.some((f) => f.name === discField))
+                    continue;
+                const own = siteDef.discriminant;
+                return own?.field === discField
+                    ? (own.cases.find((c) => c.tag === tag)?.values ?? null)
+                    : null;
+            }
+            if (ts.isSpreadAssignment(prop))
+                return null;
+            if ((ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) &&
+                propNameText(lowerer, prop.name) === discField)
+                return ts.isPropertyAssignment(prop)
+                    ? literalValues(lowerer.typeOf(prop.initializer))
+                    : literalValues(lowerer.typeOf(prop.name));
+        }
+        return null;
+    };
+    // Every key some contributor may write for this source arm; null when a
+    // contributor has no fixed key set (an index signature, a non-record).
+    const writtenKeys = (arm) => {
+        const names = new Set();
+        for (let i = 0; i < props.length; i++) {
+            const prop = props[i];
+            if (ts.isSpreadAssignment(prop)) {
+                let node = prop.expression;
+                while (ts.isParenthesizedExpression(node))
+                    node = node.expression;
+                const t = i === spreadIndex ? arm : lowerer.mapTypeOf(lowerer.typeOf(node));
+                if (t !== null && isUnitType(t))
+                    continue;
+                if (t?.kind !== "record")
+                    return null;
+                const shape = lowerer.shapes.get(t.shapeId);
+                if (!shape || shape.indexValue || shape.tuple)
+                    return null;
+                for (const f of shape.fields)
+                    names.add(f.name);
+            }
+            else if (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) {
+                names.add(propNameText(lowerer, prop.name));
+            }
+            else {
+                return null;
+            }
+        }
+        return names;
+    };
+    const destinationOf = (tag, arm) => {
+        const keys = writtenKeys(arm);
+        if (keys === null)
+            return null;
+        let candidates = target.arms
+            .map((a, t) => ({ a, t }))
+            .filter((c) => c.a.kind === "record")
+            .filter((c) => {
+            const fields = lowerer.shapes.get(c.a.shapeId).fields;
+            return [...keys].every((k) => fields.some((f) => f.name === k));
+        });
+        const values = discriminantOf(tag, arm);
+        if (values && values.length > 0 && target.discriminant) {
+            const cases = target.discriminant.cases;
+            candidates = candidates.filter((c) => (cases.find((k) => k.tag === c.t)?.values ?? []).some((v) => values.includes(v)));
+        }
+        if (candidates.length === 1)
+            return candidates[0].a;
+        if (arm.kind === "record") {
+            const same = candidates.find((c) => c.a.shapeId === arm.shapeId);
+            if (same)
+                return same.a;
+        }
+        const exactKeys = candidates.filter((c) => lowerer.shapes.get(c.a.shapeId).fields.length === keys.size);
+        return exactKeys.length === 1 ? exactKeys[0].a : null;
+    };
+    // Plan every arm before lowering anything.
+    const plan = [];
+    for (let tag = 0; tag < siteDef.arms.length; tag++) {
+        const arm = siteDef.arms[tag];
+        const destination = destinationOf(tag, arm);
+        if (destination === null)
+            return null;
+        plan.push({ tag, arm, destination });
+    }
+    const loc = locOf(expr);
+    let source = lowerer.lowerExpr(site);
+    if (source.type.kind === "union" && !typeEquals(source.type, siteType)) {
+        const helper = lowerer.narrowedRetagHelper(site, source.type.unionId, siteType.unionId, source.loc);
+        if (helper)
+            source = { kind: "call", callee: helper, args: [source], type: siteType, loc: source.loc };
+    }
+    if (!typeEquals(source.type, siteType))
+        return null;
+    const saved = lowerer.declareHiddenLocal("%spreadArms", siteType);
+    const ref = varRef(saved.id, siteType, loc);
+    let result = null;
+    for (let i = plan.length - 1; i >= 0; i--) {
+        const { tag, arm, destination } = plan[i];
+        const armValue = arm.kind === "record"
+            ? { kind: "unionNarrow", value: ref, unionId: siteType.unionId, tag, type: arm, loc }
+            : {
+                kind: "recordLit",
+                fields: [],
+                type: { kind: "record", shapeId: lowerer.shapes.intern([]) },
+                loc,
+            };
+        lowerer.spreadArmOverrides.set(site, armValue);
+        let built;
+        try {
+            built = lowerObjectLiteral(lowerer, expr, destination, true);
+        }
+        finally {
+            lowerer.spreadArmOverrides.delete(site);
+        }
+        const wrapped = lowerer.coerceToExpected(built, mapped);
+        if (!typeEquals(wrapped.type, mapped))
+            return null;
+        result =
+            result === null
+                ? wrapped
+                : {
+                    kind: "ternary",
+                    cond: {
+                        kind: "unionIsTag",
+                        value: ref,
+                        unionId: siteType.unionId,
+                        tag,
+                        negated: false,
+                        type: BOOL,
+                        loc,
+                    },
+                    then: wrapped,
+                    else_: result,
+                    type: mapped,
+                    loc,
+                };
+    }
+    if (result === null)
+        return null;
+    return {
+        kind: "seqExpr",
+        stmts: [{ kind: "varDecl", localId: saved.id, init: source, loc }],
+        result,
+        type: mapped,
+        loc,
+    };
+}
+/** `{ ...a, ...b }` over union-typed sources that lowerDistributedUnionSpread
+ * declined: no single destination arm holds every key the contributors may
+ * write (`provider-composer`'s two all-optional compat unions, an aggregate
+ * config merged from a http|stdio union plus a patch naming both). Node
+ * builds ONE plain object: each source's own enumerable keys copy in source
+ * order (later writers win), then the explicit fields write in their own
+ * positions. Build exactly that object — the checked-dynamic literal — and
+ * validate it into the declared union at the slot. The value keeps its
+ * runtime keys (reflection, JSON, and inspection see what Node sees); a
+ * value the union cannot hold throws the catchable TypeError at the
+ * conversion instead of being reinterpreted as one arm.
+ *
+ * Null when the shape is not the SC2003 one (no union-typed spread source),
+ * when the build must not demote (inside a capture buffer, or under
+ * `--tier=static-only`, which keeps today's refusal), or when the union has
+ * no checked extraction. The caller then keeps its refusal. */
+function lowerUnionSpreadMergeDyn(lowerer, expr, target) {
+    if (isJsSourceFile(ts.getSourceFileOfNode(expr)))
+        return null;
+    const spreadsUnion = expr.properties.nodes.some((prop) => {
+        if (!ts.isSpreadAssignment(prop))
+            return false;
+        let node = prop.expression;
+        while (ts.isParenthesizedExpression(node))
+            node = node.expression;
+        return lowerer.mapTypeOf(lowerer.typeOf(node))?.kind === "union";
+    });
+    if (!spreadsUnion)
+        return null;
+    if (lowerer.tierMode !== "auto" || lowerer.diagSink !== null)
+        return null;
+    if (!canDynCheckTo(target, (id) => lowerer.shapes.get(id), (id) => lowerer.unions.get(id)))
+        return null;
+    return lowerer.coerceToExpected(lowerDynObjectLiteral(lowerer, expr), target);
+}
 /** A union of plain records can preserve its existing variant while
  * replacing shared fields. Dispatch before constructing the copy: only
  * the selected arm evaluates overrides, and recordClone snapshots fields
@@ -2446,6 +2862,15 @@ function lowerUnionRecordClone(lowerer, expr) {
                 };
         }
     }
+    // Any other source (a capture, a runtime-optional binding, a member
+    // read) converts through the same checked re-tag: the arms the site's
+    // checker type excludes, a hidden absence arm included, throw the
+    // catchable TypeError instead of being cloned.
+    if (!typeEquals(source.type, sourceType) && source.type.kind === "union") {
+        const helper = lowerer.narrowedRetagHelper(spread.expression, source.type.unionId, sourceType.unionId, source.loc);
+        if (helper)
+            source = { kind: "call", callee: helper, args: [source], type: sourceType, loc: source.loc };
+    }
     if (!typeEquals(source.type, sourceType)) {
         lowerer.unsupported("SC1090", spread, "a union record clone whose stored source still includes absence");
     }
@@ -2632,15 +3057,50 @@ function lowerConditionalRecordSpread(lowerer, spread, loc) {
         loc,
     };
 }
+/** A spread's source expression with parentheses stripped, seeing through
+ * an empty-object default: `...(x ?? {})` and `...(x || {})` spread exactly
+ * what `...x` spreads (a nullish or other falsy value is a primitive with
+ * no own keys, and x evaluates once either way). Only where `x` is a plain
+ * record or a record-or-unit union, which the field copy and the
+ * optional-spread desugar handle; index-signature and other sources keep
+ * their paths. */
+function spreadSourceNode(lowerer, expr) {
+    let e = expr;
+    while (ts.isParenthesizedExpression(e))
+        e = e.expression;
+    if (!ts.isBinaryExpression(e) ||
+        (e.operatorToken.kind !== ts.SyntaxKind.QuestionQuestionToken &&
+            e.operatorToken.kind !== ts.SyntaxKind.BarBarToken))
+        return e;
+    let right = e.right;
+    while (ts.isParenthesizedExpression(right))
+        right = right.expression;
+    if (!ts.isObjectLiteralExpression(right) || right.properties.nodes.length !== 0)
+        return e;
+    let left = e.left;
+    while (ts.isParenthesizedExpression(left))
+        left = left.expression;
+    const plainRecord = (t) => t?.kind === "record" && lowerer.shapes.get(t.shapeId)?.indexValue === undefined;
+    const source = lowerer.mapTypeOf(lowerer.typeOf(left));
+    if (plainRecord(source ?? undefined))
+        return left;
+    if (source?.kind === "union") {
+        const arms = lowerer.unions.get(source.unionId)?.arms ?? [];
+        const records = arms.filter((arm) => arm.kind === "record");
+        if (records.length === 1 &&
+            plainRecord(records[0]) &&
+            arms.every((arm) => arm.kind === "record" || isUnitType(arm)))
+            return left;
+    }
+    return e;
+}
 /** A spread source the record desugar cannot enumerate: an untyped
  * (`unknown`) value, or one whose shape carries an index signature
  * (`Record<string, unknown>`, `{ [key: string]: T }`) so its keys are
  * runtime state. Node copies own enumerable keys in insertion order, which
  * the checked-dynamic object reproduces. */
 function dynSpreadSource(lowerer, node) {
-    let e = node;
-    while (ts.isParenthesizedExpression(e))
-        e = e.expression;
+    const e = spreadSourceNode(lowerer, node);
     if ((lowerer.typeOf(e).flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0)
         return true;
     const indexed = (t) => {
@@ -2770,6 +3230,28 @@ export function conditionalSpreadOf(expr) {
     }
     return { cond: e.condition, props, whenTrue: trueCarries };
 }
+/** The record arms of a union spread source of the declared-shape merge,
+ * or null unless every arm is a non-tuple record or the null/undefined
+ * unit and at least one arm is a record. Unit arms contribute nothing:
+ * CopyDataProperties skips nullish sources. */
+function declaredMergeUnionArms(lowerer, unionId) {
+    const def = lowerer.unions.get(unionId);
+    if (!def)
+        return null;
+    const arms = [];
+    for (let tag = 0; tag < def.arms.length; tag++) {
+        const arm = def.arms[tag];
+        if (arm.kind === "undefinedT" || arm.kind === "nullT")
+            continue;
+        if (arm.kind !== "record")
+            return null;
+        const armShape = lowerer.shapes.get(arm.shapeId);
+        if (!armShape || armShape.tuple)
+            return null;
+        arms.push({ tag, shapeId: arm.shapeId, shape: armShape });
+    }
+    return arms.length > 0 ? arms : null;
+}
 /** `{ ...idx, ...idx2 }` typed a DECLARED shape (no index signature) — the
  * defaults-merge idiom over runtime-keyed sources (`{ ...fromEntries(a),
  * ...fromEntries(b) }` typed AppConfig). Lowers to ONE interned helper
@@ -2785,7 +3267,12 @@ export function conditionalSpreadOf(expr) {
  * untyped copy would store the lie) — and a key naming NO declared field
  * is DROPPED (the shape cannot represent it; Node keeps it invisibly —
  * divergence 68). Later contributors overwrite earlier ones
- * (last-write-wins). Fixed, hybrid, and pure index records may contribute. */
+ * (last-write-wins). Fixed, hybrid, and pure index records may contribute,
+ * and so may a union of those records with the null/undefined unit: each
+ * record arm copies through its own shape's helper behind its tag test,
+ * a unit arm copies nothing (CopyDataProperties skips nullish sources),
+ * and the union is held in a hidden local, so it still evaluates once, in
+ * order. */
 function lowerDeclaredSpreadMerge(lowerer, expr, type, shape, loc) {
     const srcs = [];
     for (const prop of expr.properties.nodes) {
@@ -2795,6 +3282,15 @@ function lowerDeclaredSpreadMerge(lowerer, expr, type, shape, loc) {
             srcs.push({ value, shapeId: "dyn" });
             continue;
         }
+        if (value.type.kind === "union") {
+            const arms = declaredMergeUnionArms(lowerer, value.type.unionId);
+            if (arms) {
+                for (const arm of arms)
+                    fenceAccessorSpreadSource(lowerer, prop, arm.shape);
+                srcs.push({ value, shapeId: "union", arms });
+                continue;
+            }
+        }
         const srcShape = value.type.kind === "record" ? lowerer.shapes.get(value.type.shapeId) : undefined;
         if (value.type.kind !== "record" || !srcShape || srcShape.tuple) {
             lowerer.unsupported("SC1090", prop, `object spread of '${lowerer.fmt(value.type)}' into '${lowerer.fmt(type)}' (only records spread into a declared shape)`);
@@ -2932,12 +3428,11 @@ function lowerDeclaredSpreadMerge(lowerer, expr, type, shape, loc) {
             loc,
         },
     ];
-    for (const source of srcs) {
+    const mergeHelper = (source, sourceType) => {
         const key = `declmerge-source:${type.shapeId}:${source.shapeId}`;
         let helper = lowerer.valueHelpers.get(key);
         if (!helper) {
             helper = keyedHelperName(lowerer, "%rec.declmerge", key);
-            const sourceType = source.value.type;
             const destination = varRef("out.0", type, loc);
             const receiver = varRef("source.0", sourceType, loc);
             const locals = [
@@ -3112,6 +3607,59 @@ function lowerDeclaredSpreadMerge(lowerer, expr, type, shape, loc) {
             // leave an entry that a later literal could reuse without a body.
             lowerer.valueHelpers.set(key, helper);
         }
+        return helper;
+    };
+    for (const source of srcs) {
+        if (source.arms && source.value.type.kind === "union") {
+            // Evaluate the union once, then copy the running arm's own keys.
+            const unionType = source.value.type;
+            const held = lowerer.declareHiddenLocal("%declMergeSource", unionType);
+            const heldRef = varRef(held.id, unionType, loc);
+            stmts.push({ kind: "varDecl", localId: held.id, init: source.value, loc });
+            for (const arm of source.arms) {
+                const armType = { kind: "record", shapeId: arm.shapeId };
+                const helper = mergeHelper({ value: heldRef, shapeId: arm.shapeId, shape: arm.shape }, armType);
+                stmts.push({
+                    kind: "if",
+                    cond: {
+                        kind: "unionIsTag",
+                        unionId: unionType.unionId,
+                        tag: arm.tag,
+                        negated: false,
+                        value: heldRef,
+                        type: BOOL,
+                        loc,
+                    },
+                    then: [
+                        {
+                            kind: "exprStmt",
+                            expr: {
+                                kind: "call",
+                                callee: helper,
+                                args: [
+                                    outRef,
+                                    {
+                                        kind: "unionNarrow",
+                                        unionId: unionType.unionId,
+                                        tag: arm.tag,
+                                        value: heldRef,
+                                        type: armType,
+                                        loc,
+                                    },
+                                ],
+                                type,
+                                loc,
+                            },
+                            loc,
+                        },
+                    ],
+                    else_: null,
+                    loc,
+                });
+            }
+            continue;
+        }
+        const helper = mergeHelper(source, source.value.type);
         stmts.push({
             kind: "exprStmt",
             expr: { kind: "call", callee: helper, args: [outRef, source.value], type, loc },
@@ -3134,7 +3682,8 @@ function shorthandBuiltinValue(lowerer, prop) {
     const js = isJsSourceFile(ts.getSourceFileOfNode(prop));
     const name = ts.symbolName(symbol);
     return ((js ? builtinNamespaceValue(lowerer, name, locOf(prop.name)) : null) ??
-        builtinGlobalValue(name, locOf(prop.name), js));
+        builtinGlobalValue(name, locOf(prop.name), js) ??
+        tsUntypedGlobalValue(lowerer, prop.name, name, locOf(prop.name)));
 }
 export function lowerShorthandValue(lowerer, prop) {
     // 7 types the shorthand's name as PropertyName; it is always an