@almadar/core 7.25.0 → 8.0.0

package/dist/domain-language/index.d.ts

@@ -1,557 +1,12 @@
-import { a6 as EntityField, a9 as EntityPersistence, cX as TraitReference, c$ as TraitScope, cS as TraitEventListener, a2 as Entity, br as Page, bh as OrbitalSchema, cE as Trait } from '../schema-BVni4uNf.js';
+import { e as DomainEntity, J as ParseResult, l as DomainPage, D as DomainBehavior, j as DomainGuard, H as GuardCondition, c as DomainDocument, Q as SectionMapping, P as ParseError, k as DomainMutation } from '../diff-factory-calls-DlBcMWPM.js';
+export { A as ASTNode, C as CallSiteDiff, a as ComparisonCondition, b as ComparisonOperator, d as DomainEffect, f as DomainField, g as DomainFieldDefault, h as DomainFieldItems, i as DomainFieldType, m as DomainPageAction, n as DomainPageSection, o as DomainRelationship, p as DomainRuleOverlayEntry, q as DomainTick, r as DomainTransition, E as EffectType, F as FactoryCallSite, s as FactoryCallSiteParams, t as FactoryEntitySignature, u as FactoryPageSignature, v as FactoryParamValue, w as FactorySignature, x as FactorySignatureCatalog, y as FactorySignatureEntityField, z as FactoryTraitSignature, B as FieldCheckCondition, G as FieldReference, L as LogicalCondition, I as LogicalOperator, O as OwnershipOverlayEntry, K as PresentationNavItem, M as PresentationOverlay, R as RelationshipType, N as RuleOverlay, S as SchemaFieldType, T as SourceLocation, U as SourceRange, V as TraitOverlay, W as TraitOverlayEntry, X as TraitOverlayListener, Y as TranslationBinding, Z as TranslationResult, _ as TranslationWarning, $ as UserCheckCondition, a0 as diffFactoryCalls, a1 as translateDomainToParams } from '../diff-factory-calls-DlBcMWPM.js';
 import { S as SExpr } from '../expression-BVRFm0sV.js';
+import { y as Entity, bg as Trait } from '../trait-BPe356_9.js';
+export { H as EntityPersistence, bD as TraitScope } from '../trait-BPe356_9.js';
+import { aa as Page, a3 as OrbitalSchema } from '../schema-Bg4qX43l.js';
 import 'zod';
 import '@almadar/patterns';
 
-/**
- * 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>;
-}
-/**
- * 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;
-}
-
 /**
  * Domain Language Tokens
  *
@@ -1032,88 +487,6 @@ declare function applySectionUpdate(schema: OrbitalSchema, sectionType: 'entity'
  */
 declare function deleteSection(schema: OrbitalSchema, sectionType: 'entity' | 'page' | 'behavior' | 'tick', sectionId: string): OrbitalSchema;
 
-/**
- * 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>;
-
 /**
  * Section Mapping
  *
@@ -1255,6 +628,55 @@ declare function validateDomainChunk(chunk: DomainChunk): string[];
  */
 declare function formatMergeSummary(result: MergeResult): string;
 
+/**
+ * Phase 5 — `mergeDocuments(base, overlay)` overlay reducer.
+ *
+ * The studio questionnaire renders `mergeDocuments(factoryBase,
+ * userOverlay)` as its surface — the user edits the overlay; the base
+ * never mutates. Server-side, the planner reads the user's persisted
+ * overlay and merges it on top of the catalog's `baseDocument` to
+ * derive the final `DomainDocument` fed to `translateDomainToParams`.
+ *
+ * Semantics:
+ *   - `entities[]`, `pages[]`, `behaviors[]` matched by `name`. The
+ *     overlay's entry replaces the base's; missing names from one side
+ *     are kept verbatim from the other.
+ *   - Within a matched entity / page / behavior, overlay fields win
+ *     (overlay-replace, not deep-merge). This means a user clearing
+ *     `fields: []` is honoured rather than silently re-inflating from
+ *     the base. The questionnaire UI emits partial overlays only for
+ *     the slots the user touched, so this is the right granularity.
+ *   - Arrays inside matched entries (`entities[i].fields[]`,
+ *     `pages[i].sections[]`) are NOT field-level merged — the overlay
+ *     replaces the base array verbatim when present. For granular
+ *     additions ("add a field"), the UI authors a `DomainMutation`
+ *     and applies via `applyMutation` instead of going through
+ *     `mergeDocuments`.
+ *   - Top-level `type` is always `'document'`.
+ *
+ * Pure function — no I/O, no mutation of inputs. Returns a new
+ * `DomainDocument`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Compose a base `DomainDocument` (factory catalog baseline) with a
+ * user-authored overlay (questionnaire answers + edits). Entities,
+ * pages, and behaviors are matched by `name`; the overlay replaces
+ * any base entry with the same name. Unmatched entries on either side
+ * survive unchanged.
+ *
+ * Idempotent: `mergeDocuments(d, emptyDocument)` returns a deep-copy
+ * of `d`. `mergeDocuments(emptyDocument, d)` likewise.
+ *
+ * @param base    The starting document (factory `baseDocument` or
+ *                organism-level union).
+ * @param overlay The user-authored overlay carrying edits.
+ * @returns A new merged document; neither input is mutated.
+ */
+declare function mergeDocuments(base: DomainDocument, overlay: DomainDocument): DomainDocument;
+
 /**
  * Domain Language Registry
  *
@@ -1408,4 +830,4 @@ declare function generateDomainLanguageReference(): string;
  */
 declare function applyMutation(doc: DomainDocument, mut: DomainMutation): DomainDocument;
 
