@almadar/runtime 2.6.2 → 3.0.0

package/dist/{OrbitalServerRuntime-BlR7TM23.d.ts → OrbitalServerRuntime-QXgOGiS8.d.ts}

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { I as IEventBus, f as RuntimeEvent, e as EventListener, U as Unsubscribe, T as TraitDefinition, R as RuntimeConfig, h as TransitionObserver, g as TraitState, i as TransitionResult, E as EffectHandlers } from './types-DYcUvi4H.js';
+import { I as IEventBus, g as RuntimeEvent, f as EventListener, U as Unsubscribe, T as TraitDefinition, R as RuntimeConfig, i as TransitionObserver, h as TraitState, j as TransitionResult, E as EvaluationContextExtensions, a as EffectHandlers } from './types-CM6txTNy.js';
 import { EventPayload, EntityRow, OrbitalSchema, Orbital, Trait, OrbitalDefinition, Entity, TraitTick } from '@almadar/core';
 
 /**
@@ -126,6 +126,11 @@ interface ProcessEventOptions {
      * When true, log warnings when bindings resolve to undefined. (RCG-01)
      */
     strictBindings?: boolean;
+    /**
+     * Additional fields to spread onto EvaluationContext for guard evaluation.
+     * Used to inject module contexts (e.g., { agent: AgentContext }).
+     */
+    contextExtensions?: EvaluationContextExtensions;
 }
 /**
  * Process an event through a trait's state machine.
@@ -238,6 +243,48 @@ declare class StateMachineManager {
     resetAll(): void;
 }
 
+/**
+ * LocalPersistenceAdapter - Filesystem CRUD for `persistence: "local"` entities.
+ *
+ * One directory per entity type, one JSON file per instance.
+ * Language-level feature: benefits all .orb programs, not just the agent.
+ * Offline-first apps, CLI tools, config managers, local databases all use it.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Filesystem-backed persistence adapter.
+ *
+ * Storage layout:
+ * ```
+ * {root}/
+ *   {entityType}/
+ *     {id}.json
+ * ```
+ */
+declare class LocalPersistenceAdapter implements PersistenceAdapter {
+    private readonly root;
+    constructor(root: string);
+    private entityDir;
+    private filePath;
+    create(entityType: string, data: EntityRow): Promise<{
+        id: string;
+    }>;
+    update(entityType: string, id: string, data: EntityRow): Promise<void>;
+    delete(entityType: string, id: string): Promise<void>;
+    getById(entityType: string, id: string): Promise<EntityRow | null>;
+    list(entityType: string): Promise<EntityRow[]>;
+    /**
+     * Remove all data for an entity type.
+     */
+    clear(entityType: string): Promise<void>;
+    /**
+     * Remove all local data.
+     */
+    clearAll(): Promise<void>;
+}
+
 /**
  * External Orbital Loader
  *
@@ -702,6 +749,17 @@ interface OrbitalServerRuntimeConfig {
      * Default: true
      */
     namespaceEvents?: boolean;
+    /**
+     * Root directory for `persistence: "local"` entities.
+     * Default: ~/.orb/data/
+     */
+    localStorageRoot?: string;
+    /**
+     * Additional fields to spread onto every EvaluationContext.
+     * Use this to inject module contexts (e.g., { agent: AgentContext }).
+     * The evaluator dispatches agent/* operators to ctx.agent.
+     */
+    contextExtensions?: EvaluationContextExtensions;
 }
 /**
  * Adapter for persisting entity data
@@ -727,6 +785,7 @@ declare class OrbitalServerRuntime {
     private entitySharingMap;
     private eventNamespaceMap;
     private osHandlers;
+    private localPersistence;
     constructor(config?: OrbitalServerRuntimeConfig);
     /**
      * Register an OrbitalSchema for execution.
@@ -906,4 +965,4 @@ declare class OrbitalServerRuntime {
  */
 declare function createOrbitalServerRuntime(config?: OrbitalServerRuntimeConfig): OrbitalServerRuntime;
 
