@almadar/core 10.28.0 → 10.30.0

package/dist/builders.d.ts

@@ -1,5 +1,5 @@
-import './pattern-types-BeQXwgpZ.js';
-export { i as ComposeBehaviorsInput, j as ComposeBehaviorsResult, c7 as ComposeConnection, c8 as ComposePage, a6 as EventWiringEntry, aq as LayoutStrategy, c9 as MakeAtomOrbitalOpts, ca as MakeAtomOrbitalTraitOverrides, cb as MakeEntityOpts, cc as MakeLayoutTraitOpts, cd as MakeOrbitalWithUsesOpts, ce as MakePageOpts, cf as MakePageRefOpts, cg as MakePageRefOptsTyped, M as MakeTraitRefOpts, ch as MakeTraitRefOptsTyped, bS as applyEventWiring, ci as applyTraitConfigOverrides, cj as compose, bT as composeBehaviors, ck as connect, bU as detectLayoutStrategy, cl as ensureIdField, cm as extractTrait, cn as makeAtomOrbital, co as makeEntity, cp as makeLayoutTrait, cq as makeOrbital, cr as makeOrbitalWithUses, cs as makePage, ct as makePageRef, cu as makeRenderUI, cv as makeSchema, cw as makeSlot, cx as makeTraitRef, cy as mergeOrbitals, cz as pipe, cA as plural, cB as wire } from './builders-BN3WLFYM.js';
-import './trait-DZkS625T.js';
-import './expression-C6X4A8L7.js';
+import './pattern-types-CLcOXOmW.js';
+export { i as ComposeBehaviorsInput, j as ComposeBehaviorsResult, c7 as ComposeConnection, c8 as ComposePage, a6 as EventWiringEntry, aq as LayoutStrategy, c9 as MakeAtomOrbitalOpts, ca as MakeAtomOrbitalTraitOverrides, cb as MakeEntityOpts, cc as MakeLayoutTraitOpts, cd as MakeOrbitalWithUsesOpts, ce as MakePageOpts, cf as MakePageRefOpts, cg as MakePageRefOptsTyped, M as MakeTraitRefOpts, ch as MakeTraitRefOptsTyped, bS as applyEventWiring, ci as applyTraitConfigOverrides, cj as compose, bT as composeBehaviors, ck as connect, bU as detectLayoutStrategy, cl as ensureIdField, cm as extractTrait, cn as makeAtomOrbital, co as makeEntity, cp as makeLayoutTrait, cq as makeOrbital, cr as makeOrbitalWithUses, cs as makePage, ct as makePageRef, cu as makeRenderUI, cv as makeSchema, cw as makeSlot, cx as makeTraitRef, cy as mergeLedgers, cz as mergeOrbitals, cA as pipe, cB as plural, cC as wire } from './builders-C458pIMW.js';
+import './trait-CwWjkU-1.js';
+import './expression-CB9R3KWk.js';
 import 'zod';

package/dist/builders.js

@@ -1,6 +1,80 @@
 import { z } from 'zod';
 
 // src/types/orbital.ts
