@almadar/runtime 6.71.0 → 6.72.0

package/dist/{chunk-PAEMYGKV.js → chunk-A474B57C.js}

@@ -1,12 +1,12 @@
 import { parseCron, cronMinuteKey, cronMatches } from './chunk-OU3ITB5S.js';
-import { createContextFromBindings, interpolateValue, deferEntityBindings } from './chunk-ZJ62H3ES.js';
+import { createContextFromBindings, interpolateValue, deferEntityBindings } from './chunk-ZWAOJT6R.js';
 import { seedRandom, randomArrayElement, randomInt, shuffleArray, randomPastDate } from './chunk-T4VDAB4C.js';
 import { collectTraitRefsFromValue, collectTraitRefsFromEffects } from './chunk-SCRAHWOC.js';
 import { createLogger, setNamespaceLevel } from '@almadar/logger';
 import { evaluateGuard, SExpressionEvaluator } from '@almadar/evaluator';
-import { OrbitalSchemaSchema, isInlineTrait, isEntityCall, isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef, isReferenceConfigType, configRefEventKnob, normalizeCallSiteConfigToValues, resolveConfigRefEventName, eventListPropsOf } from '@almadar/core';
+import { OrbitalSchemaSchema, isInlineTrait, isEntityCall, isEntityReference, parseEntityRef, parseImportedTraitRef, isPageReference, isPageReferenceString, isPageReferenceObject, parsePageRef, parseOrbitalRef, overrideDeclaredKnobs, asTraitId, asEntityId, asPageId, asOrbitalId, deriveId, isReferenceConfigType, configRefEventKnob, normalizeCallSiteConfigToValues, resolveConfigRefEventName, isCallSiteConfigDeclaration, idPrefix, eventListPropsOf } from '@almadar/core';
 export { normalizeCallSiteConfigToValues } from '@almadar/core';
