@almadar/core 10.28.0 → 10.30.0

package/dist/{types-DFn3sWpV.d.ts → types-yW22YNNt.d.ts}

@@ -1,5 +1,6 @@
-import { E as EntityField, a as EntityPersistence, R as RelationConfig } from './pattern-types-BeQXwgpZ.js';
-import { T as TraitEventListener, a as TraitReference } from './trait-DZkS625T.js';
+import { E as EntityField, a as EntityPersistence, R as RelationConfig } from './pattern-types-CLcOXOmW.js';
+import { T as TraitEventListener, a as TraitReference } from './trait-CwWjkU-1.js';
+import { J as JsonValue } from './json-DOTchoRS.js';
 
 /**
  * Cross-cutting presentation knobs that don't live per orbital
@@ -68,62 +69,6 @@ interface OwnershipOverlayEntry {
     ownerField: string;
 }
 
-/**
- * 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;
-/**
- * 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[];
-
 /**
  * Recursive JSON Schema. Intentionally narrow — only the keywords V2's
  * signature → schema generator emits. Custom `x-*` extensions carry
@@ -219,6 +164,14 @@ interface FactoryConfigParam {
     /** Key name as advertised by the trait. Matches the override path
      *  `traitOverrides.<traitName>.config.<key>`. */
     key: string;
+    /** True when the atom's own state machine consumes this config value in
+     *  an entity position (`['persist', op, '@config.<key>', …]` or
+     *  `['fetch', '@config.<key>', …]`) — the value IS an entity name.
+     *  Source-derived at signature extraction, never authored. Consumers
+     *  threading a `params.entityName` rename must rewrite every
+     *  entityRef-marked value equal to the renamed entity, or the baked
+     *  default dangles against an entity that no longer exists. */
+    entityRef?: boolean;
     /** Type tag lifted from the `.lolo` config declaration. Drives the
      *  question widget selection. Free-form to admit array/object
      *  brackets (`[object]`, `[string]`) and atom-defined custom tags. */
