@velarscript/compiler 0.12.0 → 0.13.0

package/dist/emitter.js

@@ -3,8 +3,8 @@ import { VELAR_CLASS_FIELD_MODULE, VELAR_CLASS_FIELD_RUNTIME } from "./class-run
 import { VELAR_COLLECTION_HOST_EXPORTS, VELAR_COLLECTION_HOST_MODULE, VELAR_COLLECTION_IDENTITY_RUNTIME, VELAR_COLLECTION_LIST_RUNTIME, VELAR_COLLECTION_RECORD_RUNTIME, VELAR_COLLECTION_SET_MAP_RUNTIME, VELAR_COLLECTION_TYPE_RUNTIME } from "./collection-runtime.js";
 import { VELAR_COLLECTION_LOWERING_EXPORTS, VELAR_COLLECTION_LOWERING_MODULE, VELAR_COLLECTION_LOWERING_RUNTIME } from "./collection-lowering-runtime.js";
 import { describeType, formatTypeReference, formatTypeSyntax, mapNestedTypes, resolveTypeReference, semanticTypeIdentity, typeContainsParameter } from "./types.js";
-import { disposeMemberKey, iterateMemberKey } from "./analyzer.js";
-import { VELAR_ERROR_NORMALIZATION_MODULE, VELAR_ERROR_NORMALIZATION_RUNTIME, VELAR_HOST_ERROR_NAMES, VELAR_HOST_ERROR_RUNTIME } from "./error-runtime.js";
+import { disposeMemberKey, iterateAsyncMemberKey, iterateMemberKey } from "./analyzer.js";
+import { VELAR_ASSERTION_ERROR_RUNTIME, VELAR_ERROR_NORMALIZATION_MODULE, VELAR_ERROR_NORMALIZATION_RUNTIME, VELAR_HOST_ERROR_NAMES, VELAR_HOST_ERROR_RUNTIME } from "./error-runtime.js";
 import { embeddedJavaScriptSpecifier } from "./embedded-module.js";
 import { VELAR_NARROWING_MODULE, VELAR_NARROWING_RUNTIME } from "./narrowing-runtime.js";
 import { VELAR_NUMBER_METHOD_RUNTIME } from "./number-runtime.js";
@@ -16,11 +16,28 @@ import { VELAR_TEXT_METHOD_RUNTIME } from "./text-runtime.js";
 import { VELAR_TYPE_REGISTRY_RUNTIME } from "./type-registry-runtime.js";
 import { VELAR_RUNTIME_TYPE_COLLECTION_RUNTIME, VELAR_TYPE_VALIDATION_MODULE, VELAR_TYPE_VALIDATION_RUNTIME, VELAR_VALIDATION_ERROR_RUNTIME, } from "./type-validation-runtime.js";
 const javaScriptNodeMarker = /\u0000VELAR_MAP_(\d+)\u0000/gu;
+/**
+ * How deep a structural record's inline field proof nests before it degrades
+ * to the presence test. A generated validator recurses through a function
+ * call; an expression can only recurse by growing, so the depth is what keeps
+ * a deeply nested (or self-referential) structural type from expanding without
+ * bound.
+ */
+const maximumStructuralFieldDepth = 4;
+/**
+ * D90 rule R5: the placeholder a container's copy plan carries where its own
+ * identity goes, until interning has decided the name that identity is spelled
+ * with. A container's plan is both the callback it hands the runtime helper
+ * and the key that helper's memo files the copy under, so the body has to name
+ * itself before it has a name.
+ */
+const copyPlanSelfReference = "__velarCopyPlanSelf";
 // ENM-U4 + COL-U5: the compiler-raised error types are nameable in source;
 // their runtime classes carry compiler-owned names. The source names are
 // reserved Core bindings, so a bare reference is always the builtin.
 const builtinErrorRuntimeNames = new Map([
     ["ValidationError", "__VelarValidationError"],
+    ["AssertionError", "__VelarAssertionError"],
     ["NarrowingError", "__VelarNarrowingError"],
     ["IndexError", "__VelarIndexError"],
 ]);
