@almadar/core 4.4.2 → 4.6.0

package/dist/builders.d.ts

@@ -1,8 +1,52 @@
-import { T as TraitEventContract, E as EntityField, a as EntityPersistence, b as EntityRow, O as OrbitalDefinition, c as OrbitalSchema, d as Trait, e as Entity, P as Page } from './schema-B0Yin-RM.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-Da0YDcli.js';
+import { T as TraitReference, a as TraitEventContract, E as EntityField, b as EntityPersistence, c as EntityRow, O as OrbitalDefinition, d as OrbitalSchema, e as Trait, f as Entity, P as Page } from './schema-CLFPg1xW.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-Bp32KayC.js';
 import 'zod';
 import '@almadar/patterns';
 
+/**
+ * Explode Behavior Composition
+ *
+ * Human-authoring primitive (Phase 5.3 of Almadar_Agent_Behaviors_Plan).
+ *
+ * Reads a behavior's compiled `.orb` from the sibling `@almadar/std`
+ * registry on disk and returns the flat list of `TraitReference` objects
+ * it's composed from — each with `from`, `ref`, `linkedEntity`, and any
+ * call-site overrides. **Not exposed to the agent or LLM.** The helper
+ * exists for developers designing new molecules or debugging compositions.
+ *
+ * The function is Node-only. It walks the filesystem under
+ * `packages/almadar-std/behaviors/registry/{atoms,molecules,organisms}/`
+ * relative to this source file and will throw a descriptive error if the
+ * behavior cannot be resolved.
+ *
+ * When the target is a leaf atom (no `uses:` / composition), the function
+ * returns a single synthetic `TraitReference` pointing at the atom's own
+ * inline trait so consumers always get something useful.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Flatten a behavior's `.orb` composition into the list of
+ * `TraitReference` objects it's built from.
+ *
+ * For composed behaviors (molecules, organisms) this returns every
+ * `TraitReference` entry from every orbital's `traits:` array, carrying
+ * the call-site `ref`, backfilled `from` (looked up against the orbital's
+ * `uses:` imports when omitted), `linkedEntity`, `events`, `effects`, and
+ * any other override fields declared at the call site.
+ *
+ * For leaf atoms (no composition, only an inline trait) the function
+ * returns a single synthetic `TraitReference` pointing at the atom's own
+ * trait, so consumers always get a non-empty array they can iterate.
+ *
+ * @param behaviorName - Registry name of the behavior (e.g. `"std-cart"`,
+ *                       `"std-browse"`).
+ * @returns Flat list of every `TraitReference` the behavior is composed of.
+ * @throws Error when the behavior cannot be found in any registry level.
+ */
+declare function explodeBehaviorComposition(behaviorName: string): TraitReference[];
+
 /**
  * Orbital Builders
  *
@@ -103,4 +147,4 @@ declare function compose(orbitals: (OrbitalDefinition | OrbitalSchema)[], pages:
  */
 declare function pipe(orbitals: (OrbitalDefinition | OrbitalSchema)[], events: TraitEventContract[], appName?: string): OrbitalSchema;
 
-export { type ComposeConnection, type ComposePage, type MakeEntityOpts, type MakePageOpts, compose, connect, ensureIdField, extractTrait, makeEntity, makeOrbital, makePage, makeSchema, mergeOrbitals, pipe, plural, wire };
+export { type ComposeConnection, type ComposePage, type MakeEntityOpts, type MakePageOpts, compose, connect, ensureIdField, explodeBehaviorComposition, extractTrait, makeEntity, makeOrbital, makePage, makeSchema, mergeOrbitals, pipe, plural, wire };

package/dist/builders.js