-import { sampleRowCount, sampleRow } from '@almadar/core/mock';
+import { sampleRowCount, sampleRow, identityEntitiesOf, roleVocabularyOf } from '@almadar/core/mock';
 
 var log = createLogger("almadar:runtime:eventbus");
 var EventBus = class {
@@ -324,6 +324,7 @@ function isValidDurationString(interval) {
   return /^(\d+)(ms|s|m|h)?$/.test(interval);
 }
 var smLog = createLogger("almadar:runtime:sm");
+var LIFECYCLE_EVENTS = ["INIT", "LOAD", "$MOUNT"];
 function findInitialState(trait) {
   if (!trait.states || trait.states.length === 0) {
     smLog.warn("trait-has-no-states", { trait: trait.name });
@@ -1197,13 +1198,23 @@ var EffectExecutor = class _EffectExecutor {
       const isCompound = operator === "do" || operator === "when" || operator === "let" || operator === "if";
       const resolvedArgs = isCompound ? rawArgs : resolveArgs(rawArgs, this.bindings, this.strictBindings, this.contextExtensions);
       try {
-        await this.dispatch(operator, resolvedArgs);
-        results.push({
-          type: operator,
-          args: resolvedArgs,
-          status: "executed",
-          durationMs: Date.now() - start
-        });
+        const outcome = await this.dispatch(operator, resolvedArgs);
+        if (outcome?.failed) {
+          results.push({
+            type: operator,
+            args: resolvedArgs,
+            status: "failed",
+            error: outcome.error,
+            durationMs: Date.now() - start
+          });
+        } else {
+          results.push({
+            type: operator,
+            args: resolvedArgs,
+            status: "executed",
+            durationMs: Date.now() - start
+          });
+        }
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         results.push({
@@ -1260,10 +1271,10 @@ var EffectExecutor = class _EffectExecutor {
       this.handlers.emit(eventName, payload, this.sourceStamp(), fromPersistSuccess);
     }
   }
-  emitFailure(emit, err) {
+  emitFailure(emit, err, extra) {
     if (!emit?.failure) return;
     const error = err instanceof Error ? err.message : String(err);
-    this.handlers.emit(emit.failure, { error }, this.sourceStamp());
+    this.handlers.emit(emit.failure, { ...extra, error }, this.sourceStamp());
   }
   /**
    * Narrow the generic emit config into the `os/watch-*` handler surface
@@ -1310,6 +1321,14 @@ var EffectExecutor = class _EffectExecutor {
   // ==========================================================================
   // Effect Dispatch
   // ==========================================================================
+  /**
+   * Dispatches one effect. Returns `void` for the ordinary case (the
+   * caller only cares whether it threw). A `persist` that resolves
+   * without throwing — the store DENIED the write, signalled by return
+   * value rather than an exception, per the "close the circuit" doctrine
+   * — reports that outcome here so `executeWithResults` can record it as
+   * `status: 'failed'` instead of the default `'executed'`.
+   */
   async dispatch(operator, args) {
     switch (operator) {
       // === Universal Effects ===
@@ -1383,6 +1402,15 @@ var EffectExecutor = class _EffectExecutor {
           success: emitCfg?.success,
           failure: emitCfg?.failure
         });
+        if (this.handlers.persistDelegated === true) {
+          persistLog.debug("persist:delegated", {
+            action,
+            entityType: action === "batch" ? "batch" : args[1],
+            traitName: this.context.traitName,
+            transition: this.context.transition
+          });
+          return;
+        }
         try {
           if (action === "batch") {
             const operations = args[1];
@@ -1406,16 +1434,38 @@ var EffectExecutor = class _EffectExecutor {
             const entityType = args[1];
             const data = args[2];
             const persisted = await this.handlers.persist(action, entityType, data);
-            const successPayload = persisted ?? data;
-            const dataId = typeof successPayload === "string" ? successPayload : successPayload && typeof successPayload === "object" ? successPayload.id : void 0;
-            persistLog.debug("persist:success", {
-              action,
-              entityType,
-              dataId,
-              willEmit: emitCfg?.success
-            });
-            this.emitSuccess(emitCfg, "success", successPayload, true);
-            persistLog.debug("persist:emit-fired", { action, eventName: emitCfg?.success });
+            if (persisted === void 0) {
+              const attemptedId = typeof data === "string" ? data : data && typeof data === "object" ? data.id : void 0;
+              persistLog.error("persist:denied", { action, entityType, attemptedId });
+              const deniedError = `persist ${action} ${entityType} was denied or failed`;
+              this.emitFailure(
+                emitCfg,
+                new Error(deniedError),
+                { entityType, id: attemptedId }
+              );
+              return { failed: true, error: deniedError };
+            } else {
+              const dataId = typeof persisted === "string" ? persisted : persisted.id;
+              persistLog.debug("persist:success", {
+                action,
+                entityType,
+                dataId,
+                willEmit: emitCfg?.success
+              });
+              if (action === "create" && this.bindings.entity && typeof dataId === "string") {
+                const boundId = this.bindings.entity.id;
+                const submittedId = data && typeof data === "object" ? data.id : void 0;
+                if (boundId === void 0 || boundId === submittedId) {
+                  this.bindings.entity.id = dataId;
+                  persistLog.debug("persist:create-bound-id", {
+                    entityType,
+                    id: dataId
+                  });
+                }
+              }
+              this.emitSuccess(emitCfg, "success", persisted, true);
+              persistLog.debug("persist:emit-fired", { action, eventName: emitCfg?.success });
+            }
           }
         } catch (err) {
           persistLog.error("persist:error", {
@@ -1450,8 +1500,16 @@ var EffectExecutor = class _EffectExecutor {
           const emitCfg = this.extractEmitConfig(rawOpt);
           try {
             const result = await this.handlers.fetch(entityType, options);
-            const payload = result ? { data: result.rows, totalCount: result.total } : { data: null, totalCount: 0 };
-            this.emitSuccess(emitCfg, "success", payload);
+            if (result === null) {
+              if (options?.id !== void 0) {
+                this.emitFailure(emitCfg, new Error(`${entityType} ${options.id} not found`));
+              } else {
+                this.emitSuccess(emitCfg, "success", { data: [], totalCount: 0 });
+              }
+            } else {
+              const payload = { data: result.rows, totalCount: result.total };
+              this.emitSuccess(emitCfg, "success", payload);
+            }
           } catch (err) {
             this.emitFailure(emitCfg, err);
             throw err;
@@ -2642,7 +2700,11 @@ var MockPersistenceAdapter = class _MockPersistenceAdapter {
   async create(entityType, data) {
     const store = this.getStore(entityType);
     this.assertFileValuesWithinCeiling(entityType, data);
-    const id = this.nextId(entityType);
+    const suppliedId = typeof data.id === "string" && data.id.length > 0 ? data.id : void 0;
+    if (suppliedId && store.has(suppliedId)) {
+      throw new Error(`Entity ${entityType} with id ${suppliedId} already exists`);
+    }
+    const id = suppliedId ?? this.nextId(entityType);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const withDefaults = this.applyFieldDefaults(entityType, data);
     const item = {
@@ -2904,6 +2966,7 @@ var HttpLoader = class {
       data: {
         orbital,
         orbitals: schema.orbitals,
+        ...schema.config ? { schemaConfig: schema.config } : {},
         sourcePath: schemaResult.data.sourcePath,
         importPath
       }
@@ -3113,7 +3176,7 @@ async function getExternalLoaderModule() {
     return null;
   }
   try {
-    externalLoaderModule = await import('./external-loader-YUUADLAP.js');
+    externalLoaderModule = await import('./external-loader-CISUEINQ.js');
     return externalLoaderModule;
   } catch {
     return null;
@@ -3287,6 +3350,7 @@ var UnifiedLoader = class {
         data: {
           orbital: found,
           orbitals: schema.orbitals,
+          ...schema.config ? { schemaConfig: schema.config } : {},
           sourcePath: schemaResult.data.sourcePath,
           importPath
         }
@@ -3303,6 +3367,7 @@ var UnifiedLoader = class {
       data: {
         orbital: schema.orbitals[0],
         orbitals: schema.orbitals,
+        ...schema.config ? { schemaConfig: schema.config } : {},
         sourcePath: schemaResult.data.sourcePath,
         importPath
       }
@@ -3637,6 +3702,205 @@ function spliceLambdaTraitRefs(traits, pages) {
   }
 }
 
+// src/resolver/sentinel-resolution.ts
+var PRIMITIVE_TYPE_ARG_NAMES = /* @__PURE__ */ new Set([
+  "string",
+  "money",
+  "any",
+  "icon",
+  "component",
+  "email",
+  "url",
+  "phone",
+  "uuid",
+  "image",
+  "node",
+  "json",
+  "render-ui",
+  "relation",
+  "int",
+  "float",
+  "number",
+  "duration",
+  "bool",
+  "boolean",
+  "date",
+  "datetime",
+  "timestamp",
+  "object",
+  "sexpr",
+  "scalar"
+]);
+var BARE_PAYLOAD_CARRIER = "value";
+function resolveTypeArgValue(value, entitiesByName, typesByName) {
+  if (PRIMITIVE_TYPE_ARG_NAMES.has(value)) {
+    return { kind: "scalar", primitive: value };
+  }
+  const entity = entitiesByName.get(value);
+  if (entity) {
+    return { kind: "entity", entity };
+  }
+  const shape = typesByName[value];
+  if (shape) {
+    return { kind: "struct", shape };
+  }
+  return void 0;
+}
+function entityFieldToPayloadField(f) {
+  if (f.type === "object" && f.items) {
+    const valueType = fieldTypeTagOf(f.items);
+    return {
+      name: f.name ?? "",
+      type: `Map<string,${valueType}>`,
+      ...f.required !== void 0 ? { required: f.required } : {}
+    };
+  }
+  let properties;
+  if (f.type === "object" && f.properties) {
+    properties = Object.values(f.properties).map(entityFieldToPayloadField);
+  } else if (f.type === "union" && f.properties) {
+    const ordered = f.values ?? Object.keys(f.properties);
+    properties = ordered.map((k) => f.properties?.[k]).filter((v) => v !== void 0).map(entityFieldToPayloadField);
+  } else if (f.type === "array" && f.items) {
+    properties = entityFieldToPayloadField(f.items).properties;
+  }
+  const isArrayOfStruct = f.type === "array" && properties !== void 0;
+  return {
+    name: f.name ?? "",
+    type: isArrayOfStruct ? "[object]" : fieldTypeTagOf(f),
+    ...f.required !== void 0 ? { required: f.required } : {},
+    ...properties && properties.length > 0 ? { properties } : {}
+  };
+}
+function fieldTypeTagOf(f) {
+  return f.type;
+}
+function entityFieldsToPayloadFields(entity) {
+  return entity.fields.map(entityFieldToPayloadField);
+}
+function flattenBareEntityPayload(fields, entityDef, subs) {
+  if (fields.length !== 1) return false;
+  const field = fields[0];
+  if (field.name !== BARE_PAYLOAD_CARRIER) return false;
+  let entity;
+  if (field.type === "@entity") {
+    entity = entityDef;
+  } else if (field.type === "object" && field.properties) {
+    entity = entityDef;
+  } else if (field.type.startsWith("$")) {
+    const sub = subs.get(field.type.slice(1));
+    entity = sub?.kind === "entity" ? sub.entity : void 0;
+  }
+  if (!entity) return false;
+  fields.length = 0;
+  fields.push(...entityFieldsToPayloadFields(entity));
+  return true;
+}
+function resolveSentinelFields(fields, entityDef, subs, declaredNames) {
+  let changed = false;
+  for (const field of fields) {
+    const isSelfRef = field.type === "@entity" || field.type === "[@entity]";
+    if (isSelfRef) {
+      if (entityDef) {
+        const isArray = field.type.startsWith("[");
+        field.type = isArray ? "[object]" : "object";
+        field.properties = entityFieldsToPayloadFields(entityDef);
+        field.entity = entityDef.name;
+        changed = true;
+      }
+      continue;
+    }
+    const isArraySentinel = field.type.startsWith("[$") && field.type.endsWith("]");
+    const isBareSentinel = !isArraySentinel && field.type.startsWith("$");
+    if (isBareSentinel || isArraySentinel) {
+      const paramName = isArraySentinel ? field.type.slice(2, -1) : field.type.slice(1);
+      const sub = subs.get(paramName);
+      if (sub) {
+        switch (sub.kind) {
+          case "scalar":
+            field.type = isArraySentinel ? `[${sub.primitive}]` : sub.primitive;
+            field.properties = void 0;
+            break;
+          case "entity":
+            field.type = isArraySentinel ? "[object]" : "object";
+            field.properties = entityFieldsToPayloadFields(sub.entity);
+            field.entity = sub.entity.name;
+            break;
+          case "struct":
+            field.type = isArraySentinel ? "[object]" : "object";
+            field.properties = [...sub.shape];
+            break;
+        }
+        changed = true;
+        continue;
+      }
+      if (declaredNames.has(paramName)) {
+        continue;
+      }
+      if (entityDef) {
+        field.type = isArraySentinel ? "[object]" : "object";
+        field.properties = entityFieldsToPayloadFields(entityDef);
+        field.entity = entityDef.name;
+        changed = true;
+      }
+      continue;
+    }
+    if (field.properties) {
+      const mutableProps = field.properties;
+      changed = resolveSentinelFields(mutableProps, entityDef, subs, declaredNames) || changed;
+    }
+  }
+  return changed;
+}
+function resolveTraitTypeParamSentinels(trait, entityDef, entitiesByName, typesByName, typeArgs) {
+  const declared = trait.typeParams ?? [];
+  const subs = /* @__PURE__ */ new Map();
+  const declaredNames = /* @__PURE__ */ new Set();
+  for (const p of declared) {
+    declaredNames.add(p.name);
+    const argValue = typeArgs?.[p.name];
+    let sub;
+    if (argValue !== void 0) {
+      sub = resolveTypeArgValue(argValue, entitiesByName, typesByName);
+    } else if (p.kind === "Entity" && entityDef) {
+      sub = { kind: "entity", entity: entityDef };
+    } else if (p.default) {
+      sub = resolveTypeArgValue(p.default, entitiesByName, typesByName);
+    }
+    if (sub) subs.set(p.name, sub);
+  }
+  let changed = false;
+  for (const emit of trait.emits ?? []) {
+    if (!emit.payloadSchema) continue;
+    const schema = emit.payloadSchema;
+    if (flattenBareEntityPayload(schema, entityDef, subs)) {
+      changed = true;
+    } else {
+      changed = resolveSentinelFields(schema, entityDef, subs, declaredNames) || changed;
+    }
+  }
+  for (const ev of trait.stateMachine?.events ?? []) {
+    if (!ev.payloadSchema) continue;
+    const schema = ev.payloadSchema;
+    if (flattenBareEntityPayload(schema, entityDef, subs)) {
+      changed = true;
+    } else {
+      changed = resolveSentinelFields(schema, entityDef, subs, declaredNames) || changed;
+    }
+  }
+  return changed;
+}
+function resolveOrbitalTypeParamSentinels(traits, primaryEntity, auxiliaryEntities, orbitalTypes) {
+  const entitiesByName = /* @__PURE__ */ new Map();
+  entitiesByName.set(primaryEntity.name, primaryEntity);
+  for (const e of auxiliaryEntities) entitiesByName.set(e.name, e);
+  const typesByName = orbitalTypes ?? {};
+  for (const rt of traits) {
+    const entityDef = rt.trait.linkedEntity ? entitiesByName.get(rt.trait.linkedEntity) : void 0;
+    resolveTraitTypeParamSentinels(rt.trait, entityDef, entitiesByName, typesByName, rt.typeArgs);
+  }
+}
+
 // src/resolver/reference-resolver.ts
 var refResolverLog = createLogger("almadar:runtime:ref-resolver");
 function indexOrbitalNodes(orbital, idIndex) {
@@ -3910,6 +4174,25 @@ function renameTraitEmbedsInValue(node, subs) {
   }
   return next;
 }
+function renameEntityNameTokensInValue(node, entitySubs) {
+  if (node === null || node === void 0) return node;
+  if (typeof node === "string") {
+    if (!node.startsWith("@")) return node;
+    const rest = node.slice(1);
+    const dot = rest.search(/[.[]/);
+    const name = dot === -1 ? rest : rest.slice(0, dot);
+    const suffix = dot === -1 ? "" : rest.slice(dot);
+    const to = entitySubs.get(name);
+    return to === void 0 ? node : `@${to}${suffix}`;
+  }
+  if (Array.isArray(node)) return node.map((item) => renameEntityNameTokensInValue(item, entitySubs));
+  if (typeof node !== "object") return node;
+  const next = {};
+  for (const [key, value] of Object.entries(node)) {
+    next[key] = renameEntityNameTokensInValue(value, entitySubs);
+  }
+  return next;
+}
 function renameTraitEmbeds(trait, subs) {
   if (subs.size === 0) return trait;
   const sm = trait.stateMachine;
@@ -3956,6 +4239,36 @@ function findTraitEntryInOrbital(orbital, localName) {
   }
   return null;
 }
+function homeOrbitalConfigForTrait(imported, traitName) {
+  for (const o of importedOrbitals(imported)) {
+    if (findTraitEntryInOrbital(o, traitName)) return o.config;
+  }
+  return void 0;
+}
+function findPageEntryInOrbital(orbital, localName) {
+  for (const pageRef of orbital.pages ?? []) {
+    if (typeof pageRef === "string") continue;
+    if (!("ref" in pageRef)) {
+      if (pageRef.name === localName) return pageRef;
+      continue;
+    }
+    const refObj = pageRef;
+    if (parsePageRef(refObj.ref)?.pageName === localName) return refObj;
+  }
+  return null;
+}
+function toPageTraitRef(traitRef) {
+  if (typeof traitRef === "string") return { ref: traitRef };
+  if ("stateMachine" in traitRef) return { ref: traitRef.name };
+  const refObj = traitRef;
+  return {
+    ref: refObj.name ?? refObj.ref,
+    ...refObj.refId !== void 0 ? { refId: refObj.refId } : {},
+    ...refObj.linkedEntity !== void 0 ? { linkedEntity: refObj.linkedEntity } : {},
+    ...refObj.linkedEntityId !== void 0 ? { linkedEntityId: refObj.linkedEntityId } : {},
+    ...refObj.config !== void 0 ? { config: refObj.config } : {}
+  };
+}
 function traitEmbedNamesOf(trait) {
   const found = /* @__PURE__ */ new Set();
   const walk = (node) => {
@@ -3975,34 +4288,179 @@ function traitEmbedNamesOf(trait) {
     if (typeof node !== "object") return;
     for (const value of Object.values(node)) walk(value);
   };
-  for (const t of trait.stateMachine?.transitions ?? []) walk(t.effects);
-  for (const tick of trait.ticks ?? []) walk(tick.effects);
+  for (const t of trait.stateMachine?.transitions ?? []) {
+    walk(t.guard);
+    walk(t.effects);
+  }
+  for (const tick of trait.ticks ?? []) {
+    walk(tick.guard);
+    walk(tick.effects);
+  }
   for (const field of Object.values(trait.config ?? {})) walk(field.default);
-  return [...found];
+  return [...found].sort();
 }
-function resolveForwardedSiblingConfig(trait, parent) {
+function resolveForwardedSiblingConfigFrom(trait, parentChain, orbitalConfig, schemaConfig) {
   const declared = trait.config;
-  const parentDeclared = parent?.config;
-  if (!declared || !parentDeclared) return trait;
+  if (!declared) return trait;
+  const next = resolveConfigForwards(declared, parentChain, orbitalConfig, void 0, void 0, schemaConfig);
+  return next ? { ...trait, config: next } : trait;
+}
+function callSiteRungValue(rungConfig, knob) {
+  const entry = rungConfig[knob];
+  if (entry === void 0) return void 0;
+  return isCallSiteConfigDeclaration(entry) ? entry.default : entry;
+}
+function walkConfigForwardChain(forward, parentChain, orbitalConfig, upstreamOrbitalConfig, upstreamSchemaConfig, schemaConfig) {
+  let knob = forward.slice("@config.".length);
+  if (knob.length === 0 || knob.includes(".")) return void 0;
+  let value;
+  let currentForward = forward;
+  for (const rungConfig of parentChain) {
+    const rungValue = callSiteRungValue(rungConfig, knob);
+    if (rungValue === void 0 || rungValue === currentForward) continue;
+    if (typeof rungValue === "string" && rungValue.startsWith("@config.")) {
+      const nextKnob = rungValue.slice("@config.".length);
+      if (nextKnob.length === 0 || nextKnob.includes(".") || nextKnob === knob) continue;
+      knob = nextKnob;
+      currentForward = rungValue;
+      continue;
+    }
+    value = rungValue;
+    break;
+  }
+  if (value === void 0 || value === currentForward) value = orbitalConfig?.[knob]?.default;
+  if (value === void 0 || value === currentForward) value = upstreamOrbitalConfig?.[knob]?.default;
+  if (value === void 0 || value === currentForward) value = upstreamSchemaConfig?.[knob]?.default;
+  if (value === void 0 || value === currentForward) value = schemaConfig?.[knob]?.default;
+  if (value === void 0 || value === currentForward) return void 0;
+  return value;
+}
+function resolveConfigForwards(declared, parentChain, orbitalConfig, upstreamOrbitalConfig, upstreamSchemaConfig, schemaConfig) {
   let next;
   for (const [key, field] of Object.entries(declared)) {
     const forward = field.default;
     if (typeof forward !== "string" || !forward.startsWith("@config.")) continue;
-    const knob = forward.slice("@config.".length);
-    if (knob.length === 0 || knob.includes(".")) continue;
-    const value = parentDeclared[knob]?.default;
-    if (value === void 0 || value === forward) continue;
+    const value = walkConfigForwardChain(
+      forward,
+      parentChain,
+      orbitalConfig,
+      upstreamOrbitalConfig,
+      upstreamSchemaConfig,
+      schemaConfig
+    );
+    if (value === void 0) continue;
     next ??= { ...declared };
-    next[key] = { ...field, default: value };
+    next[key] = { ...field, default: value, forwardedFrom: forward };
   }
-  return next ? { ...trait, config: next } : trait;
+  return next;
+}
+function resolveCallSiteConfigForwards(config, parentChain, orbitalConfig, schemaConfig) {
+  let next;
+  for (const [key, entry] of Object.entries(config)) {
+    const forward = isCallSiteConfigDeclaration(entry) ? entry.default : entry;
+    if (typeof forward !== "string" || !forward.startsWith("@config.")) continue;
+    const value = walkConfigForwardChain(forward, parentChain, orbitalConfig, void 0, void 0, schemaConfig);
+    if (value === void 0) continue;
+    next ??= { ...config };
+    next[key] = isCallSiteConfigDeclaration(entry) ? { ...entry, default: value, forwardedFrom: forward } : value;
+  }
+  return next;
+}
+function traitRefEmbedNamesOf(traitRef) {
+  if (typeof traitRef === "string") return [];
+  return traitEmbedNamesOf(traitRef);
+}
+function traitRefLocalName(traitRef) {
+  if (typeof traitRef === "string") {
+    return parseImportedTraitRef(traitRef)?.traitName ?? traitRef;
+  }
+  if ("stateMachine" in traitRef) return traitRef.name;
+  const refObj = traitRef;
+  return refObj.name ?? parseImportedTraitRef(refObj.ref)?.traitName ?? refObj.ref;
+}
+function traitRefConfigOf(traitRef) {
+  if (typeof traitRef === "string") return void 0;
+  return traitRef.config;
+}
+function buildEmbedGraph(traitRefs) {
+  const out = /* @__PURE__ */ new Map();
+  for (const traitRef of traitRefs) {
+    const referrerName = traitRefLocalName(traitRef);
+    if (!referrerName) continue;
+    for (const child of traitRefEmbedNamesOf(traitRef)) {
+      if (child === referrerName) continue;
+      if (!out.has(child)) out.set(child, referrerName);
+    }
+  }
+  return out;
+}
+function embedderChain(localName, traitRefs, graph) {
+  const chain = [];
+  const visited = /* @__PURE__ */ new Set([localName]);
+  let cur = graph.get(localName);
+  let hops = 0;
+  while (cur !== void 0 && !visited.has(cur) && hops < traitRefs.length) {
+    visited.add(cur);
+    hops++;
+    const entry = traitRefs.find((t) => traitRefLocalName(t) === cur);
+    const entryConfig = entry ? traitRefConfigOf(entry) : void 0;
+    if (entryConfig) chain.push(entryConfig);
+    cur = graph.get(cur);
+  }
+  return chain;
+}
+function resolveEmbedderConfigForward(config, localName, embedCtx, schemaConfig) {
+  const chain = embedderChain(localName, embedCtx.traitRefs, embedCtx.embedGraph);
+  const next = resolveCallSiteConfigForwards(config, chain, embedCtx.orbitalConfig, schemaConfig);
+  return next ? next : config;
+}
+function consumerKnownEntityRebindSubs(trait, entityIds) {
+  const out = /* @__PURE__ */ new Map();
+  const refs = trait.entityRefIds;
+  if (!refs) return out;
+  const idToConsumerName = /* @__PURE__ */ new Map();
+  for (const [name, id] of entityIds) {
+    if (!idToConsumerName.has(id)) idToConsumerName.set(id, name);
+  }
+  for (const [tokenName, entityId] of Object.entries(refs)) {
+    const consumerName = idToConsumerName.get(entityId);
+    if (consumerName !== void 0 && consumerName !== tokenName) {
+      out.set(tokenName, consumerName);
+    }
+  }
+  return out;
+}
+function staleEntityRebindSubs(trait, newEntity) {
+  const out = /* @__PURE__ */ new Map();
+  const boundId = trait.linkedEntityId;
+  const refs = trait.entityRefIds;
+  if (boundId && refs) {
+    for (const [tokenName, entityId] of Object.entries(refs)) {
+      if (entityId === boundId) out.set(tokenName, newEntity);
+    }
+  }
+  return out;
 }
-function applyLinkedEntityRename(trait, linkedEntity) {
+function applyLinkedEntityRename(trait, linkedEntity, entityIds) {
   const atomLinked = trait.linkedEntity;
-  if (!linkedEntity || !atomLinked || linkedEntity === atomLinked) return trait;
-  const sm = trait.stateMachine;
-  if (!sm) return { ...trait, linkedEntity };
+  const entitySubs = consumerKnownEntityRebindSubs(trait, entityIds);
+  if (!linkedEntity || !atomLinked || linkedEntity === atomLinked) {
+    return rewriteEntityRefIds(trait, entitySubs, entityIds);
+  }
+  for (const [from, to] of staleEntityRebindSubs(trait, linkedEntity)) {
+    entitySubs.set(from, to);
+  }
+  entitySubs.set(atomLinked, linkedEntity);
   const rename = (name) => name === atomLinked ? linkedEntity : void 0;
+  const sm = trait.stateMachine;
+  const rebound = {
+    ...trait,
+    linkedEntity,
+    linkedEntityId: entityIds.get(linkedEntity)
+  };
+  if (!sm) {
+    return renamePayloadEntityMarkers(rewriteEntityRefIds(rebound, entitySubs, entityIds), rename);
+  }
   const nextTransitions = (sm.transitions ?? []).map((t) => {
     const nextEffects = t.effects ? renameEntityInEffects(
       t.effects,
@@ -4017,11 +4475,14 @@ function applyLinkedEntityRename(trait, linkedEntity) {
     to: linkedEntity,
     transitionCount: nextTransitions.length
   });
-  return {
-    ...trait,
-    linkedEntity,
-    stateMachine: { ...sm, transitions: nextTransitions }
-  };
+  return renamePayloadEntityMarkers(
+    rewriteEntityRefIds(
+      { ...rebound, stateMachine: { ...sm, transitions: nextTransitions } },
+      entitySubs,
+      entityIds
+    ),
+    rename
+  );
 }
 function resolveEntityTokensById(trait, idIndex) {
   const map = trait.entityRefIds;
@@ -4170,17 +4631,44 @@ function applyEventRenamesToCallSiteConfig(config, declared, renames) {
   }
   return touched ? next : config;
 }
+function resolvedKnobValues(before, after, knobs) {
+  const out = /* @__PURE__ */ new Map();
+  if (knobs.length === 0) return out;
+  const knobSet = new Set(knobs);
+  const beforeEmits = before.emits ?? [];
+  const afterEmits = after.emits ?? [];
+  for (let i = 0; i < beforeEmits.length; i++) {
+    const knob = configRefEventKnob(beforeEmits[i].event);
+    if (knob !== void 0 && knobSet.has(knob)) out.set(knob, afterEmits[i].event);
+  }
+  return out;
+}
+function foldEventRenameOntoDeclaredKnobs(trait, resolved, eventRenames) {
+  if (!eventRenames || resolved.size === 0 || !trait.config) return trait;
+  let nextConfig;
+  for (const [knob, resolvedValue] of resolved) {
+    const renamed = eventRenames[resolvedValue];
+    if (renamed === void 0 || renamed === resolvedValue) continue;
+    const field = trait.config[knob];
+    if (!field) continue;
+    nextConfig ??= { ...trait.config };
+    nextConfig[knob] = { ...field, default: renamed };
+  }
+  return nextConfig ? { ...trait, config: nextConfig } : trait;
+}
 function resolveConfigRefEmitNames(trait, callSiteConfig) {
   const emits = trait.emits ?? [];
   const hasRef = emits.some((em) => configRefEventKnob(em.event) !== void 0);
-  if (!hasRef) return { trait, errors: [] };
+  if (!hasRef) return { trait, errors: [], resolvedKnobs: [] };
   const effectiveConfig = {
     ...normalizeCallSiteConfigToValues(trait.config) ?? {},
     ...normalizeCallSiteConfigToValues(callSiteConfig) ?? {}
   };
   const errors = [];
+  const resolvedTriples = [];
   const nextEmits = emits.map((em) => {
-    if (configRefEventKnob(em.event) === void 0) return em;
+    const knob = configRefEventKnob(em.event);
+    if (knob === void 0) return em;
     const result = resolveConfigRefEventName(em.event, trait.config, effectiveConfig);
     if (!result.ok) {
       errors.push(
@@ -4193,78 +4681,1065 @@ function resolveConfigRefEmitNames(trait, callSiteConfig) {
       ref: em.event,
       resolved: result.value
     });
+    resolvedTriples.push({ knob, from: em.event, to: result.value });
     return { ...em, event: result.value };
   });
-  return { trait: { ...trait, emits: nextEmits }, errors };
+  const sm = trait.stateMachine;
+  const nextEvents = resolvedTriples.length > 0 && sm ? sm.events.map((ev) => {
+    const hit = resolvedTriples.find((t) => t.from === ev.key);
+    return hit ? { ...ev, key: hit.to } : ev;
+  }) : sm?.events;
+  return {
+    trait: {
+      ...trait,
+      emits: nextEmits,
+      ...sm && nextEvents !== sm.events ? { stateMachine: { ...sm, events: nextEvents } } : {}
+    },
+    errors,
+    resolvedKnobs: resolvedTriples.map((t) => t.knob)
+  };
 }
-var ReferenceResolver = class {
-  loader;
-  options;
-  localTraits;
-  /** id-keyed mirror of `localTraits`, populated wherever the trait carries an `id`. */
-  localTraitsById = /* @__PURE__ */ new Map();
-  /** Import scope of each loaded source orbital, keyed by its source path. */
-  sourceImportsCache = /* @__PURE__ */ new Map();
-  loaderInitialized = false;
-  constructor(options) {
-    this.options = options;
-    this.loader = options.loader;
-    this.localTraits = options.localTraits ?? /* @__PURE__ */ new Map();
-    for (const trait of this.localTraits.values()) {
-      if (trait.id) {
-        this.localTraitsById.set(trait.id, trait);
-      }
+function foldCallSiteConfigOntoTrait(trait, callSiteConfig) {
+  if (!callSiteConfig) return trait;
+  const declared = trait.config;
+  const overrideValues = {};
+  const overriddenKeys = /* @__PURE__ */ new Set();
+  const newDeclarations = {};
+  for (const [key, entry] of Object.entries(callSiteConfig)) {
+    const isDecl = isCallSiteConfigDeclaration(entry);
+    const value = isDecl ? entry.default : entry;
+    if (declared && key in declared) {
+      if (value !== void 0) {
+        overrideValues[key] = value;
+        overriddenKeys.add(key);
+      }
+    } else if (isDecl) {
+      newDeclarations[key] = entry;
+    }
+  }
+  if (overriddenKeys.size === 0 && Object.keys(newDeclarations).length === 0) {
+    return trait;
+  }
+  let nextConfig = overrideDeclaredKnobs(declared ?? {}, overrideValues);
+  if (overriddenKeys.size > 0) {
+    const patched = { ...nextConfig };
+    for (const key of overriddenKeys) {
+      const field = patched[key];
+      if (!field) continue;
+      const entry = callSiteConfig[key];
+      const entryDecl = isCallSiteConfigDeclaration(entry) ? entry : void 0;
+      patched[key] = {
+        ...field,
+        forwardedFrom: entryDecl?.forwardedFrom,
+        // The atom's OWN `refId` (a reference-config field's declared
+        // default names a SPECIFIC node by id) describes the ATOM's OWN
+        // `default`, not whatever this override just replaced it with —
+        // carrying it forward unchanged left a STALE id bound to the NEW
+        // literal string, so the id-index's "current name" correction
+        // (`resolveConfigRefsById`) silently rewrote the override BACK to
+        // the atom's own default target — found via std-notes'
+        // `NoteGlobalSearch`: `idleContent`'s override says `@trait.
+        // NoteCatalog` but the atom's OWN stale `refId` (still pointing at
+        // `AppSearchIdleHint`, the atom's default) rewrote the sibling-pull
+        // target back to it (rung 2: an override with no id of its own
+        // names no id, so it must clear the atom's). An override that
+        // carries ITS OWN `refId` (an annotated, id-aware override) wins
+        // instead — same precedence a `default` override already has.
+        refId: entryDecl?.refId,
+        ...entryDecl?.label !== void 0 ? { label: entryDecl.label } : {},
+        ...entryDecl?.description !== void 0 ? { description: entryDecl.description } : {},
+        ...entryDecl?.synonyms !== void 0 ? { synonyms: entryDecl.synonyms } : {},
+        ...entryDecl?.tier !== void 0 ? { tier: entryDecl.tier } : {}
+      };
     }
+    nextConfig = patched;
   }
-  async ensureLoader() {
-    if (this.loader || this.loaderInitialized) return;
-    this.loaderInitialized = true;
-    try {
-      const { ExternalOrbitalLoader } = await import('./external-loader-YUUADLAP.js');
-      this.loader = new ExternalOrbitalLoader(this.options);
-    } catch {
-    }
+  if (Object.keys(newDeclarations).length > 0) {
+    nextConfig = { ...nextConfig, ...newDeclarations };
   }
-  /**
-   * Resolve all references in an orbital.
-   */
-  async resolve(orbital, sourcePath, chain) {
-    const errors = [];
-    const warnings = [];
-    const importChain = chain ?? { push: () => null, pop: () => {
-    }, clone() {
-      return this;
-    } };
-    const traitsList = orbital.traits ?? [];
-    const alreadyResolved = traitsList.length > 0 && traitsList.every((t) => isInlineTrait(t));
-    const importsResult = alreadyResolved ? { success: true, data: { orbitals: /* @__PURE__ */ new Map(), idIndex: /* @__PURE__ */ new Map() }} : await this.resolveImports(orbital.uses ?? [], sourcePath, importChain);
-    if (!importsResult.success) {
-      return { success: false, errors: importsResult.errors };
-    }
-    const imports = importsResult.data;
-    imports.idIndex = buildIdIndex(orbital, imports.orbitals);
-    const entityResult = this.resolveEntity(orbital.entity, imports);
-    if (!entityResult.success) {
-      errors.push(...entityResult.errors);
-    }
-    const traitsResult = this.resolveTraits(orbital.traits, imports);
-    if (!traitsResult.success) {
-      errors.push(...traitsResult.errors);
-    }
-    const pagesResult = this.resolvePages(orbital.pages, imports);
-    if (!pagesResult.success) {
-      errors.push(...pagesResult.errors);
+  return { ...trait, config: nextConfig };
+}
+var ENTITY_FIELD_TOKEN_PREFIX = "@entity.";
+function rewriteEntityFieldTokensInValue(node, subs) {
+  if (node === null || node === void 0) return node;
+  if (typeof node === "string") {
+    if (!node.startsWith(ENTITY_FIELD_TOKEN_PREFIX)) return node;
+    const rest = node.slice(ENTITY_FIELD_TOKEN_PREFIX.length);
+    const dot = rest.search(/[.[]/);
+    const name = dot === -1 ? rest : rest.slice(0, dot);
+    const suffix = dot === -1 ? "" : rest.slice(dot);
+    const to = subs.get(name);
+    return to === void 0 ? node : `${ENTITY_FIELD_TOKEN_PREFIX}${to}${suffix}`;
+  }
+  if (Array.isArray(node)) return node.map((item) => rewriteEntityFieldTokensInValue(item, subs));
+  if (typeof node !== "object") return node;
+  const next = {};
+  for (const [key, value] of Object.entries(node)) {
+    next[key] = rewriteEntityFieldTokensInValue(value, subs);
+  }
+  return next;
+}
+function rewriteEntityFieldsInTrait(trait, fieldSubs) {
+  if (fieldSubs.size === 0) return trait;
+  const rewrite = (v) => rewriteEntityFieldTokensInValue(v, fieldSubs);
+  const next = { ...trait };
+  const sm = trait.stateMachine;
+  if (sm) {
+    next.stateMachine = {
+      ...sm,
+      transitions: (sm.transitions ?? []).map((t) => ({
+        ...t,
+        ...t.guard !== void 0 ? { guard: rewrite(t.guard) } : {},
+        ...t.effects ? { effects: rewrite(t.effects) } : {}
+      }))
+    };
+  }
+  if (trait.ticks) {
+    next.ticks = trait.ticks.map((tick) => ({
+      ...tick,
+      ...tick.guard !== void 0 ? { guard: rewrite(tick.guard) } : {},
+      effects: rewrite(tick.effects)
+    }));
+  }
+  if (trait.listens) {
+    next.listens = trait.listens.map((l) => ({
+      ...l,
+      ...l.guard !== void 0 ? { guard: rewrite(l.guard) } : {},
+      ...l.payloadMapping ? { payloadMapping: rewrite(l.payloadMapping) } : {}
+    }));
+  }
+  if (trait.initialEffects) {
+    next.initialEffects = rewrite(trait.initialEffects);
+  }
+  if (trait.config) {
+    const nextConfig = {};
+    for (const [key, field] of Object.entries(trait.config)) {
+      nextConfig[key] = field.default === void 0 ? field : { ...field, default: rewrite(field.default) };
     }
-    if (errors.length > 0) {
-      return { success: false, errors };
+    next.config = nextConfig;
+  }
+  return next;
+}
+function rewriteEntityFieldsInEntity(entity, fieldSubs) {
+  if (fieldSubs.size === 0) return entity;
+  const rewrite = (v) => rewriteEntityFieldTokensInValue(v, fieldSubs);
+  return {
+    ...entity,
+    fields: entity.fields.map((f) => f.name && fieldSubs.has(f.name) ? { ...f, name: fieldSubs.get(f.name) } : f),
+    ...entity.read_policy !== void 0 ? { read_policy: rewrite(entity.read_policy) } : {},
+    ...entity.create_policy !== void 0 ? { create_policy: rewrite(entity.create_policy) } : {},
+    ...entity.update_policy !== void 0 ? { update_policy: rewrite(entity.update_policy) } : {},
+    ...entity.delete_policy !== void 0 ? { delete_policy: rewrite(entity.delete_policy) } : {}
+  };
+}
+var USER_FIELD_PREFIX = "@user.";
+function directUserField(node) {
+  if (typeof node !== "string" || !node.startsWith(USER_FIELD_PREFIX)) return void 0;
+  const rest = node.slice(USER_FIELD_PREFIX.length);
+  return rest.length > 0 && !/[.[]/.test(rest) ? rest : void 0;
+}
+var EQUALITY_OPS = /* @__PURE__ */ new Set(["=", "==", "!=", "!==", "eq", "neq"]);
+var NEGATED_EQUALITY_OPS = /* @__PURE__ */ new Set(["!=", "!==", "neq"]);
+function literalHaystackMembers(items) {
+  const isListCall = items[0] === "list";
+  const members = isListCall ? items.slice(1) : items;
+  return members.every((v) => typeof v === "string") ? [...members] : void 0;
+}
+function rewriteRoleLiteralsInValue(node, roleFields, roles) {
+  if (node === null || node === void 0) return node;
+  if (Array.isArray(node)) {
+    const head = node[0];
+    if (typeof head === "string" && EQUALITY_OPS.has(head) && node.length === 3) {
+      const [, left, right] = node;
+      const leftField = directUserField(left);
+      const rightField = directUserField(right);
+      const userField = leftField !== void 0 && rightField === void 0 ? leftField : rightField !== void 0 && leftField === void 0 ? rightField : void 0;
+      if (userField !== void 0 && roleFields.has(userField)) {
+        const literalSide = leftField !== void 0 ? right : left;
+        if (typeof literalSide === "string" && literalSide in roles) {
+          const targets = roles[literalSide];
+          if (targets.length === 1) {
+            return leftField !== void 0 ? [head, left, targets[0]] : [head, targets[0], right];
+          }
+          const includesExpr = ["array/includes", [...targets], leftField !== void 0 ? left : right];
+          return NEGATED_EQUALITY_OPS.has(head) ? ["not", includesExpr] : includesExpr;
+        }
+      }
     }
-    if (!entityResult.success || !traitsResult.success || !pagesResult.success) {
-      return { success: false, errors: ["Internal error: unexpected failure state"] };
+    if (head === "array/includes" && node.length === 3 && Array.isArray(node[1])) {
+      const needleField = directUserField(node[2]);
+      if (needleField !== void 0 && roleFields.has(needleField)) {
+        const members = literalHaystackMembers(node[1]);
+        if (members !== void 0) {
+          const expanded = [];
+          for (const literal of members) {
+            const mapped = roles[literal];
+            if (mapped) {
+              for (const target of mapped) if (!expanded.includes(target)) expanded.push(target);
+            } else if (!expanded.includes(literal)) {
+              expanded.push(literal);
+            }
+          }
+          const isListCall = node[1][0] === "list";
+          return ["array/includes", isListCall ? ["list", ...expanded] : expanded, node[2]];
+        }
+      }
     }
-    const pullErrors = await this.pullSiblingTraits(traitsResult.data, imports, importChain);
-    if (pullErrors.length > 0) {
+    return node.map((item) => rewriteRoleLiteralsInValue(item, roleFields, roles));
+  }
+  if (typeof node !== "object") return node;
+  const next = {};
+  for (const [key, value] of Object.entries(node)) {
+    next[key] = rewriteRoleLiteralsInValue(value, roleFields, roles);
+  }
+  return next;
+}
+function rewriteRoleLiteralsInTrait(trait, roleFields, roles) {
+  if (roleFields.size === 0 || Object.keys(roles).length === 0) return trait;
+  const rewrite = (v) => rewriteRoleLiteralsInValue(v, roleFields, roles);
+  const next = { ...trait };
+  const sm = trait.stateMachine;
+  if (sm) {
+    next.stateMachine = {
+      ...sm,
+      transitions: (sm.transitions ?? []).map((t) => ({
+        ...t,
+        ...t.guard !== void 0 ? { guard: rewrite(t.guard) } : {},
+        ...t.effects ? { effects: rewrite(t.effects) } : {}
+      }))
+    };
+  }
+  if (trait.ticks) {
+    next.ticks = trait.ticks.map((tick) => ({
+      ...tick,
+      ...tick.guard !== void 0 ? { guard: rewrite(tick.guard) } : {},
+      effects: rewrite(tick.effects)
+    }));
+  }
+  if (trait.listens) {
+    next.listens = trait.listens.map((l) => ({
+      ...l,
+      ...l.guard !== void 0 ? { guard: rewrite(l.guard) } : {},
+      ...l.payloadMapping ? { payloadMapping: rewrite(l.payloadMapping) } : {}
+    }));
+  }
+  if (trait.initialEffects) {
+    next.initialEffects = rewrite(trait.initialEffects);
+  }
+  if (trait.config) {
+    const nextConfig = {};
+    for (const [key, field] of Object.entries(trait.config)) {
+      nextConfig[key] = field.default === void 0 ? field : { ...field, default: rewrite(field.default) };
+    }
+    next.config = nextConfig;
+  }
+  if (trait.sourceEntityDefinition) {
+    next.sourceEntityDefinition = rewriteRoleLiteralsInEntity(trait.sourceEntityDefinition, roleFields, roles);
+  }
+  return next;
+}
+function rewriteRoleLiteralsInEntity(entity, roleFields, roles) {
+  if (roleFields.size === 0 || Object.keys(roles).length === 0) return entity;
+  const rewrite = (v) => rewriteRoleLiteralsInValue(v, roleFields, roles);
+  return {
+    ...entity,
+    ...entity.read_policy !== void 0 ? { read_policy: rewrite(entity.read_policy) } : {},
+    ...entity.create_policy !== void 0 ? { create_policy: rewrite(entity.create_policy) } : {},
+    ...entity.update_policy !== void 0 ? { update_policy: rewrite(entity.update_policy) } : {},
+    ...entity.delete_policy !== void 0 ? { delete_policy: rewrite(entity.delete_policy) } : {}
+  };
+}
+function renameRelationTargetsInField(field, entitySubs, entityIds) {
+  let next = field;
+  if (next.type === "relation") {
+    const to = entitySubs.get(next.relation.entity);
+    if (to !== void 0) {
+      next = { ...next, relation: { ...next.relation, entity: to, entityId: entityIds.get(to) } };
+    }
+  }
+  if ((next.type === "array" || next.type === "object") && next.items) {
+    next = { ...next, items: renameRelationTargetsInField(next.items, entitySubs, entityIds) };
+  }
+  if (next.properties) {
+    const nextProperties = {};
+    for (const [key, value] of Object.entries(next.properties)) {
+      nextProperties[key] = renameRelationTargetsInField(value, entitySubs, entityIds);
+    }
+    next = { ...next, properties: nextProperties };
+  }
+  return next;
+}
+function renameEntityRelationTargets(entity, entitySubs, entityIds) {
+  if (entitySubs.size === 0) return entity;
+  return { ...entity, fields: entity.fields.map((f) => renameRelationTargetsInField(f, entitySubs, entityIds)) };
+}
+function renameSourceEntityDefinition(trait, subs, entityIds) {
+  const src = trait.sourceEntityDefinition;
+  if (!src || subs.size === 0) return trait;
+  const renamedName = subs.get(src.name) ?? src.name;
+  const nextSrc = renameEntityRelationTargets({ ...src, name: renamedName }, subs, entityIds);
+  return { ...trait, sourceEntityDefinition: nextSrc };
+}
+function renamePayloadEntity(fields, rename) {
+  return fields.map((field) => {
+    const renamedEntity = field.entity !== void 0 ? rename(field.entity) : void 0;
+    const renamedProps = field.properties ? renamePayloadEntity(field.properties, rename) : field.properties;
+    return {
+      ...field,
+      ...renamedEntity !== void 0 ? { entity: renamedEntity } : {},
+      ...renamedProps !== void 0 ? { properties: renamedProps } : {}
+    };
+  });
+}
+function renamePayloadEntityMarkers(trait, rename) {
+  const sm = trait.stateMachine;
+  const nextEvents = sm?.events ? sm.events.map(
+    (ev) => ev.payloadSchema ? { ...ev, payloadSchema: renamePayloadEntity(ev.payloadSchema, rename) } : ev
+  ) : void 0;
+  const nextEmits = trait.emits ? trait.emits.map(
+    (em) => em.payloadSchema ? { ...em, payloadSchema: renamePayloadEntity(em.payloadSchema, rename) } : em
+  ) : void 0;
+  return {
+    ...trait,
+    ...sm && nextEvents ? { stateMachine: { ...sm, events: nextEvents } } : {},
+    ...nextEmits ? { emits: nextEmits } : {}
+  };
+}
+function walkEntityInPayloadMapping(payloadMapping, rename, props) {
+  const next = {};
+  for (const [key, value] of Object.entries(payloadMapping)) {
+    next[key] = renameEntityInEffect(value, rename, props);
+  }
+  return next;
+}
+function renameEntitiesInTrait(trait, entitySubs) {
+  if (entitySubs.size === 0) return trait;
+  const rename = (name) => entitySubs.get(name);
+  const withTokens = (value) => renameEntityNameTokensInValue(value, entitySubs);
+  const nextLinked = trait.linkedEntity !== void 0 ? entitySubs.get(trait.linkedEntity) ?? trait.linkedEntity : trait.linkedEntity;
+  const sm = trait.stateMachine;
+  const nextTransitions = sm?.transitions ? sm.transitions.map((t) => ({
+    ...t,
+    ...t.guard !== void 0 ? { guard: withTokens(renameEntityInEffect(t.guard, rename, REBIND_ENTITY_PROPS)) } : {},
+    effects: t.effects ? withTokens(renameEntityInEffects(t.effects, rename, REBIND_ENTITY_PROPS)) : t.effects
+  })) : sm?.transitions;
+  const nextTicks = trait.ticks ? trait.ticks.map((tick) => ({
+    ...tick,
+    ...tick.guard !== void 0 ? { guard: withTokens(renameEntityInEffect(tick.guard, rename, REBIND_ENTITY_PROPS)) } : {},
+    effects: withTokens(renameEntityInEffects(
+      tick.effects,
+      rename,
+      REBIND_ENTITY_PROPS
+    ))
+  })) : trait.ticks;
+  const nextListens = trait.listens ? trait.listens.map((l) => ({
+    ...l,
+    ...l.guard !== void 0 ? { guard: withTokens(renameEntityInEffect(l.guard, rename, REBIND_ENTITY_PROPS)) } : {},
+    ...l.payloadMapping ? { payloadMapping: withTokens(walkEntityInPayloadMapping(l.payloadMapping, rename, REBIND_ENTITY_PROPS)) } : {}
+  })) : trait.listens;
+  const nextInitial = trait.initialEffects ? withTokens(renameEntityInEffects(
+    trait.initialEffects,
+    rename,
+    REBIND_ENTITY_PROPS
+  )) : trait.initialEffects;
+  return renamePayloadEntityMarkers(
+    {
+      ...trait,
+      linkedEntity: nextLinked,
+      ...sm ? { stateMachine: { ...sm, transitions: nextTransitions ?? [] } } : {},
+      ...nextTicks !== void 0 ? { ticks: nextTicks } : {},
+      ...nextListens !== void 0 ? { listens: nextListens } : {},
+      ...nextInitial !== void 0 ? { initialEffects: nextInitial } : {}
+    },
+    rename
+  );
+}
+function rewriteEntityRefIds(trait, entitySubs, entityIds) {
+  const refs = trait.entityRefIds;
+  if (!refs) return trait;
+  const out = {};
+  for (const [from, oldId] of Object.entries(refs)) {
+    const name = entitySubs.get(from) ?? from;
+    out[name] = entityIds.get(name) ?? oldId;
+  }
+  return { ...trait, entityRefIds: out };
+}
+function applyAliasEntityRenames(trait, subs, entityIds) {
+  if (subs.size === 0) return trait;
+  const rename = (name) => subs.get(name);
+  const withTokens = (value) => renameEntityNameTokensInValue(value, subs);
+  const sm = trait.stateMachine;
+  const nextTransitions = sm?.transitions ? sm.transitions.map((t) => ({
+    ...t,
+    ...t.guard !== void 0 ? { guard: withTokens(renameEntityInEffect(t.guard, rename, REBIND_ENTITY_PROPS)) } : {},
+    effects: t.effects ? withTokens(renameEntityInEffects(t.effects, rename, REBIND_ENTITY_PROPS)) : t.effects
+  })) : sm?.transitions;
+  const nextTicks = trait.ticks ? trait.ticks.map((tick) => ({
+    ...tick,
+    ...tick.guard !== void 0 ? { guard: withTokens(renameEntityInEffect(tick.guard, rename, REBIND_ENTITY_PROPS)) } : {},
+    effects: withTokens(
+      renameEntityInEffects(tick.effects, rename, REBIND_ENTITY_PROPS)
+    )
+  })) : trait.ticks;
+  const next = {
+    ...trait,
+    ...sm ? { stateMachine: { ...sm, transitions: nextTransitions ?? [] } } : {},
+    ...nextTicks !== void 0 ? { ticks: nextTicks } : {}
+  };
+  return rewriteEntityRefIds(next, subs, entityIds);
+}
+function collectEntityNamesInTrait(trait, candidates) {
+  const collected = /* @__PURE__ */ new Set();
+  const collect = (name) => {
+    if (candidates.has(name)) collected.add(name);
+    return void 0;
+  };
+  const sm = trait.stateMachine;
+  for (const t of sm?.transitions ?? []) {
+    if (t.guard !== void 0) renameEntityInEffect(t.guard, collect, REBIND_ENTITY_PROPS);
+    if (t.effects) renameEntityInEffects(t.effects, collect, REBIND_ENTITY_PROPS);
+  }
+  for (const tick of trait.ticks ?? []) {
+    if (tick.guard !== void 0) renameEntityInEffect(tick.guard, collect, REBIND_ENTITY_PROPS);
+    renameEntityInEffects(tick.effects, collect, REBIND_ENTITY_PROPS);
+  }
+  for (const l of trait.listens ?? []) {
+    if (l.guard !== void 0) renameEntityInEffect(l.guard, collect, REBIND_ENTITY_PROPS);
+    if (l.payloadMapping) walkEntityInPayloadMapping(l.payloadMapping, collect, REBIND_ENTITY_PROPS);
+  }
+  if (trait.initialEffects) {
+    renameEntityInEffects(trait.initialEffects, collect, REBIND_ENTITY_PROPS);
+  }
+  return collected;
+}
+function collectRelationTargets(field, candidates, out) {
+  if (field.type === "relation" && candidates.has(field.relation.entity)) out.add(field.relation.entity);
+  if ((field.type === "array" || field.type === "object") && field.items) {
+    collectRelationTargets(field.items, candidates, out);
+  }
+  if (field.properties) {
+    for (const value of Object.values(field.properties)) collectRelationTargets(value, candidates, out);
+  }
+}
+function relationTargetsOfEntity(entity, candidates) {
+  const out = /* @__PURE__ */ new Set();
+  for (const field of entity.fields) collectRelationTargets(field, candidates, out);
+  return out;
+}
+function rewriteListenSources(trait, subs, idByName, orbitalRename) {
+  const listens = trait.listens;
+  if (!listens || listens.length === 0) return trait;
+  let changed = false;
+  const nextListens = listens.map((listen) => {
+    const source = listen.source;
+    if (!source) return listen;
+    if (source.kind === "trait") {
+      const target = subs.get(source.trait);
+      if (target === void 0 || target === source.trait) return listen;
+      changed = true;
+      const traitId = idByName.get(target);
+      return {
+        ...listen,
+        source: { kind: "trait", trait: target, ...traitId ? { traitId } : {} }
+      };
+    }
+    if (source.kind === "orbital" && orbitalRename && source.orbital === orbitalRename.from) {
+      const targetTrait = subs.get(source.trait) ?? source.trait;
+      changed = true;
+      const traitId = idByName.get(targetTrait);
+      return {
+        ...listen,
+        source: {
+          kind: "orbital",
+          orbital: orbitalRename.to,
+          trait: targetTrait,
+          ...traitId ? { traitId } : {}
+        }
+      };
+    }
+    return listen;
+  });
+  return changed ? { ...trait, listens: nextListens } : trait;
+}
+function isInlineEntity(ref) {
+  return !isEntityReference(ref) && !isEntityCall(ref);
+}
+function inlineEntityRefsOf(orbital) {
+  return [orbital.entity, ...orbital.auxiliaryEntities ?? []].filter(isInlineEntity);
+}
+function entityByNameForAlias(imports, alias, entityName) {
+  const imported = imports.orbitals.get(alias);
+  if (!imported) return void 0;
+  for (const o of importedOrbitals(imported)) {
+    const found = inlineEntityRefsOf(o).find((e) => e.name === entityName);
+    if (found) return found;
+  }
+  return void 0;
+}
+function entityByNameAnyAlias(imports, entityName) {
+  const aliases = Array.from(imports.orbitals.keys()).sort();
+  for (const alias of aliases) {
+    const found = entityByNameForAlias(imports, alias, entityName);
+    if (found) return found;
+  }
+  return void 0;
+}
+function ownedTraitEntryFor(imports, alias, traitName) {
+  const imported = imports.orbitals.get(alias);
+  if (!imported) return void 0;
+  const owner = importedOrbitals(imported).find(
+    (o) => findTraitEntryInOrbital(o, traitName) !== null
+  );
+  if (!owner || !isInlineEntity(owner.entity)) return void 0;
+  return { owner, ownerEntity: owner.entity, entry: findTraitEntryInOrbital(owner, traitName) };
+}
+function boundTraitOrbitalBinding(imports, alias, traitName) {
+  const imported = imports.orbitals.get(alias);
+  if (imported?.resolvedOrbitals) {
+    for (const ro of imported.resolvedOrbitals) {
+      const entry = findTraitEntryInOrbital(ro.original, traitName);
+      if (!entry) continue;
+      const bound2 = entry.linkedEntity;
+      const resolvedEntities = [ro.entity, ...ro.auxiliaryEntities ?? []];
+      const boundEntity2 = bound2 !== void 0 ? resolvedEntities.find((e) => e.name === bound2) : void 0;
+      const requiredData2 = new Set(
+        ro.traits.find((rt) => rt.trait.name === traitName)?.trait.entityContract?.requires ?? []
+      );
+      return { owner: ro.original, ownerEntity: ro.entity, entity: boundEntity2 ?? ro.entity, requiredData: requiredData2 };
+    }
+  }
+  const owned = ownedTraitEntryFor(imports, alias, traitName);
+  if (!owned) return void 0;
+  const ownerEntities = inlineEntityRefsOf(owned.owner);
+  const bound = owned.entry?.linkedEntity;
+  const boundEntity = bound !== void 0 ? ownerEntities.find((e) => e.name === bound) : void 0;
+  const requiredData = new Set(
+    owned.entry && "stateMachine" in owned.entry ? owned.entry.entityContract?.requires ?? [] : []
+  );
+  return { owner: owned.owner, ownerEntity: owned.ownerEntity, entity: boundEntity ?? owned.ownerEntity, requiredData };
+}
+function auxEntitiesFromUnrebindTraitRefs(orbitalTraits, imports) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (e) => {
+    if (!seen.has(e.name)) {
+      seen.add(e.name);
+      out.push(e);
+    }
+  };
+  for (const tr of orbitalTraits) {
+    let ref;
+    let linkedEntity;
+    if (typeof tr === "string") {
+      ref = tr;
+    } else if ("ref" in tr) {
+      ref = tr.ref;
+      linkedEntity = tr.linkedEntity;
+    } else {
+      continue;
+    }
+    const parsed = parseImportedTraitRef(ref);
+    if (!parsed) continue;
+    const binding = boundTraitOrbitalBinding(imports, parsed.alias, parsed.traitName);
+    if (!binding) continue;
+    if (linkedEntity === void 0) {
+      push(binding.entity);
+    }
+    for (const e of inlineEntityRefsOf(binding.owner)) {
+      if (e.name !== binding.ownerEntity.name) push(e);
+    }
+  }
+  return out;
+}
+function rewriteSelfRelationTarget(field, oldName, newName, newId) {
+  if (field.type === "relation" && field.relation.entity === oldName) {
+    field.relation = { ...field.relation, entity: newName, entityId: newId };
+  }
+  if (field.type === "array" && field.items) {
+    rewriteSelfRelationTarget(field.items, oldName, newName, newId);
+  }
+  if (field.type === "object" && field.items) {
+    rewriteSelfRelationTarget(field.items, oldName, newName, newId);
+  }
+  if (field.properties) {
+    for (const key of Object.keys(field.properties)) {
+      rewriteSelfRelationTarget(field.properties[key], oldName, newName, newId);
+    }
+  }
+}
+function mergeImportedEntityFields(callerEntity, importedEntity, intrinsicOnly, requiredData) {
+  const existingNames = new Set(
+    callerEntity.fields.map((f) => f.name).filter((n) => n !== void 0)
+  );
+  const oldName = importedEntity.name;
+  const newName = callerEntity.name;
+  const newId = callerEntity.id;
+  for (const field of importedEntity.fields) {
+    if (intrinsicOnly && field.intrinsic !== true) continue;
+    if (field.name === void 0) continue;
+    if (requiredData.has(field.name) && field.intrinsic !== true) continue;
+    if (existingNames.has(field.name)) continue;
+    const cloned = structuredClone(field);
+    rewriteSelfRelationTarget(cloned, oldName, newName, newId);
+    callerEntity.fields.push(cloned);
+  }
+}
+function mergeImportedEntityFieldsIntoOrbital(orbitalTraits, entity, declaredAuxEntities, imports) {
+  const mergedAliases = /* @__PURE__ */ new Set();
+  const pending = [];
+  for (const tr of orbitalTraits) {
+    let ref;
+    let linkedEntity;
+    if (typeof tr === "string") {
+      ref = tr;
+    } else if ("ref" in tr) {
+      ref = tr.ref;
+      linkedEntity = tr.linkedEntity;
+    } else {
+      continue;
+    }
+    const parsed = parseImportedTraitRef(ref);
+    if (!parsed) continue;
+    const binding = boundTraitOrbitalBinding(imports, parsed.alias, parsed.traitName);
+    if (!binding) continue;
+    const carriesFields = linkedEntity !== void 0 ? true : binding.entity.name === entity.name;
+    if (!carriesFields) continue;
+    const key = `${parsed.alias}\0${parsed.traitName}`;
+    if (mergedAliases.has(key)) continue;
+    mergedAliases.add(key);
+    pending.push({
+      target: linkedEntity,
+      imported: binding.entity,
+      intrinsicOnly: linkedEntity === void 0,
+      requiredData: binding.requiredData
+    });
+  }
+  for (const pm of pending) {
+    const auxTarget = pm.target !== void 0 && pm.target !== entity.name ? declaredAuxEntities.find((e) => e.name === pm.target) : void 0;
+    mergeImportedEntityFields(auxTarget ?? entity, pm.imported, pm.intrinsicOnly, pm.requiredData);
+  }
+}
+function consumerEntityIdsOf(orbitals) {
+  const out = /* @__PURE__ */ new Map();
+  for (const orbital of orbitals) {
+    for (const entity of inlineEntityRefsOf(orbital)) {
+      if (entity.id) out.set(entity.name, entity.id);
+    }
+  }
+  return out;
+}
+function materializedPrimaryEntity(upstreamEntity, upstreamOrbitalId, ref, localName) {
+  const name = ref.entity ?? `${localName}${upstreamEntity.name}`;
+  const id = asEntityId(
+    deriveMaterializedId(upstreamEntity.id, upstreamOrbitalId, upstreamEntity.name, localName, "entity")
+  );
+  return { name, id };
+}
+function applyExtendFields(entity, extend, fieldSubs, consumerEntityIds, localName) {
+  if (!extend || extend.length === 0) return { entity, errors: [] };
+  const errors = [];
+  const taken = new Set(entity.fields.map((f) => f.name).filter((n) => Boolean(n)));
+  for (const target of fieldSubs.values()) taken.add(target);
+  const added = [];
+  for (const field of extend) {
+    const name = field.name;
+    if (!name) continue;
+    if (taken.has(name)) {
+      errors.push(
+        `Orbital "${localName}" declares extend field "${name}" but the upstream primary entity already has a field of that name after "fields {}" renames (ORB_O_EXTEND_FIELD_COLLISION)`
+      );
+      continue;
+    }
+    taken.add(name);
+    if (field.type === "relation" && !field.relation.entityId) {
+      const targetId = consumerEntityIds.get(field.relation.entity);
+      added.push(targetId ? { ...field, relation: { ...field.relation, entityId: targetId } } : field);
+      continue;
+    }
+    added.push(field);
+  }
+  if (added.length === 0) return { entity, errors };
+  return { entity: { ...entity, fields: [...entity.fields, ...added] }, errors };
+}
+function deriveMaterializedId(sourceId, upstreamOrbitalId, sourceName, localName, kind) {
+  const parent = sourceId ?? `${idPrefix(kind)}orbital-import-seed:${upstreamOrbitalId ?? "no-orbital-id"}:${sourceName}`;
+  return deriveId(parent, localName);
+}
+function navigatePathSegments(path) {
+  return path.split("/").filter((segment) => segment.length > 0);
+}
+function navigateParamStrippedPrefix(path) {
+  const segments = navigatePathSegments(path);
+  const last = segments[segments.length - 1];
+  if (last === void 0 || !last.startsWith(":")) return void 0;
+  return `/${segments.slice(0, -1).join("/")}/`;
+}
+function rewriteConcatPrefix(literalPrefix, pathMap) {
+  const normalized = literalPrefix.endsWith("/") ? literalPrefix : `${literalPrefix}/`;
+  for (const [upstreamPath, finalPath] of pathMap) {
+    const stripped = navigateParamStrippedPrefix(upstreamPath);
+    if (stripped === void 0 || stripped !== normalized) continue;
+    const finalStripped = navigateParamStrippedPrefix(finalPath);
+    if (finalStripped !== void 0) return finalStripped;
+  }
+  return void 0;
+}
+function rewriteNavigateTargets(node, pathMap) {
+  if (node === null || node === void 0) return node;
+  if (Array.isArray(node)) {
+    if (node[0] === "navigate" && node.length >= 2) {
+      const target = node[1];
+      if (typeof target === "string" && pathMap.has(target)) {
+        return [node[0], pathMap.get(target), ...node.slice(2).map((v) => rewriteNavigateTargets(v, pathMap))];
+      }
+      if (Array.isArray(target) && target[0] === "str/concat" && typeof target[1] === "string" && target[1].startsWith("/")) {
+        const rewrittenPrefix = rewriteConcatPrefix(target[1], pathMap);
+        const nextTarget = rewrittenPrefix !== void 0 ? [target[0], rewrittenPrefix, ...target.slice(2)] : target;
+        return [node[0], nextTarget, ...node.slice(2).map((v) => rewriteNavigateTargets(v, pathMap))];
+      }
+    }
+    return node.map((item) => rewriteNavigateTargets(item, pathMap));
+  }
+  if (typeof node !== "object") return node;
+  const next = {};
+  for (const [key, value] of Object.entries(node)) {
+    next[key] = rewriteNavigateTargets(value, pathMap);
+  }
+  return next;
+}
+function rewriteTraitNavigateTargets(trait, pathMap) {
+  if (pathMap.size === 0) return trait;
+  const rewrite = (v) => rewriteNavigateTargets(v, pathMap);
+  const next = { ...trait };
+  const sm = trait.stateMachine;
+  if (sm) {
+    next.stateMachine = {
+      ...sm,
+      transitions: (sm.transitions ?? []).map(
+        (t) => t.effects ? { ...t, effects: rewrite(t.effects) } : t
+      )
+    };
+  }
+  if (trait.ticks) {
+    next.ticks = trait.ticks.map((tick) => ({ ...tick, effects: rewrite(tick.effects) }));
+  }
+  if (trait.initialEffects) {
+    next.initialEffects = rewrite(trait.initialEffects);
+  }
+  return next;
+}
+function rewriteConfigPagePaths(node, pathMap) {
+  if (typeof node === "string") return pathMap.get(node) ?? node;
+  if (Array.isArray(node)) return node.map((item) => rewriteConfigPagePaths(item, pathMap));
+  if (node !== null && typeof node === "object") {
+    const next = {};
+    for (const [key, value] of Object.entries(node)) {
+      next[key] = rewriteConfigPagePaths(value, pathMap);
+    }
+    return next;
+  }
+  return node;
+}
+function rewriteTraitConfigPagePaths(trait, pathMap) {
+  if (pathMap.size === 0 || !trait.config) return trait;
+  const nextConfig = {};
+  for (const [key, field] of Object.entries(trait.config)) {
+    nextConfig[key] = field.default === void 0 ? field : { ...field, default: rewriteConfigPagePaths(field.default, pathMap) };
+  }
+  return { ...trait, config: nextConfig };
+}
+function foldUseConfigOverride(declared, override, context) {
+  if (!override) return declared;
+  const values = {};
+  for (const [key, field] of Object.entries(override)) {
+    if (!(key in declared)) {
+      refResolverLog.warn("use-config:unknown-knob", { ...context, key });
+      continue;
+    }
+    if (field.default !== void 0) values[key] = field.default;
+  }
+  return Object.keys(values).length > 0 ? overrideDeclaredKnobs(declared, values) : declared;
+}
+function forwardConsumerAppKnobs(folded, consumer) {
+  if (!consumer) return folded;
+  const forwards = {};
+  for (const [key, field] of Object.entries(folded)) {
+    const token = field.default;
+    if (typeof token !== "string" || !token.startsWith("@config.")) continue;
+    const source = token.slice("@config.".length);
+    if (source.includes(".") || !(source in consumer)) continue;
+    if (consumer[source].default === void 0) continue;
+    forwards[key] = source;
+  }
+  if (Object.keys(forwards).length === 0) return folded;
+  const next = { ...folded };
+  for (const [key, source] of Object.entries(forwards)) {
+    next[key] = { ...folded[key], default: consumer[source].default, forwardedFrom: `@config.${source}` };
+  }
+  return next;
+}
+var ReferenceResolver = class _ReferenceResolver {
+  loader;
+  options;
+  localTraits;
+  /** id-keyed mirror of `localTraits`, populated wherever the trait carries an `id`. */
+  localTraitsById = /* @__PURE__ */ new Map();
+  /** Import scope of each loaded source orbital, keyed by its source path. */
+  sourceImportsCache = /* @__PURE__ */ new Map();
+  /**
+   * {@link preResolveImportFile}'s cache, keyed by absolute source path —
+   * `null` for a file whose own pre-resolution failed (best-effort, cached
+   * too, so a repeat import doesn't retry a doomed resolve). Distinct from
+   * {@link sourceImportsCache} (raw import SCOPE, no trait resolution) —
+   * this holds the file's fully RESOLVED orbitals.
+   */
+  importFileResolveCache = /* @__PURE__ */ new Map();
+  loaderInitialized = false;
+  /** The schema's declared `config {}` — outermost rung of the forwarded-config chain (§4.5). */
+  schemaConfig;
+  /**
+   * Schema-wide CONSUMER entity NAME → id, growing as each of THIS
+   * schema's own orbitals finishes resolving. JS twin of the compiled
+   * path's `consumer_entity_ids` (`orbital-compiler/src/phases/inline/
+   * mod.rs`), extended the same way: once per orbital, right after it
+   * resolves. Extended ONLY by {@link noteResolvedEntityIds} — called by
+   * the free function {@link resolveSchema} after each of ITS OWN orbitals
+   * finishes — never automatically inside `resolve()` itself, so the
+   * nested `this.resolve()` call {@link materializeOrbitalRef} makes for an
+   * external upstream orbital (a DIFFERENT file, never this consumer
+   * schema) cannot pollute it.
+   */
+  schemaEntityIds = /* @__PURE__ */ new Map();
+  /**
+   * Entity NAME → id visible to the orbital CURRENTLY being resolved:
+   * {@link schemaEntityIds} (every name an EARLIER orbital in this schema
+   * already established) plus the current orbital's own declared primary +
+   * auxiliary entities — JS twin of the compiled path's per-orbital `entity_
+   * ids = consumer_entity_ids.clone(); entity_ids.extend(collect_orbital_
+   * entity_ids(orbital))`, timed the same way (before this orbital's own
+   * trait composition runs). Read by {@link applyLinkedEntityRename}'s call
+   * sites so a call-site `-> Entity` rebind can REFRESH (never merely drop)
+   * the trait's `entityRefIds` side-map when the rebind target's id is
+   * already known — the gap `std-api-gateway` exposed: `RouteOrbital`'s
+   * no-rebind `Audit.traits.AuditCaptureListener` pull establishes
+   * `AuditEntry`'s id; `GatewayUserOrbital`, resolved LATER in the same
+   * schema, rebinds `Browse.traits.BrowseItemBrowse -> AuditEntry` and must
+   * see it. `resolve()` re-sets this fresh at its own entry (no restore
+   * needed once it returns): nothing reads it once `resolve()` has
+   * returned, and no `resolve()` call is ever active while another is on
+   * this instance — the only recursive `this.resolve()` call
+   * (`materializeOrbitalRef`'s upstream re-resolve) runs strictly BEFORE
+   * `resolveSchema`'s own per-orbital loop begins, never nested inside it.
+   */
+  entityIdsInScope = /* @__PURE__ */ new Map();
+  /**
+   * Per-orbital name → the FINAL trait names {@link pullSiblingTraits}
+   * auto-pulled for it (`ResolvedOrbital.name` keyed, set once per `resolve()`
+   * call). JS twin of Rust's `pulled_by_orbital` (`inline/mod.rs`) — read by
+   * {@link uniquifyCrossOrbitalPulledSiblings}, run once by the free
+   * function {@link resolveSchema} AFTER every orbital in the schema has
+   * resolved, because the rename decision (does this pulled name collide
+   * with ANOTHER orbital's own declared trait name?) needs the WHOLE
+   * schema's roster, not just this orbital's — exactly why Rust's own
+   * `uniquify_cross_orbital_pulled_siblings` runs once, after its per-orbital
+   * inline loop, not inside `inline_orbital` itself.
+   */
+  pulledTraitNamesByOrbital = /* @__PURE__ */ new Map();
+  /**
+   * Seed {@link schemaEntityIds} with EVERY orbital's PRIMARY (+ any
+   * already-declared auxiliary) entity name → id, from the RAW pre-resolve
+   * schema — JS twin of the compiled path's `consumer_entity_ids` INITIAL
+   * build (`orbital-compiler/src/phases/inline/mod.rs`, `schema.orbitals
+   * .iter().flat_map(...)`), which scans ALL orbitals' primaries up front,
+   * before ANY of them inlines — not just the ones resolved so far. Without
+   * this, an EARLY-resolved orbital's own `entityRefIds` secondary
+   * references to a LATER orbital's primary entity (`RouteOrbital`'s
+   * `entityRefIds["RateBucket"]`, `RateBucket` being a DIFFERENT, not-yet-
+   * resolved orbital's own primary in `std-api-gateway`) would see nothing
+   * in {@link entityIdsInScope} and {@link consumerKnownEntityRebindSubs}
+   * would never refresh the stale atom-baked id. Called by {@link
+   * resolveSchema} ONCE, before its per-orbital loop begins; {@link
+   * noteResolvedEntityIds} then keeps widening past this seed with each
+   * orbital's post-resolve auxiliary discoveries (Gap #22, sibling pulls),
+   * same as before.
+   */
+  seedSchemaEntityIds(orbitals) {
+    const next = new Map(this.schemaEntityIds);
+    for (const orbital of orbitals) {
+      for (const e of inlineEntityRefsOf(orbital)) {
+        if (e.id) next.set(e.name, e.id);
+      }
+    }
+    this.schemaEntityIds = next;
+  }
+  /**
+   * Extend {@link schemaEntityIds} with a just-resolved orbital's FINAL
+   * entity set — primary + every auxiliary entity resolution carried in
+   * (including a no-rebind sibling pull's own bound entity,
+   * `ResolvedOrbital.auxiliaryEntities`). Mirrors the compiled path's
+   * `consumer_entity_ids.extend(collect_orbital_entity_ids(orbital))`,
+   * called the same way: once per orbital, immediately after it resolves.
+   * Called by {@link resolveSchema}'s own per-orbital loop only.
+   */
+  noteResolvedEntityIds(resolved) {
+    const next = new Map(this.schemaEntityIds);
+    if (resolved.entity.id) next.set(resolved.entity.name, resolved.entity.id);
+    for (const aux of resolved.auxiliaryEntities ?? []) {
+      if (aux.id) next.set(aux.name, aux.id);
+    }
+    this.schemaEntityIds = next;
+  }
+  /**
+   * Make auto-pulled sibling traits app-unique across orbitals — JS twin of
+   * Rust's `uniquify_cross_orbital_pulled_siblings` (`inline/mod.rs`), called
+   * by the free function {@link resolveSchema} once every orbital in the
+   * schema has resolved (mirroring Rust's own post-per-orbital-loop timing:
+   * the rename decision needs the WHOLE schema's trait-name roster, built
+   * fresh here rather than grown incrementally like {@link schemaEntityIds}).
+   * An auto-pulled sibling keeps its source name within its OWN orbital, so a
+   * `@trait.<Sibling>` reference inside that orbital still resolves — but
+   * when TWO orbitals in the same schema each declare (pulled OR explicit) a
+   * trait of the SAME name, that name collides app-wide. Only renames a
+   * PULLED copy (never an explicitly-authored trait ref —
+   * {@link pulledTraitNamesByOrbital} is the eligibility set) whose name is
+   * ALSO declared by at least one OTHER orbital, prefixing it with the
+   * owning orbital's own name; the prefixed name must itself be free
+   * schema-wide or the rename is skipped (matches Rust: a collision on the
+   * PREFIXED name is left for the validator, never silently double-renamed).
+   * Mutates `orbitals`' traits in place, same mutation style as
+   * {@link pullSiblingTraits}.
+   */
+  uniquifyCrossOrbitalPulledSiblings(orbitals) {
+    if (this.pulledTraitNamesByOrbital.size === 0) return;
+    const nameOrbitalCount = /* @__PURE__ */ new Map();
+    for (const orbital of orbitals) {
+      const local = new Set(
+        orbital.traits.map((rt) => rt.trait.name).filter((n) => Boolean(n))
+      );
+      for (const name of local) {
+        nameOrbitalCount.set(name, (nameOrbitalCount.get(name) ?? 0) + 1);
+      }
+    }
+    for (const orbital of orbitals) {
+      const pulledNames = this.pulledTraitNamesByOrbital.get(orbital.name);
+      if (!pulledNames || pulledNames.size === 0) continue;
+      const renames = /* @__PURE__ */ new Map();
+      for (const oldName of pulledNames) {
+        if ((nameOrbitalCount.get(oldName) ?? 0) <= 1) continue;
+        const newName = `${orbital.name}${oldName}`;
+        if (nameOrbitalCount.has(newName)) continue;
+        renames.set(oldName, newName);
+      }
+      if (renames.size === 0) continue;
+      for (const rt of orbital.traits) {
+        if (rt.trait.name && renames.has(rt.trait.name)) {
+          rt.trait = { ...rt.trait, name: renames.get(rt.trait.name) };
+        }
+      }
+      const idByName = /* @__PURE__ */ new Map();
+      for (const rt of orbital.traits) {
+        if (rt.trait.name) idByName.set(rt.trait.name, rt.trait.id);
+      }
+      for (const rt of orbital.traits) {
+        rt.trait = renameTraitEmbeds(rt.trait, renames);
+        rt.trait = rewriteListenSources(rt.trait, renames, idByName);
+      }
+    }
+  }
+  constructor(options) {
+    this.options = options;
+    this.loader = options.loader;
+    this.schemaConfig = options.schemaConfig;
+    this.localTraits = options.localTraits ?? /* @__PURE__ */ new Map();
+    for (const trait of this.localTraits.values()) {
+      if (trait.id) {
+        this.localTraitsById.set(trait.id, trait);
+      }
+    }
+  }
+  async ensureLoader() {
+    if (this.loader || this.loaderInitialized) return;
+    this.loaderInitialized = true;
+    try {
+      const { ExternalOrbitalLoader } = await import('./external-loader-CISUEINQ.js');
+      this.loader = new ExternalOrbitalLoader(this.options);
+    } catch {
+    }
+  }
+  /**
+   * Resolve all references in an orbital.
+   */
+  async resolve(orbital, sourcePath, chain, opts) {
+    const errors = [];
+    const warnings = [];
+    const importChain = chain ?? { push: () => null, pop: () => {
+    }, clone() {
+      return this;
+    } };
+    this.entityIdsInScope = new Map([...this.schemaEntityIds, ...inlineEntityRefsOf(orbital).flatMap((e) => e.id ? [[e.name, e.id]] : [])]);
+    const traitsList = orbital.traits ?? [];
+    const alreadyResolved = traitsList.length > 0 && traitsList.every((t) => isInlineTrait(t));
+    const importsResult = alreadyResolved ? { success: true, data: { orbitals: /* @__PURE__ */ new Map(), idIndex: /* @__PURE__ */ new Map() }} : await this.resolveImports(orbital.uses ?? [], sourcePath, importChain);
+    if (!importsResult.success) {
+      return { success: false, errors: importsResult.errors };
+    }
+    const imports = importsResult.data;
+    imports.idIndex = buildIdIndex(orbital, imports.orbitals);
+    const gap22AuxEntities = auxEntitiesFromUnrebindTraitRefs(orbital.traits ?? [], imports);
+    if (gap22AuxEntities.length > 0) {
+      const next = new Map(this.entityIdsInScope);
+      for (const e of gap22AuxEntities) {
+        if (e.id && !next.has(e.name)) next.set(e.name, e.id);
+      }
+      this.entityIdsInScope = next;
+    }
+    if (isInlineEntity(orbital.entity)) {
+      mergeImportedEntityFieldsIntoOrbital(
+        orbital.traits ?? [],
+        orbital.entity,
+        (orbital.auxiliaryEntities ?? []).filter(isInlineEntity),
+        imports
+      );
+    }
+    const entityResult = this.resolveEntity(orbital.entity, imports);
+    if (!entityResult.success) {
+      errors.push(...entityResult.errors);
+    }
+    const traitsResult = await this.resolveTraits(orbital.traits, imports, importChain, orbital.config);
+    if (!traitsResult.success) {
+      errors.push(...traitsResult.errors);
+    }
+    const pagesResult = await this.resolvePages(orbital.pages, imports, importChain);
+    if (!pagesResult.success) {
+      errors.push(...pagesResult.errors);
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    if (!entityResult.success || !traitsResult.success || !pagesResult.success) {
+      return { success: false, errors: ["Internal error: unexpected failure state"] };
+    }
+    const { errors: pullErrors, auxEntities: pulledAuxEntities, pulledNames } = await this.pullSiblingTraits(
+      traitsResult.data,
+      imports,
+      importChain,
+      orbital.config
+    );
+    if (pullErrors.length > 0) {
       return { success: false, errors: pullErrors };
     }
+    this.pulledTraitNamesByOrbital.set(orbital.name, pulledNames);
+    const known = /* @__PURE__ */ new Set([entityResult.data.entity.name]);
+    const declaredAux = (orbital.auxiliaryEntities ?? []).filter(isInlineEntity);
+    for (const e of declaredAux) known.add(e.name);
+    const combined = [...declaredAux];
+    for (const e of [...gap22AuxEntities, ...pulledAuxEntities]) {
+      if (!known.has(e.name)) {
+        known.add(e.name);
+        combined.push(e);
+      }
+    }
+    const resolvedAuxEntities = combined.length > 0 ? combined : void 0;
     for (const resolvedTrait of traitsResult.data) {
       resolvedTrait.trait = resolveEntityTokensById(resolvedTrait.trait, imports.idIndex);
       resolvedTrait.trait = resolveConfigRefsById(resolvedTrait.trait, imports.idIndex);
@@ -4277,6 +5752,14 @@ var ReferenceResolver = class {
       }
       throw e;
     }
+    if (!opts?.skipTypeParamSentinels) {
+      resolveOrbitalTypeParamSentinels(
+        traitsResult.data,
+        entityResult.data.entity,
+        resolvedAuxEntities ?? [],
+        orbital.types
+      );
+    }
     return {
       success: true,
       data: {
@@ -4284,6 +5767,7 @@ var ReferenceResolver = class {
         entity: entityResult.data.entity,
         entitySource: entityResult.data.source,
         traits: traitsResult.data,
+        ...resolvedAuxEntities ? { auxiliaryEntities: resolvedAuxEntities } : {},
         pages: pagesResult.data,
         imports,
         original: orbital
@@ -4291,6 +5775,98 @@ var ReferenceResolver = class {
       warnings
     };
   }
+  /**
+   * Pre-resolve one imported FILE's own orbitals to completion — its own
+   * `uses` (recursively, through THIS same method), its own trait refs,
+   * its own sibling pulls, its own entity-ref-id rebinds — BEFORE the
+   * consumer that names this alias ever folds or pulls from it. JS twin
+   * of Rust's per-`uses` recursive `inline_orbital` call (`orbital-
+   * compiler/src/phases/inline/mod.rs:1001-1013`): every `uses` alias's
+   * OWN orbitals are inlined to completion, ahead of `ctx.add_alias_multi`
+   * registering the alias for the consumer's own lookups. Without this, a
+   * sibling-pull collision that is a genuine top-level PEER collision
+   * INSIDE the imported file (`std-approval-request.orb`'s
+   * `InlineBrowseItemBrowse6`/`…10`, both `ref: Dense.traits.
+   * BrowseItemBrowse`, each embedding `@trait.DataGrid1`) never becomes
+   * visible as a peer collision to the CONSUMER's own {@link
+   * pullSiblingTraits} call — it arrives already flattened one level
+   * deeper, sharing one JS-visible owner (see that method's own
+   * drain-order doc for the full trace this ports).
+   *
+   * Cached per absolute `sourcePath` ({@link importFileResolveCache}) —
+   * "a file imported twice resolves once" — so the cache must not bake in
+   * any ONE call site's `uses { config }` override: the child resolver
+   * below is seeded with this FILE's own raw, un-folded `config {}`
+   * (`fileSchemaConfig`), never a folded override. A genuinely
+   * call-site-configured explicit ref (`Alias.traits.X { config: {…} }`)
+   * still resolves through the pre-existing lazy path
+   * ({@link resolveTraitEntry} / {@link resolveTraitRefString}), which
+   * this cache does not touch.
+   *
+   * Runs on a FRESH child `ReferenceResolver`, never `this` — `resolve()`'s
+   * own `entityIdsInScope` / `schemaEntityIds` / `pulledTraitNamesByOrbital`
+   * are single mutable instance state scoped to ONE active `resolve()` call
+   * tree (see {@link entityIdsInScope}'s own doc: "no `resolve()` call is
+   * ever active while another is on this instance"); reusing `this` here
+   * would nest a `resolve()` call inside the CONSUMER's own still-active
+   * `resolve()` → `resolveImports` call and corrupt that state once this
+   * nested call returns. The child reuses `this.loader` (and therefore its
+   * underlying `LoaderCache`) so raw parsing still dedupes exactly as
+   * before. `chain` is threaded through unchanged (not cloned, matching
+   * every other cross-call `chain` hand-off in this file) so genuine `uses`
+   * cycles are still caught by the loader.
+   *
+   * Mirrors {@link resolveSchema}'s own orchestration (flatten orbital
+   * references → collect local traits → seed schema entity ids →
+   * per-orbital `resolve()` → `uniquifyCrossOrbitalPulledSiblings`) rather
+   * than calling that free function directly — it accepts no `chain`
+   * parameter, so a direct call would silently drop cycle protection one
+   * level in.
+   *
+   * Best-effort: returns `null` (never throws) on any failure — a caller
+   * falls back to the pre-existing raw-ref walk, matching this file's
+   * other best-effort pre-passes (e.g. {@link precomputeReferenceFormPrimaryIds}).
+   */
+  async preResolveImportFile(fileOrbitals, sourcePath, fileSchemaConfig, chain) {
+    const cached = this.importFileResolveCache.get(sourcePath);
+    if (cached !== void 0) return cached;
+    let result;
+    try {
+      result = await this.preResolveImportFileUncached(fileOrbitals, sourcePath, fileSchemaConfig, chain);
+    } catch {
+      result = null;
+    }
+    this.importFileResolveCache.set(sourcePath, result);
+    return result;
+  }
+  async preResolveImportFileUncached(fileOrbitals, sourcePath, fileSchemaConfig, chain) {
+    const child = new _ReferenceResolver({
+      ...this.options,
+      loader: this.loader,
+      schemaConfig: fileSchemaConfig
+    });
+    const fileSchema = {
+      name: sourcePath,
+      orbitals: fileOrbitals,
+      ...fileSchemaConfig ? { config: fileSchemaConfig } : {}
+    };
+    const flattenResult = await child.resolveOrbitalImports(fileSchema, { skipTypeParamSentinels: true });
+    if (!flattenResult.success) return null;
+    const orbitals = flattenResult.data;
+    const inlineTraits = orbitals.flatMap(
+      (o) => o.traits.filter((t) => typeof t !== "string" && "stateMachine" in t)
+    );
+    child.addLocalTraits(inlineTraits);
+    child.seedSchemaEntityIds(orbitals);
+    const resolved = [];
+    for (const orbital of orbitals) {
+      const result = await child.resolve(orbital, sourcePath, chain, { skipTypeParamSentinels: true });
+      if (!result.success) return null;
+      resolved.push(result.data);
+      child.noteResolvedEntityIds(result.data);
+    }
+    return resolved;
+  }
   /**
    * Resolve `uses` declarations to loaded orbitals.
    */
@@ -4304,6 +5880,10 @@ var ReferenceResolver = class {
         warnings: ["External loading skipped"]
       };
     }
+    const effectiveChain = chain ?? { push: () => null, pop: () => {
+    }, clone() {
+      return this;
+    } };
     for (const use of uses) {
       if (orbitals.has(use.as)) {
         errors.push(`Duplicate import alias: ${use.as}`);
@@ -4318,18 +5898,32 @@ var ReferenceResolver = class {
         use.from,
         void 0,
         sourcePath,
-        chain
+        effectiveChain
       );
       if (!loadResult.success) {
         errors.push(`Failed to load "${use.from}" as "${use.as}": ${loadResult.error}`);
         continue;
       }
+      const fileOrbitals = loadResult.data.orbitals ?? [loadResult.data.orbital];
+      const resolvedOrbitals = await this.preResolveImportFile(
+        fileOrbitals,
+        loadResult.data.sourcePath,
+        loadResult.data.schemaConfig,
+        effectiveChain
+      );
       orbitals.set(use.as, {
         alias: use.as,
         from: use.from,
         orbital: loadResult.data.orbital,
-        orbitals: loadResult.data.orbitals ?? [loadResult.data.orbital],
-        sourcePath: loadResult.data.sourcePath
+        orbitals: fileOrbitals,
+        sourcePath: loadResult.data.sourcePath,
+        ...resolvedOrbitals ? { resolvedOrbitals } : {},
+        ...loadResult.data.schemaConfig ? {
+          schemaConfig: forwardConsumerAppKnobs(
+            foldUseConfigOverride(loadResult.data.schemaConfig, use.config, use),
+            this.schemaConfig
+          )
+        } : {}
       });
     }
     if (errors.length > 0) {
@@ -4420,14 +6014,79 @@ var ReferenceResolver = class {
     }
     return entityRef;
   }
+  /**
+   * The ATOM's OWN trait `alias.traits.traitName` resolves to — no call-site
+   * overrides applied (`callSiteConfig` omitted) — so its DECLARED
+   * `linkedEntity` can drive {@link buildAliasEntityRenames}. Same lookup
+   * `resolveTraitRefString`'s imported branch performs to find the base
+   * `trait` before any rebind, factored out so the pre-pass and the main
+   * resolve share one lookup rather than two. `null` when the alias or
+   * trait cannot be found — the pre-pass simply skips that entry, same as a
+   * lookup failure anywhere else in this best-effort pass.
+   */
+  async atomOwnTrait(alias, traitName, imports, chain) {
+    const imported = imports.orbitals.get(alias);
+    if (!imported) return null;
+    for (const o of importedOrbitals(imported)) {
+      const entry = findTraitEntryInOrbital(o, traitName);
+      if (!entry) continue;
+      const entryResolved = await this.resolveTraitEntry(imported, entry, traitName, chain, imports);
+      return entryResolved.success ? entryResolved.data.trait : null;
+    }
+    return null;
+  }
+  /**
+   * Alias-scoped cross-trait entity-rebind propagation — JS twin of Rust's
+   * `alias_entity_renames` pre-pass (`inline/trait.rs::inline_traits`). One
+   * explicit pull's `linkedEntity` override (`Button.traits.ButtonRender ->
+   * Route`) establishes a rebind (the atom's OWN declared `linkedEntity` →
+   * the override) that a SIBLING pull from the SAME alias with NO rebind of
+   * its own (`Button.traits.ButtonRender`, no `->`) never sees through
+   * {@link applyLinkedEntityRename} — that call only ever knows ITS OWN
+   * delta. But the no-rebind pull's `entityRefIds` side-map can still carry
+   * a SECONDARY, positional reference to that same atom-local name (a
+   * "self" entry keyed by the atom's own bound entity), which nothing else
+   * rewrites — `std-api-gateway`'s `RouteOrbital.InlineButtonRender3`
+   * (`Button.traits.ButtonRender`, no rebind) recovers `entityRefIds`'
+   * `ButtonItem` key to `Route` only because `InlineButtonRender9` (`Button.
+   * traits.ButtonRender -> Route`) established the rebind earlier in the
+   * SAME orbital's `traits` list. Scanned once per orbital, over every
+   * EXPLICIT `Alias.traits.X -> Y` entry in `traitRefs`: `(alias, atom's
+   * declared linkedEntity) -> override`. First rebind for a given `(alias,
+   * atomLocal)` pair wins (`Map.set` only on a fresh key), matching Rust's
+   * `.or_insert_with`.
+   */
+  async buildAliasEntityRenames(traitRefs, imports, chain) {
+    const out = /* @__PURE__ */ new Map();
+    for (const traitRef of traitRefs) {
+      if (typeof traitRef === "string" || "stateMachine" in traitRef || !("ref" in traitRef)) continue;
+      const refObj = traitRef;
+      if (!refObj.linkedEntity) continue;
+      const parsed = parseImportedTraitRef(refObj.ref);
+      if (!parsed) continue;
+      const atomTrait = await this.atomOwnTrait(parsed.alias, parsed.traitName, imports, chain);
+      const atomLocal = atomTrait?.linkedEntity;
+      if (!atomLocal || atomLocal === refObj.linkedEntity) continue;
+      const forAlias = out.get(parsed.alias) ?? /* @__PURE__ */ new Map();
+      if (!forAlias.has(atomLocal)) forAlias.set(atomLocal, refObj.linkedEntity);
+      out.set(parsed.alias, forAlias);
+    }
+    return out;
+  }
   /**
    * Resolve trait references.
    */
-  resolveTraits(traitRefs, imports) {
+  async resolveTraits(traitRefs, imports, chain, orbitalConfig) {
     const errors = [];
     const resolved = [];
+    const embedCtx = {
+      traitRefs,
+      embedGraph: buildEmbedGraph(traitRefs),
+      orbitalConfig
+    };
+    const aliasEntityRenames = await this.buildAliasEntityRenames(traitRefs, imports, chain);
     for (const traitRef of traitRefs) {
-      const result = this.resolveTraitRef(traitRef, imports);
+      const result = await this.resolveTraitRef(traitRef, imports, chain, embedCtx, aliasEntityRenames);
       if (!result.success) {
         errors.push(...result.errors);
       } else {
@@ -4458,6 +6117,99 @@ var ReferenceResolver = class {
     this.sourceImportsCache.set(key, result.data);
     return result.data;
   }
+  /**
+   * The concrete base `Trait` a trait entry (found under `localName` in
+   * `imported`) resolves to — an inline entry resolves its own
+   * `@config.<knob>` emit refs against `callSiteConfig` (the ref hop that
+   * led here, e.g. `std-approval-gate`'s `CloseButton = Button.traits.
+   * ButtonRender { config: { action: CLOSE } }` resolving `ButtonRender`
+   * itself); a ref-shaped entry (an atom's sub-view declared `trait X =
+   * Y.traits.Z {…}` INSIDE the source atom, e.g. `std-note`'s
+   * `NoteSubpages = RecordDetail.traits.RecordItemDetail`) recurses through
+   * that source's own import scope via {@link importsOfSource} — the
+   * entry's own declared overrides are its call site. Single owner for
+   * `pullSiblingTraits`' sibling pull and `resolveTraitRefString`'s
+   * imported branch, both of which used to reach `findTraitInOrbital`'s
+   * `stateMachine`-gated lookup (its ref arm did nothing), silently failing
+   * to resolve a nested ref (ledger (i)).
+   *
+   * `callSiteConfig` MUST be threaded by any caller that goes on to fold a
+   * call-site config of its own onto the returned trait
+   * (`resolveTraitRefString`'s ref-imported branch, ledger (o)) — the
+   * `@config.<knob>` emit-name substitution is destructive
+   * (`resolveConfigRefEmitNames` rewrites the marker to a concrete literal
+   * in place), so resolving it here with the WRONG effective config
+   * (the atom's own bare default, absent the override) permanently loses
+   * the override: a second `resolveConfigRefEmitNames` call downstream sees
+   * no more `@config.<knob>` marker to substitute and silently no-ops.
+   * `pullSiblingTraits` (no further fold of its own) omits it, matching its
+   * prior no-callSiteConfig behavior exactly.
+   */
+  async resolveTraitEntry(imported, entry, localName, chain, homeImports, callSiteConfig) {
+    if ("stateMachine" in entry) {
+      const { trait, errors } = resolveConfigRefEmitNames(entry, callSiteConfig);
+      if (errors.length > 0) return { success: false, errors };
+      return {
+        success: true,
+        data: { trait, embedScope: { imports: homeImports, alias: imported.alias } },
+        warnings: []
+      };
+    }
+    const refObj = entry;
+    const srcImports = await this.importsOfSource(imported, chain);
+    if (!srcImports) {
+      return {
+        success: false,
+        errors: [
+          `Trait "${localName}" in imported behavior could not resolve its own import scope to follow ref "${refObj.ref}"`
+        ]
+      };
+    }
+    const nested = await this.resolveTraitRefString(
+      refObj.ref,
+      srcImports,
+      chain,
+      refObj.config,
+      refObj.linkedEntity,
+      refObj.name ?? localName,
+      refObj.events,
+      refObj.listens,
+      refObj.refId,
+      refObj.typeArgs
+    );
+    if (!nested.success) return nested;
+    return {
+      success: true,
+      data: {
+        trait: nested.data.trait,
+        embedScope: nested.data.embedScope ?? { imports: srcImports, alias: imported.alias },
+        ...nested.data.typeArgs !== void 0 ? { typeArgs: nested.data.typeArgs } : {}
+      },
+      warnings: nested.warnings
+    };
+  }
+  /**
+   * The concrete `Page` a page entry (found under `localName` in `imported`)
+   * resolves to — an inline `Page` passes through; a `PageRefObject` (a
+   * re-exported page declared inside the SOURCE orbital's own `pages {}`,
+   * {@link findPageEntryInOrbital}'s ref arm) recurses through that source's
+   * own import scope via {@link importsOfSource} and
+   * {@link resolvePageRefObject} — the page twin of {@link resolveTraitEntry}
+   * (nested refs, ledger (i)).
+   */
+  async resolvePageEntry(imported, entry, chain) {
+    if (!("ref" in entry)) return { success: true, data: { page: entry }, warnings: [] };
+    const srcImports = await this.importsOfSource(imported, chain);
+    if (!srcImports) {
+      return {
+        success: false,
+        errors: [`Page in imported behavior could not resolve its own import scope to follow ref "${entry.ref}"`]
+      };
+    }
+    const nested = await this.resolvePageRefObject(entry, srcImports, chain);
+    if (!nested.success) return nested;
+    return { success: true, data: { page: nested.data.page }, warnings: nested.warnings };
+  }
   /**
    * Sibling-trait auto-pull — the JS twin of the compiler's
    * `phases/inline/trait.rs` pass, appending to `resolved` in place.
@@ -4479,7 +6231,8 @@ var ReferenceResolver = class {
    * source name; later owners pull under `<Owner><Sibling>` — unique by
    * construction, since owner names are unique within the orbital.
    */
-  async pullSiblingTraits(resolved, imports, chain) {
+  async pullSiblingTraits(resolved, imports, chain, orbitalConfig) {
+    const auxEntities = [];
     const work = [];
     const ownerSubs = /* @__PURE__ */ new Map();
     const subsFor = (owner) => {
@@ -4495,18 +6248,48 @@ var ReferenceResolver = class {
       const owner = rt.trait.name;
       subsFor(owner).set(rt.source.traitName, owner);
       for (const sibling of traitEmbedNamesOf(rt.trait)) {
-        work.push({ alias: rt.source.alias, sibling, linkedEntity: rt.linkedEntity, parent: owner, owner });
+        work.push({
+          alias: rt.source.alias,
+          fallback: rt.embedScope,
+          sibling,
+          linkedEntity: rt.linkedEntity,
+          parent: owner,
+          owner,
+          // Top-level SEED — always starts with the raw-walk-first gate
+          // (see {@link PullItem.preResolvedScope}'s own doc).
+          preResolvedScope: void 0
+        });
       }
     }
-    if (work.length === 0) return [];
+    if (work.length === 0) return { errors: [], auxEntities: [], pulledNames: /* @__PURE__ */ new Set() };
     const errors = [];
     const consumerDeclared = new Set(resolved.map((r) => r.trait.name).filter(Boolean));
+    const consumerDeclaredProvenance = /* @__PURE__ */ new Map();
+    for (const rt of resolved) {
+      if (rt.source.type === "imported" && rt.trait.name) {
+        consumerDeclaredProvenance.set(rt.trait.name, { alias: rt.source.alias, traitName: rt.source.traitName });
+      }
+    }
     const seen = new Set(consumerDeclared);
     const visited = /* @__PURE__ */ new Set();
     const pulledAs = /* @__PURE__ */ new Map();
     const ownerOf = /* @__PURE__ */ new Map();
+    const parentOf = /* @__PURE__ */ new Map();
     const parentRewrites = /* @__PURE__ */ new Map();
     const pulled = [];
+    const embedderChain2 = (finalName) => {
+      const chain2 = [];
+      const seenNames = /* @__PURE__ */ new Set();
+      let cur = finalName;
+      while (cur !== void 0 && !seenNames.has(cur)) {
+        seenNames.add(cur);
+        const t = resolved.find((r) => r.trait.name === cur)?.trait ?? pulled.find((r) => r.trait.name === cur)?.trait;
+        if (!t) break;
+        if (t.config) chain2.push(t.config);
+        cur = parentOf.get(cur);
+      }
+      return chain2;
+    };
     const noteRewrite = (parent, from, to) => {
       let m = parentRewrites.get(parent);
       if (!m) {
@@ -4516,8 +6299,8 @@ var ReferenceResolver = class {
       m.set(from, to);
     };
     for (let item = work.pop(); item !== void 0; item = work.pop()) {
-      const { alias, sibling, linkedEntity, parent, owner } = item;
-      const pullKey = `${alias}\0${sibling}\0${owner}`;
+      const { alias, fallback, sibling, linkedEntity, parent, owner, preResolvedScope } = item;
+      const pullKey = `${alias} ${sibling} ${owner} ${parent}`;
       const existing = pulledAs.get(pullKey);
       if (existing !== void 0) {
         if (existing !== sibling) noteRewrite(parent, sibling, existing);
@@ -4525,73 +6308,122 @@ var ReferenceResolver = class {
       }
       let finalName = sibling;
       if (seen.has(sibling)) {
-        if (consumerDeclared.has(sibling)) continue;
-        finalName = `${owner}${sibling}`;
+        const provenance = consumerDeclaredProvenance.get(sibling);
+        if (consumerDeclared.has(sibling) && provenance?.alias === alias && provenance.traitName === sibling) {
+          continue;
+        }
+        finalName = `${parent}${sibling}`;
         if (seen.has(finalName)) continue;
       }
       if (visited.has(pullKey)) continue;
       visited.add(pullKey);
-      const imported = imports.orbitals.get(alias);
-      if (!imported) continue;
-      let atomEntry = null;
-      for (const o of importedOrbitals(imported)) {
-        atomEntry = findTraitEntryInOrbital(o, sibling);
-        if (atomEntry) break;
-      }
-      if (!atomEntry) continue;
+      let searchImports = imports;
+      let searchAlias = alias;
       let atomTrait;
-      if ("stateMachine" in atomEntry) {
-        const { trait: cfgResolved, errors: cfgErrors } = resolveConfigRefEmitNames(
-          atomEntry
-        );
-        if (cfgErrors.length > 0) {
-          errors.push(...cfgErrors);
-          continue;
+      let childScope;
+      let foundTypeArgs;
+      let childPreResolvedScope;
+      if (preResolvedScope) {
+        const found = preResolvedScope.traits.find((rt) => rt.trait.name === sibling);
+        if (found) {
+          atomTrait = found.trait;
+          childScope = { imports: searchImports, alias: searchAlias };
+          foundTypeArgs = found.typeArgs;
+          childPreResolvedScope = preResolvedScope;
         }
-        atomTrait = cfgResolved;
-      } else {
-        const srcImports = await this.importsOfSource(imported, chain);
-        if (!srcImports) continue;
-        const refObj = atomEntry;
-        const nested = this.resolveTraitRefString(
-          refObj.ref,
-          srcImports,
-          refObj.config,
-          refObj.linkedEntity,
-          refObj.name ?? sibling,
-          refObj.events,
-          refObj.listens,
-          refObj.refId
-        );
-        if (!nested.success) {
-          errors.push(...nested.errors);
-          continue;
+      }
+      if (!atomTrait) {
+        let imported = imports.orbitals.get(alias);
+        let atomEntry = null;
+        let atomOrbitalIndex = -1;
+        if (imported) {
+          const list = importedOrbitals(imported);
+          for (let i = 0; i < list.length; i++) {
+            atomEntry = findTraitEntryInOrbital(list[i], sibling);
+            if (atomEntry) {
+              atomOrbitalIndex = i;
+              break;
+            }
+          }
+        }
+        if (!atomEntry && fallback) {
+          const fbImported = fallback.imports.orbitals.get(fallback.alias);
+          if (fbImported) {
+            const list = importedOrbitals(fbImported);
+            for (let i = 0; i < list.length; i++) {
+              atomEntry = findTraitEntryInOrbital(list[i], sibling);
+              if (atomEntry) {
+                imported = fbImported;
+                searchImports = fallback.imports;
+                searchAlias = fallback.alias;
+                atomOrbitalIndex = i;
+                break;
+              }
+            }
+          }
+        }
+        if (!imported || !atomEntry) continue;
+        const preResolvedOrbital = imported.resolvedOrbitals?.[atomOrbitalIndex];
+        const preResolved = preResolvedOrbital?.traits.find((rt) => rt.trait.name === sibling);
+        if (preResolved) {
+          atomTrait = preResolved.trait;
+          childScope = { imports: searchImports, alias: searchAlias };
+          foundTypeArgs = preResolved.typeArgs;
+          childPreResolvedScope = preResolvedOrbital;
+        } else {
+          const entryResolved = await this.resolveTraitEntry(imported, atomEntry, sibling, chain, searchImports);
+          if (!entryResolved.success) {
+            errors.push(...entryResolved.errors);
+            continue;
+          }
+          atomTrait = entryResolved.data.trait;
+          childScope = entryResolved.data.embedScope;
+          foundTypeArgs = entryResolved.data.typeArgs;
         }
-        atomTrait = nested.data.trait;
       }
-      const embedder = resolved.find((r) => r.trait.name === parent)?.trait ?? pulled.find((r) => r.trait.name === parent)?.trait;
-      let copy = resolveForwardedSiblingConfig(
-        applyLinkedEntityRename(atomTrait, linkedEntity),
-        embedder
+      if (!atomTrait || !childScope) continue;
+      const nextFallback = childScope.alias === searchAlias && childScope.imports === searchImports ? void 0 : childScope;
+      let copy = resolveForwardedSiblingConfigFrom(
+        applyLinkedEntityRename(atomTrait, linkedEntity, this.entityIdsInScope),
+        embedderChain2(parent),
+        orbitalConfig,
+        this.schemaConfig
       );
       if (finalName !== sibling) {
         copy = { ...copy, name: finalName };
         noteRewrite(parent, sibling, finalName);
       }
+      const childParent = childPreResolvedScope ? parent : finalName;
       for (const next of traitEmbedNamesOf(copy)) {
-        work.push({ alias, sibling: next, linkedEntity, parent: finalName, owner });
+        work.push({
+          alias,
+          fallback: nextFallback,
+          sibling: next,
+          linkedEntity,
+          parent: childParent,
+          owner,
+          preResolvedScope: childPreResolvedScope
+        });
       }
       pulledAs.set(pullKey, finalName);
       subsFor(owner).set(sibling, finalName);
       ownerOf.set(finalName, owner);
+      parentOf.set(finalName, parent);
       seen.add(finalName);
       pulled.push({
         trait: copy,
         source: { type: "imported", alias, traitName: sibling },
-        ...linkedEntity !== void 0 ? { linkedEntity } : {}
+        ...linkedEntity !== void 0 ? { linkedEntity } : {},
+        ...foundTypeArgs !== void 0 ? { typeArgs: foundTypeArgs } : {}
       });
+      if (copy.linkedEntity !== void 0) {
+        const aux = entityByNameForAlias(imports, alias, copy.linkedEntity) ?? entityByNameAnyAlias(imports, copy.linkedEntity);
+        if (aux) auxEntities.push(aux);
+      }
+    }
+    if (pulled.length === 0 && parentRewrites.size === 0) {
+      return { errors, auxEntities, pulledNames: /* @__PURE__ */ new Set() };
     }
-    if (pulled.length === 0 && parentRewrites.size === 0) return errors;
     const applyRewrites = (rt) => {
       const subs = rt.trait.name ? parentRewrites.get(rt.trait.name) : void 0;
       if (subs) rt.trait = renameTraitEmbeds(rt.trait, subs);
@@ -4603,39 +6435,29 @@ var ReferenceResolver = class {
       if (rt.trait.name) idByName.set(rt.trait.name, rt.trait.id);
     }
     for (const rt of pulled) {
-      const listens = rt.trait.listens;
       const owner = rt.trait.name ? ownerOf.get(rt.trait.name) : void 0;
       const subs = owner ? ownerSubs.get(owner) : void 0;
-      if (!listens || listens.length === 0 || !subs) continue;
-      let changed = false;
-      const nextListens = listens.map((listen) => {
-        const source = listen.source;
-        if (!source || source.kind !== "trait") return listen;
-        const target = subs.get(source.trait);
-        if (target === void 0 || target === source.trait) return listen;
-        changed = true;
-        const traitId = idByName.get(target);
-        return {
-          ...listen,
-          source: { kind: "trait", trait: target, ...traitId ? { traitId } : {} }
-        };
-      });
-      if (changed) rt.trait = { ...rt.trait, listens: nextListens };
+      if (!subs) continue;
+      rt.trait = rewriteListenSources(rt.trait, subs, idByName);
     }
     refResolverLog.info("sibling-pull", {
       pulled: pulled.map((p) => ({
         trait: p.trait.name,
         owner: p.trait.name ? ownerOf.get(p.trait.name) : void 0,
+        parent: p.trait.name ? parentOf.get(p.trait.name) : void 0,
         linkedEntity: p.linkedEntity ?? p.trait.linkedEntity
       }))
     });
     resolved.push(...pulled);
-    return errors;
+    const pulledNames = new Set(
+      pulled.map((p) => p.trait.name).filter((n) => Boolean(n))
+    );
+    return { errors, auxEntities, pulledNames };
   }
   /**
    * Resolve a single trait reference.
    */
-  resolveTraitRef(traitRef, imports) {
+  async resolveTraitRef(traitRef, imports, chain, embedCtx, aliasEntityRenames) {
     if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
       const { trait: resolvedInline, errors } = resolveConfigRefEmitNames(traitRef);
       if (errors.length > 0) {
@@ -4655,16 +6477,33 @@ var ReferenceResolver = class {
       return this.resolveTraitRefString(
         refObj.ref,
         imports,
+        chain,
         refObj.config,
         refObj.linkedEntity,
         refObj.name,
         refObj.events,
         refObj.listens,
-        refObj.refId
+        refObj.refId,
+        refObj.typeArgs,
+        embedCtx,
+        aliasEntityRenames
       );
     }
     if (typeof traitRef === "string") {
-      return this.resolveTraitRefString(traitRef, imports);
+      return this.resolveTraitRefString(
+        traitRef,
+        imports,
+        chain,
+        void 0,
+        void 0,
+        void 0,
+        void 0,
+        void 0,
+        void 0,
+        void 0,
+        embedCtx,
+        aliasEntityRenames
+      );
     }
     return {
       success: false,
@@ -4674,8 +6513,10 @@ var ReferenceResolver = class {
   /**
    * Resolve a trait reference string.
    */
-  resolveTraitRefString(ref, imports, config, linkedEntity, overrideName, eventRenames, listensOverride, refId) {
+  async resolveTraitRefString(ref, imports, chain, config, linkedEntity, overrideName, eventRenames, listensOverride, refId, typeArgs, embedCtx, aliasEntityRenames) {
     const parsed = parseImportedTraitRef(ref);
+    const localName = overrideName ?? (parsed ? parsed.traitName : ref);
+    const resolvedConfig = config && embedCtx ? resolveEmbedderConfigForward(config, localName, embedCtx, this.schemaConfig) : config;
     if (parsed) {
       const imported = imports.orbitals.get(parsed.alias);
       if (!imported) {
@@ -4687,9 +6528,27 @@ var ReferenceResolver = class {
         };
       }
       let trait = null;
-      for (const o of importedOrbitals(imported)) {
-        trait = this.findTraitInOrbital(o, parsed.traitName, refId, imports.idIndex);
-        if (trait) break;
+      let embedScope = { imports, alias: parsed.alias };
+      const idEntry = refId ? imports.idIndex?.get(refId) : void 0;
+      if (idEntry && idEntry.kind === "trait") {
+        trait = idEntry.node;
+      } else {
+        for (const o of importedOrbitals(imported)) {
+          const entry = findTraitEntryInOrbital(o, parsed.traitName);
+          if (!entry) continue;
+          const entryResolved = await this.resolveTraitEntry(
+            imported,
+            entry,
+            parsed.traitName,
+            chain,
+            imports,
+            resolvedConfig
+          );
+          if (!entryResolved.success) return entryResolved;
+          trait = entryResolved.data.trait;
+          embedScope = entryResolved.data.embedScope;
+          break;
+        }
       }
       if (!trait) {
         const available = importedOrbitals(imported).flatMap((o) => this.listTraitsInOrbital(o));
@@ -4700,15 +6559,36 @@ var ReferenceResolver = class {
           ]
         };
       }
+      if (embedCtx && trait.config) {
+        const homeResolvedConfig = resolveConfigForwards(
+          trait.config,
+          embedderChain(localName, embedCtx.traitRefs, embedCtx.embedGraph),
+          embedCtx.orbitalConfig,
+          homeOrbitalConfigForTrait(imported, parsed.traitName),
+          imported.schemaConfig,
+          this.schemaConfig
+        );
+        if (homeResolvedConfig) {
+          trait = { ...trait, config: homeResolvedConfig };
+        }
+      }
       const baseTrait = overrideName ? { ...trait, name: overrideName } : trait;
-      const { trait: configResolvedTrait, errors: configRefErrors } = resolveConfigRefEmitNames(baseTrait, config);
+      const { trait: configResolvedTrait, errors: configRefErrors, resolvedKnobs } = resolveConfigRefEmitNames(baseTrait, resolvedConfig);
       if (configRefErrors.length > 0) {
         return { success: false, errors: configRefErrors };
       }
-      const reboundTrait = applyLinkedEntityRename(configResolvedTrait, linkedEntity);
-      const renamedTrait = applyEventRenames(reboundTrait, eventRenames);
-      const renamedConfig = applyEventRenamesToCallSiteConfig(config, reboundTrait.config, eventRenames);
-      const finalTrait = listensOverride !== void 0 ? { ...renamedTrait, listens: listensOverride } : renamedTrait;
+      const reboundTrait = applyLinkedEntityRename(configResolvedTrait, linkedEntity, this.entityIdsInScope);
+      const aliasSubs = aliasEntityRenames?.get(parsed.alias);
+      const aliasReboundTrait = aliasSubs ? applyAliasEntityRenames(reboundTrait, aliasSubs, this.entityIdsInScope) : reboundTrait;
+      const renamedTrait = applyEventRenames(aliasReboundTrait, eventRenames);
+      const foldedTrait = foldEventRenameOntoDeclaredKnobs(
+        renamedTrait,
+        resolvedKnobValues(baseTrait, configResolvedTrait, resolvedKnobs),
+        eventRenames
+      );
+      const renamedConfig = applyEventRenamesToCallSiteConfig(resolvedConfig, reboundTrait.config, eventRenames);
+      const configFoldedTrait = foldCallSiteConfigOntoTrait(foldedTrait, renamedConfig);
+      const finalTrait = listensOverride !== void 0 ? { ...configFoldedTrait, listens: listensOverride } : configFoldedTrait;
       if (listensOverride !== void 0) {
         refResolverLog.info("listens-override:imported", {
           trait: finalTrait.name,
@@ -4723,7 +6603,9 @@ var ReferenceResolver = class {
           trait: finalTrait,
           source: { type: "imported", alias: parsed.alias, traitName: parsed.traitName },
           config: renamedConfig,
-          linkedEntity
+          linkedEntity,
+          embedScope,
+          ...typeArgs !== void 0 ? { typeArgs } : {}
         },
         warnings: []
       };
@@ -4731,14 +6613,20 @@ var ReferenceResolver = class {
     const localTrait = (refId && this.localTraitsById.get(refId)) ?? this.localTraits.get(ref);
     if (localTrait) {
       const baseLocal = overrideName ? { ...localTrait, name: overrideName } : localTrait;
-      const { trait: configResolvedLocal, errors: localConfigRefErrors } = resolveConfigRefEmitNames(baseLocal, config);
+      const { trait: configResolvedLocal, errors: localConfigRefErrors, resolvedKnobs: localResolvedKnobs } = resolveConfigRefEmitNames(baseLocal, resolvedConfig);
       if (localConfigRefErrors.length > 0) {
         return { success: false, errors: localConfigRefErrors };
       }
-      const reboundLocal = applyLinkedEntityRename(configResolvedLocal, linkedEntity);
+      const reboundLocal = applyLinkedEntityRename(configResolvedLocal, linkedEntity, this.entityIdsInScope);
       const renamedLocalTrait = applyEventRenames(reboundLocal, eventRenames);
-      const renamedLocalConfig = applyEventRenamesToCallSiteConfig(config, reboundLocal.config, eventRenames);
-      const finalLocalTrait = listensOverride !== void 0 ? { ...renamedLocalTrait, listens: listensOverride } : renamedLocalTrait;
+      const foldedLocalTrait = foldEventRenameOntoDeclaredKnobs(
+        renamedLocalTrait,
+        resolvedKnobValues(baseLocal, configResolvedLocal, localResolvedKnobs),
+        eventRenames
+      );
+      const renamedLocalConfig = applyEventRenamesToCallSiteConfig(resolvedConfig, reboundLocal.config, eventRenames);
+      const configFoldedLocalTrait = foldCallSiteConfigOntoTrait(foldedLocalTrait, renamedLocalConfig);
+      const finalLocalTrait = listensOverride !== void 0 ? { ...configFoldedLocalTrait, listens: listensOverride } : configFoldedLocalTrait;
       if (listensOverride !== void 0) {
         refResolverLog.info("listens-override:local", {
           trait: finalLocalTrait.name,
@@ -4753,7 +6641,8 @@ var ReferenceResolver = class {
           trait: finalLocalTrait,
           source: { type: "local", name: ref },
           config: renamedLocalConfig,
-          linkedEntity
+          linkedEntity,
+          ...typeArgs !== void 0 ? { typeArgs } : {}
         },
         warnings: []
       };
@@ -4765,31 +6654,6 @@ var ReferenceResolver = class {
       ]
     };
   }
-  /**
-   * Find a trait in an orbital by name. Id-primary: when the calling ref
-   * carries a `refId` and the id index has a matching trait entry, return it
-   * directly — else fall back to the existing name match unchanged.
-   */
-  findTraitInOrbital(orbital, traitName, refId, idIndex) {
-    if (refId && idIndex) {
-      const entry = idIndex.get(refId);
-      if (entry && entry.kind === "trait") {
-        return entry.node;
-      }
-    }
-    for (const traitRef of orbital.traits) {
-      if (typeof traitRef !== "string" && "stateMachine" in traitRef) {
-        if (traitRef.name === traitName) {
-          return traitRef;
-        }
-      }
-      if (typeof traitRef !== "string" && "ref" in traitRef) {
-        const refObj = traitRef;
-        if (refObj.ref === traitName || refObj.name === traitName) ;
-      }
-    }
-    return null;
-  }
   /**
    * List trait names in an orbital.
    */
@@ -4805,11 +6669,11 @@ var ReferenceResolver = class {
   /**
    * Resolve page references.
    */
-  resolvePages(pageRefs, imports) {
+  async resolvePages(pageRefs, imports, chain) {
     const errors = [];
     const resolved = [];
     for (const pageRef of pageRefs) {
-      const result = this.resolvePageRef(pageRef, imports);
+      const result = await this.resolvePageRef(pageRef, imports, chain);
       if (!result.success) {
         errors.push(...result.errors);
       } else {
@@ -4824,7 +6688,7 @@ var ReferenceResolver = class {
   /**
    * Resolve a single page reference.
    */
-  resolvePageRef(pageRef, imports) {
+  async resolvePageRef(pageRef, imports, chain) {
     if (!isPageReference(pageRef)) {
       return {
         success: true,
@@ -4837,10 +6701,10 @@ var ReferenceResolver = class {
       };
     }
     if (isPageReferenceString(pageRef)) {
-      return this.resolvePageRefString(pageRef, imports);
+      return this.resolvePageRefString(pageRef, imports, chain);
     }
     if (isPageReferenceObject(pageRef)) {
-      return this.resolvePageRefObject(pageRef, imports);
+      return this.resolvePageRefObject(pageRef, imports, chain);
     }
     return {
       success: false,
@@ -4850,7 +6714,7 @@ var ReferenceResolver = class {
   /**
    * Resolve a page reference string.
    */
-  resolvePageRefString(ref, imports, refId) {
+  async resolvePageRefString(ref, imports, chain, refId) {
     const parsed = parsePageRef(ref);
     if (!parsed) {
       return {
@@ -4868,9 +6732,18 @@ var ReferenceResolver = class {
       };
     }
     let page = null;
-    for (const o of importedOrbitals(imported)) {
-      page = this.findPageInOrbital(o, parsed.pageName, refId, imports.idIndex);
-      if (page) break;
+    const idEntry = refId ? imports.idIndex?.get(refId) : void 0;
+    if (idEntry && idEntry.kind === "page") {
+      page = { ...idEntry.node };
+    } else {
+      for (const o of importedOrbitals(imported)) {
+        const entry = findPageEntryInOrbital(o, parsed.pageName);
+        if (!entry) continue;
+        const entryResolved = await this.resolvePageEntry(imported, entry, chain);
+        if (!entryResolved.success) return entryResolved;
+        page = entryResolved.data.page;
+        break;
+      }
     }
     if (!page) {
       const available = importedOrbitals(imported).flatMap((o) => this.listPagesInOrbital(o));
@@ -4892,10 +6765,18 @@ var ReferenceResolver = class {
     };
   }
   /**
-   * Resolve a page reference object with optional path override.
+   * Resolve a page reference object, applying every call-site override —
+   * `path` (direct assignment), `linkedEntity` (rebind `primaryEntity` and
+   * every page-level trait pointer that named the old entity), and `traits`
+   * (full replacement) — mirroring the compiler's `apply_overrides_to_page`
+   * (`phases/inline/page.rs:21-93`). `Page.traits` is a `PageTraitRef[]`
+   * pointer list (a trait's own body lives in the orbital's `traits {}`, not
+   * on the page), so unlike Rust's `TraitReference` the `linkedEntity` rebind
+   * only ever touches each pointer's OWN `linkedEntity` field — there is no
+   * inline trait body here to walk with `renameEntitiesInTrait`.
    */
-  resolvePageRefObject(refObj, imports) {
-    const baseResult = this.resolvePageRefString(refObj.ref, imports, refObj.refId);
+  async resolvePageRefObject(refObj, imports, chain) {
+    const baseResult = await this.resolvePageRefString(refObj.ref, imports, chain, refObj.refId);
     if (!baseResult.success) {
       return baseResult;
     }
@@ -4909,36 +6790,25 @@ var ReferenceResolver = class {
       resolved.pathOverridden = true;
       resolved.originalPath = originalPath;
     }
+    if (refObj.linkedEntity) {
+      const oldEntity = resolved.page.primaryEntity;
+      const newEntity = refObj.linkedEntity;
+      const rebindPointers = (pointers) => oldEntity && oldEntity !== newEntity ? pointers?.map((pt) => pt.linkedEntity === oldEntity ? { ...pt, linkedEntity: newEntity } : pt) : pointers;
+      resolved.page = {
+        ...resolved.page,
+        primaryEntity: newEntity,
+        traits: rebindPointers(resolved.page.traits)
+      };
+    }
+    if (refObj.traits) {
+      resolved.page = { ...resolved.page, traits: refObj.traits.map(toPageTraitRef) };
+    }
     return {
       success: true,
       data: resolved,
       warnings: baseResult.warnings
     };
   }
-  /**
-   * Find a page in an orbital by name. Id-primary: when the calling ref
-   * carries a `refId` and the id index has a matching page entry, return it
-   * directly — else fall back to the existing name match unchanged.
-   */
-  findPageInOrbital(orbital, pageName, refId, idIndex) {
-    if (refId && idIndex) {
-      const entry = idIndex.get(refId);
-      if (entry && entry.kind === "page") {
-        return { ...entry.node };
-      }
-    }
-    const pages = orbital.pages;
-    if (!pages) return null;
-    for (const pageRef of pages) {
-      if (typeof pageRef !== "string" && !("ref" in pageRef)) {
-        const page = pageRef;
-        if (page.name === pageName) {
-          return { ...page };
-        }
-      }
-    }
-    return null;
-  }
   /**
    * List page names in an orbital.
    */
@@ -4953,6 +6823,567 @@ var ReferenceResolver = class {
     }
     return names;
   }
+  /**
+   * Flatten every reference-form orbital (`orbital X = Alias.orbitals.Y
+   * { … }`, docs/Almadar_Orbital_Import.md §4) in a schema BEFORE the
+   * ordinary per-orbital {@link resolve} pass runs — the interpreter-path
+   * twin of the (not-yet-landed) compiler's inline-phase flatten. After this
+   * call, no returned `OrbitalDefinition` carries `.reference`.
+   */
+  async resolveOrbitalImports(schema, opts) {
+    const errors = [];
+    const flattened = [];
+    const chain = { push: () => null, pop: () => {
+    }, clone() {
+      return this;
+    } };
+    const visiting = /* @__PURE__ */ new Set();
+    const consumerEntityIds = consumerEntityIdsOf(schema.orbitals);
+    for (const [name, id] of await this.precomputeReferenceFormPrimaryIds(schema, chain)) {
+      if (!consumerEntityIds.has(name)) consumerEntityIds.set(name, id);
+    }
+    const consumerRoster = identityEntitiesOf(schema.orbitals);
+    for (const orbital of schema.orbitals) {
+      if (!orbital.reference) {
+        if (!opts?.skipTypeParamSentinels && isInlineEntity(orbital.entity)) {
+          resolveOrbitalTypeParamSentinels(
+            orbital.traits.filter(isInlineTrait).map((t) => ({ trait: t })),
+            orbital.entity,
+            (orbital.auxiliaryEntities ?? []).filter(isInlineEntity),
+            orbital.types
+          );
+        }
+        flattened.push(orbital);
+        continue;
+      }
+      const result = await this.resolveOrbitalRefChain(orbital, void 0, chain, visiting, consumerEntityIds, consumerRoster);
+      if (!result.success) {
+        errors.push(...result.errors);
+        continue;
+      }
+      flattened.push(result.data);
+    }
+    if (errors.length > 0) return { success: false, errors };
+    return { success: true, data: flattened, warnings: [] };
+  }
+  /**
+   * (B) The materialized primary name → derived id of every REFERENCE-FORM
+   * orbital this schema declares (`orbital X = Alias.orbitals.Y { … }`),
+   * computed order-free — WITHOUT requiring any other orbital in `schema`
+   * to have resolved first, and without recursively flattening the
+   * upstream. Each reference's alias is loaded via the ordinary
+   * `resolveImports` path, which the loader caches by absolute path (see
+   * `ExternalOrbitalLoader`'s `LoaderCache`) — the REAL flatten
+   * (`resolveOrbitalRefChain`) moments later is then a cache hit, no
+   * duplicate work — and its named orbital looked up directly in the
+   * loaded (un-flattened) schema: an upstream's OWN primary entity id/name
+   * never change through resolution (only a CONSUMER-side CLONE gets a
+   * fresh derived id), so this shallow load's entity is exactly what the
+   * real flatten pass would see too. Uses the SAME `materializedPrimaryEntity`
+   * pair `materializeOrbitalRef` computes for itself — one owner. JS twin
+   * of the compiled path's `precompute_reference_form_primary_ids`.
+   *
+   * Best-effort: a reference this pre-pass cannot resolve (unknown alias,
+   * malformed reference string, upstream orbital not found, load failure)
+   * is silently skipped here — the REAL `resolveOrbitalRefChain` call
+   * moments later still surfaces the actual error for it.
+   */
+  async precomputeReferenceFormPrimaryIds(schema, chain) {
+    const out = /* @__PURE__ */ new Map();
+    for (const orbital of schema.orbitals) {
+      const ref = orbital.reference;
+      if (!ref) continue;
+      const parsed = parseOrbitalRef(ref.ref);
+      if (!parsed) continue;
+      const importsResult = await this.resolveImports(orbital.uses ?? [], void 0, chain);
+      if (!importsResult.success) continue;
+      const imported = importsResult.data.orbitals.get(parsed.alias);
+      if (!imported) continue;
+      const upstream = importedOrbitals(imported).find((o) => o.name === parsed.orbitalName);
+      if (!upstream || !isInlineEntity(upstream.entity)) continue;
+      const { name, id } = materializedPrimaryEntity(upstream.entity, upstream.id, ref, orbital.name);
+      out.set(name, id);
+    }
+    return out;
+  }
+  /**
+   * Resolve one reference-form orbital, recursing into the upstream first
+   * when IT is also reference-form ("already fully inlined because inline
+   * recursed into every loaded orbital" — docs/Almadar_Orbital_Import.md §9
+   * step 3 — the JS resolver needs its own cycle guard since it has no
+   * file-level inline-order pass to lean on).
+   */
+  async resolveOrbitalRefChain(orbital, sourcePath, chain, visiting, consumerEntityIds, consumerRoster) {
+    const ref = orbital.reference;
+    if (!ref) return { success: true, data: orbital, warnings: [] };
+    const parsed = parseOrbitalRef(ref.ref);
+    if (!parsed) {
+      return {
+        success: false,
+        errors: [`Invalid orbital reference format: ${ref.ref}. Expected "Alias.orbitals.OrbitalName"`]
+      };
+    }
+    const importsResult = await this.resolveImports(orbital.uses ?? [], sourcePath, chain);
+    if (!importsResult.success) return { success: false, errors: importsResult.errors };
+    const imported = importsResult.data.orbitals.get(parsed.alias);
+    if (!imported) {
+      return {
+        success: false,
+        errors: [
+          `Unknown import alias in orbital reference: ${parsed.alias}. Available aliases: ${Array.from(importsResult.data.orbitals.keys()).join(", ") || "none"}`
+        ]
+      };
+    }
+    const candidates = importedOrbitals(imported);
+    let upstream = candidates.find((o) => o.name === parsed.orbitalName);
+    if (!upstream) {
+      return {
+        success: false,
+        errors: [
+          `Orbital "${parsed.orbitalName}" not found in imported behavior "${parsed.alias}". Available orbitals: ${candidates.map((o) => o.name).join(", ") || "none"}`
+        ]
+      };
+    }
+    const cycleKey = `${imported.sourcePath}::${parsed.orbitalName}`;
+    if (visiting.has(cycleKey)) {
+      return {
+        success: false,
+        errors: [
+          `Circular orbital reference: "${orbital.name}" imports "${parsed.alias}.orbitals.${parsed.orbitalName}" while that orbital is itself being resolved`
+        ]
+      };
+    }
+    visiting.add(cycleKey);
+    if (upstream.reference) {
+      const nested = await this.resolveOrbitalRefChain(
+        upstream,
+        imported.sourcePath,
+        chain,
+        visiting,
+        consumerEntityIds,
+        consumerRoster
+      );
+      if (!nested.success) {
+        visiting.delete(cycleKey);
+        return nested;
+      }
+      upstream = nested.data;
+    }
+    visiting.delete(cycleKey);
+    const materialized = await this.materializeOrbitalRef(
+      upstream,
+      ref,
+      orbital.name,
+      orbital.id,
+      imported.sourcePath,
+      chain,
+      candidates,
+      consumerEntityIds,
+      consumerRoster,
+      imported.schemaConfig
+    );
+    if (!materialized.success) return materialized;
+    const siblingTraits = orbital.traits ?? [];
+    return {
+      success: true,
+      data: {
+        ...materialized.data,
+        ...siblingTraits.length > 0 ? { traits: [...materialized.data.traits, ...siblingTraits] } : {},
+        uses: orbital.uses
+      },
+      warnings: materialized.warnings
+    };
+  }
+  /**
+   * Materialize a reference-form orbital: flatten the (already-inlined)
+   * upstream orbital's whole trait/entity/page closure into the consumer,
+   * unconditionally prefixed by `localName` (docs/Almadar_Orbital_Import.md
+   * §4.3). JS twin of the (not-yet-landed) compiler's
+   * `resolve_orbital_reference`.
+   */
+  async materializeOrbitalRef(upstream, ref, localName, localId, sourcePath, chain, aliasOrbitals, consumerEntityIds, consumerRoster, importedSchemaConfig) {
+    const savedSchemaConfig = this.schemaConfig;
+    this.schemaConfig = importedSchemaConfig;
+    let resolvedUpstream;
+    try {
+      resolvedUpstream = await this.resolve(upstream, sourcePath, chain);
+    } finally {
+      this.schemaConfig = savedSchemaConfig;
+    }
+    if (!resolvedUpstream.success) {
+      return {
+        success: false,
+        errors: resolvedUpstream.errors.map(
+          (e) => `Orbital reference "${localName}" (${ref.ref}): ${e}`
+        )
+      };
+    }
+    const {
+      entity: upstreamEntity,
+      traits: upstreamTraits,
+      pages: upstreamPages,
+      // (C) the RESOLVED aux-entity set — includes whatever sibling-pull
+      // surfaced (`pullSiblingTraits`'s aux-entity carry), never just
+      // `upstream.auxiliaryEntities` (the pre-resolve INPUT, which misses
+      // every un-rebound composed atom's own entity).
+      auxiliaryEntities: upstreamAuxiliaryEntities
+    } = resolvedUpstream.data;
+    const onlySet = ref.only ? new Set(ref.only) : void 0;
+    const omitSet = new Set(ref.omit ?? []);
+    const keptTraits = upstreamTraits.filter(
+      (rt) => onlySet ? onlySet.has(rt.trait.name) : !omitSet.has(rt.trait.name)
+    );
+    const keptNames = new Set(keptTraits.map((rt) => rt.trait.name));
+    const removedNames = new Set(
+      upstreamTraits.map((rt) => rt.trait.name).filter((n) => !keptNames.has(n))
+    );
+    const errors = [];
+    for (const rt of keptTraits) {
+      for (const embed of traitEmbedNamesOf(rt.trait)) {
+        if (removedNames.has(embed)) {
+          errors.push(
+            `Orbital "${localName}" omits trait "${embed}" but surviving trait "${rt.trait.name}" still embeds it via @trait.${embed} (ORB_O_OMIT_EMBEDDED_TRAIT)`
+          );
+        }
+      }
+    }
+    if (errors.length > 0) return { success: false, errors };
+    let auxEntities = upstreamAuxiliaryEntities ?? [];
+    const subs = /* @__PURE__ */ new Map();
+    for (const rt of keptTraits) subs.set(rt.trait.name, `${localName}${rt.trait.name}`);
+    const { name: primaryFinalName, id: primaryId } = materializedPrimaryEntity(
+      upstreamEntity,
+      upstream.id,
+      ref,
+      localName
+    );
+    subs.set(upstreamEntity.name, primaryFinalName);
+    for (const e of auxEntities) subs.set(e.name, `${localName}${e.name}`);
+    const fieldSubs = new Map(Object.entries(ref.fields ?? {}));
+    const closure = /* @__PURE__ */ new Set([upstreamEntity.name, ...auxEntities.map((e) => e.name)]);
+    const upstreamUniverse = /* @__PURE__ */ new Set();
+    const upstreamUniverseEntities = /* @__PURE__ */ new Map();
+    const primaryEntityNames = /* @__PURE__ */ new Set();
+    for (const o of aliasOrbitals) {
+      if (o.name === upstream.name) continue;
+      if (isInlineEntity(o.entity)) primaryEntityNames.add(o.entity.name);
+      for (const entity of inlineEntityRefsOf(o)) {
+        if (!closure.has(entity.name)) {
+          upstreamUniverse.add(entity.name);
+          upstreamUniverseEntities.set(entity.name, entity);
+        }
+      }
+    }
+    const entityIds = /* @__PURE__ */ new Map();
+    if (ref.entities) {
+      for (const [upstreamKey, consumerName] of Object.entries(ref.entities)) {
+        if (!upstreamUniverse.has(upstreamKey)) {
+          errors.push(
+            `Orbital "${localName}" declares entities { ${upstreamKey}: ${consumerName} } but "${upstreamKey}" is not an out-of-orbital entity of upstream alias "${upstream.name}" (ORB_O_ENTITY_UNKNOWN_KEY)`
+          );
+          continue;
+        }
+        const consumerId = consumerEntityIds.get(consumerName);
+        if (consumerId === void 0) {
+          errors.push(
+            `Orbital "${localName}" entities { ${upstreamKey}: ${consumerName} } targets "${consumerName}", which the consumer schema does not declare (ORB_O_ENTITY_TARGET_UNKNOWN)`
+          );
+          continue;
+        }
+        subs.set(upstreamKey, consumerName);
+        entityIds.set(consumerName, consumerId);
+      }
+      if (errors.length > 0) return { success: false, errors };
+    }
+    const referenced = /* @__PURE__ */ new Set();
+    for (const rt of keptTraits) {
+      if (rt.trait.linkedEntity && upstreamUniverse.has(rt.trait.linkedEntity)) {
+        referenced.add(rt.trait.linkedEntity);
+      }
+      for (const name of collectEntityNamesInTrait(rt.trait, upstreamUniverse)) referenced.add(name);
+      if (rt.trait.sourceEntityDefinition) {
+        for (const name of relationTargetsOfEntity(rt.trait.sourceEntityDefinition, upstreamUniverse)) {
+          referenced.add(name);
+        }
+      }
+    }
+    for (const name of relationTargetsOfEntity(upstreamEntity, upstreamUniverse)) referenced.add(name);
+    for (const aux of auxEntities) {
+      for (const name of relationTargetsOfEntity(aux, upstreamUniverse)) referenced.add(name);
+    }
+    for (const rp of upstreamPages) {
+      if (rp.page.primaryEntity && upstreamUniverse.has(rp.page.primaryEntity)) {
+        referenced.add(rp.page.primaryEntity);
+      }
+      for (const tr of rp.page.traits ?? []) {
+        if (tr.linkedEntity && upstreamUniverse.has(tr.linkedEntity)) referenced.add(tr.linkedEntity);
+      }
+    }
+    for (const name of referenced) {
+      if (subs.has(name)) continue;
+      const definition = upstreamUniverseEntities.get(name);
+      const auxOnly = definition !== void 0 && !primaryEntityNames.has(name);
+      if (definition && auxOnly && !definition.identity) {
+        auxEntities = [...auxEntities, definition];
+        subs.set(name, `${localName}${name}`);
+        continue;
+      }
+      errors.push(
+        `Orbital "${localName}" references out-of-orbital entity "${name}" with no "${name}: <consumer entity>" mapping in entities {} (ORB_O_ENTITY_UNMAPPED)`
+      );
+    }
+    if (errors.length > 0) return { success: false, errors };
+    const roleFields = /* @__PURE__ */ new Map();
+    for (const entity of identityEntitiesOf(aliasOrbitals)) {
+      for (const field of entity.fields) {
+        if (!field.name) continue;
+        const vocab = roleVocabularyOf(entity, field.name);
+        if (vocab) roleFields.set(field.name, vocab);
+      }
+    }
+    const consumerRoleFields = /* @__PURE__ */ new Map();
+    for (const entity of consumerRoster) {
+      for (const field of entity.fields) {
+        if (!field.name) continue;
+        const vocab = roleVocabularyOf(entity, field.name);
+        if (!vocab) continue;
+        let values = consumerRoleFields.get(field.name);
+        if (!values) {
+          values = /* @__PURE__ */ new Set();
+          consumerRoleFields.set(field.name, values);
+        }
+        for (const value of vocab) values.add(value);
+      }
+    }
+    for (const [literal, targets] of Object.entries(ref.roles ?? {})) {
+      const matchingFields = [...roleFields.entries()].filter(([, vocab]) => vocab.includes(literal)).map(([field]) => field).sort();
+      if (matchingFields.length === 0) {
+        errors.push(
+          `Orbital "${localName}" declares roles { ${literal}: ... } but upstream alias "${upstream.name}"'s roster declares no role field with literal "${literal}" in its vocabulary (ORB_O_ROLE_UNKNOWN_UPSTREAM)`
+        );
+        continue;
+      }
+      for (const field of matchingFields) {
+        const allowed = consumerRoleFields.get(field);
+        for (const target of targets) {
+          if (allowed?.has(target)) continue;
+          errors.push(
+            `Orbital "${localName}" roles { ${literal}: ${target} } targets "${target}", which is not a member of consumer field "${field}" on the roster (values: ${allowed ? [...allowed].sort().join(", ") : "(none)"}) (ORB_O_ROLE_TARGET_NOT_MEMBER)`
+          );
+        }
+      }
+    }
+    if (errors.length > 0) return { success: false, errors };
+    const declaredConfig = upstream.config;
+    if (ref.config) {
+      for (const key of Object.keys(ref.config)) {
+        if (!declaredConfig || !(key in declaredConfig)) {
+          errors.push(
+            `Orbital "${localName}" overrides config "${key}" but upstream orbital "${upstream.name}" does not declare that knob (ORB_O_CONFIG_UNKNOWN_KEY)`
+          );
+        }
+      }
+      if (errors.length > 0) return { success: false, errors };
+    }
+    const configOverrideValues = {};
+    for (const [key, field] of Object.entries(ref.config ?? {})) {
+      if (field.default !== void 0) configOverrideValues[key] = field.default;
+    }
+    const foldedConfig = declaredConfig ? overrideDeclaredKnobs(declaredConfig, configOverrideValues) : void 0;
+    const idByName = /* @__PURE__ */ new Map();
+    const materializedTraits = keptTraits.map((rt) => {
+      const finalName = subs.get(rt.trait.name);
+      const finalId = asTraitId(deriveMaterializedId(rt.trait.id, upstream.id, rt.trait.name, localName, "trait"));
+      idByName.set(finalName, finalId);
+      return { ...rt.trait, name: finalName, id: finalId };
+    });
+    const embeddersOf = /* @__PURE__ */ new Map();
+    for (const t of materializedTraits) {
+      for (const embed of traitEmbedNamesOf(t)) {
+        const embedFinal = subs.get(embed);
+        if (!embedFinal) continue;
+        let embedders = embeddersOf.get(embedFinal);
+        if (!embedders) {
+          embedders = [];
+          embeddersOf.set(embedFinal, embedders);
+        }
+        embedders.push(t.name);
+      }
+    }
+    const parentConfigs = new Map(
+      materializedTraits.map((t) => [t.name, t.config])
+    );
+    const transitiveEmbedderChain = (name) => {
+      const chain2 = [];
+      const seenNames = /* @__PURE__ */ new Set([name]);
+      let cur = embeddersOf.get(name)?.[0];
+      while (cur !== void 0 && !seenNames.has(cur)) {
+        seenNames.add(cur);
+        const cfg = parentConfigs.get(cur);
+        if (cfg) chain2.push(cfg);
+        cur = embeddersOf.get(cur)?.[0];
+      }
+      return chain2;
+    };
+    entityIds.set(primaryFinalName, primaryId);
+    for (const e of auxEntities) {
+      entityIds.set(
+        subs.get(e.name),
+        asEntityId(deriveMaterializedId(e.id, upstream.id, e.name, localName, "entity"))
+      );
+    }
+    const upstreamPathSet = new Set(upstreamPages.map((rp) => rp.page.path));
+    for (const path of [...Object.keys(ref.pages ?? {}), ...Object.keys(ref.mounts ?? {})]) {
+      if (!upstreamPathSet.has(path)) {
+        errors.push(
+          `Orbital "${localName}" names page path "${path}" but upstream orbital "${upstream.name}" has no page at that path (ORB_O_PAGE_UNKNOWN_PATH)`
+        );
+      }
+    }
+    if (errors.length > 0) return { success: false, errors };
+    const pathMap = new Map(
+      upstreamPages.map((rp) => [rp.page.path, ref.pages?.[rp.page.path] ?? rp.page.path])
+    );
+    const orbitalRename = upstream.name !== localName ? { from: upstream.name, to: localName } : void 0;
+    const finalTraits = materializedTraits.map((trait) => {
+      let next = renameTraitEmbeds(trait, subs);
+      next = renameEntitiesInTrait(next, subs);
+      if (next.linkedEntity !== void 0) {
+        const linkedEntityId = entityIds.get(next.linkedEntity);
+        if (linkedEntityId !== void 0) next = { ...next, linkedEntityId };
+      }
+      next = rewriteEntityRefIds(next, subs, entityIds);
+      next = renameSourceEntityDefinition(next, subs, entityIds);
+      next = rewriteRoleLiteralsInTrait(next, roleFields, ref.roles ?? {});
+      if (fieldSubs.size > 0) next = rewriteEntityFieldsInTrait(next, fieldSubs);
+      next = rewriteListenSources(next, subs, idByName, orbitalRename);
+      if (pathMap.size > 0) {
+        next = rewriteTraitNavigateTargets(next, pathMap);
+      }
+      for (const embedderName of embeddersOf.get(trait.name) ?? []) {
+        const embedderConfig = parentConfigs.get(embedderName);
+        next = resolveForwardedSiblingConfigFrom(next, embedderConfig ? [embedderConfig] : []);
+      }
+      next = resolveForwardedSiblingConfigFrom(next, transitiveEmbedderChain(trait.name));
+      next = resolveForwardedSiblingConfigFrom(next, [], foldedConfig, importedSchemaConfig);
+      if (pathMap.size > 0) {
+        next = rewriteTraitConfigPagePaths(next, pathMap);
+      }
+      next = applyEventRenames(next, ref.events);
+      return next;
+    });
+    const renamedPrimaryEntity = rewriteRoleLiteralsInEntity(
+      renameEntityRelationTargets(
+        rewriteEntityFieldsInEntity(
+          {
+            ...upstreamEntity,
+            name: primaryFinalName,
+            id: primaryId
+          },
+          fieldSubs
+        ),
+        subs,
+        entityIds
+      ),
+      roleFields,
+      ref.roles ?? {}
+    );
+    const extendResult = applyExtendFields(
+      renamedPrimaryEntity,
+      ref.extend,
+      fieldSubs,
+      consumerEntityIds,
+      localName
+    );
+    if (extendResult.errors.length > 0) return { success: false, errors: extendResult.errors };
+    const primaryEntity = extendResult.entity;
+    const finalAuxEntities = auxEntities.map((e) => {
+      const finalName = subs.get(e.name);
+      return rewriteRoleLiteralsInEntity(
+        renameEntityRelationTargets(
+          rewriteEntityFieldsInEntity(
+            {
+              ...e,
+              name: finalName,
+              id: entityIds.get(finalName)
+            },
+            fieldSubs
+          ),
+          subs,
+          entityIds
+        ),
+        roleFields,
+        ref.roles ?? {}
+      );
+    });
+    const finalPages = upstreamPages.map((rp) => {
+      const original = rp.page;
+      const mountNames = ref.mounts?.[original.path] ?? [];
+      const finalPageTraits = [
+        ...(original.traits ?? []).filter((tr) => !removedNames.has(tr.ref)).map((tr) => {
+          const finalRef = subs.get(tr.ref) ?? tr.ref;
+          const refId = idByName.get(finalRef);
+          return {
+            ...tr,
+            ref: finalRef,
+            ...refId !== void 0 ? { refId } : {},
+            ...tr.linkedEntity !== void 0 ? { linkedEntity: subs.get(tr.linkedEntity) ?? tr.linkedEntity } : {}
+          };
+        }),
+        ...mountNames.map((name) => ({ ref: name }))
+      ];
+      return {
+        ...original,
+        // Gap (E) — unconditionally prefixed, same as traits/entities (§4.3):
+        // two imports of the same upstream orbital with distinct `pages {}`
+        // path maps must not collide on page NAME (`Duplicate page name`).
+        // `id` is the page-scope sibling of `deriveMaterializedId` (never
+        // `mintId`) — fresh and pairwise-disjoint across imports, same as
+        // trait/entity ids above.
+        name: `${localName}${original.name}`,
+        id: asPageId(deriveMaterializedId(original.id, upstream.id, original.name, localName, "page")),
+        path: pathMap.get(original.path) ?? original.path,
+        ...original.primaryEntity !== void 0 ? { primaryEntity: subs.get(original.primaryEntity) ?? original.primaryEntity } : {},
+        traits: finalPageTraits
+      };
+    });
+    const forwardedKnobs = /* @__PURE__ */ new Set();
+    for (const rt of keptTraits) {
+      for (const field of Object.values(rt.trait.config ?? {})) {
+        if (typeof field.default === "string" && field.default.startsWith("@config.")) {
+          const knob = field.default.slice("@config.".length);
+          if (knob.length > 0 && !knob.includes(".")) forwardedKnobs.add(knob);
+        }
+      }
+    }
+    const prunedConfig = foldedConfig ? Object.fromEntries(Object.entries(foldedConfig).filter(([key]) => forwardedKnobs.has(key))) : void 0;
+    const orbitalId = localId ?? (upstream.id ? asOrbitalId(deriveId(upstream.id, localName)) : void 0);
+    refResolverLog.info("orbital-import:materialize", {
+      local: localName,
+      upstream: upstream.name,
+      traits: finalTraits.length,
+      pages: finalPages.length
+    });
+    return {
+      success: true,
+      data: {
+        ...upstream,
+        name: localName,
+        ...orbitalId ? { id: orbitalId } : {},
+        entity: primaryEntity,
+        ...finalAuxEntities.length > 0 ? { auxiliaryEntities: finalAuxEntities } : {},
+        traits: finalTraits,
+        pages: finalPages,
+        emits: void 0,
+        listens: void 0,
+        exposes: void 0,
+        ...prunedConfig ? { config: prunedConfig } : { config: void 0 },
+        uses: void 0,
+        reference: void 0
+      },
+      warnings: []
+    };
+  }
   /**
    * Add local traits for resolution.
    */
@@ -4972,28 +7403,36 @@ var ReferenceResolver = class {
   }
 };
 async function resolveSchema(schema, options) {
-  const resolver = new ReferenceResolver(options);
+  const resolver = new ReferenceResolver({ ...options, schemaConfig: schema.config });
   const errors = [];
   const warnings = [];
   const resolved = [];
-  for (const orbital of schema.orbitals) {
+  const flattenResult = await resolver.resolveOrbitalImports(schema);
+  if (!flattenResult.success) {
+    return { success: false, errors: flattenResult.errors };
+  }
+  const orbitals = flattenResult.data;
+  for (const orbital of orbitals) {
     const inlineTraits = orbital.traits.filter(
       (t) => typeof t !== "string" && "stateMachine" in t
     );
     resolver.addLocalTraits(inlineTraits);
   }
-  for (const orbital of schema.orbitals) {
+  resolver.seedSchemaEntityIds(orbitals);
+  for (const orbital of orbitals) {
     const result = await resolver.resolve(orbital);
     if (!result.success) {
       errors.push(`Orbital "${orbital.name}": ${result.errors.join(", ")}`);
     } else {
       resolved.push(result.data);
+      resolver.noteResolvedEntityIds(result.data);
       warnings.push(...result.warnings.map((w) => `Orbital "${orbital.name}": ${w}`));
     }
   }
   if (errors.length > 0) {
     return { success: false, errors };
   }
+  resolver.uniquifyCrossOrbitalPulledSiblings(resolved);
   return { success: true, data: resolved, warnings };
 }
 
@@ -5208,4 +7647,4 @@ var InMemoryPersistence = class {
   }
 };
 
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, createInitialTraitState, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes };
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, LIFECYCLE_EVENTS, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, createInitialTraitState, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes };