@almadar/core 7.25.0 → 8.0.0

package/dist/builders.d.ts

@@ -1,6 +1,7 @@
-import { d7 as UISlot, Z as Effect, cE as Trait, bN as RenderUIEffect, cQ as TraitEventContract, a2 as Entity, cS as TraitEventListener, cH as TraitConfig, a6 as EntityField, a9 as EntityPersistence, ag as EntityRow, dc as UseDeclaration, ab as EntityRef, cV as TraitRef, bs as PageRef, b6 as OrbitalDefinition, bh as OrbitalSchema, br as Page, bt as PageRefObject, cX as TraitReference } from './schema-BVni4uNf.js';
+import { bL as UISlot, t as Effect, bg as Trait, aC as RenderUIEffect, bs as TraitEventContract, y as Entity, bu as TraitEventListener, bj as TraitConfig, B as EntityField, H as EntityPersistence, L as EntityRow, bx as TraitRef, bz as TraitReference } from './trait-BPe356_9.js';
+import { aA as UseDeclaration, B as EntityRef, ab as PageRef, X as OrbitalDefinition, a3 as OrbitalSchema, aa as Page, ac as PageRefObject } from './schema-Bg4qX43l.js';
 import { S as SExpr } from './expression-BVRFm0sV.js';
-export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiringEntry, L as LayoutStrategy, b as applyEventWiring, c as composeBehaviors, d as detectLayoutStrategy } from './compose-behaviors-CHAMivlZ.js';
+export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiringEntry, L as LayoutStrategy, b as applyEventWiring, c as composeBehaviors, d as detectLayoutStrategy } from './compose-behaviors-Bq8tdeBU.js';
 import { AnyPatternConfig } from '@almadar/patterns';
 import 'zod';
 

package/dist/{compose-behaviors-CHAMivlZ.d.ts → compose-behaviors-Bq8tdeBU.d.ts}

