@almadar/core 10.119.0 → 10.119.1

package/dist/builders.d.ts

@@ -323,6 +323,10 @@ declare function dedupeComposedSurface(orbitals: OrbitalDefinition[]): {
  *   A literal compared against a field the winner does not declare is a
  *   shape mismatch: compose fails with a deterministic error rather than
  *   silently shipping dead policy branches.
+ * A loser is a demoted identity, or an identity an orbital `expects` by name that no orbital
+ * provides as identity (composed from another organism): its role vocabulary joins the winner's,
+ * and its expectation is rewritten when the app holds it as a plain record.
+ *
  * - FIX-L — a composed `expects identity <Loser>` would fail the link-check
  *   (`ORB_S_EXPECTATION_PROVIDER_MISMATCH`) on every recompose; it is
  *   rewritten to `expects entity <Loser>` — the compiled path's own
@@ -347,6 +351,15 @@ declare function asEntityObject(entity: OrbitalDefinition['entity']): {
 } | null;
 /** The entity an orbital DECLARES (object form only — a bare string ref owns nothing here). */
 declare function orbitalEntityName(def: OrbitalDefinition): string | null;
+/**
+ * `organismOrderOf` for a registry: an orbital's position among its organism's declared orbitals,
+ * by the catalog orbital it was built from (`catalogOrbitalOf`, rename-stable). Each organism is
+ * loaded once.
+ */
+declare function organismOrderResolver(catalogOrbitalOf: (orbitalName: string) => {
+    organism: string;
+    orbital: string;
+} | undefined, loadOrganism: (organism: string) => OrbitalSchema | null): (orbitalName: string) => number | undefined;
 /**
  * `importedOrbitalOf` for a registry: an import's `reference.ref` (`Alias.orbitals.Name`)
  * resolved through the orbital's `uses` to the behavior it imports, then to that behavior's
@@ -416,6 +429,12 @@ interface ComposeSurfaceOptions {
      * own file follows.
      */
     organismOf?: (orbitalName: string) => string | undefined;
+    /**
+     * An orbital's position in its organism's declared orbitals. The first declared orbital boots
+     * the organism standalone, so composed behind another organism it is the landing page the nav
+     * must link; without it, the first composed orbital of the organism stands in.
+     */
+    organismOrderOf?: (orbitalName: string) => number | undefined;
     /** The atom's declaration of a referenced trait (see `RenameEntityOptions.atomTraitOf`); namespacing reads it. */
     atomTraitOf?: (orbital: OrbitalDefinition, traitRef: string) => Trait | undefined;
     /** An orbital import's source orbital (`orbitalImportResolver`); its pages count as owned when nav is narrowed. */
@@ -995,4 +1014,4 @@ declare function compose(orbitals: (OrbitalDefinition | OrbitalSchema)[], pages:
  */
 declare function pipe(orbitals: (OrbitalDefinition | OrbitalSchema)[], events: TraitEventContract[], appName?: string): OrbitalSchema;
 
-export { type ComposeAppFromFilesOptions, type ComposeAppFromFilesResult, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type ComposeConnection, type ComposePage, type ComposeSurfaceOptions, type ComposedSurface, type ConfigNavItemsNarrowResult, type EntityRenameBlocker, type EventWiringEntry, type FieldBindingContext, type IdentityDedupeResult, type IdentityDemotion, type IdentityExpectsRewrite, type IdentityRelationRetarget, type IdentityRoleUnion, type LandingNavResult, type LayoutStrategy, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeLayoutTraitOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakePageRefOptsTyped, type MakeTraitRefOpts, type MakeTraitRefOptsTyped, type NavItemsNarrowResult, type OrganismRename, type RenameEntityOptions, type SurfaceRename, type UnrenamableCollision, applyEventWiring, applyTraitConfigOverrides, asEntityObject, atomTraitResolver, collectFieldComparisonLiterals, collectOwnedSurface, collectOwnerComparedFields, collectOwnerStampedFields, compose, composeAppFromFiles, composeBehaviors, composeOrbitalSurface, connect, dedupeComposedIdentity, dedupeComposedSurface, detectLayoutStrategy, ensureIdField, entityRenameBlockers, extractTrait, findDanglingRefs, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeLedgers, mergeOrbitals, orbitalEntityName, orbitalImportResolver, orbitalRouteSlug, pipe, plural, renameEntity, renameEntityInSchema, renameOrbital, wire };
+export { type ComposeAppFromFilesOptions, type ComposeAppFromFilesResult, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type ComposeConnection, type ComposePage, type ComposeSurfaceOptions, type ComposedSurface, type ConfigNavItemsNarrowResult, type EntityRenameBlocker, type EventWiringEntry, type FieldBindingContext, type IdentityDedupeResult, type IdentityDemotion, type IdentityExpectsRewrite, type IdentityRelationRetarget, type IdentityRoleUnion, type LandingNavResult, type LayoutStrategy, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeLayoutTraitOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakePageRefOptsTyped, type MakeTraitRefOpts, type MakeTraitRefOptsTyped, type NavItemsNarrowResult, type OrganismRename, type RenameEntityOptions, type SurfaceRename, type UnrenamableCollision, applyEventWiring, applyTraitConfigOverrides, asEntityObject, atomTraitResolver, collectFieldComparisonLiterals, collectOwnedSurface, collectOwnerComparedFields, collectOwnerStampedFields, compose, composeAppFromFiles, composeBehaviors, composeOrbitalSurface, connect, dedupeComposedIdentity, dedupeComposedSurface, detectLayoutStrategy, ensureIdField, entityRenameBlockers, extractTrait, findDanglingRefs, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeLedgers, mergeOrbitals, orbitalEntityName, orbitalImportResolver, orbitalRouteSlug, organismOrderResolver, pipe, plural, renameEntity, renameEntityInSchema, renameOrbital, wire };

package/dist/builders.js

@@ -2947,12 +2947,32 @@ function dedupeComposedIdentity(orbitals) {
     demotions.push({ orbitalName: def.name, entityName: entity.name });
     demotedEntities.push(demoted);
   }
-  if (winnerIndex === -1 || demotions.length === 0) {
+  if (winnerIndex === -1) {
     return { demotions, roleUnions: [], expectsRewrites: [], relationsRetargeted: [] };
   }
-  const roleUnions = unionDemotedRoleVocabularies(orbitals, winnerIndex, demotedEntities);
-  const expectsRewrites = rewriteDemotedIdentityExpects(orbitals, demotions);
-  const relationsRetargeted = retargetDemotedOwnerRelations(orbitals, winnerIndex, demotions);
+  const winnerName = orbitalEntityName(orbitals[winnerIndex]);
+  const demotedNames = new Set(demotions.map((d) => d.entityName));
+  const strayExpects = [];
+  for (const def of orbitals) {
+    for (const e of def.expects ?? []) {
+      if (e.kind !== "identity" || e.name === void 0 || e.name === winnerName || demotedNames.has(e.name)) continue;
+      strayExpects.push({ name: e.name, shape: e.shape ?? [] });
+    }
+  }
+  if (demotions.length === 0 && strayExpects.length === 0) {
+    return { demotions, roleUnions: [], expectsRewrites: [], relationsRetargeted: [] };
+  }
+  const providedNames = new Set(orbitals.flatMap((def) => inlineEntitiesOf(def).map((e) => e.name)));
+  const roleUnions = unionDemotedRoleVocabularies(orbitals, winnerIndex, [
+    ...demotedEntities.map((d) => ({ name: d.name, fields: d.fields })),
+    ...strayExpects.map((e) => ({ name: e.name, fields: e.shape }))
+  ]);
+  const loserNames = /* @__PURE__ */ new Set([
+    ...demotedNames,
+    ...strayExpects.map((e) => e.name).filter((name) => providedNames.has(name))
+  ]);
+  const expectsRewrites = rewriteDemotedIdentityExpects(orbitals, loserNames);
+  const relationsRetargeted = retargetDemotedOwnerRelations(orbitals, winnerIndex, loserNames);
   return { demotions, roleUnions, expectsRewrites, relationsRetargeted };
 }
 function fieldVocabulary(field) {
@@ -3054,8 +3074,7 @@ function collectPersistedFields(node, entityName, out) {
     for (const value of Object.values(node)) collectPersistedFields(value, entityName, out);
   }
 }
-function rewriteDemotedIdentityExpects(orbitals, demotions) {
-  const demotedNames = new Set(demotions.map((d) => d.entityName));
+function rewriteDemotedIdentityExpects(orbitals, demotedNames) {
   const entityByName = /* @__PURE__ */ new Map();
   for (const def of orbitals) for (const entity of inlineEntitiesOf(def)) entityByName.set(entity.name, entity);
   const rewrites = [];
@@ -3073,12 +3092,13 @@ function rewriteDemotedIdentityExpects(orbitals, demotions) {
       collectPersistedFields(def.traits ?? [], e.name, persisted);
       const declared = new Set(e.shape.map((f) => f.name));
       const entity = entityByName.get(e.name);
+      const asDeclared = (field) => entity?.fields.find((f) => f.name === field.name) ?? field;
       const added = [...persisted].sort().flatMap((field) => {
         if (declared.has(field)) return [];
         const own = entity?.fields.find((f) => f.name === field);
         return own !== void 0 ? [own] : [];
       });
-      return { kind: "entity", name: e.name, shape: [...e.shape, ...added] };
+      return { kind: "entity", name: e.name, shape: [...e.shape.map(asDeclared), ...added] };
     });
     if (mutated) orbitals[i] = { ...def, expects: next };
   }
@@ -3108,11 +3128,10 @@ function retargetOwnerRelationFields(entity, fieldNames, demotedNames, winner) {
   });
   return applied.length === 0 ? null : { entity: { ...entity, fields }, applied };
 }
