@almadar/core 7.26.0 → 8.1.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 { bK 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-g5-2JR48.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-Cov1FvVJ.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-DsgVjsAB.js';
 import { AnyPatternConfig } from '@almadar/patterns';
 import 'zod';
 

package/dist/{compose-behaviors-CHAMivlZ.d.ts → compose-behaviors-DsgVjsAB.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-Cov1FvVJ.js';
 
 /**
  * Event Wiring

package/dist/factory/index.d.ts

@@ -0,0 +1,339 @@
+import { B as EntityField, H as EntityPersistence, bz as TraitReference, bu as TraitEventListener } from '../trait-g5-2JR48.js';
+import 'zod';
+import '../expression-BVRFm0sV.js';
+import '@almadar/patterns';
+
+/**
+ * OrbitalSchema field type tags. The factory-signature extractor lifts
+ * these directly from the resolved `.orb`; consumers narrow further at
+ * dispatch time.
+ */
+type SchemaFieldType = 'string' | 'number' | 'boolean' | 'date' | 'timestamp' | 'datetime' | 'array' | 'object' | 'enum' | 'relation';
+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
+ * orbital + which override knobs a presentation overlay can target.
+ */
+interface FactoryTraitSignature {
+    /** Canonical trait name post-rename (e.g. `"ChatMessageList"`). */
+    name: string;
+    /** 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>;
+    /** Capability tags lifted directly from the source `.lolo` trait's
+     *  header annotations. Free-form strings — the translator overlay
+     *  matches rules to traits by exact set membership. */
+    capabilities: ReadonlyArray<string>;
+}
+/** One page the factory emits. The path is the factory default; the
+ *  projector may override via `params.pagePaths`. */
+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). */
+    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.
+ */
+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 {
+    organism: string;
+    orbital: string;
+    factoryPath: string;
+    params: FactoryCallSiteParams;
+}
+/**
+ * The typed param surface every factory's call site populates. Each
+ * field corresponds to one row in the translator's overlay → factory
+ * mapping table.
+ */
+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. */
+    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`. */
+    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. */
+    extraTraits?: ReadonlyArray<TraitReference>;
+}
+/**
+ * Allowed leaf values for the typed factory-param surface.
+ */
+type FactoryParamValue = string | number | boolean | ReadonlyArray<FactoryParamValue> | {
+    readonly [key: string]: FactoryParamValue;
+};
+
+/**
+ * Cross-cutting presentation knobs that don't live per orbital
+ * 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;
+    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`.
+ */
+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';
+    listens?: ReadonlyArray<TraitEventListener>;
+}
+type TraitOverlayListener = TraitEventListener;
+/**
+ * Rules carry a free-form `capability: string` that the translator
+ * matches against `signature.traits[].capabilities` (source-tagged
+ * in `.lolo`).
+ */
+interface RuleOverlay {
+    rules: ReadonlyArray<RuleOverlayEntry>;
+    /** Entity-level ownership signal. The translator threads it into
+     *  the matched trait's `config.ownerField` (when the matched trait
+     *  advertises that key in `overridableConfigKeys`). */
+    ownership?: ReadonlyArray<OwnershipOverlayEntry>;
+}
+interface RuleOverlayEntry {
+    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. */
+    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 the orbital's bound entity name). */
+    entity: string;
+    /** Field name on the entity that carries the owner identifier. */
+    ownerField: string;
+}
+
+/**
+ * The per-orbital binding the agent assembles when it picks a
+ * signature. Carries the user-authored overrides directly; no shared
+ * domain ontology, no DomainDocument.
+ */
+interface TranslationBinding {
+    /** Entity name override. When equal to `signature.entities[0].name`,
+     *  no rename is emitted. */
+    entityName: string;
+    /** Extra fields beyond the signature's canonical entity surface. */
+    entityFields?: ReadonlyArray<EntityField>;
+    /** Persistence override. */
+    persistence?: EntityPersistence;
+    /** Collection name override. */
+    collection?: string;
+    /** Per-page path overrides keyed by `signature.pages[i].name`. */
+    pagePaths?: Readonly<Record<string, string>>;
+}
+interface TranslationWarning {
+    /** Dotted path of the binding field that couldn't be lowered. */
+    field: string;
+    /** Human-readable reason. */
+    reason: string;
+}
+interface TranslationResult {
+    callSite: FactoryCallSite;
+    warnings: ReadonlyArray<TranslationWarning>;
+}
+declare function translateOverlaysToParams(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>;
+
+/**
+ * One slot the agent emits per orbital. Slim shape — agent-facing,
+ * carries only what factory dispatch needs. The studio renders forms
+ * over this; the projector turns it into a `FactoryCallSite`.
+ */
+interface OrbitalCallInput {
+    orbitalName: string;
+    organism?: string;
+    orbital?: string;
+    entityName?: string;
+    entityFields?: ReadonlyArray<EntityField>;
+    persistence?: EntityPersistence;
+    collection?: string;
+    pagePaths?: Readonly<Record<string, string>>;
+    traitOverlay?: Readonly<Record<string, {
+        config?: Readonly<Record<string, FactoryParamValue>>;
+        linkedEntity?: string;
+        name?: string;
+    }>>;
+    extraTraits?: ReadonlyArray<TraitReference>;
+}
+/**
+ * Discriminated union of typed edits. Each variant carries only the
+ * payload pieces that change. The reducer is total over the union.
+ */
+type FactoryCallPlanMutation = {
+    kind: 'set-orbital-entity-fields';
+    orbitalName: string;
+    fields: ReadonlyArray<EntityField>;
+} | {
+    kind: 'set-orbital-entity-name';
+    orbitalName: string;
+    name: string;
+} | {
+    kind: 'set-orbital-persistence';
+    orbitalName: string;
+    persistence: EntityPersistence;
+} | {
+    kind: 'set-orbital-collection';
+    orbitalName: string;
+    collection: string;
+} | {
+    kind: 'set-orbital-page-path';
+    orbitalName: string;
+    pageName: string;
+    path: string;
+} | {
+    kind: 'set-trait-override-config';
+    orbitalName: string;
+    traitName: string;
+    key: string;
+    value: FactoryParamValue;
+} | {
+    kind: 'add-extra-trait';
+    orbitalName: string;
+    trait: TraitReference;
+} | {
+    kind: 'remove-extra-trait';
+    orbitalName: string;
+    ref: string;
+} | {
+    kind: 'set-rule';
+    rule: RuleOverlayEntry;
+} | {
+    kind: 'remove-rule';
+    ruleId: string;
+};
+/**
+ * State shape the reducer operates on. Mirrors the slice of the
+ * agent's analysis result that incremental edits target.
+ */
+interface FactoryCallPlanState {
+    orbitals: ReadonlyArray<OrbitalCallInput>;
+    ruleOverlay?: RuleOverlay;
+}
+/**
+ * Immutable reducer. Returns a new state; never mutates input.
+ */
+declare function applyFactoryCallPlanMutation(state: FactoryCallPlanState, m: FactoryCallPlanMutation): FactoryCallPlanState;
+
+export { type CallSiteDiff, type FactoryCallPlanMutation, type FactoryCallPlanState, type FactoryCallSite, type FactoryCallSiteParams, type FactoryEntitySignature, type FactoryPageSignature, type FactoryParamValue, type FactorySignature, type FactorySignatureCatalog, type FactorySignatureEntityField, type FactoryTraitSignature, type OrbitalCallInput, type OwnershipOverlayEntry, type PresentationNavItem, type PresentationOverlay, type RuleOverlay, type RuleOverlayEntry, type SchemaFieldType, type TraitOverlay, type TraitOverlayEntry, type TraitOverlayListener, type TranslationBinding, type TranslationResult, type TranslationWarning, applyFactoryCallPlanMutation, diffFactoryCalls, translateOverlaysToParams };