@alneas/eaos-server 0.0.0-stage → 0.2.0

package/dist/db-package/db/local-first-sqlite-adapter.d.ts

@@ -0,0 +1,432 @@
+import { DataAccessAdapter, Filter, QueryOptions } from '@alneas/appkit-core/data/types';
+
+/**
+ * @fileoverview Local-First SQLite DataAccessAdapter with Adaptive Sync & WAL Lock Prevention
+ *
+ * Implements @alneas/appkit-core DataAccessAdapter interface.
+ * - Reads/writes locally to SQLite before attempting remote delivery.
+ * - Configures SQLite WAL mode, NORMAL synchronous, and busy_timeout to prevent DB locking.
+ * - Records mutations in an outbox queue (_outbox_queue) with pre-change snapshots for attempted rollback after permanent delivery failure.
+ * - Tracks user access frequency (_access_frequency) to adaptively sync frequently used collections.
+ * - Pulls remote incremental changes from an ORA_ROWSCN-capable upstream within batch transactions.
+ * - Handles window focus & network online lifecycle hooks for seamless just-in-time synchronization.
+ *
+ * @module db/local-first-sqlite-adapter
+ */
+
+/**
+ * Host SQLite operations required by {@link LocalFirstSqliteAdapter}; execution and transaction ownership belong to the host.
+ */
+interface SqliteDriver {
+    /**
+     * Executes SQLite SQL with positional bindings.
+     * @param sql - SQL statement, including transaction control statements.
+     * @param params - Positional values for question-mark placeholders; omitted for parameterless SQL.
+     * @returns Driver-specific execution result, which the adapter does not inspect.
+     * @throws Rejects on driver/database failure; callers determine rollback handling.
+     
+     * @example
+     * ```typescript
+     * import type { SqliteDriver } from "@alneas/eaos-server/db";
+     * export async function inspectConnectedSqlite(driver: SqliteDriver) {
+     *   // The host opens and closes the connection; this statement changes no records.
+     *   return await driver.execute("SELECT 1 AS ready", []);
+     * }
+     * ```
+     */
+    execute(sql: string, params?: any[]): Promise<any>;
+    /**
+     * Selects SQLite rows using positional bindings.
+     * @typeParam T - Row shape expected by the caller; the driver does not establish runtime validation.
+     * @param sql - SELECT statement.
+     * @param params - Positional values, or omitted for parameterless queries.
+     * @returns Matching rows, or an empty array.
+     * @throws Rejects on driver/database failure.
+     
+     * @example
+     * ```typescript
+     * import type { SqliteDriver } from "@alneas/eaos-server/db";
+     * export async function selectConnectedSqlite(driver: SqliteDriver) {
+     *   const rows = await driver.select<{ ready: number }>("SELECT 1 AS ready", []);
+     *   return rows[0]?.ready; // The type argument does not perform runtime validation.
+     * }
+     * ```
+     */
+    select<T = any>(sql: string, params?: any[]): Promise<T[]>;
+}
+/**
+ * Local outbox lifecycle status; successfully synchronized rows are removed by processOutbox.
+ * @see LocalFirstSqliteAdapter.processOutbox.
+ */
+type SyncStatus = 'pending' | 'syncing' | 'synced' | 'failed';
+/**
+ * Local mutation and rollback snapshot awaiting upstream synchronization.
+ * @see LocalFirstSqliteAdapter.processOutbox.
+ */
+interface OutboxItem {
+    /** Outbox row identifier. */
+    id: string;
+    /** Target local/upstream table. */
+    tableName: string;
+    /** Mutation record identifier. */
+    recordId: string;
+    /** INSERT, UPDATE, or DELETE operation forwarded upstream. */
+    operation: 'INSERT' | 'UPDATE' | 'DELETE';
+    /** Mutation data; update retains only the supplied changes. */
+    payload: Record<string, any>;
+    /** Optional pre-mutation row used for rollback; null for inserts or missing snapshots. */
+    previousState?: Record<string, any> | null;
+    /** Persisted synchronization state. */
+    status: SyncStatus;
+    /** Optional most recent persisted error description. */
+    errorMessage?: string;
+    /** Number of recognized transient failures recorded so far. */
+    retryCount: number;
+    /** ISO creation timestamp used for batch ordering. */
+    createdAt: string;
+}
+/**
+ * Permanent synchronization failure notification emitted after local rollback handling.
+ * @see LocalFirstSqliteAdapterOptions.onSyncError.
+ */
+interface SyncErrorEvent {
+    /** Outbox item whose permanent failure caused rollback handling. */
+    item: OutboxItem;
+    /** Underlying synchronization failure. */
+    error: Error;
+    /** True when rollback handling reached the callback; it is not a remote rollback guarantee. */
+    rolledBack: boolean;
+}
+/**
+ * Per-table local counters used to rank adaptive synchronization candidates.
+ * @see LocalFirstSqliteAdapter.recordAccess.
+ */
+interface AccessFrequencyRecord {
+    /** Tracked collection identifier. */
+    table_name: string;
+    /** Accumulated read count. */
+    read_count: number;
+    /** Accumulated write count. */
+    write_count: number;
+    /** ISO timestamp of the most recently recorded access. */
+    last_accessed_at: string;
+}
+/**
+ * Host drivers, sync behavior, and cleanup-sensitive scheduling for {@link LocalFirstSqliteAdapter}.
+ */
+interface LocalFirstSqliteAdapterOptions {
+    /** SQLite driver instance */
+    sqlite: SqliteDriver;
+    /** Cloud upstream adapter (e.g. OracleOrdsAdapter / SupabaseAdapter) */
+    upstream: DataAccessAdapter;
+    /** Optional tenant_id default added only on create when neither tenant_id nor tenantId is supplied; this does not scope reads, updates, deletes, or upstream access. Host authorization remains required. */
+    tenantId?: string;
+    /** Essential master tables that are always synchronized (Tier 1) */
+    essentialTables?: string[];
+    /** Callback fired when an outbox sync fails permanently and triggers a rollback */
+    onSyncError?: (event: SyncErrorEvent) => void;
+    /** Outbox polling interval in milliseconds. Zero disables polling; other falsy values fall back to 5000. @defaultValue 5000 */
+    syncIntervalMs?: number;
+    /** Whether to immediately trigger background sync after local mutation (default: true) */
+    autoSyncOnMutation?: boolean;
+    /** Whether to attach window focus / online event listeners (default: true if in browser/tauri) */
+    enableLifecycleSync?: boolean;
+}
+/**
+ * Persists local mutations and an outbox, then synchronizes with a host-provided upstream adapter.
+ * @remarks Call initSchema before use; it creates metadata only, so provision domain tables separately. Local mutation and outbox insertion are separate writes, so failure may leave an unqueued local change. No tenant authorization is implemented: tenantId is only a create default. Serialize transaction-sensitive operations on the host driver; processOutbox excludes overlapping calls on this instance only. Call destroy to remove timers/listeners; it does not cancel in-flight work or close either driver.
+ * @example
+ * ```typescript
+ * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+ * export async function example(options: LocalFirstSqliteAdapterOptions) {
+ *   // The host supplies an initialized domain schema and authorized upstream adapter.
+ *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+ *   try {
+ *     await adapter.initSchema();
+ *     return await adapter.find("records");
+ *   } finally { adapter.destroy(); }
+ * }
+ * ```
+ */
+declare class LocalFirstSqliteAdapter implements DataAccessAdapter {
+    /** Optional create-time tenant_id fallback captured from options; not a read or mutation authorization filter. */
+    readonly tenantId?: string;
+    private sqlite;
+    private upstream;
+    private onSyncError?;
+    private autoSyncOnMutation;
+    private essentialTables;
+    private syncTimer;
+    private isSyncing;
+    private cleanupListeners?;
+    /**
+     * Captures drivers and starts optional outbox polling and browser lifecycle listeners.
+     * @param options - Host drivers and synchronization settings; see {@link LocalFirstSqliteAdapterOptions}.
+     * @remarks The constructor performs no schema initialization. Timers/listeners start immediately unless disabled; call destroy when the instance is no longer needed.
+     */
+    constructor(options: LocalFirstSqliteAdapterOptions);
+    /**
+     * Initializes SQLite synchronization metadata tables and attempts WAL, NORMAL, and 5000 ms busy-timeout pragmas.
+     * @returns No value; resolves after metadata table creation. Pragma failures are deliberately ignored.
+     * @throws Rejects metadata table creation failures; earlier tables may already exist.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     await adapter.initSchema();
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    initSchema(): Promise<void>;
+    /**
+     * Attaches window focus & network online hooks to trigger synchronization at user activity moments.
+     */
+    private attachLifecycleListeners;
+    /**
+     * Increments a table read or write counter and records the current ISO timestamp.
+     * @param collection - Table name recorded as a metadata value.
+     * @param type - Counter to increment; read contributes weight 2 and write weight 5 in adaptive ranking.
+     * @returns No value; resolves after the counter upsert.
+     * @throws Rejects SQLite failures.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     await adapter.recordAccess("records", "read");
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    recordAccess(collection: string, type: 'read' | 'write'): Promise<void>;
+    /**
+     * Pulls every essential table plus the highest weighted access-frequency tables sequentially.
+     * @param limit - Maximum frequency-ranked tables selected in addition to essential tables; defaults to 8 and is passed to SQLite without additional validation.
+     * @returns Names whose pullChanges calls completed, including tables with no new rows; failed tables are warned and omitted.
+     * @throws Rejects the initial frequency query failure; individual pull failures are caught.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.syncActiveTables(8);
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    syncActiveTables(limit?: number): Promise<string[]>;
+    /**
+     * Queries local SQLite rows and schedules a best-effort read-frequency update.
+     * @typeParam T - Expected local row shape; no runtime schema validation is performed.
+     * @param collection - Local table identifier, quoted by the adapter.
+     * @param filter - AND-combined equality/null or $eq/$gt/$gte/$lt/$lte column conditions; other operator objects are rejected.
+     * @param options - Supports sort, limit, and skip; limit/skip must be nonnegative safe integers. Projection and other options are ignored.
+     * @returns Local rows, or an empty array; remote freshness is not implied.
+     * @throws Rejects unsupported filters, invalid pagination, or SQLite query failures. Access-stat failures are ignored.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.find("records", { active: true }, { limit: 10 });
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    find<T = unknown>(collection: string, filter?: Filter, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Counts local rows matching a filter without pagination.
+     * @param collection - Local table identifier, quoted by the adapter.
+     * @param filter - Same supported AND-combined conditions as find.
+     * @param options - Sort is retained; limit and skip are discarded. Other options are ignored.
+     * @returns Numeric count, or zero if the driver returns no count row.
+     * @throws Rejects unsupported filters or SQLite failures; access-stat failures are ignored.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.count("records");
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    count(collection: string, filter?: Filter, options?: QueryOptions): Promise<number>;
+    /**
+     * Queries a local row by its id column.
+     * @typeParam T - Expected local row shape; no runtime validation is performed.
+     * @param collection - Local table identifier.
+     * @param id - ID value bound to an equality filter.
+     * @param options - find options with limit overridden to 1; skip, if supplied, still applies.
+     * @returns First matching row, or null.
+     * @throws Rejects invalid pagination or SQLite query failures.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.findOne("records", "record-1");
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    findOne<T = unknown>(collection: string, id: string, options?: QueryOptions): Promise<T | null>;
+    /**
+     * Inserts a local record before separately enqueueing its upstream INSERT.
+     * @typeParam T - Expected returned record shape; no runtime validation is performed.
+     * @param collection - Provisioned local table identifier.
+     * @param data - Column values; a truthy id is retained, otherwise an ID is generated. Missing tenant columns may receive the configured tenantId. Object values are JSON-encoded for local SQL.
+     * @param _options - Accepted for DataAccessAdapter compatibility and ignored.
+     * @returns The input record with its chosen ID and optional tenant default, before upstream acknowledgement.
+     * @throws Rejects local SQL, serialization, or enqueue failure; a local insert may already have committed. Background outbox errors are ignored by this call.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.create("records", { title: "Example" });
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    create<T = unknown>(collection: string, data: Record<string, unknown>, _options?: QueryOptions): Promise<T>;
+    /**
+     * Snapshots a local row, updates its columns, and separately enqueues an upstream UPDATE.
+     * @typeParam T - Expected returned merged record shape.
+     * @param collection - Provisioned local table identifier.
+     * @param id - Record ID bound in local SQL and used for upstream update.
+     * @param data - Updated columns; local SQL excludes id but the payload is forwarded unchanged upstream. An empty update can cause a SQLite syntax failure.
+     * @param _options - Accepted for DataAccessAdapter compatibility and ignored.
+     * @returns Snapshot merged with data and the supplied id, even if no local row existed.
+     * @throws Rejects snapshot, local SQL, serialization, or enqueue failures; local changes may already have committed.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.update("records", "record-1", { title: "Changed" });
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    update<T = unknown>(collection: string, id: string, data: Record<string, unknown>, _options?: QueryOptions): Promise<T>;
+    /**
+     * Deletes a local row and separately enqueues upstream deletion with a rollback snapshot.
+     * @typeParam T - Expected deleted record shape.
+     * @param collection - Provisioned local table identifier.
+     * @param id - Record ID used for local and upstream deletion.
+     * @param _options - Accepted for DataAccessAdapter compatibility and ignored.
+     * @returns The previous local record, or an object containing only id when absent.
+     * @throws Rejects snapshot, local delete, or enqueue failures; local deletion may already have committed.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.delete("records", "record-1");
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    delete<T = unknown>(collection: string, id: string, _options?: QueryOptions): Promise<T>;
+    /**
+     * Pulls incremental remote changes from Oracle ADB using ORA_ROWSCN cursor within a batch transaction.
+     *
+     * @param collection - Provisioned local table whose upstream supports ORA_ROWSCN filtering, ordering, and projection.
+     * @returns Number of remote rows upserted, or zero when no changes were returned.
+     * @throws Rejects upstream or local SQL failures; an opened local transaction is rolled back best-effort on upsert/cursor failure.
+     * @remarks Remote deletes are not discovered by this pull. No per-table synchronization lock prevents overlapping pulls or concurrent host transactions.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     return await adapter.pullChanges("records");
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    pullChanges(collection: string): Promise<number>;
+    /**
+     * Background Outbox Worker:
+     * Processes at most 20 pending mutations in creation order, pushes upstream, and attempts rollback for non-network failures.
+     * @returns No value; resolves after one batch, or immediately if this instance already has a batch running.
+     * @throws Rejects metadata reads, malformed persisted JSON, or error-handling SQL failures. Ordinary upstream failures are recorded or rolled back rather than rejected.
+     * @remarks Recognized network failures return rows to pending and increment retry_count; no delay/backoff is applied here. Other failures attempt local snapshot rollback and mark failed; rollback/callback errors are logged. Remote success followed by local queue-delete failure may leave an uncertain delivery outcome. There is no cross-instance lease or deduplication.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     await adapter.processOutbox();
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    processOutbox(): Promise<void>;
+    /**
+     * Rolls back a failed mutation in local SQLite using its previousState snapshot.
+     */
+    private rollbackItem;
+    private enqueueOutbox;
+    private insertLocal;
+    private updateLocal;
+    private upsertLocal;
+    private buildSelectQuery;
+    private escapeId;
+    /**
+     * Stops this instance's polling timer and removes its browser focus/online listeners.
+     * @returns No value; repeated calls are safe. In-flight synchronization continues and drivers remain open.
+     * @example
+     * ```typescript
+     * import { LocalFirstSqliteAdapter, type LocalFirstSqliteAdapterOptions } from "@alneas/eaos-server/db/local-first-sqlite-adapter";
+     * export async function example(options: LocalFirstSqliteAdapterOptions) {
+     *   // The host supplies an initialized domain schema and authorized upstream adapter.
+     *   const adapter = new LocalFirstSqliteAdapter({ ...options, syncIntervalMs: 0, enableLifecycleSync: false });
+     *   try {
+     *     await adapter.initSchema();
+     *     adapter.destroy();
+     *   } finally { adapter.destroy(); }
+     * }
+     * ```
+     */
+    destroy(): void;
+}
+
+export { LocalFirstSqliteAdapter };
+export type { AccessFrequencyRecord, LocalFirstSqliteAdapterOptions, OutboxItem, SqliteDriver, SyncErrorEvent, SyncStatus };

