@almadar/core 10.86.0 → 10.87.0

package/dist/factory-runtime/index.d.ts

@@ -1,8 +1,9 @@
-import { O as OrbitalSchema, a as OrbitalDefinition } from '../schema-BhfQb1oe.js';
-import { i as CallSiteConfig, j as CallSiteConfigEntry, h as Trait } from '../trait-pavNlGqm.js';
-import { E as EntityField, a as EntityPersistence } from '../effect-BgDiw_bG.js';
+import { O as OrbitalSchema, a as OrbitalDefinition } from '../schema-_SPrm5Ic.js';
+import { g as TraitConfigValue, i as CallSiteConfig, j as CallSiteConfigEntry, h as Trait } from '../trait-9tfq2tQb.js';
+import { E as EntityField, a as EntityPersistence } from '../effect-DMA97JxX.js';
 import { MakeTraitRefOpts } from '../builders.js';
-import '../expression-Fk8bQWef.js';
+import '../json-D8gmyK3l.js';
+import '../expression-WfTp2arD.js';
 import 'zod';
 
 /**
@@ -25,6 +26,14 @@ interface OrbitalParamsManifest {
     paramFields: readonly ParamFieldDescriptor[];
     traitNames: readonly string[];
     inlineTraitNames: readonly string[];
+    /**
+     * The orbital's own declared config knob names (`Orbital.config`), the
+     * `config` param's allow-list. Present only when the orbital declares at
+     * least one knob of its own — mirrors `paramFields`' persistence-style
+     * gate (see `extractManifest`). Absent means `config` is not a valid
+     * top-level param for this orbital at all.
+     */
+    configKeys?: readonly string[];
 }
 
 /**
@@ -36,6 +45,13 @@ interface OrbitalParamsManifest {
  * @packageDocumentation
  */
 
+/**
+ * The param descriptors this orbital actually accepts — the closed L1 delta
+ * allow-list, gated per orbital exactly like `persistence`/`collection`
+ * (dropped when the entity's persistence mode disallows overrides): `config`
+ * is dropped when the orbital declares no config knobs of its own.
+ */
+declare function paramFieldsFor(_orb: OrbitalSchema, orbital: OrbitalSchema['orbitals'][number]): readonly ParamFieldDescriptor[];
 declare function extractManifest(orb: OrbitalSchema): readonly OrbitalParamsManifest[];
 
 /**
@@ -80,6 +96,13 @@ interface OrbitalFactoryParams {
     readonly collection?: string;
     /** Per-imported-trait overrides, keyed on the trait's canonical `name`. */
     readonly traitOverrides?: Readonly<Record<string, OrbitalTraitOverride | undefined>>;
