@almadar/runtime 6.32.0 → 6.34.0

package/dist/createOsHandlers.d.ts

@@ -1,4 +1,4 @@
-import { a as EffectHandlers } from './types-D-9feVsj.js';
+import { E as EffectHandlers } from './types-C8RsO0xa.js';
 import { EventPayload } from '@almadar/core';
 
 /**

package/dist/{external-loader-OPXVTNC4.js → external-loader-FNK5AU6U.js}

@@ -50,6 +50,22 @@ var LoaderCache = class {
     return this.cache.size;
   }
 };
+var BROWSE_FORM_HELP = "Accepted forms \u2014 loader: std/behaviors/<name> (e.g. std/behaviors/std-stats) | almadar-behaviors/<name> (e.g. almadar-behaviors/rpg-hero); browse: @std/<topic>/<kind>/<name>.lolo (e.g. @std/ui/core/atoms/std-stats.lolo) | @behaviors/<topic>/<kind>/<name>.lolo (e.g. @behaviors/app/molecules/app-crud-manager.lolo)";
+var BROWSE_PREFIX_TO_PACKAGE = [
+  ["@std/", "std/behaviors/"],
+  ["@behaviors/", "almadar-behaviors/"]
+];
+function mapBrowseSpecifier(importPath) {
+  for (const [prefix, pkg] of BROWSE_PREFIX_TO_PACKAGE) {
+    if (!importPath.startsWith(prefix)) continue;
+    const rest = importPath.slice(prefix.length);
+    const basename2 = rest.slice(rest.lastIndexOf("/") + 1);
+    const name = basename2.endsWith(".lolo") ? basename2.slice(0, -".lolo".length) : basename2;
+    if (name.length === 0) return { kind: "malformed" };
+    return { kind: "mapped", canonical: `${pkg}${name}` };
+  }
+  return { kind: "not-browse-form" };
+}
 var ExternalOrbitalLoader = class {
   options;
   cache;
@@ -147,6 +163,16 @@ var ExternalOrbitalLoader = class {
    * Resolve an import path to an absolute filesystem path.
    */
   resolvePath(importPath, fromPath) {
+    const mapped = mapBrowseSpecifier(importPath);
+    if (mapped.kind === "malformed") {
+      return {
+        success: false,
+        error: `Unresolvable primitive import "${importPath}". ${BROWSE_FORM_HELP}`
+      };
+    }
+    if (mapped.kind === "mapped") {
+      importPath = mapped.canonical;
+    }
     if (importPath.startsWith("std/")) {
       return this.resolveStdPath(importPath);
     }
@@ -438,4 +464,4 @@ function autoDetectBehaviorsLibPaths(stdLibPath) {
   return found;
 }
 
-export { ExternalOrbitalLoader, ImportChain, LoaderCache, createLoader, parseImportPath };
+export { ExternalOrbitalLoader, ImportChain, LoaderCache, createLoader, mapBrowseSpecifier, parseImportPath };

package/dist/index.d.ts

@@ -1,14 +1,16 @@
-import { B as BindingContext, E as EvaluationContextExtensions, P as PatternProps, a as EffectHandlers, b as EffectContext, c as ExecutionEnvironment, d as EffectResult, T as TraitDefinition } from './types-D-9feVsj.js';
-export { e as Effect, f as EventListener, H as HANDLER_MANIFEST, I as IEventBus, R as RuntimeConfig, g as RuntimeEvent, h as TraitState, i as TransitionObserver, j as TransitionResult, U as Unsubscribe } from './types-D-9feVsj.js';
-import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital, P as PersistenceAdapter } from './OrbitalServerRuntime-DpAwIrmv.js';
-export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, e as InMemoryPersistence, O as OrbitalEventRequest, f as OrbitalEventResponse, g as OrbitalServerRuntimeConfig, h as PreprocessOptions, i as PreprocessResult, j as PreprocessedSchema, k as ProcessEventOptions, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, o as StateMachineManager, p as collectDeclaredConfigDefaults, q as collectDeclaredEntityDefaults, r as createInitialTraitState, s as findInitialState, t as findTransition, u as getIsolatedCollectionName, v as getNamespacedEvent, w as isBrowser, x as isElectron, y as isNamespacedEvent, z as isNode, A as normalizeCallSiteConfigToValues, B as normalizeEventKey, C as parseNamespacedEvent, D as preprocessSchema, F as processEvent } from './OrbitalServerRuntime-DpAwIrmv.js';
+import { B as BindingContext, f as EvaluationContextExtensions, P as PatternProps, E as EffectHandlers, g as EffectContext, h as ExecutionEnvironment, i as EffectResult, T as TraitDefinition } from './types-C8RsO0xa.js';
+export { j as BrowserFileMeta, k as BrowserFilePickerOptions, l as BrowserGeolocationOptions, m as BrowserGeolocationPosition, C as ConfigContext, n as Effect, a as EventListener, H as HANDLER_MANIFEST, I as IEventBus, b as RuntimeConfig, R as RuntimeEvent, d as TraitState, c as TransitionObserver, e as TransitionResult, U as Unsubscribe } from './types-C8RsO0xa.js';
+import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital, P as PersistenceAdapter } from './OrbitalServerRuntime-BrHSXDfp.js';
+export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, e as InMemoryPersistence, O as OrbitalEventRequest, f as OrbitalEventResponse, g as OrbitalServerRuntimeConfig, h as PreprocessOptions, i as PreprocessResult, j as PreprocessedSchema, k as ProcessEventOptions, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, o as StateMachineManager, p as collectDeclaredConfigDefaults, q as collectDeclaredEntityDefaults, r as createInitialTraitState, s as findInitialState, t as findTransition, u as getIsolatedCollectionName, v as getNamespacedEvent, w as isBrowser, x as isElectron, y as isNamespacedEvent, z as isNode, A as normalizeEventKey, B as parseNamespacedEvent, C as preprocessSchema, D as processEvent } from './OrbitalServerRuntime-BrHSXDfp.js';
 import { EvaluationContext, SExpressionEvaluator } from '@almadar/evaluator';
 export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
