@almadar/core 7.17.0 → 7.18.0

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

@@ -13,6 +13,24 @@ import '@almadar/patterns';
  * @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
  */
@@ -41,6 +59,10 @@ interface ASTNode {
  * 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
@@ -216,6 +238,102 @@ interface ParseResult<T> {
     errors: ParseError[];
     warnings: ParseError[];
 }
+/**
+ * Inferred role of a trait within an orbital. Driven by heuristics over
+ * the trait body (state-machine event names, AppLayout suffix, etc.)
+ * during signature extraction. Stays a closed union so the Phase 2
+ * projector can pattern-match exhaustively; `'other'` is the
+ * catch-all for traits that don't fit a known kind.
+ */
+type FactoryTraitKind = 'list' | 'detail' | 'modal' | 'layout' | 'wizard' | 'tabs' | 'realtime' | 'browse' | 'inspector' | 'navigation' | 'lifecycle' | 'access-control' | 'audit' | 'persistor' | 'other';
+/**
+ * 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>;
+    /** Default persistence mode the factory emits; overridable by params. */
+    persistence: EntityPersistence;
+    /** True when the factory's params accept an `entityName` override. */
+    renameable: boolean;
+    /**
+     * True when the factory's params accept appending extra fields via
+     * `params.fields[]`. Almost always true; declared explicitly so the
+     * projector can introspect.
+     */
+    fieldsExtensible: boolean;
+}
+/**
+ * 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.
+ */
+interface FactoryTraitSignature {
+    /** Canonical trait name post-rename (e.g. `"ChatMessageList"`). */
+    name: string;
+    kind: FactoryTraitKind;
+    /** Event keys this trait emits (post-rename). */
+    emittedEvents: ReadonlyArray<string>;
+    /** Event keys this trait listens for. */
+    listenedEvents: ReadonlyArray<string>;
+    /** Config keys overridable via `traitOverrides.<name>.config.<key>`. */
+    overridableConfigKeys: 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>;
+}
 
 /**
  * Domain Language Tokens
@@ -969,4 +1087,4 @@ declare function getRegistryStats(): {
  */
 declare function generateDomainLanguageReference(): string;
 
-export { type ASTNode, 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 DomainPage, type DomainPageAction, type DomainPageSection, type DomainRelationship, type DomainTick, type DomainToSchemaResult, type DomainTransition, EFFECT_REGISTRY, type EffectMapping, type EffectType, EntityPersistence, FIELD_TYPE_REGISTRY, 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 RelationshipType, type SchemaToDomainResult, type SectionMapping, type SourceLocation, type SourceRange, type Token, TokenType, TraitScope, type UserCheckCondition, 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, mergeDomainChunks, parseBehavior, parseDomainEffect, parseDomainEffects, parseDomainGuard, parseEntity, parseGuard, parsePage, parseSectionId, removeMapping, resolveConflict, schemaEntityToDomainEntity, schemaPageToDomainPage, schemaTraitToDomainBehavior, schemaTypeToDomainKeyword, tokenize, updateMappingRange, updateSchemaHash, upsertMapping, validateDomainChunk };
+export { type ASTNode, 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 DomainPage, type DomainPageAction, type DomainPageSection, type DomainRelationship, type DomainTick, type DomainToSchemaResult, type DomainTransition, EFFECT_REGISTRY, type EffectMapping, type EffectType, EntityPersistence, FIELD_TYPE_REGISTRY, type FactoryEntitySignature, type FactoryPageSignature, type FactorySignature, type FactorySignatureCatalog, type FactorySignatureEntityField, type FactoryTraitKind, 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 RelationshipType, type SchemaToDomainResult, type SectionMapping, type SourceLocation, type SourceRange, type Token, TokenType, TraitScope, type UserCheckCondition, 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, mergeDomainChunks, parseBehavior, parseDomainEffect, parseDomainEffects, parseDomainGuard, parseEntity, parseGuard, parsePage, parseSectionId, removeMapping, resolveConflict, schemaEntityToDomainEntity, schemaPageToDomainPage, schemaTraitToDomainBehavior, schemaTypeToDomainKeyword, tokenize, updateMappingRange, updateSchemaHash, upsertMapping, validateDomainChunk };