import { OrbitalSchema, EntityField, EntityPersistence, OrbitalDefinition, Trait } from '@almadar/core';
import { O as OrbitalParamsManifest } from '../dispatch-DgvWJ48c.js';
export { P as ParamFieldDescriptor } from '../dispatch-DgvWJ48c.js';
import { MakeTraitRefOpts } from '@almadar/core/builders';
import '@almadar/core/types';

/**
 * `extractManifest(orb)` — derive the typed `OrbitalParamsManifest[]` from a
 * resolved `.orb`, one entry per orbital. The result has the exact same
 * shape the codegen `regenerate-std-ts.mjs` emits as `*OrbitalManifest`
 * literals.
 *
 * Pure data → data. No I/O. No behavior-specific branching.
 *
 * Used by:
 * - `scripts/regenerate-std-ts.mjs` — emits the manifest as a TS literal.
 * - The promotion server (Phase B) — stores `manifests[]` alongside the orb.
 *
 * @packageDocumentation
 */

/**
 * Produce one `OrbitalParamsManifest` per orbital in the orb. The orb's
 * top-level `name` is the behavior name (e.g. `std-embedded-dashboard`);
 * each orbital's `name` is the orbital name (e.g. `DashboardOrbital`).
 */
declare function extractManifest(orb: OrbitalSchema): readonly OrbitalParamsManifest[];

/**
 * Factory-runtime — typed shapes.
 *
 * The factory runtime is the data-driven equivalent of the per-behavior TS
 * factories generated by `scripts/regenerate-std-ts.mjs`. The script bakes
 * the same overlay logic into each emitted factory; the runtime form lifts it
 * out so team-published behaviors (Firestore-stored, not code-published) can
 * flow through the identical code path.
 *
 * Reference: `docs/Almadar_Studio_SDK.md` §7.4.
 *
 * @packageDocumentation
 */

/**
 * The override surface for a single imported trait. Mirrors `.lolo`'s native
 * trait-composition surface 1:1 (see SDK doc §7.4 + the generated
 * `traitOverrides` types in each std factory). `effects` is intentionally
 * NOT exposed — that's atom-owned (use `listens` via a sibling trait to
 * react to atom events).
 */
type OrbitalTraitOverride = Pick<MakeTraitRefOpts, 'config' | 'linkedEntity' | 'events' | 'name' | 'emitsScope' | 'listens'>;
/**
 * Strongly-typed params accepted by `applyParamsToOrb`. Same shape as every
 * generated per-orbital `*Params` interface (the codegen narrows
 * `traitOverrides`'s key type to that orbital's `traitNames`; the runtime
 * form keeps it open and validates the keys against the manifest at call
 * time).
 */
interface OrbitalFactoryParams {
    /** Extra fields appended to the canonical entity (caller wins on name collision). */
    readonly fields?: readonly EntityField[];
    /** URL path override for the orbital's first page. */
    readonly pagePath?: string;
    /** Override the canonical entity persistence mode. */
    readonly persistence?: EntityPersistence;
    /** Rename the canonical entity (PascalCase singular, ≤32 chars). */
    readonly entityName?: string;
    /** Override the derived collection key (defaults to plural-of-entityName). */
    readonly collection?: string;
    /** Per-imported-trait overrides, keyed on the trait's canonical `name`. */
    readonly traitOverrides?: Readonly<Record<string, OrbitalTraitOverride | undefined>>;
}
/**
 * Discriminated failure shape for params validation against a manifest. Each
 * variant carries the smallest information needed for an actionable error
 * message — never a raw thrown `Error`.
 */
type ParamValidationError = {
    readonly kind: 'unknown-key';
    readonly key: string;
} | {
    readonly kind: 'unknown-trait-override';
    readonly trait: string;
    readonly allowed: readonly string[];
} | {
    readonly kind: 'not-object';
    readonly received: string;
} | {
    readonly kind: 'trait-overrides-not-object';
    readonly received: string;
};
/** Discriminated result type for validation. Caller never widens. */
type ParamValidationResult = {
    readonly ok: true;
    readonly params: OrbitalFactoryParams;
} | {
    readonly ok: false;
    readonly error: ParamValidationError;
};

/**
 * `applyParamsToOrb` — pure runtime overlay function. Equivalent to the body
 * the codegen `regenerate-std-ts.mjs` emits inline for every std factory
 * (`scripts/regenerate-std-ts.mjs:612-737`), lifted out so that:
 *   1. team-published behaviors (Firestore-stored) can dispatch through the
 *      same overlay as std behaviors;
 *   2. std factories *can* (future cleanup) collapse to a one-line wrapper
 *      calling this function.
 *
 * Reference: `docs/Almadar_Studio_SDK.md` §7.4.2.
 *
 * Pure data → data. No I/O.
 *
 * @packageDocumentation
 */

