@lossless.org/client 0.1.0

package/readme.md

@@ -0,0 +1,157 @@
+# @lossless.org/client
+
+One TypeScript client for lossless.org NoSQLDB, SQLDB and ObjectStorage, with MongoDB, MariaDB, ClickHouse and S3 protocol adapters. `LosslessOrgClient` owns named connections and provides `nosqldb()`, `sqldb()` and `objectstorage()` interfaces. Server engines remain separate packages; this client never starts a database or creates a bucket implicitly.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Install and connect
+
+```sh
+pnpm add @lossless.org/client
+```
+
+```ts
+import { LosslessOrgClient } from '@lossless.org/client';
+
+const client = new LosslessOrgClient({
+  nosqldb: {
+    app: { backend: 'mongodb', url: process.env.MONGODB_URL!, database: 'app' },
+  },
+  sqldb: {
+    primary: { backend: 'mariadb', host: process.env.SQL_HOST!, database: 'app',
+      user: process.env.SQL_USER!, password: process.env.SQL_PASSWORD! },
+    analytics: { backend: 'clickhouse', url: process.env.CLICKHOUSE_URL!, database: 'app',
+      username: process.env.CLICKHOUSE_USER!, password: process.env.CLICKHOUSE_PASSWORD! },
+  },
+  objectstorage: {
+    assets: { backend: 's3', endpoint: process.env.S3_ENDPOINT!, region: 'us-east-1',
+      credentials: { accessKeyId: process.env.S3_ACCESS_KEY!, secretAccessKey: process.env.S3_SECRET_KEY! },
+      readinessBucket: 'existing-assets' },
+  },
+});
+
+await client.connect({ timeoutMs: 30_000 });
+try {
+  const primary = client.sqldb('primary'); // SqlConnection
+  const analytics = client.sqldb('analytics'); // ClickHouseConnection
+  const rows = await primary.query<{ id: bigint }>({
+    sql: 'SELECT id FROM accounts WHERE email = ?', values: ['alice@example.com'],
+  }, { maxRows: 100 });
+  for await (const row of analytics.stream<{ temperature: number }>({
+    sql: 'SELECT temperature FROM readings WHERE device = {device:String}',
+    values: { device: 'ssd-1' },
+  })) {
+    // Process each row before requesting more; filtering happens on the server.
+  }
+  const readiness = await client.ready();
+} finally {
+  await client.close();
+}
+```
+
+Select `nosqldb`, `sqldb` or `objectstorage` as the backend for the corresponding lossless.org server. An engine profile declares capabilities; it does not translate unsupported SQL or add backend features. SQLDB requires engine version 0.2.3 or later for pooled connection reset and parameterless prepared statements. It has a smaller SQL/type subset than MariaDB, and does not currently support TLS, savepoints or `ALTER TABLE`. ClickHouse uses its HTTP protocol and SQL dialect. There are no cross-backend transactions or automatic replication.
+
+Literal connection names and backend discriminators determine the return types. Each client owns the connections it constructs. `connect()` probes databases without changing their schemas. S3 construction is local; `ready()` checks an explicitly configured existing bucket and returns `readiness_bucket_required` if none was supplied. `close()` is idempotent, stops admission, cancels owned SQL operations, closes pools and joins final metrics-writer flushes. Create a new aggregate client after failure or close.
+
+## Interfaces
+
+| Import | API |
+| --- | --- |
+| `@lossless.org/client` | `LosslessOrgClient`, configuration, capabilities, readiness, `LosslessClientError` |
+| `@lossless.org/client/nosqldb` | Migrated SmartData models, decorators, collections, cursors, sessions, exact persistence and administration; `NoSqlConnection` |
+| `@lossless.org/client/sqldb` | `SqlConnection`, `SqlTransaction`, `SqlTable`, `ClickHouseConnection`, `SmartClickHouseDb`, tables, query builders, `TimeDataTable`, `MetricWriter` |
+| `@lossless.org/client/objectstorage` | Migrated `SmartBucket`, buckets, directories, files, metadata, watchers, exact operations; `ObjectStorageConnection` |
+| `@lossless.org/client/testsupport` | Explicit disposable-database testing helpers |
+
+Family imports preserve the established SmartData and SmartBucket names and constructors. Their implementations live here; the client does not depend on the old packages. The aggregate loads only configured families. Direct family entry points do not initialize unrelated connections.
+
+## Relational SQL
+
+`SqlConnection` uses the official MariaDB connector for parameters, protocol, TLS and decoding. This client owns cancellable admission and TCP sockets from authentication onward. A transaction holds one physical session; releasing a session resets its state before reuse.
+
+- `execute({ sql, values }, options)` returns `affectedRows`, optional exact `insertId: bigint`, and `completion: 'acknowledged'`. Use it for statements that return an update result.
+- `query<Row>(statement, options)` materializes at most 10,000 rows and 16 MiB by default. Set `maxRows` and `maxBytes` explicitly to change those limits. Overflow rejects with `result_limit` and closes the stream.
+- `stream<Row>(statement, options)` iterates rows with backpressure. Early return, timeout, cancellation and connection shutdown close its owned stream/socket.
+- `insert(table, iterable, options)` accepts iterable or async-iterable rows with the same columns, batching at 500 rows/4 MiB by default. Batches commit independently. A later failure reports `partial_write` with acknowledged rows, or `ambiguous_write` if the current batch outcome is unknown. Use a transaction with explicit statements for atomic multi-statement writes.
+- `transaction(async tx => ..., options)` joins an outstanding final transaction operation before commit. Await each operation; concurrent operations on one transaction are rejected. A thrown callback rolls back when the session is still connected. An interrupted commit has an unknown outcome.
+- `table<Row>(name)` handles an existing table with bound equality/null selectors, typed `query`, `stream`, `insert`, `update` and `delete`. Empty mutation selectors and `undefined` selector values are rejected. Schema creation is explicit SQL.
+
+Values use placeholders; identifiers use a separate quoting function. Raw SQL text is trusted application code. A result generic is a caller-declared shape, not static validation of arbitrary SQL.
+
+MariaDB returns `BIGINT` as `bigint`, `DECIMAL` as a string, binary columns as `Buffer`, SQL null as `null`, and dates/times as strings. Fractional timestamp strings retain server precision. JavaScript `Date` inputs bind in UTC with millisecond precision; MariaDB sessions use UTC. Exact fractional values beyond milliseconds should be supplied as strings. Unsafe integer numbers, non-finite numbers, invalid dates and unsupported parameter objects are rejected; use `bigint` or decimal strings for exact large values. SQLDB's supported scalar types follow its engine contract.
+
+## ClickHouse and metrics
+
+`ClickHouseConnection` uses the official streaming HTTP connector. `stream()` consumes `JSONEachRow` batches without buffering the complete response. `query()` applies the same materialization limits as relational SQL. `insert()` streams an iterable with a default 4 MiB per-row limit and backpressure. It does not make a large insert atomic; a failed insert may have stored part or all of the input. JavaScript JSON row values must be serializable; represent 64-bit input integers as decimal strings. `Int64`/`UInt64` and decimal results are returned as strings; decimal formatting follows the server and may omit trailing zeros. Binary data needs an explicit application encoding. Date/time strings follow the column's ClickHouse type and timezone.
+
+`execute()` waits for server response completion and requests synchronous mutations, returning a query ID and acknowledged completion. It does not invent relational transactions for ClickHouse. Named parameters use ClickHouse syntax, such as `{device:String}`. Identifiers are quoted separately, including literal dots and backslashes.
+
+`connection.metrics` exposes the migrated table/query features. Canonical `metrics.createTable()` defaults `autoSchemaEvolution` to false; preparation and schema changes are explicit. Standalone `SmartClickHouseDb` retains its existing opt-in startup/schema behavior for migrating applications.
+
+```ts
+const table = await client.sqldb('analytics').metrics.createTable<{ id: number; temperature: number }>({
+  tableName: 'readings', orderBy: 'id',
+  columns: [{ name: 'id', type: 'UInt32' }, { name: 'temperature', type: 'Float64' }],
+});
+const writer = table.createInsertStream({ batchSize: 500, maxBatchBytes: 4 * 1024 * 1024 });
+await writer.write({ id: 1, temperature: 38.5 });
+await writer.close(); // Joins the final server acknowledgement; rejects on failure.
+```
+
+Await every writer `write()` for backpressure. `flush()` and `close()` propagate errors, including background flush failures. Client close flushes owned writers before closing the connection. Timestamp-only polling watches cannot guarantee delivery of equal-timestamp or late rows and explicitly report `unsupported_capability`.
+
+SQLDB advanced object metrics and disk-resident analytical scans remain unavailable. The client does not download objects to discover nested paths or aggregate them. Automatic deep-path indexing, correlated array predicates, expiry-driven path retirement and terabyte-scale storage require the corresponding qualified engine capability.
+
+## Budgets, errors and capabilities
+
+New SQL methods accept `signal` and a total `timeoutMs` (30 seconds by default, including pool admission). Read cancellation closes owned transport resources. User-provided iterators receive `return()` on cancellation; their own pending I/O must also cooperate with the caller's signal. JavaScript cannot forcibly interrupt an arbitrary promise or transaction callback. Expiry revokes the transaction handle, so a callback resuming later cannot dispatch a write.
+
+`LosslessClientError` provides a safe outer message, a code, optional `backendCode`, `retryability`, `outcome` and acknowledged-row evidence. `cause` preserves the original error and can contain statement values; do not log it indiscriminately. The taxonomy includes invalid arguments, unsupported capability, authentication, conflict, timeout, cancellation, result limits, backend failure, partial writes and unknown write outcomes. There are no automatic write retries. A transient hint never establishes that retrying an ambiguous write is safe.
+
+Migrated document and object APIs retain their existing typed errors and exact-operation evidence. Their established per-operation timeout/ownership contracts continue to apply. `capabilities` distinguishes `available`, `unsupported` and `unknown`; MongoDB transaction/change-stream availability still depends on deployment topology. NoSQLDB change streams are explicitly unsupported. S3 exact-operation capability tests remain explicit and require owned disposable resources.
+
+## Migrating existing applications
+
+Replace imports and the corresponding manifest dependency:
+
+| Previous package | New import |
+| --- | --- |
+| `@push.rocks/smartdata` | `@lossless.org/client/nosqldb` |
+| `@push.rocks/smartdata/testsupport` | `@lossless.org/client/testsupport` |
+| `@push.rocks/smartbucket` | `@lossless.org/client/objectstorage` |
+| `@push.rocks/smartclickhouse` | `@lossless.org/client/sqldb` |
+
+SmartData persisted identities, decorator symbols, BSON/null/undefined behavior and exact persistence contracts are retained. Existing normal application access stays through those public model APIs; direct driver access belongs to this foundation or explicit versioned migrations.
+
+ObjectStorage retains companion `<key>.metadata` objects and `.trash/<encoded-original-key>` layouts. Existing buffer/replay helpers, list-array methods and watcher state materialize data and are outside the new streaming-memory guarantee. Metadata locks are advisory, not atomic distributed locks; directory move remains unsupported. The `getStorageClient()` migration escape hatch is retained. No readiness call creates or deletes a bucket.
+
+SmartClickHouse migration changes: replace RxJS `next/complete` insertion with awaited writer `write/close`; join database close during application shutdown. Materialized SQL reads now have explicit limits. Query-builder `toSQL()` contains placeholders; use `toStatement()` or pass its `parameters` with the SQL. Watch APIs reject the unsupported continuation guarantee. Insert errors always reach the caller. Existing stored dotted-column names remain unchanged. Original API documentation and licenses are preserved in the repository under [docs/source](https://code.foss.global/lossless.org/client/src/branch/main/docs/source).
+
+## Verification
+
+`pnpm build` builds production declarations. `pnpm test` checks aggregate lifecycle and writers. `pnpm run test:nosqldb`, `test:mongodb`, `test:objectstorage` and `test:sqldb` exercise isolated backends. Wrappers own and remove their disposable servers, containers and data directories. Never supply a production database or bucket to these destructive suites.
+
+Qualification includes NoSQLDB 8.0.2, MongoDB 8.0.26 replica sets, ObjectStorage 10.1.0, SQLDB 0.2.3, MariaDB 11.8 and ClickHouse 25.8. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository [license file](./license.md).
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@lossless.org/client',
+  version: '0.1.0',
+  description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
+}