+    /**
+     * Override this orbital's OWN declared config knobs (`Orbital.config`) by
+     * key. Only present when the manifest carries `configKeys` (the orbital
+     * declares at least one knob of its own); every key must be a member of
+     * `configKeys` or validation rejects it.
+     */
+    readonly config?: Readonly<Record<string, TraitConfigValue>>;
 }
 /**
  * Discriminated failure shape for params validation against a manifest. Each
@@ -99,6 +122,13 @@ type ParamValidationError = {
 } | {
     readonly kind: 'trait-overrides-not-object';
     readonly received: string;
+} | {
+    readonly kind: 'config-not-object';
+    readonly received: string;
+} | {
+    readonly kind: 'unknown-config-key';
+    readonly key: string;
+    readonly allowed: readonly string[];
 };
 /** Discriminated result type for validation. Caller never widens. */
 type ParamValidationResult = {
@@ -286,4 +316,4 @@ declare function applyParamsToOrb(orb: OrbitalSchema, orbitalName: string, _mani
 
 declare function applyParamsToWholeOrb(orb: OrbitalSchema, manifests: readonly OrbitalParamsManifest[], params: OrbitalFactoryParams): OrbitalSchema;
 
-export { type EntityDeclarationRename, type OrbitalFactoryParams, type OrbitalParamsManifest, type OrbitalTraitOverride, type ParamFieldDescriptor, type ParamValidationError, type ParamValidationResult, type WalkableData, applyDeclarationEntityRename, applyDeclarationTraitRenames, applyParamsToOrb, applyParamsToWholeOrb, extractManifest, healEntityLedgerRows, healTraitLedgerRows, mergeCallSiteConfigOverrides, rebindInlineTraitEntity, rewriteEntityInInlineTrait, rewriteTraitRefsInTree, validateOrbitalFactoryParams };
+export { type EntityDeclarationRename, type OrbitalFactoryParams, type OrbitalParamsManifest, type OrbitalTraitOverride, type ParamFieldDescriptor, type ParamValidationError, type ParamValidationResult, type WalkableData, applyDeclarationEntityRename, applyDeclarationTraitRenames, applyParamsToOrb, applyParamsToWholeOrb, extractManifest, healEntityLedgerRows, healTraitLedgerRows, mergeCallSiteConfigOverrides, paramFieldsFor, rebindInlineTraitEntity, rewriteEntityInInlineTrait, rewriteTraitRefsInTree, validateOrbitalFactoryParams };

package/dist/factory-runtime/index.js

@@ -429,6 +429,9 @@ var EntityPersistenceSchema = z.enum([
 ]);
 var OrbitalEntitySchema = z.object({
   name: z.string().min(1, "Entity name is required"),
+  // V4 arena id (`EntityDefinition.id`); declared so the strip-mode zod gate
+  // carries an imported entity's id through instead of erasing it.
+  id: EntityIdSchema.optional(),
   persistence: EntityPersistenceSchema.default("persistent"),
   shared: z.boolean().optional(),
   // Must stay in step with the Rust serde field (`EntityDefinition.identity`,
@@ -520,7 +523,8 @@ var PayloadFieldSchema = z.object({
   type: z.string().min(1),
   required: z.boolean().optional(),
   properties: z.lazy(() => z.array(PayloadFieldSchema)).optional(),
-  typeWhen: z.array(PayloadTypeWhenSchema).optional()
+  typeWhen: z.array(PayloadTypeWhenSchema).optional(),
+  entity: z.string().min(1).optional()
 });
 var EventSchema = z.object({
   key: z.string().min(1, "Event key is required"),
@@ -569,6 +573,19 @@ var TraitConfigSchema = z.record(TraitConfigValueSchema);
 function isCallSiteConfigDeclaration(entry) {
   return typeof entry === "object" && entry !== null && !Array.isArray(entry) && "type" in entry && typeof entry.type === "string" && "default" in entry;
 }
+function overrideDeclaredKnobs(declared, overrides) {
+  const out = { ...declared };
+  for (const key of Object.keys(overrides)) {
+    const field = declared[key];
+    if (field === void 0) {
+      throw new Error(
+        `overrideDeclaredKnobs: config override "${key}" is not a declared knob (ORB_O_CONFIG_UNKNOWN_KEY). Declared: ${Object.keys(declared).join(", ") || "(none)"}`
+      );
+    }
+    out[key] = { ...field, default: overrides[key] };
+  }
+  return out;
+}
 var ConfigFieldItemsDeclarationSchema = z.lazy(
   () => z.object({
     type: z.string().optional(),
@@ -588,7 +605,8 @@ var ConfigFieldDeclarationSchema = z.object({
   values: z.array(z.string()).optional(),
   synonyms: z.string().optional(),
   items: ConfigFieldItemsDeclarationSchema.optional(),
-  properties: z.lazy(() => z.record(TraitEntityFieldSchema)).optional()
+  properties: z.lazy(() => z.record(TraitEntityFieldSchema)).optional(),
+  forwardedFrom: z.string().optional()
 });
 var DeclaredTraitConfigSchema = z.record(
   ConfigFieldDeclarationSchema
@@ -610,31 +628,32 @@ var TraitCategorySchema = z.enum([
   "game-board",
   "game-puzzle"
 ]);
+var TRAIT_FIELD_TYPES = [
+  "string",
+  "number",
+  "boolean",
+  "date",
+  "array",
+  "object",
+  "timestamp",
+  "datetime",
+  "enum",
+  "email",
+  "url",
+  "phone",
+  "uuid",
+  "image",
+  "trait",
+  "slot",
+  "pattern",
+  "node",
+  "event",
+  "scalar",
+  "union"
+];
 var TraitEntityFieldSchema = z.object({
   name: z.string().min(1),
-  type: z.enum([
-    "string",
-    "number",
-    "boolean",
-    "date",
-    "array",
-    "object",
-    "timestamp",
-    "datetime",
-    "enum",
-    "email",
-    "url",
-    "phone",
-    "uuid",
-    "image",
-    "trait",
-    "slot",
-    "pattern",
-    // `node` was missing here while being a real `TraitFieldType` member
-    // — the same latent-drift trap `event` would otherwise repeat.
-    "node",
-    "event"
-  ]),
+  type: z.enum(TRAIT_FIELD_TYPES),
   required: z.boolean().optional(),
   default: TraitConfigValueSchema.optional(),
   values: z.array(z.string()).optional(),
@@ -689,7 +708,7 @@ var EventPayloadFieldSchema = z.object({
   type: z.string().min(1),
   required: z.boolean().optional(),
   description: z.string().optional(),
-  entityType: z.string().optional(),
+  entity: z.string().optional(),
   properties: z.lazy(() => z.array(EventPayloadFieldSchema)).optional(),
   typeWhen: z.array(PayloadTypeWhenSchema).optional()
 });
@@ -746,8 +765,7 @@ var TraitEventListenerSchema = z.object({
 });
 var RequiredFieldSchema = z.object({
   name: z.string().min(1),
-  // `node` was missing here too (same drift as TraitEntityFieldSchema above).
-  type: z.enum(["string", "number", "boolean", "date", "array", "object", "timestamp", "datetime", "enum", "email", "url", "phone", "uuid", "image", "trait", "slot", "pattern", "node", "event"]),
+  type: z.enum(TRAIT_FIELD_TYPES),
   description: z.string().optional()
 });
 var TraitReferenceSchema = z.object({
@@ -766,6 +784,7 @@ var TraitReferenceSchema = z.object({
     z.string().min(1, "events value (caller event name) must be non-empty")
   ).optional(),
   eventIds: z.record(z.string().min(1), EventIdSchema).optional(),
+  _resolved: z.lazy(() => TraitSchema).optional(),
   // 3-II type-parameter arguments (see `TraitReference.typeArgs`).
   typeArgs: z.record(
     z.string().min(1, "typeArgs key (declared param name) must be non-empty"),
@@ -1384,7 +1403,8 @@ var UseDeclarationSchema = z.object({
   as: z.string().min(1, "Alias is required").regex(
     /^[A-Z][a-zA-Z0-9]*$/,
     'Alias must be PascalCase (e.g., "Health", "GameCore")'
-  )
+  ),
+  config: DeclaredTraitConfigSchema.optional()
 });
 var ExpectDeclarationSchema = z.discriminatedUnion("kind", [
   z.object({
@@ -1461,6 +1481,25 @@ var PageRefSchema = z.union([
   PageRefStringSchema,
   PageRefObjectSchema
 ]);
+var OrbitalRefStringSchema = z.string().regex(
+  /^[A-Z][a-zA-Z0-9]*\.orbitals\.[A-Z][a-zA-Z0-9]*$/,
+  'Orbital reference must be "Alias.orbitals.OrbitalName"'
+);
+var OrbitalRefObjectSchema = z.object({
+  ref: OrbitalRefStringSchema,
+  refId: OrbitalIdSchema.optional(),
+  entity: z.string().optional(),
+  fields: z.record(z.string()).optional(),
+  pages: z.record(z.string()).optional(),
+  omit: z.array(z.string()).optional(),
+  only: z.array(z.string()).optional(),
+  config: DeclaredTraitConfigSchema.optional(),
+  events: z.record(z.string()).optional(),
+  roles: z.record(z.string(), z.array(z.string())).optional(),
+  entities: z.record(z.string(), z.string()).optional(),
+  mounts: z.record(z.string(), z.array(z.string())).optional(),
+  extend: z.array(EntityFieldSchema).optional()
+});
 z.string().regex(
   /^([A-Z][a-zA-Z0-9]*\.traits\.)?[A-Z][a-zA-Z0-9]*$/,
   'Trait reference must be "TraitName" or "Alias.traits.TraitName"'
@@ -1503,6 +1542,15 @@ var OrbitalDefinitionSchema = z.object({
   services: z.array(ServiceRefSchema).optional(),
   // Components (inline or reference)
   entity: EntityRefSchema,
+  // Mirrors the `OrbitalDefinition.auxiliaryEntities` type field — WAS
+  // undeclared here, so `OrbitalSchemaSchema.safeParse` (every load through
+  // `external-loader.ts`) silently stripped it on every externally-loaded
+  // orbital (zod drops unrecognized keys by default), while a schema parsed
+  // directly via `JSON.parse` kept it. Found via the entity-field auto-merge
+  // rebind-target fallback landing on the wrong entity for any RECURSIVELY
+  // loaded `uses` file (`packages/almadar-runtime/src/resolver/
+  // reference-resolver.ts`'s `mergeImportedEntityFieldsIntoOrbital`).
+  auxiliaryEntities: z.array(EntityRefSchema).optional(),
   traits: z.array(TraitRefSchema),
   pages: z.array(PageRefSchema),
   // Event interface (trait-centric model) - computed by resolver
@@ -1510,6 +1558,10 @@ var OrbitalDefinitionSchema = z.object({
   listens: z.array(ComputedEventListenerSchema).optional(),
   // Filter for exposed events (trait-centric model)
   exposes: z.array(z.string()).optional(),
+  // This orbital's own declared knobs (§4.5)
+  config: DeclaredTraitConfigSchema.optional(),
+  // Transient — set by lowering, cleared by inline/resolve
+  reference: OrbitalRefObjectSchema.optional(),
   // Context fields - persisted throughout orbital lifecycle
   domainContext: DomainContextSchema.optional(),
   design: DesignPreferencesSchema.optional(),
@@ -1517,18 +1569,6 @@ var OrbitalDefinitionSchema = z.object({
   types: z.record(z.string(), z.array(EventPayloadFieldSchema)).optional()
 });
 var OrbitalSchema = OrbitalDefinitionSchema;
-var OrbitalConfigSchema = z.object({
-  theme: z.object({
-    primary: z.string().optional(),
-    secondary: z.string().optional(),
-    mode: z.enum(["light", "dark", "system"]).optional()
-  }).optional(),
-  features: z.record(z.boolean()).optional(),
-  api: z.object({
-    baseUrl: z.string().optional(),
-    timeout: z.number().optional()
-  }).optional()
-});
 var ConfigProvenanceRecordSchema = z.object({
   trait: z.string(),
   patternPath: z.string().optional(),
@@ -1554,7 +1594,7 @@ z.object({
   customPatterns: CustomPatternMapSchema,
   orbitals: z.array(OrbitalSchema).min(1, "At least one orbital is required"),
   services: z.array(ServiceDefinitionSchema).optional(),
-  config: OrbitalConfigSchema.optional(),
+  config: DeclaredTraitConfigSchema.optional(),
   _metadata: SchemaMetadataSchema.optional(),
   // V4 identity — optional/dual-carry until the Phase-7 flip. Present on
   // id-carrying `.orb` files so `parseOrbitalSchema` preserves them instead
@@ -1628,6 +1668,11 @@ var STATIC_PARAM_FIELDS = [
     name: "traitOverrides",
     type: "Partial<Record<TraitName, { config?, linkedEntity?, events?, name?, emitsScope?, listens? }>>",
     description: ".lolo's native trait-composition surface 1:1: per-imported-trait config, linkedEntity, events, name, emitsScope, listens. effects is excluded (atom-owned; use listens via a sibling trait)."
+  },
+  {
+    name: "config",
+    type: "Readonly<Record<string, TraitConfigValue>>",
+    description: "Override this orbital's own declared config knobs (Orbital.config) by key."
   }
 ];
 function entityPersistence(entity) {
@@ -1636,11 +1681,21 @@ function entityPersistence(entity) {
   }
   return void 0;
 }
-function paramFieldsForPersistence(persistence) {
-  if (persistenceModeAllowsOverrides(persistence)) {
-    return STATIC_PARAM_FIELDS;
-  }
-  return STATIC_PARAM_FIELDS.filter((f) => f.name !== "persistence" && f.name !== "collection");
+function declaredConfigKeys(config) {
+  if (config === void 0) return void 0;
+  const keys = Object.keys(config).sort();
+  return keys.length > 0 ? keys : void 0;
+}
+function paramFieldsFor(_orb, orbital) {
+  const allowPersistenceOverride = persistenceModeAllowsOverrides(entityPersistence(orbital.entity));
+  const hasConfig = declaredConfigKeys(orbital.config) !== void 0;
+  return STATIC_PARAM_FIELDS.filter((f) => {
+    if ((f.name === "persistence" || f.name === "collection") && !allowPersistenceOverride) {
+      return false;
+    }
+    if (f.name === "config" && !hasConfig) return false;
+    return true;
+  });
 }
 function splitTraits(traits) {
   const refTraitNames = [];
@@ -1661,12 +1716,14 @@ function extractManifest(orb) {
   const behaviorName = orb.name;
   return orb.orbitals.map((orbital) => {
     const { refTraitNames, inlineTraitNames } = splitTraits(orbital.traits);
+    const configKeys = declaredConfigKeys(orbital.config);
     return {
       organism: behaviorName,
       orbitalName: orbital.name,
-      paramFields: paramFieldsForPersistence(entityPersistence(orbital.entity)),
+      paramFields: paramFieldsFor(orb, orbital),
       traitNames: refTraitNames,
-      inlineTraitNames
+      inlineTraitNames,
+      ...configKeys !== void 0 ? { configKeys } : {}
     };
   });
 }
@@ -1748,6 +1805,21 @@ function validateOrbitalFactoryParams(manifest, raw) {
       }
     }
   }
+  if (candidate.config !== void 0) {
+    const cfg = candidate.config;
+    if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg)) {
+      return {
+        ok: false,
+        error: { kind: "config-not-object", received: Array.isArray(cfg) ? "array" : typeof cfg }
+      };
+    }
+    const allowedKeys = manifest.configKeys ?? [];
+    for (const key of Object.keys(cfg)) {
+      if (!allowedKeys.includes(key)) {
+        return { ok: false, error: { kind: "unknown-config-key", key, allowed: allowedKeys } };
+      }
+    }
+  }
   return { ok: true, params: candidate };
 }
 function assertResolvedEntity(entity, orbitalName, orbName) {
@@ -1901,8 +1973,8 @@ function rewriteEventContract(contract, oldName, newName) {
     ...contract,
     payloadSchema: contract.payloadSchema.map((f) => {
       const next = { ...f, type: rewritePayloadFieldType(f.type, oldName, newName) };
-      if (typeof f.entityType === "string" && f.entityType === oldName) {
-        next.entityType = newName;
+      if (typeof f.entity === "string" && f.entity === oldName) {
+        next.entity = newName;
       }
       return next;
     })
@@ -2162,6 +2234,9 @@ function applyParamsToOrb(orb, orbitalName, _manifest, params) {
     traits: rebuildTraits(orbital.traits),
     pages: rebuildPages(orbital.pages)
   });
+  if (orbital.config !== void 0) {
+    built.config = params.config !== void 0 ? overrideDeclaredKnobs(orbital.config, params.config) : orbital.config;
+  }
   if (built.traits && params.traitOverrides !== void 0) {
     built.traits = built.traits.map((t) => {
       if (!isTraitReferenceObject(t) || typeof t.name !== "string") return t;
@@ -2219,6 +2294,6 @@ function applyParamsToWholeOrb(orb, manifests, params) {
   return { ...orb, orbitals: rebuilt };
 }
 
-export { applyDeclarationEntityRename, applyDeclarationTraitRenames, applyParamsToOrb, applyParamsToWholeOrb, extractManifest, healEntityLedgerRows, healTraitLedgerRows, mergeCallSiteConfigOverrides, rebindInlineTraitEntity, rewriteEntityInInlineTrait, rewriteTraitRefsInTree, validateOrbitalFactoryParams };
+export { applyDeclarationEntityRename, applyDeclarationTraitRenames, applyParamsToOrb, applyParamsToWholeOrb, extractManifest, healEntityLedgerRows, healTraitLedgerRows, mergeCallSiteConfigOverrides, paramFieldsFor, rebindInlineTraitEntity, rewriteEntityInInlineTrait, rewriteTraitRefsInTree, validateOrbitalFactoryParams };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map