@almadar/core 10.53.0 → 10.55.0

package/dist/{types-DJquF4Ot.d.ts → types-C4YztU2N.d.ts}

@@ -1,6 +1,6 @@
-import { E as EntityField, a as EntityPersistence, R as RelationConfig } from './effect-CqTo1gAF.js';
-import { T as TraitEventListener, a as TraitReference } from './trait-CnbGhs6A.js';
-import { J as JsonValue } from './expression-Yf7qvvOs.js';
+import { E as EntityField, a as EntityPersistence, R as RelationConfig } from './effect-DxD-XTI8.js';
+import { T as TraitEventListener, a as TraitReference } from './trait-WnYkvPdZ.js';
+import { J as JsonValue } from './expression-Fk8bQWef.js';
 
 /**
  * Cross-cutting presentation knobs that don't live per orbital
@@ -284,6 +284,13 @@ interface FactoryTraitSignature {
      *  header annotations. Free-form strings — the translator overlay
      *  matches rules to traits by exact set membership. */
     capabilities: ReadonlyArray<string>;
+    /** The entity this trait is bound to at THIS call site — the `.orb`
+     *  `TraitReference.linkedEntity` / inline `Trait.linkedEntity` (the same
+     *  field a `traitOverrides.<name>.linkedEntity` rebind ultimately writes).
+     *  Absent for a bare string ref, whose binding lives on the referenced
+     *  atom's own signature entry in the same catalog. Read directly off the
+     *  trait node — no inference. */
+    linkedEntity?: string;
     /** `true` when the source trait's entity binding was authored
      *  `-> @rebindable Entity`. Only then may a consumer rebind it via
      *  `traitOverrides.<name>.linkedEntity`; rabit enum-constrains that
@@ -301,6 +308,19 @@ interface FactoryTraitSignature {
      *  fed to catalog prose + knob-embeddings for binding-discovery. */
     entityBindingDescription?: string;
     entityBindingSynonyms?: string;
+    /** Entity names this trait's state-machine effects reference
+     *  (`stateMachine.transitions[].effects[]` — `persist create/update/delete`
+     *  and `fetch`), deduplicated. Distinct from `linkedEntity` (the trait's
+     *  OWN binding): this is every OTHER entity an effect reads or writes,
+     *  e.g. `CheckoutWizard`'s `persist create OrderRecord` names
+     *  `'OrderRecord'` here even though the trait itself is bound to
+     *  `Checkout`. `subset_closure` (`packages/almadar-rabit`) uses this to
+     *  detect a roster subset that would otherwise dangle a persist-effect
+     *  reference the relation-field/`linkedEntity` walk alone can't see —
+     *  measured cause of `ORB_EFF_FETCH_INVALID_ENTITY` on a scoped roster
+     *  (`docs/Almadar_Studio_Failures_2026-08-04.md` §N). Absent = topology
+     *  unknown (legacy catalogs), same convention as `transitionEvents`. */
+    effectEntityRefs?: ReadonlyArray<string>;
 }
 /** One event a trait emits or listens for, with its authored annotations — the
  *  per-event analogue of `FactorySignatureEntityField` / `FactoryConfigParam`.
@@ -466,6 +486,16 @@ interface FactoryCallSiteParams {
     collection?: string;
     /** Per-page path overrides keyed by `signature.pages[i].name`. */
     pagePaths?: Readonly<Record<string, string>>;
+    /**
+     * Theme name (a `data-theme` key from the built-in `@almadar-ui/themes/`
+     * registry) stamped onto `Orbital.theme` post-factory. Plan-level and
+     * uniform — the coordinator decides it once and threads the same value
+     * to every orbital; the per-orbital subagent does not independently pick.
+     * Applied post-`dispatchOrbitalFactoryMerged` via `applyOrbitalTheme`,
+     * exactly as `pagePaths`/`pages` are applied post-factory, so the factory's
+     * typed guard never sees it.
+     */
+    theme?: string;
     /** Trait-level overrides keyed by `signature.traits[i].name`. Each value
      *  is a {@link TraitOverlayEntry} — the canonical override surface that
      *  admits the full documented set (`config`, `linkedEntity`, `events`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/core",
-  "version": "10.53.0",
+  "version": "10.55.0",
   "description": "Core schema types and definitions for Almadar",
   "type": "module",
   "main": "./dist/index.js",

package/src/types/bindings.ts

@@ -106,6 +106,18 @@ export const BINDING_DOCS = {
     examples: ['@callsitePayload.error', '@callsitePayload.row'],
     requiresPath: true,
   },
+  pages: {
+    description:
+      'Render-resolved schema sigil — the host orbital\'s pages as a NavItem[] array (href = page.path, label = page.name). Substituted from the OrbitalSchema before codegen; never survives as a live binding.',
+    examples: ['@pages'],
+    requiresPath: false,
+  },
+  currentTheme: {
+    description:
+      'Render-resolved schema sigil — the host orbital\'s active data-theme key, derived from Orbital.theme. Substituted from the OrbitalSchema before codegen; never survives as a live binding.',
+    examples: ['@currentTheme'],
+    requiresPath: false,
+  },
 } as const;
 
 /**
@@ -118,7 +130,7 @@ export const BINDING_CONTEXT_RULES = {
       'Guards can access entity fields, event payload, current state, time, the call-site trait config (@config.X), and the authenticated user context (@user.id, @user.role) for ownership / role gates. Config access lets atoms write mode-aware guards — e.g. std-modal\'s OPEN can require @payload.row only when @config.mode equals "edit", letting create-mode legitimately fire OPEN with no row. Like effects, @config.X is substituted at molecule/organism inline time with the literal call-site value; at atom-scope validate, @config is allowed-but-unresolved.',
   },
   effect: {
-    allowed: ['entity', 'payload', 'state', 'now', 'trait', 'config', 'user', 'callsitePayload'] as const,
+    allowed: ['entity', 'payload', 'state', 'now', 'trait', 'config', 'user', 'callsitePayload', 'pages', 'currentTheme'] as const,
     description:
       'Effects can access and modify entity fields, use payload data, embed another trait\'s live frame via @trait.X inside render-ui children, read trait config values (@config.X) for atoms parameterized by their call-site, and read the authenticated user context (@user.id, @user.role). At molecule/organism inline time, @config.X is substituted with the literal value from the call-site config block; at atom-scope validate, @config is allowed-but-unresolved. @callsitePayload.X is the call-site-captured event payload emitted by the compiler\'s inline-trait hoisting (a hoisted render block that captured @payload); it is resolved at the composing effect by the runtime BindingResolver.',
   },