@almadar/core 4.5.0 → 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-D4VBpRZI.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-BtjmpmIC.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([
@@ -1038,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) {
@@ -1227,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