+var ID_PREFIXES = {
+  orbital: "orb_",
+  entity: "ent_",
+  trait: "trt_",
+  event: "evt_",
+  page: "pag_",
+  service: "svc_",
+  theme: "thm_",
+  palette: "pal_"
+};
+function brand(value) {
+  return value;
+}
+function makeIdKind(kind) {
+  const prefix = ID_PREFIXES[kind];
+  const is = (value) => value.startsWith(prefix) && value.length > prefix.length;
+  const as = (value) => {
+    if (!is(value)) {
+      throw new Error(
+        `Expected ${kind} id (prefix "${prefix}"), got: ${JSON.stringify(value)}`
+      );
+    }
+    return brand(value);
+  };
+  return { prefix, is, as };
+}
+var orbitalKind = makeIdKind("orbital");
+var entityKind = makeIdKind("entity");
+var traitKind = makeIdKind("trait");
+var eventKind = makeIdKind("event");
+var pageKind = makeIdKind("page");
+var serviceKind = makeIdKind("service");
+var themeKind = makeIdKind("theme");
+var paletteKind = makeIdKind("palette");
+var isOrbitalId = orbitalKind.is;
+var isEntityId = entityKind.is;
+var isTraitId = traitKind.is;
+var isEventId = eventKind.is;
+var isPageId = pageKind.is;
+var isServiceId = serviceKind.is;
+var isThemeId = themeKind.is;
+var isPaletteEntryId = paletteKind.is;
+var OrbitalIdSchema = z.string().refine(isOrbitalId, { message: `Expected an orbital id (prefix "${ID_PREFIXES.orbital}")` });
+var EntityIdSchema = z.string().refine(isEntityId, { message: `Expected an entity id (prefix "${ID_PREFIXES.entity}")` });
+var TraitIdSchema = z.string().refine(isTraitId, { message: `Expected a trait id (prefix "${ID_PREFIXES.trait}")` });
+var EventIdSchema = z.string().refine(isEventId, { message: `Expected an event id (prefix "${ID_PREFIXES.event}")` });
+var PageIdSchema = z.string().refine(isPageId, { message: `Expected a page id (prefix "${ID_PREFIXES.page}")` });
+z.string().refine(isServiceId, { message: `Expected a service id (prefix "${ID_PREFIXES.service}")` });
+z.string().refine(isThemeId, { message: `Expected a theme id (prefix "${ID_PREFIXES.theme}")` });
+z.string().refine(isPaletteEntryId, { message: `Expected a palette-entry id (prefix "${ID_PREFIXES.palette}")` });
+var LedgerKindSchema = z.enum([
+  "orbital",
+  "entity",
+  "trait",
+  "event",
+  "page",
+  "service",
+  "theme"
+]);
+var LedgerEntrySchema = z.object({
+  id: z.string(),
+  kind: LedgerKindSchema,
+  bakedName: z.string(),
+  curName: z.string(),
+  renames: z.array(
+    z.object({ from: z.string(), to: z.string(), at: z.string() })
+  ),
+  owner: z.enum(["std", "io", "workspace"]),
+  parent: TraitIdSchema.optional()
+});
+z.object({
+  schemaVersion: z.literal(1),
+  entries: z.record(LedgerEntrySchema)
+});
 z.enum([
   "string",
   "number",
@@ -25,6 +99,7 @@ var RelationCardinalitySchema = z.enum([
 ]);
 var RelationConfigSchema = z.object({
   entity: z.string().min(1, "Target entity is required"),
+  entityId: EntityIdSchema.optional(),
   field: z.string().optional(),
   cardinality: RelationCardinalitySchema.optional(),
   onDelete: z.enum(["cascade", "nullify", "restrict"]).optional(),
@@ -35,6 +110,7 @@ var RelationConfigSchema = z.object({
 }).transform((data) => {
   const normalized = {
     entity: data.entity || data.target || "",
+    entityId: data.entityId,
     cardinality: data.cardinality || data.type,
     field: data.field,
     onDelete: data.onDelete
@@ -321,10 +397,12 @@ var StateSchema = z.object({
 var PayloadFieldSchema = z.object({
   name: z.string().min(1),
   type: z.string().min(1),
-  required: z.boolean().optional()
+  required: z.boolean().optional(),
+  properties: z.lazy(() => z.array(PayloadFieldSchema)).optional()
 });
 var EventSchema = z.object({
   key: z.string().min(1, "Event key is required"),
+  id: EventIdSchema.optional(),
   name: z.string().min(1, "Event name is required"),
   description: z.string().optional(),
   synonyms: z.string().optional(),
@@ -342,6 +420,7 @@ var TransitionSchema = z.object({
   from: z.string().min(1, "Transition source state is required"),
   to: z.string().min(1, "Transition target state is required"),
   event: z.string().min(1, "Transition event is required"),
+  eventId: EventIdSchema.optional(),
   guard: ExpressionSchema.nullish(),
   effects: z.array(EffectSchema).optional(),
   description: z.string().nullish()
@@ -368,14 +447,25 @@ var TraitConfigSchema = z.record(TraitConfigValueSchema);
 function isCallSiteConfigDeclaration(entry) {
   return typeof entry === "object" && entry !== null && !Array.isArray(entry) && "type" in entry && typeof entry.type === "string" && "default" in entry;
 }
+var ConfigFieldItemsDeclarationSchema = z.lazy(
+  () => z.object({
+    type: z.string().optional(),
+    properties: z.record(TraitEntityFieldSchema).optional(),
+    items: ConfigFieldItemsDeclarationSchema.optional()
+  })
+);
 var ConfigFieldDeclarationSchema = z.object({
   type: z.string(),
   default: TraitConfigValueSchema.optional(),
+  refId: z.string().optional(),
+  required: z.boolean().optional(),
   label: z.string().optional(),
   description: z.string().optional(),
   tier: z.string().optional(),
   values: z.array(z.string()).optional(),
-  synonyms: z.string().optional()
+  synonyms: z.string().optional(),
+  items: ConfigFieldItemsDeclarationSchema.optional(),
+  properties: z.lazy(() => z.record(TraitEntityFieldSchema)).optional()
 });
 var DeclaredTraitConfigSchema = z.record(
   ConfigFieldDeclarationSchema
@@ -412,7 +502,9 @@ var TraitEntityFieldSchema = z.object({
   ]),
   required: z.boolean().optional(),
   default: z.unknown().optional(),
-  values: z.array(z.string()).optional()
+  values: z.array(z.string()).optional(),
+  items: ConfigFieldItemsDeclarationSchema.optional(),
+  properties: z.lazy(() => z.record(TraitEntityFieldSchema)).optional()
 });
 var TraitDataEntitySchema = z.object({
   name: z.string().min(1),
@@ -431,9 +523,11 @@ var TraitTickSchema = z.object({
   interval: z.union([z.literal("frame"), z.number().positive()]),
   appliesTo: z.array(z.string()).optional(),
   pages: z.array(z.string()).optional(),
+  pageIds: z.array(PageIdSchema).optional(),
   guard: ExpressionSchema.optional(),
   effects: z.array(EffectSchema).min(1),
-  emits: z.array(z.string()).optional()
+  emits: z.array(z.string()).optional(),
+  emitIds: z.array(EventIdSchema).optional()
 });
 var EventScopeSchema = z.enum(["internal", "external"]);
 var EventPayloadFieldSchema = z.object({
@@ -451,7 +545,8 @@ var EventPayloadFieldSchema = z.object({
   type: z.string().min(1),
   required: z.boolean().optional(),
   description: z.string().optional(),
-  entityType: z.string().optional()
+  entityType: z.string().optional(),
+  properties: z.lazy(() => z.array(EventPayloadFieldSchema)).optional()
 });
 var TraitEventContractSchema = z.object({
   /**
@@ -459,12 +554,15 @@ var TraitEventContractSchema = z.object({
    * starts with a letter, then any letters / digits / underscores. Both
    * UPPER_SNAKE_CASE and PascalCase shapes are valid identifiers in the
    * post-Phase 2.5 nominal-event type system (events declared via
-   * `type X = Event<T>`).
+   * `type X = Event<T>`). A pre-resolution `@config.<knob>` reference
+   * (Option B) is also legal — inline/resolve substitutes it with the
+   * knob's effective literal before codegen/runtime consume it.
    */
   event: z.string().min(1).regex(
-    /^[A-Za-z][A-Za-z0-9_]*$/,
-    "Event name must start with a letter and contain only letters, digits, and underscores"
+    /^([A-Za-z][A-Za-z0-9_]*|@config\.[A-Za-z_][A-Za-z0-9_]*)$/,
+    "Event name must start with a letter and contain only letters, digits, and underscores, or be a `@config.<knob>` reference"
   ),
+  eventId: EventIdSchema.optional(),
   description: z.string().optional(),
   synonyms: z.string().optional(),
   tier: z.string().optional(),
@@ -473,16 +571,24 @@ var TraitEventContractSchema = z.object({
 });
 var ListenSourceSchema = z.union([
   z.object({ kind: z.literal("any") }),
-  z.object({ kind: z.literal("trait"), trait: z.string().min(1) }),
+  z.object({
+    kind: z.literal("trait"),
+    trait: z.string().min(1),
+    traitId: TraitIdSchema.optional()
+  }),
   z.object({
     kind: z.literal("orbital"),
     orbital: z.string().min(1),
-    trait: z.string().min(1)
+    trait: z.string().min(1),
+    orbitalId: OrbitalIdSchema.optional(),
+    traitId: TraitIdSchema.optional()
   })
 ]);
 var TraitEventListenerSchema = z.object({
   event: z.string().min(1),
+  eventId: EventIdSchema.optional(),
   triggers: z.string().min(1),
+  triggersId: EventIdSchema.optional(),
   description: z.string().optional(),
   synonyms: z.string().optional(),
   tier: z.string().optional(),
@@ -498,14 +604,20 @@ var RequiredFieldSchema = z.object({
 });
 z.object({
   ref: z.string().min(1),
+  refId: TraitIdSchema.optional(),
+  // V4 local declaration id (see the interface doc) — declared so the
+  // strip-mode zod gate carries it through instead of dropping it.
+  id: TraitIdSchema.optional(),
   // Phase 1.2: optional registry path disambiguator, pairs with `ref`.
   from: z.string().optional(),
   linkedEntity: z.string().optional(),
+  linkedEntityId: EntityIdSchema.optional(),
   name: z.string().optional(),
   events: z.record(
     z.string().min(1, "events key (atom event name) must be non-empty"),
     z.string().min(1, "events value (caller event name) must be non-empty")
   ).optional(),
+  eventIds: z.record(z.string().min(1), EventIdSchema).optional(),
   fields: z.record(
     z.string().min(1, "fields key (canonical field name) must be non-empty"),
     z.string().min(1, "fields value (consumer field name) must be non-empty")
@@ -555,6 +667,7 @@ var SourceBehaviorMetadataSchema = z.object({
   originalName: z.string().min(1)
 });
 var TraitSchema = z.object({
+  id: TraitIdSchema.optional(),
   name: z.string().min(1),
   description: z.string().optional(),
   description_visual_prompt: z.string().optional(),
@@ -566,6 +679,9 @@ var TraitSchema = z.object({
   capabilities: z.array(z.string()).optional(),
   scope: TraitScopeSchema,
   linkedEntity: z.string().optional(),
+  linkedEntityId: EntityIdSchema.optional(),
+  entityRefIds: z.record(z.string().min(1), EntityIdSchema).optional(),
+  traitEmbedIds: z.record(z.string().min(1), TraitIdSchema).optional(),
   requiredFields: z.array(RequiredFieldSchema).optional(),
   dataEntities: z.array(TraitDataEntitySchema).optional(),
   stateMachine: StateMachineSchema.optional(),
@@ -611,10 +727,13 @@ var ViewTypeSchema = z.enum([
 ]);
 var PageTraitRefSchema = z.object({
   ref: z.string().min(1, "Trait ref is required"),
+  refId: TraitIdSchema.optional(),
   linkedEntity: z.string().optional(),
+  linkedEntityId: EntityIdSchema.optional(),
   config: TraitConfigSchema.optional()
 });
 z.object({
+  id: PageIdSchema.optional(),
   name: z.string().min(1, "Page name is required"),
   path: z.string().min(1, "Page path is required").startsWith("/", "Path must start with /"),
   primaryEntity: z.string().min(1, "Primary entity is required"),
@@ -622,6 +741,7 @@ z.object({
   title: z.string().optional()
 }).strict();
 var OrbitalPageSchema = z.object({
+  id: PageIdSchema.optional(),
   name: z.string().min(1, "Page name is required"),
   path: z.string().min(1, "Page path is required").startsWith("/", "Path must start with /"),
   viewType: ViewTypeSchema.optional(),
@@ -1143,11 +1263,14 @@ var PageRefStringSchema = z.string().regex(
 );
 var PageRefObjectSchema = z.object({
   ref: PageRefStringSchema,
+  refId: PageIdSchema.optional(),
   // Phase 1.2: optional registry path disambiguator, pairs with `ref`.
   from: z.string().optional(),
   path: z.string().startsWith("/").optional(),
   linkedEntity: z.string().optional(),
-  traits: z.array(TraitRefSchema).optional()
+  linkedEntityId: EntityIdSchema.optional(),
+  traits: z.array(TraitRefSchema).optional(),
+  traitRefIds: z.array(TraitIdSchema).optional()
 });
 var PageRefSchema = z.union([
   PageSchema,
@@ -1188,6 +1311,7 @@ var ComputedEventListenerSchema = z.object({
   payloadMapping: z.record(z.string()).optional()
 });
 z.object({
+  id: OrbitalIdSchema.optional(),
   name: z.string().min(1, "Orbital name is required"),
   description: z.string().optional(),
   visual_prompt: z.string().optional(),
@@ -1370,13 +1494,40 @@ function applyEventWiring(orbitals, wiring) {
 }
 
 // src/builders/compose-behaviors.ts
+function isSchema(input) {
+  return "orbitals" in input && Array.isArray(input.orbitals);
+}
 function asDefinitions(inputs) {
-  return inputs.flatMap((input) => {
-    if ("orbitals" in input && Array.isArray(input.orbitals)) {
-      return input.orbitals;
+  return inputs.flatMap(
+    (input) => isSchema(input) ? input.orbitals : [input]
+  );
+}
+function mergeLedgers(inputs) {
+  const merged = /* @__PURE__ */ new Map();
+  let sawLedger = false;
+  for (const input of inputs) {
+    if (!isSchema(input) || input.ledger === void 0) continue;
+    sawLedger = true;
+    for (const [id, entry] of Object.entries(input.ledger.entries)) {
+      if (!merged.has(id)) merged.set(id, entry);
     }
-    return [input];
-  });
+  }
+  if (!sawLedger) return void 0;
+  const entries = {};
+  for (const [id, entry] of [...merged.entries()].sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  )) {
+    entries[id] = entry;
+  }
+  return { schemaVersion: 1, entries };
+}
+function mergeSchemaVersions(inputs) {
+  let max;
+  for (const input of inputs) {
+    if (!isSchema(input) || input.schemaVersion === void 0) continue;
+    max = max === void 0 ? input.schemaVersion : Math.max(max, input.schemaVersion);
+  }
+  return max;
 }
 function toKebabCase(name) {
   return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
@@ -1446,10 +1597,14 @@ function composeBehaviors(input) {
       pages: page ? [page] : []
     };
   });
+  const ledger = mergeLedgers(rawInputs);
+  const schemaVersion = mergeSchemaVersions(rawInputs);
   const schema = {
     name: appName,
     version: "1.0.0",
-    orbitals: orbitalsWithPages
+    orbitals: orbitalsWithPages,
+    ...schemaVersion !== void 0 ? { schemaVersion } : {},
+    ...ledger !== void 0 ? { ledger } : {}
   };
   return {
     schema,
@@ -1588,6 +1743,7 @@ function makeTraitRef(opts) {
   if (opts.from !== void 0) ref.from = opts.from;
   if (opts.name !== void 0) ref.name = opts.name;
   if (opts.linkedEntity !== void 0) ref.linkedEntity = opts.linkedEntity;
+  if (opts.linkedEntityId !== void 0) ref.linkedEntityId = opts.linkedEntityId;
   if (opts.events !== void 0) ref.events = opts.events;
   if (opts.fields !== void 0) ref.fields = opts.fields;
   if (opts.effects !== void 0) ref.effects = opts.effects;
@@ -1789,6 +1945,6 @@ function pipe(orbitals, events, appName) {
   };
 }
 
-export { applyEventWiring, applyTraitConfigOverrides, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeOrbitals, pipe, plural, wire };
+export { applyEventWiring, applyTraitConfigOverrides, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeLedgers, mergeOrbitals, pipe, plural, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map