@almadar/core 7.22.0 → 7.24.0

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

@@ -1,4 +1,4 @@
-import { a6 as EntityField, a9 as EntityPersistence, cX as TraitReference, c$ as TraitScope, a2 as Entity, br as Page, bh as OrbitalSchema, cE as Trait } from '../schema-BVni4uNf.js';
+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 { S as SExpr } from '../expression-BVRFm0sV.js';
 import 'zod';
 import '@almadar/patterns';
@@ -472,6 +472,73 @@ interface PresentationNavItem {
     /** 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
@@ -1001,7 +1068,7 @@ interface TranslationResult {
     callSite: FactoryCallSite;
     warnings: ReadonlyArray<TranslationWarning>;
 }
-declare function translateDomainToParams(binding: TranslationBinding, signature: FactorySignature, presentation?: PresentationOverlay): TranslationResult;
+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,
@@ -1329,4 +1396,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 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 ParseError, type ParseResult, type PresentationNavItem, type PresentationOverlay, type RelationshipType, type SchemaFieldType, type SchemaToDomainResult, type SectionMapping, type SourceLocation, type SourceRange, type Token, TokenType, 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, 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

@@ -6430,7 +6430,7 @@ var UI_SLOTS2 = [
 ];
 
 // src/domain-language/sync/translate-domain-to-params.ts
-function translateDomainToParams(binding, signature, presentation) {
+function translateDomainToParams(binding, signature, presentation, ruleOverlay, traitOverlay, catalog) {
   const warnings = [];
   const params = {};
   applyEntityName(binding.entity, signature, params);
@@ -6438,6 +6438,8 @@ function translateDomainToParams(binding, signature, presentation) {
   applyPersistence(binding.entity, signature, params, warnings);
   applyPagePaths(binding.pages ?? [], signature, params, warnings);
   applyPresentation(presentation, signature, params, warnings);
+  applyTraitOverlay(traitOverlay, signature, params, warnings);
+  applyRuleOverlay(ruleOverlay, signature, binding, catalog, params, warnings);
   return {
     callSite: {
       organism: signature.organism,
@@ -6526,6 +6528,165 @@ function applyPresentation(overlay, signature, params, warnings) {
     }
   };
 }
+function applyTraitOverlay(overlay, signature, params, warnings) {
+  if (!overlay) return;
+  const traitsByName = new Map(signature.traits.map((t) => [t.name, t]));
+  for (const [traitName, entry] of Object.entries(overlay)) {
+    const trait = traitsByName.get(traitName);
+    if (!trait) {
+      warnings.push({
+        field: `traitOverlay.${traitName}`,
+        reason: `factory signature has no trait named "${traitName}"`
+      });
+      continue;
+    }
+    mergeTraitOverride(traitName, entry, trait, params, warnings);
+  }
+}
+function mergeTraitOverride(traitName, entry, trait, params, warnings) {
+  const advertised = new Set(trait.overridableConfigKeys);
+  const existing = params.traitOverrides?.[traitName] ?? {};
+  const existingConfig = existing.config ?? {};
+  const mergedConfig = { ...existingConfig };
+  if (entry.config) {
+    for (const [k, v] of Object.entries(entry.config)) {
+      if (!advertised.has(k)) {
+        warnings.push({
+          field: `traitOverlay.${traitName}.config.${k}`,
+          reason: `trait does not advertise config key "${k}" (overridableConfigKeys: [${trait.overridableConfigKeys.join(", ")}])`
+        });
+        continue;
+      }
+      mergedConfig[k] = v;
+    }
+  }
+  const next = {
+    ...existing,
+    ...Object.keys(mergedConfig).length > 0 ? { config: mergedConfig } : {}
+  };
+  params.traitOverrides = {
+    ...params.traitOverrides,
+    [traitName]: next
+  };
+}
+function applyRuleOverlay(overlay, signature, binding, catalog, params, warnings) {
+  if (!overlay) return;
+  for (const rule of overlay.rules) {
+    if (!ruleAppliesToBinding(rule, binding)) continue;
+    if (!catalog) {
+      warnings.push({
+        field: `ruleOverlay.rules.${rule.id}`,
+        reason: "rule overlay supplied without a catalog \u2014 capability lookup requires one"
+      });
+      continue;
+    }
+    const match = findTraitByCapability(catalog, rule.capability);
+    if (!match) {
+      warnings.push({
+        field: `ruleOverlay.rules.${rule.id}`,
+        reason: `no trait in the catalog advertises capability "${rule.capability}"`
+      });
+      continue;
+    }
+    appendRuleExtraTrait(rule, match, binding, params);
+    if (rule.config) {
+      threadRuleConfig(rule, match.trait, params, warnings);
+    }
+  }
+  if (overlay.ownership) {
+    for (const entry of overlay.ownership) {
+      if (entry.entity !== binding.entity.name) continue;
+      applyOwnership(entry, params, signature, catalog, warnings);
+    }
+  }
+}
+function ruleAppliesToBinding(rule, binding) {
+  if (rule.appliesTo.length === 0) return true;
+  return rule.appliesTo.includes(binding.entity.name);
+}
+function findTraitByCapability(catalog, capability) {
+  for (const sig of catalog) {
+    for (const trait of sig.traits) {
+      if (trait.capabilities.includes(capability)) {
+        return { signature: sig, trait };
+      }
+    }
+  }
+  return void 0;
+}
+function appendRuleExtraTrait(rule, match, binding, params) {
+  const fromPath = `std/behaviors/${match.signature.organism}`;
+  const alias = organismToAlias(match.signature.organism);
+  const ref2 = {
+    from: fromPath,
+    ref: `${alias}.traits.${match.trait.name}`,
+    linkedEntity: binding.entity.name
+  };
+  const existing = params.extraTraits ?? [];
+  params.extraTraits = [...existing, ref2];
+}
+function organismToAlias(organism) {
+  const trimmed = organism.startsWith("std-") ? organism.slice(4) : organism;
+  return trimmed.split("-").filter((s) => s.length > 0).map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+function threadRuleConfig(rule, trait, params, warnings) {
+  if (!rule.config) return;
+  const advertised = new Set(trait.overridableConfigKeys);
+  const existing = params.traitOverrides?.[trait.name] ?? {};
+  const existingConfig = existing.config ?? {};
+  const merged = { ...existingConfig };
+  for (const [k, v] of Object.entries(rule.config)) {
+    if (!advertised.has(k)) {
+      warnings.push({
+        field: `ruleOverlay.rules.${rule.id}.config.${k}`,
+        reason: `trait "${trait.name}" does not advertise config key "${k}"`
+      });
+      continue;
+    }
+    merged[k] = v;
+  }
+  if (Object.keys(merged).length > 0) {
+    params.traitOverrides = {
+      ...params.traitOverrides,
+      [trait.name]: { ...existing, config: merged }
+    };
+  }
+}
+function applyOwnership(entry, params, signature, catalog, warnings) {
+  const local = signature.traits.find(
+    (t) => t.overridableConfigKeys.includes("ownerField")
+  );
+  if (local) {
+    writeOwnerField(local.name, entry.ownerField, params);
+    return;
+  }
+  if (catalog) {
+    for (const sig of catalog) {
+      const trait = sig.traits.find(
+        (t) => t.overridableConfigKeys.includes("ownerField")
+      );
+      if (trait) {
+        writeOwnerField(trait.name, entry.ownerField, params);
+        return;
+      }
+    }
+  }
+  warnings.push({
+    field: `ruleOverlay.ownership.${entry.entity}`,
+    reason: "no trait in the bound signature or catalog advertises an `ownerField` config knob"
+  });
+}
+function writeOwnerField(traitName, ownerField, params) {
+  const existing = params.traitOverrides?.[traitName] ?? {};
+  const existingConfig = existing.config ?? {};
+  params.traitOverrides = {
+    ...params.traitOverrides,
+    [traitName]: {
+      ...existing,
+      config: { ...existingConfig, ownerField }
+    }
+  };
+}
 function lowerField(f) {
   const schemaType = DOMAIN_TO_SCHEMA_FIELD_TYPE[f.fieldType];
   if (!schemaType) return void 0;