@scriptc/compiler 0.4.2 → 0.4.4

package/dist/frontend/lowering/key-order-witness.js

@@ -1,5 +1,35 @@
-import { shapeHasAccessorSlots, typeEquals, UNDEFINED_T } from "../../ir/ir.js";
-import { everyExprChild, everyStmtChild, everyTypeChild } from "../../ir/traverse.js";
+import { BOOL, F64, KEY_ORDER_FIELD, shapeHasAccessorSlots, typeEquals, UNDEFINED_T, VOID, } from "../../ir/ir.js";
+import { everyExprChild, everyStmtChild, everyTypeChild, transformStmtList, } from "../../ir/traverse.js";
+import * as ts from "../ts7/adapter.js";
+import { ALWAYS_THROW_LIB_FNS } from "../../ir/builtin-effects.js";
+import { recordMayKeepSource } from "./record-sources.js";
+/** The statements a key-order helper runs for record `ref`: `walks[0]`,
+ * its walk over the shape's table, or, for a shape with orderVariants, a
+ * branch per order (walks[i] for order i) on the value's KEY_ORDER_FIELD.
+ * `walks` follows shapeKeyOrders. */
+export function perKeyOrder(shape, ref, walks, loc) {
+    let tail = walks[0];
+    for (let i = walks.length - 1; i >= 1; i--) {
+        const index = {
+            kind: "recordGet",
+            obj: ref,
+            shapeId: shape.id,
+            field: KEY_ORDER_FIELD,
+            type: F64,
+            loc,
+        };
+        const cond = {
+            kind: "bin",
+            op: "===",
+            left: index,
+            right: { kind: "numLit", value: i, type: F64, loc },
+            type: BOOL,
+            loc,
+        };
+        tail = [{ kind: "if", cond, then: walks[i], else_: tail, loc }];
+    }
+    return tail;
+}
 /** Witness notes the lowering attaches to the IR nodes it builds. Keyed by
  * node identity, so nodes a speculative lowering discards are never walked.
  * Literals the IR rewriters rebuild (traverse.ts mapExprChildren) carry
@@ -8,6 +38,7 @@ import { everyExprChild, everyStmtChild, everyTypeChild } from "../../ir/travers
 export class KeyOrderNotes {
     literals = new Map();
     copies = new Map();
+    methodResults = new Map();
     /** Shapes a frontend order surface (keys, values/entries, inspect,
      * index-signature merges) walks. */
     observed = new Set();
@@ -21,8 +52,14 @@ export class KeyOrderNotes {
         this.copies.set(node, sourceShapeId);
         return node;
     }