/**
 * Structural validation of caller-supplied params against the manifest.
 * Rejects unknown top-level keys and unknown `traitOverrides` keys (the
 * latter against the manifest's `traitNames` allow-list).
 *
 * `raw: object` is the minimum-typed input: callers must already have
 * narrowed from JSON / LLM output to a plain object. The discriminated
 * result lifts callers into the typed `OrbitalFactoryParams` on success.
 */
declare function validateOrbitalFactoryParams(manifest: OrbitalParamsManifest, raw: object): ParamValidationResult;
/**
 * Rewrite every entity-name reference inside an inline `Trait` so a
 * factory-driven `params.entityName` rename actually lands on the
 * SExpression literals embedded in transitions / effects / ticks /
 * payload type strings. The trait's top-level `linkedEntity` is rewritten
 * separately by `rewriteInlineLinkedEntity`; this function walks every
 * field that can carry a body-level reference. Returns the same canonical
 * `Trait` shape — no widening, no `unknown`.
 */
/**
 * Rebind an inline `Trait` to a renamed entity. Combines top-level
 * `linkedEntity` rewrite + body-level entity-ref rewriting (SExpr literals
 * in transitions / effects / ticks / payloads / listens).
 *
 * Exported for use by codegen-emitted std factories
 * (`packages/almadar-std/behaviors/functions/*.ts`) so the codegen and the
 * runtime overlay share ONE rewriter. Plan rule 6: codegen + runtime overlay
 * MUST stay symmetric — making both call this single helper enforces that.
 */
declare function rebindInlineTraitEntity(trait: Trait, oldName: string, newName: string): Trait;
/**
 * The overlay. Resolves the effective entity name + collection, calls
 * `makeOrbitalWithUses` with the rewritten data, then applies the params'
 * trait/page overrides post-hoc — exactly mirroring the codegen emit at
 * `scripts/regenerate-std-ts.mjs:612-737`.
 *
 * `_manifest` is accepted for parity with the future dispatcher signature
 * but is unused in this overlay — the manifest is consumed by
 * `validateOrbitalFactoryParams` upstream. Kept on the signature so std
 * factories can collapse to one-line wrappers without an arg-shape change.
 */
declare function applyParamsToOrb(orb: OrbitalSchema, orbitalName: string, _manifest: OrbitalParamsManifest, params: OrbitalFactoryParams): OrbitalDefinition;

/**
 * `applyParamsToWholeOrb` — pure runtime overlay for an ENTIRE stored orb.
 *
 * Companion to `applyParamsToOrb` (single-orbital). Where `applyParamsToOrb`
 * materialises one orbital from a multi-orbital schema, this function applies
 * the same overlay to every orbital in the schema by joining each orbital to
 * its matching manifest entry from `manifests[]`. Returns a new
 * `OrbitalSchema` with the rebuilt orbitals.
 *
 * Used by team-behavior dispatch on the LLM-loop seam (`call_behavior` tool
 * in @almadar/agent): the LLM emits `call_behavior('team/<name>@<v>', params)`,
 * std-import returns undefined, the agent's `extra.dispatchWhole` port runs
 * this function over the Firestore-stored record's `{ orb, manifests }`.
 *
 * Reference: `docs/Almadar_Studio_SDK.md` §7.4.4.
 *
 * Pure data → data. No I/O.
 *
 * @packageDocumentation
 */

/**
 * Apply `params` to every orbital in `orb` that has a matching manifest in
 * `manifests[]`. Orbitals with no manifest are passed through unchanged —
 * the storage convention is one manifest per orbital, so a missing manifest
 * indicates a stored orbital we don't know how to parameterise (rare; the
 * promote path writes manifests for every orbital it knows).
 *
 * @param orb        The full team-behavior schema as stored.
 * @param manifests  Per-orbital param manifests; joined to orbitals by name.
 * @param params     One shared params bag applied to every parameterised
 *                   orbital. Mirrors the std whole-behavior factories'
 *                   convention of a single `params` argument.
 */
declare function applyParamsToWholeOrb(orb: OrbitalSchema, manifests: readonly OrbitalParamsManifest[], params: OrbitalFactoryParams): OrbitalSchema;

export { type OrbitalFactoryParams, OrbitalParamsManifest, type OrbitalTraitOverride, type ParamValidationError, type ParamValidationResult, applyParamsToOrb, applyParamsToWholeOrb, extractManifest, rebindInlineTraitEntity, validateOrbitalFactoryParams };
