@lowdefy/build 5.5.1 → 6.0.0

package/dist/build/buildRefs/walker.js

@@ -13,7 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import path from 'path';
-import { get, serializer, type } from '@lowdefy/helpers';
+import { get, ReservedKeyError, type } from '@lowdefy/helpers';
 import { ConfigError } from '@lowdefy/errors';
 import { evaluateOperators } from '@lowdefy/operators';
 import makeRefDefinition from './makeRefDefinition.js';
@@ -22,10 +22,12 @@ import getRefContent from './getRefContent.js';
 import getModuleRefContent from './getModuleRefContent.js';
 import runTransformer from './runTransformer.js';
 import getKey from './getKey.js';
-import { scopeMenuItemIds } from '../resolveModuleOperators.js';
+import { scopeMenuItemIds } from './scopeMenuItemIds.js';
 import resolveDepTarget from '../resolveDepTarget.js';
 import setNonEnumerableProperty from '../../utils/setNonEnumerableProperty.js';
+import cloneWithMarkers from './cloneWithMarkers.js';
 import collectExceptions from '../../utils/collectExceptions.js';
+import { createRecord, getPlaceholderId, getRecord, makePlaceholder, makeRecordId, resolveDeferred } from './deferredRegistry.js';
 let WalkContext = class WalkContext {
     child(segment) {
         return new WalkContext({
@@ -40,10 +42,15 @@ let WalkContext = class WalkContext {
             path: this.path ? `${this.path}.${segment}` : segment,
             currentFile: this.currentFile,
             refChain: this.refChain,
+            deferModuleRefs: this.deferModuleRefs,
+            entrySection: this.entrySection,
             operators: this.operators,
             env: this.env,
+            lowdefyApp: this.lowdefyApp,
             dynamicIdentifiers: this.dynamicIdentifiers,
-            shouldStop: this.shouldStop
+            shouldStop: this.shouldStop,
+            entryId: this.entryId,
+            activeRecord: this.activeRecord
         });
     }
     forRef({ refId, vars, filePath, moduleRoot, packageRoot, moduleDependencies, moduleEntry, extraRefChainKeys }) {
@@ -68,10 +75,15 @@ let WalkContext = class WalkContext {
             path: this.path,
             currentFile: filePath ?? this.currentFile,
             refChain: newChain,
+            deferModuleRefs: this.deferModuleRefs,
+            entrySection: this.entrySection,
             operators: this.operators,
             env: this.env,
+            lowdefyApp: this.lowdefyApp,
             dynamicIdentifiers: this.dynamicIdentifiers,
-            shouldStop: this.shouldStop
+            shouldStop: this.shouldStop,
+            entryId: (moduleEntry ?? this.moduleEntry)?.id ?? this.entryId,
+            activeRecord: this.activeRecord
         });
     }
     collectError(error) {
@@ -83,20 +95,34 @@ let WalkContext = class WalkContext {
     get unresolvedRefVars() {
         return this.buildContext.unresolvedRefVars;
     }
-    constructor({ buildContext, refId, sourceRefId, vars, moduleDependencies, moduleEntry, moduleRoot, packageRoot, path, currentFile, refChain, operators, env, dynamicIdentifiers, shouldStop }){
+    constructor({ buildContext, refId, sourceRefId, vars, moduleDependencies, moduleEntry, moduleRoot, packageRoot, path, currentFile, refChain, deferModuleRefs, operators, env, lowdefyApp, dynamicIdentifiers, shouldStop, entryId, entrySection, activeRecord }){
         this.buildContext = buildContext;
         this.refId = refId;
         this.sourceRefId = sourceRefId;
         this.vars = vars;
         this.moduleDependencies = moduleDependencies;
         this.moduleEntry = moduleEntry ?? null;
+        // The owning module entry id for deferred-record coordinates. Set by the
+        // manifest resolvers even before the entry object exists (the local pass
+        // walks the manifest before registration completes).
+        this.entryId = entryId ?? this.moduleEntry?.id ?? null;
+        // The deferred record this walk resolves (null in ordinary walks). Threads
+        // through child() and forRef() unchanged, like refChain — every demand made
+        // anywhere inside a record's resolution attributes to that record in the
+        // wait-graph.
+        this.activeRecord = activeRecord ?? null;
         this.moduleRoot = moduleRoot;
         this.packageRoot = packageRoot;
         this.path = path;
         this.currentFile = currentFile;
         this.refChain = refChain;
+        this.deferModuleRefs = deferModuleRefs ?? false;
+        // Which entry-config section a prepare walk serves ('consumerVars' or
+        // 'connections') — entryRef record coordinates and slots need it.
+        this.entrySection = entrySection ?? null;
         this.operators = operators;
         this.env = env;
+        this.lowdefyApp = lowdefyApp;
         this.dynamicIdentifiers = dynamicIdentifiers;
         this.shouldStop = shouldStop;
     }
@@ -130,62 +156,6 @@ function tagRefDeep(node, refId) {
         }
     }
 }
-// Deep clone preserving non-enumerable build markers (~r, ~l, ~k, ~arr, ~deferredFrom).
-// Used before resolving ref def path/vars to prevent mutation of stored originals.
-function cloneForResolve(value) {
-    if (!type.isObject(value) && !type.isArray(value)) return value;
-    if (type.isArray(value)) {
-        const clone = value.map((item)=>cloneForResolve(item));
-        if (value['~r'] !== undefined) setNonEnumerableProperty(clone, '~r', value['~r']);
-        if (value['~l'] !== undefined) setNonEnumerableProperty(clone, '~l', value['~l']);
-        if (value['~k'] !== undefined) setNonEnumerableProperty(clone, '~k', value['~k']);
-        if (value['~arr'] !== undefined) setNonEnumerableProperty(clone, '~arr', value['~arr']);
-        if (value['~deferredFrom'] !== undefined) setNonEnumerableProperty(clone, '~deferredFrom', value['~deferredFrom']);
-        return clone;
-    }
-    const clone = {};
-    for (const key of Object.keys(value)){
-        clone[key] = cloneForResolve(value[key]);
-    }
-    if (value['~r'] !== undefined) setNonEnumerableProperty(clone, '~r', value['~r']);
-    if (value['~l'] !== undefined) setNonEnumerableProperty(clone, '~l', value['~l']);
-    if (value['~k'] !== undefined) setNonEnumerableProperty(clone, '~k', value['~k']);
-    if (value['~deferredFrom'] !== undefined) setNonEnumerableProperty(clone, '~deferredFrom', value['~deferredFrom']);
-    return clone;
-}
-// Deep clone a var value, preserving markers and setting ~r provenance.
-// When sourceRefId is null, preserves the template's existing ~r markers.
-function cloneVarValue(value, sourceRefId) {
-    if (!type.isObject(value) && !type.isArray(value)) return value;
-    return cloneDeepWithProvenance(value, sourceRefId);
-}
-function cloneDeepWithProvenance(node, sourceRefId) {
-    if (!type.isObject(node) && !type.isArray(node)) return node;
-    if (type.isArray(node)) {
-        const clone = node.map((item)=>cloneDeepWithProvenance(item, sourceRefId));
-        if (node['~r'] !== undefined) {
-            setNonEnumerableProperty(clone, '~r', node['~r']);
-        } else if (sourceRefId) {
-            setNonEnumerableProperty(clone, '~r', sourceRefId);
-        }
-        if (node['~l'] !== undefined) setNonEnumerableProperty(clone, '~l', node['~l']);
-        if (node['~k'] !== undefined) setNonEnumerableProperty(clone, '~k', node['~k']);
-        if (node['~arr'] !== undefined) setNonEnumerableProperty(clone, '~arr', node['~arr']);
-        return clone;
-    }
-    const clone = {};
-    for (const key of Object.keys(node)){
-        clone[key] = cloneDeepWithProvenance(node[key], sourceRefId);
-    }
-    if (node['~r'] !== undefined) {
-        setNonEnumerableProperty(clone, '~r', node['~r']);
-    } else if (sourceRefId) {
-        setNonEnumerableProperty(clone, '~r', sourceRefId);
-    }
-    if (node['~l'] !== undefined) setNonEnumerableProperty(clone, '~l', node['~l']);
-    if (node['~k'] !== undefined) setNonEnumerableProperty(clone, '~k', node['~k']);
-    return clone;
-}
 // Evaluate a _build.* operator using evaluateOperators
 function evaluateBuildOperator(node, ctx) {
     const { output, errors } = evaluateOperators({
@@ -193,6 +163,7 @@ function evaluateBuildOperator(node, ctx) {
         operators: ctx.operators,
         operatorPrefix: '_build.',
         env: ctx.env,
+        lowdefyApp: ctx.lowdefyApp,
         dynamicIdentifiers: ctx.dynamicIdentifiers
     });
     if (errors.length > 0) {
@@ -203,26 +174,46 @@ function evaluateBuildOperator(node, ctx) {
     }
     return output;
 }
+// _var keys are author-written YAML, so a reserved name (e.g. "constructor") is a config
+// mistake, not a missing var. Wraps both call shapes for that check. The object form call
+// site below passes no `options` argument at all, so a missing key comes back from `get` as
+// `undefined` instead of a default — resolveVar relies on that `undefined` to tell "var not
+// provided" apart from "var provided as null".
+function readVar(key, ctx, options) {
+    try {
+        return get(ctx.vars, key, options);
+    } catch (error) {
+        if (!(error instanceof ReservedKeyError)) throw error;
+        throw new ConfigError(`_var key "${key}" is a reserved name.`, {
+            cause: error,
+            filePath: ctx.currentFile
+        });
+    }
+}
 // Resolve a _var node
 function resolveVar(node, ctx) {
     const varDef = node._var;
     // String form: { _var: "key" }
     if (type.isString(varDef)) {
-        const value = get(ctx.vars, varDef, {
+        const value = readVar(varDef, ctx, {
             default: null
         });
-        return cloneVarValue(value, ctx.sourceRefId);
+        return cloneWithMarkers(value, {
+            assignRefId: ctx.sourceRefId
+        });
     }
     // Object form: { _var: { key, default } }
     if (type.isObject(varDef) && type.isString(varDef.key)) {
-        const varFromParent = get(ctx.vars, varDef.key);
+        const varFromParent = readVar(varDef.key, ctx);
         // Var provided (even if null) → use parent's sourceRefId for location
         if (!type.isUndefined(varFromParent)) {
-            return cloneVarValue(varFromParent, ctx.sourceRefId);
+            return cloneWithMarkers(varFromParent, {
+                assignRefId: ctx.sourceRefId
+            });
         }
         // Not provided → use default, preserve template's ~r
         const defaultValue = type.isNone(varDef.default) ? null : varDef.default;
-        return cloneVarValue(defaultValue, null);
+        return cloneWithMarkers(defaultValue);
     }
     throw new ConfigError('_var operator takes a string or object with "key" field as arguments.', {
         filePath: ctx.currentFile
@@ -237,7 +228,9 @@ async function resolveModuleVar(node, ctx) {
         });
     }
     const value = await resolveEffectiveVar(key, ctx.moduleEntry, ctx);
-    return cloneVarValue(value, ctx.sourceRefId);
+    return cloneWithMarkers(value, {
+        assignRefId: ctx.sourceRefId
+    });
 }
 // Navigate the var definitions tree by dot-path key, following `properties` nesting.
 function getVarDef(varDefs, key) {
@@ -258,27 +251,27 @@ function getVarDef(varDefs, key) {
 // at the module manifest. The fresh context prevents false circular-ref detection
 // from the consumer's refChain and ensures _ref paths resolve relative to the
 // module root.
-async function resolveVarDefault(rawDefault, moduleEntry, ctx) {
-    const moduleYamlPath = path.join(moduleEntry.moduleRoot, 'module.lowdefy.yaml');
-    const defaultCtx = new WalkContext({
-        buildContext: ctx.buildContext,
-        refId: moduleEntry.refDef.id,
-        sourceRefId: null,
-        vars: {},
-        moduleDependencies: moduleEntry.moduleDependencies,
-        moduleEntry,
-        moduleRoot: moduleEntry.moduleRoot,
-        packageRoot: moduleEntry.packageRoot,
-        path: '',
-        currentFile: moduleYamlPath,
-        refChain: new Set(moduleEntry.refDef.path ? [
-            moduleEntry.refDef.path
-        ] : []),
-        operators: ctx.operators,
-        env: ctx.env,
-        dynamicIdentifiers: ctx.dynamicIdentifiers
-    });
-    return await resolve(rawDefault, defaultCtx);
+// Deep-force: demand every deferred-record placeholder in a value's subtree
+// and splice the results in place, so cached var values are placeholder-free
+// pure data — no consumer of the var cache needs to know records exist.
+async function deepForcePlaceholders(value, ctx) {
+    const rootId = getPlaceholderId(value);
+    if (rootId !== undefined) {
+        return cloneWithMarkers(await resolveDeferred(ctx, rootId));
+    }
+    if (type.isArray(value)) {
+        for(let i = 0; i < value.length; i++){
+            value[i] = await deepForcePlaceholders(value[i], ctx);
+        }
+        return value;
+    }
+    if (type.isObject(value)) {
+        for (const key of Object.keys(value)){
+            value[key] = await deepForcePlaceholders(value[key], ctx);
+        }
+        return value;
+    }
+    return value;
 }
 // Build a merged object for namespace vars (vars with `properties`). Each
 // declared property resolves through resolveEffectiveVar — consumer values
@@ -291,22 +284,53 @@ async function resolveNamespaceVar(prefix, varDef, moduleEntry, ctx) {
     }
     return result;
 }
+// Read a consumer value by dotted key, forcing any entryRef placeholder on the
+// path: a placeholder at the key or any ancestor resolves through
+// resolveDeferred and is spliced into consumerVars in place, then the read
+// continues. There is no case split on entry state and no structural-snapshot
+// read — a read forces exactly the records its value depends on.
+async function readConsumerValue(moduleEntry, key, ctx) {
+    // Whole-blob deferral: the entire consumerVars value can be a placeholder
+    // (vars: { _ref: { module, component } }) — force it before walking keys.
+    const rootPlaceholderId = getPlaceholderId(moduleEntry.consumerVars);
+    if (rootPlaceholderId !== undefined) {
+        moduleEntry.consumerVars = cloneWithMarkers(await resolveDeferred(ctx, rootPlaceholderId)) ?? {};
+    }
+    const parts = key.split('.');
+    let parent = moduleEntry.consumerVars;
+    for(let i = 0; i < parts.length; i++){
+        if (!type.isObject(parent)) return undefined;
+        let node = parent[parts[i]];
+        const placeholderId = getPlaceholderId(node);
+        if (placeholderId !== undefined) {
+            node = cloneWithMarkers(await resolveDeferred(ctx, placeholderId));
+            parent[parts[i]] = node;
+        }
+        if (i === parts.length - 1) return node;
+        parent = node;
+    }
+    return undefined;
+}
 // Core lazy var resolution with caching on the module entry.
 async function resolveEffectiveVar(key, moduleEntry, ctx) {
     if (Object.hasOwn(moduleEntry.resolvedVarCache, key)) {
         return moduleEntry.resolvedVarCache[key];
     }
-    const consumerValue = get(moduleEntry.consumerVars, key, {
-        default: undefined
-    });
+    const consumerValue = await readConsumerValue(moduleEntry, key, ctx);
     const varDef = getVarDef(moduleEntry.varDefs, key);
     let result;
     if (varDef?.properties) {
         result = await resolveNamespaceVar(key, varDef, moduleEntry, ctx);
     } else if (!type.isNone(consumerValue)) {
-        result = consumerValue;
+        // Deep-force: a consumer value can carry deferred-record placeholders at
+        // any depth — demand each and splice, so the cache holds pure data.
+        result = await deepForcePlaceholders(consumerValue, ctx);
     } else if (varDef && !type.isUndefined(varDef.default)) {
-        result = await resolveVarDefault(varDef.default, moduleEntry, ctx);
+        // Object/array defaults are varDefault records (demand-only — never swept,
+        // a broken default nobody reads must not fail the build); scalar defaults
+        // stay raw in varDefs and need no walk.
+        const defaultRecordId = getPlaceholderId(varDef.default);
+        result = defaultRecordId !== undefined ? await resolveDeferred(ctx, defaultRecordId) : varDef.default;
     } else {
         result = null;
     }
@@ -318,6 +342,8 @@ const MODULE_ID_OPERATOR_KEYS = [
     '_module.pageId',
     '_module.connectionId',
     '_module.endpointId',
+    '_module.agentId',
+    '_module.notificationId',
     '_module.id'
 ];
 function isModuleIdOperator(node) {
@@ -348,16 +374,28 @@ function resolveModulePageId(arg, moduleEntry, context, configKey) {
     });
 }
 // Resolve _module.connectionId
-function resolveModuleConnectionId(arg, moduleEntry, context, configKey) {
+async function resolveModuleConnectionId(arg, moduleEntry, ctx, configKey) {
+    const context = ctx.buildContext;
+    // A connections value can be an entryRef placeholder mid-build — demand it
+    // through the read path and splice, exactly like consumerVars reads. True
+    // remap cycles surface as named wait-graph errors from resolveDeferred.
+    const readRemapValue = async (entry, id)=>{
+        const remapping = entry.connections ?? {};
+        const placeholderId = getPlaceholderId(remapping[id]);
+        if (placeholderId !== undefined) {
+            remapping[id] = cloneWithMarkers(await resolveDeferred(ctx, placeholderId));
+        }
+        return remapping[id];
+    };
     if (type.isString(arg)) {
         if (!moduleEntry) {
             throw new ConfigError('_module.connectionId string form is ambiguous at the app level — no module to scope against. Use { id, module } to specify the target module.', {
                 configKey
             });
         }
-        const remapping = moduleEntry.connections ?? {};
-        if (remapping[arg]) {
-            return remapping[arg];
+        const remapValue = await readRemapValue(moduleEntry, arg);
+        if (remapValue) {
+            return remapValue;
         }
         return `${moduleEntry.id}/${arg}`;
     }
@@ -369,9 +407,9 @@ function resolveModuleConnectionId(arg, moduleEntry, context, configKey) {
             configKey,
             usage: `_module.connectionId { id: "${arg.id}", module: "${arg.module}" }`
         });
-        const targetRemapping = targetEntry.connections ?? {};
-        if (targetRemapping[arg.id]) {
-            return targetRemapping[arg.id];
+        const remapValue = await readRemapValue(targetEntry, arg.id);
+        if (remapValue) {
+            return remapValue;
         }
         return `${targetEntry.id}/${arg.id}`;
     }
@@ -403,6 +441,54 @@ function resolveModuleEndpointId(arg, moduleEntry, context, configKey) {
         configKey
     });
 }
+// Resolve _module.agentId
+function resolveModuleAgentId(arg, moduleEntry, context, configKey) {
+    if (type.isString(arg)) {
+        if (!moduleEntry) {
+            throw new ConfigError('_module.agentId string form is ambiguous at the app level — no module to scope against. Use { id, module } to specify the target module.', {
+                configKey
+            });
+        }
+        return `${moduleEntry.id}/${arg}`;
+    }
+    if (type.isObject(arg) && type.isString(arg.id) && type.isString(arg.module)) {
+        const targetEntry = resolveDepTarget({
+            moduleEntry,
+            depName: arg.module,
+            context,
+            configKey,
+            usage: `_module.agentId { id: "${arg.id}", module: "${arg.module}" }`
+        });
+        return `${targetEntry.id}/${arg.id}`;
+    }
+    throw new ConfigError('_module.agentId requires a string or object { id, module }.', {
+        configKey
+    });
+}
+// Resolve _module.notificationId
+function resolveModuleNotificationId(arg, moduleEntry, context, configKey) {
+    if (type.isString(arg)) {
+        if (!moduleEntry) {
+            throw new ConfigError('_module.notificationId string form is ambiguous at the app level — no module to scope against. Use { id, module } to specify the target module.', {
+                configKey
+            });
+        }
+        return `${moduleEntry.id}/${arg}`;
+    }
+    if (type.isObject(arg) && type.isString(arg.id) && type.isString(arg.module)) {
+        const targetEntry = resolveDepTarget({
+            moduleEntry,
+            depName: arg.module,
+            context,
+            configKey,
+            usage: `_module.notificationId { id: "${arg.id}", module: "${arg.module}" }`
+        });
+        return `${targetEntry.id}/${arg.id}`;
+    }
+    throw new ConfigError('_module.notificationId requires a string or object { id, module }.', {
+        configKey
+    });
+}
 // Resolve _module.id
 function resolveModuleId(arg, moduleEntry, context, configKey) {
     if (!type.isObject(arg)) {
@@ -428,7 +514,7 @@ function resolveModuleId(arg, moduleEntry, context, configKey) {
     });
 }
 // Dispatch _module.*Id operators
-function resolveModuleIdOperator(node, ctx) {
+async function resolveModuleIdOperator(node, ctx) {
     const { moduleEntry } = ctx;
     const context = ctx.buildContext;
     const configKey = node['~k'];
@@ -436,18 +522,61 @@ function resolveModuleIdOperator(node, ctx) {
         return resolveModulePageId(node['_module.pageId'], moduleEntry, context, configKey);
     }
     if (!type.isUndefined(node['_module.connectionId'])) {
-        return resolveModuleConnectionId(node['_module.connectionId'], moduleEntry, context, configKey);
+        const connectionArg = node['_module.connectionId'];
+        // Prepare (deferModuleRefs) must not resolve the object form: it reads the
+        // TARGET entry's remap table, which may not be prepared yet — an eager read
+        // would see a raw ref instead of a demandable placeholder. It becomes a
+        // connRemap record; demand resolves it once every entry is prepared, so
+        // chained remaps force each other value-granularly and true remap cycles
+        // surface as named wait-graph errors.
+        if (ctx.deferModuleRefs && type.isObject(connectionArg)) {
+            const nested = ctx.path.split('.').includes('$refvars');
+            const section = ctx.entrySection ?? 'connections';
+            const recordId = makeRecordId({
+                entryId: ctx.entryId,
+                configPath: ctx.path ? `${section}.${ctx.path}` : section
+            });
+            createRecord(ctx.buildContext, {
+                id: recordId,
+                kind: 'connRemap',
+                body: node,
+                env: {
+                    file: ctx.currentFile,
+                    moduleRoot: null,
+                    packageRoot: null,
+                    entryId: null,
+                    refId: ctx.refId,
+                    configKey: configKey ?? null
+                },
+                slot: nested ? null : {
+                    entryId: ctx.entryId,
+                    section,
+                    path: ctx.path
+                }
+            });
+            return makePlaceholder(recordId);
+        }
+        return resolveModuleConnectionId(connectionArg, moduleEntry, ctx, configKey);
     }
     if (!type.isUndefined(node['_module.endpointId'])) {
         return resolveModuleEndpointId(node['_module.endpointId'], moduleEntry, context, configKey);
     }
+    if (!type.isUndefined(node['_module.agentId'])) {
+        return resolveModuleAgentId(node['_module.agentId'], moduleEntry, context, configKey);
+    }
+    if (!type.isUndefined(node['_module.notificationId'])) {
+        return resolveModuleNotificationId(node['_module.notificationId'], moduleEntry, context, configKey);
+    }
     if (!type.isUndefined(node['_module.id'])) {
         return resolveModuleId(node['_module.id'], moduleEntry, context, configKey);
     }
     return node;
 }
-// Resolve a _ref node (16-step ref handling)
-async function resolveRef(node, ctx) {
+// Steps 1–7: scope-dependent prepare — resolves path/vars/key, normalises module
+// paths, updates refMap, and checks for package-root escapes and circular refs.
+// Returns the fully-resolved refDef; all side-effects (unresolvedRefVars, refMap)
+// happen here. No file I/O is performed.
+async function prepareRef(node, ctx) {
     // 1. Create ref definition
     const lineNumber = node['~l'];
     const refDef = makeRefDefinition(node._ref, ctx.refId, ctx.refMap, lineNumber, ctx.path);
@@ -456,19 +585,32 @@ async function resolveRef(node, ctx) {
     const varKeys = Object.keys(refDef.vars);
     if (varKeys.length > 0) {
         ctx.unresolvedRefVars[refDef.id] = refDef.vars;
-        refDef.vars = cloneForResolve(refDef.vars);
+        refDef.vars = cloneWithMarkers(refDef.vars);
     }
     // 3. Resolve dynamic path/vars/key
     if (type.isObject(refDef.path)) {
-        refDef.path = await resolve(cloneForResolve(refDef.path), ctx);
+        refDef.path = await resolve(cloneWithMarkers(refDef.path), ctx);
+    }
+    if (type.isObject(refDef.vars) && !type.isUndefined(refDef.vars._ref)) {
+        // A _ref at the root of vars resolves to the whole vars object
+        // (vars: { _ref: config.yaml }).
+        const varCtx = ctx.deferModuleRefs && refDef.module ? ctx.child('$refvars') : ctx;
+        refDef.vars = await resolve(refDef.vars, varCtx) ?? {};
+    } else {
+        await Promise.all(varKeys.map(async (varKey)=>{
+            if (type.isObject(refDef.vars[varKey]) || type.isArray(refDef.vars[varKey])) {
+                // Under prepare (deferModuleRefs), nested module refs inside this ref's
+                // vars become entryRef records too. Extend the path with a reserved
+                // segment so their coordinates are unique (distinct from this ref's own
+                // record) and recognizably nested (slot: null — their placeholder lives
+                // in the prepared body, not in consumerVars).
+                const varCtx = ctx.deferModuleRefs && refDef.module ? ctx.child('$refvars').child(varKey) : ctx;
+                refDef.vars[varKey] = await resolve(refDef.vars[varKey], varCtx);
+            }
+        }));
     }
-    await Promise.all(varKeys.map(async (varKey)=>{
-        if (type.isObject(refDef.vars[varKey]) || type.isArray(refDef.vars[varKey])) {
-            refDef.vars[varKey] = await resolve(refDef.vars[varKey], ctx);
-        }
-    }));
     if (type.isObject(refDef.key)) {
-        refDef.key = await resolve(cloneForResolve(refDef.key), ctx);
+        refDef.key = await resolve(cloneWithMarkers(refDef.key), ctx);
     }
     // 4. Module path resolution: resolve relative paths from the module root
     rebaseModuleRefPaths({
@@ -504,113 +646,133 @@ async function resolveRef(node, ctx) {
             lineNumber: ctx.currentFile ? lineNumber : null
         });
     }
-    // Steps 8-16: File operations that can fail independently per ref.
-    // Errors are collected so the walker can continue processing sibling refs,
-    // allowing multiple errors to be reported at once.
+    return refDef;
+}
+// Steps 8–12, module flavor: content lookup, cross-module cycle key, module
+// child context, consumer-var forwarding into file-ref bodies, walk under the
+// module context, menu item scoping. Returns the walked content; loadAndWalkRef
+// applies the shared tail (steps 13–16). Replayed deferred sentinels route here
+// too — `fromFile` carries their original provenance.
+async function resolveModuleExportRef(refDef, ctx, { configKey, fromFile }) {
+    // 8. Load content. Components and menus dereference a deferred record and
+    // clone its immutable body — the record env names the source file
+    // explicitly. Legacy live content (scalar bodies, sections produced inline
+    // by static operators) resolves against the manifest file.
+    const result = await getModuleRefContent({
+        context: ctx.buildContext,
+        refDef,
+        referencedFrom: fromFile,
+        walkCtx: ctx,
+        configKey
+    });
+    const resolvedEntryId = result.entryId;
+    const moduleEntry = ctx.buildContext.modules[resolvedEntryId];
+    let content;
+    let sourceFile;
+    if (result.recordId !== undefined) {
+        const record = getRecord(ctx.buildContext, result.recordId);
+        content = cloneWithMarkers(record.body);
+        sourceFile = record.env.file;
+    } else {
+        content = cloneWithMarkers(result.content);
+        sourceFile = path.join(moduleEntry.moduleRoot, 'module.lowdefy.yaml');
+    }
+    // 9. Circular detection for cross-module component/menu refs.
+    // File-based cycle detection (prepareRef step 7) misses these because each
+    // module has a different file path. Use a synthetic key with the resolved
+    // concrete entry ID: "module:<entryId>/<type>:<name>".
+    const exportType = refDef.component ? 'component' : 'menu';
+    const exportName = refDef.component ?? refDef.menu;
+    const cycleKey = `module:${resolvedEntryId}/${exportType}:${exportName}`;
+    if (ctx.refChain.has(cycleKey)) {
+        const chainDisplay = [
+            ...ctx.refChain,
+            cycleKey
+        ].join('\n  -> ');
+        throw new ConfigError(`Circular module reference detected. Module "${resolvedEntryId}" ${exportType} "${exportName}" ` + `references itself through:\n  -> ${chainDisplay}`, {
+            filePath: fromFile
+        });
+    }
+    // 10. Create module child context for the ref
+    const childCtx = ctx.forRef({
+        refId: refDef.id,
+        vars: refDef.vars,
+        filePath: sourceFile,
+        moduleRoot: moduleEntry.moduleRoot,
+        packageRoot: moduleEntry.packageRoot,
+        moduleDependencies: moduleEntry.moduleDependencies,
+        moduleEntry,
+        extraRefChainKeys: [
+            cycleKey
+        ]
+    });
+    // When component/menu content is a file _ref, the inner ref would create
+    // a fresh var scope and lose the consumer's vars. Inject them into the clone.
+    if (type.isObject(content) && content._ref) {
+        if (type.isObject(content._ref)) {
+            content._ref.vars = {
+                ...content._ref.vars ?? {},
+                ...refDef.vars
+            };
+        } else if (type.isString(content._ref) && Object.keys(refDef.vars).length > 0) {
+            content._ref = {
+                path: content._ref,
+                vars: refDef.vars
+            };
+        }
+    }
+    // 11. Walk the content
+    content = await resolve(content, childCtx);
+    // 12. Scope menu item IDs (menu refs only)
+    if (refDef.menu) {
+        scopeMenuItemIds(content, moduleEntry.id);
+    }
+    return content;
+}
+// Steps 8–16: load content, build child context, walk, transform, tag.
+// Module refs take steps 8–12 in resolveModuleExportRef; both paths share the
+// tail (steps 13–16). `referencedFrom` overrides ctx.currentFile for provenance
+// (used when replaying a deferred sentinel whose origin file differs from the
+// stage-2 ctx.currentFile).
+async function loadAndWalkRef(refDef, ctx, { configKey, referencedFrom } = {}) {
+    const fromFile = referencedFrom ?? ctx.currentFile;
+    // Errors here are collected (not thrown) so the walker can continue
+    // processing sibling refs and report multiple errors at once.
     try {
-        // 8. Load content
         let content;
-        let resolvedEntryId = null;
         if (refDef.module) {
-            const result = await getModuleRefContent({
-                context: ctx.buildContext,
-                refDef,
-                referencedFrom: ctx.currentFile,
-                walkCtx: ctx,
-                configKey: node['~k']
+            content = await resolveModuleExportRef(refDef, ctx, {
+                configKey,
+                fromFile
             });
-            content = cloneForResolve(result.content);
-            resolvedEntryId = result.entryId;
         } else {
+            // 8. Load content
             content = await getRefContent({
                 context: ctx.buildContext,
                 refDef,
-                referencedFrom: ctx.currentFile
+                referencedFrom: fromFile
             });
-        }
-        // 9. Circular detection for cross-module component/menu refs.
-        // File-based cycle detection (step 7) misses these because each module
-        // has a different file path. Use a synthetic key with the resolved
-        // concrete entry ID: "module:<entryId>/<type>:<name>".
-        if (resolvedEntryId && (refDef.component || refDef.menu)) {
-            const exportType = refDef.component ? 'component' : 'menu';
-            const exportName = refDef.component ?? refDef.menu;
-            const cycleKey = `module:${resolvedEntryId}/${exportType}:${exportName}`;
-            if (ctx.refChain.has(cycleKey)) {
-                const chainDisplay = [
-                    ...ctx.refChain,
-                    cycleKey
-                ].join('\n  -> ');
-                throw new ConfigError(`Circular module reference detected. Module "${resolvedEntryId}" ${exportType} "${exportName}" ` + `references itself through:\n  -> ${chainDisplay}`, {
-                    filePath: ctx.currentFile
-                });
-            }
-        }
-        // 10. Create child context for the ref
-        let childCtx;
-        if (refDef.module && (refDef.component || refDef.menu)) {
-            const moduleEntry = ctx.buildContext.modules[resolvedEntryId];
-            const deferredFrom = content['~deferredFrom'];
-            const exportType = refDef.component ? 'component' : 'menu';
-            const exportName = refDef.component ?? refDef.menu;
-            const cycleKey = `module:${resolvedEntryId}/${exportType}:${exportName}`;
-            childCtx = ctx.forRef({
-                refId: refDef.id,
-                vars: refDef.vars,
-                filePath: deferredFrom ?? path.join(moduleEntry.moduleRoot, 'module.lowdefy.yaml'),
-                moduleRoot: moduleEntry.moduleRoot,
-                packageRoot: moduleEntry.packageRoot,
-                moduleDependencies: moduleEntry.moduleDependencies,
-                moduleEntry,
-                extraRefChainKeys: [
-                    cycleKey
-                ]
-            });
-            // Clone so each consumer gets an independent copy — getModuleRefContent
-            // returns a shared reference, and resolve() mutates in place.
-            // deferredFrom was read above before the clone (serializer.copy strips
-            // non-enumerable properties).
-            content = serializer.copy(content);
-            // When component/menu content is a file _ref, the inner ref would create
-            // a fresh var scope and lose the consumer's vars. Inject them into the clone.
-            if ((refDef.component || refDef.menu) && type.isObject(content) && content._ref) {
-                if (type.isObject(content._ref)) {
-                    content._ref.vars = {
-                        ...content._ref.vars ?? {},
-                        ...refDef.vars
-                    };
-                } else if (type.isString(content._ref) && Object.keys(refDef.vars).length > 0) {
-                    content._ref = {
-                        path: content._ref,
-                        vars: refDef.vars
-                    };
-                }
-            }
-        } else {
-            childCtx = ctx.forRef({
+            // 10. Create child context for the ref
+            const childCtx = ctx.forRef({
                 refId: refDef.id,
                 vars: refDef.vars,
                 filePath: refDef.path
             });
-        }
-        // 11. Walk the content
-        content = await resolve(content, childCtx);
-        // 12. Scope menu item IDs (module menu refs only)
-        if (refDef.module && refDef.menu) {
-            const moduleEntry = ctx.buildContext.modules[resolvedEntryId];
-            scopeMenuItemIds(content, moduleEntry.id);
+            // 11. Walk the content
+            content = await resolve(content, childCtx);
         }
         // 13. Run transformer
         content = await runTransformer({
             context: ctx.buildContext,
             input: content,
             refDef,
-            referencedFrom: ctx.currentFile
+            referencedFrom: fromFile
         });
         // 14. Extract key
         content = getKey({
             input: content,
-            refDef
+            refDef,
+            filePath: fromFile
         });
         // 15. Tag all nodes with ~r for provenance
         tagRefDeep(content, refDef.id);
@@ -635,22 +797,81 @@ async function resolveRef(node, ctx) {
         throw error;
     }
 }
+// Resolve a _ref node: prepare (steps 1–7), then optionally defer module refs
+// as sentinels (when ctx.deferModuleRefs is true), otherwise load-and-walk (steps 8–16).
+async function resolveRef(node, ctx) {
+    const refDef = await prepareRef(node, ctx);
+    if (ctx.deferModuleRefs && refDef.module) {
+        // Prepare-time deferral: the refDef's dynamic parts are already resolved
+        // in the enclosing scope (steps 1-7); only the content pull defers. The
+        // prepared refDef becomes an entryRef record and the tree gets a
+        // placeholder. Records created inside another prepared ref's vars
+        // ($refvars segment) have no consumerVars slot — their placeholder lives
+        // in the parent body and is spliced by the walk that encounters it.
+        const nested = ctx.path.split('.').includes('$refvars');
+        const section = ctx.entrySection ?? 'consumerVars';
+        const id = makeRecordId({
+            entryId: ctx.entryId,
+            // ctx.path is '' when the whole section value is the ref (whole-blob).
+            configPath: ctx.path ? `${section}.${ctx.path}` : section
+        });
+        createRecord(ctx.buildContext, {
+            id,
+            kind: 'entryRef',
+            body: refDef,
+            env: {
+                // entryRef resolution runs at app level: no module scope; provenance
+                // is the file the ref was written in (replaces ~deferredFrom).
+                file: ctx.currentFile,
+                moduleRoot: null,
+                packageRoot: null,
+                entryId: null,
+                refId: ctx.refId,
+                configKey: node['~k'] ?? null
+            },
+            slot: nested ? null : {
+                entryId: ctx.entryId,
+                section,
+                path: ctx.path
+            }
+        });
+        return makePlaceholder(id);
+    }
+    return loadAndWalkRef(refDef, ctx, {
+        configKey: node['~k']
+    });
+}
 // Core walk function — single-pass async tree walker
 async function resolve(node, ctx) {
     // 1. Primitives pass through
     if (!type.isObject(node) && !type.isArray(node)) return node;
-    // 2. _ref — top-down (only operator that needs it)
+    // 2. Deferred-record placeholder — kind-aware dispatch. Per-consumer kinds
+    // (component, menuLinks) pass through every generic walk untouched; only
+    // module-ref consumption dereferences them. Single-value kinds (entryRef,
+    // varDefault) force the record and splice a clone in place — the memoized
+    // value is shared across demanders, and the tree gets mutated downstream.
+    if (type.isObject(node)) {
+        const deferredId = getPlaceholderId(node);
+        if (deferredId !== undefined) {
+            const record = getRecord(ctx.buildContext, deferredId);
+            if (record.kind === 'component' || record.kind === 'menuLinks') {
+                return node;
+            }
+            return cloneWithMarkers(await resolveDeferred(ctx, deferredId));
+        }
+    }
+    // 3. _ref — top-down (only operator that needs it)
     if (type.isObject(node) && !type.isUndefined(node._ref)) {
         return resolveRef(node, ctx);
     }
-    // 3. Array — walk children in parallel
+    // 4. Array — walk children in parallel
     if (type.isArray(node)) {
         await Promise.all(node.map(async (item, i)=>{
             node[i] = await resolve(item, ctx.child(String(i)));
         }));
         return node;
     }
-    // 4. Object — walk children in parallel (with shouldStop)
+    // 5. Object — walk children in parallel (with shouldStop)
     const keys = Object.keys(node);
     await Promise.all(keys.map(async (key)=>{
         if (ctx.shouldStop) {
@@ -660,16 +881,49 @@ async function resolve(node, ctx) {
                 delete node[key];
                 return;
             }
-            if (stopMode === 'preserve') {
-                if (type.isObject(node[key]) || type.isArray(node[key])) {
-                    setNonEnumerableProperty(node[key], '~deferredFrom', ctx.currentFile);
-                }
+            if (stopMode === 'skip' || stopMode === 'preserve') {
+                // Leave raw — a later phase or consumer handles this region.
+                // 'preserve' is a legacy synonym: the ~deferredFrom marker it used
+                // to stamp is gone (records carry the source file in env.file).
+                return;
+            }
+            if (type.isString(stopMode) && stopMode.startsWith('record:')) {
+                // Record-ify: move the raw body into the registry and splice in the
+                // placeholder. The body stays untagged, exactly like an in-place
+                // preserved body: manifest walks call resolve() directly (no step 15),
+                // so consumer provenance is applied at consumption time by
+                // loadAndWalkRef's tagRefDeep over the cloned body.
+                const body = node[key];
+                // Scalars stay in the tree (mirrors 'preserve', which cannot stamp
+                // them); a placeholder means the region was already record-ified by
+                // an earlier pass — do not create a duplicate.
+                if (!type.isObject(body) && !type.isArray(body)) return;
+                if (getPlaceholderId(body) !== undefined) return;
+                const kind = stopMode.slice('record:'.length);
+                const entryId = ctx.entryId;
+                const id = makeRecordId({
+                    entryId,
+                    configPath: childPath
+                });
+                createRecord(ctx.buildContext, {
+                    id,
+                    kind,
+                    body,
+                    env: {
+                        file: ctx.currentFile,
+                        moduleRoot: ctx.moduleRoot ?? null,
+                        packageRoot: ctx.packageRoot ?? null,
+                        entryId,
+                        refId: ctx.refId
+                    }
+                });
+                node[key] = makePlaceholder(id);
                 return;
             }
         }
         node[key] = await resolve(node[key], ctx.child(key));
     }));
-    // 5. _var — substitution (children already resolved)
+    // 6. _var — substitution (children already resolved)
     if (!type.isUndefined(node._var)) {
         try {
             const varResult = resolveVar(node, ctx);
@@ -682,24 +936,51 @@ async function resolve(node, ctx) {
             throw error;
         }
     }
-    // 6. _module.var — module variable substitution
+    // 7. _module.var — module variable substitution
     if (!type.isUndefined(node['_module.var'])) {
         if (!ctx.moduleEntry) {
-            if (ctx.moduleRoot) return node;
+            if (ctx.moduleRoot) {
+                // Module scope without an entry = the header parse or the exportables
+                // pass. Those walk module-static structure only: a _module.var here
+                // would make manifest headers or export ids vary per consumer, which
+                // makes by-name lookup order-dependent.
+                throw new ConfigError('_module.var cannot be used in manifest headers or component/menu ids — ' + 'these are module-static. Move it inside a component body, page, or api section.', {
+                    filePath: ctx.currentFile
+                });
+            }
             throw new ConfigError('_module.var cannot be used at the app level.');
         }
         return resolve(await resolveModuleVar(node, ctx), ctx);
     }
-    // 7. _module.*Id — resolve to scoped ID string
+    // 8. _module.*Id — resolve to scoped ID string
     if (isModuleIdOperator(node)) {
         return resolveModuleIdOperator(node, ctx);
     }
-    // 8. _build.* operator
+    // 9. _build.* operator
     if (isBuildOperator(node)) {
+        // Under prepare (deferModuleRefs), an operand subtree can hold a deferred
+        // placeholder where a module ref used to be — the operator cannot fold
+        // over it. Leave the node unevaluated: the finalize/demand walk (deferral
+        // off) splices concrete values via the placeholder dispatch before this
+        // branch runs, and the fold happens then, in the same enclosing scope.
+        if (ctx.deferModuleRefs && findPlaceholderInSubtree(node)) {
+            return node;
+        }
         const result = evaluateBuildOperator(node, ctx);
         tagRefDeep(result, ctx.refId);
         return result;
     }
     return node;
 }
-export { resolve, WalkContext, cloneForResolve, tagRefDeep };
+// Does any node in the subtree carry a deferred-record placeholder?
+function findPlaceholderInSubtree(node) {
+    if (getPlaceholderId(node) !== undefined) return true;
+    if (type.isArray(node)) {
+        return node.some((item)=>findPlaceholderInSubtree(item));
+    }
+    if (type.isObject(node)) {
+        return Object.keys(node).some((key)=>findPlaceholderInSubtree(node[key]));
+    }
+    return false;
+}
+export { resolve, loadAndWalkRef, WalkContext, tagRefDeep };