@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/chunk-JT6BRGQM.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-JT6BRGQM.js.map

package/dist/chunk-JT6BRGQM.js.map

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

package/dist/chunk-L6PMAEMB.js

@@ -0,0 +1,115 @@
+// src/lifecycle/index.ts
+import { mkdir, readFile, open, rename, unlink, rmdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createMiddleware } from "hono/factory";
+import { emptyLifecycleState, normalizeLifecycleState } from "@alneas/eaos-server/lifecycle-engine";
+var FileLifecycleStore = class {
+  /** Absolute ledger path resolved at construction; lock directory is path + ".lock". */
+  path;
+  /**
+   * Resolves a host-selected ledger filename without reading or creating it.
+   * @param path - Ledger filename, resolved relative to the current process directory.
+   */
+  constructor(path) {
+    this.path = resolve(path);
+  }
+  /**
+   * Reads and normalizes the JSON lifecycle ledger.
+   * @returns Stored lifecycle state, or a fresh empty state if the file does not exist.
+   * @throws Rejects filesystem, JSON parsing, or state-normalization failures other than ENOENT.
+   * @example
+   * ```typescript
+   * import { FileLifecycleStore } from "@alneas/eaos-server/lifecycle";
+   * const state = await new FileLifecycleStore("./state/lifecycle.json").read();
+   * console.log(state.platform);
+   * ```
+   */
+  async read() {
+    try {
+      return normalizeLifecycleState(JSON.parse(await readFile(this.path, "utf8")));
+    } catch (error) {
+      if (error.code === "ENOENT") return emptyLifecycleState();
+      throw error;
+    }
+  }
+  /**
+   * Runs one writer callback under an exclusive filesystem lock directory.
+   * @typeParam T - Callback result passed through unchanged.
+   * @param fn - Called after lock acquisition with ledger read and durable write operations; must await its writes before returning.
+   * @returns The callback result after lock directory removal. Writer.write resolves without a value after temporary-file fsync, rename, and directory fsync.
+   * @throws Rejects an existing lock, filesystem failures, callback failures, or final lock-removal failures.
+   * @remarks Lock acquisition does not wait or retry. Ordinary callback failure removes the lock; a process crash can leave it behind and requires operator reconciliation. Writes may have committed before a later failure. The store does not enforce that all external writers use this lock.
+   * @example
+   * ```typescript
+   * import { FileLifecycleStore } from "@alneas/eaos-server/lifecycle";
+   * const store = new FileLifecycleStore("./state/lifecycle.json");
+   * const state = await store.withLock(async writer => writer.read());
+   * console.log(state.platform);
+   * ```
+   */
+  async withLock(fn) {
+    await mkdir(dirname(this.path), { recursive: true });
+    const lock = this.path + ".lock";
+    try {
+      await mkdir(lock, { mode: 448 });
+    } catch (error) {
+      if (error.code === "EEXIST") throw new Error("Lifecycle writer is locked; a crashed operation requires reconciliation", { cause: error });
+      throw error;
+    }
+    try {
+      return await fn({ read: () => this.read(), write: (state) => this.write(state) });
+    } finally {
+      await rmdir(lock);
+    }
+  }
+  async write(state) {
+    const temporary = this.path + "." + randomUUID() + ".tmp";
+    try {
+      const handle = await open(temporary, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(state) + "\n");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, this.path);
+      const directory = await open(dirname(this.path), "r");
+      try {
+        await directory.sync();
+      } finally {
+        await directory.close();
+      }
+    } finally {
+      await unlink(temporary).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
+  }
+};
+async function resolveLifecycleBackend(runtime, tenantId) {
+  const backendId = runtime.resolveBackend ? await runtime.resolveBackend(tenantId) : runtime.backendId;
+  if (!backendId) throw new Error("Tenant lifecycle target is unavailable");
+  return backendId;
+}
+async function runLifecycleJob(runtime, job, callback) {
+  return runtime.lifecycle.run(await resolveLifecycleBackend(runtime, job.tenantId), job.tenantId, job.pluginId, callback);
+}
+function createLifecycleGuard(runtime, pluginId) {
+  return createMiddleware(async (c, next) => {
+    const tenantId = await runtime.resolveTenant(c);
+    if (!tenantId) return c.json({ error: "Unauthorized" }, 401);
+    const backendId = runtime.resolveBackend ? await runtime.resolveBackend(tenantId) : runtime.backendId;
+    if (!backendId || !await runtime.lifecycle.isEnabled(backendId, tenantId, pluginId)) return c.json({ error: "Plugin is inactive" }, 403);
+    c.set("tenantId", tenantId);
+    await next();
+  });
+}
+
+export {
+  FileLifecycleStore,
+  resolveLifecycleBackend,
+  runLifecycleJob,
+  createLifecycleGuard
+};
+//# sourceMappingURL=chunk-L6PMAEMB.js.map

