@almadar/core 7.10.0 → 7.10.1

package/dist/builders.d.ts

@@ -4,6 +4,21 @@ export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiri
 import 'zod';
 import '@almadar/patterns';
 
+/**
+ * Orbital Builders
+ *
+ * Pure functions for constructing and composing Orbitals.
+ * No new types. Everything uses existing core types:
+ * Entity, Trait, Page, OrbitalDefinition, OrbitalSchema.
+ *
+ * Three categories:
+ * 1. Builders: construct Entity, Page from common params
+ * 2. Utilities: ensureIdField, resolveDefaults
+ * 3. Composition: connect, compose, pipe
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Ensure the fields array has an `id` field. Prepends one if missing.
  */
@@ -67,6 +82,46 @@ interface MakeTraitRefOpts {
     /** Call-site config overrides. Matches {@link TraitReference.config}. */
     config?: TraitConfig;
 }
+/**
+ * Typed-narrowing variant of {@link MakeTraitRefOpts} for callers that know
+ * the imported atom's overridable surfaces — its event-key set, listen-key
+ * set, and config shape. Generated std factories use this variant so an LLM
+ * tool consumer (orbital-agent) sees the closed event-name set and the
+ * config field schema instead of the un-narrowed `Record<string, string>` /
+ * `TraitConfig` defaults.
+ *
+ * Type parameters:
+ * - `EventKey`   — string union of the atom's emit event names. Narrows the
+ *   `events` rename map's keys to legal originals only.
+ * - `ConfigShape` — typed shape of the trait's `config { ... }` block (literal
+ *   unions intact). Narrows the `config` override to the atom's actual fields.
+ * - `ListenKey`  — string union of the atom's listen-key contract. Narrows
+ *   each listens entry's `event` against the atom's real subscription set.
+ *
+ * Runtime behavior is unchanged — {@link makeTraitRef} accepts both the
+ * narrow and wide forms via the standard structural-typing rules. This is
+ * a type-level narrowing only; widening at the call boundary is intentional.
+ */
+interface MakeTraitRefOptsTyped<EventKey extends string = string, ConfigShape extends TraitConfig = Record<string, never>, ListenKey extends string = string> extends Omit<MakeTraitRefOpts, 'events' | 'effects' | 'listens' | 'config'> {
+    /** Per-key rename map, narrowed to the atom's actual event keys. */
+    events?: Partial<Record<EventKey, string>>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names so they're caller-defined (no narrowing here); values stay typed
+     * as `SExpr[]`.
+     */
+    effects?: Partial<Record<string, SExpr[]>>;
+    /**
+     * Replace the imported trait's `listens` array entirely. Each entry's
+     * `event` field is narrowed to {@link ListenKey} where the atom's
+     * subscription set is fixed; otherwise this widens to plain string.
+     */
+    listens?: Array<TraitEventListener & {
+        event?: ListenKey;
+    }>;
+    /** Typed call-site config overrides — narrowed to {@link ConfigShape}. */
+    config?: ConfigShape;
+}
 /**
  * Build a {@link TraitReference} from options.
  *
@@ -93,6 +148,21 @@ interface MakePageRefOpts {
     /** Replace the page's trait list. */
     traits?: TraitRef[];
 }
+/**
+ * Typed-narrowing variant of {@link MakePageRefOpts}. Narrows the `traits`
+ * override array's entries to the orbital's known trait-name union — so the
+ * agent can't pass a trait name that doesn't exist on the page's owning
+ * orbital. Generated std page-helpers use this variant to surface the
+ * trait set in the tool schema; un-narrowed call sites stay compatible.
+ *
+ * Type parameter:
+ * - `TraitName` — string union of trait names the page may reference.
+ */
+interface MakePageRefOptsTyped<TraitName extends string = string> extends Omit<MakePageRefOpts, 'traits'> {
+    traits?: Array<{
+        ref: TraitName;
+    } | TraitRef>;
+}
 /**
  * Build a {@link PageRefObject} from options. Pass-through factory — omits
  * optional keys that are `undefined`.
@@ -225,4 +295,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 MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakeTraitRefOpts, compose, connect, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };
+export { type ComposeConnection, type ComposePage, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakePageRefOptsTyped, type MakeTraitRefOpts, type MakeTraitRefOptsTyped, compose, connect, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };