@almadar/core 10.40.0 → 10.42.0

package/dist/builders.d.ts

@@ -1,6 +1,597 @@
-import './entity-DfD-iXkn.js';
-export { i as ComposeBehaviorsInput, j as ComposeBehaviorsResult, c7 as ComposeConnection, c8 as ComposePage, a6 as EventWiringEntry, aq as LayoutStrategy, c9 as MakeAtomOrbitalOpts, ca as MakeAtomOrbitalTraitOverrides, cb as MakeEntityOpts, cc as MakeLayoutTraitOpts, cd as MakeOrbitalWithUsesOpts, ce as MakePageOpts, cf as MakePageRefOpts, cg as MakePageRefOptsTyped, M as MakeTraitRefOpts, ch as MakeTraitRefOptsTyped, bS as applyEventWiring, ci as applyTraitConfigOverrides, cj as compose, bT as composeBehaviors, ck as connect, bU as detectLayoutStrategy, cl as ensureIdField, cm as extractTrait, cn as makeAtomOrbital, co as makeEntity, cp as makeLayoutTrait, cq as makeOrbital, cr as makeOrbitalWithUses, cs as makePage, ct as makePageRef, cu as makeRenderUI, cv as makeSchema, cw as makeSlot, cx as makeTraitRef, cy as mergeLedgers, cz as mergeOrbitals, cA as pipe, cB as plural, cC as wire } from './builders-Dw270YQh.js';
-import './trait-C_TZnqb_.js';
-import './expression-DpAj1RzP.js';
+import { I as IdentityLedger, A as AnyPatternConfig, U as UISlot, c as Effect, h as RenderBinding, i as RenderUIEffect, d as EntityId, e as Entity, E as EntityField, a as EntityPersistence, f as EntityRow } from './effect-D4os99OL.js';
+import { a as OrbitalDefinition, O as OrbitalSchema, U as UseDeclaration, E as EntityRef, P as PageRef, b as Page, c as PageRefObject } from './schema-C_lv_cta.js';
+import { b as TraitConfig, g as Trait, T as TraitEventListener, h as CallSiteConfig, j as TraitEventContract, d as TraitRef, a as TraitReference } from './trait-BQIlqUHC.js';
+import { S as SExpr } from './expression-DpAj1RzP.js';
 import 'zod';
