@almadar/core 10.41.0 → 10.43.0

package/dist/{expression-DpAj1RzP.d.ts → expression-Yf7qvvOs.d.ts}

@@ -1,5 +1,69 @@
 import { z } from 'zod';
 
+/**
+ * JSON primitives — the universal "data crossed a boundary" type.
+ *
+ * Every value that arrives over the wire from an LLM (tool-call args),
+ * from disk (workspace files), or from an HTTP body before
+ * domain-specific validation is a `JsonValue`. Narrow with a typed
+ * predicate (`is`-guard) at the boundary; don't widen back to `unknown`.
+ *
+ * `JsonObject` and `ToolArgs` are aliases for the common
+ * `Record<string, JsonValue>` shape. `ToolArgs` is the name the
+ * agent surface uses for LLM-emitted tool-call arguments; `JsonObject`
+ * is the general-purpose alias. They are the same type — the alias
+ * exists so call sites read at the right semantic level.
+ *
+ * Why not `Record<string, unknown>`? Two reasons. (1) `unknown` widens
+ * back to anything, which defeats the purpose of typing the boundary.
+ * (2) The `@almadar/eslint-plugin/no-record-string-unknown` rule blocks
+ * the wider form — `JsonValue`-based records are the typed answer.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Recursive JSON value union — every shape JSON can carry.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * JSON object — keyed string→JsonValue. The wire form of arbitrary
+ * structured data. Replaces `Record<string, unknown>` at typed
+ * boundaries (LLM emits, file reads, HTTP bodies).
+ */
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * LLM tool-call arguments — same shape as `JsonObject`, named for the
+ * agent-surface call site. Each tool's `execute(args: ToolArgs)`
+ * receives this and narrows via an `is`-guard predicate before any
+ * field access.
+ */
+type ToolArgs = JsonObject;
+/**
+ * Universal type-guard input — every runtime value shape a predicate can
+ * be handed, enumerated instead of `unknown` (the repo bans `unknown`
+ * even at guard boundaries). Primitives cover every `typeof` result;
+ * `object` covers arrays, records, class instances, and functions.
+ */
+type RuntimeValue = string | number | bigint | boolean | symbol | Date | null | undefined | object;
+/**
+ * Type guard: is the given value a JSON primitive (non-array,
+ * non-object)? Used by walkers that decide whether to recurse.
+ */
+declare function isJsonPrimitive(value: JsonValue): value is string | number | boolean | null;
+/**
+ * Type guard: is the given value a JSON object (non-array, non-null)?
+ */
+declare function isJsonObject(value: JsonValue): value is JsonObject;
+/**
+ * Type guard: is the given value a JSON array?
+ */
+declare function isJsonArray(value: JsonValue): value is JsonValue[];
+
 /**
  * S-Expression Types
  *
@@ -25,7 +89,11 @@ import { z } from 'zod';
  * - A binding reference (string starting with @)
  * - A call expression (array with operator as first element)
  */
-type SExprAtom = string | number | boolean | null | Record<string, unknown>;
+/** Object literal branch of an S-expression atom (payload data, props, etc.). */
+interface SExprObject {
+    [key: string]: SExpr;
+}
+type SExprAtom = string | number | boolean | null | SExprObject;
 type SExpr = SExprAtom | SExpr[];
 /**
  * Expression type - S-expressions only.
@@ -35,6 +103,13 @@ type SExpr = SExprAtom | SExpr[];
  * All expressions must be S-expression arrays.
  */
 type Expression = SExpr;
+/**
+ * Recursive schema for s-expr-shaped DATA in literal positions (object
+ * values, effect arguments). Unlike `SExprSchema`, arrays may be empty or
+ * non-operator-headed — literal data lists (`children: []`, `tiles: [...]`)
+ * are valid here; only call positions get the operator-head refine.
+ */
+declare const SExprDataSchema: z.ZodType<SExpr>;
 /**
  * Schema for atomic S-expression values (non-array)
  * Includes objects for payload data, props, etc.
@@ -59,7 +134,7 @@ declare const ExpressionSchema: z.ZodType<Expression>;
  * @param value - Value to check
  * @returns true if value is an S-expression (array with string operator)
  */
-declare function isSExpr(value: unknown): value is SExpr[];
+declare function isSExpr(value: RuntimeValue): value is SExpr[];
 /**
  * Type guard for S-expression atoms (non-array values).
  *
@@ -67,7 +142,7 @@ declare function isSExpr(value: unknown): value is SExpr[];
  * Includes null, strings, numbers, booleans, and objects. Used to
  * distinguish atomic values from S-expression calls (arrays).
  *
- * @param {unknown} value - Value to check
+ * @param {RuntimeValue} value - Value to check
  * @returns {boolean} True if value is an S-expression atom, false otherwise
  *
  * @example
@@ -77,7 +152,7 @@ declare function isSExpr(value: unknown): value is SExpr[];
  * isSExprAtom({ key: 'value' }); // returns true
  * isSExprAtom(['+', 1, 2]); // returns false
  */