package/ts/classes.losslessorgclient.ts

@@ -0,0 +1,104 @@
+import * as plugins from './plugins.js';
+import type { NoSqlConnection, INoSqlConnectionOptions } from './nosqldb/classes.connection.js';
+import type { ObjectStorageConnection, IObjectStorageConnectionOptions } from './objectstorage/classes.connection.js';
+import type { SqlConnection } from './sqldb/classes.sqlconnection.js';
+import type { ClickHouseConnection } from './sqldb/classes.clickhouseconnection.js';
+import type { ISqlConnectionOptions, IClickHouseConnectionOptions } from './sqldb/interfaces.js';
+import type { IOperationOptions, IReadiness } from './core/interfaces.js';
+import { LosslessClientError } from './core/classes.error.js';
+import { Operation } from './core/classes.operation.js';
+
+export interface ILosslessOrgClientOptions {
+  nosqldb?: Record<string, INoSqlConnectionOptions>;
+  sqldb?: Record<string, ISqlConnectionOptions | IClickHouseConnectionOptions>;
+  objectstorage?: Record<string, IObjectStorageConnectionOptions>;
+}
+type TSqlFor<Options> = Options extends { backend: 'clickhouse' } ? ClickHouseConnection : SqlConnection;
+type TResource = NoSqlConnection | ObjectStorageConnection | SqlConnection | ClickHouseConnection;
+
+/** Named connections with one lifecycle; engines and persisted domain semantics stay separate. */
+export class LosslessOrgClient<const Options extends ILosslessOrgClientOptions = ILosslessOrgClientOptions> {
+  private readonly resources = new Map<string, TResource>();
+  private connecting?: Promise<void>;
+  private closing?: Promise<void>;
+  private connectOperation?: Operation;
+  private state: 'initial' | 'connecting' | 'connected' | 'failed' | 'closing' | 'closed' = 'initial';
+
+  constructor(public readonly options: Options) {}
+
+  public connect(options: IOperationOptions = {}): Promise<void> {
+    if (this.state === 'connected') return Promise.resolve();
+    if (this.state === 'connecting' && this.connecting) return this.connecting;
+    if (this.state !== 'initial') return Promise.reject(new LosslessClientError('closed', 'Create a new client after failure or close.'));
+    this.connectOperation = new Operation(options);
+    this.state = 'connecting';
+    const operation = this.connectOperation;
+    this.connecting = (async () => {
+      try {
+        for (const [name, config] of Object.entries(this.options.nosqldb ?? {})) {
+          operation.check();
+          const { NoSqlConnection } = await plugins.loadNoSql();
+          const connection = new NoSqlConnection(config);
+          this.resources.set(`nosqldb:${name}`, connection);
+          await connection.connect({ signal: operation.signal });
+        }
+        for (const [name, config] of Object.entries(this.options.sqldb ?? {})) {
+          operation.check();
+          const connection = config.backend === 'clickhouse'
+            ? new (await plugins.loadClickHouse()).ClickHouseConnection(config)
+            : new (await plugins.loadSql()).SqlConnection(config);
+          this.resources.set(`sqldb:${name}`, connection);
+          await connection.connect({ signal: operation.signal });
+          operation.check();
+        }
+        for (const [name, config] of Object.entries(this.options.objectstorage ?? {})) {
+          operation.check();
+          const { ObjectStorageConnection } = await plugins.loadObjects();
+          this.resources.set(`objectstorage:${name}`, new ObjectStorageConnection(config));
+        }
+        operation.check();
+        this.state = 'connected';
+      } catch (error) {
+        const cleanup = await Promise.allSettled([...this.resources.values()].map(resource => resource.close()));
+        this.state = 'failed';
+        const errors = cleanup.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+        if (errors.length) throw new AggregateError([error, ...errors], 'Client connection and cleanup failed.');
+        throw error;
+      } finally { operation.dispose(); this.connectOperation = undefined; }
+    })();
+    void this.connecting.finally(() => { this.connecting = undefined; }).catch(() => {});
+    return this.connecting;
+  }
+
+  private get(family: string, name: string): TResource {
+    if (this.state !== 'connected') throw new LosslessClientError('not_connected', 'Call and await client.connect() first.');
+    const resource = this.resources.get(`${family}:${name}`);
+    if (!resource) throw new LosslessClientError('invalid_argument', `Unknown ${family} connection: ${name}`);
+    return resource;
+  }
+  public nosqldb<Name extends keyof NonNullable<Options['nosqldb']> & string>(name: Name): NoSqlConnection {
+    return this.get('nosqldb', name) as NoSqlConnection;
+  }
+  public sqldb<Name extends keyof NonNullable<Options['sqldb']> & string>(name: Name): TSqlFor<NonNullable<Options['sqldb']>[Name]> {
+    return this.get('sqldb', name) as TSqlFor<NonNullable<Options['sqldb']>[Name]>;
+  }
+  public objectstorage<Name extends keyof NonNullable<Options['objectstorage']> & string>(name: Name): ObjectStorageConnection {
+    return this.get('objectstorage', name) as ObjectStorageConnection;
+  }
+  public async ready(options: IOperationOptions = {}): Promise<Record<string, IReadiness>> {
+    if (this.state !== 'connected') throw new LosslessClientError('not_connected', 'Client is not connected.');
+    return Object.fromEntries(await Promise.all([...this.resources].map(async ([name, resource]) => [name, await resource.ready(options)])));
+  }
+  public close(): Promise<void> {
+    return this.closing ??= (async () => {
+      this.state = 'closing';
+      this.connectOperation?.cancel();
+      await this.connecting?.catch(() => {});
+      const result = await Promise.allSettled([...this.resources.values()].map(resource => resource.close()));
+      const errors = result.flatMap(item => item.status === 'rejected' ? [item.reason] : []);
+      if (errors.length) throw new AggregateError(errors, 'Client cleanup failed.');
+      this.resources.clear();
+      this.state = 'closed';
+    })();
+  }
+}