-export { type EntitySharingMap as E, type LoaderConfig as L, type OrbitalEventRequest as O, type PersistenceAdapter as P, type RegisteredOrbital as R, StateMachineManager as S, EventBus as a, type EventNamespaceMap as b, type OrbitalEventResponse as c, type OrbitalServerRuntimeConfig as d, type PreprocessOptions as e, type PreprocessResult as f, type PreprocessedSchema as g, type ProcessEventOptions as h, type RuntimeOrbital as i, type RuntimeOrbitalSchema as j, type RuntimeTrait as k, createInitialTraitState as l, findInitialState as m, findTransition as n, getIsolatedCollectionName as o, getNamespacedEvent as p, isNamespacedEvent as q, normalizeEventKey as r, parseNamespacedEvent as s, preprocessSchema as t, processEvent as u, type EffectResult as v, OrbitalServerRuntime as w, type RuntimeTraitTick as x, createOrbitalServerRuntime as y };
+export { type EntitySharingMap as E, type LoaderConfig as L, type OrbitalEventRequest as O, type PersistenceAdapter as P, type RegisteredOrbital as R, StateMachineManager as S, EventBus as a, type EventNamespaceMap as b, type OrbitalEventResponse as c, type OrbitalServerRuntimeConfig as d, type PreprocessOptions as e, type PreprocessResult as f, type PreprocessedSchema as g, type ProcessEventOptions as h, type RuntimeOrbital as i, type RuntimeOrbitalSchema as j, type RuntimeTrait as k, createInitialTraitState as l, findInitialState as m, findTransition as n, getIsolatedCollectionName as o, getNamespacedEvent as p, isNamespacedEvent as q, normalizeEventKey as r, parseNamespacedEvent as s, preprocessSchema as t, processEvent as u, type EffectResult as v, LocalPersistenceAdapter as w, OrbitalServerRuntime as x, type RuntimeTraitTick as y, createOrbitalServerRuntime as z };

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { v as EffectResult, L as LoaderConfig, O as OrbitalEventRequest, c as OrbitalEventResponse, w as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, x as RuntimeTraitTick, y as createOrbitalServerRuntime } from './OrbitalServerRuntime-BlR7TM23.js';
-import './types-DYcUvi4H.js';
+export { v as EffectResult, L as LoaderConfig, w as LocalPersistenceAdapter, O as OrbitalEventRequest, c as OrbitalEventResponse, x as OrbitalServerRuntime, d as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, i as RuntimeOrbital, j as RuntimeOrbitalSchema, k as RuntimeTrait, y as RuntimeTraitTick, z as createOrbitalServerRuntime } from './OrbitalServerRuntime-QXgOGiS8.js';
+import './types-CM6txTNy.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,12 +1,86 @@
-import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-ESNML4B4.js';
+import { EventBus, createUnifiedLoader, preprocessSchema, StateMachineManager, createContextFromBindings, EffectExecutor } from './chunk-HIM4HJAN.js';
+import './chunk-PZ5AY32C.js';
 import { Router } from 'express';
+import * as fs from 'fs';
+import fs__default from 'fs';
+import path from 'path';
 import { evaluateGuard, evaluate } from '@almadar/evaluator';
-import { isInlineTrait } from '@almadar/core';
+import { isInlineTrait, isEntityCall } from '@almadar/core';
 import { faker } from '@faker-js/faker';
-import * as fs from 'fs';
 import * as net from 'net';
 import { execSync } from 'child_process';
 
