@faicad/faijs 0.33.1 → 0.35.2

package/dist/cad-runtime/direct-executor.js

@@ -12,7 +12,9 @@
  *   被 await 是合法 JS）；
  * - keep/keepHidden 尾随键剥离（行内 keep 由 MetadataExtractor 的 metadata.keep
  *   表另存，§4.4 消费判定用——执行侧不传）；
- * - 顶层函数定义提升到 `__ctx.<name>`（函数体 cad 等经命名空间绑定注入）；
+ * - 顶层函数定义提升到 `__ctx.<name>`（函数体 cad 等经命名空间绑定注入；函数体
+ *   引用到的顶层变量/函数经 call-time 守卫 + `let { ... } = __ctx` 解构注入——
+ *   约束 1：读顶层 call-time 取值，函数体内赋值写本地副本不落顶层）；
  * - import 行不执行（库装载在 runtime 层；`ns.<binding>` 经命名空间对象访问）。
  *
  * 错误定位：单行单元失败记 failedAt（{ index, callee, message } + lineNo）。
@@ -49,6 +51,112 @@ function resolveExecBackend(choice) {
         return new InterpBackend();
     return new VmBackend();
 }
+/**
+ * F1（2026-10-15）：标识符提升的**保护区间**——字符串字面量 / 模板文本 / 注释。
+ *
+ * 根因：hoistBlockText ② 与 hoistText 用文本级 `\b<name>\b` 全局替换做标识符提升，
+ * 不区分代码与字符串。for 循环体内与顶层标识符同名的字符串字面量被改写成
+ * `__ctx.<name>`（`parent: 'carrier'` → `'__ctx.carrier'`），装配侧按「父级不存在」
+ * 静默挂错父级——animation 钉子 `test/p2-child-ref.test.ts:83-105` 的上游根因。
+ *
+ * 区间来自 acorn AST（ranges 已开）：字符串 Literal 全区间、TemplateLiteral 的
+ * quasis（模板**文本**部分；`${…}` 表达式是代码，不保护）、onComment 收集的注释
+ * 区间。解析策略与 hoistBlockText 一致（module 直解 → `(function(){ … })` 回退，
+ * 放行 break/continue/return）；回退包装的前缀长度逐区间扣减，保持原文本基准。
+ * 两轮都解析失败（调用方传入的不是合法 JS 片段，如对象方法简写）时返回空数组
+ * = 无保护，维持修复前行为。
+ */
+function collectHoistProtectedRanges(text) {
+    const ranges = [];
+    const comments = [];
+    const parseOpts = {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        locations: false,
+        ranges: true,
+        onComment: (_block, _text, start, end) => {
+            comments.push([start, end]);
+        },
+    };
+    let ast;
+    let shift = 0;
+    try {
+        ast = acornParse(text, parseOpts);
+    }
+    catch {
+        const wrapped = `(function(){ ${text} })`;
+        try {
+            ast = acornParse(wrapped, parseOpts);
+            shift = '(function(){ '.length;
+        }
+        catch {
+            return [];
+        }
+    }
+    const walk = (n) => {
+        if (!n || typeof n !== 'object')
+            return;
+        if (n.type === 'Literal' && typeof n.value === 'string') {
+            ranges.push([n.start - shift, n.end - shift]);
+        }
+        else if (n.type === 'TemplateLiteral') {
+            for (const q of n.quasis ?? []) {
+                if (typeof q?.start === 'number' && typeof q?.end === 'number') {
+                    ranges.push([q.start - shift, q.end - shift]);
+                }
+            }
+        }
+        for (const k of Object.keys(n)) {
+            if (k === 'loc' || k === 'start' || k === 'end' || k === 'range' || k === 'parent' || k === 'type')
+                continue;
+            const v = n[k];
+            if (Array.isArray(v))
+                for (const item of v)
+                    walk(item);
+            else if (v && typeof v === 'object')
+                walk(v);
+        }
+    };
+    walk(ast);
+    for (const [s, e] of comments)
+        ranges.push([s - shift, e - shift]);
+    return ranges;
+}
+/**
+ * F1：带保护区间的顺序文本替换（标识符 / 命名空间提升专用）。
+ *
+ * `subs` 每条 { re, emit } 依次作用于 text（后者看到前者的输出，与既有顺序替换
+ * 语义一致）；匹配整体落在保护区间（字符串 / 模板文本 / 注释）内时原样保留。
+ * 保护区间按**当前** text 重算（前一条 sub 会改变偏移），text 未变时复用。
+ * 无保护区间（解析失败）时退化为普通替换——与修复前完全一致。
+ *
+ * `re` 必须带 `g` 标志；`emit(groups)` 接收捕获组（$1 起），返回替换文本。
+ */
+function replaceOutsideProtected(text, subs) {
+    let out = text;
+    let ranges = [];
+    let rangesFor = null;
+    for (const sub of subs) {
+        if (!sub.re.global)
+            throw new Error('replaceOutsideProtected: sub.re must carry the g flag');
+        if (rangesFor !== out) {
+            ranges = collectHoistProtectedRanges(out);
+            rangesFor = out;
+        }
+        const rr = ranges;
+        out = out.replace(sub.re, (...args) => {
+            const match = args[0];
+            const groups = args.slice(1, -2);
+            const offset = args[args.length - 2];
+            for (const [s, e] of rr) {
+                if (offset >= s && offset + match.length <= e)
+                    return match;
+            }
+            return sub.emit(groups);
+        });
+    }
+    return out;
+}
 /**
  * DirectExecutor executes `.fai.js` source text directly in the JS VM. Each
  * top-level statement is transformed mechanically (ctx hoisting + await
@@ -186,7 +294,8 @@ export class DirectExecutor {
             if (node.type === 'ImportDeclaration')
                 continue;
             const rawLine = (node?.loc?.start?.line ?? 1) - lineOffset;
-            const unit = this.transformTopNode(node, parseText, declared, rawLine, lineOffset);
+            // 仅取行区间（lineNo/endLine），注入内容不消费——候选全集传空集即可。
+            const unit = this.transformTopNode(node, parseText, declared, rawLine, lineOffset, new Set());
             if (unit)
                 ranges.push({ lineNo: unit.lineNo, endLine: unit.endLine });
         }
@@ -700,22 +809,100 @@ export class DirectExecutor {
         }
         const { nodes, lineOffset, parseText } = this.parseBody(code);
         const declared = new Set(); // 累积：参数名 + outputs + 函数名
+        // 约束 1：函数体外层引用注入的候选全集（逐语句变换前一次预扫）。
+        // 不能用逐语句累积的 declared——函数定义在顶层声明之前（前向引用）时该名
+        // 尚未入集 → 漏注入 → vm 调用失败而 interp call-time 查 ctx 成功 → 双后端分叉。
+        const allCtxNames = this.collectAllCtxNames(nodes);
         const units = [];
+        const seenLines = new Set();
         for (const node of nodes) {
             if (node.type === 'ImportDeclaration')
                 continue; // import 行不执行
             const rawLine = (node?.loc?.start?.line ?? 1) - lineOffset;
-            const unit = this.transformTopNode(node, parseText, declared, rawLine, lineOffset);
+            if (seenLines.has(rawLine)) {
+                throw new ParseError(`multiple statements on line ${rawLine}: faijs requires one statement per line (use newline instead of ';')`, rawLine, 'E_SYNTAX');
+            }
+            seenLines.add(rawLine);
+            const unit = this.transformTopNode(node, parseText, declared, rawLine, lineOffset, allCtxNames);
             if (unit)
                 units.push(unit);
         }
         return units;
     }
-    transformTopNode(node, code, declared, lineNo, lineOffset) {
+    /**
+     * 约束 1 候选全集预扫：本脚本全部声明名（含块内声明——vm 的块单元经
+     * hoistBlockText 把块内 let/const/function 提升写 ctx，interp 的 root env
+     * 块级写入同样落 ctx）∪ 现有 ctx 键（params/imports 预置键 + append 场景
+     * 先前执行产出）。不下潜函数体——函数局部量永不入 ctx。
+     * 命名空间名从候选剔除（函数体的 ns 绑定由 transformFunction 的 binds 提供）。
+     */
+    collectAllCtxNames(nodes) {
+        const names = new Set(Object.keys(this.ctx));
+        const walk = (n) => {
+            if (!n || typeof n !== 'object')
+                return;
+            if (n.type === 'VariableDeclarator') {
+                this.collectPatternNames(n.id, names);
+            }
+            else if (n.type === 'FunctionDeclaration') {
+                if (n.id?.type === 'Identifier')
+                    names.add(n.id.name);
+                return; // 函数体内声明是函数局部量，不入 ctx
+            }
+            else if (n.type === 'FunctionExpression' || n.type === 'ArrowFunctionExpression') {
+                return; // 函数表达式/箭头函数体同样不下潜
+            }
+            for (const k of Object.keys(n)) {
+                if (k === 'loc' || k === 'start' || k === 'end' || k === 'range' || k === 'parent' || k === 'type')
+                    continue;
+                const v = n[k];
+                if (Array.isArray(v))
+                    for (const item of v)
+                        walk(item);
+                else if (v && typeof v === 'object')
+                    walk(v);
+            }
+        };
+        for (const node of nodes)
+            walk(node);
+        for (const k of Object.keys(this.namespaces)) {
+            if (k !== 'contractVersion')
+                names.delete(k);
+        }
+        return names;
+    }
+    /** 解构模式绑定名收集（Identifier / ObjectPattern / ArrayPattern / AssignmentPattern / RestElement）。 */
+    collectPatternNames(pattern, names) {
+        if (!pattern || typeof pattern !== 'object')
+            return;
+        switch (pattern.type) {
+            case 'Identifier':
+                names.add(pattern.name);
+                return;
+            case 'ObjectPattern':
+                for (const prop of pattern.properties ?? []) {
+                    if (prop.type === 'Property')
+                        this.collectPatternNames(prop.value, names);
+                    else if (prop.type === 'RestElement')
+                        this.collectPatternNames(prop.argument, names);
+                }
+                return;
+            case 'ArrayPattern':
+                for (const el of pattern.elements ?? [])
+                    this.collectPatternNames(el, names);
+                return;
+            case 'AssignmentPattern':
+                this.collectPatternNames(pattern.left, names);
+                return;
+            default:
+                return;
+        }
+    }
+    transformTopNode(node, code, declared, lineNo, lineOffset, allCtxNames) {
         let unit;
         switch (node.type) {
             case 'FunctionDeclaration':
-                unit = this.transformFunction(node, code, declared, lineNo);
+                unit = this.transformFunction(node, code, declared, lineNo, allCtxNames);
                 break;
             case 'VariableDeclaration':
                 unit = this.transformVariable(node, code, declared, lineNo);
@@ -786,7 +973,8 @@ export class DirectExecutor {
      * ctx 键，不会导致错误）。v2 可加 AST walk 精确跳过嵌套作用域。
      *
      * 实现策略：先收集块内所有声明名（acorn 扫描 VariableDeclarator + 函数名），
-     * 再做两步文本替换：① 声明 LHS 提升写 __ctx 赋值；② 自由引用提升走 hoistText。
+     * 再做文本替换（⓪ for-of 头 ① 声明 LHS ② 自由引用 ③ 命名空间绑定），全部经
+     * replaceOutsideProtected 跳过字符串 / 模板文本 / 注释区间（F1，2026-10-15）。
      */
     hoistBlockText(text, declared) {
         // 收集块内所有声明名（用于引用提升与声明改写）
@@ -844,28 +1032,45 @@ export class DirectExecutor {
         // 从提升集合中移除命名空间名（cad 等留在 __ns）
         for (const nsName of nsNames)
             names.delete(nsName);
-        // 声明 LHS 改写 + 自由引用提升（词法级，两步替换）
-        let out = text;
-        // ⓪ for-of/in 头部声明：`for (const x of/in ...)` → `for (__ctx.x of/in ...)`。
-        //   步骤①的 `\w+\s*=` 形态匹配不到 of/in 头部，若不先行改写，步骤②会把
-        //   声明名提升为 `const __ctx.x` → SyntaxError。双前缀由下方修正兜底。
-        out = out.replace(/\bfor\s*\(\s*(?:const|let)\s+(\w+)\s+(of|in)\b/g, 'for (__ctx.$1 $2 ');
-        // ① const/let x = ... → __ctx.x = ...（去关键字 + LHS 加 __ctx.）
-        out = out.replace(/\b(?:const|let)\s+(\w+)\s*=/g, '__ctx.$1 =');
-        // ② 自由引用提升（与 hoistText 同逻辑，但含块内声明名；排除命名空间名）
-        for (const name of names) {
-            out = out.replace(new RegExp(`\\b${name}\\b`, 'g'), `__ctx.${name}`);
+        // ⓪ for-of/in 头部声明 + ① 声明 LHS 改写 + ② 自由引用提升 + ③ 命名空间绑定：
+        // 统一走 replaceOutsideProtected（F1）——落在字符串 / 模板文本 / 注释区间内的
+        // 匹配原样保留。修复前循环体内 `parent: 'carrier'` 被改写成 `'__ctx.carrier'`，
+        // 装配侧静默挂错父级（animation 钉子 test/p2-child-ref.test.ts:83-105）。
+        const subs = [
+            // ⓪ for-of/in 头部声明：`for (const x of/in ...)` → `for (__ctx.x of/in ...)`。
+            //    ① 的 `\w+\s*=` 形态匹配不到 of/in 头部，若不先行改写，② 会把声明名
+            //    提升为 `const __ctx.x` → SyntaxError。双前缀由下方修正兜底。
+            {
+                re: /\bfor\s*\(\s*(?:const|let)\s+(\w+)\s+(of|in)\b/g,
+                emit: (g) => `for (__ctx.${g[0]} ${g[1]} `,
+            },
+            // ① const/let x = ... → __ctx.x = ...（去关键字 + LHS 加 __ctx.）
+            { re: /\b(?:const|let)\s+(\w+)\s*=/g, emit: (g) => `__ctx.${g[0]} =` },
+        ];
+        // ② 自由引用提升（与 hoistText 同逻辑，但含块内声明名；排除命名空间名）。
+        //    合并为单趟交替替换：插入的 `__ctx.` 前缀不会让其它名字被二次匹配
+        //    （`_`/`.` 都是词边界断点），与逐名顺序替换等价。
+        if (names.size > 0) {
+            subs.push({
+                re: new RegExp(`\\b(${[...names].join('|')})\\b`, 'g'),
+                emit: (g) => `__ctx.${g[0]}`,
+            });
         }
         // ③ 命名空间名 → __ns.<name> + await 调用
-        // 块内 cad.xxx(...) 调用需要 await（与扁平行式 emitCall 的 await 语义一致）。
-        // 分两步：先替换调用形态 `<ns>.<member>(` → `await __ns.<ns>.<member>(`，
-        // 再替换裸引用 `<ns>`（非成员访问）→ `__ns.<ns>`。
-        for (const nsName of nsNames) {
+        if (nsNames.size > 0) {
+            const alt = [...nsNames].join('|');
             // 调用形态：`cad.box(` → `await __ns.cad.box(`
-            out = out.replace(new RegExp(`(?<![.\\w])\\b${nsName}\\s*\\.\\s*(\\w+)\\s*\\(`, 'g'), `await __ns.${nsName}.$1(`);
+            subs.push({
+                re: new RegExp(`(?<![.\\w])\\b(${alt})\\s*\\.\\s*(\\w+)\\s*\\(`, 'g'),
+                emit: (g) => `await __ns.${g[0]}.${g[1]}(`,
+            });
             // 裸成员访问（非调用）：`cad.foo` → `__ns.cad.foo`（非调用不加 await）
-            out = out.replace(new RegExp(`(?<![.\\w])\\b${nsName}\\s*\\.`, 'g'), `__ns.${nsName}.`);
+            subs.push({
+                re: new RegExp(`(?<![.\\w])\\b(${alt})\\s*\\.`, 'g'),
+                emit: (g) => `__ns.${g[0]}.`,
+            });
         }
+        let out = replaceOutsideProtected(text, subs);
         // __ctx.__ctx.x → __ctx.x（双前缀修正：LHS 改写后 name 又被提升替换）
         out = out.replace(/__ctx\.__ctx\./g, '__ctx.');
         // __ns.__ns.cad → __ns.cad（命名空间双前缀修正）
@@ -874,26 +1079,316 @@ export class DirectExecutor {
         out = out.replace(/await\s+await\s+__ns\./g, 'await __ns.');
         return out;
     }
-    /** 顶层函数提升：`__ctx.<name> = async function <name>(...) { 命名空间绑定; 体 }`。 */
-    transformFunction(node, code, declared, lineNo) {
+    /** 顶层函数提升：`__ctx.<name> = async function <name>(...) { 命名空间绑定; 外层引用守卫+解构; 体 }`。 */
+    transformFunction(node, code, declared, lineNo, allCtxNames) {
         const name = node.id?.name;
         if (!name)
             throw new ParseError('function declaration must have a name', lineNo, 'E_STATEMENT');
+        // 形参名单（fnParams / 遮蔽集用）；默认值等非 Identifier 形参不在此列。
         const params = (node.params ?? []).map((p) => p?.name).filter((x) => typeof x === 'string');
-        const bodyText = code.slice(node.body.start + 1, node.body.end - 1);
+        // 形参保留源文（含默认值表达式）——默认值在 call-time 求值。此前只取 p.name
+        // 会把默认值静默剥离（`d = SIZE` 变成 `d`），与 interp 的 E_UNSUPPORTED_SYNTAX
+        // 形成静默/报错分叉；保留原文后，默认值引用顶层变量在 call 时 ReferenceError
+        // （默认值先于注入解构求值），两后端都失败（constraint 1 差分测试钉住）。
+        let paramsText = (node.params ?? []).map((p) => code.slice(p.start, p.end)).join(', ');
+        let bodyText = code.slice(node.body.start + 1, node.body.end - 1);
         const nsNames = Object.keys(this.namespaces).filter((k) => k !== 'contractVersion');
+        // 约束 1 配套：函数体直接作用域内「返回 Promise 的调用」（顶层本机函数 /
+        // 命名空间 op）注入 await——与 emitCall 给顶层调用行加 await 的语义一致。
+        // 缺此注入时 vm 对 `fib(n-1) + fib(n-2)` 之类组合运算拿到 Promise（既有缺陷，
+        // 旧测试只断言不失败未暴露）；interp 的 evalExpr 原生 await 无此问题。
+        // 编辑点分两区：参数默认值（签名区）与函数体（体区），右→左插入保持偏移有效。
+        const awaitCalls = this.collectFnAwaitEdits(node, allCtxNames, nsNames);
+        awaitCalls.sort((a, b) => b.start - a.start);
+        const bodyStart = node.body.start + 1;
+        const paramsStart = (node.params?.[0]?.start ?? bodyStart);
+        for (const c of awaitCalls) {
+            if (c.start < bodyStart) {
+                const rel = c.start - paramsStart;
+                paramsText = `${paramsText.slice(0, rel)}await ${paramsText.slice(rel)}`;
+            }
+            else {
+                const rel = c.start - bodyStart;
+                bodyText = `${bodyText.slice(0, rel)}await ${bodyText.slice(rel)}`;
+            }
+        }
         const binds = nsNames.map((n) => `  const ${n} = __ns.${n}`).join('\n');
+        // 约束 1：函数体读顶层变量——把函数体引用到的顶层名注入 call-time 守卫 + let 解构。
+        // 读：call-time 取当前值（与 interp 的 ctx 查找同语义，含前向引用）；
+        // 写：解构用 let，函数体内赋值写本地副本，不落顶层（与 interp 的 function env
+        // assign 写本地 vars 同语义）。
+        const outerVars = this.collectFnBodyOuterRefs(node, allCtxNames, params, nsNames);
+        const guards = outerVars.map((v) => `  if (!Object.prototype.hasOwnProperty.call(__ctx, '${v}')) throw new ReferenceError('${v} is not defined')`);
         const body = [
-            `__ctx.${name} = async function ${name}(${params.join(', ')}) {`,
+            `__ctx.${name} = async function ${name}(${paramsText}) {`,
             binds,
+            ...guards,
+            ...(outerVars.length > 0 ? [`  let { ${outerVars.join(', ')} } = __ctx`] : []),
             bodyText,
             '}',
         ].join('\n');
-        // 本机函数体引用其它本机函数/变量走 __ctx（与顶层一致）
+        // 本机函数体引用其它本机函数/变量走外层引用注入（call-time 读 __ctx，与顶层一致）
         declared.add(name);
         this.fnParams.set(name, params);
         return { lineNo, body, writes: [name], refs: [], callee: name, endLine: 0 };
     }
+    /**
+     * 约束 1 配套：收集函数体直接作用域内需要注入 await 的调用节点。
+     * 资格：callee 是 Identifier 且属于候选全集（顶层本机函数），或 callee 是
+     * MemberExpression 且 object 是命名空间名（cad.box 等）。已显式 await 的调用
+     * 不重复注入（其参数里的调用仍递归处理）。不下潜嵌套函数——嵌套 sync function
+     * 体内 await 是 SyntaxError，维持既有行为。参数默认值表达式同样覆盖
+     * （默认值在 async 函数作用域求值，await 合法）。
+     */
+    collectFnAwaitEdits(fnNode, allCtxNames, nsNames) {
+        const edits = [];
+        const ns = new Set(nsNames);
+        const qualifies = (call) => {
+            const callee = call.callee;
+            if (callee?.type === 'Identifier')
+                return allCtxNames.has(callee.name);
+            if (callee?.type === 'MemberExpression' && callee.object?.type === 'Identifier') {
+                return ns.has(callee.object.name);
+            }
+            return false;
+        };
+        const walk = (n) => {
+            if (!n || typeof n !== 'object')
+                return;
+            if (n.type === 'FunctionDeclaration' || n.type === 'FunctionExpression' || n.type === 'ArrowFunctionExpression') {
+                return;
+            }
+            if (n.type === 'AwaitExpression') {
+                // 已显式 await：调用本身不重复注入；实参/实参表达式里的调用仍递归处理
+                const arg = n.argument;
+                if (arg?.type === 'CallExpression') {
+                    this.walkChildNodes(arg.callee, walk);
+                    for (const a of arg.arguments ?? [])
+                        walk(a);
+                }
+                else {
+                    walk(arg);
+                }
+                return;
+            }
+            if (n.type === 'CallExpression') {
+                if (qualifies(n))
+                    edits.push(n);
+                this.walkChildNodes(n.callee, walk);
+                for (const a of n.arguments ?? [])
+                    walk(a);
+                return;
+            }
+            this.walkChildNodes(n, walk);
+        };
+        const stmts = fnNode.body?.type === 'BlockStatement' ? (fnNode.body.body ?? []) : [];
+        for (const s of stmts)
+            walk(s);
+        for (const p of fnNode.params ?? [])
+            walk(p); // 参数默认值表达式（call-time 求值）
+        return edits;
+    } /** 遍历节点全部子节点（跳过元数据键），逐个交给 walk。 */
+    walkChildNodes(n, walk) {
+        if (!n || typeof n !== 'object')
+            return;
+        for (const k of Object.keys(n)) {
+            if (k === 'loc' || k === 'start' || k === 'end' || k === 'range' || k === 'parent' || k === 'type')
+                continue;
+            const v = n[k];
+            if (Array.isArray(v))
+                for (const item of v)
+                    walk(item);
+            else if (v && typeof v === 'object')
+                walk(v);
+        }
+    }
+    /**
+     * 约束 1：函数体引用到的顶层名（注入候选）= 候选全集 ∩ 函数体引用集
+     * − 本函数作用域遮蔽集 − 命名空间名。
+     */
+    collectFnBodyOuterRefs(node, allCtxNames, params, nsNames) {
+        const shadow = new Set(params);
+        this.collectFnShadowNames(node.body, shadow);
+        const referenced = new Set();
+        this.collectFnReferences(node.body, referenced);
+        const ns = new Set(nsNames);
+        return [...referenced]
+            .filter((v) => allCtxNames.has(v) && !shadow.has(v) && !ns.has(v))
+            .sort();
+    }
+    /**
+     * 本函数「函数作用域」遮蔽集：决定哪些名不注入（函数体内的同名绑定优先于
+     * 注入的顶层解构）。收集规则：
+     * - 函数体**顶层语句列表**直接声明的 let/const/function 名（函数级作用域）；
+     * - 任意块深的 `var` 声明名（var 是函数级；若块内 var 与注入解构同名会
+     *   SyntaxError，必须让位）；
+     * - 任意块深的 function 声明名（vm 的 new Function 体是 sloppy 模式，块内
+     *   function 声明经 Annex B 提升到函数级）；
+     * - **不下潜嵌套函数体**：嵌套函数自己的声明只遮蔽它内部，不应阻止外层注入
+     *   （否则嵌套函数本地遮蔽会让外层同名顶层引用解析失败）。
+     * 块级 let/const 不入遮蔽集：它们是块作用域，与注入的函数级 `let { ... }`
+     * 并存是合法遮蔽，语义正确。
+     */
+    collectFnShadowNames(body, shadow) {
+        const stmts = body?.type === 'BlockStatement' ? (body.body ?? []) : [];
+        for (const stmt of stmts) {
+            if (stmt.type === 'FunctionDeclaration') {
+                if (stmt.id?.type === 'Identifier')
+                    shadow.add(stmt.id.name);
+            }
+            else if (stmt.type === 'VariableDeclaration' && (stmt.kind === 'let' || stmt.kind === 'const')) {
+                for (const d of stmt.declarations ?? [])
+                    this.collectPatternNames(d.id, shadow);
+            }
+        }
+        const walk = (n) => {
+            if (!n || typeof n !== 'object')
+                return;
+            if (n.type === 'FunctionDeclaration') {
+                if (n.id?.type === 'Identifier')
+                    shadow.add(n.id.name);
+                return; // 不下潜嵌套函数体
+            }
+            if (n.type === 'FunctionExpression' || n.type === 'ArrowFunctionExpression')
+                return;
+            if (n.type === 'VariableDeclaration' && n.kind === 'var') {
+                for (const d of n.declarations ?? [])
+                    this.collectPatternNames(d.id, shadow);
+            }
+            for (const k of Object.keys(n)) {
+                if (k === 'loc' || k === 'start' || k === 'end' || k === 'range' || k === 'parent' || k === 'type')
+                    continue;
+                const v = n[k];
+                if (Array.isArray(v))
+                    for (const item of v)
+                        walk(item);
+                else if (v && typeof v === 'object')
+                    walk(v);
+            }
+        };
+        for (const stmt of stmts)
+            walk(stmt);
+    }
+    /**
+     * 函数体引用位置标识符收集（含嵌套函数体——嵌套函数引用的顶层名注入到外层
+     * 函数作用域后经闭包可见）。排除声明/绑定位置与非 computed 成员属性、
+     * 非 shorthand 对象键、label。
+     */
+    collectFnReferences(n, refs) {
+        if (!n || typeof n !== 'object')
+            return;
+        switch (n.type) {
+            case 'Identifier':
+                refs.add(n.name);
+                return;
+            case 'MemberExpression':
+                this.collectFnReferences(n.object, refs);
+                if (n.computed)
+                    this.collectFnReferences(n.property, refs);
+                return;
+            case 'Property':
+                // shorthand `{ SIZE }`：key 同时是引用；computed `{ [SIZE]: 1 }`：key 是引用；
+                // 普通键 `{ SIZE: 1 }`：key 不是引用。
+                if (n.shorthand || n.computed)
+                    this.collectFnReferences(n.key, refs);
+                this.collectFnReferences(n.value, refs);
+                return;
+            case 'VariableDeclaration':
+                for (const d of n.declarations ?? []) {
+                    this.walkFnPattern(d.id, refs); // 绑定名跳过；模式内默认值是引用
+                    this.collectFnReferences(d.init, refs);
+                }
+                return;
+            case 'FunctionDeclaration':
+            case 'FunctionExpression':
+            case 'ArrowFunctionExpression':
+                for (const p of n.params ?? [])
+                    this.walkFnPattern(p, refs);
+                this.collectFnReferences(n.body, refs);
+                return;
+            case 'CatchClause':
+                this.walkFnPattern(n.param, refs);
+                this.collectFnReferences(n.body, refs);
+                return;
+            case 'ForStatement':
+                if (n.init?.type === 'VariableDeclaration') {
+                    for (const d of n.init.declarations ?? []) {
+                        this.walkFnPattern(d.id, refs);
+                        this.collectFnReferences(d.init, refs);
+                    }
+                }
+                else {
+                    this.collectFnReferences(n.init, refs);
+                }
+                this.collectFnReferences(n.test, refs);
+                this.collectFnReferences(n.update, refs);
+                this.collectFnReferences(n.body, refs);
+                return;
+            case 'ForInStatement':
+            case 'ForOfStatement':
+                if (n.left?.type === 'VariableDeclaration') {
+                    for (const d of n.left.declarations ?? [])
+                        this.walkFnPattern(d.id, refs);
+                }
+                else {
+                    this.walkFnPattern(n.left, refs); // for (x of ...)——左值是赋值目标（引用）
+                }
+                this.collectFnReferences(n.right, refs);
+                this.collectFnReferences(n.body, refs);
+                return;
+            case 'LabeledStatement':
+                this.collectFnReferences(n.body, refs);
+                return;
+            case 'BreakStatement':
+            case 'ContinueStatement':
+                return; // label 不是引用
+            default:
+                for (const k of Object.keys(n)) {
+                    if (k === 'loc' || k === 'start' || k === 'end' || k === 'range' || k === 'parent' || k === 'type')
+                        continue;
+                    const v = n[k];
+                    if (Array.isArray(v))
+                        for (const item of v)
+                            this.collectFnReferences(item, refs);
+                    else if (v && typeof v === 'object')
+                        this.collectFnReferences(v, refs);
+                }
+        }
+    }
+    /** 绑定模式遍历：绑定名跳过；模式内默认值表达式（AssignmentPattern.right）按引用收集。 */
+    walkFnPattern(n, refs) {
+        if (!n || typeof n !== 'object')
+            return;
+        switch (n.type) {
+            case 'Identifier':
+                return; // 绑定名，不是引用
+            case 'AssignmentPattern':
+                this.collectFnReferences(n.right, refs);
+                this.walkFnPattern(n.left, refs);
+                return;
+            case 'ObjectPattern':
+                for (const prop of n.properties ?? []) {
+                    if (prop.type === 'Property') {
+                        if (prop.computed)
+                            this.collectFnReferences(prop.key, refs);
+                        this.walkFnPattern(prop.value, refs);
+                    }
+                    else if (prop.type === 'RestElement') {
+                        this.walkFnPattern(prop.argument, refs);
+                    }
+                }
+                return;
+            case 'ArrayPattern':
+                for (const el of n.elements ?? [])
+                    this.walkFnPattern(el, refs);
+                return;
+            case 'RestElement':
+                this.walkFnPattern(n.argument, refs);
+                return;
+            default:
+                this.collectFnReferences(n, refs);
+        }
+    }
     /** const/let 行：参数（字面量）直接进 ctx；op 行变换调用；派生常量求值。 */
     transformVariable(node, code, declared, lineNo) {
         if (node.kind !== 'const' && node.kind !== 'let') {
@@ -939,8 +1434,11 @@ export class DirectExecutor {
             return { lineNo, body: `__ctx.${name} = ${call}`, writes: [name], refs: this.collectRefs(init), callee: this.calleeOf(init), endLine: 0 };
         }
         if (init) {
-            // 参数行（字面量/数组/对象）或派生常量：求值后写入 ctx（引用走 __ctx 提升）
-            const exprText = this.hoistText(code.slice(init.start, init.end), declared);
+            // 参数行（字面量/数组/对象）或派生常量：AST 变换后写入 ctx。
+            // 用 transformArg 而非整段 hoistText——数组/对象/成员/条件/二元里的命名空间
+            // 调用与 ctx 引用才能正确发射（约束 2：顶层值表达式不得绕过 AST 变换走上
+            // 「文本同构」快路径）。
+            const exprText = this.transformArg(init, code, declared, lineNo);
             declared.add(name);
             return { lineNo, body: `__ctx.${name} = ${exprText}`, writes: [name], refs: [], callee: undefined, endLine: 0 };
         }
@@ -961,8 +1459,8 @@ export class DirectExecutor {
                 return { lineNo, body: `__ctx.${varName} = ${call}`, writes: [varName], refs: this.collectRefs(init), callee: this.calleeOf(init), endLine: 0 };
             }
             // 变量→变量重赋值 / 表达式重赋值（`bp = bp2` / `x = a + b`）：合法 JS，
-            // 直接提升自由标识符写回 ctx（A-15 最后写者语义）。
-            const rhsText = this.hoistText(code.slice(init?.start ?? expr.right.start, expr.right.end), declared);
+            // 走 AST 变换提升自由标识符写回 ctx（A-15 最后写者语义）。
+            const rhsText = this.transformArg(expr.right, code, declared, lineNo);
             return { lineNo, body: `__ctx.${varName} = ${rhsText}`, writes: [varName], refs: [], callee: undefined, endLine: 0 };
         }
         if (expr?.type === 'CallExpression') {
@@ -1112,16 +1610,24 @@ export class DirectExecutor {
         switch (node.type) {
             case 'Literal':
                 return JSON.stringify(node.value);
-            case 'Identifier':
+            case 'Identifier': {
                 // P6/D7 + 2026-10-06：免 import 安全全局（单位常量 MM / INCH / DEGREE / … 以及
                 // Math / JSON / Number / Infinity / …）从 globalThis 解析，保持裸名发射；否则会被
                 // 写成 `__ctx.Math`（undefined），求值结果静默变错。
                 // 已声明变量优先提升为 __ctx.<name>，使同名遮蔽（如 `let Math = 5`）仍按用户变量解析。
                 if (declared.has(node.name))
                     return `__ctx.${node.name}`;
+                // ctx 键（import 预置 / append 跨文件产出）优先于命名空间——与 emitCall 的
+                // `declared || ctxHas ? __ctx : __ns` 判定同序（约束 2：命名空间绑定不是顶层标识符）。
+                if (this.ctxHas(node.name))
+                    return `__ctx.${node.name}`;
+                if (node.name !== 'contractVersion' && Object.hasOwn(this.namespaces, node.name)) {
+                    return `__ns.${node.name}`;
+                }
                 if (isSafeGlobalIdent(node.name))
                     return node.name;
                 return `__ctx.${node.name}`;
+            }
             case 'CallExpression':
                 return this.emitCall(node, code, declared, lineNo);
             case 'ArrayExpression': {
@@ -1137,6 +1643,12 @@ export class DirectExecutor {
                         parts.push(`...${this.transformArg(prop.argument, code, declared, lineNo)}`);
                         continue;
                     }
+                    if (prop.method === true || (prop.kind && prop.kind !== 'init')) {
+                        // 方法简写 / getter / setter：AST 没有「属性名: 函数值」的对等再现形态，
+                        // 保留原文本片段（内部 ctx/ns 引用仍走 hoistText 提升）。
+                        parts.push(this.hoistText(code.slice(prop.start, prop.end), declared));
+                        continue;
+                    }
                     const key = prop.key?.type === 'Identifier' ? prop.key.name
                         : prop.key?.type === 'Literal' ? JSON.stringify(String(prop.key.value))
                             : null;
@@ -1149,7 +1661,9 @@ export class DirectExecutor {
                 return `{ ${parts.join(', ')} }`;
             }
             case 'UnaryExpression':
-                return `${node.operator}(${this.transformArg(node.argument, code, declared, lineNo)})`;
+                // 外层括号：AST 发射丢弃了源括号，一元运算符紧邻 `**` 左操作数时 JS 要求
+                // 显式括号（`(-a) ** 2` 合法，`-a ** 2` 抛 SyntaxError）。
+                return `(${node.operator}(${this.transformArg(node.argument, code, declared, lineNo)}))`;
             case 'BinaryExpression':
             case 'LogicalExpression':
                 // Parenthesize both operands: the AST emission drops the source's
@@ -1158,24 +1672,85 @@ export class DirectExecutor {
                 return `(${this.transformArg(node.left, code, declared, lineNo)} ${node.operator} ${this.transformArg(node.right, code, declared, lineNo)})`;
             case 'ConditionalExpression':
                 return `(${this.transformArg(node.test, code, declared, lineNo)} ? ${this.transformArg(node.consequent, code, declared, lineNo)} : ${this.transformArg(node.alternate, code, declared, lineNo)})`;
-            case 'MemberExpression':
-                return this.hoistText(code.slice(node.start, node.end), declared);
+            case 'TemplateLiteral': {
+                // AST 重建模板：默认分支的 hoistText 会把模板「文本部分」里的标识符也做词边界
+                // 替换（`n=${n}` 的文本 n 与变量 n 同名 → `__ctx.n=${__ctx.n}`，求值错）。
+                const quasis = node.quasis ?? [];
+                const exprs = node.expressions ?? [];
+                let out = '`';
+                for (let i = 0; i < quasis.length; i++) {
+                    out += quasis[i].value.raw ?? quasis[i].value.cooked ?? '';
+                    if (i < exprs.length)
+                        out += '${' + this.transformArg(exprs[i], code, declared, lineNo) + '}';
+                }
+                return out + '`';
+            }
+            case 'SequenceExpression':
+                // AST 序号表达式丢弃了源括号（node.start 不含 `(`），必须补回，
+                // 否则 `x = (1, 2)` 被发射成 `x = 1, 2` → 只赋 1（两后端不一致）。
+                return `(${(node.expressions ?? [])
+                    .map((e) => this.transformArg(e, code, declared, lineNo))
+                    .join(', ')})`;
+            case 'MemberExpression': {
+                // 可选链保持文本兜底（递归会丢 `?.`）。
+                if (node.optional)
+                    return this.hoistText(code.slice(node.start, node.end), declared);
+                // 递归 object（而非整段 hoistText）：object 可能是命名空间调用（cad.box(…).x）
+                // 或 ctx 成员链。始终给 object 加括号，保证 await/调用/二元结果的成员访问优先级
+                // 正确——`await __ns.cad.box(x).y` 会先取 `.y` 再 await（错），
+                // 必须 `(await __ns.cad.box(x)).y`（约束 2 的链式形态）。
+                const objText = this.transformArg(node.object, code, declared, lineNo);
+                if (node.computed) {
+                    return `(${objText})[${this.transformArg(node.property, code, declared, lineNo)}]`;
+                }
+                return `(${objText}).${node.property.name}`;
+            }
             default:
                 return this.hoistText(code.slice(node.start, node.end), declared);
         }
     }
     /** 文本级自由标识符提升：把已声明变量名 + 当前 ctx 键（import 预置/先前执行产出）
-     *  替换为 __ctx.<name>（词边界）。含 ctx 键 → append 跨文件引用（D6）与模块命名空间
-     *  成员（cfg.OUTX）在实参文本中同样可解析。 */
+     *  替换为 __ctx.<name>（词边界）；命名空间绑定（cad + registerLib 注册库）替换为
+     *  __ns.<binding>（调用形态前置 await），与 hoistBlockText 步骤 ③ 同语义。
+     *
+     *  含 ctx 键 → append 跨文件引用（D6）与模块命名空间成员（cfg.OUTX）在实参文本中
+     *  同样可解析。命名空间分支不可省：该函数服务顶层**值表达式**（数组/对象/成员/条件/
+     *  二元等非调用 RHS）与 transformArg 的 MemberExpression/default 兜底，这些位置不经过
+     *  emitCall，若不在此发射 __ns.<binding>，裸名在 vm 包装（只注入 __ctx/__ns/__isGeom）
+     *  内即是自由标识符 → ReferenceError（`cad is not defined`）；而执行同段文本的
+     *  interpreter 后端靠 env 的 ns 查找能解析，形成两后端差分（约束 2）。 */
     hoistText(text, declared) {
-        let out = text;
         const names = new Set(declared);
         for (const key of Object.keys(this.ctx))
             names.add(key);
-        for (const name of names) {
-            out = out.replace(new RegExp(`\\b${name}\\b`, 'g'), `__ctx.${name}`);
+        // 命名空间绑定（排除 contractVersion / 已声明同名遮蔽 / 已由 import 预置进 ctx 的绑定）
+        const nsNames = Object.keys(this.namespaces).filter((k) => k !== 'contractVersion' && !names.has(k));
+        // 标识符 + 命名空间提升统一走 replaceOutsideProtected（F1）：字符串 / 模板文本 /
+        // 注释区间内的匹配原样保留（修复前实参文本里的 `'carrier'` 会被改写成
+        // `'__ctx.carrier'`，与 hoistBlockText 同根因）。
+        const subs = [];
+        if (names.size > 0) {
+            subs.push({
+                re: new RegExp(`\\b(${[...names].join('|')})\\b`, 'g'),
+                emit: (g) => `__ctx.${g[0]}`,
+            });
         }
-        return out;
+        if (nsNames.length > 0) {
+            const alt = nsNames.join('|');
+            // 调用形态：`cad.box(` → `await __ns.cad.box(`
+            subs.push({
+                re: new RegExp(`(?<![.\\w])\\b(${alt})\\s*\\.\\s*(\\w+)\\s*\\(`, 'g'),
+                emit: (g) => `await __ns.${g[0]}.${g[1]}(`,
+            });
+            // 裸成员访问（非调用）：`cad.foo` → `__ns.cad.foo`（非调用不加 await）
+            subs.push({
+                re: new RegExp(`(?<![.\\w])\\b(${alt})\\s*\\.`, 'g'),
+                emit: (g) => `__ns.${g[0]}.`,
+            });
+        }
+        const out = replaceOutsideProtected(text, subs);
+        // 双前缀修正（与 hoistBlockText 尾部一致）
+        return out.replace(/__ns\.__ns\./g, '__ns.').replace(/await\s+await\s+__ns\./g, 'await __ns.');
     }
     calleeOf(callNode) {
         if (!callNode || callNode.type !== 'CallExpression')