package/ts/core/classes.error.ts

@@ -0,0 +1,31 @@
+import type { TClientErrorCode } from './interfaces.js';
+
+export class LosslessClientError extends Error {
+  public readonly backendCode?: string;
+  /** A transient cause is a hint, never permission to retry an ambiguous mutation. */
+  public readonly retryability: 'transient' | 'permanent' | 'unknown';
+  public readonly outcome: 'unknown' | 'partial' | undefined;
+  public readonly acknowledgedRows?: number;
+  constructor(public readonly code: TClientErrorCode, message: string,
+    options?: ErrorOptions & { backendCode?: string; retryability?: 'transient' | 'permanent' | 'unknown'; acknowledgedRows?: number }) {
+    super(message, options);
+    this.name = 'LosslessClientError';
+    this.backendCode = options?.backendCode;
+    this.retryability = options?.retryability ?? 'unknown';
+    this.outcome = code === 'ambiguous_write' ? 'unknown' : code === 'partial_write' ? 'partial' : undefined;
+    this.acknowledgedRows = options?.acknowledgedRows;
+  }
+}
+
+/** Safe outer message; the original backend error remains available explicitly through cause. */
+export const backendError = (error: unknown): LosslessClientError => {
+  if (error instanceof LosslessClientError) return error;
+  const details = error && typeof error === 'object' ? error as Record<string, unknown> : {};
+  const code = String(details.code ?? details.errno ?? '');
+  const authentication = ['ER_ACCESS_DENIED_ERROR', 'ER_DBACCESS_DENIED_ERROR', '1045', '1044', '516'].includes(code);
+  const conflict = ['ER_DUP_ENTRY', 'ER_LOCK_DEADLOCK', 'ER_LOCK_WAIT_TIMEOUT', '1062', '1213', '1205'].includes(code);
+  const transient = ['ER_LOCK_DEADLOCK', 'ER_LOCK_WAIT_TIMEOUT', '1213', '1205', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT'].includes(code);
+  return new LosslessClientError(authentication ? 'authentication' : conflict ? 'conflict' : 'backend_error',
+    authentication ? 'Backend authentication failed.' : conflict ? 'Backend operation conflicted.' : 'Backend operation failed.',
+    { cause: error, backendCode: code || undefined, retryability: transient ? 'transient' : authentication ? 'permanent' : 'unknown' });
+};

package/ts/core/classes.operation.ts

@@ -0,0 +1,60 @@
+import { LosslessClientError } from './classes.error.js';
+import type { IOperationOptions } from './interfaces.js';
+
+/** Owns one deadline and abort listener; callers join resource cleanup before disposal. */
+export class Operation {
+  public readonly controller = new AbortController();
+  public get signal(): AbortSignal { return this.controller.signal; }
+  private readonly timer: ReturnType<typeof setTimeout>;
+  private readonly upstream?: AbortSignal;
+  private readonly onAbort = () => this.cancel(new LosslessClientError('cancelled', 'Operation cancelled.'));
+
+  constructor(options: IOperationOptions = {}, defaultTimeoutMs = 30_000) {
+    const timeout = options.timeoutMs ?? defaultTimeoutMs;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 86_400_000) {
+      throw new LosslessClientError('invalid_argument', 'timeoutMs must be an integer between 1 and 86400000.');
+    }
+    this.upstream = options.signal;
+    this.upstream?.addEventListener('abort', this.onAbort, { once: true });
+    this.timer = setTimeout(() => this.cancel(new LosslessClientError('timeout', 'Operation deadline exceeded.')), timeout);
+    this.timer.unref();
+    if (this.upstream?.aborted) this.onAbort();
+  }
+
+  public check(): void { if (this.signal.aborted) throw this.signal.reason; }
+  /** Revoke admission while waiting for caller code. This cannot interrupt arbitrary JavaScript. */
+  public async wait<Result>(task: PromiseLike<Result>): Promise<Result> {
+    const aborted = Promise.withResolvers<never>();
+    const abort = () => aborted.reject(this.signal.reason);
+    this.signal.addEventListener('abort', abort, { once: true });
+    if (this.signal.aborted) abort();
+    try { return await Promise.race([task, aborted.promise]); }
+    finally { this.signal.removeEventListener('abort', abort); }
+  }
+  public async *iterate<Row>(rows: AsyncIterable<Row> | Iterable<Row>): AsyncGenerator<Row> {
+    const asyncRows = rows as AsyncIterable<Row>;
+    const iterator = asyncRows[Symbol.asyncIterator]?.() ?? (rows as Iterable<Row>)[Symbol.iterator]?.();
+    if (!iterator) throw new LosslessClientError('invalid_argument', 'Insert input must be iterable.');
+    let completed = false;
+    try {
+      while (true) {
+        this.check();
+        const result = await this.wait(Promise.resolve(iterator.next()));
+        if (result.done) { completed = true; return; }
+        this.check();
+        yield result.value;
+      }
+    } finally {
+      // Request source cleanup even after cancellation. A caller-owned producer must cooperate
+      // with the supplied signal to stop its own pending I/O; no backend lease remains attached.
+      if (!completed && iterator.return) await this.wait(Promise.resolve(iterator.return()));
+    }
+  }
+  public cancel(reason = new LosslessClientError('closed', 'Connection closed.')): void {
+    this.controller.abort(reason);
+  }
+  public dispose(): void {
+    clearTimeout(this.timer);
+    this.upstream?.removeEventListener('abort', this.onAbort);
+  }
+}