-import './effect-DQPFowvO.js';
+
+/**
+ * Event Wiring
+ *
+ * Applies cross-orbital event wiring to orbital definitions.
+ * Adds emits/listens declarations to traits so they can communicate
+ * across orbital boundaries.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A single event wiring entry connecting two traits across orbitals.
+ */
+interface EventWiringEntry {
+    /** Source trait name or orbital name */
+    from: string;
+    /** Event name (UPPER_SNAKE_CASE) */
+    event: string;
+    /** Target trait name or orbital name */
+    to: string;
+    /** Event to trigger on the listener side */
+    triggers: string;
+}
+/**
+ * Apply event wiring to orbital definitions.
+ *
+ * For each wiring entry:
+ * 1. Find the source trait and add an external emit (if not already present)
+ * 2. Find the target trait and add an external listen (if not already present)
+ *
+ * Returns a new array of orbitals with wiring applied (deep-cloned).
+ */
+declare function applyEventWiring(orbitals: OrbitalDefinition[], wiring: EventWiringEntry[]): OrbitalDefinition[];
+
+/**
+ * Layout Strategy Detection
+ *
+ * Auto-detects the best layout strategy for a composed application
+ * based on the number of orbitals and their event wiring topology.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Layout strategy for the composed application.
+ *
+ * - 'single': One orbital, one page
+ * - 'tabs': 2-4 orbitals with no sequential chain
+ * - 'sidebar': 5+ orbitals (navigation-heavy)
+ * - 'dashboard': Single page with all orbitals visible
+ * - 'wizard-flow': Sequential event chain detected (A -> B -> C)
+ */
+type LayoutStrategy = 'sidebar' | 'tabs' | 'dashboard' | 'wizard-flow' | 'single';
+/**
+ * Detect the best layout strategy based on orbital count and event wiring.
+ *
+ * Heuristic:
+ * 1. Sequential event chain detected -> 'wizard-flow'
+ * 2. 1 orbital -> 'single'
+ * 3. 2-4 orbitals -> 'tabs'
+ * 4. 5+ orbitals -> 'sidebar'
+ */
+declare function detectLayoutStrategy(orbitals: OrbitalDefinition[], eventWiring?: EventWiringEntry[]): LayoutStrategy;
+
+/**
+ * Compose Behaviors
+ *
+ * Main entry point for composing multiple orbital definitions into
+ * a single OrbitalSchema application. Handles event wiring, layout
+ * strategy detection, and page generation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Union the identity ledgers of the schema-shaped inputs (V4 Phase 6, runtime
+ * mirror of the Rust compose ledger merge). Bare OrbitalDefinition inputs and
+ * ledger-less schemas contribute nothing (pre-V4 back-compat: no ledger in →
+ * no ledger out). Entries are keyed by id; first occurrence in input order wins
+ * for a duplicate id — the rows share one identity, so a `curName` divergence
+ * across slices resolves deterministically to the earliest input's row. Output
+ * entries are sorted by id for stable, order-independent composition.
+ */
+declare function mergeLedgers(inputs: (OrbitalDefinition | OrbitalSchema)[]): IdentityLedger | undefined;
+/**
+ * Input for composing behaviors into an application.
+ */
+interface ComposeBehaviorsInput {
+    /** Application name */
+    appName: string;
+    /** Orbital definitions (or schemas) to compose */
+    orbitals: (OrbitalDefinition | OrbitalSchema)[];
+    /** Layout strategy override, or 'auto' to detect */
+    layoutStrategy?: LayoutStrategy | 'auto';
+    /** Cross-orbital event wiring */
+    eventWiring?: EventWiringEntry[];
+    /** Optional entity name mappings (original -> renamed) */
+    entityMappings?: Record<string, string>;
+}
+/**
+ * Result of composing behaviors.
+ */
+interface ComposeBehaviorsResult {
+    /** The composed OrbitalSchema */
+    schema: OrbitalSchema;
+    /** Layout metadata */
+    layout: {
+        strategy: LayoutStrategy;
+        pageCount: number;
+    };
+    /** Wiring metadata */
+    wiring: {
+        connections: number;
+    };
+}
+/**
+ * Compose multiple orbital definitions into a single application schema.
+ *
+ * Steps:
+ * 1. Apply event wiring (adds emits/listens to traits)
+ * 2. Detect or use provided layout strategy
+ * 3. Generate pages based on the strategy
+ * 4. Build the final OrbitalSchema
+ */
+declare function composeBehaviors(input: ComposeBehaviorsInput): ComposeBehaviorsResult;
+
+/**
+ * Apply trait config overrides to a schema — pure, returns a new schema.
+ *
+ * Used by config-driven preview surfaces (the playground property inspector and
+ * the verify config-sweep) to render a behavior with different `config` values
+ * WITHOUT recompiling: the override is written onto the matching trait, then the
+ * schema is re-registered and re-rendered.
+ *
+ * The resolved schema's traits are inlined `Trait`s whose `config` is the
+ * DECLARED schema (`{ field: { type, default, ... } }`), so an override patches
+ * each field's `default`. A trait that instead carries call-site value config
+ * (a `{ ref, config }` reference) gets the values merged directly.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Return a new schema with `config` overrides applied to traits whose identity
+ * (`name`, falling back to `ref`) matches a key in `overrides`. Fields not
+ * declared on the trait are ignored — overrides never invent config.
+ */
+declare function applyTraitConfigOverrides(schema: OrbitalSchema, overrides: Readonly<Record<string, TraitConfig>>): OrbitalSchema;
+
+/**
+ * Layout-Trait Builders
+ *
+ * Helpers for constructing the canonical inline LayoutTrait pattern that
+ * std layout-shell molecules (`std-filtered-list`, `std-master-detail-layout`,
+ * etc.) use to wrap a set of atom trait references in a `(render-ui main)`
+ * effect with `@trait.X` slot embeds.
+ *
+ * The canonical LayoutTrait is stateless: ONE state (`composing`, initial),
+ * ONE transition (`INIT` self-loop) carrying two effects — `(fetch Entity
+ * {emit: {success, failure}})` and `(render-ui "main" <pattern-tree>)`. Atoms
+ * embedded via `@trait.X` slot references react to the bus events the fetch
+ * emits; the LayoutTrait owns no further state.
+ *
+ * Usage from a std layout-shell molecule:
+ *
+ * ```ts
+ * import { makeSlot, makeLayoutTrait } from '@almadar/core/builders';
+ *
+ * const layout = makeLayoutTrait({
+ *   name: 'DashboardLayout',
+ *   linkedEntity: 'Metric',
+ *   fetchEntity: 'Metric',
+ *   loadedEvent: 'MetricLoaded',
+ *   loadFailedEvent: 'MetricLoadFailed',
+ *   renderUI: {
+ *     type: 'stack',
+ *     direction: 'vertical',
+ *     children: [
+ *       makeSlot('StatsRow'),
+ *       makeSlot('ChartsRow'),
+ *       makeSlot('FeedRow'),
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build a `@trait.<name>` slot reference string. Used as a child entry in a
+ * pattern tree to embed another trait's render-ui at that position. The
+ * runtime resolves `@trait.X` to the matching trait's render-ui inline.
+ *
+ * @example makeSlot('FilteredItemSearch') // "@trait.FilteredItemSearch"
+ */
+declare function makeSlot(traitName: string): string;
+/**
+ * Build a `(render-ui <slot> <root>)` effect tuple. Pattern-typed sugar over
+ * the raw `RenderUIEffect` literal so callers don't have to spell out the
+ * three-element tuple form.
+ *
+ * @param slot - Canonical UI slot name (`'main'`, `'header'`, etc. — see UI_SLOTS).
+ * @param root - The pattern config for this slot's content, OR a `@`-binding
+ *   string ({@link RenderBinding}) pointing at a render tree in `config` /
+ *   `payload` (e.g. `'@config.bodyContent'`). Pass `null` to clear.
+ */
+declare function makeRenderUI(slot: UISlot, root: AnyPatternConfig | RenderBinding | null): RenderUIEffect;
+/**
+ * Options for {@link makeLayoutTrait}.
+ */
+interface MakeLayoutTraitOpts {
+    /** Trait name, e.g. `"DashboardGridLayout"`. */
+    name: string;
+    /** Entity this layout's emits/listens bind to. */
+    linkedEntity: string;
+    /** Optional human-readable description (carried through to `Trait.description`). */
+    description?: string;
+    /**
+     * Entity name to fetch on INIT. When set, a `(fetch <Entity> {emit:
+     * {success, failure}})` effect is prepended to the INIT transition. Omit
+     * for purely-presentational layouts that don't load data themselves.
+     */
+    fetchEntity?: string;
+    /**
+     * Event name emitted on successful fetch. Required when `fetchEntity` is
+     * set; the LayoutTrait declares this event in its `emits` and uses it as
+     * the `success` emit-name in the fetch effect.
+     * Convention: `"<Entity>Loaded"`.
+     */
+    loadedEvent?: string;
+    /**
+     * Event name emitted on fetch failure. Required when `fetchEntity` is
+     * set. Convention: `"<Entity>LoadFailed"`.
+     */
+    loadFailedEvent?: string;
+    /**
+     * Payload schema for the loaded event. Defaults to `[{ name: "data", type:
+     * "[<Entity>]" }]` when `fetchEntity` is set. Provide explicitly when the
+     * payload should carry additional fields.
+     */
+    loadedPayloadSchema?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>;
+    /**
+     * The pattern tree for the layout's main slot. Children may include
+     * `@trait.X` slot strings (built via {@link makeSlot}) interleaved with
+     * inline pattern configs (`{ type: 'stack', ... }`). The shape conforms to
+     * `AnyPatternConfig` from `@almadar/patterns`.
+     */
+    renderUI: AnyPatternConfig;
+    /**
+     * Override the slot the render-ui effect targets. Defaults to `'main'`.
+     * Specify when the layout shell should render into a sub-slot (rare).
+     */
+    slot?: UISlot;
+    /**
+     * Additional effects appended to the INIT transition AFTER the fetch +
+     * render-ui pair. Most layouts don't need this; provided for advanced
+     * cases (analytics emit, persistence seed, etc.).
+     */
+    extraEffects?: Effect[];
+}
+/**
+ * Build the canonical stateless LayoutTrait used by std layout-shell molecules.
+ *
+ * Result shape:
+ * - `category: 'interaction'`, `scope: 'instance'`
+ * - `linkedEntity` set per the option
+ * - `emits` declares the loaded + loadFailed events when `fetchEntity` is set
+ * - One state: `'composing'` (`isInitial: true`)
+ * - One transition: `composing → composing` on `INIT`, with effects:
+ *   - (when `fetchEntity` set) `['fetch', '<Entity>', { emit: { success, failure } }]`
+ *   - `['render-ui', slot, renderUI]`
+ *   - …`extraEffects` if provided
+ *
+ * Atoms whose trait names appear as `@trait.<name>` strings inside `renderUI`
+ * get embedded by the runtime when the orbital instantiates. The LayoutTrait
+ * itself stays stateless — all reactive behaviour lives in the embedded atoms.
+ */
+declare function makeLayoutTrait(opts: MakeLayoutTraitOpts): Trait;
+
+/**
+ * Orbital Builders
+ *
+ * Pure functions for constructing and composing Orbitals.
+ * No new types. Everything uses existing core types:
+ * Entity, Trait, Page, OrbitalDefinition, OrbitalSchema.
+ *
+ * Three categories:
+ * 1. Builders: construct Entity, Page from common params
+ * 2. Utilities: ensureIdField, resolveDefaults
+ * 3. Composition: connect, compose, pipe
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Ensure the fields array has an `id` field. Prepends one if missing.
+ */
+declare function ensureIdField(fields?: EntityField[]): EntityField[];
+/**
+ * Simple pluralization: append 's'.
+ */
+declare function plural(name: string): string;
+interface MakeEntityOpts {
+    name: string;
+    fields: EntityField[];
+    persistence?: EntityPersistence;
+    collection?: string;
+    /** Pre-authored seed data instances */
+    instances?: EntityRow[];
+}
+/**
+ * Build an Entity from options. Auto-adds id field, auto-derives collection.
+ */
+declare function makeEntity(opts: MakeEntityOpts): Entity;
+interface MakePageOpts {
+    name: string;
+    path: string;
+    traitName: string;
+    isInitial?: boolean;
+}
+/**
+ * Build a Page that binds to a single trait.
+ */
+declare function makePage(opts: MakePageOpts): Page;
+/**
+ * Build an OrbitalDefinition from its three components.
+ */
+declare function makeOrbital(name: string, entity: Entity, traits: Trait[], pages: Page[]): OrbitalDefinition;
+/**
+ * Options for {@link makeTraitRef}.
+ */
+interface MakeTraitRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link TraitReference.from}).
+     */
+    from?: string;
+    /** Trait reference string, e.g. "Browse.traits.BrowseItemBrowse". */
+    ref: string;
+    /** Rename the inlined trait at the call site. */
+    name?: string;
+    /** Rebind the trait to a different linkedEntity. */
+    linkedEntity?: string;
+    /** Dual-carry id sibling of {@link linkedEntity} (V4 identity graph). */
+    linkedEntityId?: EntityId;
+    /** Per-key rename map, e.g. `{ OPEN: "ADD_ITEM" }`. */
+    events?: Record<string, string>;
+    /**
+     * Entity-field remap, e.g. `{ name: "title", folder: "parentId" }`. Rewrites
+     * the inlined trait's canonical `@entity.X` / `@payload.row.X` references to
+     * the consumer entity's field names. Mirrors {@link TraitReference.fields}.
+     */
+    fields?: Record<string, string>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names. See {@link TraitReference.effects} for the full contract.
+     */
+    effects?: Record<string, SExpr[]>;
+    /** Replace the imported trait's `listens` array entirely. */
+    listens?: TraitEventListener[];
+    /** Set every emit's scope. */
+    emitsScope?: 'internal' | 'external';
+    /**
+     * Call-site config overrides. Each entry is either a plain wiring value
+     * (`TraitConfigValue`) or a fully-annotated re-declaration
+     * (`ConfigFieldDeclaration`). Matches {@link TraitReference.config}.
+     */
+    config?: CallSiteConfig;
+}
+/**
+ * Typed-narrowing variant of {@link MakeTraitRefOpts} for callers that know
+ * the imported atom's overridable surfaces — its event-key set, listen-key
+ * set, and config shape. Generated std factories use this variant so an LLM
+ * tool consumer (orbital-agent) sees the closed event-name set and the
+ * config field schema instead of the un-narrowed `Record<string, string>` /
+ * `TraitConfig` defaults.
+ *
+ * Type parameters:
+ * - `EventKey`   — string union of the atom's emit event names. Narrows the
+ *   `events` rename map's keys to legal originals only.
+ * - `ConfigShape` — typed shape of the trait's `config { ... }` block (literal
+ *   unions intact). Narrows the `config` override to the atom's actual fields.
+ *   Extends `CallSiteConfig` to allow both plain wiring values and annotated
+ *   declarations. Existing callers using plain `TraitConfig` shapes are
+ *   unaffected (TraitConfig ⊆ CallSiteConfig).
+ * - `ListenKey`  — string union of the atom's listen-key contract. Narrows
+ *   each listens entry's `event` against the atom's real subscription set.
+ *
+ * Runtime behavior is unchanged — {@link makeTraitRef} accepts both the
+ * narrow and wide forms via the standard structural-typing rules. This is
+ * a type-level narrowing only; widening at the call boundary is intentional.
+ */
+interface MakeTraitRefOptsTyped<EventKey extends string = string, ConfigShape extends CallSiteConfig = Record<string, never>, ListenKey extends string = string> extends Omit<MakeTraitRefOpts, 'events' | 'effects' | 'listens' | 'config'> {
+    /** Per-key rename map, narrowed to the atom's actual event keys. */
+    events?: Partial<Record<EventKey, string>>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names so they're caller-defined (no narrowing here); values stay typed
+     * as `SExpr[]`.
+     */
+    effects?: Partial<Record<string, SExpr[]>>;
+    /**
+     * Replace the imported trait's `listens` array entirely. Each entry's
+     * `event` field is narrowed to {@link ListenKey} where the atom's
+     * subscription set is fixed; otherwise this widens to plain string.
+     */
+    listens?: Array<TraitEventListener & {
+        event?: ListenKey;
+    }>;
+    /** Typed call-site config overrides — narrowed to {@link ConfigShape}. */
+    config?: ConfigShape;
+}
+/**
+ * Build a {@link TraitReference} from options.
+ *
+ * Pass-through factory: copies only the fields that are actually provided,
+ * so optionals stay absent (no `key: undefined` slots) and the emitted
+ * object matches the inliner's expectation that "present = override".
+ */
+declare function makeTraitRef(opts: MakeTraitRefOpts): TraitReference;
+/**
+ * Options for {@link makePageRef}.
+ */
+interface MakePageRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link PageRefObject.from}).
+     */
+    from?: string;
+    /** Page reference string, e.g. "Browse.pages.BrowseItemPage". */
+    ref: string;
+    /** URL path override. */
+    path?: string;
+    /** Rebind the page's primary entity. */
+    linkedEntity?: string;
+    /** Replace the page's trait list. */
+    traits?: TraitRef[];
+}
+/**
+ * Typed-narrowing variant of {@link MakePageRefOpts}. Narrows the `traits`
+ * override array's entries to the orbital's known trait-name union — so the
+ * agent can't pass a trait name that doesn't exist on the page's owning
+ * orbital. Generated std page-helpers use this variant to surface the
+ * trait set in the tool schema; un-narrowed call sites stay compatible.
+ *
+ * Type parameter:
+ * - `TraitName` — string union of trait names the page may reference.
+ */
+interface MakePageRefOptsTyped<TraitName extends string = string> extends Omit<MakePageRefOpts, 'traits'> {
+    traits?: Array<{
+        ref: TraitName;
+    } | TraitRef>;
+}
+/**
+ * Build a {@link PageRefObject} from options. Pass-through factory — omits
+ * optional keys that are `undefined`.
+ */
+declare function makePageRef(opts: MakePageRefOpts): PageRefObject;
+/**
+ * Options for {@link makeOrbitalWithUses}.
+ */
+interface MakeOrbitalWithUsesOpts {
+    /** Orbital name. */
+    name: string;
+    /**
+     * Per-orbital `uses:` header entries (see CLAUDE.md "uses: lives inside
+     * the orbital").
+     */
+    uses: UseDeclaration[];
+    /** Entity (inline or reference form). */
+    entity: EntityRef;
+    /** Trait references. */
+    traits: TraitRef[];
+    /** Optional page references (omitted entirely when not provided). */
+    pages?: PageRef[];
+}
+/**
+ * Build an {@link OrbitalDefinition} with the `uses:` header set. Follows
+ * the convention that `uses:` lives on the orbital (not the schema).
+ *
+ * When `pages` is omitted, the result has no `pages` property (matches the
+ * existing {@link OrbitalDefinition.pages} optionality in descriptors that
+ * carry trait-only atoms).
+ */
+declare function makeOrbitalWithUses(opts: MakeOrbitalWithUsesOpts): OrbitalDefinition;
+/**
+ * Options for {@link makeAtomOrbital}.
+ *
+ * Overrides for the single trait reference. Mirrors the {@link MakeTraitRefOpts}
+ * subset that is meaningful at the atom-wrapping call site.
+ */
+interface MakeAtomOrbitalTraitOverrides {
+    name?: string;
+    events?: Record<string, string>;
+    effects?: Record<string, SExpr[]>;
+    listens?: TraitEventListener[];
+    emitsScope?: 'internal' | 'external';
+    config?: CallSiteConfig;
+}
+/**
+ * Options for {@link makeAtomOrbital}.
+ */
+interface MakeAtomOrbitalOpts {
+    /** Orbital name, e.g. `${entityName}Orbital`. */
+    name: string;
+    /** Atom registry path, e.g. `std/behaviors/atoms/std-browse`. */
+    atomPath: string;
+    /** Import alias (PascalCase), e.g. `Browse`. */
+    alias: string;
+    /** Entity definition to attach to the orbital. */
+    entity: Entity;
+    /** Trait reference string, e.g. `Browse.traits.BrowseItemBrowse`. */
+    traitRef: string;
+    /** Optional trait-level overrides applied at the call site. */
+    traitOverrides?: MakeAtomOrbitalTraitOverrides;
+    /** Optional page reference string, e.g. `Browse.pages.BrowseItemPage`. */
+    pageRef?: string;
+    /** Optional page-level overrides applied at the call site. */
+    pageOverrides?: {
+        path?: string;
+    };
+}
+/**
+ * Build a single-atom {@link OrbitalDefinition}.
+ *
+ * The common atom shape: one entity + one trait reference + (optionally) one
+ * page reference, all under a single `uses:` import. Wraps
+ * {@link makeTraitRef}, {@link makePageRef}, and {@link makeOrbitalWithUses}.
+ *
+ * The trait reference is linkedEntity-bound to `entity.name` by default so
+ * that the inliner's entity-substitution pass rewrites every `["ref", X]`
+ * and `@X.path` reference inside the atom.
+ */
+declare function makeAtomOrbital(opts: MakeAtomOrbitalOpts): OrbitalDefinition;
+/**
+ * Wrap one or more OrbitalDefinitions into an OrbitalSchema.
+ * Every .orb file should be a full OrbitalSchema — this is the builder for that.
+ */
+declare function makeSchema(name: string, ...definitions: OrbitalDefinition[]): OrbitalSchema;
+/**
+ * Merge multiple OrbitalDefinitions into one.
+ * Collects all traits from all sources into a single orbital with a shared entity.
+ * Pure: clones all traits, no mutation.
+ */
+declare function mergeOrbitals(name: string, entity: Entity, sources: OrbitalDefinition[], pages: Page[]): OrbitalDefinition;
+/**
+ * Wire an intra-orbital event between two traits.
+ * Adds emits to the source trait, listens to the target trait.
+ * Pure: returns cloned traits, no mutation.
+ */
+declare function wire(source: Trait, target: Trait, event: TraitEventContract, triggers: string): [Trait, Trait];
+/**
+ * Extract the first trait from an OrbitalDefinition or OrbitalSchema.
+ * If given an OrbitalSchema, unwraps to the first orbital inside it.
+ */
+declare function extractTrait(input: OrbitalDefinition | OrbitalSchema): Trait;
+/**
+ * Wire a cross-orbital event between two orbitals.
+ * Adds emits to a's first trait, listens to b's first trait.
+ * Pure: returns new orbitals, no mutation.
+ */
+declare function connect(a: OrbitalDefinition | OrbitalSchema, b: OrbitalDefinition | OrbitalSchema, event: TraitEventContract, triggers?: string): [OrbitalDefinition, OrbitalDefinition];
+interface ComposeConnection {
+    from: string;
+    to: string;
+    event: TraitEventContract;
+    triggers?: string;
+}
+interface ComposePage {
+    name: string;
+    path: string;
+    traits: string[];
+    isInitial?: boolean;
+}
+/**
+ * Compose multiple orbitals into a single OrbitalSchema (application).
+ * Applies connections (cross-orbital event wiring) and page assignments.
+ */
+declare function compose(orbitals: (OrbitalDefinition | OrbitalSchema)[], pages: ComposePage[], connections: ComposeConnection[], appName?: string): OrbitalSchema;
+/**
+ * Chain orbitals in sequence with automatic event wiring.
+ * Sugar over connect + compose: wires events[0] from orbital[0] to orbital[1], etc.
+ */
+declare function pipe(orbitals: (OrbitalDefinition | OrbitalSchema)[], events: TraitEventContract[], appName?: string): OrbitalSchema;
+
+export { type ComposeBehaviorsInput, type ComposeBehaviorsResult, type ComposeConnection, type ComposePage, type EventWiringEntry, type LayoutStrategy, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeLayoutTraitOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakePageRefOptsTyped, type MakeTraitRefOpts, type MakeTraitRefOptsTyped, applyEventWiring, applyTraitConfigOverrides, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeLedgers, mergeOrbitals, pipe, plural, wire };

package/dist/builders.js

@@ -625,7 +625,7 @@ var RequiredFieldSchema = z.object({
   type: z.enum(["string", "number", "boolean", "date", "array", "object", "timestamp", "datetime", "enum", "email", "url", "phone", "uuid", "image"]),
   description: z.string().optional()
 });
-z.object({
+var TraitReferenceSchema = z.object({
   ref: z.string().min(1),
   refId: TraitIdSchema.optional(),
   // V4 local declaration id (see the interface doc) — declared so the
@@ -718,19 +718,7 @@ var TraitSchema = z.object({
 });
 var TraitRefSchema = z.union([
   z.string().min(1),
-  z.object({
-    ref: z.string().min(1),
-    config: TraitConfigSchema.optional(),
-    linkedEntity: z.string().optional(),
-    name: z.string().optional(),
-    // Phase F.4: same non-empty refine as TraitReferenceSchema.events.
-    // Both schemas accept the same call-site argument shape, so the
-    // validators should agree.
-    events: z.record(
-      z.string().min(1, "events key (atom event name) must be non-empty"),
-      z.string().min(1, "events value (caller event name) must be non-empty")
-    ).optional()
-  }),
+  TraitReferenceSchema,
   TraitSchema
   // Allow inline trait definitions
 ]);