-import { EventPayload, EntityField, EntityRow, ServiceParams, PayloadField, OrbitalDefinition, OrbitalSchema } from '@almadar/core';
-export { EntityField } from '@almadar/core';
+import { TraitConfigObject, EventPayload, PatternConfig, EntityId, EntityField, EntityRow, ServiceParams, PayloadField, OrbitalDefinition, OrbitalSchema } from '@almadar/core';
+export { EntityField, normalizeCallSiteConfigToValues } from '@almadar/core';
 export { ServerBridgeConfig, ServerBridgeState } from './ServerBridge.js';
 export { OsHandlerContext, OsHandlerResult } from './createOsHandlers.js';
+export { MultiSourceSlotManager, PERF_NAMESPACE, PerfDetail, PerfDetailValue, PerfEntry, PreparedPreviewSchema, RendererContractViolationError, ResolvedPageTraits, SlotContent, SlotContentValidationError, SlotManager, SlotSource, VerificationBus, adjustSchemaForMockData, aggregateSlotContent, assertIsMultiSourceSlotManager, assertIsSlotManager, bindEventBus, bindTraitStateGetter, buildMockData, buildOrbitalsByTrait, clearPerf, collectEmbeddedTraits, collectTraitRefsFromResolvedTrait, createSlotSetter, ensureVerificationApi, getOrbitalVerification, perfEnd, perfStart, perfStore, perfTime, prepareSchemaForPreview, pushPerfEntry, validateSlotContent, wrapCallbackForEvent } from './ui/index.js';
 import 'express';
+import '@almadar/core/patterns';
 
 /**
  * Unified Schema Loader
@@ -242,6 +244,23 @@ declare function isValidDurationString(interval: string): boolean;
  * @packageDocumentation
  */
 