+var LocalPersistenceAdapter = class {
+  root;
+  constructor(root) {
+    this.root = root;
+    fs__default.mkdirSync(root, { recursive: true });
+  }
+  entityDir(entityType) {
+    const dir = path.join(this.root, entityType.toLowerCase());
+    fs__default.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+  filePath(entityType, id) {
+    return path.join(this.entityDir(entityType), `${id}.json`);
+  }
+  async create(entityType, data) {
+    const id = data.id || `${entityType.toLowerCase()}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const record = { ...data, id };
+    const filePath = this.filePath(entityType, id);
+    fs__default.writeFileSync(filePath, JSON.stringify(record, null, 2), "utf-8");
+    return { id };
+  }
+  async update(entityType, id, data) {
+    const filePath = this.filePath(entityType, id);
+    let existing = { id };
+    if (fs__default.existsSync(filePath)) {
+      existing = JSON.parse(fs__default.readFileSync(filePath, "utf-8"));
+    }
+    const merged = { ...existing, ...data, id };
+    fs__default.writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf-8");
+  }
+  async delete(entityType, id) {
+    const filePath = this.filePath(entityType, id);
+    if (fs__default.existsSync(filePath)) {
+      fs__default.unlinkSync(filePath);
+    }
+  }
+  async getById(entityType, id) {
+    const filePath = this.filePath(entityType, id);
+    if (!fs__default.existsSync(filePath)) return null;
+    return JSON.parse(fs__default.readFileSync(filePath, "utf-8"));
+  }
+  async list(entityType) {
+    const dir = this.entityDir(entityType);
+    if (!fs__default.existsSync(dir)) return [];
+    const files = fs__default.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    const results = [];
+    for (const file of files) {
+      const content = fs__default.readFileSync(path.join(dir, file), "utf-8");
+      results.push(JSON.parse(content));
+    }
+    return results;
+  }
+  /**
+   * Remove all data for an entity type.
+   */
+  async clear(entityType) {
+    const dir = path.join(this.root, entityType.toLowerCase());
+    if (fs__default.existsSync(dir)) {
+      fs__default.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+  /**
+   * Remove all local data.
+   */
+  async clearAll() {
+    if (fs__default.existsSync(this.root)) {
+      fs__default.rmSync(this.root, { recursive: true, force: true });
+      fs__default.mkdirSync(this.root, { recursive: true });
+    }
+  }
+};
 var MockPersistenceAdapter = class {
   stores = /* @__PURE__ */ new Map();
   schemas = /* @__PURE__ */ new Map();
@@ -563,6 +637,7 @@ var OrbitalServerRuntime = class {
   entitySharingMap = {};
   eventNamespaceMap = {};
   osHandlers = null;
+  localPersistence = null;
   constructor(config = {}) {
     this.config = {
       mode: "mock",
@@ -591,6 +666,9 @@ var OrbitalServerRuntime = class {
     } else {
       this.persistence = config.persistence || new InMemoryPersistence();
     }
+    if (config.localStorageRoot) {
+      this.localPersistence = new LocalPersistenceAdapter(config.localStorageRoot);
+    }
     this.osHandlers = createOsHandlers({
       emitEvent: (type, payload) => this.eventBus.emit(type, payload)
     });
@@ -757,9 +835,24 @@ var OrbitalServerRuntime = class {
         listens: t.listens
       };
     });
-    const manager = new StateMachineManager(traitDefs);
+    const manager = new StateMachineManager(traitDefs, {
+      contextExtensions: this.config.contextExtensions
+    });
     const entityRef = orbital.entity;
-    const entity = typeof entityRef === "string" ? { name: entityRef, fields: [] } : entityRef;
+    let entity;
+    if (typeof entityRef === "string") {
+      entity = { name: entityRef, fields: [] };
+    } else if (isEntityCall(entityRef)) {
+      const fallbackName = entityRef.name ?? entityRef.extends.replace(/\.entity$/, "");
+      entity = {
+        name: fallbackName,
+        fields: entityRef.fields ?? [],
+        ...entityRef.persistence ? { persistence: entityRef.persistence } : {},
+        ...entityRef.collection ? { collection: entityRef.collection } : {}
+      };
+    } else {
+      entity = entityRef;
+    }
     this.orbitals.set(orbital.name, {
       schema: orbital,
       entity,
@@ -957,7 +1050,7 @@ var OrbitalServerRuntime = class {
               entity,
               payload: {},
               state: registered.manager.getState(traitName)?.currentState || "unknown"
-            });
+            }, false, this.config.contextExtensions);
             const guardPasses = evaluateGuard(
               tick.guard,
               ctx
@@ -1434,7 +1527,7 @@ var OrbitalServerRuntime = class {
             current,
             entity: entityData,
             payload
-          });
+          }, false, this.config.contextExtensions);
           let newData;
           if (Array.isArray(transform)) {
             const result = evaluate(
@@ -1487,7 +1580,8 @@ var OrbitalServerRuntime = class {
           handlers,
           bindings: bindingsRef ?? {},
           context: contextRef ?? { traitName, state: "unknown", transition: "unknown" },
-          debug: this.config.debug
+          debug: this.config.debug,
+          contextExtensions: this.config.contextExtensions
         });
         for (const innerEffect of atomicEffects) {
           if (atomicFailed) break;
@@ -1516,8 +1610,8 @@ var OrbitalServerRuntime = class {
       renderUI: (slot, pattern, props, priority) => {
         clientEffects.push(["render-ui", slot, pattern, props, priority]);
       },
-      navigate: (path, params) => {
-        clientEffects.push(["navigate", path, params]);
+      navigate: (path2, params) => {
+        clientEffects.push(["navigate", path2, params]);
       },
       notify: (message, type) => {
         if (this.config.debug) {
@@ -1555,7 +1649,8 @@ var OrbitalServerRuntime = class {
       handlers,
       bindings,
       context,
-      debug: this.config.debug
+      debug: this.config.debug,
+      contextExtensions: this.config.contextExtensions
     });
     await executor.executeAll(effects);
   }
@@ -1891,6 +1986,6 @@ function createOrbitalServerRuntime(config) {
   return new OrbitalServerRuntime(config);
 }
 
-export { OrbitalServerRuntime, createOrbitalServerRuntime };
+export { LocalPersistenceAdapter, OrbitalServerRuntime, createOrbitalServerRuntime };
 //# sourceMappingURL=OrbitalServerRuntime.js.map
 //# sourceMappingURL=OrbitalServerRuntime.js.map