package/ts/core/interfaces.ts

@@ -0,0 +1,24 @@
+export type TBackend = 'nosqldb' | 'mongodb' | 'sqldb' | 'mariadb' | 'clickhouse' | 'objectstorage' | 's3';
+export type TCapability = 'available' | 'unsupported' | 'unknown';
+
+export interface ICapabilities {
+  readonly backend: TBackend;
+  readonly transactions: TCapability;
+  readonly changeStreams: TCapability;
+  readonly objectMetrics: TCapability;
+  readonly diskResidentScans: TCapability;
+}
+
+export interface IOperationOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface IReadiness {
+  ready: boolean;
+  reason?: string;
+}
+
+export type TClientErrorCode = 'invalid_argument' | 'unsupported_capability' | 'not_connected' |
+  'closed' | 'timeout' | 'cancelled' | 'result_limit' | 'authentication' | 'conflict' |
+  'backend_error' | 'ambiguous_write' | 'partial_write';

package/ts/index.ts

@@ -0,0 +1,4 @@
+export { LosslessOrgClient } from './classes.losslessorgclient.js';
+export type { ILosslessOrgClientOptions } from './classes.losslessorgclient.js';
+export { LosslessClientError } from './core/classes.error.js';
+export type { ICapabilities, IOperationOptions, IReadiness, TBackend, TCapability, TClientErrorCode } from './core/interfaces.js';