-export { type ASTNode, type CallSiteDiff, type ComparisonCondition, type ComparisonOperator, type DomainBehavior, type DomainChunk, type DomainDocument, type DomainEffect, type DomainEntity, type DomainField, type DomainFieldDefault, type DomainFieldItems, type DomainFieldType, type DomainGuard, type DomainMutation, type DomainPage, type DomainPageAction, type DomainPageSection, type DomainRelationship, type DomainRuleOverlayEntry, type DomainTick, type DomainToSchemaResult, type DomainTransition, EFFECT_REGISTRY, type EffectMapping, type EffectType, EntityPersistence, FIELD_TYPE_REGISTRY, type FactoryCallSite, type FactoryCallSiteParams, type FactoryEntitySignature, type FactoryPageSignature, type FactoryParamValue, type FactorySignature, type FactorySignatureCatalog, type FactorySignatureEntityField, type FactoryTraitSignature, type FieldCheckCondition, type FieldReference, type FieldTypeMapping, GUARD_REGISTRY, type GuardCondition, type GuardMapping, KEYWORDS, Lexer, type LogicalCondition, type LogicalOperator, MULTI_WORD_KEYWORDS, type MappingStore, type MergeResult, type OwnershipOverlayEntry, type ParseError, type ParseResult, type PresentationNavItem, type PresentationOverlay, type RelationshipType, type RuleOverlay, type SchemaFieldType, type SchemaToDomainResult, type SectionMapping, type SourceLocation, type SourceRange, type Token, TokenType, type TraitOverlay, type TraitOverlayEntry, type TraitOverlayListener, TraitScope, type TranslationBinding, type TranslationResult, type TranslationWarning, type UserCheckCondition, applyMutation, applySectionUpdate, computeSchemaHash, convertDomainToSchema, convertEntitiesToDomain, convertPagesToDomain, convertSchemaToDomain, convertTraitsToDomain, createMappingStore, deleteSection, detectChanges, diffFactoryCalls, domainKeywordToSchemaType, findMapping, findMappingByPath, findMappingsByType, formatBehaviorToDomain, formatBehaviorToSchema, formatDomainGuardToSchema, formatEntityToDomain, formatEntityToSchema, formatGuardConditionToDomain, formatGuardToDomain, formatGuardToSchema, formatMergeSummary, formatPageToDomain, formatPageToSchema, formatSchemaEntityToDomain, formatSchemaGuardToDomain, formatSchemaPageToDomain, formatSchemaTraitToDomain, generateDomainLanguageReference, generateSectionId, getEffectMapping, getFieldTypeMapping, getGuardMapping, getRegisteredEffects, getRegisteredFieldTypes, getRegisteredGuards, getRegistryStats, getSchemaPath, hasSchemaChanged, isEffectRegistered, isFieldTypeRegistered, isGuardRegistered, mergeDomainChunks, parseBehavior, parseDomainEffect, parseDomainEffects, parseDomainGuard, parseEntity, parseGuard, parsePage, parseSectionId, removeMapping, resolveConflict, schemaEntityToDomainEntity, schemaPageToDomainPage, schemaTraitToDomainBehavior, schemaTypeToDomainKeyword, tokenize, translateDomainToParams, updateMappingRange, updateSchemaHash, upsertMapping, validateDomainChunk };
+export { DomainBehavior, type DomainChunk, DomainDocument, DomainEntity, DomainGuard, DomainMutation, DomainPage, type DomainToSchemaResult, EFFECT_REGISTRY, type EffectMapping, FIELD_TYPE_REGISTRY, type FieldTypeMapping, GUARD_REGISTRY, GuardCondition, type GuardMapping, KEYWORDS, Lexer, MULTI_WORD_KEYWORDS, type MappingStore, type MergeResult, ParseError, ParseResult, type SchemaToDomainResult, SectionMapping, type Token, TokenType, applyMutation, applySectionUpdate, computeSchemaHash, convertDomainToSchema, convertEntitiesToDomain, convertPagesToDomain, convertSchemaToDomain, convertTraitsToDomain, createMappingStore, deleteSection, detectChanges, domainKeywordToSchemaType, findMapping, findMappingByPath, findMappingsByType, formatBehaviorToDomain, formatBehaviorToSchema, formatDomainGuardToSchema, formatEntityToDomain, formatEntityToSchema, formatGuardConditionToDomain, formatGuardToDomain, formatGuardToSchema, formatMergeSummary, formatPageToDomain, formatPageToSchema, formatSchemaEntityToDomain, formatSchemaGuardToDomain, formatSchemaPageToDomain, formatSchemaTraitToDomain, generateDomainLanguageReference, generateSectionId, getEffectMapping, getFieldTypeMapping, getGuardMapping, getRegisteredEffects, getRegisteredFieldTypes, getRegisteredGuards, getRegistryStats, getSchemaPath, hasSchemaChanged, isEffectRegistered, isFieldTypeRegistered, isGuardRegistered, mergeDocuments, mergeDomainChunks, parseBehavior, parseDomainEffect, parseDomainEffects, parseDomainGuard, parseEntity, parseGuard, parsePage, parseSectionId, removeMapping, resolveConflict, schemaEntityToDomainEntity, schemaPageToDomainPage, schemaTraitToDomainBehavior, schemaTypeToDomainKeyword, tokenize, updateMappingRange, updateSchemaHash, upsertMapping, validateDomainChunk };