-function retargetDemotedOwnerRelations(orbitals, winnerIndex, demotions) {
+function retargetDemotedOwnerRelations(orbitals, winnerIndex, demotedNames) {
   const winnerDef = orbitals[winnerIndex];
   const winnerEntity = winnerDef.entity;
   if (winnerEntity === void 0 || isEntityReferenceAny(winnerEntity)) return [];
-  const demotedNames = new Set(demotions.map((d) => d.entityName));
   const candidates = /* @__PURE__ */ new Map();
   const addAll = (entityName, fields) => {
     if (fields.size === 0) return;
@@ -3222,6 +3241,18 @@ function collectOwnedPages(orbitals, importedOrbitalOf) {
   }
   return owned;
 }
+function organismOrderResolver(catalogOrbitalOf, loadOrganism) {
+  const declared = /* @__PURE__ */ new Map();
+  return (orbitalName) => {
+    const source = catalogOrbitalOf(orbitalName);
+    if (source === void 0) return void 0;
+    if (!declared.has(source.organism)) {
+      declared.set(source.organism, loadOrganism(source.organism)?.orbitals.map((o) => o.name) ?? null);
+    }
+    const index = declared.get(source.organism)?.indexOf(source.orbital) ?? -1;
+    return index >= 0 ? index : void 0;
+  };
+}
 function orbitalImportResolver(loadBehaviorOrb) {
   const loaded = /* @__PURE__ */ new Map();
   return (orbital) => {
@@ -3276,7 +3307,7 @@ function firstInlinePage(orbital) {
   }
   return void 0;
 }
-function linkLandingPages(orbitals, config, organismOf, navDeclaringOrbitals) {
+function linkLandingPages(orbitals, config, organismOf, navDeclaringOrbitals, organismOrderOf) {
   const navKnobs = Object.entries(config).filter(([, field2]) => field2.type === "[NavItem]" && Array.isArray(field2.default));
   if (navKnobs.length !== 1) return { config, added: [] };
   const [knob, field] = navKnobs[0];
@@ -3301,7 +3332,15 @@ function linkLandingPages(orbitals, config, organismOf, navDeclaringOrbitals) {
     const organism = organismOf(name);
     if (organism !== void 0) navOrganisms.add(organism);
   }
-  const seenOrganisms = /* @__PURE__ */ new Set();
+  const landingOf = /* @__PURE__ */ new Map();
+  orbitals.forEach((orbital, i) => {
+    const organism = organismOf(orbital.name);
+    if (organism === void 0 || firstInlinePage(orbital) === void 0) return;
+    const rank = organismOrderOf?.(orbital.name) ?? orbitals.length + i;
+    const current = landingOf.get(organism);
+    if (current === void 0 || rank < current.rank) landingOf.set(organism, { name: orbital.name, rank });
+  });
+  let bootOrganism;
   let booted = false;
   orbitals.forEach((orbital, i) => {
     const page = firstInlinePage(orbital);
@@ -3309,11 +3348,11 @@ function linkLandingPages(orbitals, config, organismOf, navDeclaringOrbitals) {
     const organism = organismOf(orbital.name);
     if (!booted) {
       booted = true;
-      if (organism !== void 0) seenOrganisms.add(organism);
+      bootOrganism = organism;
       return;
     }
-    if (organism === void 0 || navOrganisms.has(organism) && seenOrganisms.has(organism)) return;
-    seenOrganisms.add(organism);
+    if (organism === void 0) return;
+    if (navOrganisms.has(organism) && (organism === bootOrganism || landingOf.get(organism)?.name !== orbital.name)) return;
     if (linked.has(page.path) || page.path.split("/").some((segment) => segment.startsWith(":"))) return;
     let at = 0;
     next.forEach((entry, p) => {
@@ -3571,7 +3610,7 @@ function composeOrbitalSurface(files, options = {}) {
       if (!Object.values(f.config).some((entry) => entry.type === "[NavItem]")) continue;
       for (const o of f.orbitals) navDeclaringOrbitals.add(o.name);
     }
-    const linked = linkLandingPages(orbitals, config, options.organismOf, navDeclaringOrbitals);
+    const linked = linkLandingPages(orbitals, config, options.organismOf, navDeclaringOrbitals, options.organismOrderOf);
     config = linked.config;
     landingNavAdded = linked.added;
   }
@@ -3592,7 +3631,8 @@ function composeAppFromFiles(files, options) {
   const { orbitals, config, ledger, ...outcomes } = composeOrbitalSurface(files, {
     ...options.organismOf !== void 0 ? { organismOf: options.organismOf } : {},
     ...options.atomTraitOf !== void 0 ? { atomTraitOf: options.atomTraitOf } : {},
-    ...options.importedOrbitalOf !== void 0 ? { importedOrbitalOf: options.importedOrbitalOf } : {}
+    ...options.importedOrbitalOf !== void 0 ? { importedOrbitalOf: options.importedOrbitalOf } : {},
+    ...options.organismOrderOf !== void 0 ? { organismOrderOf: options.organismOrderOf } : {}
   });
   const result = composeBehaviors({
     appName: options.appName,
@@ -3942,6 +3982,6 @@ function pipe(orbitals, events, appName) {
   };
 }
 
-export { applyEventWiring, applyTraitConfigOverrides, asEntityObject, atomTraitResolver, collectFieldComparisonLiterals, collectOwnedSurface, collectOwnerComparedFields, collectOwnerStampedFields, compose, composeAppFromFiles, composeBehaviors, composeOrbitalSurface, connect, dedupeComposedIdentity, dedupeComposedSurface, detectLayoutStrategy, ensureIdField, entityRenameBlockers, extractTrait, findDanglingRefs, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeLedgers, mergeOrbitals, orbitalEntityName, orbitalImportResolver, orbitalRouteSlug, pipe, plural, renameEntity, renameEntityInSchema, renameOrbital, wire };
+export { applyEventWiring, applyTraitConfigOverrides, asEntityObject, atomTraitResolver, collectFieldComparisonLiterals, collectOwnedSurface, collectOwnerComparedFields, collectOwnerStampedFields, compose, composeAppFromFiles, composeBehaviors, composeOrbitalSurface, connect, dedupeComposedIdentity, dedupeComposedSurface, detectLayoutStrategy, ensureIdField, entityRenameBlockers, extractTrait, findDanglingRefs, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeLedgers, mergeOrbitals, orbitalEntityName, orbitalImportResolver, orbitalRouteSlug, organismOrderResolver, pipe, plural, renameEntity, renameEntityInSchema, renameOrbital, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map