package/ts/nosqldb/classes.atomicdelete.ts

@@ -0,0 +1,81 @@
+import * as plugins from './plugins.js';
+import type { SmartdataCollection } from './classes.collection.js';
+import {
+  runWithOrdinarySmartdataSession,
+  type TSmartdataOrdinarySession,
+} from './classes.session.js';
+
+/**
+ * Executes a model-validated atomic delete against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicDelete()` owns the
+ * public API and must validate every filter before calling this raw persistence
+ * boundary.
+ */
+export const executeAtomicDelete = async <T>(
+  collectionArg: SmartdataCollection<T>,
+  filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>,
+  optsArg?: {
+    session?: TSmartdataOrdinarySession;
+    timeoutMS?: number;
+  },
+): Promise<plugins.mongodb.DeleteResult> => {
+  return runWithOrdinarySmartdataSession(
+    optsArg?.session,
+    collectionArg.smartdataDb,
+    {
+      ordinaryWrite: true,
+      prepared: collectionArg.isInitializedForCurrentDatabase(),
+      preparationMessage:
+        `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    },
+    async (rawSessionArg) => {
+      await collectionArg.init();
+      return collectionArg.mongoDbCollection.deleteOne(
+        filterArg,
+        {
+          session: rawSessionArg,
+          timeoutMS: optsArg?.timeoutMS,
+        },
+      );
+    },
+  );
+};
+
+/**
+ * Executes a model-validated atomic delete-many against MongoDB.
+ *
+ * This helper is package-internal. `SmartDataDbDoc.atomicDeleteMany()` owns
+ * the public API and must validate every filter before calling this raw
+ * persistence boundary. Each matched document is deleted atomically; the
+ * batch as a whole is not isolated.
+ */
+export const executeAtomicDeleteMany = async <T>(
+  collectionArg: SmartdataCollection<T>,
+  filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>,
+  optsArg?: {
+    session?: TSmartdataOrdinarySession;
+    timeoutMS?: number;
+  },
+): Promise<plugins.mongodb.DeleteResult> => {
+  return runWithOrdinarySmartdataSession(
+    optsArg?.session,
+    collectionArg.smartdataDb,
+    {
+      ordinaryWrite: true,
+      prepared: collectionArg.isInitializedForCurrentDatabase(),
+      preparationMessage:
+        `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    },
+    async (rawSessionArg) => {
+      await collectionArg.init();
+      return collectionArg.mongoDbCollection.deleteMany(
+        filterArg,
+        {
+          session: rawSessionArg,
+          timeoutMS: optsArg?.timeoutMS,
+        },
+      );
+    },
+  );
+};

