@almadar/core 4.5.0 → 4.7.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 Entity, S as SExpr, b as TraitEventListener, c as EntityField, d as EntityPersistence, e as EntityRow, U as UseDeclaration, f as EntityRef, g as TraitRef, P as PageRef, O as OrbitalDefinition, h as OrbitalSchema, i as Trait, j as Page, k as PageRefObject } from './schema-C-6fdZ5P.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-BLEoAOk6.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
  *
@@ -52,6 +96,146 @@ declare function makePage(opts: MakePageOpts): Page;
  * Build an OrbitalDefinition from its three components.
  */
 declare function makeOrbital(name: string, entity: Entity, traits: Trait[], pages: Page[]): OrbitalDefinition;
+/**
+ * Options for {@link makeTraitRef}.
+ */
+interface MakeTraitRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link TraitReference.from}).
+     */
+    from?: string;
+    /** Trait reference string, e.g. "Browse.traits.BrowseItemBrowse". */
+    ref: string;
+    /** Rename the inlined trait at the call site. */
+    name?: string;
+    /** Rebind the trait to a different linkedEntity. */
+    linkedEntity?: string;
+    /** Per-key rename map, e.g. `{ OPEN: "ADD_ITEM" }`. */
+    events?: Record<string, string>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names. See {@link TraitReference.effects} for the full contract.
+     */
+    effects?: Record<string, SExpr[]>;
+    /** Replace the imported trait's `listens` array entirely. */
+    listens?: TraitEventListener[];
+    /** Set every emit's scope. */
+    emitsScope?: 'internal' | 'external';
+    /**
+     * Nested config overrides. Matches the real {@link TraitReference.config}
+     * shape: `Record<string, Record<string, unknown>>` (the outer key is the
+     * config field name, the inner record is its value shape).
+     */
+    config?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Build a {@link TraitReference} from options.
+ *
+ * Pass-through factory: copies only the fields that are actually provided,
+ * so optionals stay absent (no `key: undefined` slots) and the emitted
+ * object matches the inliner's expectation that "present = override".
+ */
+declare function makeTraitRef(opts: MakeTraitRefOpts): TraitReference;
+/**
+ * Options for {@link makePageRef}.
+ */
+interface MakePageRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link PageRefObject.from}).
+     */
+    from?: string;
+    /** Page reference string, e.g. "Browse.pages.BrowseItemPage". */
+    ref: string;
+    /** URL path override. */
+    path?: string;
+    /** Rebind the page's primary entity. */
+    linkedEntity?: string;
+    /** Replace the page's trait list. */
+    traits?: TraitRef[];
+}
+/**
+ * Build a {@link PageRefObject} from options. Pass-through factory — omits
+ * optional keys that are `undefined`.
+ */
+declare function makePageRef(opts: MakePageRefOpts): PageRefObject;
+/**
+ * Options for {@link makeOrbitalWithUses}.
+ */
+interface MakeOrbitalWithUsesOpts {
+    /** Orbital name. */
+    name: string;
+    /**
+     * Per-orbital `uses:` header entries (see CLAUDE.md "uses: lives inside
+     * the orbital").
+     */
+    uses: UseDeclaration[];
+    /** Entity (inline or reference form). */
+    entity: EntityRef;
+    /** Trait references. */
+    traits: TraitRef[];
+    /** Optional page references (omitted entirely when not provided). */
+    pages?: PageRef[];
+}
+/**
+ * Build an {@link OrbitalDefinition} with the `uses:` header set. Follows
+ * the convention that `uses:` lives on the orbital (not the schema).
+ *
+ * When `pages` is omitted, the result has no `pages` property (matches the
+ * existing {@link OrbitalDefinition.pages} optionality in descriptors that
+ * carry trait-only atoms).
+ */
+declare function makeOrbitalWithUses(opts: MakeOrbitalWithUsesOpts): OrbitalDefinition;
+/**
+ * Options for {@link makeAtomOrbital}.
+ *
+ * Overrides for the single trait reference. Mirrors the {@link MakeTraitRefOpts}
+ * subset that is meaningful at the atom-wrapping call site.
+ */
+interface MakeAtomOrbitalTraitOverrides {
+    name?: string;
+    events?: Record<string, string>;
+    effects?: Record<string, SExpr[]>;
+    listens?: TraitEventListener[];
+    emitsScope?: 'internal' | 'external';
+    config?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Options for {@link makeAtomOrbital}.
+ */
+interface MakeAtomOrbitalOpts {
+    /** Orbital name, e.g. `${entityName}Orbital`. */
+    name: string;
+    /** Atom registry path, e.g. `std/behaviors/atoms/std-browse`. */
+    atomPath: string;
+    /** Import alias (PascalCase), e.g. `Browse`. */
+    alias: string;
+    /** Entity definition to attach to the orbital. */
+    entity: Entity;
+    /** Trait reference string, e.g. `Browse.traits.BrowseItemBrowse`. */
+    traitRef: string;
+    /** Optional trait-level overrides applied at the call site. */
+    traitOverrides?: MakeAtomOrbitalTraitOverrides;
+    /** Optional page reference string, e.g. `Browse.pages.BrowseItemPage`. */
+    pageRef?: string;
+    /** Optional page-level overrides applied at the call site. */
+    pageOverrides?: {
+        path?: string;
+    };
+}
+/**
+ * Build a single-atom {@link OrbitalDefinition}.
+ *
+ * The common atom shape: one entity + one trait reference + (optionally) one
+ * page reference, all under a single `uses:` import. Wraps
+ * {@link makeTraitRef}, {@link makePageRef}, and {@link makeOrbitalWithUses}.
+ *
+ * The trait reference is linkedEntity-bound to `entity.name` by default so
+ * that the inliner's entity-substitution pass rewrites every `["ref", X]`
+ * and `@X.path` reference inside the atom.
+ */
+declare function makeAtomOrbital(opts: MakeAtomOrbitalOpts): OrbitalDefinition;
 /**
  * Wrap one or more OrbitalDefinitions into an OrbitalSchema.
  * Every .orb file should be a full OrbitalSchema — this is the builder for that.
@@ -103,4 +287,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 MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakeTraitRefOpts, compose, connect, ensureIdField, explodeBehaviorComposition, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, 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) {
@@ -1080,6 +1181,64 @@ function makePage(opts) {
 function makeOrbital(name, entity, traits, pages) {
   return { name, entity, traits, pages };
 }
+function makeTraitRef(opts) {
+  const ref = { ref: opts.ref };
+  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.events !== void 0) ref.events = opts.events;
+  if (opts.effects !== void 0) ref.effects = opts.effects;
+  if (opts.listens !== void 0) ref.listens = opts.listens;
+  if (opts.emitsScope !== void 0) ref.emitsScope = opts.emitsScope;
+  if (opts.config !== void 0) ref.config = opts.config;
+  return ref;
+}
+function makePageRef(opts) {
+  const ref = { ref: opts.ref };
+  if (opts.from !== void 0) ref.from = opts.from;
+  if (opts.path !== void 0) ref.path = opts.path;
+  if (opts.linkedEntity !== void 0) ref.linkedEntity = opts.linkedEntity;
+  if (opts.traits !== void 0) ref.traits = opts.traits;
+  return ref;
+}
+function makeOrbitalWithUses(opts) {
+  const orbital = {
+    name: opts.name,
+    uses: opts.uses,
+    entity: opts.entity,
+    traits: opts.traits,
+    pages: opts.pages ?? []
+  };
+  return orbital;
+}
+function makeAtomOrbital(opts) {
+  const traitRef = makeTraitRef({
+    from: opts.atomPath,
+    ref: opts.traitRef,
+    linkedEntity: opts.entity.name,
+    ...opts.traitOverrides?.name !== void 0 ? { name: opts.traitOverrides.name } : {},
+    ...opts.traitOverrides?.events !== void 0 ? { events: opts.traitOverrides.events } : {},
+    ...opts.traitOverrides?.effects !== void 0 ? { effects: opts.traitOverrides.effects } : {},
+    ...opts.traitOverrides?.listens !== void 0 ? { listens: opts.traitOverrides.listens } : {},
+    ...opts.traitOverrides?.emitsScope !== void 0 ? { emitsScope: opts.traitOverrides.emitsScope } : {},
+    ...opts.traitOverrides?.config !== void 0 ? { config: opts.traitOverrides.config } : {}
+  });
+  const pages = opts.pageRef ? [
+    makePageRef({
+      from: opts.atomPath,
+      ref: opts.pageRef,
+      linkedEntity: opts.entity.name,
+      ...opts.pageOverrides?.path !== void 0 ? { path: opts.pageOverrides.path } : {}
+    })
+  ] : void 0;
+  return makeOrbitalWithUses({
+    name: opts.name,
+    uses: [{ from: opts.atomPath, as: opts.alias }],
+    entity: opts.entity,
+    traits: [traitRef],
+    ...pages !== void 0 ? { pages } : {}
+  });
+}
 function makeSchema(name, ...definitions) {
   return { name, version: "1.0.0", orbitals: definitions };
 }
@@ -1227,6 +1386,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, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map