package/dist/db-package/db/local-first-sqlite-adapter.js

@@ -0,0 +1,7 @@
+import {
+  LocalFirstSqliteAdapter
+} from "../../chunk-VISRDVTK.js";
+export {
+  LocalFirstSqliteAdapter
+};
+//# sourceMappingURL=local-first-sqlite-adapter.js.map

package/dist/db-package/db/local-first-sqlite-adapter.js.map

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

package/dist/db-package/index.d.ts

@@ -0,0 +1,7 @@
+export * from '@alneas/eaos-core/contracts/data-contracts';
+export * from '@alneas/eaos-core/migration-types';
+export { MigrationAggregator, SchemaSource } from './migration/aggregator.js';
+export { AccessFrequencyRecord, LocalFirstSqliteAdapter, LocalFirstSqliteAdapterOptions, OutboxItem, SqliteDriver, SyncErrorEvent, SyncStatus } from './db/local-first-sqlite-adapter.js';
+export { ConnectionStats, DatabaseAdapter, TenantSessionContext } from '@alneas/eaos-core/db';
+import '@alneas/eaos-core/plugin-sdk/types';
+import '@alneas/appkit-core/data/types';

package/dist/db-package/index.js

@@ -0,0 +1,16 @@
+import "../chunk-JT6BRGQM.js";
+import {
+  MigrationAggregator
+} from "../chunk-5WOZWPZA.js";
+import {
+  LocalFirstSqliteAdapter
+} from "../chunk-VISRDVTK.js";
+
+// src/db-package/index.ts
+export * from "@alneas/eaos-core/contracts/data-contracts";
+export * from "@alneas/eaos-core/migration-types";
+export {
+  LocalFirstSqliteAdapter,
+  MigrationAggregator
+};
+//# sourceMappingURL=index.js.map