package/ts/nosqldb/classes.atomicfindoneandupdate.ts

@@ -0,0 +1,152 @@
+import * as plugins from './plugins.js';
+import type { SmartdataCollection } from './classes.collection.js';
+import {
+  normalizeOrdinaryPersistenceError,
+  SmartdataPersistenceError,
+} from './classes.persistence.js';
+import {
+  runWithOrdinarySmartdataSession,
+  isSmartdataSession,
+  failSmartdataTransaction,
+  type SmartdataSession,
+  type TSmartdataOrdinarySession,
+} from './classes.session.js';
+import { validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
+
+type TRawDocument = plugins.mongodb.WithId<plugins.mongodb.Document>;
+
+export type TAtomicFindOneAndUpdateExecutionResult =
+  | { status: 'matched'; document: TRawDocument }
+  | { status: 'upserted'; document: TRawDocument | null }
+  | { status: 'not_matched'; document: null };
+
+const unsupportedResult = (): never => {
+  throw new SmartdataPersistenceError(
+    'unsupported_operation',
+    'MongoDB returned unsupported atomic find-one-and-update metadata.',
+  );
+};
+
+const classifyResult = (
+  resultArg: plugins.mongodb.ModifyResult<plugins.mongodb.Document>,
+  optionsArg: {
+    returnDocument: 'before' | 'after';
+    upsert: boolean;
+  },
+): TAtomicFindOneAndUpdateExecutionResult => {
+  const metadata = resultArg.lastErrorObject;
+  if (resultArg.ok !== 1 || !metadata) return unsupportedResult();
+  const hasUpserted = Object.prototype.hasOwnProperty.call(metadata, 'upserted');
+  const upserted = metadata.upserted;
+
+  if (
+    metadata.n === 1
+    && metadata.updatedExisting === true
+    && !hasUpserted
+    && resultArg.value !== null
+  ) {
+    return { status: 'matched', document: resultArg.value };
+  }
+
+  if (
+    optionsArg.upsert
+    && metadata.n === 1
+    && metadata.updatedExisting === false
+    && hasUpserted
+    && upserted !== undefined
+    && upserted !== null
+    && (
+      (optionsArg.returnDocument === 'before' && resultArg.value === null)
+      || (optionsArg.returnDocument === 'after' && resultArg.value !== null)
+    )
+  ) {
+    return { status: 'upserted', document: resultArg.value };
+  }
+
+  if (
+    !optionsArg.upsert
+    && metadata.n === 0
+    && metadata.updatedExisting === false
+    && !hasUpserted
+    && resultArg.value === null
+  ) {
+    return { status: 'not_matched', document: null };
+  }
+
+  return unsupportedResult();
+};
+
+/**
+ * Executes a model-validated atomic find-one-and-update against MongoDB.
+ *
+ * This helper is package-internal. It classifies driver metadata before
+ * returning and never exposes a MongoDB ModifyResult to the public model API.
+ */
+export const executeAtomicFindOneAndUpdate = async <T>(
+  collectionArg: SmartdataCollection<T>,
+  filterArg: plugins.mongodb.Filter<plugins.mongodb.Document>,
+  updateArg: plugins.mongodb.UpdateFilter<plugins.mongodb.Document>,
+  optionsArg: {
+    returnDocument: 'before' | 'after';
+    upsert: boolean;
+    sort?: Record<string, 1 | -1>;
+    session?: TSmartdataOrdinarySession;
+  },
+): Promise<TAtomicFindOneAndUpdateExecutionResult> => {
+  const policy = collectionArg.getBoundModelSchema()?.ordinaryPersistence;
+  if (policy && (!isSmartdataSession(optionsArg.session) || optionsArg.returnDocument !== 'after')) {
+    throw new SmartdataPersistenceError('unsupported_operation',
+      'Validated ordinary updates require an owned transaction and an after image.');
+  }
+  return runWithOrdinarySmartdataSession(
+    optionsArg.session,
+    collectionArg.smartdataDb,
+    {
+      ordinaryWrite: true,
+      prepared: collectionArg.isInitializedForCurrentDatabase(),
+      preparationMessage:
+        `Initialize collection "${collectionArg.collectionName}" before using an owned SmartData session.`,
+    },
+    async (rawSessionArg) => {
+      if (policy && !rawSessionArg?.inTransaction()) {
+        throw new SmartdataPersistenceError('unsupported_operation',
+          'Validated ordinary updates require an active owned transaction.');
+      }
+      await collectionArg.init();
+      try {
+        const result = await collectionArg.mongoDbCollection.findOneAndUpdate(
+          filterArg,
+          updateArg,
+          {
+            includeResultMetadata: true,
+            returnDocument: optionsArg.returnDocument,
+            upsert: optionsArg.upsert,
+            ...(optionsArg.sort ? { sort: optionsArg.sort } : {}),
+            session: rawSessionArg,
+          },
+        );
+        try {
+          const classified = classifyResult(result, optionsArg);
+          if (policy && classified.document) {
+            classified.document = validateOrdinaryStoredDocument(
+              classified.document, policy, collectionArg.getBoundModelSchema()!.persistedFields,
+            ) as TRawDocument;
+          }
+          return classified;
+        } catch (errorArg) {
+          if (policy) {
+            failSmartdataTransaction(
+              optionsArg.session as SmartdataSession, collectionArg.smartdataDb, errorArg,
+            );
+          }
+          throw errorArg;
+        }
+      } catch (errorArg) {
+        return normalizeOrdinaryPersistenceError(
+          errorArg,
+          `Atomic find-one-and-update conflicts with a unique index in collection "${collectionArg.collectionName}".`,
+        );
+      }
+    },
+  );
+};