@@ -1,4 +1,4 @@
-import { b6 as OrbitalDefinition, bh as OrbitalSchema } from './schema-BVni4uNf.js';
+import { X as OrbitalDefinition, a3 as OrbitalSchema } from './schema-Bg4qX43l.js';
 
 /**
  * Event Wiring

package/dist/diff-factory-calls-DlBcMWPM.d.ts

@@ -0,0 +1,648 @@
+import { B as EntityField, H as EntityPersistence, bz as TraitReference, bD as TraitScope, bu as TraitEventListener } from './trait-BPe356_9.js';
+
+/**
+ * Domain Language Types
+ *
+ * AST node types for the domain language that maps to KFlow schema.
+ * All entity references use explicit names (e.g., Order, Task, CurrentUser)
+ * per GAP-002 - no magic variables like `entity.` or `context.`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Field type mapping: OrbitalSchema type → Domain Language keyword
+ *
+ * This is the single source of truth for type conversion.
+ * When adding new field types to OrbitalSchema, add the mapping here.
+ */
+declare const FIELD_TYPE_MAPPING: {
+    readonly string: "text";
+    readonly number: "number";
+    readonly boolean: "yes/no";
+    readonly date: "date";
+    readonly timestamp: "timestamp";
+    readonly datetime: "datetime";
+    readonly array: "list";
+    readonly object: "object";
+    readonly enum: "enum";
+    readonly relation: "relation";
+};
+/**
+ * Effect operator mapping: Both systems use the same operator names
+ */
+declare const EFFECT_OPERATORS: readonly ["set", "emit", "navigate", "render-ui", "persist", "call-service", "spawn", "despawn", "do", "notify"];
+/**
+ * Effect operator names (S-expression first element)
+ * These are the operators used in S-expression effects like ['emit', ...]
+ */
+type EffectType = (typeof EFFECT_OPERATORS)[number];
+interface SourceLocation {
+    line: number;
+    column: number;
+    offset: number;
+}
+interface SourceRange {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+interface ASTNode {
+    type: string;
+    range?: SourceRange;
+}
+/**
+ * Domain Language field types
+ *
+ * Note: These map to OrbitalSchema types via DOMAIN_TO_SCHEMA_FIELD_TYPE
+ */
+type DomainFieldType = 'text' | 'long text' | 'number' | 'currency' | 'date' | 'timestamp' | 'datetime' | 'yes/no' | 'enum' | 'list' | 'object' | 'relation';
+/**
+ * OrbitalSchema field types (for reference)
+ */
+type SchemaFieldType = keyof typeof FIELD_TYPE_MAPPING;
+/**
+ * Default value for a `DomainField`. Mirrors the JSON-leaf shape an
+ * `EntityField.default` may carry on `OrbitalSchema`: scalar, list, or
+ * nested object (when the field type is `'object'` or `'list'`).
+ */
+type DomainFieldDefault = string | number | boolean | null | DomainFieldDefault[] | {
+    [k: string]: DomainFieldDefault;
+};
+/**
+ * For `fieldType: 'list'`, the typed shape of each item. Mirrors
+ * `EntityField.items` on `OrbitalSchema`. Currently a single-level
+ * type tag (matching how the schema uses it); extend if/when nested
+ * list-of-list / list-of-object signatures are required.
+ */
+interface DomainFieldItems {
+    type: DomainFieldType;
+}
+interface DomainField extends ASTNode {
+    type: 'field';
+    name: string;
+    fieldType: DomainFieldType;
+    required: boolean;
+    unique: boolean;
+    auto: boolean;
+    default?: DomainFieldDefault;
+    enumValues?: string[];
+    /** List-of-X item type when `fieldType === 'list'`. */
+    items?: DomainFieldItems;
+}
+type RelationshipType = 'belongs_to' | 'has_many' | 'has_one';
+interface DomainRelationship extends ASTNode {
+    type: 'relationship';
+    relationshipType: RelationshipType;
+    targetEntity: string;
+    alias?: string;
+}
+interface DomainEntity extends ASTNode {
+    type: 'entity';
+    name: string;
+    description: string;
+    fields: DomainField[];
+    relationships: DomainRelationship[];
+    states?: string[];
+    initialState?: string;
+    /**
+     * Storage mode on the resolved schema. Mirrors `EntityPersistence` in
+     * `@almadar/core/types/entity.ts`. Omitted ⇒ projector defaults to
+     * `'persistent'`. Domain text syntax: `Persistence: <value>` line in
+     * the entity section.
+     */
+    persistence?: EntityPersistence;
+    /**
+     * Storage collection key. Mirrors `OrbitalSchema.entities[i].collection`.
+     * Omitted ⇒ defaults to `plural(name).toLowerCase()`. Surfaced to the
+     * factory translator so the LLM can override the storage key without
+     * touching the entity name (e.g. entity `Product` → collection
+     * `"catalog"`).
+     */
+    collection?: string;
+}
+interface DomainPageSection extends ASTNode {
+    type: 'page_section';
+    description: string;
+}
+interface DomainPageAction extends ASTNode {
+    type: 'page_action';
+    trigger: string;
+    action: string;
+}
+interface DomainPage extends ASTNode {
+    type: 'page';
+    name: string;
+    description: string;
+    purpose: string;
+    url: string;
+    primaryEntity?: string;
+    traitName?: string;
+    sections: DomainPageSection[];
+    actions: DomainPageAction[];
+    onAccess?: string;
+}
+type ComparisonOperator = '==' | '!=' | '>' | '<' | '>=' | '<=';
+type LogicalOperator = 'AND' | 'OR';
+interface FieldReference extends ASTNode {
+    type: 'field_reference';
+    entityName: string;
+    fieldName: string;
+}
+interface FieldCheckCondition extends ASTNode {
+    type: 'field_check';
+    field: FieldReference;
+    check: 'provided' | 'empty' | 'equals';
+    value?: string | number | boolean;
+}
+interface ComparisonCondition extends ASTNode {
+    type: 'comparison';
+    field: FieldReference;
+    operator: ComparisonOperator;
+    value: string | number | boolean;
+}
+interface UserCheckCondition extends ASTNode {
+    type: 'user_check';
+    check: 'is_role' | 'owns_this';
+    role?: string;
+    ownerField?: string;
+}
+interface LogicalCondition extends ASTNode {
+    type: 'logical';
+    operator: LogicalOperator;
+    left: GuardCondition;
+    right: GuardCondition;
+}
+type GuardCondition = FieldCheckCondition | ComparisonCondition | UserCheckCondition | LogicalCondition;
+interface DomainGuard extends ASTNode {
+    type: 'guard';
+    condition: GuardCondition;
+    raw: string;
+}
+interface DomainEffect extends ASTNode {
+    type: 'effect';
+    effectType: EffectType;
+    description: string;
+    config: Record<string, unknown>;
+}
+interface DomainTransition extends ASTNode {
+    type: 'transition';
+    fromState: string;
+    toState: string;
+    event: string;
+    guards: DomainGuard[];
+    effects: DomainEffect[];
+}
+interface DomainTick extends ASTNode {
+    type: 'tick';
+    name: string;
+    interval: string;
+    intervalMs?: number;
+    guard?: DomainGuard;
+    effects: DomainEffect[];
+}
+interface DomainBehavior extends ASTNode {
+    type: 'behavior';
+    name: string;
+    entityName: string;
+    states: string[];
+    initialState: string;
+    transitions: DomainTransition[];
+    ticks: DomainTick[];
+    rules: string[];
+    /**
+     * Instance- vs collection-scoped state machine. Mirrors
+     * `Trait.scope: TraitScope` in `@almadar/core/types/trait.ts`.
+     * Omitted ⇒ projector defaults to `'instance'`. Domain text syntax:
+     * `Scope: instance|collection` line in the behavior section.
+     */
+    scope?: TraitScope;
+}
+interface DomainDocument extends ASTNode {
+    type: 'document';
+    entities: DomainEntity[];
+    pages: DomainPage[];
+    behaviors: DomainBehavior[];
+}
+interface SectionMapping {
+    sectionId: string;
+    sectionType: 'entity' | 'page' | 'behavior' | 'tick';
+    schemaPath: string;
+    domainText: string;
+    aiDescription?: string;
+    range?: SourceRange;
+    lastModified?: number;
+}
+interface ParseError {
+    message: string;
+    range?: SourceRange;
+    suggestion?: string;
+}
+interface ParseResult<T> {
+    success: boolean;
+    data?: T;
+    errors: ParseError[];
+    warnings: ParseError[];
+}
+/**
+ * One field on a factory's canonical entity, in signature form. Mirrors
+ * the subset of `EntityField` that the projector needs to score a
+ * domain-entity match. Auto-added audit fields (id / createdAt /
+ * updatedAt) are omitted by the extractor.
+ */
+interface FactorySignatureEntityField {
+    name: string;
+    type: SchemaFieldType;
+    required: boolean;
+}
+/**
+ * The canonical entity a factory produces. Almost always one entity
+ * per orbital; modeled as an array to keep the door open for orbitals
+ * that compose multiple entities.
+ */
+interface FactoryEntitySignature {
+    /** Canonical entity name the factory's params build (e.g. `"ChatMessage"`). */
+    name: string;
+    /** Fields the factory emits, post-auto-field stripping. */
+    fields: ReadonlyArray<FactorySignatureEntityField>;
+    /** Persistence mode declared on the canonical entity in the `.orb`. */
+    persistence: EntityPersistence;
+}
+/**
+ * One trait the factory composes into the orbital. The projector reads
+ * these to determine which factory's trait stack covers a given
+ * `DomainBehavior` + which override knobs a presentation overlay can
+ * deterministically target. Trait identity is by `name` only; the
+ * projector matches structurally on the event / config arrays — no
+ * inferred "kind" tag.
+ */
+interface FactoryTraitSignature {
+    /** Canonical trait name post-rename (e.g. `"ChatMessageList"`). */
+    name: string;
+    /** Event keys this trait emits (post-rename). Read directly from
+     *  the trait's `emits[].event`. */
+    emittedEvents: ReadonlyArray<string>;
+    /** Event keys this trait listens for. Read directly from `listens[].event`. */
+    listenedEvents: ReadonlyArray<string>;
+    /** Config keys overridable via `traitOverrides.<name>.config.<key>`.
+     *  Read directly from the trait's `config` declaration block. */
+    overridableConfigKeys: ReadonlyArray<string>;
+    /** Capability tags lifted directly from the source `.lolo` trait's
+     *  header annotations. Free-form strings — the Phase 4 translator
+     *  overlay matches rules to traits by exact set membership. Empty
+     *  when the trait declared none. See `docs/Almadar_Domain_Language.md`
+     *  Phase 3. */
+    capabilities: ReadonlyArray<string>;
+}
+/** One page the factory emits. The path is the factory default; the
+ *  projector may override via `params.pagePath` or `params.pages[].path`. */
+interface FactoryPageSignature {
+    name: string;
+    defaultPath: string;
+    primaryEntity: string;
+}
+interface FactorySignature {
+    /** Organism the factory belongs to (e.g. `"std-realtime-chat"`). */
+    organism: string;
+    /** Orbital this factory builds within that organism. */
+    orbital: string;
+    /** Tier the factory sits in (informational; drives nothing today). */
+    tier: 'atoms' | 'molecules' | 'organisms';
+    /** Path of the generated factory source (relative to the std root). */
+    factoryPath: string;
+    /** Canonical entity surface(s) the factory produces. */
+    entities: ReadonlyArray<FactoryEntitySignature>;
+    /** Trait stack the factory composes. */
+    traits: ReadonlyArray<FactoryTraitSignature>;
+    /** Pages the factory emits. */
+    pages: ReadonlyArray<FactoryPageSignature>;
+    /** Union of all `traits[].emittedEvents`. */
+    emittedEvents: ReadonlyArray<string>;
+    /** Union of all `traits[].listenedEvents`. */
+    listenedEvents: ReadonlyArray<string>;
+    /**
+     * Phase 5 — canonical starting `DomainDocument` fragment the studio
+     * questionnaire renders before any user input. Lifted verbatim from
+     * the factory's resolved `.orb` by `almadar-pattern-sync`. Users
+     * append / override via `DomainMutation` from the questionnaire UI;
+     * the base itself is never edited in place (consumers compose with
+     * `mergeDocuments(base, overlay)`).
+     *
+     * Optional during the 7.26.x transition — older catalog snapshots
+     * predating the sync regeneration omit it. Consumers should fall
+     * back to building a minimal document from `entities` + `pages`
+     * when this is missing.
+     */
+    baseDocument?: DomainDocument;
+}
+/**
+ * Aggregate catalog written to
+ * `packages/almadar-std/behaviors/registry/factory-signatures.json`.
+ * Sorted by organism then orbital. One entry per factory in the
+ * regenerate pipeline.
+ */
+interface FactorySignatureCatalog {
+    /** Generated-by version stamp (the `@almadar/std` minor it shipped in). */
+    generatedFromStdVersion: string;
+    /** Sorted list of factory signatures. */
+    signatures: ReadonlyArray<FactorySignature>;
+}
+/**
+ * A single factory invocation, as the typed result of the translator.
+ * Lower into runtime by calling the factory at `factoryPath` with
+ * these `params`. Stable identity for downstream diffing is
+ * `(organism, orbital)`.
+ */
+interface FactoryCallSite {
+    /** Matches `FactorySignature.organism`. */
+    organism: string;
+    /** Matches `FactorySignature.orbital`. */
+    orbital: string;
+    /** Matches `FactorySignature.factoryPath`. Convenience pointer; the
+     *  authoritative source remains the signature catalog. */
+    factoryPath: string;
+    /** Typed param surface fed to the factory at invocation time. */
+    params: FactoryCallSiteParams;
+}
+/**
+ * The typed param surface every factory's call site populates. Each
+ * field on this interface corresponds to one row in the translator's
+ * domain↔factory mapping table. Adding a new domain concept means
+ * adding a field here AND wiring it in `translateDomainToParams`.
+ *
+ * Fields are all optional because not every factory consumes every
+ * concept; the translator only sets what the chosen signature
+ * advertises.
+ */
+interface FactoryCallSiteParams {
+    /** Override `signature.entities[0].name` (entity rename). */
+    entityName?: string;
+    /** Additional or overriding entity fields. Caller wins on collision. */
+    entityFields?: ReadonlyArray<EntityField>;
+    /** Override `signature.entities[0].persistence`. */
+    persistence?: EntityPersistence;
+    /** Override the entity's storage collection key. Defaults to
+     *  `plural(entityName).toLowerCase()` at factory dispatch time
+     *  when omitted. */
+    collection?: string;
+    /** Per-page path overrides keyed by `signature.pages[i].name`. */
+    pagePaths?: Readonly<Record<string, string>>;
+    /** Trait config overrides keyed by `signature.traits[i].name`. Each
+     *  value is a record keyed by the trait's `overridableConfigKeys`. */
+    traitOverrides?: Readonly<Record<string, {
+        config?: Readonly<Record<string, FactoryParamValue>>;
+    }>>;
+    /** Extra traits to compose into the orbital that aren't part of the
+     *  canonical signature trait stack. Used when a domain behavior
+     *  isn't covered by any canonical trait. */
+    extraTraits?: ReadonlyArray<TraitReference>;
+}
+/**
+ * Allowed leaf values for the typed factory-param surface. Same as
+ * `DomainFieldDefault` minus null, plus arrays + records to mirror
+ * the trait-config shape factories accept today.
+ */
+type FactoryParamValue = string | number | boolean | ReadonlyArray<FactoryParamValue> | {
+    readonly [key: string]: FactoryParamValue;
+};
+/**
+ * Discriminated union of edits to a `DomainDocument`. Each variant
+ * carries typed AST nodes already defined in this file — never raw
+ * JSON. `applyMutation` is total over this union.
+ */
+type DomainMutation = {
+    kind: 'add-entity';
+    entity: DomainEntity;
+} | {
+    kind: 'remove-entity';
+    entityName: string;
+} | {
+    kind: 'rename-entity';
+    from: string;
+    to: string;
+} | {
+    kind: 'update-entity';
+    entityName: string;
+    entity: DomainEntity;
+} | {
+    kind: 'add-field';
+    entityName: string;
+    field: DomainField;
+} | {
+    kind: 'remove-field';
+    entityName: string;
+    fieldName: string;
+} | {
+    kind: 'update-field';
+    entityName: string;
+    field: DomainField;
+} | {
+    kind: 'add-page';
+    page: DomainPage;
+} | {
+    kind: 'remove-page';
+    pageName: string;
+} | {
+    kind: 'update-page';
+    pageName: string;
+    page: DomainPage;
+} | {
+    kind: 'add-behavior';
+    behavior: DomainBehavior;
+} | {
+    kind: 'remove-behavior';
+    behaviorName: string;
+} | {
+    kind: 'update-behavior';
+    behaviorName: string;
+    behavior: DomainBehavior;
+} | {
+    kind: 'add-transition';
+    behaviorName: string;
+    transition: DomainTransition;
+} | {
+    kind: 'remove-transition';
+    behaviorName: string;
+    from: string;
+    to: string;
+    event: string;
+} | {
+    kind: 'add-relationship';
+    entityName: string;
+    relationship: DomainRelationship;
+} | {
+    kind: 'remove-relationship';
+    entityName: string;
+    targetEntity: string;
+    relationshipType: RelationshipType;
+};
+/**
+ * Cross-cutting presentation knobs that don't live in `DomainDocument`
+ * because they're factory-layer concerns (nav items live on a layout
+ * trait; theme is a separate `ThemeRef`). The translator reads these
+ * and threads them into the matching factory params.
+ */
+interface PresentationOverlay {
+    /** Nav items to add to the orbital's layout trait. The translator
+     *  looks for a `signature.traits[i]` with `overridableConfigKeys`
+     *  including `navItems` and writes into `traitOverrides[name].config.navItems`. */
+    navAdditions?: ReadonlyArray<PresentationNavItem>;
+    /** Optional theme ref override for the orbital. */
+    themeRef?: string;
+}
+interface PresentationNavItem {
+    label: string;
+    path: string;
+    /** Optional icon key (consumer-resolved). */
+    icon?: string;
+}
+/**
+ * LLM-authored trait-level overrides keyed by trait name (matches
+ * `signature.traits[].name`). Each entry's `config` keys are
+ * validated against `signature.traits[i].overridableConfigKeys`;
+ * unknown trait names or unknown config keys emit typed warnings
+ * and are skipped. Mirrors the existing call-site override surface
+ * on `TraitReference` in `OrbitalSchema`.
+ */
+type TraitOverlay = Readonly<Record<string, TraitOverlayEntry>>;
+interface TraitOverlayEntry {
+    config?: Readonly<Record<string, FactoryParamValue>>;
+    linkedEntity?: string;
+    events?: Readonly<Record<string, string>>;
+    name?: string;
+    emitsScope?: 'internal' | 'external';
+    /** Reuses `TraitEventListener` from `@almadar/core/types/trait` so the
+     *  overlay's listen entries carry the same `event` / `triggers` /
+     *  `source` / `guard` shape as everywhere else — no narrower clone. */
+    listens?: ReadonlyArray<TraitEventListener>;
+}
+/** @deprecated Phase 4.1 placeholder — use `TraitEventListener` instead.
+ *  Kept as a structural type alias so callers that imported it keep
+ *  compiling through the transition; will be removed in 7.25.0. */
+type TraitOverlayListener = TraitEventListener;
+/**
+ * Rules carry a free-form `capability: string` that the translator
+ * matches against `signature.traits[].capabilities` (source-tagged
+ * in `.lolo`, propagated via `@almadar/core@7.22.0`).
+ *
+ * NO closed enum on `capability` — atoms advertise capability
+ * strings in their `.lolo` headers, and the catalog grows the
+ * vocabulary organically. The agent emits whatever capability
+ * string the user's domain expresses; if no trait in the catalog
+ * advertises that capability, the translator emits a typed warning.
+ */
+interface RuleOverlay {
+    rules: ReadonlyArray<DomainRuleOverlayEntry>;
+    /**
+     * Entity-level ownership signal. Until Phase 1.5 promotes
+     * `ownedBy` into `DomainEntity`, ownership rides here as a
+     * parallel typed channel. The translator threads it into the
+     * matched trait's `config.ownerField` (when the matched trait
+     * advertises that key in `overridableConfigKeys`).
+     */
+    ownership?: ReadonlyArray<OwnershipOverlayEntry>;
+}
+interface DomainRuleOverlayEntry {
+    id: string;
+    /** Free-form capability label, matched against
+     *  `signature.traits[].capabilities` by exact set membership. */
+    capability: string;
+    description: string;
+    /** Entity names this rule binds to. Empty array = cross-cutting:
+     *  the rule applies to every orbital the translator visits. */
+    appliesTo: ReadonlyArray<string>;
+    /** Optional role name (e.g. `"admin"`) when the rule is role-scoped. */
+    role?: string;
+    /** Optional extra config knobs threaded into the matched trait's
+     *  `config`. Validated against the trait's `overridableConfigKeys`. */
+    config?: Readonly<Record<string, FactoryParamValue>>;
+}
+interface OwnershipOverlayEntry {
+    /** Entity name (matches `DomainEntity.name`). */
+    entity: string;
+    /** Field name on the entity that carries the owner identifier. */
+    ownerField: string;
+}
+
+/**
+ * Deterministic translator: one `DomainDocument` slice + one chosen
+ * `FactorySignature` → one `FactoryCallSite`. The agent picks the
+ * signature upstream via embedding-search over the catalog; this
+ * function does ZERO matching. It just lowers domain fields onto the
+ * factory's advertised param surface, field-by-field.
+ *
+ * The binding (which `DomainEntity` / `DomainPage[]` map to this
+ * orbital) is the agent's explicit decision and is passed in. No name
+ * matching, no scoring, no tie-breaks.
+ *
+ * Adding a new domain concept means:
+ *   1. Add a field on `DomainEntity` / `DomainPage` / `DomainBehavior`
+ *      (`packages/almadar-core/src/domain-language/types.ts`).
+ *   2. Make sure at least one factory signature advertises a
+ *      consuming knob (Phase 1.5 gate — generated by
+ *      almadar-pattern-sync from `.orb`).
+ *   3. Add one helper-fn row below that lowers the new field into
+ *      `FactoryCallSiteParams`.
+ *
+ * If a binding field has no signature consumer, the translator emits
+ * a typed warning and SKIPS the field — that's the loud signal the
+ * field shouldn't have been admitted to the language.
+ */
+
+/**
+ * The slice of `DomainDocument` that maps onto the chosen signature.
+ * The agent assembles this when it picks the signature: it knows
+ * which `DomainEntity` / `DomainPage[]` are this orbital's
+ * responsibility.
+ */
+interface TranslationBinding {
+    /** The single domain entity this signature's orbital owns. */
+    entity: DomainEntity;
+    /** Pages from the domain doc that map to this orbital's pages. The
+     *  translator pairs them with `signature.pages[]` by name. */
+    pages?: ReadonlyArray<DomainPage>;
+}
+interface TranslationWarning {
+    /** Dotted path of the domain field that couldn't be lowered. */
+    field: string;
+    /** Human-readable reason. */
+    reason: string;
+}
+interface TranslationResult {
+    callSite: FactoryCallSite;
+    warnings: ReadonlyArray<TranslationWarning>;
+}
+declare function translateDomainToParams(binding: TranslationBinding, signature: FactorySignature, presentation?: PresentationOverlay, ruleOverlay?: RuleOverlay, traitOverlay?: TraitOverlay, catalog?: ReadonlyArray<FactorySignature>): TranslationResult;
+
+/**
+ * Structural diff between two `FactoryCallSite[]` lists. Pure typed,
+ * no side effects. Used by downstream consumers (agent planner, UI
+ * cascade view) to turn a "previous calls" + "next calls" pair into a
+ * minimal change set.
+ *
+ * Identity for diffing is `(organism, orbital)`. Renames are not
+ * handled here — they show up as a delete + add. The agent layer is
+ * expected to merge those back into a `'rename'` op if it can prove
+ * the underlying domain entity was renamed.
+ */
+
+type CallSiteDiff = {
+    kind: 'add';
+    orbitalName: string;
+    next: FactoryCallSite;
+} | {
+    kind: 'delete';
+    orbitalName: string;
+    prior: FactoryCallSite;
+} | {
+    kind: 'edit';
+    orbitalName: string;
+    prior: FactoryCallSite;
+    next: FactoryCallSite;
+} | {
+    kind: 'keep';
+    orbitalName: string;
+    call: FactoryCallSite;
+};
+declare function diffFactoryCalls(prior: ReadonlyArray<FactoryCallSite>, next: ReadonlyArray<FactoryCallSite>): ReadonlyArray<CallSiteDiff>;
+
+export { type UserCheckCondition as $, type ASTNode as A, type FieldCheckCondition as B, type CallSiteDiff as C, type DomainBehavior as D, type EffectType as E, type FactoryCallSite as F, type FieldReference as G, type GuardCondition as H, type LogicalOperator as I, type ParseResult as J, type PresentationNavItem as K, type LogicalCondition as L, type PresentationOverlay as M, type RuleOverlay as N, type OwnershipOverlayEntry as O, type ParseError as P, type SectionMapping as Q, type RelationshipType as R, type SchemaFieldType as S, type SourceLocation as T, type SourceRange as U, type TraitOverlay as V, type TraitOverlayEntry as W, type TraitOverlayListener as X, type TranslationBinding as Y, type TranslationResult as Z, type TranslationWarning as _, type ComparisonCondition as a, diffFactoryCalls as a0, translateDomainToParams as a1, type ComparisonOperator as b, type DomainDocument as c, type DomainEffect as d, type DomainEntity as e, type DomainField as f, type DomainFieldDefault as g, type DomainFieldItems as h, type DomainFieldType as i, type DomainGuard as j, type DomainMutation as k, type DomainPage as l, type DomainPageAction as m, type DomainPageSection as n, type DomainRelationship as o, type DomainRuleOverlayEntry as p, type DomainTick as q, type DomainTransition as r, type FactoryCallSiteParams as s, type FactoryEntitySignature as t, type FactoryPageSignature as u, type FactoryParamValue as v, type FactorySignature as w, type FactorySignatureCatalog as x, type FactorySignatureEntityField as y, type FactoryTraitSignature as z };