package/dist/db-package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/db-package/index.ts"],"sourcesContent":["export * from '@alneas/eaos-core/contracts/data-contracts'\nexport * from '@alneas/eaos-core/migration-types'\nexport * from './migration/index'\nexport * from './db/local-first-sqlite-adapter'\nexport type { DatabaseAdapter, TenantSessionContext, ConnectionStats } from '@alneas/eaos-core/db'\n"],"mappings":";;;;;;;;;AAAA,cAAc;AACd,cAAc;","names":[]}

package/dist/db-package/migration/aggregator.d.ts

@@ -0,0 +1,86 @@
+import { DataContract } from '@alneas/eaos-core/contracts/data-contracts';
+import { PluginManifest } from '@alneas/eaos-core/plugin-sdk/types';
+
+/**
+ * Legacy table-schema input collected for migration text generation.
+ * @see MigrationAggregator for a complete usage example.
+ */
+interface SchemaSource {
+    /** Plugin ID, or data:{contractId} for resolved data contracts. */
+    pluginId: string;
+    /** Optional display label used in generated SQL comments. */
+    pluginName?: string;
+    /** Optional extension ID appended to the source identifier. */
+    extensionId?: string;
+    /** Sort order from the plugin manifest; defaults to 999 for plugin schemas. */
+    migrationOrder?: number;
+    /** Legacy tables/columns schema; canonical x-db/$defs schemas require reviewed lifecycle migrations instead. */
+    schemaJson: Record<string, any>;
+}
+/**
+ * Collects plugin schema sources and renders legacy PostgreSQL or Oracle DDL text.
+ * @remarks Generation never executes SQL. Schema identifiers, defaults, and comments are interpolated from trusted schema inputs; review generated SQL before applying it. Canonical data-contract JSON Schema requires reviewed lifecycle migrations rather than these legacy converters.
+ * @example
+ * ```typescript
+ * import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
+ * const aggregator = new MigrationAggregator([]);
+ * console.log(aggregator.generatePostgres([]));
+ * ```
+ */
+declare class MigrationAggregator {
+    private plugins;
+    private dataContracts;
+    /**
+     * Captures plugin manifests and available data contracts for later collection.
+     * @param plugins - Manifests consulted on every collection call; the array is retained rather than cloned.
+     * @param dataContracts - Available contracts used to resolve manifest requirements; defaults to none and is retained.
+     */
+    constructor(plugins: PluginManifest[], dataContracts?: DataContract[]);
+    /**
+     * Collects resolved data contracts first, then plugin and extension schemas by migration order.
+     * @param resolveSchema - Called with plugin ID and optional extension ID; returns a legacy schema or null to skip it. Plugin schemas declaring data contracts skip the plugin-level callback, but extensions are still resolved.
+     * @returns Ordered schema sources; manifests with equal order retain their sort order and missing callback results are omitted.
+     * @throws Propagates contract resolution or callback errors.
+     * @example
+     * ```typescript
+     * import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
+     * const aggregator = new MigrationAggregator([]);
+     * console.log(aggregator.collectSchemas(() => null)); // []
+     * ```
+     */
+    collectSchemas(resolveSchema: (pluginId: string, extensionId?: string) => Record<string, any> | null): SchemaSource[];
+    /**
+     * Renders PostgreSQL table DDL and tenant_id row-level-security policies as text.
+     * @param sources - Trusted legacy schemas rendered in supplied order. Every table must declare tenant_id not explicitly nullable.
+     * @param dbDriver - Label included in SQL comments only; defaults to postgres and does not change dialect.
+     * @returns SQL text with a generated timestamp, CREATE TABLE IF NOT EXISTS, and tenant policies using app.current_tenant as UUID.
+     * @throws For canonical x-db/$defs schemas or missing/nullable tenant_id columns.
+     * @remarks The host must set app.current_tenant appropriately and review/apply SQL separately.
+     * @example
+     * ```typescript
+     * import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
+     * const aggregator = new MigrationAggregator([]);
+     * console.log(aggregator.generatePostgres([]));
+     * ```
+     */
+    generatePostgres(sources: SchemaSource[], dbDriver?: string): string;
+    /**
+     * Renders legacy Oracle table DDL as text.
+     * @param sources - Trusted legacy schemas rendered in supplied order; every table must declare tenant_id not explicitly nullable.
+     * @returns SQL text with a generated timestamp and CREATE TABLE statements; no VPD policies or default clauses are emitted by this converter.
+     * @throws For canonical x-db/$defs schemas or missing/nullable tenant_id columns.
+     * @remarks Applying SQL and enforcing Oracle tenant isolation remain host responsibilities.
+     * @example
+     * ```typescript
+     * import { MigrationAggregator } from "@alneas/eaos-server/db/migration/aggregator";
+     * const aggregator = new MigrationAggregator([]);
+     * console.log(aggregator.generateOracle([]));
+     * ```
+     */
+    generateOracle(sources: SchemaSource[]): string;
+    private convertJsonSchemaToPostgresSql;
+    private convertJsonSchemaToOracleSql;
+}
+
+export { MigrationAggregator };
+export type { SchemaSource };

package/dist/db-package/migration/aggregator.js

@@ -0,0 +1,7 @@
+import {
+  MigrationAggregator
+} from "../../chunk-5WOZWPZA.js";
+export {
+  MigrationAggregator
+};
+//# sourceMappingURL=aggregator.js.map

package/dist/db-package/migration/aggregator.js.map

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

package/dist/db-package/migration/index.d.ts

@@ -0,0 +1,3 @@
+export { MigrationAggregator, SchemaSource } from './aggregator.js';
+import '@alneas/eaos-core/contracts/data-contracts';
+import '@alneas/eaos-core/plugin-sdk/types';

package/dist/db-package/migration/index.js

@@ -0,0 +1,8 @@
+import "../../chunk-JT6BRGQM.js";
+import {
+  MigrationAggregator
+} from "../../chunk-5WOZWPZA.js";
+export {
+  MigrationAggregator
+};
+//# sourceMappingURL=index.js.map

package/dist/db-package/migration/index.js.map

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