@@ -1,4 +1,7 @@
 import { z } from 'zod';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
 
 // src/types/orbital.ts
 var FieldTypeSchema = z.enum([
@@ -46,34 +49,61 @@ var FieldFormatSchema = z.enum([
   "datetime",
   "uuid"
 ]);
+var FIELD_TYPE_ALIASES = {
+  text: "string",
+  int: "number",
+  float: "number",
+  ts: "timestamp"
+};
 var EntityFieldSchema = z.lazy(
-  () => z.object({
-    name: z.string().min(1, "Field name is required"),
-    type: FieldTypeSchema,
-    required: z.boolean().optional(),
-    default: z.unknown().optional(),
-    values: z.array(z.string()).optional(),
-    enum: z.array(z.string()).optional(),
-    format: FieldFormatSchema.optional(),
-    min: z.number().optional(),
-    max: z.number().optional(),
-    items: EntityFieldSchema.optional(),
-    relation: RelationConfigSchema.optional()
-  }).refine(
-    (field) => field.type !== "relation" || field.relation !== void 0,
-    { message: 'Relation config is required when type is "relation"', path: ["relation"] }
-  ).refine(
-    // Enum fields must carry their allowed values. Without this refine,
-    // the type was lying about what's valid — bare `type: 'enum'` without
-    // `values` passed zod but failed `orb validate` downstream with
-    // ORB_E_EMPTY_ENUM_VALUES, stalling the agent pipeline for 20 minutes.
-    // `enum` is the legacy field-name alias; accept either.
-    (field) => {
-      if (field.type !== "enum") return true;
-      const vals = field.values ?? field.enum;
-      return Array.isArray(vals) && vals.length > 0;
+  () => z.preprocess(
+    (input) => {
+      if (input !== null && typeof input === "object" && "type" in input && typeof input.type === "string") {
+        const raw = input.type;
+        const canonical = FIELD_TYPE_ALIASES[raw];
+        if (canonical !== void 0) {
+          return { ...input, type: canonical };
+        }
+      }
+      return input;
     },
-    { message: "Enum field requires a non-empty `values` array", path: ["values"] }
+    z.object({
+      name: z.string().min(1, "Field name is required"),
+      type: FieldTypeSchema,
+      required: z.boolean().optional(),
+      default: z.unknown().optional(),
+      values: z.array(z.string()).optional(),
+      enum: z.array(z.string()).optional(),
+      format: FieldFormatSchema.optional(),
+      min: z.number().optional(),
+      max: z.number().optional(),
+      items: EntityFieldSchema.optional(),
+      relation: RelationConfigSchema.optional()
+    }).refine(
+      (field) => field.type !== "relation" || field.relation !== void 0,
+      { message: 'Relation config is required when type is "relation"', path: ["relation"] }
+    ).refine(
+      // Enum fields must carry their allowed values. Without this refine,
+      // the type was lying about what's valid — bare `type: 'enum'` without
+      // `values` passed zod but failed `orb validate` downstream with
+      // ORB_E_EMPTY_ENUM_VALUES, stalling the agent pipeline for 20 minutes.
+      // `enum` is the legacy field-name alias; accept either.
+      (field) => {
+        if (field.type !== "enum") return true;
+        const vals = field.values ?? field.enum;
+        return Array.isArray(vals) && vals.length > 0;
+      },
+      { message: "Enum field requires a non-empty `values` array", path: ["values"] }
+    ).refine(
+      // Array fields must describe their element shape. Bare `type: 'array'`
+      // with no `items` forces downstream consumers (builders, UI renderers,
+      // persistence) to guess, so reject it at the schema boundary.
+      (field) => {
+        if (field.type !== "array") return true;
+        return field.items !== void 0;
+      },
+      { message: "Array field requires an `items` schema describing each element", path: ["items"] }
+    )
   )
 );
 var ENTITY_ROLES = [
@@ -370,6 +400,8 @@ var RequiredFieldSchema = z.object({
 });
 z.object({
   ref: z.string().min(1),
+  // Phase 1.2: optional registry path disambiguator, pairs with `ref`.
+  from: z.string().optional(),
   linkedEntity: z.string().optional(),
   name: z.string().optional(),
   events: z.record(
@@ -735,6 +767,8 @@ var PageRefStringSchema = z.string().regex(
 );
 var PageRefObjectSchema = z.object({
   ref: PageRefStringSchema,
+  // 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()
@@ -1007,6 +1041,104 @@ function composeBehaviors(input) {
     }
   };
 }
+function registryRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "..", "..", "almadar-std", "behaviors", "registry");
+}
+var LEVELS = ["atoms", "molecules", "organisms"];
+function resolveBehavior(behaviorName) {
+  const root = registryRoot();
+  const searched = [];
+  for (const level of LEVELS) {
+    const path = resolve(root, level, `${behaviorName}.orb`);
+    searched.push(path);
+    let source;
+    try {
+      source = readFileSync(path, "utf8");
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(source);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `explodeBehaviorComposition: failed to parse ${path} as JSON: ${message}`
+      );
+    }
+    return { level, path, schema: parsed };
+  }
+  throw new Error(
+    `explodeBehaviorComposition: behavior "${behaviorName}" not found. Searched:
+  - ${searched.join("\n  - ")}`
+  );
+}
+function isTraitReferenceObject(entry) {
+  return typeof entry === "object" && entry !== null && "ref" in entry && typeof entry.ref === "string" && !isInlineTrait(entry);
+}
+function aliasToFromMap(uses) {
+  const map = /* @__PURE__ */ new Map();
+  if (!uses) return map;
+  for (const use of uses) {
+    map.set(use.as, use.from);
+  }
+  return map;
+}
+function extractAlias(ref) {
+  const match = ref.match(/^([A-Z][a-zA-Z0-9]*)\.traits\.[A-Z][a-zA-Z0-9]*$/);
+  return match ? match[1] : null;
+}
+function findAtomInlineTrait(orbital) {
+  for (const entry of orbital.traits) {
+    if (typeof entry === "object" && entry !== null && isInlineTrait(entry)) {
+      return entry;
+    }
+  }
+  return void 0;
+}
+function syntheticLeafReference(behaviorName, orbital, trait) {
+  const base = behaviorName.replace(/^std-/, "");
+  const alias = base.split("-").filter((segment) => segment.length > 0).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join("") || "Behavior";
+  const entityName = typeof orbital.entity === "string" ? orbital.entity : "name" in orbital.entity && typeof orbital.entity.name === "string" ? orbital.entity.name : void 0;
+  const reference = {
+    ref: `${alias}.traits.${trait.name}`,
+    from: `std/behaviors/${behaviorName}`
+  };
+  if (trait.linkedEntity !== void 0) {
+    reference.linkedEntity = trait.linkedEntity;
+  } else if (entityName !== void 0) {
+    reference.linkedEntity = entityName;
+  }
+  return reference;
+}
+function explodeBehaviorComposition(behaviorName) {
+  const resolved = resolveBehavior(behaviorName);
+  const orbitals = Array.isArray(resolved.schema.orbitals) ? resolved.schema.orbitals : [];
+  const references = [];
+  for (const orbital of orbitals) {
+    const aliasMap = aliasToFromMap(orbital.uses);
+    for (const entry of orbital.traits ?? []) {
+      if (!isTraitReferenceObject(entry)) continue;
+      const copy = { ...entry };
+      if (copy.from === void 0) {
+        const alias = extractAlias(copy.ref);
+        const fromPath = alias !== null ? aliasMap.get(alias) : void 0;
+        if (fromPath !== void 0) {
+          copy.from = fromPath;
+        }
+      }
+      references.push(copy);
+    }
+  }
+  if (references.length > 0) return references;
+  const firstOrbital = orbitals[0];
+  const inlineTrait = firstOrbital ? findAtomInlineTrait(firstOrbital) : void 0;
+  if (firstOrbital && inlineTrait) {
+    return [syntheticLeafReference(behaviorName, firstOrbital, inlineTrait)];
+  }
+  return [];
+}
 
 // src/builders.ts
 function ensureIdField(fields) {
@@ -1196,6 +1328,6 @@ function pipe(orbitals, events, appName) {
   };
 }
 
-export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeEntity, makeOrbital, makePage, makeSchema, mergeOrbitals, pipe, plural, wire };
+export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, explodeBehaviorComposition, extractTrait, makeEntity, makeOrbital, makePage, makeSchema, mergeOrbitals, pipe, plural, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map