@@ -39,6 +56,30 @@ export class JavaScriptEmitter {
     genericTypeParameters = null;
     /** Hoisted `function __velarTypeOf_N()` bodies for instantiations written outside a generic. */
     hoistedGenericInstances = new Map();
+    /**
+     * D90 rule R5: one hoisted `function __velarCopyPlanN` per distinct copy
+     * plan, found by the plan's own emitted text. The memo a copy keeps is keyed
+     * by source object *and* plan, so a plan needs an identity that is the same
+     * object at every visit; a module-level function declaration is that identity
+     * and the element callback in one, and it hoists past any temporal dead zone.
+     */
+    copyPlans = new Map();
+    copyPlanDeclarations = [];
+    /**
+     * The copy plans of the generic record currently being emitted. A plan that
+     * reads `__velarArguments` cannot hoist to module level and must not be
+     * shared between instantiations, so it is interned onto the instantiation's
+     * own arguments object instead — one array per instantiation, built once.
+     */
+    genericCopyPlans = null;
+    genericCopyPlanNames = null;
+    /**
+     * The plan array the generic record whose copy was emitted last needs on its
+     * arguments object, empty when every one of its plans hoisted to module level.
+     */
+    pendingGenericCopyPlans = [];
+    /** Whether a copy plan is being asked about rather than emitted, so nothing is interned. */
+    copyPlanProbe = false;
     externModuleExports = new Map();
     needsExternExportHelper = false;
     hints;
@@ -64,9 +105,11 @@ export class JavaScriptEmitter {
     needsIntegrityFailureHelper = false;
     needsRequiredValueHelper = false;
     needsNarrowingErrorClass = false;
-    suppressPromiseNormalization = 0;
+    needsAssertionErrorClass = false;
+    suppressedPromiseValues = new Set();
     nextJavaScriptNodeId = 0;
     javaScriptNodeSpans = new Map();
+    structuralFieldChecks = new Set();
     generatedMappings = [];
     generatedCode = "";
     sourcePath;
@@ -280,7 +323,10 @@ export class JavaScriptEmitter {
                 helpers.push(VELAR_PROMISE_NORMALIZATION_RUNTIME);
             }
         }
-        if (this.hints.asyncForStatements.size > 0) {
+        // D90 R18: the structural-pull helpers serve only the capability-handle
+        // shapes; an `async for` over a declared asynchronous `@iterate:` calls
+        // the emitted member directly and needs none of them.
+        if ([...this.hints.asyncForStatements].some((start) => !this.hints.asyncIterationStatements.has(start))) {
             helpers.push([
                 "const __velarAsyncPullGetOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;",
                 "const __velarAsyncPullGetPrototypeOf = Object.getPrototypeOf;",
@@ -316,6 +362,18 @@ export class JavaScriptEmitter {
         if (this.needsDisposalHelper) {
             helpers.push(...this.disposalHelpers());
         }
+        // D86 rule 212: `assert` and `value!` raise one compiler-owned class, so
+        // the class is emitted wherever either lowering is, independently of the
+        // error-normalization runtime a module may or may not also need.
+        if (this.needsAssertionErrorClass) {
+            if (this.sharedRuntimeModules) {
+                this.requireRuntimeModule(VELAR_ERROR_NORMALIZATION_MODULE);
+                helpers.push(`import { AssertionError as __VelarAssertionError } from ${JSON.stringify(VELAR_ERROR_NORMALIZATION_MODULE)};`);
+            }
+            else {
+                helpers.push(VELAR_ASSERTION_ERROR_RUNTIME);
+            }
+        }
         if (this.needsIntegrityFailureHelper) {
             helpers.push(...this.integrityFailureHelpers());
         }
@@ -537,6 +595,10 @@ export class JavaScriptEmitter {
         const chunks = [
             ...helpers.map((code) => ({ code, mappings: [] })),
             ...instances.map((code) => ({ code, mappings: [] })),
+            // D90 rule R5: the interned copy plans. They are `function` declarations
+            // for the same reason the instantiation accessors are — a plan names the
+            // Type objects declared below it and is only ever called after they exist.
+            ...this.copyPlanDeclarations.map((code) => ({ code, mappings: [] })),
             ...statements.map((node) => this.renderJavaScriptNode(node)),
         ];
         let output = "";
@@ -585,10 +647,14 @@ export class JavaScriptEmitter {
             const markerIndex = marker.index;
             code += node.code.slice(cursor, markerIndex);
             const sourceSpan = this.javaScriptNodeSpans.get(Number(marker[1]));
+            cursor = markerIndex + marker[0].length;
+            // A marker id this emit never issued cannot come from a marked node, so
+            // it is text that only looks like emitter metadata. Markers are
+            // invisible by construction: the render drops the sequence and keeps one
+            // mapping fewer rather than failing the whole compile with a host throw.
             if (!sourceSpan)
-                throw new Error("A generated JavaScript mapping marker has no source node");
+                continue;
             mappings.push({ offset: code.length, sourceSpan });
-            cursor = markerIndex + marker[0].length;
         }
         code += node.code.slice(cursor);
         return { code, mappings };
@@ -704,12 +770,25 @@ export class JavaScriptEmitter {
     integrityFailureHelpers() {
         return [[
                 "const __velarIntegrityDescriptor = Object.getOwnPropertyDescriptor;",
+                "const __velarIntegrityPrototypeOf = Object.getPrototypeOf;",
                 "function __velarIsIntegrityFailure(value) {",
                 "  if (value === null || (typeof value !== \"object\" && typeof value !== \"function\")) return false;",
                 "  const descriptor = __velarIntegrityDescriptor(value, \"name\");",
                 "  if (!descriptor || !(\"value\" in descriptor)) return false;",
                 "  const name = descriptor.value;",
-                "  return name === \"AssertionError\" || name === \"NarrowingError\" || name === \"IndexError\";",
+                "  if (name !== \"AssertionError\" && name !== \"NarrowingError\" && name !== \"IndexError\") return false;",
+                // D51 rule 107: the class a value was constructed from is what decides
+                // here, exactly as it decides `code`. A relabelled host error carries
+                // the name but no class declaring it, and must not pass through `try`
+                // as though the language had raised it. The comparison is on the
+                // declared name rather than on the class object because a module that
+                // inlines its runtime holds its own copy of each class, and a failure
+                // raised inside another module is still the same language failure.
+                "  const prototype = __velarIntegrityPrototypeOf(value);",
+                "  const constructor = prototype === null ? null : __velarIntegrityDescriptor(prototype, \"constructor\");",
+                "  if (!constructor || !(\"value\" in constructor) || typeof constructor.value !== \"function\") return false;",
+                "  const declared = __velarIntegrityDescriptor(constructor.value, \"name\");",
+                "  return !!declared && \"value\" in declared && declared.value === name;",
                 "}",
             ].join("\n")];
     }
@@ -722,9 +801,7 @@ export class JavaScriptEmitter {
         return [[
                 "function __velarRequired(value, description, offset) {",
                 "  if (value === null || value === undefined) {",
-                "    const __velarRequiredError = new Error(\"Required value \" + description + \" is absent at source offset \" + offset);",
-                "    __velarRequiredError.name = \"AssertionError\";",
-                "    throw __velarRequiredError;",
+                "    throw new __VelarAssertionError(\"Required value \" + description + \" is absent at source offset \" + offset);",
                 "  }",
                 "  return value;",
                 "}",
@@ -997,6 +1074,7 @@ export class JavaScriptEmitter {
     }
     markRuntimeType(type) {
         this.needsRuntimeTypeHelpers = true;
+        const structural = new Set();
         const visit = (value) => {
             // D55 rule 121: `Box<string>` needs `Box`'s factory emitted and every
             // argument's own runtime types marked; the application's display name is
@@ -1052,17 +1130,40 @@ export class JavaScriptEmitter {
             else if (value.kind === "union") {
                 value.members.forEach(visit);
             }
+            else if (value.kind === "object") {
+                // A structural field is proved inline, so whatever its own check needs
+                // — a collection's `TypeIs` helper, a declared record's validator — is
+                // this module's dependency exactly as a named field's would be.
+                if (structural.has(value))
+                    return;
+                structural.add(value);
+                value.fields.forEach(visit);
+                structural.delete(value);
+            }
         };
         visit(type);
     }
-    markRuntimeNarrowingType(type) {
+    markRuntimeNarrowingType(type, structural = new Set()) {
         if (type.kind === "optional") {
-            this.markRuntimeNarrowingType(type.inner);
+            this.markRuntimeNarrowingType(type.inner, structural);
             return;
         }
         if (type.kind === "union") {
             for (const member of type.members)
-                this.markRuntimeNarrowingType(member);
+                this.markRuntimeNarrowingType(member, structural);
+            return;
+        }
+        // A structural object's recheck spells its field table inline, so every
+        // field's own evidence is emitted into this module and its helpers must be
+        // required here. The expansion the emitter bounds is the *expression*; the
+        // dependency walk only has to terminate, so one visit per object suffices.
+        if (type.kind === "object") {
+            if (structural.has(type))
+                return;
+            structural.add(type);
+            for (const field of type.fields.values())
+                this.markRuntimeNarrowingType(field, structural);
+            structural.delete(type);
             return;
         }
         if (type.kind === "list" || type.kind === "set" || type.kind === "map" || type.kind === "record"
@@ -1186,12 +1287,11 @@ export class JavaScriptEmitter {
             case "ThrowStatement":
                 return `${indentation}throw ${this.emitMappedExpression(statement.value)};`;
             case "AssertStatement": {
+                this.needsAssertionErrorClass = true;
                 const message = statement.message ? this.emitMappedExpression(statement.message) : JSON.stringify("Assertion failed");
                 return [
                     `${indentation}if (!(${this.emitCondition(statement.condition)})) {`,
-                    `${indentation}  const __velarAssertionError = new Error(${message});`,
-                    `${indentation}  __velarAssertionError.name = "AssertionError";`,
-                    `${indentation}  throw __velarAssertionError;`,
+                    `${indentation}  throw new __VelarAssertionError(${message});`,
                     `${indentation}}`,
                 ].join("\n");
             }
@@ -1255,13 +1355,18 @@ export class JavaScriptEmitter {
                     const valueName = `__velarAsyncForValue${suffix}`;
                     const indexName = `__velarAsyncForIndex${suffix}`;
                     const bodyDepth = depth + 2;
+                    // D90 R18: a source whose class declares the asynchronous
+                    // `@iterate:` form is pulled through the declared member — no
+                    // structural `next` capture, because the contract is a declaration,
+                    // not a resemblance.
+                    const declared = this.hints.asyncIterationStatements.has(statement.span.start);
                     const lines = [
                         `${indentation}{`,
                         `${"  ".repeat(depth + 1)}const ${sourceName} = ${this.emitMappedExpression(statement.iterable)};`,
-                        `${"  ".repeat(depth + 1)}const ${nextName} = __velarAsyncPullNext(${sourceName});`,
+                        ...(declared ? [] : [`${"  ".repeat(depth + 1)}const ${nextName} = __velarAsyncPullNext(${sourceName});`]),
                         `${"  ".repeat(depth + 1)}let ${indexName} = 0;`,
                         `${"  ".repeat(depth + 1)}while (true) {`,
-                        `${"  ".repeat(bodyDepth)}const ${valueName} = await __velarNormalizePromiseValue(__velarAsyncPullCall(${sourceName}, ${nextName}));`,
+                        `${"  ".repeat(bodyDepth)}const ${valueName} = await __velarNormalizePromiseValue(${declared ? `${sourceName}[${JSON.stringify(iterateAsyncMemberKey)}]()` : `__velarAsyncPullCall(${sourceName}, ${nextName})`});`,
                         `${"  ".repeat(bodyDepth)}if (${valueName} === null) break;`,
                         ...this.emitBindingPatternStatements(statement.pattern, valueName, "const", false, bodyDepth, "Async for"),
                         ...(statement.secondPattern
@@ -1513,10 +1618,27 @@ export class JavaScriptEmitter {
         }
         if (checked.length > 0) {
             this.needsExternExportHelper = true;
+            // Charter section 12, line 2737: "an `export let` remains a live
+            // ES-module value: the exporting module can reassign it between reads".
+            // So the name binds through a real `import` and the presence probe runs
+            // beside it as its own statement. Reading the namespace *into* a `const`
+            // would have frozen the foreign binding at its initial value, which is
+            // neither what `import js * as`, nor `unsafe js`, nor JavaScript itself
+            // does with the same declaration.
+            //
+            // W-22's probe survives as the interop backstop rather than the primary
+            // check: a host that link-checks named imports refuses a missing export
+            // before any statement runs, and where the name links to `undefined`
+            // instead — bundled CommonJS interop — the probe beside it is what
+            // reports, in the velar voice.
+            const names = checked
+                .map((specifier) => specifier.imported === specifier.local ? specifier.imported : `${specifier.imported} as ${specifier.local}`)
+                .join(", ");
             const namespaceName = `__velarExternModule${statement.span.start}`;
+            lines.push(`${indentation}import { ${names} } from ${JSON.stringify(emittedSource)};`);
             lines.push(`${indentation}import * as ${namespaceName} from ${JSON.stringify(emittedSource)};`);
             for (const specifier of checked) {
-                lines.push(`${indentation}const ${specifier.local} = __velarExternExport(${namespaceName}, ${JSON.stringify(specifier.imported)}, ${JSON.stringify(source)});`);
+                lines.push(`${indentation}__velarExternExport(${namespaceName}, ${JSON.stringify(specifier.imported)}, ${JSON.stringify(source)});`);
             }
         }
         return lines.join("\n");
@@ -1529,11 +1651,15 @@ export class JavaScriptEmitter {
                 continue;
             const specifier = embeddedJavaScriptSpecifier(this.sourcePath, ordinal);
             const occupiedJavaScriptNames = new Set(statement.bindings.map((binding) => binding.name));
-            let factoryName = statement.contract ? `__velarEmbeddedFactory_${ordinal}` : null;
+            // A factory exists to hand the block its captures. With no captures
+            // there is nothing to hand over, so the block stays a real ES module and
+            // its exports stay live bindings — see `emitEmbeddedJavaScript`.
+            const needsFactory = statement.contract !== null && statement.captures.length > 0;
+            let factoryName = needsFactory ? `__velarEmbeddedFactory_${ordinal}` : null;
             while (factoryName && occupiedJavaScriptNames.has(factoryName))
                 factoryName += "_";
-            const localFactoryName = statement.contract ? `__velarEmbeddedFactoryBinding_${ordinal}` : null;
-            const generated = statement.contract
+            const localFactoryName = needsFactory ? `__velarEmbeddedFactoryBinding_${ordinal}` : null;
+            const generated = factoryName
                 ? emitCheckedEmbeddedJavaScript(statement, factoryName)
                 : mappedSource(statement.source, statement.sourceSpan.start);
             this.embeddedJavaScript.set(statement, {
@@ -1551,14 +1677,24 @@ export class JavaScriptEmitter {
         const prepared = this.embeddedJavaScript.get(statement);
         if (!prepared)
             throw new Error("An embedded JavaScript declaration has no prepared sibling module");
-        if (!statement.contract) {
+        if (!prepared.factoryName) {
+            // Charter section 12, line 2737: an `export let` the block reassigns is
+            // a live ES-module value. A block with no captures needs no factory to
+            // receive them, so its sibling module keeps its own `export`
+            // declarations and the names arrive here as real imported bindings —
+            // the same value `unsafe js` and `import js * as` observe. A contract changes what the
+            // compiler proves about a block, never what the program observes.
+            const declared = statement.contract ? contractExportNames(statement.contract) : null;
+            const exported = declared
+                ? statement.exports.filter((item) => declared.has(item.name))
+                : statement.exports;
             const imported = {
                 kind: "ImportDeclaration",
                 source: prepared.specifier,
                 sourceSpan: statement.sourceSpan,
                 javascript: true,
                 unsafe: true,
-                specifiers: statement.exports.map((item) => ({
+                specifiers: exported.map((item) => ({
                     imported: item.name,
                     local: item.name,
                     namespace: false,
@@ -1568,11 +1704,8 @@ export class JavaScriptEmitter {
             };
             return this.emitImport(imported, indentation);
         }
-        const names = [
-            ...statement.contract.functions.map((item) => item.name),
-            ...statement.contract.constants.map((item) => item.name),
-            ...statement.contract.classes.map((item) => item.name),
-        ];
+        // A factory only exists for a checked block, and only when it has captures.
+        const names = statement.contract ? [...contractExportNames(statement.contract)] : [];
         const captureValues = statement.captures.map((capture) => this.emitMappedExpression({
             kind: "IdentifierExpression",
             name: capture.name,
@@ -1614,6 +1747,13 @@ export class JavaScriptEmitter {
             type: this.resolveDeclarationType(field.type),
             syntax: field.type.syntax,
         }));
+        // D90 rule R5: the predicate stays the charter's "present own enumerable
+        // data properties" and deliberately does not demand `writable` and
+        // `configurable` the way `__velarRecordFields` does. Since parse now
+        // returns a copy whose every field is an ordinary mutable data property, a
+        // frozen source can no longer make a later write to the validated record
+        // fail — so refusing frozen host configuration would cost expressiveness
+        // and buy nothing.
         const checks = fields.map(({ descriptor, type }) => {
             const present = `${descriptor}?.enumerable && "value" in ${descriptor} && ${this.emitTypeCheck(type, `${descriptor}.value`, guarded ? "__state" : "undefined")}`;
             return type.kind === "optional" ? `(${descriptor} === undefined || (${present}))` : present;
@@ -1637,6 +1777,13 @@ export class JavaScriptEmitter {
         // type the author wrote and the memo still answers with one Type object per
         // instantiation.
         const argumentsParameter = generic ? ", __velarArguments" : "";
+        const copyName = this.runtimeTypeCopyName(statement.name);
+        // The copy plan this declaration files its own copies under. It has to be
+        // the same value at every visit within one parse and a different value for
+        // every other declared shape: the copy function itself is that for a plain
+        // record, and the arguments object is that for an instantiation, exactly as
+        // the traversal guard already reads them.
+        const ownCopyPlan = generic ? "__velarArguments" : copyName;
         const displayName = generic ? "__velarArguments.name" : JSON.stringify(statement.name);
         const pathText = (suffix) => generic
             ? (suffix === "" ? displayName : `${displayName} + ${JSON.stringify(suffix)}`)
@@ -1696,15 +1843,35 @@ export class JavaScriptEmitter {
             `${indentation}      const __velarDetail = ${explainName}(value${generic ? ", __velarArguments" : ""});`,
             `${indentation}      throw new __VelarValidationError(${generic ? `"Value does not match " + ${displayName}` : JSON.stringify(`Value does not match ${statement.name}`)} + (__velarDetail.reason ? " — " + __velarDetail.reason : "") + __velarValidationRejectionHint(value), __velarDetail);`,
             `${indentation}    }`,
-            `${indentation}    return value;`,
+            // D90 rule R5: parse hands back a fresh value built from the validated
+            // shape, so a later write through the argument cannot falsify a field
+            // the caller was handed, and a value reached through a readonly view
+            // does not widen by passing through parse. The copy memo is keyed by
+            // source object and plan, and this type's own plan is the identity that
+            // is one per declaration — its arguments for an instantiation, since two
+            // instantiations of one generic are two different declared shapes.
+            `${indentation}    return ${copyName}(value, __velarValidationState(), ${ownCopyPlan}${generic ? ", __velarArguments" : ""});`,
+            `${indentation}  },`,
+            // A derived type calls this with the plan it is itself copying under, so
+            // the inherited prefix lands on the derived copy instead of on a base
+            // copy another position in the same parse may already be holding.
+            `${indentation}  copy(value, __state = __velarValidationState(), __velarCopyPlan = ${ownCopyPlan}) {`,
+            `${indentation}    return ${copyName}(value, __state, __velarCopyPlan${generic ? ", __velarArguments" : ""});`,
             `${indentation}  },`,
         ];
         if (generic) {
             const instances = `__velarGenericInstances_${statement.name}`;
+            const copyLines = this.recordCopyFunctionLines(fields, copyName, baseExpression, indentation, argumentsParameter);
+            // A plan that reads the instantiation's arguments cannot hoist to module
+            // level and must not be shared between instantiations, so it is built
+            // once here, beside the arguments object it belongs to and reads.
+            const plans = this.pendingGenericCopyPlans;
             return [
                 ...explainLines,
                 ...this.recordCheckFunctionLines(fields, predicate, checkName, indentation, argumentsParameter, guarded),
                 "",
+                ...copyLines,
+                "",
                 `${indentation}const ${instances} = [];`,
                 // The instantiation memo: one frozen Type object per set of arguments,
                 // found by a key the emitter builds from the arguments' own identities.
@@ -1721,6 +1888,11 @@ export class JavaScriptEmitter {
                 `${indentation}    for (let __velarIndex = 0; __velarIndex < __velarTexts.length; __velarIndex += 1) __velarName += (__velarIndex === 0 ? "" : ", ") + __velarTexts[__velarIndex];`,
                 `${indentation}    __velarName += ">";`,
                 `${indentation}    const __velarArguments = { keys: __velarKeys, texts: __velarTexts, checks: __velarChecks, name: __velarName };`,
+                ...(plans.length > 0 ? [
+                    `${indentation}    __velarArguments.plans = [`,
+                    ...plans.map((plan) => `${indentation}      ${plan},`),
+                    `${indentation}    ];`,
+                ] : []),
                 `${indentation}    const __velarType = __velarRegisterRuntimeType(__velarValidationFreeze({`,
                 ...typeObject.map((line) => `${indentation}  ${line}`),
                 `${indentation}    }));`,
@@ -1734,6 +1906,8 @@ export class JavaScriptEmitter {
             ...explainLines,
             ...this.recordCheckFunctionLines(fields, predicate, checkName, indentation, "", guarded),
             "",
+            ...this.recordCopyFunctionLines(fields, copyName, baseExpression, indentation, ""),
+            "",
             `${indentation}${exportPrefix}const ${statement.name} = __velarRegisterRuntimeType(__velarValidationFreeze({`,
             ...typeObject,
             `${indentation}}));`,
@@ -1779,6 +1953,195 @@ export class JavaScriptEmitter {
             `${indentation}}`,
         ];
     }
+    runtimeTypeCopyName(name) {
+        return `__velarTypeCopy_${name}`;
+    }
+    /**
+     * D90 rule R5: the record's copy — one fresh object per source object *and*
+     * declared type, with every declared field rebuilt. The plan the caller is
+     * copying under is threaded in and passed on to the base, so a value reached
+     * once as `Base` and once as `Derived` in the same parse is two copies, each
+     * complete for its own type, rather than the base's copy with the derived
+     * fields written over it. Within one plan a base still builds the object and
+     * records it, and the derived fields land on that same copy, so one source
+     * object still maps to exactly one copy however deep the chain is.
+     */
+    recordCopyFunctionLines(fields, copyName, baseExpression, indentation, argumentsParameter) {
+        const fresh = baseExpression
+            ? `${baseExpression}.copy(value, __state, __velarCopyPlan)`
+            : `__state.copy.object(__state, value, __velarCopyPlan)`;
+        const previousPlans = this.genericCopyPlans;
+        const previousNames = this.genericCopyPlanNames;
+        this.genericCopyPlans = argumentsParameter ? [] : null;
+        this.genericCopyPlanNames = argumentsParameter ? new Map() : null;
+        const fieldLines = fields.flatMap(({ name, type }) => {
+            const descriptor = "__velarCopyField";
+            const copied = this.typeCopyExpression(type, `${descriptor}.value`, "__state");
+            return [
+                `${indentation}  {`,
+                `${indentation}    const ${descriptor} = __velarValidationOwnDescriptor(value, ${JSON.stringify(name)});`,
+                `${indentation}    if (${descriptor} !== undefined) __state.copy.field(__velarCopy, ${JSON.stringify(name)}, ${copied ?? `${descriptor}.value`});`,
+                `${indentation}  }`,
+            ];
+        });
+        this.pendingGenericCopyPlans = this.genericCopyPlans ?? [];
+        this.genericCopyPlans = previousPlans;
+        this.genericCopyPlanNames = previousNames;
+        return [
+            `${indentation}function ${copyName}(value, __state, __velarCopyPlan${argumentsParameter}) {`,
+            `${indentation}  const __velarCopySeen = __state.copy.seen(__state, value, __velarCopyPlan);`,
+            `${indentation}  if (__velarCopySeen !== undefined) return __velarCopySeen;`,
+            `${indentation}  const __velarCopy = ${fresh};`,
+            ...fieldLines,
+            `${indentation}  return __velarCopy;`,
+            `${indentation}}`,
+        ];
+    }
+    /**
+     * D90 rule R5: the module-level function that carries one copy plan, or null
+     * when the position rebuilds nothing. Interning is by the plan's own emitted
+     * text — which is what the plan means, module-locally — so two positions that
+     * copy the same shape share one plan and one memo entry, and two that copy
+     * different shapes can never be handed each other's copy.
+     */
+    copyPlanName(type) {
+        const body = this.copyPlanBody(type);
+        if (body === null)
+            return null;
+        if (this.copyPlanProbe)
+            return copyPlanSelfReference;
+        const generic = this.genericCopyPlans;
+        const genericNames = this.genericCopyPlanNames;
+        if (generic !== null && genericNames !== null && body.includes("__velarArguments")) {
+            const interned = genericNames.get(body);
+            if (interned !== undefined)
+                return interned;
+            const name = `__velarArguments.plans[${generic.length}]`;
+            genericNames.set(body, name);
+            generic.push(`(__velarCopyItem, __velarCopyState) => ${body.replaceAll(copyPlanSelfReference, name)}`);
+            return name;
+        }
+        const known = this.copyPlans.get(body);
+        if (known !== undefined)
+            return known;
+        const name = `__velarCopyPlan${this.copyPlans.size}`;
+        this.copyPlans.set(body, name);
+        this.copyPlanDeclarations.push([
+            `function ${name}(__velarCopyItem, __velarCopyState) {`,
+            `  return ${body.replaceAll(copyPlanSelfReference, name)};`,
+            "}",
+        ].join("\n"));
+        return name;
+    }
+    /**
+     * One copy plan's body. A container names itself where its memo key goes,
+     * because the copy it files is the one a later visit under the same plan must
+     * find — including the visit that reaches it through its own elements.
+     */
+    copyPlanBody(type) {
+        switch (type.kind) {
+            case "list":
+                return `__velarCopyState.copy.listOf(__velarCopyItem, __velarCopyState, ${this.typeCopyCallback(type.element)}, ${copyPlanSelfReference})`;
+            case "set":
+                return `__velarCopyState.copy.setOf(__velarCopyItem, __velarCopyState, ${this.typeCopyCallback(type.element)}, ${copyPlanSelfReference})`;
+            case "map":
+                return `__velarCopyState.copy.mapOf(__velarCopyItem, __velarCopyState, ${this.typeCopyCallback(type.key)}, ${this.typeCopyCallback(type.value)}, ${copyPlanSelfReference})`;
+            case "record":
+                return `__velarCopyState.copy.recordOf(__velarCopyItem, __velarCopyState, ${this.typeCopyCallback(type.value)}, ${copyPlanSelfReference})`;
+            default:
+                return this.typeCopyExpression(type, "__velarCopyItem", "__velarCopyState");
+        }
+    }
+    /** Whether a position rebuilds anything, asked without interning the plan it would need. */
+    typeCopiesAnything(type) {
+        const previous = this.copyPlanProbe;
+        this.copyPlanProbe = true;
+        try {
+            return this.typeCopyExpression(type, "__velarCopyItem", "__velarCopyState") !== null;
+        }
+        finally {
+            this.copyPlanProbe = previous;
+        }
+    }
+    /**
+     * D90 rule R5: the expression that rebuilds one validated position, or null
+     * when the position has nothing to copy — a primitive, an enum member, a
+     * class instance, or an opaque `unknown`. The copy follows the declared
+     * shape rather than the value, so an `unknown` field keeps handing back the
+     * reference the author was given: copying an opaque value structurally would
+     * change what parse returns.
+     */
+    typeCopyExpression(type, value, state) {
+        switch (type.kind) {
+            case "unknown":
+            case "any":
+            case "null":
+            case "string":
+            case "number":
+            case "bool":
+            case "promise":
+            case "class":
+            case "enum":
+            case "enumMember":
+            case "function":
+            case "action":
+            case "intrinsic":
+            case "typeObject":
+            case "runtimeType":
+            case "enumObject":
+            case "classConstructor":
+            case "extension":
+                return null;
+            case "optional": {
+                const inner = this.typeCopyExpression(type.inner, value, state);
+                return inner === null ? null : `(${value} == null ? ${value} : ${inner})`;
+            }
+            // A container copies through its own interned plan, because the plan is
+            // the identity its memo files the copy under and a fresh closure at every
+            // visit would be a different identity every time.
+            case "list":
+            case "set":
+            case "map":
+            case "record": {
+                const plan = this.copyPlanName(type);
+                return plan === null ? null : `${plan}(${value}, ${state})`;
+            }
+            case "named":
+                // An instantiation's copy is the declaration's, reached through the
+                // same memoized Type object its predicate is reached through.
+                if (type.application && this.genericTypeBinding(type.application.name)) {
+                    this.needsRuntimeTypeHelpers = true;
+                    return `${this.genericInstanceExpression(type.application)}.copy(${value}, ${state})`;
+                }
+                // Duration is text, an enum member is text, and a class instance is
+                // not plain data — none of them can or should be rebuilt.
+                if (type.name === "Duration")
+                    return null;
+                if (this.hints.enumNames.has(type.name))
+                    return null;
+                if (this.hints.classNames.has(type.name))
+                    return null;
+                if (this.enumAliasTarget(type.name) !== null)
+                    return null;
+                if (this.typeDeclarations.has(type.name))
+                    return `${type.name}.copy(${value}, ${state})`;
+                return this.runtimeTypeBinding(type.name) ? `${state}.copy.through(${type.name}, ${value}, ${state})` : null;
+            // A union, a structural object, and an erased type parameter are all
+            // positions the predicate did not fully decide, so the copy is the
+            // structural one: plain data recurses and anything else passes through.
+            case "union":
+                return type.members.every((member) => !this.typeCopiesAnything(member))
+                    ? null
+                    : `${state}.copy.plain(${value}, ${state})`;
+            case "object":
+            case "parameter":
+                return `${state}.copy.plain(${value}, ${state})`;
+        }
+    }
+    /** The per-element copy a container hands its runtime helper, or `null` when the element position has nothing to copy. */
+    typeCopyCallback(type) {
+        return this.copyPlanName(type) ?? "null";
+    }
     emitTypeAliasDeclaration(statement, depth) {
         const indentation = "  ".repeat(depth);
         // ENM-I4: identities follow aliases, so an alias whose target resolves to
@@ -1801,6 +2164,17 @@ export class JavaScriptEmitter {
         const checkName = this.runtimeTypeCheckName(statement.name);
         const guarded = this.runtimeTypeNeedsTraversalGuard(statement.name);
         const predicate = this.emitTypeCheck(resolveTypeReference(statement.target), "value", guarded ? "__state" : "undefined");
+        // D90 rule R5: an alias copies whatever its target copies. An alias of a
+        // primitive has nothing to rebuild, so its parse still returns the same
+        // value and allocates nothing. An alias of a declared record is that
+        // record's copy, so it passes on the plan it was called under too — an
+        // alias is a legal base, and the derived fields must not land on a copy
+        // the aliased record filed under its own plan.
+        const aliasTarget = resolveTypeReference(statement.target);
+        const copied = this.typeCopyExpression(aliasTarget, "value", "__state");
+        const forwarded = copied !== null && aliasTarget.kind === "named" && this.typeDeclarations.has(aliasTarget.name)
+            ? `${aliasTarget.name}.copy(value, __state, __velarCopyPlan)`
+            : copied;
         const exportPrefix = statement.exported ? "export " : "";
         return [
             guarded
@@ -1819,8 +2193,11 @@ export class JavaScriptEmitter {
             `${indentation}    if (!${checkName}(value)) {`,
             `${indentation}      throw new __VelarValidationError(${JSON.stringify(`Value does not match ${statement.name}`)}, { path: ${JSON.stringify(statement.name)} });`,
             `${indentation}    }`,
-            `${indentation}    return value;`,
+            `${indentation}    return ${copied === null ? "value" : `${statement.name}.copy(value)`};`,
             `${indentation}  },`,
+            ...(copied === null
+                ? [`${indentation}  copy(value) {`, `${indentation}    return value;`, `${indentation}  },`]
+                : [`${indentation}  copy(value, __state = __velarValidationState(), __velarCopyPlan) {`, `${indentation}    return ${forwarded};`, `${indentation}  },`]),
             `${indentation}}));`,
         ].join("\n");
     }
@@ -1843,6 +2220,12 @@ export class JavaScriptEmitter {
             `${indentation}    }`,
             `${indentation}    return value;`,
             `${indentation}  },`,
+            // D90 rule R5: every runtime Type object answers `copy`, so a record
+            // field typed by an imported enum reaches the same ABI a record does. An
+            // enum member is text, so the copy is the value itself.
+            `${indentation}  copy(value) {`,
+            `${indentation}    return value;`,
+            `${indentation}  },`,
             // ENM-U1: the members in declaration order, a fresh mutable List per call.
             `${indentation}  values() {`,
             `${indentation}    return [${values.join(", ")}];`,
@@ -1909,7 +2292,7 @@ export class JavaScriptEmitter {
             case "union":
                 return `(${type.members.map((member) => this.emitTypeCheck(member, value, state)).join(" || ")})`;
             case "object":
-                return `${value} !== null && typeof ${value} === "object"`;
+                return this.emitObjectTypeCheck(type, value, (field, read) => this.emitTypeCheck(field, read, state));
             case "function":
             case "action":
             case "intrinsic":
@@ -1966,6 +2349,8 @@ export class JavaScriptEmitter {
                 if (!this.runtimeTypeBinding(type.name))
                     return `${value} != null`;
                 return this.emitTypeCheck(type, value, state);
+            case "object":
+                return this.emitObjectTypeCheck(type, value, (field, read) => this.emitNarrowingCheck(field, read, state));
             case "parameter":
             case "typeObject":
             case "runtimeType":
@@ -1977,6 +2362,44 @@ export class JavaScriptEmitter {
                 return this.emitTypeCheck(type, value, state);
         }
     }
+    /**
+     * Charter section 5: a record proves its fields, not merely its presence. A
+     * declared record answers through the deep validator its declaration emits;
+     * a structural one has no declaration to hang a function on, so the same
+     * evidence is spelled inline as one expression over the field table the type
+     * already carries. `check` is the caller's own recursion, so a narrowing
+     * recheck keeps degrading a field it cannot prove rather than refusing it.
+     *
+     * The expansion is bounded, because an expression cannot recurse the way a
+     * generated function can: a structural type already being expanded, or one
+     * nested deeper than `maximumStructuralFieldDepth`, falls back to the
+     * presence test — the same evidence charter line 1006 allows an erased
+     * position. A field whose own check is a constant is dropped from the
+     * conjunction for the same reason: `false` there would refuse a value the
+     * language cannot inspect, and `true` proves nothing worth emitting.
+     */
+    emitObjectTypeCheck(type, value, check) {
+        const presence = `${value} !== null && typeof ${value} === "object"`;
+        if (type.fields.size === 0 || this.structuralFieldChecks.has(type)
+            || this.structuralFieldChecks.size >= maximumStructuralFieldDepth) {
+            return presence;
+        }
+        this.structuralFieldChecks.add(type);
+        try {
+            const fields = [];
+            for (const [name, field] of type.fields) {
+                const read = `${value}${javaScriptMemberAccess(name)}`;
+                const proof = check(field, read);
+                if (proof === "true" || proof === "false")
+                    continue;
+                fields.push(type.optionalFields?.has(name) ? `(${read} === undefined || ${proof})` : proof);
+            }
+            return fields.length === 0 ? presence : `(${presence} && ${fields.join(" && ")})`;
+        }
+        finally {
+            this.structuralFieldChecks.delete(type);
+        }
+    }
     runtimeTypeCheckName(name) {
         return `__velarTypeCheck_${name}`;
     }
@@ -2194,6 +2617,8 @@ export class JavaScriptEmitter {
             return null;
         if (name === "ValidationError")
             this.needsRuntimeTypeHelpers = true;
+        else if (name === "AssertionError")
+            this.needsAssertionErrorClass = true;
         else if (name === "NarrowingError")
             this.needsNarrowingErrorClass = true;
         else
@@ -2308,8 +2733,12 @@ export class JavaScriptEmitter {
         // D68 rule 177: `@iterate:` lands the same way, under its own unspellable
         // key. It is a plain prototype member, so a derived block simply shadows
         // the base's — overriding replaces, which is what "one answer" means.
+        // D90 R18: the asynchronous pull form is an async method under its own
+        // key — `async for` calls it once per element, and the trailing
+        // `return null` makes falling off the end mean exhaustion.
         const iterate = [];
         if (statement.iterate) {
+            const asynchronous = this.hints.asyncIterateBlocks.has(spanIdentity(statement.iterate.keywordSpan));
             const iterateDepth = depth + 2;
             const indent = "  ".repeat(iterateDepth);
             const body = [
@@ -2317,7 +2746,7 @@ export class JavaScriptEmitter {
                 ...this.emitStatementLines(statement.iterate.body, iterateDepth),
                 `${indent}return null;`,
             ];
-            iterate.push(`${indentation}  [${JSON.stringify(iterateMemberKey)}]() {\n${body.join("\n")}\n${indentation}  }`);
+            iterate.push(`${indentation}  ${asynchronous ? "async " : ""}[${JSON.stringify(asynchronous ? iterateAsyncMemberKey : iterateMemberKey)}]() {\n${body.join("\n")}\n${indentation}  }`);
         }
         const extension = statement.base ? ` extends ${statement.base.name}` : "";
         return `${indentation}${statement.exported ? "export " : ""}class ${statement.name}${extension} {\n${[...privateFields, ...staticFields, constructor, ...getters, ...methods, ...dispose, ...iterate].join("\n\n")}\n${indentation}}`;
@@ -2357,18 +2786,24 @@ export class JavaScriptEmitter {
     emitMappedExpression(expression, normalizeNull = true) {
         return this.emitMappedJavaScript(expression.span, () => {
             const key = spanIdentity(expression.span);
-            const normalizePromise = normalizeNull
-                && this.suppressPromiseNormalization === 0
-                && this.hints.normalizedPromiseValues.has(key);
-            if (normalizePromise)
-                this.suppressPromiseNormalization += 1;
+            // The wrapper covers exactly the value it wraps, so suppression follows
+            // the value rather than the whole subtree: an `await` in an argument
+            // position produces a *different* Promise and keeps its own boundary,
+            // which is what makes `await use(await supply())` check both of them.
+            const suppressed = this.suppressedPromiseValues.delete(key);
+            const normalizePromise = normalizeNull && !suppressed && this.hints.normalizedPromiseValues.has(key);
+            const passThrough = normalizePromise || suppressed
+                ? promiseValuePassThrough(expression).map((item) => spanIdentity(item.span))
+                : [];
+            for (const item of passThrough)
+                this.suppressedPromiseValues.add(item);
             let emitted;
             try {
                 emitted = this.emitExpression(expression);
             }
             finally {
-                if (normalizePromise)
-                    this.suppressPromiseNormalization -= 1;
+                for (const item of passThrough)
+                    this.suppressedPromiseValues.delete(item);
             }
             const narrowing = this.hints.runtimeNarrowings.get(key);
             if (narrowing) {
@@ -2469,6 +2904,15 @@ export class JavaScriptEmitter {
                     });
                     return `${asynchronous ? "await __velarCreateListAsync" : "__velarCreateList"}([${parts.join(", ")}])`;
                 }
+                if (expression.elements.length === 0) {
+                    // COL-P1: an empty List literal is the one array the runtime cannot
+                    // tell from an array JavaScript handed over empty, and the difference
+                    // decides whether every later element read re-proves its slot. The
+                    // compiler knows which one this is, so it is the compiler that says
+                    // so; a `[]` that arrives from the host is never adopted.
+                    this.needsCollectionHelpers = true;
+                    return "__velarAdoptList([])";
+                }
                 return `[${expression.elements.map((element) => this.emitMappedExpression(element)).join(", ")}]`;
             case "ObjectExpression": {
                 const needsControlledConstruction = expression.properties.some((property) => property.kind === "ObjectSpread"
@@ -2498,6 +2942,7 @@ export class JavaScriptEmitter {
             // absence is, not ten lines later where the `undefined` would surface.
             case "RequiredExpression": {
                 this.needsRequiredValueHelper = true;
+                this.needsAssertionErrorClass = true;
                 const description = JSON.stringify(requiredValueDescription(expression.value));
                 return `__velarRequired(${this.emitMappedExpression(expression.value)}, ${description}, ${expression.span.start})`;
             }
@@ -3257,7 +3702,14 @@ export class JavaScriptEmitter {
         return lines;
     }
     escapeTemplateText(value) {
-        return value.replaceAll("\\", "\\\\").replaceAll("\r", "\\r").replaceAll("`", "\\`").replaceAll("${", "\\${");
+        return value.replaceAll("\\", "\\\\").replaceAll("\r", "\\r").replaceAll("`", "\\`").replaceAll("${", "\\${")
+            // `\u{0}` is a sanctioned source spelling, so a C0 control reaches here
+            // as a raw byte. U+0000 delimits this emitter's own source-map markers
+            // (see `javaScriptNodeMarker`), so author text could otherwise spell a
+            // marker the renderer would delete out of the program. Every C0 control
+            // leaves as an escape sequence instead of a byte, which no scan of the
+            // generated text can mistake for emitter metadata.
+            .replaceAll(/[\u0000-\u001F]/gu, (control) => `\\u${control.codePointAt(0).toString(16).padStart(4, "0")}`);
     }
     blockAlwaysReturns(statements) {
         for (const statement of statements) {
@@ -3279,6 +3731,23 @@ export class JavaScriptEmitter {
         return false;
     }
 }
+/**
+ * The sub-expressions whose value *is* this expression's value. A Promise
+ * wrapper on the outer node already normalizes whatever these produce, so they
+ * skip a second one; every other position — an argument, a receiver, a
+ * function body — carries a Promise of its own and keeps its own boundary.
+ */
+function promiseValuePassThrough(expression) {
+    if (expression.kind === "ConditionalExpression")
+        return [expression.thenValue, expression.elseValue];
+    if (expression.kind === "BinaryExpression" && expression.operator === "??")
+        return [expression.left, expression.right];
+    return [];
+}
+/** The member-read suffix for a field name: a dot when the name is spellable, a subscript otherwise. */
+function javaScriptMemberAccess(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
+}
 function javaScriptIdentifiers(sources) {
     const identifiers = new Set();
     const identifierStart = (character) => /[A-Za-z_$]/u.test(character);
@@ -3468,6 +3937,14 @@ function mappedSource(source, sourceStart) {
     }
     return { code: source, mappings };
 }
+/** The names a checked block's contract publishes into VelarScript scope. */
+function contractExportNames(contract) {
+    return new Set([
+        ...contract.functions.map((item) => item.name),
+        ...contract.constants.map((item) => item.name),
+        ...contract.classes.map((item) => item.name),
+    ]);
+}
 function emitCheckedEmbeddedJavaScript(statement, factoryName) {
     const relative = (value) => ({
         start: value.start - statement.sourceSpan.start,