@almadar/core 7.24.0 → 7.26.0

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

@@ -114,6 +114,14 @@ interface DomainEntity extends ASTNode {
      * 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';
@@ -314,6 +322,20 @@ interface FactorySignature {
     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
@@ -361,6 +383,10 @@ interface FactoryCallSiteParams {
     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
@@ -1243,6 +1269,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
  *
@@ -1396,4 +1471,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 { 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, mergeDocuments, mergeDomainChunks, parseBehavior, parseDomainEffect, parseDomainEffects, parseDomainGuard, parseEntity, parseGuard, parsePage, parseSectionId, removeMapping, resolveConflict, schemaEntityToDomainEntity, schemaPageToDomainPage, schemaTraitToDomainBehavior, schemaTypeToDomainKeyword, tokenize, translateDomainToParams, updateMappingRange, updateSchemaHash, upsertMapping, validateDomainChunk };

package/dist/domain-language/index.js

@@ -6436,6 +6436,7 @@ function translateDomainToParams(binding, signature, presentation, ruleOverlay,
   applyEntityName(binding.entity, signature, params);
   applyEntityFields(binding.entity, signature, params, warnings);
   applyPersistence(binding.entity, signature, params, warnings);
+  applyCollection(binding.entity, params);
   applyPagePaths(binding.pages ?? [], signature, params, warnings);
   applyPresentation(presentation, signature, params, warnings);
   applyTraitOverlay(traitOverlay, signature, params, warnings);
@@ -6486,6 +6487,10 @@ function applyPersistence(entity, signature, params, warnings) {
   if (entity.persistence === signature.entities[0].persistence) return;
   params.persistence = entity.persistence;
 }
+function applyCollection(entity, params) {
+  if (!entity.collection) return;
+  params.collection = entity.collection;
+}
 function applyPagePaths(pages, signature, params, warnings) {
   if (pages.length === 0) return;
   const sigPages = new Map(signature.pages.map((p) => [p.name, p]));
@@ -7026,6 +7031,37 @@ function formatMergeSummary(result) {
   return parts.join(", ") || "empty";
 }
 
+// src/domain-language/sync/merge-documents.ts
+function mergeDocuments(base, overlay) {
+  return {
+    type: "document",
+    entities: mergeByName(base.entities, overlay.entities),
+    pages: mergeByName(base.pages, overlay.pages),
+    behaviors: mergeByName(base.behaviors, overlay.behaviors)
+  };
+}
+function mergeByName(baseItems, overlayItems) {
+  const overlayByName = /* @__PURE__ */ new Map();
+  for (const item of overlayItems) overlayByName.set(item.name, item);
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of baseItems) {
+    const replacement = overlayByName.get(item.name);
+    if (replacement) {
+      result.push(replacement);
+    } else {
+      result.push(item);
+    }
+    seen.add(item.name);
+  }
+  for (const item of overlayItems) {
+    if (!seen.has(item.name)) {
+      result.push(item);
+    }
+  }
+  return result;
+}
+
 // src/domain-language/registry.ts
 var FIELD_TYPE_REGISTRY = {
   string: {
@@ -7598,6 +7634,6 @@ function matchesRelationship(r, targetEntity, relationshipType) {
   return r.targetEntity === targetEntity && r.relationshipType === relationshipType;
 }
 
-export { EFFECT_REGISTRY, FIELD_TYPE_REGISTRY, GUARD_REGISTRY, KEYWORDS, Lexer, MULTI_WORD_KEYWORDS, TokenType, 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 { EFFECT_REGISTRY, FIELD_TYPE_REGISTRY, GUARD_REGISTRY, KEYWORDS, Lexer, MULTI_WORD_KEYWORDS, TokenType, 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, mergeDocuments, mergeDomainChunks, parseBehavior, parseDomainEffect, parseDomainEffects, parseDomainGuard, parseEntity, parseGuard, parsePage, parseSectionId, removeMapping, resolveConflict, schemaEntityToDomainEntity, schemaPageToDomainPage, schemaTraitToDomainBehavior, schemaTypeToDomainKeyword, tokenize, translateDomainToParams, updateMappingRange, updateSchemaHash, upsertMapping, validateDomainChunk };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map