-declare function isSExprAtom(value: unknown): value is SExprAtom;
+declare function isSExprAtom(value: RuntimeValue): value is SExprAtom;
 /**
  * Checks if a value is a binding reference.
  *
@@ -85,7 +160,7 @@ declare function isSExprAtom(value: unknown): value is SExprAtom;
  * Bindings reference runtime values like @entity.health, @payload.amount, @now.
  * Used for identifying bindings in S-expressions and validation.
  *
- * @param {unknown} value - Value to check
+ * @param {RuntimeValue} value - Value to check
  * @returns {boolean} True if value is a binding reference, false otherwise
  *
  * @example
@@ -94,14 +169,14 @@ declare function isSExprAtom(value: unknown): value is SExprAtom;
  * isBinding('not-a-binding'); // returns false
  * isBinding(123); // returns false
  */
-declare function isBinding(value: unknown): value is string;
+declare function isBinding(value: RuntimeValue): value is string;
 /**
  * Checks if a value is a valid S-expression call (array with operator).
  *
  * Alias for isSExpr() - validates S-expression call structure.
  * Used to distinguish between S-expression calls and atom values.
  *
- * @param {unknown} value - Value to check
+ * @param {RuntimeValue} value - Value to check
  * @returns {boolean} True if value is a valid S-expression call, false otherwise
  *
  * @example
@@ -109,7 +184,7 @@ declare function isBinding(value: unknown): value is string;
  * isSExprCall(['set', '@entity.health', 100]); // returns true
  * isSExprCall('not-a-call'); // returns false
  */
-declare function isSExprCall(value: unknown): value is SExpr[];
+declare function isSExprCall(value: RuntimeValue): value is SExpr[];
 /**
  * Parsed binding reference
  */
