@alneas/eaos-server 0.0.0-stage → 0.1.0

package/dist/agentic/event-bridge.d.ts

@@ -0,0 +1,344 @@
+import { DomainEventBus } from '@alneas/eaos-core';
+import { ServerAutonomousWorker } from './autonomous-worker.js';
+import { ServerAgentTaskRequest, ServerAgentTaskResult } from './types.js';
+
+/**
+ * Maps one domain event name to a verified host task specification.
+ * @see EventAgentBridge.registerRule.
+ */
+interface EventAgentRule {
+    /** Exact domain event name to subscribe to. */
+    eventName: string;
+    /** Filter or build task request from domain event payload. Return null to skip. */
+    createTask: (payload: unknown) => Omit<ServerAgentTaskRequest, 'id'> | null;
+}
+/**
+ * Host error/audit notification for event conversion, queueing, execution, result, or approval delivery.
+ * @see EventAgentBridgeOptions.onError.
+ */
+interface EventAgentBridgeError {
+    /** Domain event associated with the failure. */
+    eventName: string;
+    /** Optional generated task identifier, absent before task creation. */
+    taskId?: string;
+    /** Stage where the failure was observed. */
+    phase: 'createTask' | 'queue' | 'runTask' | 'result' | 'notification';
+    /** Original failure value, which may not be an Error. */
+    error: unknown;
+    /** Optional normalized task result associated with the failure. */
+    result?: ServerAgentTaskResult;
+}
+/**
+ * Event, generated task, and pending result delivered to the host approval sink.
+ * @see EventAgentBridgeOptions.onPendingApproval.
+ */
+interface EventAgentPendingApproval {
+    /** Originating domain event name. */
+    eventName: string;
+    /** Original event payload (cloned when durable queue mode is used). */
+    payload: unknown;
+    /** Generated verified task whose runtime requested approval. */
+    task: ServerAgentTaskRequest;
+    /** PENDING_APPROVAL result; the host must persist/deliver the approval request. */
+    result: ServerAgentTaskResult;
+}
+/**
+ * In-process backpressure, host notifications, and optional durable delivery for {@link EventAgentBridge}.
+ */
+interface EventAgentBridgeOptions {
+    /** In-process worker concurrency, safe integer 1–1024. Defaults to 1; durable run passes use this as their claim ceiling but are not globally serialized. */
+    maxConcurrent?: number;
+    /** In-process waiting queue ceiling while workers are fully occupied, safe integer 0–1000000. Defaults to 100. */
+    maxQueueSize?: number;
+    /** Host-owned notification/audit sink for approval requests. */
+    onPendingApproval?: (pending: EventAgentPendingApproval) => Promise<void> | void;
+    /** Host error/audit sink; returned Promise rejection is logged. Keep the callback itself nonthrowing because synchronous errors can escape reporting. */
+    onError?: (error: EventAgentBridgeError) => Promise<void> | void;
+    /** Optional host-owned durable queue. When set, events are persisted until runDurableOnce drains them. */
+    taskStore?: EventAgentTaskStore;
+}
+/**
+ * Domain event and generated task stored as one event queue item.
+ * @see EventAgentTaskStore.
+ */
+interface QueuedEventTask {
+    /** Originating subscribed event name. */
+    eventName: string;
+    /** Associated event payload; durable enqueue receives a structured clone. */
+    payload: unknown;
+    /** Generated task with ID and execution idempotency context. */
+    task: ServerAgentTaskRequest;
+}
+/** Host-owned durable queue for event-triggered agent work.
+ * @see EventAgentBridge.withDurableTaskStore for usage.
+ */
+interface EventAgentTaskStore {
+    /**
+     * Persists accepted event work before a scheduler drains it.
+     * @param task - Verified generated task and cloneable event payload.
+     * @returns No value; resolves after host persistence.
+     * @throws Queue failures propagate to bridge error reporting.
+     
+     * @example
+     * ```typescript
+     * import type { EventAgentTaskStore } from "@alneas/eaos-server";
+     * export async function enqueueAdmittedEventTask(
+     *   store: EventAgentTaskStore, task: Parameters<EventAgentTaskStore["enqueue"]>[0],
+     * ) {
+     *   // Host admission and the event-to-task mapping run before queue insertion.
+     *   await store.enqueue(task);
+     * }
+     * ```
+     */
+    enqueue(task: QueuedEventTask): Promise<void>;
+    /**
+     * Exclusively claims work for one drain pass.
+     * @param limit - Requested maximum item count.
+     * @returns Claimed queue items, or an empty array.
+     * @throws Queue failures reject the drain pass.
+     
+     * @example
+     * ```typescript
+     * import type { EventAgentTaskStore } from "@alneas/eaos-server";
+     * export async function claimEventTasks(store: EventAgentTaskStore) {
+     *   const tasks = await store.claim(10);
+     *   return tasks; // Empty when no eligible tasks are available.
+     * }
+     * ```
+     */
+    claim(limit: number): Promise<readonly QueuedEventTask[]>;
+    /**
+     * Persists the normalized result for a claimed task.
+     * @param taskId - Claimed task identifier.
+     * @param result - Runtime outcome, including failed/pending statuses.
+     * @returns No value; resolves after persistence.
+     * @throws Completion failure causes the bridge to call fail.
+     
+     * @example
+     * ```typescript
+     * import type { EventAgentTaskStore } from "@alneas/eaos-server";
+     * export async function completeEventTask(
+     *   store: EventAgentTaskStore, claimedTaskId: string,
+     *   result: Parameters<EventAgentTaskStore["complete"]>[1],
+     * ) {
+     *   await store.complete(claimedTaskId, result);
+     *   // The host decides persistence and result retention for this queue.
+     * }
+     * ```
+     */
+    complete(taskId: string, result: ServerAgentTaskResult): Promise<void>;
+    /**
+     * Records or handles a claimed execution/persistence failure.
+     * @param taskId - Claimed task identifier.
+     * @param error - Underlying execution or completion failure.
+     * @returns No value; completion/retry semantics belong to the host store.
+     * @throws Failures reject the drain pass.
+     
+     * @example
+     * ```typescript
+     * import type { EventAgentTaskStore } from "@alneas/eaos-server";
+     * export async function recordEventTaskFailure(
+     *   store: EventAgentTaskStore, claimedTaskId: string, observedError: unknown,
+     * ) {
+     *   await store.fail(claimedTaskId, observedError);
+     *   // Failure/retry policy belongs to the host store; this does not retry execution.
+     * }
+     * ```
+     */
+    fail(taskId: string, error: unknown): Promise<void>;
+}
+/**
+ * Small process-local TaskStore for development, tests and a single short-
+ * lived host. It deliberately has no lease recovery or persistence and must
+ * not be used as the production workflow/checkpoint store.
+ * @remarks Duplicate IDs compare JSON serialization exactly. Completed history/results are retained without the active-task capacity limit. No retry, lease recovery, or durable failure history exists.
+ * @example
+ * ```typescript
+ * import { InMemoryEventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+ * const store = new InMemoryEventAgentTaskStore();
+ * console.log(await store.claim(1)); // []
+ * ```
+ */
+declare class InMemoryEventAgentTaskStore implements EventAgentTaskStore {
+    private readonly pending;
+    private readonly claimed;
+    private readonly completed;
+    private readonly results;
+    private readonly maxTasks;
+    /**
+     * Creates an empty local queue with an active pending/claimed capacity limit.
+     * @param options - maxTasks defaults to 10000 and must be a safe integer 1–1000000.
+     * @throws Invalid capacity.
+     */
+    constructor(options?: {
+        /**
+         * Maximum pending plus claimed tasks retained at once; defaults to 10000 and must be a safe integer from 1 to 1000000. Completed history/results are outside this limit.
+         */
+        maxTasks?: number;
+    });
+    /**
+     * Clones a queued task unless its ID is already identically retained.
+     * @param task - Nonempty task ID and event name with structured-cloneable payload/task.
+     * @returns No value; resolves after local insertion or matching duplicate detection.
+     * @throws Missing identifiers, conflicting duplicate, active capacity exhaustion, or clone/JSON failure.
+     * @example
+     * ```typescript
+     * import { InMemoryEventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+     * import type { QueuedEventTask } from "@alneas/eaos-server/agentic/event-bridge";
+     * export async function enqueue(store: InMemoryEventAgentTaskStore, task: QueuedEventTask) { await store.enqueue(task); }
+     * ```
+     */
+    enqueue(task: QueuedEventTask): Promise<void>;
+    /**
+     * Moves pending items into the claimed map in insertion order.
+     * @param limit - Positive safe-integer maximum item count.
+     * @returns Cloned claimed items, or an empty array.
+     * @throws Invalid limit or clone failure; an item may already have moved before clone failure.
+     * @example
+     * ```typescript
+     * import { InMemoryEventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+     * const store = new InMemoryEventAgentTaskStore();
+     * console.log(await store.claim(1)); // []
+     * ```
+     */
+    claim(limit: number): Promise<readonly QueuedEventTask[]>;
+    /**
+     * Moves a claimed task into retained completion history and clones its result.
+     * @param taskId - Current claimed task identifier.
+     * @param result - Normalized runtime outcome, including FAILED or PENDING_APPROVAL data.
+     * @returns No value; completes after retaining history and result.
+     * @throws Unknown/already completed task or clone failure; history can already have changed.
+     * @example
+     * ```typescript
+     * import { InMemoryEventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+     * import type { ServerAgentTaskResult } from "@alneas/eaos-server/agentic/types";
+     * export async function complete(store: InMemoryEventAgentTaskStore, taskId: string, result: ServerAgentTaskResult) { await store.complete(taskId, result); }
+     * ```
+     */
+    complete(taskId: string, result: ServerAgentTaskResult): Promise<void>;
+    /**
+     * Removes a claimed task without retaining failure history or rescheduling it.
+     * @param taskId - Current claimed task identifier.
+     * @param _error - Failure value accepted for interface compatibility and ignored.
+     * @returns No value; resolves after removal.
+     * @throws Unknown/already failed task.
+     * @example
+     * ```typescript
+     * import { InMemoryEventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+     * export async function fail(store: InMemoryEventAgentTaskStore, taskId: string, error: unknown) { await store.fail(taskId, error); }
+     * ```
+     */
+    fail(taskId: string, _error: unknown): Promise<void>;
+    /**
+   * Inspects a cloned retained completion result for local tests/development.
+   * @param taskId - Previously completed task identifier.
+   * @returns Cloned result, or undefined if no completion result exists.
+   * @throws If a retained result cannot be cloned.
+   * @example
+   * ```typescript
+   * import { InMemoryEventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+   * console.log(new InMemoryEventAgentTaskStore().getResult("missing")); // undefined
+   * ```
+   */
+    getResult(taskId: string): ServerAgentTaskResult | undefined;
+}
+/**
+ * Converts subscribed domain events into bounded local execution or host-persisted agent work.
+ * @remarks Without taskStore, accepted work is process-local and can be lost on restart. With taskStore, the host explicitly calls runDurableOnce; event subscription callbacks still do not await durable persistence from the publisher's perspective. Authorize identity in createTask before creating specifications. Generated task IDs/idempotency defaults are per emission, so repeated events are not automatically deduplicated. Dispose every registerRule callback to release subscriptions; no global destroy is provided.
+ * @example
+ * ```typescript
+ * import { EventAgentBridge } from "@alneas/eaos-server/agentic/event-bridge";
+ * import type { DomainEventBus } from "@alneas/eaos-core";
+ * import type { ServerAutonomousWorker } from "@alneas/eaos-server/agentic/autonomous-worker";
+ * export function bridge(eventBus: DomainEventBus, worker: ServerAutonomousWorker) { return new EventAgentBridge(eventBus, worker); }
+ * ```
+ */
+declare class EventAgentBridge {
+    private eventBus;
+    private worker;
+    private rules;
+    private subscriptions;
+    private queue;
+    private activeCount;
+    private readonly maxConcurrent;
+    private readonly maxQueueSize;
+    private readonly onPendingApproval?;
+    private readonly onError?;
+    private taskStore?;
+    private taskCounter;
+    /**
+     * Captures an event bus and worker and validates local backpressure limits.
+     * @param eventBus - Host domain bus; subscriptions begin only on registerRule.
+     * @param worker - Host worker performing gatekeeper/runtime execution.
+     * @param options - Queue limits, notification/error callbacks, and optional durable store.
+     * @throws Invalid limits or malformed durable store.
+     */
+    constructor(eventBus: DomainEventBus, worker: ServerAutonomousWorker, options?: EventAgentBridgeOptions);
+    /**
+     * Persisted event work is deliberately drained by the host scheduler. The
+     * bridge never treats its in-memory queue as a durable workflow checkpoint.
+     * @param store - Host durable queue with enqueue/claim/complete/fail functions.
+     * @returns This bridge after replacing its store reference.
+     * @throws Missing/malformed store functions.
+     * @remarks Existing local queued work is not migrated by changing this store.
+     * @example
+     * ```typescript
+     * import { EventAgentBridge } from "@alneas/eaos-server/agentic/event-bridge";
+     * import type { EventAgentTaskStore } from "@alneas/eaos-server/agentic/event-bridge";
+     * export function persist(bridge: EventAgentBridge, store: EventAgentTaskStore) { return bridge.withDurableTaskStore(store); }
+     * ```
+     */
+    withDurableTaskStore(store: EventAgentTaskStore): this;
+    /**
+     * Claims one bounded durable batch and processes it sequentially.
+     * @param limit - Safe integer 1–maxConcurrent; defaults to maxConcurrent.
+     * @returns Claim/completion/failure persistence counts; a worker FAILED result counts completed if stored successfully.
+     * @throws Missing store, invalid limit, claim/fail persistence errors, or synchronous error-sink errors.
+     * @remarks Calls are not globally serialized. Notification failures are reported after result persistence. No periodic scheduler or automatic retry is installed.
+     * @example
+     * ```typescript
+     * import { EventAgentBridge } from "@alneas/eaos-server/agentic/event-bridge";
+     * export async function drain(bridge: EventAgentBridge) { return bridge.runDurableOnce(); }
+     * ```
+     */
+    runDurableOnce(limit?: number): Promise<{
+        /** Number of queued tasks returned by the host claim for this pass, including tasks later recorded as completed or failed. */
+        claimed: number;
+        /** Number of task results successfully passed to store.complete; a returned worker FAILED or PENDING_APPROVAL status still counts when its result is stored. */
+        completed: number;
+        /** Number of worker throws or store.complete failures handled through store.fail; this counts persistence/execution handling failures rather than every returned worker FAILED status. */
+        failed: number;
+    }>;
+    /**
+     * Subscribes a task-conversion rule and returns its individual unsubscribe callback.
+     * @param rule - Exact event name and synchronous createTask callback; callback receives payload and returns verified task fields or null to skip.
+     * @returns A no-argument callback returning no value; removes this rule and unsubscribes the bus handler when no rules remain.
+     * @throws Event bus subscription/unsubscription errors can propagate. Event conversion errors are reported through onError.
+     * @remarks The rule is retained by reference; do not mutate its eventName after registration. Already accepted tasks keep running after unsubscribe.
+     * @example
+     * ```typescript
+     * import { EventAgentBridge } from "@alneas/eaos-server/agentic/event-bridge";
+     * import type { EventAgentRule } from "@alneas/eaos-server/agentic/event-bridge";
+     * export function listen(bridge: EventAgentBridge, rule: EventAgentRule) { return bridge.registerRule(rule); }
+     * ```
+     */
+    registerRule(rule: EventAgentRule): () => void;
+    /**
+   * Waits until the bridge's local active count and waiting queue are empty.
+   * @returns No value; resolves when local work is idle. It does not wait for durable queue persistence/draining or asynchronous error sinks.
+   * @remarks Polls with zero-delay timers and has no timeout/cancellation; continuously arriving work can delay completion indefinitely.
+   * @example
+   * ```typescript
+   * import { EventAgentBridge } from "@alneas/eaos-server/agentic/event-bridge";
+   * export async function idle(bridge: EventAgentBridge) { await bridge.whenIdle(); }
+   * ```
+   */
+    whenIdle(): Promise<void>;
+    private handleEvent;
+    private drain;
+    private execute;
+    private reportError;
+}
+
+export { EventAgentBridge, InMemoryEventAgentTaskStore };
+export type { EventAgentBridgeError, EventAgentBridgeOptions, EventAgentPendingApproval, EventAgentRule, EventAgentTaskStore, QueuedEventTask };