package/dist/chunk-L6PMAEMB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lifecycle/index.ts"],"sourcesContent":["import { mkdir, readFile, open, rename, unlink, rmdir } from 'node:fs/promises'\nimport { dirname, resolve } from 'node:path'\nimport { randomUUID } from 'node:crypto'\nimport type { Context } from 'hono'\nimport { createMiddleware } from 'hono/factory'\nimport { emptyLifecycleState, normalizeLifecycleState, type LifecycleStore, type LifecycleWriter, type LifecycleState, type PluginLifecycle } from '@alneas/eaos-server/lifecycle-engine'\n\n/** Single control-plane filesystem. All backend processes must read the same ledger.\n * A crashed writer leaves its lock in place: reconcile DB/infra before operator recovery.\n * For independent hosts, implement LifecycleStore using a shared transactional control DB.\n * @example\n * ```typescript\n * import { FileLifecycleStore } from \"@alneas/eaos-server/lifecycle\";\n * const store = new FileLifecycleStore(\"./state/lifecycle.json\");\n * console.log((await store.read()).platform);\n * ```\n */\nexport class FileLifecycleStore implements LifecycleStore {\n  /** Absolute ledger path resolved at construction; lock directory is path + \".lock\". */\n  readonly path: string\n  /**\n   * Resolves a host-selected ledger filename without reading or creating it.\n   * @param path - Ledger filename, resolved relative to the current process directory.\n   */\n  constructor(path: string) { this.path = resolve(path) }\n  /**\n   * Reads and normalizes the JSON lifecycle ledger.\n   * @returns Stored lifecycle state, or a fresh empty state if the file does not exist.\n   * @throws Rejects filesystem, JSON parsing, or state-normalization failures other than ENOENT.\n   * @example\n   * ```typescript\n   * import { FileLifecycleStore } from \"@alneas/eaos-server/lifecycle\";\n   * const state = await new FileLifecycleStore(\"./state/lifecycle.json\").read();\n   * console.log(state.platform);\n   * ```\n   */\n  async read(): Promise<LifecycleState> {\n    try { return normalizeLifecycleState(JSON.parse(await readFile(this.path, 'utf8')) as LifecycleState) }\n    catch (error: any) { if (error.code === 'ENOENT') return emptyLifecycleState(); throw error }\n  }\n  /**\n   * Runs one writer callback under an exclusive filesystem lock directory.\n   * @typeParam T - Callback result passed through unchanged.\n   * @param fn - Called after lock acquisition with ledger read and durable write operations; must await its writes before returning.\n   * @returns The callback result after lock directory removal. Writer.write resolves without a value after temporary-file fsync, rename, and directory fsync.\n   * @throws Rejects an existing lock, filesystem failures, callback failures, or final lock-removal failures.\n   * @remarks Lock acquisition does not wait or retry. Ordinary callback failure removes the lock; a process crash can leave it behind and requires operator reconciliation. Writes may have committed before a later failure. The store does not enforce that all external writers use this lock.\n   * @example\n   * ```typescript\n   * import { FileLifecycleStore } from \"@alneas/eaos-server/lifecycle\";\n   * const store = new FileLifecycleStore(\"./state/lifecycle.json\");\n   * const state = await store.withLock(async writer => writer.read());\n   * console.log(state.platform);\n   * ```\n   */\n  async withLock<T>(fn: (writer: LifecycleWriter) => Promise<T>): Promise<T> {\n    await mkdir(dirname(this.path), { recursive: true })\n    const lock = this.path + '.lock'\n    try { await mkdir(lock, { mode: 0o700 }) }\n    catch (error: any) { if (error.code === 'EEXIST') throw new Error('Lifecycle writer is locked; a crashed operation requires reconciliation', { cause: error }); throw error }\n    try {\n      return await fn({ read: () => this.read(), write: state => this.write(state) })\n    } finally { await rmdir(lock) }\n  }\n  private async write(state: LifecycleState): Promise<void> {\n    const temporary = this.path + '.' + randomUUID() + '.tmp'\n    try {\n      const handle = await open(temporary, 'wx', 0o600)\n      try { await handle.writeFile(JSON.stringify(state) + '\\n'); await handle.sync() } finally { await handle.close() }\n      await rename(temporary, this.path)\n      const directory = await open(dirname(this.path), 'r')\n      try { await directory.sync() } finally { await directory.close() }\n    } finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error }) }\n  }\n}\n/**\n * Host identity, backend routing, and lifecycle admission used by jobs and HTTP guards.\n * @see createLifecycleGuard.\n */\nexport interface LifecycleRuntime {\n  /** Lifecycle engine consulted for current plugin admission. */\n  lifecycle: PluginLifecycle\n  /** Fallback registered backend ID used only when resolveBackend is absent. */\n  backendId: string\n  /** Resolve the registered target for a verified tenant; null denies admission without fallback. */\n  resolveBackend?: (tenantId: string) => Promise<string | null>\n  /** Must resolve authenticated identity / verified webhook signature, never a raw tenant header alone. */\n  resolveTenant: (context: Context) => Promise<string | null>\n}\n/**\n * Resolves the host-selected backend for a verified tenant without falling back after a resolver denial.\n * @param runtime - Lifecycle runtime with either a backend resolver or fixed backend ID.\n * @param tenantId - Verified tenant whose placement is being resolved.\n * @returns Nonempty resolved backend ID, or runtime.backendId when no callback exists.\n * @throws Rejects an empty/null backend result or propagated resolver errors.\n * @example\n * ```typescript\n * import { resolveLifecycleBackend, type LifecycleRuntime } from \"@alneas/eaos-server/lifecycle\";\n * export async function backend(runtime: LifecycleRuntime, tenantId: string) {\n *   return resolveLifecycleBackend(runtime, tenantId);\n * }\n * ```\n */\nexport async function resolveLifecycleBackend(runtime: LifecycleRuntime, tenantId: string): Promise<string> {\n  const backendId = runtime.resolveBackend ? await runtime.resolveBackend(tenantId) : runtime.backendId\n  if (!backendId) throw new Error('Tenant lifecycle target is unavailable')\n  return backendId\n}\n/**\n * Runs a host job through lifecycle admission for its verified tenant and plugin.\n * @typeParam T - Result resolved by the admitted callback.\n * @param runtime - Backend routing and lifecycle engine.\n * @param job - Trusted tenantId/pluginId binding of the queued job.\n * @param callback - Invoked without arguments by lifecycle.run after admission; resolves the job result.\n * @returns The callback result after lifecycle.run completes.\n * @throws Rejects unavailable backend, lifecycle admission/store failure, or callback failure.\n * @remarks Persistence, retries, and idempotency of the job body belong to the host. This wrapper delegates concurrency/drain behavior to lifecycle.run.\n * @example\n * ```typescript\n * import { runLifecycleJob, type LifecycleRuntime } from \"@alneas/eaos-server/lifecycle\";\n * export async function runJob<T>(runtime: LifecycleRuntime, tenantId: string, pluginId: string, execute: () => Promise<T>) {\n *   return runLifecycleJob(runtime, { tenantId, pluginId }, execute);\n * }\n * ```\n */\nexport async function runLifecycleJob<T>(runtime: LifecycleRuntime, job: {\n  /**\n * Verified tenant identity of the queued job, used to select its lifecycle backend.\n */\ntenantId: string;\n  /**\n * Exact plugin ID whose current lifecycle admission gates this job body.\n */\npluginId: string }, callback: () => Promise<T>): Promise<T> {\n  return runtime.lifecycle.run(await resolveLifecycleBackend(runtime, job.tenantId), job.tenantId, job.pluginId, callback)\n}\n/**\n * Creates a request guard requiring a verified tenant and currently enabled plugin placement.\n * @param runtime - Host tenant verification, backend routing, and lifecycle engine.\n * @param pluginId - Exact installed plugin ID required by the route.\n * @returns Hono middleware returning 401 for absent tenant, 403 for unavailable backend/inactive plugin, or completing downstream handling without a value after setting tenantId.\n * @throws Request handling propagates host resolver, lifecycle store, and downstream failures.\n * @remarks Authenticate webhook signatures or browser identity in resolveTenant; a raw header is insufficient. This guard performs a point-in-time isEnabled check and does not hold a lifecycle.run execution lease across downstream work.\n * @example\n * ```typescript\n * import { Hono } from \"hono\";\n * import { createLifecycleGuard, type LifecycleRuntime } from \"@alneas/eaos-server/lifecycle\";\n * export function pluginRoutes(runtime: LifecycleRuntime) {\n *   const app = new Hono();\n *   app.use(\"*\", createLifecycleGuard(runtime, \"example-plugin\"));\n *   app.get(\"/\", c => c.json({ available: true }));\n *   return app;\n * }\n * ```\n */\nexport function createLifecycleGuard(runtime: LifecycleRuntime, pluginId: string) {\n  return createMiddleware(async (c, next) => {\n    const tenantId = await runtime.resolveTenant(c)\n    if (!tenantId) return c.json({ error: 'Unauthorized' }, 401)\n    const backendId = runtime.resolveBackend ? await runtime.resolveBackend(tenantId) : runtime.backendId\n    if (!backendId || !await runtime.lifecycle.isEnabled(backendId, tenantId, pluginId)) return c.json({ error: 'Plugin is inactive' }, 403)\n    c.set('tenantId', tenantId)\n    await next()\n  })\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-LOUGW6MU.js

@@ -0,0 +1,126 @@
+// src/lifecycle-engine/platform/database-router.ts
+var TenantDatabaseRouter = class {
+  /**
+   * Snapshots configured physical database adapters and requires a single shared dialect.
+   * @param resolveTarget - Resolve the verified tenant to its trusted lifecycle backend; synchronous errors propagate.
+   * @param adapters - Nonempty map keyed by physical databaseId; adapter objects are shared and later owned by close().
+   * @throws Error for no adapters or multiple adapter dialects.
+   * 
+   * @example
+   * ```typescript
+   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';
+   * import type { DatabaseAdapter } from '@alneas/eaos-core/db/adapter';
+   * import type { BackendTarget } from '@alneas/eaos-server/lifecycle-engine';
+   * export function connectRouter(resolve: (verifiedTenantId: string) => BackendTarget, adapters: ReadonlyMap<string, DatabaseAdapter>) { return new TenantDatabaseRouter(resolve, adapters); }
+   * ```
+   */
+  constructor(resolveTarget, adapters) {
+    this.resolveTarget = resolveTarget;
+    this.adapters = new Map(adapters);
+    const types = new Set([...this.adapters.values()].map((adapter) => adapter.type));
+    if (!this.adapters.size || types.size !== 1) throw new Error("Tenant DB routing requires configured adapters of one dialect");
+    this.type = types.values().next().value;
+  }
+  resolveTarget;
+  /**
+   * The single SQL dialect shared by every configured adapter.
+   */
+  type;
+  adapters;
+  /**
+   * Rejects unscoped business database access to require a verified tenant context.
+   * @typeParam T - Callback result type required by DatabaseAdapter; this method always rejects.
+   * @param _domain - Unused business domain; no connection is opened.
+   * @param _callback - Unused callback; it is never invoked.
+   * @returns A rejected Promise; this method never resolves a callback result.
+   * @throws Always rejects with the verified-context requirement.
+   * 
+   * @example
+   * ```typescript
+   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';
+   * export async function rejectUnscoped(router: TenantDatabaseRouter) { await router.withConnection('reports', async () => undefined); }
+   * ```
+   */
+  withConnection(_domain, _callback) {
+    return Promise.reject(new Error("Business DB routing requires a verified tenant context; use a separate control adapter for administration"));
+  }
+  /**
+   * Delegates one verified tenant connection to its exact configured physical database adapter.
+   * @typeParam T - Value resolved by work on the selected tenant connection.
+   * @param domain - Business domain forwarded to the selected adapter.
+   * @param callback - Async work invoked by the adapter with its connection; must enforce resource permission.
+   * @param context - Verified nonblank trimmed tenant session; a copied context is forwarded.
+   * @returns The selected adapter callback result.
+   * @throws Rejects invalid tenant, dedicated mismatch, missing adapter or adapter/callback failure; target resolver errors may throw synchronously.
+   * 
+   * @remarks
+   * Dedicated target tenant must match. Missing target adapters and dedicated failures never fall back to shared storage. Cancellation/transaction/connection cleanup follow the selected adapter contract.
+   * 
+   * @example
+   * ```typescript
+   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';
+   * export function withVerifiedTenant<T>(router: TenantDatabaseRouter, tenantId: string, work: (connection: unknown) => Promise<T>) { return router.withTenantConnection('reports', work, { tenantId }); }
+   * ```
+   */
+  withTenantConnection(domain, callback, context) {
+    if (!context?.tenantId || context.tenantId === "*" || context.tenantId !== context.tenantId.trim()) return Promise.reject(new Error("Verified tenant context is required"));
+    const target = this.resolveTarget(context.tenantId);
+    if (target.mode === "dedicated" && target.tenantId !== context.tenantId) return Promise.reject(new Error("Dedicated database tenant mismatch"));
+    const adapter = this.adapters.get(target.databaseId);
+    if (!adapter) return Promise.reject(new Error("Tenant DB adapter is not configured; shared fallback is disabled"));
+    return adapter.withTenantConnection(domain, callback, { ...context });
+  }
+  /**
+   * Checks every distinct configured database adapter concurrently.
+   * @returns True only when every adapter ping resolves true; false if any resolves false.
+   * @throws Rejects if any adapter ping rejects.
+   * 
+   * @example
+   * ```typescript
+   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';
+   * export const health = (router: TenantDatabaseRouter) => router.ping();
+   * ```
+   */
+  async ping() {
+    return (await Promise.all([...new Set(this.adapters.values())].map((adapter) => adapter.ping()))).every(Boolean);
+  }
+  /**
+   * Aggregates connection and pool counts from every distinct configured adapter.
+   * @returns ConnectionStats with the router dialect and summed counts.
+   * @throws Propagates adapter getStats errors.
+   * 
+   * @example
+   * ```typescript
+   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';
+   * export const stats = (router: TenantDatabaseRouter) => router.getStats();
+   * ```
+   */
+  getStats() {
+    const stats = [...new Set(this.adapters.values())].map((adapter) => adapter.getStats());
+    return { driver: this.type, activeConnections: stats.reduce((n, s) => n + s.activeConnections, 0), poolSize: stats.reduce((n, s) => n + s.poolSize, 0) };
+  }
+  /**
+   * Closes all distinct configured adapters and collects asynchronous cleanup failures.
+   * @returns Resolves without a value after every adapter close settles successfully.
+   * @throws Rejects with AggregateError for one or more rejected close Promises; synchronous adapter errors may also reject.
+   * 
+   * @remarks
+   * The router does not mark itself closed or make repeated calls idempotent; each adapter owns its lifecycle semantics. A synchronously throwing close implementation can interrupt initial dispatch.
+   * 
+   * @example
+   * ```typescript
+   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';
+   * export async function shutdown(router: TenantDatabaseRouter) { await router.close(); }
+   * ```
+   */
+  async close() {
+    const results = await Promise.allSettled([...new Set(this.adapters.values())].map((adapter) => adapter.close()));
+    const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+    if (errors.length) throw new AggregateError(errors, "Tenant DB adapters failed to close");
+  }
+};
+
+export {
+  TenantDatabaseRouter
+};
+//# sourceMappingURL=chunk-LOUGW6MU.js.map

package/dist/chunk-LOUGW6MU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lifecycle-engine/platform/database-router.ts"],"sourcesContent":["import type { DatabaseAdapter, TenantSessionContext, ConnectionStats } from '@alneas/eaos-core/db/adapter'\nimport type { BackendTarget } from '../index'\n\n/**\n * Routes verified tenant operations to isolated existing database pools without implicit fallback.\n * \n * \n * One execution host, isolated pools per DB. No implicit shared fallback or unscoped business access.\n * @remarks\n * All configured adapters must share one dialect. The host supplies membership-verified tenant context, trusted target resolution and real adapter pools. Unscoped business connections always reject; administration requires a separate control adapter. close owns and closes every distinct supplied adapter.\n * \n * @example\n * ```typescript\n * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n * import type { DatabaseAdapter } from '@alneas/eaos-core/db/adapter';\n * import type { BackendTarget } from '@alneas/eaos-server/lifecycle-engine';\n * export function connectRouter(resolve: (verifiedTenantId: string) => BackendTarget, adapters: ReadonlyMap<string, DatabaseAdapter>) { return new TenantDatabaseRouter(resolve, adapters); }\n * ```\n */\nexport class TenantDatabaseRouter implements DatabaseAdapter {\n  /**\n   * The single SQL dialect shared by every configured adapter.\n   */\n  readonly type: DatabaseAdapter['type']\n  private readonly adapters: Map<string, DatabaseAdapter>\n  /**\n   * Snapshots configured physical database adapters and requires a single shared dialect.\n   * @param resolveTarget - Resolve the verified tenant to its trusted lifecycle backend; synchronous errors propagate.\n   * @param adapters - Nonempty map keyed by physical databaseId; adapter objects are shared and later owned by close().\n   * @throws Error for no adapters or multiple adapter dialects.\n   * \n   * @example\n   * ```typescript\n   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n   * import type { DatabaseAdapter } from '@alneas/eaos-core/db/adapter';\n   * import type { BackendTarget } from '@alneas/eaos-server/lifecycle-engine';\n   * export function connectRouter(resolve: (verifiedTenantId: string) => BackendTarget, adapters: ReadonlyMap<string, DatabaseAdapter>) { return new TenantDatabaseRouter(resolve, adapters); }\n   * ```\n   */\n  constructor(private readonly resolveTarget: (verifiedTenantId: string) => BackendTarget, adapters: ReadonlyMap<string, DatabaseAdapter>) {\n    this.adapters = new Map(adapters)\n    const types = new Set([...this.adapters.values()].map(adapter => adapter.type))\n    if (!this.adapters.size || types.size !== 1) throw new Error('Tenant DB routing requires configured adapters of one dialect')\n    this.type = types.values().next().value!\n  }\n  /**\n   * Rejects unscoped business database access to require a verified tenant context.\n   * @typeParam T - Callback result type required by DatabaseAdapter; this method always rejects.\n   * @param _domain - Unused business domain; no connection is opened.\n   * @param _callback - Unused callback; it is never invoked.\n   * @returns A rejected Promise; this method never resolves a callback result.\n   * @throws Always rejects with the verified-context requirement.\n   * \n   * @example\n   * ```typescript\n   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n   * export async function rejectUnscoped(router: TenantDatabaseRouter) { await router.withConnection('reports', async () => undefined); }\n   * ```\n   */\n  withConnection<T>(_domain: string, _callback: (connection: unknown) => Promise<T>): Promise<T> {\n    return Promise.reject(new Error('Business DB routing requires a verified tenant context; use a separate control adapter for administration'))\n  }\n  /**\n   * Delegates one verified tenant connection to its exact configured physical database adapter.\n   * @typeParam T - Value resolved by work on the selected tenant connection.\n   * @param domain - Business domain forwarded to the selected adapter.\n   * @param callback - Async work invoked by the adapter with its connection; must enforce resource permission.\n   * @param context - Verified nonblank trimmed tenant session; a copied context is forwarded.\n   * @returns The selected adapter callback result.\n   * @throws Rejects invalid tenant, dedicated mismatch, missing adapter or adapter/callback failure; target resolver errors may throw synchronously.\n   * \n   * @remarks\n   * Dedicated target tenant must match. Missing target adapters and dedicated failures never fall back to shared storage. Cancellation/transaction/connection cleanup follow the selected adapter contract.\n   * \n   * @example\n   * ```typescript\n   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n   * export function withVerifiedTenant<T>(router: TenantDatabaseRouter, tenantId: string, work: (connection: unknown) => Promise<T>) { return router.withTenantConnection('reports', work, { tenantId }); }\n   * ```\n   */\n  withTenantConnection<T>(domain: string, callback: (connection: unknown) => Promise<T>, context: TenantSessionContext): Promise<T> {\n    if (!context?.tenantId || context.tenantId === '*' || context.tenantId !== context.tenantId.trim()) return Promise.reject(new Error('Verified tenant context is required'))\n    const target = this.resolveTarget(context.tenantId)\n    if (target.mode === 'dedicated' && target.tenantId !== context.tenantId) return Promise.reject(new Error('Dedicated database tenant mismatch'))\n    const adapter = this.adapters.get(target.databaseId)\n    if (!adapter) return Promise.reject(new Error('Tenant DB adapter is not configured; shared fallback is disabled'))\n    return adapter.withTenantConnection(domain, callback, { ...context })\n  }\n  /**\n   * Checks every distinct configured database adapter concurrently.\n   * @returns True only when every adapter ping resolves true; false if any resolves false.\n   * @throws Rejects if any adapter ping rejects.\n   * \n   * @example\n   * ```typescript\n   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n   * export const health = (router: TenantDatabaseRouter) => router.ping();\n   * ```\n   */\n  async ping(): Promise<boolean> { return (await Promise.all([...new Set(this.adapters.values())].map(adapter => adapter.ping()))).every(Boolean) }\n  /**\n   * Aggregates connection and pool counts from every distinct configured adapter.\n   * @returns ConnectionStats with the router dialect and summed counts.\n   * @throws Propagates adapter getStats errors.\n   * \n   * @example\n   * ```typescript\n   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n   * export const stats = (router: TenantDatabaseRouter) => router.getStats();\n   * ```\n   */\n  getStats(): ConnectionStats {\n    const stats = [...new Set(this.adapters.values())].map(adapter => adapter.getStats())\n    return { driver: this.type, activeConnections: stats.reduce((n, s) => n + s.activeConnections, 0), poolSize: stats.reduce((n, s) => n + s.poolSize, 0) }\n  }\n  /**\n   * Closes all distinct configured adapters and collects asynchronous cleanup failures.\n   * @returns Resolves without a value after every adapter close settles successfully.\n   * @throws Rejects with AggregateError for one or more rejected close Promises; synchronous adapter errors may also reject.\n   * \n   * @remarks\n   * The router does not mark itself closed or make repeated calls idempotent; each adapter owns its lifecycle semantics. A synchronously throwing close implementation can interrupt initial dispatch.\n   * \n   * @example\n   * ```typescript\n   * import { TenantDatabaseRouter } from '@alneas/eaos-server/platform/database-router';\n   * export async function shutdown(router: TenantDatabaseRouter) { await router.close(); }\n   * ```\n   */\n  async close(): Promise<void> {\n    const results = await Promise.allSettled([...new Set(this.adapters.values())].map(adapter => adapter.close()))\n    const errors = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map(result => result.reason)\n    if (errors.length) throw new AggregateError(errors, 'Tenant DB adapters failed to close')\n  }\n}\n"],"mappings":";AAmBO,IAAM,uBAAN,MAAsD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoB3D,YAA6B,eAA4D,UAAgD;AAA5G;AAC3B,SAAK,WAAW,IAAI,IAAI,QAAQ;AAChC,UAAM,QAAQ,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,OAAO,CAAC,EAAE,IAAI,aAAW,QAAQ,IAAI,CAAC;AAC9E,QAAI,CAAC,KAAK,SAAS,QAAQ,MAAM,SAAS,EAAG,OAAM,IAAI,MAAM,+DAA+D;AAC5H,SAAK,OAAO,MAAM,OAAO,EAAE,KAAK,EAAE;AAAA,EACpC;AAAA,EAL6B;AAAA;AAAA;AAAA;AAAA,EAhBpB;AAAA,EACQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmCjB,eAAkB,SAAiB,WAA4D;AAC7F,WAAO,QAAQ,OAAO,IAAI,MAAM,2GAA2G,CAAC;AAAA,EAC9I;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBA,qBAAwB,QAAgB,UAA+C,SAA2C;AAChI,QAAI,CAAC,SAAS,YAAY,QAAQ,aAAa,OAAO,QAAQ,aAAa,QAAQ,SAAS,KAAK,EAAG,QAAO,QAAQ,OAAO,IAAI,MAAM,qCAAqC,CAAC;AAC1K,UAAM,SAAS,KAAK,cAAc,QAAQ,QAAQ;AAClD,QAAI,OAAO,SAAS,eAAe,OAAO,aAAa,QAAQ,SAAU,QAAO,QAAQ,OAAO,IAAI,MAAM,oCAAoC,CAAC;AAC9I,UAAM,UAAU,KAAK,SAAS,IAAI,OAAO,UAAU;AACnD,QAAI,CAAC,QAAS,QAAO,QAAQ,OAAO,IAAI,MAAM,kEAAkE,CAAC;AACjH,WAAO,QAAQ,qBAAqB,QAAQ,UAAU,EAAE,GAAG,QAAQ,CAAC;AAAA,EACtE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,OAAyB;AAAE,YAAQ,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,IAAI,KAAK,SAAS,OAAO,CAAC,CAAC,EAAE,IAAI,aAAW,QAAQ,KAAK,CAAC,CAAC,GAAG,MAAM,OAAO;AAAA,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYhJ,WAA4B;AAC1B,UAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,KAAK,SAAS,OAAO,CAAC,CAAC,EAAE,IAAI,aAAW,QAAQ,SAAS,CAAC;AACpF,WAAO,EAAE,QAAQ,KAAK,MAAM,mBAAmB,MAAM,OAAO,CAAC,GAAG,MAAM,IAAI,EAAE,mBAAmB,CAAC,GAAG,UAAU,MAAM,OAAO,CAAC,GAAG,MAAM,IAAI,EAAE,UAAU,CAAC,EAAE;AAAA,EACzJ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,MAAM,QAAuB;AAC3B,UAAM,UAAU,MAAM,QAAQ,WAAW,CAAC,GAAG,IAAI,IAAI,KAAK,SAAS,OAAO,CAAC,CAAC,EAAE,IAAI,aAAW,QAAQ,MAAM,CAAC,CAAC;AAC7G,UAAM,SAAS,QAAQ,OAAO,CAAC,WAA4C,OAAO,WAAW,UAAU,EAAE,IAAI,YAAU,OAAO,MAAM;AACpI,QAAI,OAAO,OAAQ,OAAM,IAAI,eAAe,QAAQ,oCAAoC;AAAA,EAC1F;AACF;","names":[]}

package/dist/chunk-LYPZPE53.js

@@ -0,0 +1,129 @@
+import {
+  createAgentJob,
+  enqueueAgentJob
+} from "./chunk-PBC3MZUL.js";
+
+// src/agentic/ai-broker.ts
+import {
+  createAIExecutionBroker
+} from "@alneas/eaos-core";
+var DurableAIExecutionBroker = class {
+  routesById;
+  selector;
+  now;
+  /**
+   * Validates and clones server routes and configures the core allocation selector.
+   * @param options - Nonempty routes list; optional policyVersion labels selector decisions and now supplies job timestamps, defaulting to fresh Date.
+   * @throws Invalid/missing routes, incompatible local dispatch bindings, core selector validation, or clone failures.
+   */
+  constructor(options) {
+    if (!options || !Array.isArray(options.routes) || options.routes.length === 0) throw new Error("AI execution routes are required");
+    const routes = options.routes.map(validateServerRoute);
+    this.routesById = new Map(routes.map((route) => [route.routeId, structuredClone(route)]));
+    this.selector = createAIExecutionBroker({ routes, policyVersion: options.policyVersion });
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  /**
+   * Lists registered server route bindings without exposing mutable stored objects.
+   * @returns Cloned route records in registration map order.
+   * @example
+   * ```typescript
+   * import { DurableAIExecutionBroker } from "@alneas/eaos-server/agentic/ai-broker";
+   * export function routes(broker: DurableAIExecutionBroker) { return broker.listRoutes(); }
+   * ```
+   */
+  listRoutes() {
+    return [...this.routesById.values()].map((route) => structuredClone(route));
+  }
+  /**
+   * Selects an eligible host-advertised runtime using the core routing policy.
+   * @param request - Verified AI execution requirements and context.
+   * @returns The core selector decision; no job is persisted or runtime started.
+   * @throws Propagates core routing validation/no-eligible-route errors.
+   * @example
+   * ```typescript
+   * import { DurableAIExecutionBroker } from "@alneas/eaos-server/agentic/ai-broker";
+   * import type { AIExecutionRequest } from "@alneas/eaos-core";
+   * export function decide(broker: DurableAIExecutionBroker, request: AIExecutionRequest) { return broker.decide(request); }
+   * ```
+   */
+  decide(request) {
+    return this.selector.decide(request);
+  }
+  /**
+   * Selects a route and creates a queue record with host-controlled worker/dispatch/runner bindings.
+   * @param input - Routing and task must have matching tenantId/userId; queue metadata follows AIJobSubmission.
+   * @returns Decision and newly created job; caller-supplied broker route/dispatch/runner execution fields are stripped before selected bindings are written.
+   * @throws Principal mismatch, unavailable route, invalid core routing, clone/hash/clock, or job creation failures.
+   * @remarks No persistence or deduplication occurs until enqueue; repeated plan calls generate different job IDs.
+   * @example
+   * ```typescript
+   * import { DurableAIExecutionBroker } from "@alneas/eaos-server/agentic/ai-broker";
+   * import type { AIJobSubmission } from "@alneas/eaos-server/agentic/ai-broker";
+   * export function plan(broker: DurableAIExecutionBroker, input: AIJobSubmission) { return broker.plan(input); }
+   * ```
+   */
+  plan(input) {
+    if (!input?.routing || !input.task || input.routing.context.tenantId !== input.task.tenantId || input.routing.context.userId !== input.task.userId) throw new Error("AI routing context does not match task context");
+    const decision = this.decide(input.routing);
+    const binding = this.routesById.get(decision.route.routeId);
+    if (!binding) throw new Error("Selected AI execution route is not registered");
+    const request = {
+      ...structuredClone(input.task),
+      workerType: binding.workerType,
+      jobKind: input.kind,
+      executionContext: {
+        ...withoutBrokerFields(input.task.executionContext),
+        routeId: binding.routeId,
+        dispatchMode: binding.dispatchMode,
+        ...binding.runnerId === void 0 ? {} : { runnerId: binding.runnerId }
+      }
+    };
+    const job = createAgentJob({
+      request,
+      kind: input.kind,
+      workflowInstanceId: input.workflowInstanceId,
+      correlationId: input.correlationId ?? input.routing.context.operation,
+      idempotencyKey: input.idempotencyKey,
+      maxAttempts: input.maxAttempts,
+      now: this.now()
+    });
+    return { decision, job };
+  }
+  /**
+   * Plans routing and atomically inserts or deduplicates the queue job in a caller-owned session.
+   * @param tx - Authorized atomic transaction/session; caller owns commit/rollback.
+   * @param input - Verified routing/task and queue metadata.
+   * @returns Decision plus the newly saved or existing idempotent job.
+   * @throws Planning errors, conflicting deduplication input, corrupt index, or session failures.
+   * @remarks Selection still runs before deduplication; the returned existing job is authoritative for its persisted routing. No runtime execution occurs.
+   * @example
+   * ```typescript
+   * import { DurableAIExecutionBroker } from "@alneas/eaos-server/agentic/ai-broker";
+   * import type { AIJobSubmission } from "@alneas/eaos-server/agentic/ai-broker";
+   * import type { AtomicSession } from "@alneas/eaos-server/plugin-data/atomic";
+   * export async function enqueue(broker: DurableAIExecutionBroker, tx: AtomicSession, input: AIJobSubmission) { return broker.enqueue(tx, input); }
+   * ```
+   */
+  async enqueue(tx, input) {
+    const plan = this.plan(input);
+    const saved = await enqueueAgentJob(tx, plan.job);
+    return { ...plan, job: saved };
+  }
+};
+function validateServerRoute(route) {
+  if (!route || typeof route.workerType !== "string" || !route.workerType.trim()) throw new Error("Invalid AI route worker type");
+  if (route.dispatchMode === "local-pull" && route.target !== "local-subscription-cli" && route.target !== "local-mlx") throw new Error("Only local routes may use local-pull dispatch");
+  if ((route.target === "local-subscription-cli" || route.target === "local-mlx") && route.dispatchMode !== "local-pull") throw new Error("Local CLI and MLX routes must use local-pull dispatch");
+  return structuredClone(route);
+}
+function withoutBrokerFields(context) {
+  if (!context) return {};
+  const { routeId: _routeId, dispatchMode: _dispatchMode, runnerId: _runnerId, ...callerFields } = context;
+  return callerFields;
+}
+
+export {
+  DurableAIExecutionBroker
+};
+//# sourceMappingURL=chunk-LYPZPE53.js.map

package/dist/chunk-LYPZPE53.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agentic/ai-broker.ts"],"sourcesContent":["import {\n  createAIExecutionBroker,\n  type AIExecutionCandidate,\n  type AIExecutionDecision,\n  type AIExecutionRequest,\n  type AgentJobKind,\n  type AgentJobRecord,\n} from '@alneas/eaos-core'\nimport type { AtomicSession } from '../plugin-data/atomic'\nimport { createAgentJob, enqueueAgentJob } from './agent-jobs'\nimport type {\n  ServerAgentDispatchMode,\n  ServerAgentExecutionContext,\n  ServerAgentTaskRequest,\n  ServerAgentWorkerType,\n} from './types'\n\n/**\n * Host-advertised AI candidate with server worker and queue/local-runner delivery binding.\n * @see DurableAIExecutionBroker.\n */\nexport interface ServerAIExecutionRoute extends AIExecutionCandidate {\n  /** Executor key bound to the selected host route. */\n  workerType: ServerAgentWorkerType\n  /** Local CLI/MLX candidates must use local-pull; nonlocal candidates cannot use local-pull. */\n  dispatchMode: ServerAgentDispatchMode\n  /** Pin a route to one registered local runner when the host requires it. */\n  runnerId?: string\n}\n\n/**\n * Verified task input before the broker chooses immutable runtime routing fields.\n * @see DurableAIExecutionBroker.plan.\n */\nexport interface AIJobTaskInput {\n  /** Stable task identifier. */\n  id: string\n  /** Verified tenant, required to match routing context. */\n  tenantId: string\n  /** Verified user, required to match routing context. */\n  userId: string\n  /** Human task label forwarded to runtime. */\n  title: string\n  /** Runtime instructions forwarded without domain validation here. */\n  instructions: string\n  /** Optional domain execution context. */\n  context?: Record<string, unknown>\n  /** Optional workflow/tool context; broker-owned routing fields are replaced. */\n  executionContext?: ServerAgentExecutionContext\n  /** Optional runtime timeout in milliseconds, forwarded for executor validation. */\n  timeoutMs?: number\n}\n\n/**\n * Verified routing request, task, and queue deduplication/retry metadata.\n * @see DurableAIExecutionBroker.plan.\n */\nexport interface AIJobSubmission {\n  /** Core execution requirements and verified context used for route allocation. */\n  routing: AIExecutionRequest\n  /** Verified task before worker/routing binding. */\n  task: AIJobTaskInput\n  /** Queue job kind and idempotency partition. */\n  kind: AgentJobKind\n  /** Optional associated workflow instance. */\n  workflowInstanceId?: string\n  /** Optional queue correlation ID; defaults to routing.context.operation. */\n  correlationId?: string\n  /** Optional durable deduplication key; absent uses task execution key then task.id. */\n  idempotencyKey?: string\n  /** Optional job attempt ceiling; defaults to 5 through createAgentJob. */\n  maxAttempts?: number\n}\n\n/**\n * Selected runtime decision and unpersisted or saved queue job.\n * @see DurableAIExecutionBroker.enqueue.\n */\nexport interface AIJobPlan {\n  /** Current selector decision, even when enqueue returns an existing deduplicated job. */\n  decision: AIExecutionDecision\n  /** Created or deduplicated queue record with persisted runtime routing. */\n  job: AgentJobRecord<ServerAgentTaskRequest>\n}\n\n/**\n * Micro2 controller for dynamic model/runtime allocation.\n *\n * It selects only host-advertised routes and persists the selected route in\n * the durable job. It never reads a subscription credential or starts a local\n * process. A local-pull route is later claimed by LocalRunnerPullCoordinator.\n * @remarks Route selection and planning are process-local. The host verifies identity and supplies current candidate availability/policy; authorization, runtime execution, and safe retries remain separate responsibilities.\n * @example\n * ```typescript\n * import { DurableAIExecutionBroker } from \"@alneas/eaos-server/agentic/ai-broker\";\n * export function broker(options: ConstructorParameters<typeof DurableAIExecutionBroker>[0]) {\n *   return new DurableAIExecutionBroker(options);\n * }\n * ```\n */\nexport class DurableAIExecutionBroker {\n  private readonly routesById: ReadonlyMap<string, ServerAIExecutionRoute>\n  private readonly selector: ReturnType<typeof createAIExecutionBroker>\n  private readonly now: () => Date\n\n  /**\n   * Validates and clones server routes and configures the core allocation selector.\n   * @param options - Nonempty routes list; optional policyVersion labels selector decisions and now supplies job timestamps, defaulting to fresh Date.\n   * @throws Invalid/missing routes, incompatible local dispatch bindings, core selector validation, or clone failures.\n   */\n  constructor(options: { \n  /**\n   * Nonempty host-approved execution routes, validated/cloned before configuring the selector; route IDs and runtime dispatch bindings must be compatible.\n   */\n  routes: readonly ServerAIExecutionRoute[]; \n  /**\n   * Optional decision policy label forwarded to the Core selector; omission selects ai-execution-policy-v1.\n   */\n  policyVersion?: string; \n  /**\n   * Optional clock used when constructing agent job records; omission creates a new current Date per call.\n   * @returns A valid Date used for planned job timestamps; clock failures propagate from planning.\n   * @see {@link DurableAIExecutionBroker.plan}\n   */\n  now?: () => Date }) {\n    if (!options || !Array.isArray(options.routes) || options.routes.length === 0) throw new Error('AI execution routes are required')\n    const routes = options.routes.map(validateServerRoute)\n    this.routesById = new Map(routes.map(route => [route.routeId, structuredClone(route)]))\n    this.selector = createAIExecutionBroker({ routes, policyVersion: options.policyVersion })\n    this.now = options.now ?? (() => new Date())\n  }\n\n  /**\n   * Lists registered server route bindings without exposing mutable stored objects.\n   * @returns Cloned route records in registration map order.\n   * @example\n   * ```typescript\n   * import { DurableAIExecutionBroker } from \"@alneas/eaos-server/agentic/ai-broker\";\n   * export function routes(broker: DurableAIExecutionBroker) { return broker.listRoutes(); }\n   * ```\n   */\n  listRoutes(): readonly ServerAIExecutionRoute[] {\n    return [...this.routesById.values()].map(route => structuredClone(route))\n  }\n\n  /**\n   * Selects an eligible host-advertised runtime using the core routing policy.\n   * @param request - Verified AI execution requirements and context.\n   * @returns The core selector decision; no job is persisted or runtime started.\n   * @throws Propagates core routing validation/no-eligible-route errors.\n   * @example\n   * ```typescript\n   * import { DurableAIExecutionBroker } from \"@alneas/eaos-server/agentic/ai-broker\";\n   * import type { AIExecutionRequest } from \"@alneas/eaos-core\";\n   * export function decide(broker: DurableAIExecutionBroker, request: AIExecutionRequest) { return broker.decide(request); }\n   * ```\n   */\n  decide(request: AIExecutionRequest): AIExecutionDecision {\n    return this.selector.decide(request)\n  }\n\n  /**\n   * Selects a route and creates a queue record with host-controlled worker/dispatch/runner bindings.\n   * @param input - Routing and task must have matching tenantId/userId; queue metadata follows AIJobSubmission.\n   * @returns Decision and newly created job; caller-supplied broker route/dispatch/runner execution fields are stripped before selected bindings are written.\n   * @throws Principal mismatch, unavailable route, invalid core routing, clone/hash/clock, or job creation failures.\n   * @remarks No persistence or deduplication occurs until enqueue; repeated plan calls generate different job IDs.\n   * @example\n   * ```typescript\n   * import { DurableAIExecutionBroker } from \"@alneas/eaos-server/agentic/ai-broker\";\n   * import type { AIJobSubmission } from \"@alneas/eaos-server/agentic/ai-broker\";\n   * export function plan(broker: DurableAIExecutionBroker, input: AIJobSubmission) { return broker.plan(input); }\n   * ```\n   */\n  plan(input: AIJobSubmission): AIJobPlan {\n    if (!input?.routing || !input.task || input.routing.context.tenantId !== input.task.tenantId || input.routing.context.userId !== input.task.userId) throw new Error('AI routing context does not match task context')\n    const decision = this.decide(input.routing)\n    const binding = this.routesById.get(decision.route.routeId)\n    if (!binding) throw new Error('Selected AI execution route is not registered')\n    const request: ServerAgentTaskRequest = {\n      ...structuredClone(input.task),\n      workerType: binding.workerType,\n      jobKind: input.kind,\n      executionContext: {\n        ...withoutBrokerFields(input.task.executionContext),\n        routeId: binding.routeId,\n        dispatchMode: binding.dispatchMode,\n        ...(binding.runnerId === undefined ? {} : { runnerId: binding.runnerId }),\n      },\n    }\n    const job = createAgentJob({\n      request,\n      kind: input.kind,\n      workflowInstanceId: input.workflowInstanceId,\n      correlationId: input.correlationId ?? input.routing.context.operation,\n      idempotencyKey: input.idempotencyKey,\n      maxAttempts: input.maxAttempts,\n      now: this.now(),\n    })\n    return { decision, job }\n  }\n\n  /**\n   * Plans routing and atomically inserts or deduplicates the queue job in a caller-owned session.\n   * @param tx - Authorized atomic transaction/session; caller owns commit/rollback.\n   * @param input - Verified routing/task and queue metadata.\n   * @returns Decision plus the newly saved or existing idempotent job.\n   * @throws Planning errors, conflicting deduplication input, corrupt index, or session failures.\n   * @remarks Selection still runs before deduplication; the returned existing job is authoritative for its persisted routing. No runtime execution occurs.\n   * @example\n   * ```typescript\n   * import { DurableAIExecutionBroker } from \"@alneas/eaos-server/agentic/ai-broker\";\n   * import type { AIJobSubmission } from \"@alneas/eaos-server/agentic/ai-broker\";\n   * import type { AtomicSession } from \"@alneas/eaos-server/plugin-data/atomic\";\n   * export async function enqueue(broker: DurableAIExecutionBroker, tx: AtomicSession, input: AIJobSubmission) { return broker.enqueue(tx, input); }\n   * ```\n   */\n  async enqueue(tx: AtomicSession, input: AIJobSubmission): Promise<AIJobPlan> {\n    const plan = this.plan(input)\n    const saved = await enqueueAgentJob(tx, plan.job)\n    return { ...plan, job: saved }\n  }\n}\n\nfunction validateServerRoute(route: ServerAIExecutionRoute): ServerAIExecutionRoute {\n  if (!route || typeof route.workerType !== 'string' || !route.workerType.trim()) throw new Error('Invalid AI route worker type')\n  if (route.dispatchMode === 'local-pull' && route.target !== 'local-subscription-cli' && route.target !== 'local-mlx') throw new Error('Only local routes may use local-pull dispatch')\n  if ((route.target === 'local-subscription-cli' || route.target === 'local-mlx') && route.dispatchMode !== 'local-pull') throw new Error('Local CLI and MLX routes must use local-pull dispatch')\n  return structuredClone(route)\n}\n\nfunction withoutBrokerFields(context: ServerAgentExecutionContext | undefined): ServerAgentExecutionContext {\n  if (!context) return {}\n  const { routeId: _routeId, dispatchMode: _dispatchMode, runnerId: _runnerId, ...callerFields } = context\n  return callerFields\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-NNCCN7JP.js

@@ -0,0 +1,186 @@
+// src/storage/index.ts
+function segment(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value)) throw new Error("Invalid storage scope ID");
+  return value;
+}
+function path(value, prefix = false) {
+  if (typeof value !== "string" || !prefix && !value || /[\\%\x00-\x1f\x7f?#]/.test(value) || value.startsWith("/")) throw new Error("Invalid storage key");
+  const parts = value.split("/");
+  if (prefix && parts.at(-1) === "") parts.pop();
+  if (parts.some((part) => !part || part === "." || part === "..")) throw new Error("Invalid storage key");
+  return value;
+}
+function createTenantStorage(adapter, options) {
+  const tenantId = segment(options.tenantId), pluginId = segment(options.pluginId);
+  const scope = `tenants/${tenantId}/plugins/${pluginId}/`;
+  const authorize = options.authorize;
+  const maxAge = options.maxUrlLifetimeSeconds ?? 300;
+  if (!Number.isInteger(maxAge) || maxAge < 1) throw new Error("Invalid URL lifetime");
+  async function check(operation, keys) {
+    if (await authorize({ tenantId, pluginId, operation, keys: Object.freeze([...keys]) }) !== true) throw new Error("Storage access denied");
+  }
+  function relative(key, prefix = false) {
+    if (!key.startsWith(scope)) throw new Error("Storage returned an object outside the authorized scope");
+    return path(key.slice(scope.length), prefix);
+  }
+  function object(value) {
+    return { ...value, key: relative(value.key) };
+  }
+  function exact(value, key) {
+    const result = object(value);
+    if (result.key !== key) throw new Error("Storage returned an unexpected object");
+    return result;
+  }
+  return Object.freeze({
+    async upload(key, data, settings) {
+      key = path(key);
+      if (settings?.public) throw new Error("Public tenant objects are disabled");
+      const safe = { ...settings, public: false };
+      await check("upload", [key]);
+      return exact(await adapter.upload(scope + key, data, safe), key);
+    },
+    async download(key) {
+      key = path(key);
+      await check("download", [key]);
+      return adapter.download(scope + key);
+    },
+    async delete(key) {
+      key = path(key);
+      await check("delete", [key]);
+      return adapter.delete(scope + key);
+    },
+    async exists(key) {
+      key = path(key);
+      await check("exists", [key]);
+      return adapter.exists(scope + key);
+    },
+    async head(key) {
+      key = path(key);
+      await check("head", [key]);
+      const result = await adapter.head(scope + key);
+      return result ? exact(result, key) : null;
+    },
+    async getUrl(key, settings) {
+      key = path(key);
+      const expiresIn = settings?.expiresIn ?? maxAge;
+      if (settings?.signed === false || !Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > maxAge) throw new Error("Signed URL policy violation");
+      const safe = { ...settings, signed: true, expiresIn };
+      await check("getUrl", [key]);
+      return adapter.getUrl(scope + key, safe);
+    },
+    async list(settings = {}) {
+      const prefix = path(settings.prefix ?? "", true);
+      if (settings.delimiter !== void 0 && settings.delimiter !== "/") throw new Error("Invalid delimiter");
+      let cursor;
+      if (settings.cursor) {
+        try {
+          const data = JSON.parse(Buffer.from(settings.cursor, "base64url").toString());
+          if (data.scope !== scope || data.prefix !== prefix || typeof data.token !== "string") throw new Error();
+          cursor = data.token;
+        } catch {
+          throw new Error("Invalid scoped storage cursor");
+        }
+      }
+      const safe = { ...settings, prefix: scope + prefix, cursor };
+      await check("list", [prefix]);
+      const result = await adapter.list(safe);
+      const objects = result.objects.map(object), prefixes = result.prefixes?.map((key) => relative(key, true));
+      if (objects.some((o) => !o.key.startsWith(prefix)) || prefixes?.some((p) => !p.startsWith(prefix))) throw new Error("Storage returned objects outside the requested prefix");
+      return { objects, prefixes, hasMore: result.hasMore, nextCursor: result.nextCursor ? Buffer.from(JSON.stringify({ scope, prefix, token: result.nextCursor })).toString("base64url") : void 0 };
+    },
+    ...adapter.copy ? { async copy(source, destination) {
+      source = path(source);
+      destination = path(destination);
+      await check("copy", [source, destination]);
+      return exact(await adapter.copy(scope + source, scope + destination), destination);
+    } } : {},
+    ...adapter.move ? { async move(source, destination) {
+      source = path(source);
+      destination = path(destination);
+      await check("move", [source, destination]);
+      return exact(await adapter.move(scope + source, scope + destination), destination);
+    } } : {}
+  });
+}
+
+// src/storage/s3-compatible.ts
+async function createS3CompatibleStorage(config) {
+  if (!["s3", "r2"].includes(config.provider)) throw new Error("Unsupported storage provider");
+  const maxAge = config.maxUrlLifetimeSeconds ?? 300;
+  if (!Number.isInteger(maxAge) || maxAge < 1 || maxAge > 604800) throw new Error("Invalid URL lifetime");
+  if (!config.bucket || !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(config.bucket)) throw new Error("Invalid storage bucket");
+  if (config.provider === "r2" && !/^[a-f0-9]{32}$/i.test(config.accountId)) throw new Error("Invalid R2 account ID");
+  if (config.provider === "s3" && !config.region) throw new Error("Storage region required");
+  if (config.endpoint) {
+    const endpoint = new URL(config.endpoint);
+    if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) throw new Error("Invalid storage endpoint");
+  }
+  const credentials = typeof config.credentials === "function" ? await config.credentials() : config.credentials;
+  if (!credentials.accessKeyId || !credentials.secretAccessKey) throw new Error("Storage credentials required");
+  const { provider, credentials: _credentials, maxUrlLifetimeSeconds: _maxAge, ...settings } = config;
+  const { R2StorageAdapter, S3StorageAdapter } = await import("@alneas/appkit-core/storage");
+  const adapter = provider === "r2" ? new R2StorageAdapter({ ...settings, ...credentials, defaultExpiresIn: maxAge }) : new S3StorageAdapter({ ...settings, ...credentials, defaultExpiresIn: maxAge });
+  return Object.freeze({
+    async upload(key, data, options) {
+      if (options?.public) throw new Error("Public storage uploads are disabled");
+      return adapter.upload(key, data, { ...options, public: false });
+    },
+    download: adapter.download.bind(adapter),
+    delete: adapter.delete.bind(adapter),
+    exists: adapter.exists.bind(adapter),
+    head: adapter.head.bind(adapter),
+    list: adapter.list.bind(adapter),
+    async getUrl(key, options) {
+      const expiresIn = options?.expiresIn ?? maxAge;
+      if (options?.signed === false || !Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > maxAge) throw new Error("Signed URL policy violation");
+      return adapter.getUrl(key, { ...options, signed: true, expiresIn });
+    },
+    ...adapter.copy ? { copy: adapter.copy.bind(adapter) } : {},
+    ...adapter.move ? { move: adapter.move.bind(adapter) } : {}
+  });
+}
+async function createTenantS3CompatibleStorage(config, options) {
+  const adapter = await createS3CompatibleStorage(config);
+  return createTenantStorage(adapter, { ...options, maxUrlLifetimeSeconds: options.maxUrlLifetimeSeconds ?? config.maxUrlLifetimeSeconds });
+}
+function readS3CompatibleStorageConfig(env = process.env) {
+  const provider = env.EAOS_STORAGE_PROVIDER?.trim().toLowerCase();
+  if (!provider) return null;
+  const maxAge = env.EAOS_STORAGE_MAX_URL_SECONDS ? Number(env.EAOS_STORAGE_MAX_URL_SECONDS) : void 0;
+  if (provider === "r2") {
+    const accountId = env.R2_ACCOUNT_ID?.trim() ?? "", bucket = env.R2_BUCKET?.trim() ?? "";
+    const accessKeyId = env.R2_ACCESS_KEY_ID?.trim() ?? "", secretAccessKey = env.R2_SECRET_ACCESS_KEY?.trim() ?? "";
+    if (!accountId || !bucket || !accessKeyId || !secretAccessKey) throw new Error("Incomplete R2 storage environment");
+    return {
+      provider: "r2",
+      accountId,
+      bucket,
+      ...env.R2_ENDPOINT ? { endpoint: env.R2_ENDPOINT.trim() } : {},
+      ...maxAge !== void 0 ? { maxUrlLifetimeSeconds: maxAge } : {},
+      credentials: { accessKeyId, secretAccessKey }
+    };
+  }
+  if (provider === "s3") {
+    const bucket = env.S3_BUCKET?.trim() ?? "", region = env.S3_REGION?.trim() ?? "";
+    const accessKeyId = env.S3_ACCESS_KEY_ID?.trim() ?? "", secretAccessKey = env.S3_SECRET_ACCESS_KEY?.trim() ?? "";
+    if (!bucket || !region || !accessKeyId || !secretAccessKey) throw new Error("Incomplete S3 storage environment");
+    return {
+      provider: "s3",
+      bucket,
+      region,
+      ...env.S3_ENDPOINT ? { endpoint: env.S3_ENDPOINT.trim() } : {},
+      ...env.S3_FORCE_PATH_STYLE === "true" || env.S3_FORCE_PATH_STYLE === "1" ? { forcePathStyle: true } : {},
+      ...maxAge !== void 0 ? { maxUrlLifetimeSeconds: maxAge } : {},
+      credentials: { accessKeyId, secretAccessKey }
+    };
+  }
+  throw new Error("Unsupported storage provider");
+}
+
+export {
+  createS3CompatibleStorage,
+  createTenantS3CompatibleStorage,
+  readS3CompatibleStorageConfig,
+  createTenantStorage
+};
+//# sourceMappingURL=chunk-NNCCN7JP.js.map