+    /** The checked result of a typed call of method `name`, which the program
+     * may replace on its instance (class-callbacks.ts classCallbackCall). */
+    methodResult(node, name) {
+        this.methodResults.set(node, name);
+        return node;
+    }
     /** A pass rebuilt `from` as `to` (traverse.ts mapExprChildren): the
-     * rebuilt literal is the same construction, so it keeps the witness. */
+     * rebuilt node is the same construction, so it keeps the witness. */
     follow(from, to) {
         const segments = this.literals.get(from);
         if (segments !== undefined)
@@ -30,6 +67,9 @@ export class KeyOrderNotes {
         const source = this.copies.get(from);
         if (source !== undefined)
             this.copies.set(to, source);
+        const method = this.methodResults.get(from);
+        if (method !== undefined)
+            this.methodResults.set(to, method);
     }
     observe(type) {
         if (type.kind === "record")
@@ -41,6 +81,10 @@ export class KeyOrderNotes {
     copyOf(node) {
         return this.copies.get(node);
     }
+    /** The method whose checked result `node` is, if it is one. */
+    methodResultOf(node) {
+        return this.methodResults.get(node);
+    }
 }
 const isArrayIndex = (name) => {
     const n = Number(name);
@@ -55,6 +99,70 @@ function orderPreservingClone(node) {
     const source = value.args[0];
     return (source !== undefined && source.kind === "dynFrom" && typeEquals(source.value.type, node.type));
 }
+const PRIMITIVE_KINDS = new Set([
+    "f64",
+    "bigint",
+    "string",
+    "bool",
+    "undefinedT",
+    "nullT",
+    "symbol",
+]);
+/** A checked conversion of a boxed primitive (the `undefined` a dynamic
+ * construction passes for a missing argument) answers that primitive or
+ * throws: it builds no record. */
+function primitiveSource(node) {
+    return node.value.kind === "dynFrom" && PRIMITIVE_KINDS.has(node.value.value.type.kind);
+}
+/** Whether a census site for a method name can only read the method or
+ * install a replacement whose result holds no object: a read
+ * (`C.prototype.m`, `obj.m`) outside an assignment target, or an assignment
+ * of a function expression whose return type is primitive. Other sites (a
+ * computed write of another value, a reflection call, a property bag) may
+ * install a replacement that returns a record. */
+function replacesWithoutRecords(lowerer, site) {
+    const parent = site.parent;
+    if (ts.isPropertyAccessExpression(site) || ts.isElementAccessExpression(site))
+        return !(parent !== undefined &&
+            ts.isBinaryExpression(parent) &&
+            parent.left === site &&
+            parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment);
+    if (!ts.isBinaryExpression(site) || site.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+        return false;
+    let value = site.right;
+    while (ts.isParenthesizedExpression(value))
+        value = value.expression;
+    if (!ts.isArrowFunction(value) && !ts.isFunctionExpression(value))
+        return false;
+    const signatures = lowerer.checker.getCallSignatures(lowerer.typeOf(value));
+    return (signatures.length > 0 &&
+        signatures.every((signature) => primitiveOnly(lowerer.checker.getReturnTypeOfSignature(signature))));
+}
+/** A compiler helper that boxes a class's own state for JavaScript's reads:
+ * its prototype data and the property and method dispatch over boxed
+ * instances. */
+function boxesOwnState(fnName) {
+    return (fnName.startsWith("%prototype.data.") ||
+        fnName.startsWith("%dyn.class.") ||
+        fnName.startsWith("%class."));
+}
+/** A type whose values are primitives (or void): it holds no record. */
+function primitiveOnly(type) {
+    if (type.isUnionType())
+        return ts.constituentTypes(type).every(primitiveOnly);
+    return ((type.flags &
+        (ts.TypeFlags.StringLike |
+            ts.TypeFlags.NumberLike |
+            ts.TypeFlags.BooleanLike |
+            ts.TypeFlags.BigIntLike |
+            ts.TypeFlags.ESSymbolLike |
+            ts.TypeFlags.Null |
+            ts.TypeFlags.Undefined |
+            ts.TypeFlags.Void |
+            ts.TypeFlags.Never)) !==
+        0);
+}
 /** Chooses each in-scope record shape's enumeration table from its
  * witnesses. Runs once retained reachability has settled the historical
  * tables and derived metadata, before the order-snapshotting helper bodies
@@ -90,56 +198,110 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
     /** Every record shape a type can hold, through fields, arms, elements,
      * callables, promises and class fields. */
     /** Each walk shares one `seen` set per result set, so every type graph
-     * is walked once however many roots reach it. */
-    const shapesIn = (type, out, seen) => {
-        const visit = (t) => {
+     * is walked once however many roots reach it.
+     *
+     * `produced` walks only what a checked conversion into the type can
+     * build. It answers an existing native instance for a class type (a plain
+     * object cannot acquire a class brand; only %Error rebuilds), so the
+     * records the instance's fields hold come from the class's own writes and
+     * its checked field setters, each a witness of its own. A checked
+     * function's parameters receive native values: a record parameter is
+     * passed out, never built, though a callback among them receives values
+     * built from JavaScript again. `built` false starts the walk at a value
+     * passed out (a native value boxed for JavaScript); `writes` false leaves
+     * out what JavaScript could write into the containers passed out, so the
+     * walk counts only what the functions among them receive. */
+    const shapesIn = (type, out, seen, produced = false, built = true, writes = true) => {
+        const visit = (t, built) => {
+            const mark = built ? "" : "-";
+            // A container JavaScript builds converts into fresh native storage, so
+            // its children are built too. One passed out stays shared: JavaScript
+            // writes into it (built children) and reads native values out of it,
+            // such as callbacks whose parameters it then builds (children passed
+            // out). Those children count in both directions.
+            const child = (type) => {
+                if (built || writes)
+                    visit(type, true);
+                if (!built)
+                    visit(type, false);
+                return true;
+            };
             if (t.kind === "record") {
-                if (seen.has("r:" + t.shapeId))
+                if (seen.has(mark + "r:" + t.shapeId))
                     return true;
-                seen.add("r:" + t.shapeId);
-                out.add(t.shapeId);
+                seen.add(mark + "r:" + t.shapeId);
+                if (built)
+                    out.add(t.shapeId);
                 const shape = shapes.get(t.shapeId);
                 if (shape) {
                     for (const f of shape.fields)
-                        visit(f.type);
+                        child(f.type);
                     if (shape.indexValue)
-                        visit(shape.indexValue);
+                        child(shape.indexValue);
                 }
                 return true;
             }
             if (t.kind === "union") {
-                if (seen.has("u:" + t.unionId))
+                if (seen.has(mark + "u:" + t.unionId))
                     return true;
-                seen.add("u:" + t.unionId);
+                seen.add(mark + "u:" + t.unionId);
                 for (const arm of lowerer.unions.get(t.unionId)?.arms ?? [])
-                    visit(arm);
+                    visit(arm, built);
                 return true;
             }
             if (t.kind === "object") {
-                if (seen.has("c:" + t.className))
+                if (produced && t.className !== "%Error")
+                    return true;
+                if (seen.has(mark + "c:" + t.className))
                     return true;
-                seen.add("c:" + t.className);
+                seen.add(mark + "c:" + t.className);
                 for (const f of lowerer.classes.get(t.className)?.def.fields ?? [])
-                    visit(f.type);
+                    child(f.type);
                 return true;
             }
-            return everyTypeChild(t, visit);
+            if (produced && t.kind === "func") {
+                for (const param of t.params)
+                    visit(param, !built);
+                return visit(t.ret, built);
+            }
+            return everyTypeChild(t, child);
         };
-        visit(type);
+        visit(type, built);
     };
     const opaqueShapes = new Set();
     const opaqueSeen = new Set();
     const runtimeShapes = new Set();
     const runtimeSeen = new Set();
+    /** Shapes the declaration-typed boundary converts into (adopting casts):
+     * their values come from package code that builds them in the
+     * declaration's order, the order their table holds. */
+    const declaredShapes = new Set();
+    const declaredSeen = new Set();
+    const boxedSeen = new Set();
+    /** The checked result of a replaceable method call while every site that
+     * can replace the method installs functions that return no record. */
+    const unchangedMethodResult = (node) => {
+        const name = notes.methodResultOf(node);
+        if (name === undefined)
+            return false;
+        const sites = lowerer.methodAccessSites.get(name) ?? [];
+        return sites.every((site) => replacesWithoutRecords(lowerer, site));
+    };
     const producedBy = (type, opaque) => {
         if (opaque)
             shapesIn(type, opaqueShapes, opaqueSeen);
         else
-            shapesIn(type, runtimeShapes, runtimeSeen);
+            shapesIn(type, runtimeShapes, runtimeSeen, true);
     };
     // ── collection ──────────────────────────────────────────────────────
     let pos = 0;
     let fnName = "";
+    let currentFn = null;
+    /** Literals that start by spreading a binding, by their witness: where
+     * each one is built. A literal's notes are shared by its rebuilt copies,
+     * so `literalSites` counts every literal of each witness. */
+    const leadingSpreads = new Map();
+    const literalSites = new Map();
     const loops = [];
     let loopIds = 0;
     const loopKey = () => loops.join("/");
@@ -197,8 +359,10 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
                 }
                 const segments = notes.literalOf(e);
                 const copy = notes.copyOf(e);
-                if (segments !== undefined)
+                if (segments !== undefined) {
                     f.literals.push(segments);
+                    literalSites.set(segments, (literalSites.get(segments) ?? 0) + 1);
+                }
                 else if (copy !== undefined)
                     f.copies.push({ source: copy, keys: presentKeys });
                 else
@@ -217,9 +381,33 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
             case "assignExpr":
                 noteInit(e.localId, e.value);
                 return;
+            case "seqExpr": {
+                // A spread literal evaluates its sources into bindings first.
+                const literal = e.result;
+                if (literal.kind !== "recordLit" || currentFn === null)
+                    return;
+                const segments = notes.literalOf(literal);
+                const first = segments?.[0];
+                if (segments === undefined || first?.kind !== "spread" || first.value === undefined)
+                    return;
+                const list = leadingSpreads.get(segments) ?? [];
+                list.push({ wrapper: e, literal, fn: currentFn });
+                leadingSpreads.set(segments, list);
+                return;
+            }
             case "jsonStringify":
             case "dynFrom":
                 observedRoots.push(e.value.type);
+                // A native value the program hands to JavaScript: the callbacks it
+                // holds (itself, a field, an element) receive records JavaScript
+                // builds. The helpers that box the program's own state for
+                // JavaScript's reads (a class's prototype slots and property
+                // dispatch) hand out the class's methods, whose arguments the
+                // program's own calls pass as native values, as a replaceable
+                // method's result above. Writes through the boxed value are left
+                // out: reading a boxed value creates no record.
+                if (!boxesOwnState(fnName))
+                    shapesIn(e.value.type, runtimeShapes, boxedSeen, true, false, false);
                 return;
             case "recordKeyGet":
                 observedRoots.push(e.obj.type);
@@ -229,7 +417,12 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
                 // record may walk its keys; runtime builders make new records.
                 for (const arg of e.args)
                     observedRoots.push(arg.type);
-                producedBy(e.type, true);
+                // An always-throwing call stands in for a value (`error.nodeThrow`
+                // in a narrowing ternary) and never produces one. Other calls
+                // whose signature result is VOID are typed by their use site and
+                // build the record at run time (`server.address()`).
+                if (!ALWAYS_THROW_LIB_FNS.has(e.fn))
+                    producedBy(e.type, true);
                 return;
             case "intrinsic":
                 // Intrinsics hand back values built elsewhere, except allSettled's
@@ -242,10 +435,33 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
             case "strIntrinsic":
             case "regexIntrinsic":
             case "bytesIntrinsic":
+            // Promise.withResolvers records are built by the backend in a fixed
+            // layout.
+            case "promiseWithResolvers":
                 producedBy(e.type, true);
                 return;
+            case "genResume": {
+                // A resume builds at most its IteratorResult record ({ done, value }
+                // in a fixed layout; an async generator's settles a promise of it).
+                // The value it carries is the generator's own yielded or returned
+                // value, which the generator's body constructs. The record-free
+                // drives build nothing: `value` moves that value out, and step,
+                // close and a record-free delegate answer a boolean or nothing.
+                if (e.mode === "step" || e.mode === "value" || e.mode === "close")
+                    return;
+                const result = e.type.kind === "promise" ? e.type.inner : e.type;
+                if (result.kind === "record")
+                    opaqueShapes.add(result.shapeId);
+                return;
+            }
             case "dynCheck":
-                if (!orderPreservingClone(e))
+                if (e.adopt === true)
+                    shapesIn(e.type, declaredShapes, declaredSeen);
+                // Conversions that build no record: a boxed primitive, and a
+                // replaceable method's result while no replacement the program can
+                // install returns a record: then it is the method's own value,
+                // boxed and checked back unchanged.
+                else if (!orderPreservingClone(e) && !primitiveSource(e) && !unchangedMethodResult(e))
                     producedBy(e.type, false);
                 return;
             case "dynDestrCheck":
@@ -300,6 +516,7 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
     };
     for (const fn of fns) {
         fnName = fn.name;
+        currentFn = fn;
         for (const st of fn.body)
             stmt(st);
     }
@@ -310,6 +527,9 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
     }
     for (const id of runtimeShapes)
         factsOf(id).runtime = true;
+    for (const id of declaredShapes)
+        if (!runtimeShapes.has(id))
+            factsOf(id).pinned = true;
     // ── scope ───────────────────────────────────────────────────────────
     // Only plain declared-field shapes with a table take part.
     const inScope = (shape) => shape !== undefined &&
@@ -425,13 +645,63 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
         }
         return edges;
     };
+    // ── ordered spreads ─────────────────────────────────────────────────
+    // A value a checked conversion builds keeps its source's key order in
+    // its record source when that order is not the table's (record-
+    // sources.ts), so every value of a shape enumerates in the table's order
+    // or in the order its record source holds. A literal that starts with
+    // `...value` creates the value's keys first, in the value's order. When
+    // the value's shape is one checked conversions build, the literal
+    // carries that order over: after it builds the record it gives the
+    // record a source holding the value's order (record.sourceSpread), and
+    // the keys the value lacks follow in the table's order, which every
+    // literal sequence of the shape agrees with. Such a literal resolves as
+    // if its source were in the source's table order, and its own shape
+    // counts as built at run time too, since its values may now carry a
+    // source. It qualifies when every value of the source has all of the
+    // source's keys, both shapes can keep a source, and every later spread
+    // whose values may carry a source only overwrites the source's keys
+    // (its own order cannot move them).
+    const orderedSpreads = new Set();
+    const keepsSource = (shapeId) => recordMayKeepSource(lowerer, { kind: "record", shapeId });
+    const userKeys = (shapeId) => (shapes.get(shapeId)?.fields ?? []).map((x) => x.name).filter((k) => !k.startsWith("%"));
+    const ordersSpread = (segments, sites) => {
+        const first = segments[0];
+        if (first?.kind !== "spread" || first.maybeAbsent || first.value === undefined)
+            return false;
+        const sourceId = first.shapeId;
+        if (facts.get(sourceId)?.runtime !== true || sites.length !== literalSites.get(segments))
+            return false;
+        const target = sites[0].literal.type;
+        if (target.kind !== "record" || !keepsSource(sourceId) || !keepsSource(target.shapeId))
+            return false;
+        const localId = first.value.localId;
+        const bound = ({ wrapper, literal }) => typeEquals(literal.type, target) &&
+            wrapper.stmts.some((st) => st.kind === "varDecl" &&
+                st.localId === localId &&
+                st.init !== null &&
+                st.init.type.kind === "record" &&
+                st.init.type.shapeId === sourceId);
+        if (!sites.every(bound))
+            return false;
+        const sourceKeys = new Set(userKeys(sourceId));
+        if ([...sourceKeys].some((k) => maybeAbsent(sourceId, k)))
+            return false;
+        return segments
+            .slice(1)
+            .every((s) => s.kind === "key" ||
+            (s.kind === "spread" &&
+                (facts.get(s.shapeId)?.runtime !== true ||
+                    userKeys(s.shapeId).every((k) => sourceKeys.has(k)))));
+    };
     // ── witness sequences ───────────────────────────────────────────────
     /** The key sequences one literal can create, or null when a spread
      * source's order is unknown. A key sits at its first occurrence that
      * certainly defines it; each earlier occurrence that may define it is
      * another possible position. */
-    const literalSequences = (segments, keySet, resolved) => {
+    const literalSequences = (segments, keySet, resolved, raw) => {
         const occurrences = [];
+        const ordered = orderedSpreads.has(segments);
         for (const s of segments) {
             if (s.kind === "opaque")
                 return null;
@@ -440,7 +710,9 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
                     occurrences.push({ key: s.name, definite: s.definite });
                 continue;
             }
-            const source = resolved(s.shapeId);
+            // An ordered spread's values without a source enumerate in the
+            // source's table; the others carry their order over.
+            const source = ordered && s === segments[0] ? raw(s.shapeId) : resolved(s.shapeId);
             if (source === "unknown")
                 return null;
             for (const k of source.order) {
@@ -524,8 +796,24 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
             deps.add(c.source);
         return [...deps];
     };
+    /** `{ ...value, ...rest }` that starts with a spread of a value of the
+     * literal's own shape holding every key: it creates its keys in the
+     * value's order, and the later segments only overwrite them. With no
+     * checked conversion building the shape, every value enumerates in the
+     * one table this pass chooses, so the copy agrees with any choice and
+     * adds no edge. */
+    const copiesItself = (id, f, table, segments) => {
+        const first = segments[0];
+        return (first !== undefined &&
+            first.kind === "spread" &&
+            first.shapeId === id &&
+            !first.maybeAbsent &&
+            (!f.runtime || orderedSpreads.has(segments)) &&
+            segments.every((s) => s.kind !== "opaque") &&
+            table.every((k) => !maybeAbsent(id, k)));
+    };
     /** One shape's order given its sources' current orders. */
-    const resolveOne = (id, current) => {
+    const resolveOne = (id, current, raw) => {
         const shape = shapes.get(id);
         if (!inScope(shape))
             return "unknown";
@@ -544,7 +832,9 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
         if (f.pinned)
             chain(table, edges);
         for (const segments of f.literals) {
-            const sequences = literalSequences(segments, keySet, current);
+            if (copiesItself(id, f, table, segments))
+                continue;
+            const sequences = literalSequences(segments, keySet, current, raw);
             if (sequences === null)
                 return "unknown";
             for (const seq of sequences)
@@ -608,31 +898,59 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
         const known = result.get(id);
         return known === undefined ? "unknown" : asSource(id, known);
     };
-    for (const scc of sccs) {
-        const members = new Set(scc);
-        const guess = new Map();
-        for (const id of scc) {
-            const shape = shapes.get(id);
-            guess.set(id, inScope(shape) ? { order: tableOf(shape) } : "unknown");
-        }
-        const lookup = (id) => members.has(id) ? asSource(id, guess.get(id)) : external(id);
-        let stable = false;
-        for (let round = 0; round < scc.length + 3 && !stable; round++) {
-            stable = true;
+    const resolveAll = () => {
+        result.clear();
+        late.clear();
+        for (const scc of sccs) {
+            const members = new Set(scc);
+            const guess = new Map();
             for (const id of scc) {
-                const next = resolveOne(id, lookup);
-                const prev = guess.get(id);
-                const same = next === "unknown"
-                    ? prev === "unknown"
-                    : prev !== "unknown" && prev.order.join("\0") === next.order.join("\0");
-                if (!same) {
-                    stable = false;
-                    guess.set(id, next);
+                const shape = shapes.get(id);
+                guess.set(id, inScope(shape) ? { order: tableOf(shape) } : "unknown");
+            }
+            const lookup = (id) => members.has(id) ? asSource(id, guess.get(id)) : external(id);
+            const rawLookup = (id) => members.has(id) ? guess.get(id) : (result.get(id) ?? "unknown");
+            let stable = false;
+            for (let round = 0; round < scc.length + 3 && !stable; round++) {
+                stable = true;
+                for (const id of scc) {
+                    const next = resolveOne(id, lookup, rawLookup);
+                    const prev = guess.get(id);
+                    const same = next === "unknown"
+                        ? prev === "unknown"
+                        : prev !== "unknown" && prev.order.join("\0") === next.order.join("\0");
+                    if (!same) {
+                        stable = false;
+                        guess.set(id, next);
+                    }
                 }
             }
+            for (const id of scc)
+                result.set(id, stable ? guess.get(id) : "unknown");
+        }
+    };
+    // Ordered spreads join once their source resolves; each one can let its
+    // own shape resolve, which a later spread of it needs.
+    resolveAll();
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const [segments, sites] of leadingSpreads) {
+            const first = segments[0];
+            if (first?.kind !== "spread" || orderedSpreads.has(segments))
+                continue;
+            // A self copy resolves with its own shape.
+            const target = sites[0].literal.type;
+            const source = result.get(first.shapeId) ?? "unknown";
+            const self = target.kind === "record" && target.shapeId === first.shapeId;
+            if ((source === "unknown" && !self) || !ordersSpread(segments, sites))
+                continue;
+            orderedSpreads.add(segments);
+            if (target.kind === "record")
+                factsOf(target.shapeId).runtime = true;
+            grew = true;
         }
-        for (const id of scc)
-            result.set(id, stable ? guess.get(id) : "unknown");
+        if (grew)
+            resolveAll();
     }
     // ── observation ─────────────────────────────────────────────────────
     const observed = new Set();
@@ -641,6 +959,19 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
         shapesIn({ kind: "record", shapeId: id }, observed, observedSeen);
     for (const root of observedRoots)
         shapesIn(root, observed, observedSeen);
+    // An ordered spread's copies of values without a source take the source's
+    // order from its table, which must then hold the resolved order.
+    const orderedTarget = (sites) => {
+        const target = sites[0].literal.type;
+        return target.kind === "record" && (result.get(target.shapeId) ?? "unknown") !== "unknown"
+            ? target.shapeId
+            : null;
+    };
+    for (const [segments, sites] of leadingSpreads) {
+        const first = segments[0];
+        if (orderedSpreads.has(segments) && first?.kind === "spread" && orderedTarget(sites) !== null)
+            observed.add(first.shapeId);
+    }
     // ── apply ───────────────────────────────────────────────────────────
     for (const [id, resolved] of result) {
         if (resolved === "unknown" || !observed.has(id))
@@ -654,5 +985,600 @@ export function applyKeyOrderWitnesses(lowerer, fns) {
         shape.declaredOrder = [...shape.declaredOrder.filter(isArrayIndex), ...resolved.order];
         notes.changed.add(id);
     }
+    // Ordered spreads carry their source's order over (see above).
+    let orderedResults = 0;
+    const rewritten = new Set();
+    for (const [segments, sites] of leadingSpreads) {
+        const first = segments[0];
+        if (!orderedSpreads.has(segments) || first?.kind !== "spread" || first.value === undefined)
+            continue;
+        // A shape that did not resolve keeps today's table for every value.
+        if (orderedTarget(sites) === null)
+            continue;
+        for (const { wrapper, literal, fn } of sites) {
+            if (rewritten.has(wrapper))
+                continue;
+            rewritten.add(wrapper);
+            const loc = literal.loc;
+            const localId = `%orderedSpread.${orderedResults++}`;
+            fn.locals.push({ id: localId, name: "%orderedSpread", type: literal.type, mutable: false });
+            const built = { kind: "varRef", localId, type: literal.type, loc };
+            const source = {
+                kind: "varRef",
+                localId: first.value.localId,
+                type: { kind: "record", shapeId: first.shapeId },
+                loc,
+            };
+            wrapper.stmts.push({ kind: "varDecl", localId, init: literal, loc }, {
+                kind: "exprStmt",
+                expr: {
+                    kind: "libCall",
+                    fn: "record.sourceSpread",
+                    args: [built, source],
+                    type: VOID,
+                    loc,
+                },
+                loc,
+            });
+            wrapper.result = { kind: "varRef", localId, type: literal.type, loc };
+        }
+    }
+    // ── per-instance orders ─────────────────────────────────────────────
+    // A shape whose literals write its keys in more than one order has no
+    // one table. Each value then records which of the orders it was written
+    // in (KEY_ORDER_FIELD), when every construction's order is known
+    // statically or copied from a value that records its own:
+    //  - a literal of explicit keys writes its order;
+    //  - a copy from a shape with one resolved order writes that order;
+    //  - a copy from a value of a shape with orders writes the source's
+    //    order, filtered to the copy's keys (rest bindings, width copies);
+    //  - clones copy the field, and every other construction (synthesized
+    //    literals, checked conversions, runtime producers) leaves 0, today's
+    //    table, as before.
+    // A write of an optional key a value lacks moves the key to the end of
+    // the value's order, as in Node: the orders include every order such
+    // writes reach, and each write site updates the index after it evaluates
+    // the value and before it writes the key.
+    const MAX_ORDERS = 16;
+    const unresolved = (id) => result.get(id) === "unknown";
+    /** `order` over every key of `table`: keys the order lacks follow it. */
+    const complete = (order, table) => {
+        const keys = new Set(table);
+        const out = order.filter((k) => keys.has(k));
+        const seen = new Set(out);
+        return [...out, ...table.filter((k) => !seen.has(k))];
+    };
+    const literalOrder = (segments) => {
+        const out = [];
+        for (const segment of segments) {
+            if (segment.kind !== "key" || !segment.definite)
+                return null;
+            if (!isArrayIndex(segment.name))
+                out.push(segment.name);
+        }
+        return out;
+    };
+    /** `{ ...value }` of a value of the literal's own shape: a copy of the
+     * value's order. */
+    const selfSpread = (segments, id) => segments.length === 1 &&
+        segments[0].kind === "spread" &&
+        segments[0].shapeId === id &&
+        !segments[0].maybeAbsent;
+    const sameOrder = (a, b) => a.join("\0") === b.join("\0");
+    const indexOfOrder = (orders, order) => orders.findIndex((o) => sameOrder(o, order));
+    /** The keys writes can add to a value of the shape, or null when a
+     * clone override can (the clone's order is its source's). */
+    const movingKeys = (id, f, table) => {
+        const keys = new Set(table);
+        const moving = new Set();
+        for (const w of f.writes) {
+            if (w.kind === "delete" || !keys.has(w.field) || !maybeAbsent(id, w.field))
+                continue;
+            if (w.kind === "clone")
+                return null;
+            moving.add(w.field);
+        }
+        return [...moving];
+    };
+    /** `values[i]` for the order index `current` holds, as a chain of
+     * tests. */
+    const indexChain = (current, values, loc) => {
+        let out = { kind: "numLit", value: values[values.length - 1], type: F64, loc };
+        for (let i = values.length - 2; i >= 0; i--) {
+            if (out.kind === "numLit" && out.value === values[i])
+                continue;
+            out = {
+                kind: "ternary",
+                cond: {
+                    kind: "bin",
+                    op: "===",
+                    left: current,
+                    right: { kind: "numLit", value: i, type: F64, loc },
+                    type: BOOL,
+                    loc,
+                },
+                then: { kind: "numLit", value: values[i], type: F64, loc },
+                else_: out,
+                type: F64,
+                loc,
+            };
+        }
+        return out;
+    };
+    const moves = new Map();
+    /** Adds to `orders` every order writes of `moving` keys reach from them
+     * and records each key's transitions; false past MAX_ORDERS. */
+    const closeUnderMoves = (id, orders, moving) => {
+        const transitions = new Map(moving.map((k) => [k, []]));
+        for (let i = 0; i < orders.length; i++) {
+            for (const key of moving) {
+                const moved = [...orders[i].filter((k) => k !== key), key];
+                let index = indexOfOrder(orders, moved);
+                if (index < 0) {
+                    if (orders.length === MAX_ORDERS)
+                        return false;
+                    index = orders.push(moved) - 1;
+                }
+                transitions.get(key)[i] = index;
+            }
+        }
+        if (moving.length > 0)
+            moves.set(id, transitions);
+        return true;
+    };
+    // Observed shapes, and the shapes their values copy their orders from.
+    const wanted = new Set(observed);
+    const pending = [...observed];
+    while (pending.length > 0) {
+        const f = facts.get(pending.pop());
+        if (f === undefined)
+            continue;
+        const sources = [
+            ...f.copies.map((c) => c.source),
+            ...f.literals.flatMap((segments) => segments.flatMap((s) => (s.kind === "spread" ? [s.shapeId] : []))),
+        ];
+        for (const source of sources) {
+            if (wanted.has(source))
+                continue;
+            wanted.add(source);
+            pending.push(source);
+        }
+    }
+    const orderable = (id, f) => {
+        const shape = shapes.get(id);
+        if (!wanted.has(id) || !unresolved(id) || !inScope(shape))
+            return null;
+        const moving = movingKeys(id, f, tableOf(shape));
+        return moving === null ? null : { shape, moving };
+    };
+    const variants = new Map();
+    for (const [id, f] of facts) {
+        const candidate = orderable(id, f);
+        // A runtime producer builds the shape's values in its fixed layout,
+        // which has no KEY_ORDER_FIELD.
+        if (candidate === null || f.literals.length === 0 || f.opaque)
+            continue;
+        const table = tableOf(candidate.shape);
+        const orders = [table];
+        let ok = true;
+        const add = (order) => {
+            const full = complete(order, table);
+            if (indexOfOrder(orders, full) < 0)
+                orders.push(full);
+        };
+        for (const segments of f.literals) {
+            if (selfSpread(segments, id))
+                continue;
+            const order = literalOrder(segments);
+            if (order === null)
+                ok = false;
+            else
+                add(order);
+        }
+        for (const c of f.copies) {
+            if (c.source === id)
+                continue;
+            const source = result.get(c.source);
+            if (source === undefined || source === "unknown")
+                ok = false;
+            else
+                add(source.order.filter((k) => c.keys.has(k)));
+        }
+        if (!ok || orders.length > MAX_ORDERS || !closeUnderMoves(id, orders, candidate.moving))
+            continue;
+        if (orders.length > 1)
+            variants.set(id, orders);
+        else
+            moves.delete(id);
+    }
+    const templateOf = (segments, id) => {
+        const prefix = [];
+        const suffix = [];
+        let source = null;
+        for (const segment of segments) {
+            if (segment.kind === "opaque")
+                return null;
+            if (segment.kind === "spread") {
+                if (source !== null || segment.maybeAbsent || segment.shapeId === id)
+                    return null;
+                source = segment.shapeId;
+                continue;
+            }
+            if (!segment.definite)
+                return null;
+            (source === null ? prefix : suffix).push(segment.name);
+        }
+        return source === null ? null : { source, prefix, suffix };
+    };
+    const templateKey = (t) => JSON.stringify([t.source, t.prefix, t.suffix]);
+    const copyTemplate = (source) => ({ source, prefix: [], suffix: [] });
+    const mirrors = new Map();
+    for (const [id, f] of facts) {
+        if (variants.has(id) || f.pinned || f.runtime || f.opaque)
+            continue;
+        const candidate = orderable(id, f);
+        if (candidate === null || f.literals.length + f.copies.length === 0)
+            continue;
+        const templates = f.literals.map((segments) => templateOf(segments, id));
+        for (const c of f.copies)
+            templates.push(copyTemplate(c.source));
+        const first = templates[0];
+        if (first === null ||
+            first === undefined ||
+            templates.some((t) => t === null || templateKey(t) !== templateKey(first)))
+            continue;
+        const orders = variants.get(first.source);
+        if (orders === undefined || mirrors.has(first.source))
+            continue;
+        const table = tableOf(candidate.shape);
+        const tested = first.suffix.filter((k) => maybeAbsent(first.source, k));
+        if (tested.length > 4)
+            continue;
+        const mirrorOf = (o, lacks) => {
+            const order = [...first.prefix];
+            for (const k of o)
+                if (!lacks.has(k) && !order.includes(k))
+                    order.push(k);
+            for (const k of first.suffix)
+                if (!order.includes(k))
+                    order.push(k);
+            return complete(order, table);
+        };
+        let mirrored;
+        let template = first;
+        if (tested.length === 0)
+            mirrored = orders.map((o) => mirrorOf(o, new Set()));
+        else {
+            mirrored = [];
+            const index = [];
+            for (let present = 0; present < 1 << tested.length; present++) {
+                const lacks = new Set(tested.filter((_, j) => (present & (1 << j)) === 0));
+                const row = [];
+                for (const o of orders) {
+                    const order = mirrorOf(o, lacks);
+                    let i = indexOfOrder(mirrored, order);
+                    if (i < 0)
+                        i = mirrored.push(order) - 1;
+                    row.push(i);
+                }
+                index.push(row);
+            }
+            if (mirrored.length > MAX_ORDERS)
+                continue;
+            template = {
+                source: first.source,
+                prefix: first.prefix,
+                suffix: first.suffix,
+                select: { keys: tested, index },
+            };
+        }
+        if (!closeUnderMoves(id, mirrored, candidate.moving))
+            continue;
+        if (mirrored.every((o) => sameOrder(o, mirrored[0]))) {
+            // Every order of the source agrees over these keys: one table.
+            moves.delete(id);
+            const shape = candidate.shape;
+            const only = mirrored[0] ?? table;
+            if (!sameOrder(only, table))
+                shape.declaredOrder = [...shape.declaredOrder.filter(isArrayIndex), ...only];
+            continue;
+        }
+        variants.set(id, mirrored);
+        mirrors.set(id, template);
+    }
+    if (variants.size === 0)
+        return;
+    // Every construction of those shapes, to give each its order index. A
+    // copy reads its source's index, so its source must be a plain binding.
+    const sites = new Map();
+    /** The statements a spread literal's sequence evaluates first: the
+     * spread value's binding, then its fields. */
+    const prologues = new Map();
+    const siteOf = (e) => {
+        if (e.kind === "seqExpr" && e.result.kind === "recordLit")
+            prologues.set(e.result, e.stmts);
+        if (e.kind === "recordLit" && e.type.kind === "record" && variants.has(e.type.shapeId)) {
+            const list = sites.get(e.type.shapeId) ?? [];
+            list.push(e);
+            sites.set(e.type.shapeId, list);
+        }
+        return everyExprChild(e, siteOf, siteStmt);
+    };
+    const siteStmt = (st) => everyStmtChild(st, siteOf, siteStmt);
+    /** The function each literal with a prologue is built in. */
+    const owners = new Map();
+    for (const fn of fns) {
+        const before = new Set(prologues.keys());
+        for (const st of fn.body)
+            siteStmt(st);
+        for (const lit of prologues.keys())
+            if (!before.has(lit))
+                owners.set(lit, fn);
+    }
+    /** Where a literal evaluated its spread of `source`: the declaration the
+     * spread segment names, in the literal's own prologue. */
+    const spreadBinding = (lit, source) => {
+        const stmts = prologues.get(lit);
+        if (stmts === undefined)
+            return null;
+        for (const segment of notes.literalOf(lit) ?? []) {
+            if (segment.kind !== "spread" || segment.shapeId !== source || !segment.value)
+                continue;
+            const localId = segment.value.localId;
+            const at = stmts.findIndex((st) => st.kind === "varDecl" && st.localId === localId);
+            const decl = stmts[at];
+            if (decl?.kind !== "varDecl" || decl.init === null)
+                return null;
+            return { stmts, at, value: { kind: "varRef", localId, type: decl.init.type, loc: lit.loc } };
+        }
+        return null;
+    };
+    /** The binding a copy or spread reads its fields from. A literal's spread
+     * names it; every field of a copy reads it. */
+    const copySource = (lit, source) => {
+        if (notes.literalOf(lit) !== undefined)
+            return spreadBinding(lit, source)?.value ?? null;
+        for (const field of lit.fields) {
+            const value = field.value;
+            if (value.kind === "recordGet" && value.shapeId === source && value.obj.kind === "varRef")
+                return value.obj;
+        }
+        for (const st of prologues.get(lit) ?? []) {
+            if (st.kind !== "varDecl" || st.init === null)
+                continue;
+            const t = st.init.type;
+            if (t.kind === "record" && t.shapeId === source)
+                return { kind: "varRef", localId: st.localId, type: t, loc: lit.loc };
+        }
+        return null;
+    };
+    const orderIndex = (id, lit) => {
+        const orders = variants.get(id);
+        const segments = notes.literalOf(lit);
+        if (segments !== undefined && selfSpread(segments, id)) {
+            const obj = copySource(lit, id);
+            if (obj === null)
+                return null;
+            return {
+                kind: "recordGet",
+                obj,
+                shapeId: id,
+                field: KEY_ORDER_FIELD,
+                type: F64,
+                loc: lit.loc,
+            };
+        }
+        const mirror = mirrors.get(id);
+        if (segments !== undefined && mirror !== undefined) {
+            const obj = copySource(lit, mirror.source);
+            if (obj === null)
+                return null;
+            const sourceIndex = {
+                kind: "recordGet",
+                obj,
+                shapeId: mirror.source,
+                field: KEY_ORDER_FIELD,
+                type: F64,
+                loc: lit.loc,
+            };
+            const select = mirror.select;
+            if (select === undefined)
+                return sourceIndex;
+            // Tests the source for each key in turn, then picks by its index.
+            const pick = (j, present) => {
+                if (j === select.keys.length)
+                    return indexChain(sourceIndex, select.index[present], lit.loc);
+                return {
+                    kind: "ternary",
+                    cond: lowerer.recordFieldPresent(obj, mirror.source, select.keys[j], lit.loc),
+                    then: pick(j + 1, present | (1 << j)),
+                    else_: pick(j + 1, present),
+                    type: F64,
+                    loc: lit.loc,
+                };
+            };
+            return pick(0, 0);
+        }
+        if (segments !== undefined) {
+            const order = literalOrder(segments);
+            return order === null ? null : indexOfOrder(orders, complete(order, orders[0]));
+        }
+        const source = notes.copyOf(lit);
+        if (source === undefined)
+            return 0;
+        if (variants.has(source) && (source === id || mirrors.get(id)?.source === source)) {
+            const obj = copySource(lit, source);
+            if (obj === null)
+                return null;
+            return {
+                kind: "recordGet",
+                obj,
+                shapeId: source,
+                field: KEY_ORDER_FIELD,
+                type: F64,
+                loc: lit.loc,
+            };
+        }
+        const resolved = result.get(source);
+        if (resolved === undefined || resolved === "unknown")
+            return null;
+        const keys = new Set(lit.fields.filter((x) => x.value.kind !== "fieldAbsent").map((x) => x.name));
+        return indexOfOrder(orders, complete(resolved.order.filter((k) => keys.has(k)), orders[0]));
+    };
+    const plan = new Map();
+    const dropped = new Set();
+    for (const [id, list] of sites) {
+        for (const lit of list) {
+            const index = orderIndex(id, lit);
+            if (index === null || (typeof index === "number" && index < 0))
+                dropped.add(id);
+            else
+                plan.set(lit, index);
+        }
+    }
+    // Write sites of keys that move: each reads and updates the value's
+    // index before the write.
+    const writeSites = [];
+    let writeFn = null;
+    const writeExpr = (e) => everyExprChild(e, writeExpr, writeOf);
+    const writeOf = (st) => {
+        if (st.kind === "recordSet" &&
+            st.value.kind !== "fieldAbsent" &&
+            moves.get(st.shapeId)?.has(st.field))
+            writeSites.push({ st, fn: writeFn });
+        return everyStmtChild(st, writeExpr, writeOf);
+    };
+    for (const fn of fns) {
+        writeFn = fn;
+        for (const st of fn.body)
+            writeOf(st);
+    }
+    // A shape whose copies cannot read their source keeps today's table, and
+    // so do the shapes that mirror it.
+    for (const [id, mirror] of mirrors)
+        if (dropped.has(mirror.source))
+            dropped.add(id);
+    let temporaries = 0;
+    for (const [lit, index] of plan) {
+        const id = lit.type.shapeId;
+        if (dropped.has(id))
+            continue;
+        let value = typeof index === "number" ? { kind: "numLit", value: index, type: F64, loc: lit.loc } : index;
+        // A spread's order is the source's order at the spread: a later
+        // property may move the source's keys. Read it right after the literal
+        // evaluates the source.
+        const source = mirrors.get(id)?.source;
+        const binding = typeof index === "number" || !source ? null : spreadBinding(lit, source);
+        const fn = owners.get(lit);
+        if (binding && fn) {
+            const localId = `%keyOrderSource.${temporaries++}`;
+            fn.locals.push({ id: localId, name: "%keyOrderSource", type: F64, mutable: false });
+            binding.stmts.splice(binding.at + 1, 0, {
+                kind: "varDecl",
+                localId,
+                init: value,
+                loc: lit.loc,
+            });
+            value = { kind: "varRef", localId, type: F64, loc: lit.loc };
+        }
+        lit.fields.push({ name: KEY_ORDER_FIELD, value });
+    }
+    const replacements = new Map();
+    for (const { st, fn } of writeSites) {
+        if (dropped.has(st.shapeId))
+            continue;
+        const transitions = moves.get(st.shapeId).get(st.field);
+        const loc = st.loc;
+        // A receiver other than a binding evaluates once, into a local. So does
+        // a binding when the value evaluates first (below): the value may
+        // assign the binding, and the write still goes to the object the
+        // binding held before.
+        const pure = st.value.kind === "numLit" ||
+            st.value.kind === "strLit" ||
+            st.value.kind === "boolLit" ||
+            st.value.kind === "varRef";
+        let plain = st.obj;
+        while (plain.kind === "unionNarrow" || plain.kind === "downcast")
+            plain = plain.value;
+        const prologue = [];
+        let obj = st.obj;
+        if (plain.kind !== "varRef" || !pure) {
+            const localId = `%keyOrderReceiver.${temporaries++}`;
+            fn.locals.push({ id: localId, name: "%keyOrderReceiver", type: st.obj.type, mutable: false });
+            prologue.push({ kind: "varDecl", localId, init: st.obj, loc });
+            obj = { kind: "varRef", localId, type: st.obj.type, loc };
+        }
+        const current = {
+            kind: "recordGet",
+            obj,
+            shapeId: st.shapeId,
+            field: KEY_ORDER_FIELD,
+            type: F64,
+            loc,
+        };
+        const next = indexChain(current, transitions, loc);
+        // The value evaluates before the key is tested and moved: it may add
+        // other keys to the same value, which then come first.
+        let value = st.value;
+        if (!pure) {
+            const localId = `%keyOrderValue.${temporaries++}`;
+            fn.locals.push({ id: localId, name: "%keyOrderValue", type: value.type, mutable: false });
+            prologue.push({ kind: "varDecl", localId, init: value, loc });
+            value = { kind: "varRef", localId, type: value.type, loc };
+        }
+        const absent = {
+            kind: "unary",
+            op: "!",
+            operand: lowerer.recordFieldPresent(obj, st.shapeId, st.field, loc),
+            type: BOOL,
+            loc,
+        };
+        const update = {
+            kind: "recordSet",
+            obj,
+            shapeId: st.shapeId,
+            field: KEY_ORDER_FIELD,
+            value: next,
+            loc,
+        };
+        // The write becomes a block that moves the key first.
+        const write = {
+            kind: "recordSet",
+            obj,
+            shapeId: st.shapeId,
+            field: st.field,
+            value,
+            loc,
+        };
+        const guard = { kind: "if", cond: absent, then: [update], else_: null, loc };
+        const block = { kind: "block", body: [...prologue, guard, write], loc };
+        let replaced = replacements.get(fn);
+        if (replaced === undefined) {
+            replaced = new Map();
+            replacements.set(fn, replaced);
+        }
+        replaced.set(st, block);
+    }
+    for (const [fn, replaced] of replacements) {
+        fn.body = transformStmtList(fn.body, {
+            expr: (e) => e,
+            stmt: (st) => replaced.get(st) ?? st,
+        });
+    }
+    for (const [id, orders] of variants) {
+        if (dropped.has(id))
+            continue;
+        const shape = shapes.get(id);
+        const indexKeys = (shape.declaredOrder ?? []).filter(isArrayIndex);
+        shapes.addKeyOrderField(id);
+        const tables = [];
+        for (const order of orders) {
+            const table = [...indexKeys];
+            for (const key of order)
+                table.push(key);
+            tables.push(table);
+        }
+        shape.orderVariants = tables;
+    }
 }
 //# sourceMappingURL=key-order-witness.js.map