package/dist/agentic/event-bridge.js

@@ -0,0 +1,9 @@
+import {
+  EventAgentBridge,
+  InMemoryEventAgentTaskStore
+} from "../chunk-3P4XTTQH.js";
+export {
+  EventAgentBridge,
+  InMemoryEventAgentTaskStore
+};
+//# sourceMappingURL=event-bridge.js.map

package/dist/agentic/event-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/executor.d.ts

@@ -0,0 +1,91 @@
+import { AgentRuntimeResourcePolicy } from '@alneas/eaos-core';
+import { ServerAgentTaskRequest, ServerAgentExecutor } from './types.js';
+
+/**
+ * Chooses Linux systemd-run, direct spawning, or automatic platform selection.
+ * @see createCommandAgentExecutor.
+ */
+type CommandAgentSandboxMode = 'auto' | 'systemd' | 'direct';
+/**
+ * Host sandbox selection for {@link createCommandAgentExecutor}.
+ */
+interface CommandAgentSandboxOptions {
+    /** auto uses transient systemd on Linux and direct execution on local development hosts. */
+    mode?: CommandAgentSandboxMode;
+    /** Resource policy is framework-owned by default; consumers may only tighten it in a host adapter. */
+    policy?: AgentRuntimeResourcePolicy;
+}
+/**
+ * Trusted executable, argument/environment builders, and limits for {@link createCommandAgentExecutor}.
+ */
+interface CommandAgentExecutorOptions {
+    /** Host-configured executable. It is never taken from a task request. */
+    command: string;
+    /** Called once per task with a structured clone; must return string arguments. Arguments are passed without a shell, and callback errors reject execution. */
+    buildArgs: (request: ServerAgentTaskRequest) => readonly string[];
+    /** Process working directory; omitted uses the host process directory. Under systemd this directory is also explicitly writable. */
+    cwd?: string;
+    /** Per-task environment callback receiving a clone; its entries override framework EAOS variables. Defaults to no additional variables. */
+    env?: (request: ServerAgentTaskRequest) => Record<string, string | undefined>;
+    /** Inherit host process environment before framework/custom variables. @defaultValue false */
+    includeProcessEnv?: boolean;
+    /** Default task timeout in milliseconds, safe integer 1–3600000; task.timeoutMs overrides it. @defaultValue 60000 */
+    timeoutMs?: number;
+    /** Combined stdout/stderr string-length ceiling, safe integer 1–10000000. @defaultValue 1000000 */
+    maxOutputChars?: number;
+    /** Sandbox selection; defaults to auto and a validated task/framework policy. Direct mode does not apply systemd resource/filesystem restrictions. */
+    sandbox?: CommandAgentSandboxOptions;
+}
+/**
+ * Validates that resource-policy fields retain or tighten the current framework baseline.
+ * @param policy - Runtime resource policy with AI placement, read-only root, private-only network, and bounded resources.
+ * @returns A structured clone of the accepted policy.
+ * @throws For weaker/invalid fields; malformed nested fields can also throw property-access errors.
+ * @remarks Validation does not itself apply operating-system isolation, concurrency, or network controls.
+ * @example
+ * ```typescript
+ * import { defaultRuntimePlacementPolicy } from "@alneas/eaos-core";
+ * import { validateAgentRuntimePolicy } from "@alneas/eaos-server/agentic/executor";
+ * const policy = validateAgentRuntimePolicy(defaultRuntimePlacementPolicy().ai.agentRuntime);
+ * console.log(policy.placement); // "ai"
+ * ```
+ */
+declare function validateAgentRuntimePolicy(policy: AgentRuntimeResourcePolicy): AgentRuntimeResourcePolicy;
+/**
+ * Builds systemd-run arguments for transient process resource and filesystem restrictions.
+ * @param command - Trusted executable passed after the systemd option terminator.
+ * @param args - Executable arguments, passed unchanged without a shell.
+ * @param policy - Already validated resource policy; this helper does not validate it.
+ * @param cwd - Working directory, resolved absolutely; absent/empty uses process.cwd().
+ * @param unit - Host-selected transient unit name, used for later stop requests.
+ * @returns A new argument array, using --user for a nonroot host user and rounding runtime milliseconds upward to at least one second.
+ * @remarks Requires a host with systemd-run and appropriate service-manager permissions when executed. This array does not implement network allowlisting, workspace capacity, or a concurrency scheduler; those policy fields require host enforcement.
+ * @example
+ * ```typescript
+ * import { defaultRuntimePlacementPolicy } from "@alneas/eaos-core";
+ * import { buildSystemdRunArgs } from "@alneas/eaos-server/agentic/executor";
+ * const args = buildSystemdRunArgs("agent-runtime", ["--version"], defaultRuntimePlacementPolicy().ai.agentRuntime, undefined, "example-agent");
+ * console.log(args.includes("--wait")); // true
+ * ```
+ */
+declare function buildSystemdRunArgs(command: string, args: readonly string[], policy: AgentRuntimeResourcePolicy, cwd: string | undefined, unit: string): string[];
+/**
+ * Creates a shell-free executor for OpenCode, Codex, Goose or another trusted
+ * CLI. Authorization and approval happen before this adapter is called.
+ * @param options - Trusted executable, argument/environment callbacks, output/timeout limits, and sandbox settings.
+ * @returns A per-task async executor resolving stdout on exit code zero, including an empty string when no output was produced.
+ * @throws Synchronously for invalid factory settings. Execution rejects callback/clone/policy errors and ServerAgentExecutionError for spawn, timeout, output-limit, or nonzero-exit failures.
+ * @remarks Requires Node child_process. auto selects systemd on Linux and direct execution elsewhere. No task concurrency limit is enforced here. stdin is ignored, stdout/stderr are bounded together, and stderr is excluded from successful output. On timeout/output/spawn failure the timer is cleared, SIGTERM is sent, and systemd stop is requested when managed; termination is not awaited and descendants may outlive direct-mode failure. Idempotency is only propagated through environment variables; host/runtime code must enforce safe retries.
+ * @example
+ * ```typescript
+ * import { createCommandAgentExecutor, type CommandAgentExecutorOptions } from "@alneas/eaos-server/agentic/executor";
+ * export function hostExecutor(configuration: CommandAgentExecutorOptions) {
+ *   // The host provisions the executable and performs admission/approval first.
+ *   return createCommandAgentExecutor(configuration);
+ * }
+ * ```
+ */
+declare function createCommandAgentExecutor(options: CommandAgentExecutorOptions): ServerAgentExecutor;
+
+export { buildSystemdRunArgs, createCommandAgentExecutor, validateAgentRuntimePolicy };
+export type { CommandAgentExecutorOptions, CommandAgentSandboxMode, CommandAgentSandboxOptions };