+/**
+ * Call-site payload capture grammar. Mirrors the Rust orbital-core
+ * `CALLSITE_PAYLOAD_PREFIX` (`@callsitePayload.`). A composed trait's call-site
+ * config value of this form is a snapshot of the COMPOSING effect's triggering
+ * event payload, captured at the call site — deliberately distinct from
+ * `@payload.` so it is never evaluated in the child's own INIT scope.
+ */
+declare const CALLSITE_PAYLOAD_PREFIX = "@callsitePayload.";
+/**
+ * Resolve call-site payload captures in a child trait's call-site config
+ * against the COMPOSING effect's triggering event payload. Each value of the
+ * form `@callsitePayload.<field>` becomes the literal read from `payload`
+ * (snapshot semantics — the child sees a plain value, never a payload ref).
+ * Non-capture entries pass through untouched. Returns a new object; the input
+ * is not mutated.
+ */
+declare function resolveCallSitePayloadCaptures(config: TraitConfigObject, payload: EventPayload | undefined): TraitConfigObject;
 /**
  * Interpolate binding references in props.
  *
@@ -448,7 +467,7 @@ interface ClientEventBus {
  */
 interface SlotSetter {
     /** Accumulate a pattern into the pending slot map */
-    addPattern: (slot: string, pattern: unknown, props?: PatternProps) => void;
+    addPattern: (slot: string, pattern: PatternConfig, props?: PatternProps) => void;
     /** Mark a slot for clearing */
     clearSlot: (slot: string) => void;
 }