@@ -223,7 +298,7 @@ interface EventPayload {
  * Runtime guard for `EventPayloadValue` — narrows interpreter-produced
  * `unknown` values at typed substrate boundaries (e.g. `TraceContext.emit`).
  */
-declare function isEventPayloadValue(value: unknown): value is EventPayloadValue;
+declare function isEventPayloadValue(value: RuntimeValue): value is EventPayloadValue;
 /**
  * Allowed leaf value for `LogMeta`. Mirrors `EventPayloadValue` shape so
  * the same row/list data flows through logs without manual flattening,
@@ -235,4 +310,4 @@ interface LogMeta {
     [key: string]: LogMetaValue;
 }
 
-export { CORE_BINDINGS as C, type Expression as E, type LogMeta as L, type ParsedBinding as P, type SExpr as S, type EventPayload as a, type CoreBinding as b, type EvalContext as c, type EventPayloadValue as d, type ExpressionInput as e, ExpressionSchema as f, type LogMetaValue as g, type SExprAtom as h, SExprAtomSchema as i, type SExprInput as j, SExprSchema as k, collectBindings as l, getArgs as m, getOperator as n, isBinding as o, isEventPayloadValue as p, isSExpr as q, isSExprAtom as r, isSExprCall as s, isValidBinding as t, parseBinding as u, sexpr as v, walkSExpr as w };
+export { parseBinding as A, sexpr as B, CORE_BINDINGS as C, walkSExpr as D, type Expression as E, type JsonValue as J, type LogMeta as L, type ParsedBinding as P, type RuntimeValue as R, type SExpr as S, type ToolArgs as T, type EventPayload as a, type CoreBinding as b, type EvalContext as c, type EventPayloadValue as d, type ExpressionInput as e, ExpressionSchema as f, type JsonObject as g, type LogMetaValue as h, type SExprAtom as i, SExprAtomSchema as j, SExprDataSchema as k, type SExprInput as l, type SExprObject as m, SExprSchema as n, collectBindings as o, getArgs as p, getOperator as q, isBinding as r, isEventPayloadValue as s, isJsonArray as t, isJsonObject as u, isJsonPrimitive as v, isSExpr as w, isSExprAtom as x, isSExprCall as y, isValidBinding as z };

package/dist/factory/index.d.ts

@@ -1,11 +1,9 @@
-import { h as FactoryParamValue, c as FactoryConfigTier, b as FactoryConfigParam, F as FactoryCallSite, j as FactorySignature, R as RuleOverlay, p as RuleOverlayEntry, o as PresentationOverlay, T as TraitOverlay } from '../types-CzocAZtG.js';
-export { a as FactoryCallSiteParams, d as FactoryEntitySignature, e as FactoryEventSignature, f as FactoryExposure, g as FactoryPageSignature, i as FactoryProvenance, k as FactorySignatureCatalog, l as FactorySignatureEntityField, m as FactoryTraitSignature, J as JsonSchema, n as JsonSchemaType, O as OwnershipOverlayEntry, P as PresentationNavItem, S as SchemaFieldType, q as TraitOverlayEntry, r as TraitOverlayListener } from '../types-CzocAZtG.js';
-import { E as EntityPersistence, a as EntityField } from '../entity-DfD-iXkn.js';
-export { J as JsonValue } from '../entity-DfD-iXkn.js';
-import { a as TraitReference } from '../trait-2E6TQw19.js';
+import { h as FactoryParamValue, c as FactoryConfigTier, b as FactoryConfigParam, F as FactoryCallSite, j as FactorySignature, R as RuleOverlay, p as RuleOverlayEntry, o as PresentationOverlay, T as TraitOverlay } from '../types-B4NVh8V9.js';
+export { a as FactoryCallSiteParams, d as FactoryEntitySignature, e as FactoryEventSignature, f as FactoryExposure, g as FactoryPageSignature, i as FactoryProvenance, k as FactorySignatureCatalog, l as FactorySignatureEntityField, m as FactoryTraitSignature, J as JsonSchema, n as JsonSchemaType, O as OwnershipOverlayEntry, P as PresentationNavItem, S as SchemaFieldType, q as TraitOverlayEntry, r as TraitOverlayListener } from '../types-B4NVh8V9.js';
+import { a as EntityPersistence, E as EntityField } from '../effect-NbTgX2yB.js';
+import { a as TraitReference } from '../trait-DdBiEffx.js';
+export { J as JsonValue } from '../expression-Yf7qvvOs.js';
 import 'zod';
-import '../expression-DpAj1RzP.js';
-import '../effect-DSbx6joe.js';
 
 /**
  * Typed questionnaire surface — shapes the studio renders + answers.

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

@@ -1,9 +1,9 @@
-import { O as OrbitalSchema, M as MakeTraitRefOpts, a as OrbitalDefinition } from '../builders-CikYSzX6.js';
-import { C as CallSiteConfig, b as CallSiteConfigEntry, c as Trait } from '../trait-2E6TQw19.js';
-import { a as EntityField, E as EntityPersistence } from '../entity-DfD-iXkn.js';
+import { O as OrbitalSchema, a as OrbitalDefinition } from '../schema-DdcBBHkb.js';
+import { h as CallSiteConfig, i as CallSiteConfigEntry, g as Trait } from '../trait-DdBiEffx.js';
+import { E as EntityField, a as EntityPersistence } from '../effect-NbTgX2yB.js';
+import { MakeTraitRefOpts } from '../builders.js';
+import '../expression-Yf7qvvOs.js';
 import 'zod';
-import '../effect-DSbx6joe.js';
-import '../expression-DpAj1RzP.js';
 
 /**
  * Orbital factory manifest types — shared across all packages.

package/dist/factory-runtime/index.js

@@ -343,7 +343,7 @@ var OrbitalEntitySchema = z.object({
   identity: z.boolean().optional(),
   collection: z.string().optional(),
   fields: z.array(EntityFieldSchema).min(1, "At least one field is required"),
-  instances: z.array(z.record(z.unknown())).optional(),
+  instances: z.array(z.record(JsonValueSchema)).optional(),
   timestamps: z.boolean().optional(),
   softDelete: z.boolean().optional(),
   description: z.string().optional(),
@@ -354,6 +354,29 @@ var EntitySchema = OrbitalEntitySchema;
 function persistenceModeAllowsOverrides(persistence) {
   return persistence === "persistent" || persistence === void 0;
 }
+var SExprDataSchema = z.lazy(
+  () => z.union([SExprAtomSchema, z.array(SExprDataSchema)])
+);
+var SExprAtomSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.record(SExprDataSchema)
+  // Objects for payload data
+]);
+var SExprSchema = z.lazy(
+  () => z.union([
+    SExprAtomSchema,
+    z.array(z.lazy(() => SExprSchema)).min(1).refine(
+      (arr) => typeof arr[0] === "string",
+      { message: "S-expression array must have a string operator as first element" }
+    )
+  ])
+);
+var ExpressionSchema = SExprSchema;
+
+// src/types/effect.ts
 var UI_SLOTS = [
   // App slots
   "main",
@@ -383,28 +406,10 @@ var UI_SLOTS = [
   "overlay.pause"
 ];
 z.enum(UI_SLOTS);
-var EffectSchema = z.array(z.unknown()).min(1).refine(
+var EffectSchema = z.array(SExprDataSchema).min(1).refine(
   (arr) => typeof arr[0] === "string",
   { message: "Effect must be an S-expression with a string operator as first element" }
 );
-var SExprAtomSchema = z.union([
-  z.string(),
-  z.number(),
-  z.boolean(),
-  z.null(),
-  z.record(z.unknown())
-  // Objects for payload data
-]);
-var SExprSchema = z.lazy(
-  () => z.union([
-    SExprAtomSchema,
-    z.array(z.lazy(() => SExprSchema)).min(1).refine(
-      (arr) => typeof arr[0] === "string",
-      { message: "S-expression array must have a string operator as first element" }
-    )
-  ])
-);
-var ExpressionSchema = SExprSchema;
 
 // src/types/state-machine.ts
 var StateSchema = z.object({
@@ -638,7 +643,7 @@ var RequiredFieldSchema = z.object({
   type: z.enum(["string", "number", "boolean", "date", "array", "object", "timestamp", "datetime", "enum", "email", "url", "phone", "uuid", "image"]),
   description: z.string().optional()
 });
-z.object({
+var TraitReferenceSchema = z.object({
   ref: z.string().min(1),
   refId: TraitIdSchema.optional(),
   // V4 local declaration id (see the interface doc) — declared so the
@@ -664,12 +669,9 @@ z.object({
   // through to the recursive TraitConfigValue union.
   config: z.record(z.union([ConfigFieldDeclarationSchema, TraitConfigValueSchema])).optional(),
   appliesTo: z.array(z.string()).optional(),
-  // Phase F.7: zod accepts an array (the inliner validates element
-  // shape). The full ListenDefinition shape isn't recursively encoded
-  // here because TraitReference is the call-site form — listen entries
-  // pasted in are already-resolved structured definitions, not nested
-  // overrides.
-  listens: z.array(z.unknown()).optional(),
+  // Phase F.7: caller-supplied listen entries are already-resolved
+  // structured definitions (see `TraitReference.listens`).
+  listens: z.array(TraitEventListenerSchema).optional(),
   emitsScope: z.enum(["internal", "external"]).optional(),
   // Phase F.8: per-transition effects override. The keys are event
   // names (the transition triggers AFTER renames); values are SExpr
@@ -691,6 +693,22 @@ z.object({
     path: ["events"]
   }
 );
+var TraitUIBindingSchema = z.record(
+  z.object({
+    presentation: z.enum(["modal", "drawer", "popover", "inline", "confirm-dialog"]),
+    content: z.union([z.record(JsonValueSchema), z.array(z.record(JsonValueSchema))]),
+    props: z.object({
+      size: z.enum(["sm", "md", "lg", "xl", "full"]).optional(),
+      position: z.enum(["left", "right", "top", "bottom", "center"]).optional(),
+      title: z.string().optional(),
+      closable: z.boolean().optional(),
+      width: z.string().optional(),
+      showProgress: z.boolean().optional(),
+      step: z.number().optional(),
+      totalSteps: z.number().optional()
+    }).optional()
+  })
+);
 var TraitScopeSchema = z.enum(["instance", "collection"]);
 var EntityFieldContractSchema = z.object({
   requires: z.array(z.string()),
@@ -724,26 +742,14 @@ var TraitSchema = z.object({
   ticks: z.array(TraitTickSchema).optional(),
   emits: z.array(TraitEventContractSchema).optional(),
   listens: z.array(TraitEventListenerSchema).optional(),
-  ui: z.record(z.unknown()).optional(),
+  ui: TraitUIBindingSchema.optional(),
   config: DeclaredTraitConfigSchema.optional(),
   sourceBehavior: SourceBehaviorMetadataSchema.optional(),
   sourceEntityDefinition: EntitySchema.optional()
 });
 var TraitRefSchema = z.union([
   z.string().min(1),
-  z.object({
-    ref: z.string().min(1),
-    config: TraitConfigSchema.optional(),
-    linkedEntity: z.string().optional(),
-    name: z.string().optional(),
-    // Phase F.4: same non-empty refine as TraitReferenceSchema.events.
-    // Both schemas accept the same call-site argument shape, so the
-    // validators should agree.
-    events: z.record(
-      z.string().min(1, "events key (atom event name) must be non-empty"),
-      z.string().min(1, "events value (caller event name) must be non-empty")
-    ).optional()
-  }),
+  TraitReferenceSchema,
   TraitSchema
   // Allow inline trait definitions
 ]);