package/dist/agentic/executor.js

@@ -0,0 +1,12 @@
+import {
+  buildSystemdRunArgs,
+  createCommandAgentExecutor,
+  validateAgentRuntimePolicy
+} from "../chunk-32746UQZ.js";
+import "../chunk-YABTQZDJ.js";
+export {
+  buildSystemdRunArgs,
+  createCommandAgentExecutor,
+  validateAgentRuntimePolicy
+};
+//# sourceMappingURL=executor.js.map

package/dist/agentic/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/agentic/graph-projection.d.ts

@@ -0,0 +1,119 @@
+import { GraphProjectionAdapter, GraphProjectionCursor, WorkflowEventEnvelope } from '@alneas/eaos-core';
+
+/**
+ * Host persistence for per-projection, per-tenant progress and failure state.
+ * @see GraphProjectionCoordinator.
+ */
+interface ProjectionCursorStore {
+    /**
+     * Reads current projection progress for a tenant.
+     * @param projectionId - Host projection identifier.
+     * @param tenantId - Verified event/snapshot tenant.
+     * @returns Stored cursor, or null when absent.
+     * @throws Store errors propagate to the coordinator.
+     
+     * @example
+     * ```typescript
+     * import type { ProjectionCursorStore } from "@alneas/eaos-server";
+     * export async function inspectTenantProjection(
+     *   store: ProjectionCursorStore, projectionId: string, verifiedTenantId: string,
+     * ) {
+     *   const cursor = await store.get(projectionId, verifiedTenantId);
+     *   return cursor?.status; // Null means no cursor was stored.
+     * }
+     * ```
+     */
+    get(projectionId: string, tenantId: string): Promise<GraphProjectionCursor | null>;
+    /**
+     * Persists replacement projection progress.
+     * @param cursor - Full progress/failure cursor to store.
+     * @returns No value; resolves after persistence.
+     * @throws Store errors propagate; the projection adapter may already have applied changes.
+     
+     * @example
+     * ```typescript
+     * import type { ProjectionCursorStore } from "@alneas/eaos-server";
+     * export async function saveProjectionProgress(
+     *   store: ProjectionCursorStore, cursor: Parameters<ProjectionCursorStore["put"]>[0],
+     * ) {
+     *   // The host aligns this tenant cursor with committed projection work.
+     *   await store.put(cursor);
+     * }
+     * ```
+     */
+    put(cursor: GraphProjectionCursor): Promise<void>;
+}
+/**
+ * Host projection adapter, cursor persistence, and clock for {@link GraphProjectionCoordinator}.
+ */
+interface GraphProjectionCoordinatorOptions {
+    /** Nonblank projection identifier; retained exactly without trimming. */
+    projectionId: string;
+    /** Host relationship-model adapter; must define idempotency and transaction policy. */
+    adapter: GraphProjectionAdapter;
+    /** Host cursor persistence, separate from adapter transactions unless the host coordinates them. */
+    cursorStore: ProjectionCursorStore;
+    /** Clock for ISO progress timestamps; defaults to a fresh Date. */
+    now?: () => Date;
+}
+/**
+ * Applies domain events to an ADB Graph/PGQL or other relationship read model.
+ *
+ * The coordinator is intentionally independent of Oracle. The host supplies
+ * the adapter and cursor store, so credentials, graph schema and transaction
+ * policy never enter core/server.
+ * @remarks Calls are not serialized by this class. The host must coordinate writers/rebuilds, authorize tenant data, and make adapter replay safe. Adapter changes and cursor writes are separate operations; a cursor failure can leave projection data applied but unacknowledged.
+ * @example
+ * ```typescript
+ * import { GraphProjectionCoordinator, type GraphProjectionCoordinatorOptions } from "@alneas/eaos-server/agentic/graph-projection";
+ * export function projection(options: GraphProjectionCoordinatorOptions) {
+ *   return new GraphProjectionCoordinator(options);
+ * }
+ * ```
+ */
+declare class GraphProjectionCoordinator {
+    private readonly now;
+    private readonly options;
+    /**
+     * Captures a host projection identity, adapter, cursor store, and optional clock.
+     * @param options - Host projection dependencies.
+     * @throws If projectionId is blank or adapter/cursorStore is absent.
+     */
+    constructor(options: GraphProjectionCoordinatorOptions);
+    /**
+     * Applies one event and records projection progress, skipping recognized duplicate/stale events.
+     * @param event - Trusted workflow event envelope; the adapter receives a structured clone.
+     * @returns No value; resolves after application and cursor persistence or immediately for the last event ID or a nonincreasing revision of the last aggregate.
+     * @throws Rejects rebuilding state, cursor/clock/clone failures, or adapter failures. Adapter failure attempts a failed cursor write, which can itself replace the original error.
+     * @remarks A revision gap for the last aggregate increments lagCount and records lagging but still applies the event. Deduplication covers only the last event/aggregate cursor, not full history. Failure may occur after adapter side effects; no rollback or retry occurs here.
+     * @example
+     * ```typescript
+     * import { GraphProjectionCoordinator, type GraphProjectionCoordinatorOptions } from "@alneas/eaos-server/agentic/graph-projection";
+     * import type { WorkflowEventEnvelope } from "@alneas/eaos-core";
+     * export async function apply(options: GraphProjectionCoordinatorOptions, event: WorkflowEventEnvelope) {
+     *   await new GraphProjectionCoordinator(options).apply(event);
+     * }
+     * ```
+     */
+    apply(event: Readonly<WorkflowEventEnvelope>): Promise<void>;
+    /**
+     * Marks a tenant projection rebuilding, delegates snapshot replacement, then records healthy or failed state.
+     * @param tenantId - Verified tenant whose relationship model is rebuilt.
+     * @param sourceRevision - Host source revision copied to the rebuilt cursor; not validated by this coordinator.
+     * @param snapshot - Host-authorized snapshot cloned before passing to the adapter.
+     * @returns No value; resolves after adapter rebuild and healthy cursor persistence.
+     * @throws Rejects clock, cursor, clone, or adapter failures; a failed-status write can replace an earlier failure.
+     * @remarks No cancellation or exclusive lock is acquired. The host must serialize rebuild/application and determine recovery after partial adapter or cursor failure.
+     * @example
+     * ```typescript
+     * import { GraphProjectionCoordinator, type GraphProjectionCoordinatorOptions } from "@alneas/eaos-server/agentic/graph-projection";
+     * export async function rebuild(options: GraphProjectionCoordinatorOptions, tenantId: string, revision: number, snapshot: unknown) {
+     *   await new GraphProjectionCoordinator(options).rebuild(tenantId, revision, snapshot);
+     * }
+     * ```
+     */
+    rebuild(tenantId: string, sourceRevision: number, snapshot: unknown): Promise<void>;
+}
+
+export { GraphProjectionCoordinator };
+export type { GraphProjectionCoordinatorOptions, ProjectionCursorStore };

package/dist/agentic/graph-projection.js

@@ -0,0 +1,7 @@
+import {
+  GraphProjectionCoordinator
+} from "../chunk-W6O3LVBY.js";
+export {
+  GraphProjectionCoordinator
+};
+//# sourceMappingURL=graph-projection.js.map

package/dist/agentic/graph-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}