@@ -305,6 +258,19 @@ interface FactoryTraitSignature {
     emittedEvents: ReadonlyArray<string>;
     /** Event keys this trait listens for. */
     listenedEvents: ReadonlyArray<string>;
+    /** Event keys the trait's own state machine transitions on
+     *  (`stateMachine.transitions[].event`, post-rename) — the only valid
+     *  `listens[].triggers` targets (ORB_X_LISTEN_TRIGGER_UNMATCHED
+     *  otherwise). Present when the source trait carries a state machine
+     *  (directly or inherited from its upstream atom); an EMPTY array means
+     *  the trait is render-only and cannot accept a listens entry at all.
+     *  Absent = topology unknown (legacy catalogs). */
+    transitionEvents?: ReadonlyArray<string>;
+    /** Call-site `events` rename map (old → new) authored on the trait ref.
+     *  Renames rewrite the upstream atom's transition triggers, so catalog
+     *  inheritance projects the atom's `transitionEvents` through this map
+     *  before stamping them on the call site. */
+    eventRenames?: Readonly<Record<string, string>>;
     /** Structured emit + listen events with their `@description`/`@synonyms`/`@tier`
      *  annotations. Parallel to `emittedEvents`/`listenedEvents` (kept as bare-key
      *  back-compat); the curation event matcher reads this. */
@@ -437,6 +403,28 @@ interface FactorySignature {
      * (`computeSubstrateSignature`); recomputed every generation run.
      */
     substrateSignature?: string;
+    /**
+     * Organism-only dispatch smoke test. Stamped by pattern-sync gen-ts;
+     * `true` when the organism's factory dispatch with default params
+     * round-trips `orb resolve` clean. `false` = not factory ready (excluded
+     * from HIT retrieval; stays compose-palette if palette-exposed).
+     * Undefined = not yet swept (legacy catalogs).
+     */
+    factoryReady?: boolean;
+    /** Resolve/validate error strings when `factoryReady` is `false`. */
+    readinessErrors?: ReadonlyArray<string>;
+    /**
+     * Tier-agnostic (atoms/molecules/organisms alike). Stamped by
+     * pattern-sync gen-ts for every behavior entry: `true` when the
+     * registry `.orb` passes `orb validate` + `orb resolve` at bake time.
+     * `false` = source-broken (excluded from retrieval regardless of tier).
+     * Undefined = not yet swept (legacy catalogs). Distinct from
+     * `factoryReady`, which additionally requires an organism-level
+     * dispatch smoke test.
+     */
+    sourceValid?: boolean;
+    /** `orb validate`/`orb resolve` error strings when `sourceValid` is `false`. */
+    sourceErrors?: ReadonlyArray<string>;
 }
 /**
  * Aggregate catalog written to
@@ -500,4 +488,4 @@ type FactoryParamValue = string | number | boolean | ReadonlyArray<FactoryParamV
     readonly [key: string]: FactoryParamValue;
 };
 
-export { type FactoryCallSite as F, type JsonValue as J, type OwnershipOverlayEntry as O, type PresentationNavItem as P, type RuleOverlay as R, type SchemaFieldType as S, type ToolArgs as T, type FactoryCallSiteParams as a, type FactoryConfigParam as b, type FactoryConfigTier as c, type FactoryEntitySignature as d, type FactoryEventSignature as e, type FactoryExposure as f, type FactoryPageSignature as g, type FactoryParamValue as h, type FactoryProvenance as i, type FactorySignature as j, type FactorySignatureCatalog as k, type FactorySignatureEntityField as l, type FactoryTraitSignature as m, type JsonObject as n, type JsonSchema as o, type JsonSchemaType as p, type PresentationOverlay as q, type RuleOverlayEntry as r, type TraitOverlay as s, type TraitOverlayEntry as t, type TraitOverlayListener as u, isJsonArray as v, isJsonObject as w, isJsonPrimitive as x };
+export type { FactoryCallSite as F, JsonSchema as J, OwnershipOverlayEntry as O, PresentationNavItem as P, RuleOverlay as R, SchemaFieldType as S, TraitOverlay as T, FactoryCallSiteParams as a, FactoryConfigParam as b, FactoryConfigTier as c, FactoryEntitySignature as d, FactoryEventSignature as e, FactoryExposure as f, FactoryPageSignature as g, FactoryParamValue as h, FactoryProvenance as i, FactorySignature as j, FactorySignatureCatalog as k, FactorySignatureEntityField as l, FactoryTraitSignature as m, JsonSchemaType as n, PresentationOverlay as o, RuleOverlayEntry as p, TraitOverlayEntry as q, TraitOverlayListener as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/core",
-  "version": "10.28.0",
+  "version": "10.30.0",
   "description": "Core schema types and definitions for Almadar",
   "type": "module",
   "main": "./dist/index.js",

package/src/types/bindings.ts

@@ -98,6 +98,12 @@ export const BINDING_DOCS = {
     examples: ['@user.id', '@user.role'],
     requiresPath: true,
   },
+  callsitePayload: {
+    description:
+      'Call-site-captured event payload — emitted by the compiler\'s inline-trait hoisting when an extracted render block captured @payload; resolved at the composing effect by the runtime BindingResolver',
+    examples: ['@callsitePayload.error', '@callsitePayload.row'],
+    requiresPath: true,
+  },
 } as const;
 
 /**
@@ -110,9 +116,9 @@ export const BINDING_CONTEXT_RULES = {
       'Guards can access entity fields, event payload, current state, time, the call-site trait config (@config.X), and the authenticated user context (@user.id, @user.role) for ownership / role gates. Config access lets atoms write mode-aware guards — e.g. std-modal\'s OPEN can require @payload.row only when @config.mode equals "edit", letting create-mode legitimately fire OPEN with no row. Like effects, @config.X is substituted at molecule/organism inline time with the literal call-site value; at atom-scope validate, @config is allowed-but-unresolved.',
   },
   effect: {
-    allowed: ['entity', 'payload', 'state', 'now', 'trait', 'config', 'user'] as const,
+    allowed: ['entity', 'payload', 'state', 'now', 'trait', 'config', 'user', 'callsitePayload'] as const,
     description:
-      'Effects can access and modify entity fields, use payload data, embed another trait\'s live frame via @trait.X inside render-ui children, read trait config values (@config.X) for atoms parameterized by their call-site, and read the authenticated user context (@user.id, @user.role). At molecule/organism inline time, @config.X is substituted with the literal value from the call-site config block; at atom-scope validate, @config is allowed-but-unresolved.',
+      'Effects can access and modify entity fields, use payload data, embed another trait\'s live frame via @trait.X inside render-ui children, read trait config values (@config.X) for atoms parameterized by their call-site, and read the authenticated user context (@user.id, @user.role). At molecule/organism inline time, @config.X is substituted with the literal value from the call-site config block; at atom-scope validate, @config is allowed-but-unresolved. @callsitePayload.X is the call-site-captured event payload emitted by the compiler\'s inline-trait hoisting (a hoisted render block that captured @payload); it is resolved at the composing effect by the runtime BindingResolver.',
   },
   tick: {
     allowed: ['entity', 'state', 'now', 'config', 'user'] as const,