@@ -504,10 +523,10 @@ interface CreateClientEffectHandlersOptions {
 declare function createClientEffectHandlers(options: CreateClientEffectHandlersOptions): EffectHandlers;
 
 /**
- * MockPersistenceAdapter - In-memory data store with faker-based mock generation
+ * MockPersistenceAdapter - In-memory data store with seeded mock generation
  *
  * Provides a stateful mock data layer that implements PersistenceAdapter.
- * Uses @faker-js/faker for realistic data generation based on field types.
+ * Uses a lightweight seeded PRNG so the client bundle does not pull in faker.
  *
  * @packageDocumentation
  */
@@ -521,8 +540,10 @@ type NamedEntityField = EntityField & {
 };
 interface EntitySchema {
     name: string;
+    /** V4 dual-carry id sibling of `name` — optional until the Phase-7 flip. */
+    id?: EntityId;
     fields: NamedEntityField[];
-    /** Pre-authored instance data from the schema (used instead of faker generation) */
+    /** Pre-authored instance data from the schema (used instead of generated mocks) */
     seedData?: EntityRow[];
 }
 interface MockPersistenceConfig {
@@ -534,17 +555,19 @@ interface MockPersistenceConfig {
     debug?: boolean;
 }
 /**
- * In-memory mock data store with CRUD operations and faker-based seeding.
+ * In-memory mock data store with CRUD operations and seeded mock generation.
  */
 declare class MockPersistenceAdapter implements PersistenceAdapter {
     private stores;
     private schemas;
     private idCounters;
+    /** entityId -> normalized store name, so relation lookups can prefer the id sibling over `relation.entity` name-matching. */
+    private storeNameById;
     private config;
     constructor(config?: MockPersistenceConfig);
-    /** Re-anchor faker's PRNG to the configured seed. Called before every
+    /** Re-anchor the PRNG to the configured seed. Called before every
      *  re-seed loop so identical reseed sequences produce identical rows
-     *  (timestamps + faker-generated fields). Without this, the first
+     *  (timestamps + generated fields). Without this, the first
      *  reseed produces row set A, the second produces row set B, and
      *  diff observers see all rows as "changed" between frames. */
     resetFakerSeed(): void;
@@ -553,7 +576,7 @@ declare class MockPersistenceAdapter implements PersistenceAdapter {
     /**
      * Register an entity schema and seed mock data.
      * If the schema has seedData, those instances are used directly.
-     * Otherwise, random mock data is generated with faker.
+     * Otherwise, random mock data is generated with the seeded PRNG.
      */
     registerEntity(schema: EntitySchema, seedCount?: number): void;
     /**
@@ -605,7 +628,7 @@ declare class MockPersistenceAdapter implements PersistenceAdapter {
     private generateArrayValue;
     /**
      * Generate a single object value with each declared property populated
-     * by faker. Walks `properties` and recursively delegates to
+     * by the seeded PRNG. Walks `properties` and recursively delegates to
      * `generateFieldValue` per property so nested objects-of-arrays-of-objects
      * compose correctly.
      */
@@ -613,7 +636,7 @@ declare class MockPersistenceAdapter implements PersistenceAdapter {
     /**
      * Generate a string value based on the field's declared schema metadata.
      * Reads `values` (enum) first, then `format` (email/url/phone/uuid/date/
-     * datetime), then falls back to faker.lorem.words. No field-name heuristics
+     * datetime), then falls back to randomWords. No field-name heuristics
      * — the schema is the source of truth. If a caller needs a real email, they
      * declare `format: "email"`; if they need an enum, they declare `values: [...]`.
      */
@@ -644,7 +667,7 @@ declare class MockPersistenceAdapter implements PersistenceAdapter {
      * Clear all data for an entity.
      */
     clear(entityName: string): void;
-    /** Clear all data + re-anchor faker so the next seed loop reproduces
+    /** Clear all data + re-anchor the PRNG so the next seed loop reproduces
      *  identical rows. Hermetic-frame mode calls this between every step
      *  via OrbitalServerRuntime.resetMockPersistence. */
     clearAll(): void;
@@ -942,8 +965,8 @@ declare function detectLayoutStrategy(orbitals: OrbitalDefinition[], eventWiring
 interface ComposeBehaviorsInput {
     /** Application name */
     appName: string;
-    /** Orbital definitions to compose */
-    orbitals: OrbitalDefinition[];
+    /** Orbital definitions (or schemas) to compose */
+    orbitals: (OrbitalDefinition | OrbitalSchema)[];
     /** Layout strategy override, or 'auto' to detect */
     layoutStrategy?: LayoutStrategy | 'auto';
     /** Cross-orbital event wiring */
@@ -1031,4 +1054,4 @@ declare namespace index {
   export { type index_ComposeBehaviorsInput as ComposeBehaviorsInput, type index_ComposeBehaviorsResult as ComposeBehaviorsResult, type index_EventWiringEntry as EventWiringEntry, type index_LayoutStrategy as LayoutStrategy, type index_PipeStep as PipeStep, index_applyEventWiring as applyEventWiring, index_composeBehaviors as composeBehaviors, index_detectLayoutStrategy as detectLayoutStrategy, index_pipeBehaviors as pipeBehaviors };
 }
 
-export { BindingContext, type ClientEventBus, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type CreateClientEffectHandlersOptions, type CreateServerEffectHandlersOptions, type CronFields, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntitySchema, type EventWiringEntry, ExecutionEnvironment, ImportChainLike, type LayoutStrategy, LoadResult, LoadedOrbital, LoadedSchema, MockPersistenceAdapter, type MockPersistenceConfig, type PayloadMismatch, type PayloadValidationFailure, PersistenceAdapter, type PipeStep, SchemaLoader, type ServerEffectResult, type SlotSetter, type TickHandle, TickScheduler, TraitDefinition, UnifiedLoaderOptions, applyEventWiring, buildEmitsFromTraits, composeBehaviors, index as composition, containsBindings, createClientEffectHandlers, createContextFromBindings, createMockPersistence, createServerEffectHandlers, createTestExecutor, createTickScheduler, createUnifiedLoader, cronMatches, cronMinuteKey, detectLayoutStrategy, extractBindings, formatPayloadValidationError, interpolateProps, interpolateValue, isValidCronExpression, isValidDurationString, parseCron, parseCronField, parseDurationString, pipeBehaviors, validateEventPayload, validatePayloadShapes };
+export { BindingContext, CALLSITE_PAYLOAD_PREFIX, type ClientEventBus, type ComposeBehaviorsInput, type ComposeBehaviorsResult, type CreateClientEffectHandlersOptions, type CreateServerEffectHandlersOptions, type CronFields, EffectContext, EffectExecutor, type EffectExecutorOptions, EffectHandlers, EffectResult, type EntitySchema, type EventWiringEntry, ExecutionEnvironment, ImportChainLike, type LayoutStrategy, LoadResult, LoadedOrbital, LoadedSchema, MockPersistenceAdapter, type MockPersistenceConfig, type PayloadMismatch, type PayloadValidationFailure, PersistenceAdapter, type PipeStep, SchemaLoader, type ServerEffectResult, type SlotSetter, type TickHandle, TickScheduler, TraitDefinition, UnifiedLoaderOptions, applyEventWiring, buildEmitsFromTraits, composeBehaviors, index as composition, containsBindings, createClientEffectHandlers, createContextFromBindings, createMockPersistence, createServerEffectHandlers, createTestExecutor, createTickScheduler, createUnifiedLoader, cronMatches, cronMinuteKey, detectLayoutStrategy, extractBindings, formatPayloadValidationError, interpolateProps, interpolateValue, isValidCronExpression, isValidDurationString, parseCron, parseCronField, parseDurationString, pipeBehaviors, resolveCallSitePayloadCaptures, validateEventPayload, validatePayloadShapes };

package/dist/index.js

@@ -1,6 +1,9 @@
-import { EffectExecutor, createContextFromBindings } from './chunk-YFH577FH.js';
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, extractBindings, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeCallSiteConfigToValues, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes } from './chunk-YFH577FH.js';
+import { EffectExecutor, createContextFromBindings } from './chunk-TRA44DDY.js';
+export { CALLSITE_PAYLOAD_PREFIX, EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, containsBindings, createContextFromBindings, createInitialTraitState, createMinimalContext, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, extractBindings, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, interpolateProps, interpolateValue, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeCallSiteConfigToValues, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, resolveCallSitePayloadCaptures, validateEventPayload, validatePayloadShapes } from './chunk-TRA44DDY.js';
 export { cronMatches, cronMinuteKey, isValidCronExpression, parseCron, parseCronField } from './chunk-OU3ITB5S.js';
+import './chunk-OQJIK6PZ.js';
+export { PERF_NAMESPACE, RendererContractViolationError, adjustSchemaForMockData, aggregateSlotContent, assertIsMultiSourceSlotManager, assertIsSlotManager, bindEventBus, bindTraitStateGetter, buildMockData, buildOrbitalsByTrait, clearPerf, createSlotSetter, ensureVerificationApi, getOrbitalVerification, perfEnd, perfStart, perfStore, perfTime, prepareSchemaForPreview, pushPerfEntry, validateSlotContent, wrapCallbackForEvent } from './chunk-O5VGKPTG.js';
+export { collectEmbeddedTraits, collectTraitRefsFromResolvedTrait } from './chunk-SCRAHWOC.js';
 import { __export } from './chunk-MLKGABMK.js';
 import { createLogger } from '@almadar/logger';
 import { evaluate } from '@almadar/evaluator';
@@ -87,7 +90,54 @@ function createClientEffectHandlers(options) {
     }),
     sendServer: sendServer ?? ((event, payload) => {
       sendServerEvent(orbitalName, event, payload);
-    })
+    }),
+    // === Browser device handlers (client host path) ===
+    // Each throws when the underlying API is unavailable so the executor's
+    // runSubstrate wrapper fires `emit.failure` with `{ error }`.
+    browserOpenFilePicker: async (options2) => {
+      if (typeof window === "undefined" || !("showOpenFilePicker" in window)) {
+        throw new Error("File picker API is not available in this environment");
+      }
+      const host = window;
+      const pickerOptions = {};
+      if (options2?.multiple === true) pickerOptions.multiple = true;
+      if (typeof options2?.accept === "string" && options2.accept.length > 0) {
+        pickerOptions.types = [{ accept: { [options2.accept]: [] } }];
+      }
+      const handles = await host.showOpenFilePicker(pickerOptions);
+      const files = await Promise.all(handles.map(async (handle) => {
+        const file = await handle.getFile();
+        return { name: file.name, size: file.size, type: file.type, lastModified: file.lastModified };
+      }));
+      return { files };
+    },
+    browserClipboardRead: async () => {
+      if (typeof navigator === "undefined" || !navigator.clipboard) {
+        throw new Error("Clipboard API is not available in this environment");
+      }
+      const text = await navigator.clipboard.readText();
+      return { text };
+    },
+    browserClipboardWrite: async (text) => {
+      if (typeof navigator === "undefined" || !navigator.clipboard) {
+        throw new Error("Clipboard API is not available in this environment");
+      }
+      await navigator.clipboard.writeText(text);
+      return { text };
+    },
+    browserGeolocationCurrent: async (options2) => {
+      if (typeof navigator === "undefined" || !navigator.geolocation) {
+        throw new Error("Geolocation API is not available in this environment");
+      }
+      const position = await new Promise((resolve, reject) => {
+        navigator.geolocation.getCurrentPosition(resolve, reject, options2);
+      });
+      return {
+        latitude: position.coords.latitude,
+        longitude: position.coords.longitude,
+        accuracy: position.coords.accuracy
+      };
+    }
   };
 }
 var effectLog = createLogger("almadar:runtime:effects");
@@ -669,6 +719,41 @@ function detectLayoutStrategy(orbitals, eventWiring) {
 }
 
 // src/composition/compose-behaviors.ts
+function isSchema(input) {
+  return "orbitals" in input && Array.isArray(input.orbitals);
+}
+function asDefinitions(inputs) {
+  return inputs.flatMap(
+    (input) => isSchema(input) ? input.orbitals : [input]
+  );
+}
+function mergeLedgers(inputs) {
+  const merged = /* @__PURE__ */ new Map();
+  let sawLedger = false;
+  for (const input of inputs) {
+    if (!isSchema(input) || input.ledger === void 0) continue;
+    sawLedger = true;
+    for (const [id, entry] of Object.entries(input.ledger.entries)) {
+      if (!merged.has(id)) merged.set(id, entry);
+    }
+  }
+  if (!sawLedger) return void 0;
+  const entries = {};
+  for (const [id, entry] of [...merged.entries()].sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  )) {
+    entries[id] = entry;
+  }
+  return { schemaVersion: 1, entries };
+}
+function mergeSchemaVersions(inputs) {
+  let max;
+  for (const input of inputs) {
+    if (!isSchema(input) || input.schemaVersion === void 0) continue;
+    max = max === void 0 ? input.schemaVersion : Math.max(max, input.schemaVersion);
+  }
+  return max;
+}
 function toKebabCase(name) {
   return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
 }
@@ -719,10 +804,11 @@ function getEntityName(orbital) {
 function composeBehaviors(input) {
   const {
     appName,
-    orbitals: rawOrbitals,
+    orbitals: rawInputs,
     layoutStrategy: strategyInput,
     eventWiring
   } = input;
+  const rawOrbitals = asDefinitions(rawInputs);
   const wiredOrbitals = eventWiring && eventWiring.length > 0 ? applyEventWiring(rawOrbitals, eventWiring) : rawOrbitals;
   const strategy = !strategyInput || strategyInput === "auto" ? detectLayoutStrategy(wiredOrbitals, eventWiring) : strategyInput;
   const pages = generatePages(wiredOrbitals, strategy);
@@ -736,10 +822,14 @@ function composeBehaviors(input) {
       pages: page ? [page] : []
     };
   });
+  const ledger = mergeLedgers(rawInputs);
+  const schemaVersion = mergeSchemaVersions(rawInputs);
   const schema = {
     name: appName,
     version: "1.0.0",
-    orbitals: orbitalsWithPages
+    orbitals: orbitalsWithPages,
+    ...schemaVersion !== void 0 ? { schemaVersion } : {},
+    ...ledger !== void 0 ? { ledger } : {}
   };
   return {
     schema,

package/dist/mockRandom.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lightweight seeded pseudo-random generator for mock data.
+ *
+ * Replaces @faker-js/faker in browser-facing code so the client bundle does
+ * not pay the ~3.7 MB faker cost. The API surface is intentionally narrow:
+ * only the helpers actually used by MockPersistenceAdapter.
+ */
+/** Re-seed the generator. Same signature as `faker.seed()`. */
+declare function seedRandom(value: number | undefined): void;
+/** Integer in [min, max]. */
+declare function randomInt({ min, max }: {
+    min: number;
+    max: number;
+}): number;
+/** Float in [min, max] with fixed fraction digits. */
+declare function randomFloat({ min, max, fractionDigits, }: {
+    min: number;
+    max: number;
+    fractionDigits?: number;
+}): number;
+/** True/false with 50% probability. */
+declare function randomBoolean(): boolean;
+/** Pick one element from an array. */
+declare function randomArrayElement<T>(array: ReadonlyArray<T>): T;
+/** Return a shallow-shuffled copy of the array (Fisher-Yates). */
+declare function shuffleArray<T>(array: ReadonlyArray<T>): T[];
+/** ISO-8601 date string roughly `years` in the past. */
+declare function randomPastDate({ years }?: {
+    years?: number;
+}): Date;
+/** ISO-8601 date string within the last `days`. */
+declare function randomRecentDate({ days }?: {
+    days?: number;
+}): Date;
+/** Any date in the last ~100 years. */
+declare function randomAnytimeDate(): Date;
+/** A few random words. */
+declare function randomWords(count: number): string;
+/** A short sentence. */
+declare function randomSentence(): string;
+/** UUID v4-like string (random, not strictly compliant). */
+declare function randomUuid(): string;
+/** Random hex color (#rrggbb). */
+declare function randomColor(): string;
+/** Random password of the given length. */
+declare function randomPassword(length?: number): string;
+/** Random email address. */
+declare function randomEmail(): string;
+/** Random URL. */
+declare function randomUrl(): string;
+/** Random phone number. */
+declare function randomPhone(): string;
+
+export { randomAnytimeDate, randomArrayElement, randomBoolean, randomColor, randomEmail, randomFloat, randomInt, randomPassword, randomPastDate, randomPhone, randomRecentDate, randomSentence, randomUrl, randomUuid, randomWords, seedRandom, shuffleArray };

package/dist/mockRandom.js

@@ -0,0 +1,2 @@
+export { randomAnytimeDate, randomArrayElement, randomBoolean, randomColor, randomEmail, randomFloat, randomInt, randomPassword, randomPastDate, randomPhone, randomRecentDate, randomSentence, randomUrl, randomUuid, randomWords, seedRandom, shuffleArray } from './chunk-OQJIK6PZ.js';
+import './chunk-MLKGABMK.js';

package/dist/{types-D-9feVsj.d.ts → types-C8RsO0xa.d.ts}

@@ -1,5 +1,5 @@
 import * as _almadar_core from '@almadar/core';
-import { SExpr, EventPayload, AgentContext, LlmContext, WorkspaceContext, SessionContext, MemoryContext, TraceContext, IntegrationContext, TraitConfig, BusEvent, EntityRow, FieldValue, ServiceParams, FetchResult, PatternConfig, ResolvedPatternProps, Orbital, ServiceCallResult, BusEventSource, BusEventListener, Unsubscribe as Unsubscribe$1 } from '@almadar/core';
+import { TraitId, EventId, SExpr, EventPayload, AgentContext, LlmContext, WorkspaceContext, SessionContext, MemoryContext, TraceContext, IntegrationContext, TraitConfig, BusEvent, EntityRow, FieldValue, ServiceParams, FetchResult, PatternConfig, ResolvedPatternProps, Orbital, ServiceCallResult, BusEventSource, BusEventListener, Unsubscribe as Unsubscribe$1 } from '@almadar/core';
 
 /** Alias for ResolvedPatternProps to avoid breaking internal consumers */
 type PatternProps = ResolvedPatternProps;
@@ -17,8 +17,9 @@ type Unsubscribe = Unsubscribe$1;
  * Event bus interface for pub/sub communication
  */
 interface IEventBus {
-    /** Emit an event */
-    emit(type: string, payload?: EventPayload, source?: BusEventSource): void;
+    /** Emit an event. `routingKey` (V4) keys delivery by event-id when the
+     *  schema carries ids; absent → keyed by `type` (name, legacy). */
+    emit(type: string, payload?: EventPayload, source?: BusEventSource, routingKey?: string): void;
     /** Subscribe to an event */
     on(type: string, listener: EventListener): Unsubscribe;
     /** Subscribe to ALL events (wildcard listener) */
@@ -70,6 +71,9 @@ interface TransitionResult {
  * Minimal trait definition for state machine processing
  */
 interface TraitDefinition {
+    /** V4 dual-carry id sibling of `name` — the stable state-machine lookup
+     *  key when present (ledger-backed). Absent → keyed by name (legacy). */
+    id?: TraitId;
     name: string;
     states: Array<{
         name: string;
@@ -79,6 +83,8 @@ interface TraitDefinition {
         from: string | string[];
         to: string;
         event: string;
+        /** V4 dual-carry id sibling of `event` — optional until the Phase-7 flip. */
+        eventId?: EventId;
         guard?: unknown;
         effects?: SExpr[];
         /** Compensating transition when effects fail (RCG-04) */
@@ -90,7 +96,11 @@ interface TraitDefinition {
     /** Cross-trait event listeners (optional) */
     listens?: Array<{
         event: string;
+        /** V4 dual-carry id sibling of `event` — optional until the Phase-7 flip. */
+        eventId?: EventId;
         triggers: string;
+        /** V4 dual-carry id sibling of `triggers` — optional until the Phase-7 flip. */
+        triggersId?: EventId;
         payloadMapping?: EventPayload;
     }>;
 }
@@ -221,6 +231,20 @@ interface EffectHandlers {
     osWatchEnv?: (variable: string, emit?: OsEmitConfig) => void;
     /** Configure debounce for an OS event type */
     osDebounce?: (ms: number, eventType: string) => void;
+    /** browser/open-file-picker — resolves with `{ files }` inside `result` */
+    browserOpenFilePicker?: (options?: BrowserFilePickerOptions) => Promise<{
+        files: BrowserFileMeta[];
+    }>;
+    /** browser/clipboard-read — resolves with `{ text }` inside `result` */
+    browserClipboardRead?: () => Promise<{
+        text: string;
+    }>;
+    /** browser/clipboard-write — resolves with `{ text }` (echo) inside `result` */
+    browserClipboardWrite?: (text: string) => Promise<{
+        text: string;
+    }>;
+    /** browser/geolocation-current — resolves with the position inside `result` */
+    browserGeolocationCurrent?: (options?: BrowserGeolocationOptions) => Promise<BrowserGeolocationPosition>;
     /** compose/compose-all — compose multiple orbitals into one schema */
     substrateComposeAll?: (config: {
         appName: string;
@@ -244,6 +268,32 @@ interface EffectHandlers {
  * operators meaningfully fire.
  */
 type OsEmitConfig = Pick<_almadar_core.EmitConfig, 'on_message' | 'failure'>;
+/** Options for `browser/open-file-picker`. */
+interface BrowserFilePickerOptions {
+    /** Allow selecting multiple files. */
+    multiple?: boolean;
+    /** MIME type filter (e.g. "image/*"). Best-effort; host may ignore. */
+    accept?: string;
+}
+/** Metadata for a file chosen via `browser/open-file-picker`. */
+interface BrowserFileMeta {
+    name: string;
+    size: number;
+    type: string;
+    lastModified: number;
+}
+/** Options for `browser/geolocation-current` (subset of PositionOptions). */
+interface BrowserGeolocationOptions {
+    enableHighAccuracy?: boolean;
+    timeout?: number;
+    maximumAge?: number;
+}
+/** Position returned by `browser/geolocation-current`. */
+interface BrowserGeolocationPosition {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+}
 /**
  * Context for resolving bindings like @entity.field, @payload.value
  */
@@ -393,4 +443,4 @@ interface TransitionObserver {
  */
 declare const HANDLER_MANIFEST: Record<ExecutionEnvironment, string[]>;
 
-export { type BindingContext as B, type ConfigContext as C, type EvaluationContextExtensions as E, HANDLER_MANIFEST as H, type IEventBus as I, type PatternProps as P, type RuntimeConfig as R, type TraitDefinition as T, type Unsubscribe as U, type EffectHandlers as a, type EffectContext as b, type ExecutionEnvironment as c, type EffectResult as d, type Effect as e, type EventListener as f, type RuntimeEvent as g, type TraitState as h, type TransitionObserver as i, type TransitionResult as j };
+export { type BindingContext as B, type ConfigContext as C, type EffectHandlers as E, HANDLER_MANIFEST as H, type IEventBus as I, type PatternProps as P, type RuntimeEvent as R, type TraitDefinition as T, type Unsubscribe as U, type EventListener as a, type RuntimeConfig as b, type TransitionObserver as c, type TraitState as d, type TransitionResult as e, type EvaluationContextExtensions as f, type EffectContext as g, type ExecutionEnvironment as h, type EffectResult as i, type BrowserFileMeta as j, type BrowserFilePickerOptions as k, type BrowserGeolocationOptions as l, type BrowserGeolocationPosition as m, type Effect as n };