@lossless.org/nosqldb 8.0.0

package/readme.md

@@ -0,0 +1,1733 @@
+# @lossless.org/nosqldb
+
+A MongoDB-wire-compatible embedded database server powered by a native Rust MVCC engine. It supports the documented command surface through the official `mongodb` driver without an external MongoDB server. Memory and file storage use the same paged engine, including the operation log, point-in-time revert and debug dashboard. Matching executables are bundled with the package.
+
+## 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
+
+```bash
+pnpm add @lossless.org/nosqldb
+```
+
+## Moving from @push.rocks/smartdb
+
+The module has moved to `@lossless.org/nosqldb`. Install the new package and update imports and product-specific names together:
+
+| Previous name | New name |
+| --- | --- |
+| `@push.rocks/smartdb` | `@lossless.org/nosqldb` |
+| `SmartdbServer` | `NoSqlDbServer` |
+| `LocalSmartDb` | `LocalNoSqlDb` |
+| `SmartdbStorageRehearsal` | `NoSqlDbStorageRehearsal` |
+| `SmartdbDebugServer` / `SmartdbDebugUi` | `NoSqlDbDebugServer` / `NoSqlDbDebugUi` |
+| `ISmartdb*`, `ISmartDb*`, `TSmartdb*`, `TSmartDb*` | `INoSqlDb*`, `TNoSqlDb*` |
+| `createSmartDb*`, `normalizeSmartDb*`, `smartDb*` | `createNoSqlDb*`, `normalizeNoSqlDb*`, `noSqlDb*` |
+| `SMARTDB_*` environment variables | `NOSQLDB_*` environment variables |
+| `<smartdb-debugui>` / `/api/smartdb/*` | `<nosqldb-debugui>` / `/api/nosqldb/*` |
+| Benchmark `--engine smartdb` | Benchmark `--engine nosqldb` |
+
+The `./debugui` and `./debugserver` package subpaths stay the same. The new module exports the new API names; it does not export aliases for the previous names. Update explicit binary overrides to `NOSQLDB_RUST_BINARY`, and rename the release-builder environment variables shown below.
+
+This is a package and API rename, not a storage-format conversion. Existing current-format v7 databases, authentication records, allocation identities, export formats, and operation receipts retain their original byte formats. Versioned `smartdb.*` format identifiers, the `smartdb` allocation provider, hash domains, and private locking/workspace names deliberately remain unchanged. Do not edit those values in stored data or rewrite existing receipts. The native `rustdb` executable, `rustdb_*` packaged artifact names, and `.__rustdb_*` storage directories also keep their existing identities. Earlier incompatible storage formats remain subject to the admission restrictions documented below.
+
+---
+
+## What It Does
+
+`@lossless.org/nosqldb` is a **real database server** that speaks the wire protocol used by MongoDB drivers. The core engine is written in Rust for high performance, with a thin TypeScript orchestration layer. Connect with the standard `mongodb` Node.js driver — no mocks, no stubs, no external binaries required.
+
+### Why NoSQLDB?
+
+| | NoSQLDB | External DB Server |
+|---|---|---|
+| **Startup** | Managed by the application | Managed separately |
+| **Binary distribution** | Matching executables bundled in the package | Separate installation |
+| **Install** | `pnpm add` | System package / Docker |
+| **Persistence** | Memory or file-based | Full disk engine |
+| **Debug UI** | Built in | External tooling |
+| **Point-in-time revert** | Built in | Depends on the database |
+| **Perfect for** | Unit tests, CI/CD, prototyping, local dev, embedded | Production at scale |
+
+### Three Ways to Use It
+
+- 🎯 **`LocalNoSqlDb`** — Zero-config convenience. Give it a folder path, get a persistent database over a Unix socket. Done.
+- 🏗️ **`NoSqlDbServer`** — Full control. Configure port, host, storage backend, Unix sockets. Great for test fixtures or custom setups.
+- 🖥️ **`NoSqlDbDebugServer`** — Launch a web dashboard to visually browse collections, inspect the operation log, and revert to any point in time.
+
+### Architecture: TypeScript + Rust 🦀
+
+NoSQLDB uses a **sidecar binary** pattern — TypeScript handles lifecycle, Rust handles all database operations:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                   Your Application                           │
+│                  (TypeScript / Node.js)                      │
+│  ┌──────────────────┐      ┌───────────────────────────┐     │
+│  │  NoSqlDbServer   │─────▶│  RustDbBridge (IPC)       │     │
+│  │  or LocalNoSqlDb │      │  @push.rocks/smartrust    │     │
+│  └──────────────────┘      └───────────┬───────────────┘     │
+└────────────────────────────────────────┼─────────────────────┘
+                                         │ spawn + JSON IPC
+                                         ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    rustdb binary                             │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐       │
+│  │ Wire Protocol│→ │Command Router│→ │   Handlers    │       │
+│  │  (OP_MSG)    │  │  (40+ cmds)  │  │ Find,Insert.. │       │
+│  └──────────────┘  └──────────────┘  └───────┬───────┘       │
+│                                              │               │
+│  ┌─────────┐ ┌────────┐ ┌───────────┐ ┌──────┴──────┐        │
+│  │  Query  │ │ Update │ │Aggregation│ │   Index     │        │
+│  │ Matcher │ │ Engine │ │  Engine   │ │   Engine    │        │
+│  └─────────┘ └────────┘ └───────────┘ └─────────────┘        │
+│                                                              │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────┐    │
+│  │ Native MVCC pages│  │ Memory/file I/O  │  │  OpLog   │    │
+│  └──────────────────┘  └──────────────────┘  └──────────┘    │
+└──────────────────────────────────────────────────────────────┘
+              ▲
+              │ TCP / Unix Socket (wire protocol)
+              │
+┌─────────────┴────────────────────────────────────────────────┐
+│              MongoClient (mongodb npm driver)                │
+│              Connects directly to Rust binary                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+The TypeScript layer handles **lifecycle only** (start/stop/configure via IPC). All database operations flow directly from the `MongoClient` to the Rust binary over TCP or Unix sockets — **zero per-query IPC overhead**.
+
+---
+
+## Quick Start
+
+### Option 1: LocalNoSqlDb (Zero Config) 🎯
+
+The fastest way to get a persistent local database:
+
+```typescript
+import { LocalNoSqlDb } from '@lossless.org/nosqldb';
+import { MongoClient } from 'mongodb';
+
+// Point it at a folder — that's it
+const db = new LocalNoSqlDb({ folderPath: './my-data' });
+const { connectionUri } = await db.start();
+
+// Connect with the standard driver
+const client = new MongoClient(connectionUri, { directConnection: true });
+await client.connect();
+
+// Use it like any wire-protocol-compatible database
+const users = client.db('myapp').collection('users');
+await users.insertOne({ name: 'Alice', email: 'alice@example.com' });
+const user = await users.findOne({ name: 'Alice' });
+console.log(user); // { _id: ObjectId(...), name: 'Alice', email: 'alice@example.com' }
+
+// Data persists to disk automatically — survives restarts!
+await client.close();
+await db.stop();
+```
+
+### Option 2: NoSqlDbServer (Full Control) 🏗️
+
+```typescript
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+import { MongoClient } from 'mongodb';
+
+// TCP mode
+const server = new NoSqlDbServer({ port: 27017 });
+await server.start();
+
+const client = new MongoClient('mongodb://127.0.0.1:27017');
+await client.connect();
+
+const db = client.db('myapp');
+await db.collection('users').insertOne({ name: 'Alice', age: 30 });
+const user = await db.collection('users').findOne({ name: 'Alice' });
+
+await client.close();
+await server.stop();
+```
+
+### Option 3: Debug Server (Visual Dashboard) 🖥️
+
+Launch a web-based dashboard to inspect your database in real time:
+
+`debugserver` and `debugui` are optional subpath exports. Install their
+debug dependencies only when you use them:
+
+```bash
+pnpm add '@api.global/typedserver@^8' '@design.estate/dees-element@^2'
+```
+
+```typescript
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+import { NoSqlDbDebugServer } from '@lossless.org/nosqldb/debugserver';
+
+const server = new NoSqlDbServer({ storage: 'memory' });
+await server.start();
+
+const debugServer = new NoSqlDbDebugServer(server, { port: 4000 });
+await debugServer.start();
+// Open http://localhost:4000 in your browser 🚀
+```
+
+The debug dashboard gives you:
+- 📊 **Dashboard** — server status, uptime, database/collection counts, operation breakdown
+- 📁 **Collection Browser** — browse databases, collections, and documents interactively
+- 📝 **OpLog Timeline** — every insert, update, and delete with expandable field-level diffs
+- ⏪ **Point-in-Time Revert** — select any oplog sequence, preview what will be undone, and execute
+
+---
+
+## 📝 Operation Log & Point-in-Time Revert
+
+The native engine provides these APIs for both memory and file storage. Revert
+publishes one atomic indexed data change and preserves authentication, fencing,
+publication holds and durable retry history.
+
+Every write operation (insert, update, delete) is automatically recorded in an in-memory **operation log (OpLog)** with full before/after document snapshots. The OpLog lives in RAM and resets on restart — it covers the current session only, and retention is bounded (default: 10,000 entries or 64 MiB, whichever is hit first; configurable via the `oplog` server option). Once a limit is exceeded, the oldest entries are evicted. This enables:
+
+- **Change tracking** — see exactly what changed, when, and in which collection
+- **Field-level diffs** — compare previous and new document states
+- **Point-in-time revert** — undo operations back to any retained sequence number
+- **Dry-run preview** — see what would be reverted before executing
+
+### Programmatic OpLog API
+
+```typescript
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+
+const server = new NoSqlDbServer({ port: 27017 });
+await server.start();
+
+// ... perform some CRUD operations via MongoClient ...
+
+// Get oplog entries
+const oplog = await server.getOpLog({ limit: 50 });
+console.log(oplog.entries);
+// [{ seq: 1, op: 'insert', db: 'myapp', collection: 'users', document: {...}, previousDocument: null }, ...]
+
+// Get aggregate stats
+const stats = await server.getOpLogStats();
+console.log(stats);
+// { currentSeq: 42, totalEntries: 42, oldestSeq: 1, approxBytes: 18342, entriesByOp: { insert: 20, update: 15, delete: 7 } }
+
+// Preview a revert (dry run)
+const preview = await server.revertToSeq(30, true);
+console.log(`Would undo ${preview.reverted} operations`);
+
+// Execute the revert — undoes all operations after seq 30
+const result = await server.revertToSeq(30, false);
+console.log(`Reverted ${result.reverted} operations`);
+
+// Reverts can only reach back as far as retained oplog history —
+// revertToSeq returns an error if the target sequence is older than the
+// oldest retained entry (evicted by the retention limits).
+
+// Browse collections programmatically
+const collections = await server.getCollections();
+const docs = await server.getDocuments('myapp', 'users', 50, 0);
+```
+
+### OpLog Entry Structure
+
+Each entry contains:
+
+| Field | Type | Description |
+|---|---|---|
+| `seq` | `number` | Monotonically increasing sequence number |
+| `timestampMs` | `number` | Unix timestamp in milliseconds |
+| `op` | `'insert' \| 'update' \| 'delete'` | Operation type |
+| `db` | `string` | Database name |
+| `collection` | `string` | Collection name |
+| `documentId` | `string` | Document `_id` as hex string |
+| `document` | `object \| null` | New document state (null for deletes) |
+| `previousDocument` | `object \| null` | Previous document state (null for inserts) |
+
+---
+
+## ✋ No-Op Write Detection
+
+The engine detects document rewrites that change nothing and skips them entirely — no storage write, no WAL append, no index update, and no oplog entry. A skipped rewrite still counts as matched (`matchedCount: 1`) but reports `modifiedCount: 0`.
+
+Two classes are skipped:
+
+- **Identical** — the post-image equals the stored document byte for byte.
+- **Volatile-only** — the post-image differs only in top-level volatile metadata fields (currently `_updatedAt`, the field ODM layers such as `@push.rocks/smartdata` restamp on every save). The stored document is kept as-is, including its existing `_updatedAt`, so the timestamp means "last real change" rather than "last save call".
+
+This makes periodic reconcile loops that re-save unchanged documents cost nothing at the engine level. A caller that needs a document to actually change must change a non-volatile field.
+
+Counters are exposed through `serverStatus`:
+
+```javascript
+const status = await db.command({ serverStatus: 1 });
+console.log(status.writes);
+// {
+//   updatesWritten: 42,        // rewrites that reached storage, index, and oplog
+//   noopSkipped: {
+//     identical: 1337,         // post-image equal to the stored document
+//     volatileOnly: 271,       // only volatile metadata differed
+//   },
+// }
+```
+
+---
+
+## API Reference
+
+### NoSqlDbServer
+
+The core server class. Manages the Rust database engine and exposes connection details.
+
+#### Constructor Options (`INoSqlDbServerOptions`)
+
+`binaryPath?: string` selects one exact engine executable for this server. When
+supplied, Smartrust validates a regular executable file and never searches
+`NOSQLDB_RUST_BINARY`, npm packages, development directories or `PATH`, even if
+the selected path is unusable. Missing, empty, malformed, non-file and
+non-executable paths reject startup with `RustBinaryLocatorError`, code
+`ERR_RUST_BINARY_EXPLICIT_PATH_INVALID`. Validation never changes the target's
+permissions. Executable launch or readiness failures also fail startup without
+selecting another engine. Omitting the option preserves normal discovery.
+
+Use an absolute path to the caller-installed, verified artifact. Smartrust
+anchors relative paths when the underlying bridge is constructed, without
+normalizing away filesystem symlink traversal. A bare name is a relative file
+path, not a `PATH` lookup. Options are instance-local; no environment variables
+are changed. Installer verification and protected installation paths remain the
+caller's responsibility.
+
+```typescript
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+
+const server = new NoSqlDbServer({
+  binaryPath: '/opt/spark/engines/nosqldb/rustdb_linux_amd64',
+  socketPath: '/run/spark/private/nosqldb.sock',
+  storage: 'file',
+  storagePath: '/var/lib/spark/nosqldb',
+});
+await server.start({ timeoutMs: 30_000 });
+try {
+  const connectionUri = server.getConnectionUri();
+  // Pass connectionUri to SmartData for application persistence.
+} finally {
+  await server.stop(); // Resolves after the owned engine has terminated.
+}
+```
+
+The socket parent directory must already exist with the caller's desired access
+permissions. `RustDbBridge` also accepts `{ binaryPath }` for direct lifecycle use.
+
+#### Native memory and file storage
+
+The native MVCC engine is the sole serving engine on Linux and macOS.
+`storage: 'memory'` (the default) uses ephemeral native storage;
+`storage: 'file'` persists the same record model under `storagePath`.
+`binaryPath` selects the executable; it is independent of storage selection.
+
+`fileStorageEngine`, `persistPath`, `persistIntervalMs` and
+`auth.usersPath` have been removed. Supplying them rejects at construction,
+before filesystem or process side effects. Authentication belongs to the native
+database and persists with file storage. Memory storage is ephemeral.
+
+```typescript
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+
+const server = new NoSqlDbServer({
+  binaryPath: '/opt/spark/engines/nosqldb/rustdb_linux_amd64',
+  socketPath: '/run/spark/private/nosqldb.sock',
+  storage: 'file',
+  storagePath: '/var/lib/spark/nosqldb',
+  auth: {
+    enabled: true,
+    scramIterations: 15000,
+    users: [{ database: 'app', username: 'app-owner',
+      password: bootstrapPassword, roles: ['readWrite'] }],
+  },
+});
+await server.start({ timeoutMs: 30_000 });
+try {
+  const connectionUri = server.getConnectionUri();
+  // Connect SmartData with the app credentials after native ownership is acquired.
+} finally {
+  await server.stop();
+}
+```
+
+Supply `bootstrapPassword` from protected caller configuration. The work factor
+above is an example, not a universal default. Reopen with the stored SCRAM work
+factor; bootstrap users may be omitted after initialization. `LocalNoSqlDb`
+accepts `folderPath`, `socketPath`, `binaryPath` and the same `auth` options.
+
+#### Current-format-only file startup
+
+`INoSqlDbServerOptions.fileStorageStartup` and
+`ILocalNoSqlDbOptions.fileStorageStartup` accept only
+`'current-format-only'`, which is also the default for file storage.
+The exported type is `TNoSqlDbFileStorageStartup`. Invalid values, including
+`'migrate'`, reject at construction. Selecting the policy with memory storage
+also rejects.
+
+Startup accepts a fresh root or a current native root. Foreign, old, mixed and
+orphaned migration staging layouts are rejected without conversion. TypeScript
+performs no storage writes before starting the engine. Native format admission
+uses the owning detector; the exclusive native file-root lease is acquired before
+initialization, recovery, authentication or index preparation.
+
+Only after `await server.start()` succeeds should consumers prepare SmartData
+models or run application migrations. Start cancellation and deadlines cover the
+native operation; failed-start cleanup confirms child exit, and `stop()` remains
+retryable if termination cannot yet be confirmed. A second owner of the same
+root is rejected without disturbing the winner. Callers must also exclude
+manual edits and lifecycle changes outside NoSQLDB's ownership protocol.
+
+No automatic format or auth-permission migration runs during startup.
+Persisted-format conversions belong exclusively in the top-level
+`ts_migration/` folder and require their own explicit qualification. This
+release contains no old-engine or authentication-schema conversion.
+
+```typescript
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+
+// TCP mode (default)
+const server = new NoSqlDbServer({
+  port: 0,                  // Default: 27017; 0 requests an OS-assigned port
+  host: '127.0.0.1',        // Default: 127.0.0.1
+  storage: 'memory',        // 'memory' or 'file' (default: 'memory')
+  storagePath: './data',     // Required when storage is 'file'
+});
+const startupController = new AbortController();
+await server.start({
+  signal: startupController.signal,
+  timeoutMs: 30_000,
+});
+console.log(server.port); // Actual bound port while running
+console.log(server.getConnectionUri()); // mongodb://127.0.0.1:<actual-port>
+
+// Unix socket mode — no port conflicts!
+const server = new NoSqlDbServer({
+  socketPath: '/tmp/nosqldb.sock',
+  storage: 'file',
+  storagePath: './data',
+});
+
+// Bounded in-memory oplog retention
+const server = new NoSqlDbServer({
+  port: 27017,
+  oplog: {
+    maxEntries: 50000,            // Default: 10000
+    maxBytes: 128 * 1024 * 1024,  // Default: 64 MiB
+  },
+});
+
+// TLS transport for TCP mode
+const tlsServer = new NoSqlDbServer({
+  port: 27017,
+  tls: {
+    enabled: true,
+    certPath: './certs/server.pem',
+    keyPath: './certs/server.key',
+    // caPath: './certs/client-ca.pem',
+    // requireClientCert: true, // Enables mTLS client certificate checks
+  },
+});
+
+// SCRAM-SHA-256 authentication
+const secureServer = new NoSqlDbServer({
+  port: 27017,
+  auth: {
+    enabled: true,
+    users: [
+      {
+        username: 'root',
+        password: 'change-me',
+        database: 'admin',
+        roles: ['root'],
+      },
+    ],
+  },
+});
+```
+
+When `auth.enabled` is true, protected commands require successful SCRAM-SHA-256 authentication through the official MongoDB driver:
+
+```typescript
+const client = new MongoClient('mongodb://root:change-me@127.0.0.1:27017/admin?authSource=admin', {
+  directConnection: true,
+});
+await client.connect();
+```
+
+TLS is available for TCP listeners. `getConnectionUri()` includes `?tls=true` when TLS is enabled; pass the trusted CA to the MongoDB driver with `tlsCAFile`, `ca`, or `secureContext`.
+
+Authentication verifies SCRAM credentials, denies unauthenticated commands, and enforces command-level built-in roles for supported operations. `connectionStatus` reports the authenticated users and roles for the current socket.
+
+Supported built-in role names are `root`, `read`, `readWrite`, `dbAdmin`,
+`userAdmin`, `clusterMonitor`, `readAnyDatabase`, `readWriteAnyDatabase`,
+`dbAdminAnyDatabase` and `userAdminAnyDatabase`. Native auth records contain
+derived SCRAM credentials, protected decoy material, the immutable work factor,
+principal identities, generations and bounded grant replay state. Plaintext
+passwords are not persisted. `auth.scramIterations` must match the stored
+profile on every reopen. Historical or malformed auth records fail closed.
+
+Every authenticated command resolves the current principal and generation.
+Password and role changes invalidate old sockets. Deleting and recreating a
+username creates a different principal; an old connection cannot inherit its
+authority. Auth changes and the data/control records they protect share native
+atomic publications.
+
+Single-node transactions pin one committed root across namespaces and retain
+changed documents, rather than copying a database. Supported reads and writes
+see the transaction snapshot plus its staged changes. Commit validates conflicts
+and publishes atomically; abort discards staged changes. Write conflicts report
+`WriteConflict` (112) with `TransientTransactionError`.
+
+Commit/abort outcomes and successful retryable statement results survive file
+storage restart. Duplicate commits replay their outcome; abort after commit
+reports `TransactionCommitted` (256), commit after abort reports
+`NoSuchTransaction` (251), and older transaction numbers report
+`TransactionTooOld` (225). Unsupported transactional DDL, auth mutations and
+`$out`/`$merge` reject before transaction admission or mutation.
+
+Logical sessions survive socket disconnects. Expiry, `endSessions` and
+`killSessions` drain active work and release cursors and namespace gates.
+Rejected new transaction envelopes do not consume session capacity or reset
+existing sessions. See the native resource budgets below.
+
+### Durable Database Publication Holds
+
+On supported Linux and macOS filesystems, file-backed NoSQLDB can keep a replaced or deleted database closed after the local mutation is durable and until a downstream coordinator confirms its own fsync. Check the explicit health contract before using this flow:
+
+```typescript
+const health = await server.getHealth();
+if (
+  health.publicationHoldVersion !== 1 ||
+  !health.publicationHoldSupported ||
+  health.publicationHoldRequiresExternalDrain
+) {
+  throw new Error('NoSQLDB publication holds are unavailable');
+}
+```
+
+Set `holdPublication: true` on an exact fenced `importDatabase()` or `deleteDatabaseTenant()` operation. The result contains a held `resourceFence` with a one-time `publicationCapability`. Treat that capability as a secret: do not log it or persist it outside protected control-plane state. After downstream state is durable, submit the exact receipt to `commitDatabasePublication()`:
+
+```typescript
+import type { INoSqlDbHeldPublicationReceipt } from '@lossless.org/nosqldb';
+
+const held = await server.importDatabase({
+  databaseName: 'tenant_a',
+  source: snapshot,
+  username: 'tenant_a_user',
+  fence: {
+    version: 1,
+    scopeId: 'corestore-node-1.tenant-a',
+    token: 42,
+    mutationId: 'restore-42',
+    payloadSha256: controlPlanePayloadSha256,
+  },
+  holdPublication: true,
+});
+
+const receipt = held.resourceFence as INoSqlDbHeldPublicationReceipt;
+await persistAndFsyncDownstreamState(receipt);
+const released = await server.commitDatabasePublication({
+  databaseName: 'tenant_a',
+  resourceFence: receipt,
+});
+```
+
+The held barrier survives restart and blocks wire commands, transactions and index restoration for that database while unrelated databases remain available. Native physical compaction preserves the held records. Commit is exact and idempotent. A successful commit removes the raw capability from durable state and retains only protected verification material. Provider/root identity and bounded validation of native fencing records make copied, incomplete or corrupt allocation state fail closed. A higher fencing token compacts resolved older receipts, so long-lived coordinators do not exhaust receipt capacity.
+
+Durable database publication holds and allocation fencing use native file storage on the supported Linux and macOS filesystems.
+
+Coordinators that do not yet have their own durable record can call `getDatabaseResourceFenceState({ databaseName })` before creating it. File-backed NoSQLDB returns the durable scope, highest token, current publication phase, and allocation lifecycle/identity when the name is allocation-managed, or `null` for an unfenced name. Startup first validates both directions of every allocation's fencing/auth binding. The inspection never returns mutation IDs, mutation payload digests, publication receipts, or publication capabilities. Treat any active phase, identity mismatch, corrupt state, unsupported storage, or unsafe token as a hard stop rather than creating coordinator state.
+
+### Authoritative Database Allocation
+
+`allocateDatabaseTenant()` is the create-only control-plane API for permanently allocation-managed database names. It is available only when `allocationFencingVersion === 1`, `allocationFencingSupported === true`, and `allocationFencingRequiresDrain === true`. The request requires literal `expectedAbsent: true`, an `INoSqlDbResourceFence`, and the tenant database, username, and password. `roles` is optional and defaults to `['readWrite', 'dbAdmin']`. Under native ownership and database/control admission, NoSQLDB proves catalog and principal absence, then commits the catalog, principal, complete auth allocation binding and fencing receipt at one position. It returns an `INoSqlDbAllocateDatabaseTenantResult`; its `.allocation` field is the durable `INoSqlDbDatabaseAllocationIdentity`. Exact fence replay returns the same allocation ID, generation, principal ID, and receipt digests.
+
+Pass the returned `allocation` identity to every later `ensureDatabaseTenant()`, `importDatabase()`, and `deleteDatabaseTenant()` request for that name. Managed import and delete requests also require the exact allocation `username`; the identity alone is insufficient. Each distinct managed mutation requires a strictly newer fence token; the current token is accepted only for exact receipt replay or continuation, and older receipts become explicitly stale after advancement. Held publication receipts carry the allocation into `commitDatabasePublication()`. Managed requests without it and unmanaged requests with it fail closed. Deprovision drains affected runtime authority, then atomically retires the catalog, exact principal, grants and auth binding with a permanent `deprovisioned` fencing tombstone. A later allocation requires a newer fence token, increments generation, and receives a fresh allocation and principal identity. Wire data access is available only while active and only to the current allocation principal; database/user ownership-changing wire commands are rejected.
+
+Allocation bindings are native records, excluded from logical database exports and never accepted from import payloads. Startup and stopped-storage inspection require the complete matching fence and auth binding even when no read grant was ever issued. Missing bindings are rejected without reconstruction. This includes allocated roots produced by experimental native versions that did not create the complete binding. This release provides no automatic conversion or downgrade path; never remove or edit private metadata to force admission.
+
+### Read-Only Tenant Attestation
+
+`attestDatabaseTenant()` verifies that an existing database is exclusively owned by the exact username, role set, and candidate password. It returns only `{ matches: boolean }`; it never returns a URI, credential, principal identity, or mismatch detail. Missing databases or users, conflicting ownership, role differences, allocation-principal drift, and password mismatch all return `false` through the same constant-work credential path.
+
+Attestation pins one native snapshot under the database's read-only admission. Its auth, allocation and data observations share that committed root. Attestation does not refresh process caches or call tenant ensure, create, rotate, import, delete, fence repair, publication-epoch observation, or cache invalidation. Corrupt, held, deprovisioned, disabled, or busy provider state fails as an operational error instead of returning a match result.
+
+```typescript
+const result = await server.attestDatabaseTenant({
+  databaseName: 'tenant_a',
+  username: 'tenant_a_user',
+  roles: ['readWrite'],
+  password: candidatePassword,
+});
+
+if (!result.matches) {
+  throw new Error('Existing tenant authority does not match');
+}
+```
+
+### Allocation-Bound Read Access Grants
+
+Scratch diagnostics can use `issueDatabaseAllocationReadAccessGrant()` to create one auxiliary read principal for an exact active allocation. The capability is advertised only when `databaseAllocationReadAccessGrantVersion === 1` and `databaseAllocationReadAccessGrantSupported === true`; this requires file storage, enabled authentication and ready allocation fencing. Native MVCC commits grant principals, authentication and allocation bindings atomically in the storage root. The caller supplies `databaseName`, a bounded `grantId`, a bounded unique `username`, `password`, and the complete `INoSqlDbDatabaseAllocationIdentity`. Roles and expiry are not caller-controlled. NoSQLDB always assigns exactly `['read']` and a fixed, non-renewing 12-minute expiry.
+
+```typescript
+const grant = await server.issueDatabaseAllocationReadAccessGrant({
+  databaseName: allocation.databaseName,
+  grantId: 'scratch-diagnostic-2026-08-08',
+  username: 'scratch_diagnostic_reader',
+  password: generatedSecret,
+  allocation,
+});
+
+const diagnosticClient = new MongoClient(grant.mongodbUri!, {
+  directConnection: true,
+});
+await diagnosticClient.connect();
+```
+
+Exact issue replay validates the candidate password against the persisted SCRAM credential and returns the original principal generation, `issuedAt`, and `expiresAt` only while that grant remains active and unexpired; it never renews the grant. Expired or revoked `grantId` values are rejected. NoSQLDB permits at most one active read grant per allocation. Revoked and expired `grantId` values remain in a per-allocation anti-replay set capped at 1,024 entries, with no eviction while the allocation exists. Capacity exhaustion fails closed. Allocation deprovision uses a two-phase fail-closed sequence: any active grant is first durably retired and tombstoned, then the database is durably deleted, and finally the exact owner plus that allocation's replay state are removed in one auth rewrite. Interruption before completion leaves the grant retired rather than usable.
+
+Native deprovision also durably retires an active grant before draining its
+transaction, then publishes database deletion, exact owner cleanup and its
+fencing receipt together. Bounded periodic cleanup retires expired grant
+principals and cancels their sessions and cursors.
+
+Grant-specific rejections from the issue and revoke methods are normalized automatically as `NoSqlDbAllocationReadAccessGrantError` with stable `EGRANT_INVALID_REQUEST`, `EGRANT_CREDENTIAL_MISMATCH`, `EGRANT_CONFLICT`, `EGRANT_REPLAY_CAPACITY`, or `EGRANT_STATE_UNAVAILABLE` codes. The companion exports `TNoSqlDbAllocationReadAccessGrantErrorCode`, `noSqlDbAllocationReadAccessGrantErrorCodes`, and `normalizeNoSqlDbAllocationReadAccessGrantError(error, code)` support type-safe handling and explicit normalization of structured bridge errors. Allocation and resource-fence failures retain their existing `NoSqlDbResourceFenceError` codes. Callers should classify errors by these exported classes and codes rather than by message text.
+
+Active allocation read grants never survive a NoSQLDB engine restart or a new attachment to the durable auth store. Startup durably retires and tombstones them before accepting work; diagnostics must issue a new `grantId`, username, and credential after restart.
+
+Grant principals can read only their exact allocation database. Reads, collection/index metadata, and read-only transactions are supported. Writes, DDL, user/admin operations, writing aggregates (`$out` and `$merge`), cross-database targets, and allocation ownership changes are denied. Revocation, expiry cleanup, and allocation deprovision abort matching logical sessions and transactions, release retained database permits, and remove matching cursors. Stale sockets fail their next command.
+
+`revokeDatabaseAllocationReadAccessGrant()` takes `databaseName`, `grantId`, and the complete allocation identity, returns `{ revoked: true }` without a secret, and is idempotent. Revoke-before-issue records anti-replay state only while a read permit proves that exact allocation is current. A delayed revoke after deprovision returns success without recreating auth metadata.
+
+Native `exportDatabase()` pins a committed database root while ordinary writes
+continue. Catalog, auth and publication checks use the same root; DDL remains
+excluded by the database gate. Callers can lower `maxEncodedBytes`,
+`maxCollections`, `maxDocuments` and `maxIndexes`; the server enforces these
+bounds while scanning. Results use canonical MongoDB Extended JSON, preserving
+every BSON type and numeric width.
+
+`importDatabase()` validates canonical or relaxed Extended JSON, builds a private
+native catalog in bounded commits, then atomically publishes the complete catalog
+with its fencing receipt. Incomplete staging is never visible to data readers.
+Cancellation or restart retires unpublished staging through the owning native
+logic. Index aliases, empty namespaces and validated `system.views` definitions
+are preserved; view IDs are rebound when the database name changes. Keep exported
+objects as JSON values rather than coercing BSON numeric wrappers into JavaScript
+numbers. These APIs transfer database contents; they do not convert storage files.
+
+`getDatabaseContentDigest()` computes a bounded, database-name-independent SHA-256 over collection names, exact BSON document bytes, and persisted index specifications. Collection, document, and index enumeration order is normalized; BSON field order and compound-index key order remain significant. The physical `system.views` catalog is included, with only its already-validated deterministic database prefix removed from `_id` for hashing so a cross-name import retains the same digest. `INoSqlDbGetDatabaseContentDigestInput` accepts `databaseName` and optional `INoSqlDbDatabaseContentDigestLimits` fields `maxScannedBsonBytes`, `maxCollections`, `maxDocuments`, and `maxIndexes`. Callers may lower the server ceilings of 96 MiB scanned BSON, 10,000 collections, 1,000,000 documents, and 100,000 indexes. The `INoSqlDbDatabaseContentDigest` result reports format `smartdb.database.content-digest.v1`, algorithm `sha256`, the lowercase digest, and exact scan counters.
+
+`NoSqlDbServer.start()` and the lifecycle-critical health, fence-state, digest, export, import, publication-commit, tenant-allocation, tenant-attestation, tenant-ensure, tenant-delete, read-grant issue, and read-grant revoke methods accept optional `INoSqlDbManagementOperationOptions` with `signal?: AbortSignal` and `timeoutMs?: number`. `timeoutMs`, when provided, must be a positive safe integer no greater than `2,147,483,647`. Startup applies both cancellation and one deadline across sidecar spawn, native admission, recovery and database readiness. Cancellation and deadlines are fail-stop once the sidecar is owned: NoSQLDB attempts to terminate the Rust engine before rejecting. Once termination is confirmed, the operation cannot continue after the caller releases ownership. If termination itself fails, the rejection retains bridge ownership and the service owner must retry `stop()` until it succeeds. After cancellation or deadline termination, restart NoSQLDB before accepting more traffic.
+
+```typescript
+const controller = new AbortController();
+const exported = await server.exportDatabase(
+  { databaseName: 'myapp' },
+  { signal: controller.signal, timeoutMs: 5 * 60_000 },
+);
+```
+
+Basic user management commands are available for authenticated users with `root` or `userAdmin` privileges:
+
+```typescript
+await client.db('admin').command({
+  createUser: 'reader',
+  pwd: 'readpass',
+  roles: [{ role: 'read', db: 'myapp' }],
+});
+
+await client.db('admin').command({ usersInfo: 'reader' });
+```
+
+#### Methods & Properties
+
+| Method / Property | Type | Description |
+|---|---|---|
+| `start(options?)` | `Promise<void>` | Start under one optional cancellation/deadline budget; join partial sidecars before rejection or retain ownership for `stop()` retry if termination fails |
+| `stop()` | `Promise<void>` | Wait for active startup work, then stop the server and confirm Rust bridge cleanup, including partial startup cleanup |
+| `getConnectionUri()` | `string` | Get the active `mongodb://` URI; before start and after stop, port `0` remains unresolved |
+| `running` | `boolean` | Whether the server is currently running |
+| `port` | `number` | Actual bound port while running; otherwise the configured port (TCP mode) |
+| `host` | `string` | Configured host (TCP mode) |
+| `socketPath` | `string \| undefined` | Socket path (socket mode) |
+| `processId` | `number \| undefined` | Operating-system pid of the spawned Rust engine while it runs as a child process (for crash and kill tests) |
+| `getMetrics()` | `Promise<INoSqlDbMetrics>` | Server metrics (db/collection counts, sessions, transactions, auth, uptime) |
+| `getOpLog(params?)` | `Promise<IOpLogResult>` | Query oplog entries with optional filters |
+| `getOpLogStats()` | `Promise<IOpLogStats>` | Aggregate oplog statistics |
+| `revertToSeq(seq, dryRun?)` | `Promise<IRevertResult>` | Revert to a specific oplog sequence (must be within retained oplog history) |
+| `getCollections(db?)` | `Promise<ICollectionInfo[]>` | List all collections with counts |
+| `getDocuments(db, coll, limit?, skip?)` | `Promise<IDocumentsResult>` | Browse documents with pagination |
+| `getHealth(options?)` | `Promise<INoSqlDbHealth>` | Read readiness and explicit publication-hold capability fields with optional fail-stop cancellation/deadline ownership |
+| `allocateDatabaseTenant(params, options?)` | `Promise<INoSqlDbAllocateDatabaseTenantResult>` | Authoritatively allocate an absent file-backed tenant and return its durable allocation identity; supports fail-stop cancellation and deadlines |
+| `attestDatabaseTenant(params, options?)` | `Promise<INoSqlDbAttestDatabaseTenantResult>` | Verify exact existing tenant ownership, roles, and candidate credential without mutating provider, auth, fence, or runtime cache state |
+| `issueDatabaseAllocationReadAccessGrant(params, options?)` | `Promise<INoSqlDbIssueDatabaseAllocationReadAccessGrantResult>` | Issue or exactly replay one fixed 12-minute read grant bound to the complete active allocation identity |
+| `revokeDatabaseAllocationReadAccessGrant(params, options?)` | `Promise<INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult>` | Idempotently revoke/tombstone one exact allocation read grant and invalidate its live runtime state |
+| `ensureDatabaseTenant(params, options?)` | `Promise<INoSqlDbEnsureDatabaseTenantResult>` | Idempotently ensure an exact fenced tenant; supports fail-stop cancellation and deadlines |
+| `getDatabaseResourceFenceState(params, options?)` | `Promise<INoSqlDbDatabaseResourceFenceState \| null>` | Safely inspect a file-backed database fence high-water mark and publication phase without exposing receipts or capability material; supports fail-stop cancellation and deadlines |
+| `getDatabaseContentDigest(params, options?)` | `Promise<INoSqlDbDatabaseContentDigest>` | Compute a bounded, database-name-independent digest over exact BSON documents and persisted index specifications; supports fail-stop cancellation and deadlines |
+| `exportDatabase(params, options?)` | `Promise<INoSqlDbDatabaseExport>` | Export one database as lossless canonical MongoDB Extended JSON; supports fail-stop cancellation and deadlines |
+| `importDatabase(params, options?)` | `Promise<INoSqlDbImportDatabaseResult>` | Durably replace one database from canonical or relaxed MongoDB Extended JSON, optionally leaving publication held; supports fail-stop cancellation and deadlines |
+| `deleteDatabaseTenant(params, options?)` | `Promise<INoSqlDbDeleteDatabaseTenantResult>` | Durably delete an exact tenant database/user, optionally leaving publication held; supports fail-stop cancellation and deadlines |
+| `commitDatabasePublication(params, options?)` | `Promise<TNoSqlDbCommitDatabasePublicationResult>` | Idempotently release an exact held publication receipt; supports fail-stop cancellation and deadlines |
+
+### NoSqlDbStorageRehearsal
+
+`NoSqlDbStorageRehearsal.createDestination(input, options?)` creates an isolated,
+authenticated copy of an initialized, stopped file-storage root. It verifies
+the source's existing native owner, provider and authentication bindings while
+holding its existing outer and native file-root leases continuously.
+The source is read-only throughout: no initialization, recovery, migration,
+permission repair, journal retirement or identity editing occurs there. Successful
+creation leaves it independently restartable at its original path.
+
+```typescript
+import { NoSqlDbServer, NoSqlDbStorageRehearsal } from '@lossless.org/nosqldb';
+
+const binaryPath = '/opt/corestore/engines/nosqldb/rustdb_linux_amd64';
+const operation = new NoSqlDbStorageRehearsal({ binaryPath });
+const request = {
+  sourceFolderPath: '/var/lib/corestore/authoritative',
+  destinationFolderPath: '/var/lib/corestore/rehearsals/upgrade-1',
+  operationId: 'corestore-upgrade-1',
+};
+const controller = new AbortController();
+try {
+  // Corestore has stopped the source and retains its maintenance exclusion.
+  const receipt = await operation.createDestination(request, {
+    timeoutMs: 30_000,
+    signal: controller.signal,
+  });
+  const candidate = new NoSqlDbServer({
+    binaryPath,
+    storage: 'file',
+    storagePath: receipt.destinationFolderPath,
+    fileStorageStartup: 'current-format-only',
+    storageRehearsalId: receipt.operationId,
+    socketPath: '/run/corestore/private/rehearsal.sock',
+    auth: {
+      enabled: true,
+      scramIterations: receipt.scramIterations,
+    },
+  });
+  try {
+    await candidate.start({ timeoutMs: 30_000 });
+    const uri = candidate.getConnectionUri();
+    // Connect SmartData with the preserved credentials. Prepare its models,
+    // then run Corestore's versioned ts_migration modules against this URI.
+    // Keep external services and application side effects isolated in Corestore.
+  } finally {
+    await candidate.stop();
+  }
+  // Retain the typed receipt through Corestore's normal persistence API.
+} finally {
+  await operation.stop();
+}
+```
+
+The destination's parent and socket parent must already exist, be owned by the
+effective user and have mode 0700. The socket must be absent and outside the
+storage root. Source and destination paths must be absolute, canonical, distinct,
+non-nested paths on the same supported local filesystem/device. The destination
+must be absent on the first attempt. Neither request nor receipt contains a
+password. `binaryPath` selects exactly the caller-verified executable through
+Smartrust; omission retains normal engine discovery without environment changes.
+
+The public types are `INoSqlDbStorageRehearsalOptions`,
+`INoSqlDbStorageRehearsalInput`, `INoSqlDbStorageRehearsalReceipt` and
+`INoSqlDbStorageRehearsalPreservation`. An optional
+`expectedSourceProviderRootId` pins a previously attested source provider ID;
+NoSQLDB always verifies the source's stored bindings even when this is omitted.
+Consumers do not inspect private identity files. Optional
+`limits: { maximumEntries, maximumBytes }` can lower the source scan limits.
+
+The supported storage profile is `native-mvcc-authenticated-v1`; creation
+evidence uses `smartdb.storage-rehearsal.receipt.v2`. Rehearsal accepts current
+native authentication records only. The removed `authMigration` option and
+schema-2 worker conversion are not accepted.
+
+| State | Rehearsal contract |
+|---|---|
+| Contents and catalogs | Preserve exact BSON documents, indexes and aliases, empty namespaces, and internal databases including `admin`, `local` and `config`. |
+| Authentication | Preserve usernames, roles, salts, password verifiers, work factor, principal identities, generations and retained grant replay history. |
+| Fencing and holds | Preserve allocations, retired history, counters and exact receipt records. Held databases remain held; a rehearsal cannot release their production capabilities. |
+| Sessions and outcomes | Preserve durable retry and transaction outcomes, including retained and retiring session records. |
+| Native history | Preserve the source group/timeline and committed records. The destination adds one committed provider-binding record with isolated purpose; it never resets authority counters. |
+
+Active source owners, rehearsal-as-source, old or mixed layouts, unknown entries,
+unfinished import or fencing operations, active read grants, unfinished or
+quarantined indexes, invalid catalogs, corrupt auth/outcomes and storage requiring
+recovery are rejected before publication. Source symlinks, hardlinks, nested
+mounts, special objects, unsafe owners/modes and identity changes are rejected.
+Creation supports the qualified Linux local-filesystem set and writable local
+macOS APFS with native ownership and atomic publication. Other filesystems and
+operating systems are rejected before destination initialization.
+
+Defaults and hard limits are 100,000 filesystem entries, 1 TiB of file bytes,
+depth 16, 4095-byte paths and 64 MiB of retained inventory metadata. The owning
+native catalog, index, auth, outcome and fencing validators also enforce their
+record and semantic work budgets. Exhausted bounds reject without truncation or
+reset. LSNs and fencing high-water marks in the receipt are decimal strings,
+preserving their complete unsigned 64-bit range. These are operation bounds,
+not total serving document limits.
+
+Copying and hashing stream 64 KiB chunks. Complete source/destination validation
+compares the preserved record digest as well as physical identity and contents;
+this is not a constant-time snapshot or reflink.
+
+`storageRehearsalId?: string` is supported by both `INoSqlDbServerOptions` and
+`ILocalNoSqlDbOptions`. It requires the exact recorded operation ID, file storage,
+`fileStorageStartup: 'current-format-only'`, the recorded auth work factor,
+enabled authentication, no bootstrap users, and a private explicit Unix socket.
+`LocalNoSqlDb` also forwards `auth?: INoSqlDbAuthOptions`. Ordinary startup rejects
+a rehearsal root. Native startup verifies the completion seal and new physical
+provider binding and preserved native auth profile before recovery or auth initialization. Health
+reports `storagePurpose: 'rehearsal'` and `storageRehearsalId`; production fencing,
+allocation and publication capabilities are disabled. Authenticated ordinary
+SmartData reads, writes and transactions remain available on unheld databases.
+Corestore owns application/outbound-service isolation. There is no promotion
+API: changing startup flags cannot turn this destination into production authority.
+
+One instance admits one operation at a time; independent instances can select
+different executables and sources. Native leases exclude active source owners
+and conflicting copies. `timeoutMs` defaults to one hour and is capped at 24 hours;
+the budget includes engine lookup/spawn and the native operation. Abort, deadline
+and `stop()` terminate the owned sidecar; methods settle after confirmed exit.
+Cleanup can outlast the deadline. If termination cannot be confirmed, the instance
+retains its bridge and `stop()` remains retryable. Native work also checks parent
+process death. Source stability relies on the native lease plus the caller's
+maintenance exclusion from manual edits and restarts between attempts.
+
+Publication uses a private sibling operation workspace, a bounded durable journal,
+a distinct native destination lease and an atomic exclusive rename. The renamed
+root cannot start until its completion seal is durable. After interruption, retry
+the **identical request**, including paths, operation ID, expected provider ID and
+limits, using the same NoSQLDB release or a compatible newer release. A retry may
+use a different deadline. Keep the source stopped and unchanged until an unfinished
+copy completes; do not edit, remove or move either root or the operation workspace.
+Completed retries return the same creation receipt even after legitimate rehearsal
+writes or source restart. They verify the destination's identity and seal and
+re-establish publication durability; they do not attest to its later contents.
+
+`NoSqlDbStorageRehearsalError` has fixed, secret-free messages and no raw nested
+cause. Codes are `INVALID_REQUEST`, `UNSUPPORTED`, `BUSY`, `NOT_FOUND`,
+`DESTINATION_CONFLICT`, `IDENTITY_MISMATCH`, `STATE_CORRUPT`, `SOURCE_CHANGED`,
+`CAPACITY`, `CANCELLED`, `IO`, `RECOVERY_REQUIRED` and `BINARY_UNAVAILABLE`.
+Uncertain command completion or cleanup reports `RECOVERY_REQUIRED`; an error
+does not imply an absent destination. Exact retry reconciles interrupted copies,
+renames and receipt writes without replacing unrelated paths. A changed source
+or tampered destination fails closed.
+
+The receipt identifies both paths/providers, the destination device/inode, request
+and receipt hashes, storage profile, public auth work factor, preservation counts
+and explicit `productionAuthority: false` / `promotionSupported: false`. It exposes
+no usernames, principal IDs, per-file auth hashes, verifiers or publication secrets.
+It is integrity-checked creation evidence, not an installer signature. Source
+verification compares complete bytes, object identities, owners, link counts,
+modes, modification times and change times; ordinary read access times may change.
+Matching Linux and macOS amd64/arm64 engines and their checksum/provenance files ship in the
+same published NoSQLDB package's `dist_rust/` directory; see the engine artifact
+section below.
+
+### LocalNoSqlDb
+
+Zero-config wrapper around NoSqlDbServer. Uses Unix sockets and file-based persistence.
+
+#### Constructor Options (`ILocalNoSqlDbOptions`)
+
+```typescript
+import { LocalNoSqlDb } from '@lossless.org/nosqldb';
+
+const db = new LocalNoSqlDb({
+  folderPath: './data',                  // Required: data storage directory
+  socketPath: '/tmp/custom.sock',        // Optional: custom socket (default: auto-generated)
+  binaryPath: '/opt/spark/engines/nosqldb/rustdb_linux_amd64', // Optional: exact engine
+  fileStorageStartup: 'current-format-only', // Optional; also the default
+});
+```
+
+`binaryPath` has the same strict selection contract as `NoSqlDbServer` and is
+passed through unchanged on every start. Supply an absolute path because the
+underlying server and bridge are constructed by `LocalNoSqlDb.start()`.
+
+#### Methods & Properties
+
+| Method / Property | Type | Description |
+|---|---|---|
+| `start()` | `Promise<ILocalNoSqlDbConnectionInfo>` | Start and return connection info |
+| `stop()` | `Promise<void>` | Stop the server |
+| `getConnectionInfo()` | `ILocalNoSqlDbConnectionInfo` | Get current connection info |
+| `getConnectionUri()` | `string` | Get the connection URI |
+| `getServer()` | `NoSqlDbServer` | Access the underlying server |
+| `running` | `boolean` | Whether the server is running |
+| `LocalNoSqlDb.relocateStoppedStorageRoot(input, options?)` | `Promise<ILocalNoSqlDbStoppedStorageRootRelocationReceipt>` | Atomically relocate one eligible stopped Linux or macOS file-storage root and retain a source receipt |
+| `LocalNoSqlDb.inspectOfflineStringValue(input, options?)` | `Promise<TLocalNoSqlDbOfflineStringValueInspectionResult>` | Read one exact top-level string value from stopped file storage without starting or mutating the engine |
+| `LocalNoSqlDb.inspectOfflinePhysicalNamespaces(input, options?)` | `Promise<ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult>` | Validate stopped physical file storage and return only deterministic database and collection names |
+
+#### Stopped Storage-Root Relocation
+
+`relocateStoppedStorageRoot()` moves an eligible stopped file-storage root without starting `RustDb`, binding a listener, running a TypeScript migration, initializing storage or auth, or performing WAL recovery. It supports Linux on the existing qualified local-filesystem set and macOS on writable local APFS volumes with ownership, persistent object identities, `flock`, and atomic exclusive/swap rename support. The source root, source parent, and destination parent must be trusted descriptor-safe objects on the same filesystem. The supplied source and destination must be absolute and resolve to distinct, non-root, non-nested physical paths, and the destination must be absent. macOS also rejects case-folded, Unicode-normalized, and ancestry aliases before creating relocation state. The trusted parents may differ.
+
+```typescript
+import { LocalNoSqlDb } from '@lossless.org/nosqldb';
+
+const receipt = await LocalNoSqlDb.relocateStoppedStorageRoot({
+  sourceFolderPath: '/var/lib/myapp/harness-controller/nosqldb',
+  destinationFolderPath: '/var/lib/myapp/hcon/nosqldb',
+  relocationId: 'move-2026-08-17-1',
+}, {
+  timeoutMs: 30_000,
+});
+
+// Start only the destination. The source is now the retained receipt file.
+const db = new LocalNoSqlDb({ folderPath: receipt.destinationFolderPath });
+await db.start();
+```
+
+The input must be a plain object with exactly the own enumerable data fields `sourceFolderPath`, `destinationFolderPath`, and `relocationId`. Each supplied path must already be absolute, is normalized before sidecar creation, is limited to 1 through 4095 UTF-8 bytes, and cannot contain control characters. Longer destination paths are supported within that bound. `relocationId` is a 1 through 256-byte ASCII identifier beginning with an alphanumeric character and otherwise using only alphanumerics, `.`, `_`, `:`, `@`, or `-`. Management `timeoutMs` and `signal` use the same validation and one-deadline behavior as other NoSQLDB management operations. The native operation also checks its monotonic deadline and parent-process lifetime during admission and publication.
+
+The returned exact receipt has this shape:
+
+```typescript
+interface ILocalNoSqlDbStoppedStorageRootRelocationReceipt {
+  format: 'smartdb.storage-root-relocation.receipt.v1';
+  version: 1;
+  relocationId: string;
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  providerRootId: string;
+  storageRootDevice: string; // canonical decimal u64
+  storageRootInode: string;  // canonical decimal u64
+  receiptSha256: string;
+  sourceReceiptRetained: true;
+}
+```
+
+On success, the destination directory is the original storage-root inode and the source path is an exact mode-0600 regular-file receipt. NoSQLDB does not remove that source receipt. The operation appends one native commit that changes only the fencing profile's physical path binding. All other record bytes and versions are preserved, including documents, indexes, empty namespaces, auth verifiers, principal identities, transaction outcomes, fencing history, holds and counters. The native group and timeline, provider identity, and original fencing receipt domain remain unchanged. The native commit position advances exactly once, including after retries.
+
+Relocation supports stopped current native production roots with or without authentication. It never initializes missing ownership or storage metadata. Rehearsal destinations, legacy or mixed layouts, active read-access grants, unfinished fencing or allocation operations, building or quarantined indexes, symlinks, unknown entries, unsafe modes/ownership/link counts, exceeded inspection bounds, active owners and ambiguous identities are rejected explicitly. Admission uses the same owning catalog, auth, index, outcome and fencing validators as other stopped native operations. This operation moves the existing authority; it does not promote a rehearsal copy or duplicate production authority.
+
+The operation durably records one immutable native append plan and reserves the receipt before changing the path binding. It retains exclusive ownership through the append, atomic directory/receipt exchange and confirmed journal cleanup. If a call returns `RECOVERY_REQUIRED`, stop startup attempts and retry the exact normalized source path, destination path and `relocationId` with the same native-capable NoSQLDB version. Startup rejects any relocation-workspace occupancy and never mutates or recovers it. Do not delete, rename, edit or replace either path between attempts. Native relocation does not accept unfinished journals from the removed Bitcask engine.
+
+An exact completed replay returns the same receipt only while the destination remains the current root. A later successful relocation leaves another receipt at that destination path and supersedes the earlier replay topology; retry the later operation instead. Manual copy or rename remains unsupported and continues to fail provider path/inode fencing.
+
+Failures are exposed as `LocalNoSqlDbStorageRootRelocationError` with a code-only union: `INVALID_REQUEST`, `UNSUPPORTED`, `BUSY`, `NOT_FOUND`, `DESTINATION_CONFLICT`, `IDENTITY_MISMATCH`, `STATE_CORRUPT`, `SOURCE_CHANGED`, `CAPACITY`, `CANCELLED`, `IO`, or `RECOVERY_REQUIRED`. Errors and receipts contain no credential or document material. Transport ambiguity after dispatch is `RECOVERY_REQUIRED`; exact retry is the recovery action. An explicit native cancellation or I/O error can also leave private recovery state, which the identical request can finish after the sidecar has confirmed exit.
+
+#### Offline String-Value Inspection
+
+`LocalNoSqlDb.inspectOfflineStringValue(input, options?)` reads one string from a
+stopped current native file root on supported Linux filesystems or macOS APFS.
+It starts only a disposable management sidecar, acquires the existing native
+leases read-only, and pins the committed root. It never starts a listener,
+initializes storage, repairs tails, replays writes or compacts the source.
+
+```typescript
+import { LocalNoSqlDb } from '@lossless.org/nosqldb';
+
+const result = await LocalNoSqlDb.inspectOfflineStringValue({
+  folderPath: '/var/lib/myapp/nosqldb',
+  databaseName: 'myapp',
+  collectionName: 'MetadataDoc',
+  match: { field: 'key', value: 'schemaVersion' },
+  valueField: 'value',
+  limits: {
+    maximumEntries: 100_000,
+    maximumTotalFileBytes: 1024 ** 4,
+    maximumRecords: 1_000_000,
+    maximumRecordBytes: 16 * 1024 * 1024,
+    maximumResultBytes: 1024 * 1024,
+  },
+}, { timeoutMs: 5000 });
+
+if (result.status === 'found') console.log(result.value);
+```
+
+The result is exactly `{ status: 'not-found' }` or
+`{ status: 'found', value: string }`. No other document fields cross IPC.
+Multiple matches, non-string results, corrupted storage, changed source state,
+unsafe objects, missing owner metadata and exhausted limits reject the operation.
+
+#### Offline Physical Namespace Inspection
+
+`LocalNoSqlDb.inspectOfflinePhysicalNamespaces(input, options?)` validates and
+lists the stopped native database/collection catalog. Empty namespaces are
+retained. It validates native document/count/index relationships and compares
+complete bounded filesystem observations before returning; no partial result is
+published. Documents, index definitions, IDs and values stay inside the sidecar.
+
+```typescript
+const namespaces = await LocalNoSqlDb.inspectOfflinePhysicalNamespaces({
+  folderPath: '/var/lib/myapp/nosqldb',
+  limits: {
+    maximumEntries: 100_000,
+    maximumDatabases: 1_000_000,
+    maximumCollections: 1_000_000,
+    maximumIndexes: 1_000_000,
+    maximumTotalFileBytes: 1024 ** 4,
+    maximumRecordsPerCollection: 1_000_000_000,
+    maximumRecordBytes: 16 * 1024 * 1024,
+    maximumResultBytes: 16 * 1024 * 1024,
+  },
+}, { timeoutMs: 30_000 });
+// { schemaVersion: 1, databases: [{ name: 'myapp', collections: ['MetadataDoc'] }] }
+```
+
+These required limits are validated before sidecar creation:
+
+| Limit | Supported range |
+|---|---|
+| `maximumEntries` | 1–100,000 filesystem entries |
+| `maximumTotalFileBytes` | 1 byte–1 TiB |
+| `maximumRecords` / `maximumRecordsPerCollection` | 1–1,000,000,000 |
+| `maximumRecordBytes` | 5 bytes–16 MiB |
+| `maximumResultBytes` | 1 byte–16 MiB for a value; 32 bytes–16 MiB for namespaces |
+| `maximumDatabases`, `maximumCollections`, `maximumIndexes` | 1–1,000,000 each for namespace inspection |
+| Complete encoded request | At most 2 MiB |
+| `timeoutMs` | 1–2,147,483,647 milliseconds |
+
+All numeric values must be safe integers. Paths are limited to 4095 UTF-8 bytes
+before and after absolute resolution; namespace and field names to 255 bytes.
+The string match is at most 1 MiB and must fit `maximumRecordBytes`.
+Removed per-Bitcask-file limits are rejected.
+
+One optional deadline and AbortSignal cover lookup/spawn, native inspection and
+delivery. Cancellation kills and reaps the disposable sidecar before rejection.
+An active database owner blocks inspection. The caller must retain continuous
+lifecycle exclusion through acceptance or handoff of the result: the native
+lease covers inspection, and cannot prevent a restart after the sidecar exits.
+
+### NoSqlDbDebugServer
+
+Web-based debug dashboard served via `@api.global/typedserver`. Import from the `debugserver` subpath:
+
+```typescript
+import { NoSqlDbDebugServer } from '@lossless.org/nosqldb/debugserver';
+
+const debugServer = new NoSqlDbDebugServer(server, { port: 4000 });
+await debugServer.start();
+// Dashboard at http://localhost:4000
+
+await debugServer.stop();
+```
+
+The UI is bundled as base64-encoded content (via `@git.zone/tsbundle`) and served from memory — no static file directory needed.
+
+### NoSqlDbDebugUi (Web Component)
+
+For embedding the debug UI directly into your own web application, import the `<nosqldb-debugui>` web component:
+
+```typescript
+import { NoSqlDbDebugUi } from '@lossless.org/nosqldb/debugui';
+
+// In your HTML/lit template:
+// <nosqldb-debugui .server=${myNoSqlDbServer}></nosqldb-debugui>
+//
+// Or in HTTP mode (when served by NoSqlDbDebugServer):
+// <nosqldb-debugui apiBaseUrl=""></nosqldb-debugui>
+```
+
+---
+
+## Supported Operations
+
+NoSQLDB supports the core operations through the wire protocol. Use the standard `mongodb` driver — these all work:
+
+### CRUD
+
+```typescript
+// Insert
+await collection.insertOne({ name: 'Bob' });
+await collection.insertMany([{ a: 1 }, { a: 2 }]);
+
+// Find
+const doc = await collection.findOne({ name: 'Bob' });
+const docs = await collection.find({ age: { $gte: 18 } }).toArray();
+
+// Update
+await collection.updateOne({ name: 'Bob' }, { $set: { age: 25 } });
+await collection.updateMany({ active: false }, { $set: { archived: true } });
+
+// Delete
+await collection.deleteOne({ name: 'Bob' });
+await collection.deleteMany({ archived: true });
+
+// Replace
+await collection.replaceOne({ _id: id }, { name: 'New Bob', age: 30 });
+
+// Find and Modify
+await collection.findOneAndUpdate({ name: 'Bob' }, { $inc: { visits: 1 } }, { returnDocument: 'after' });
+await collection.findOneAndDelete({ expired: true });
+await collection.findOneAndReplace({ _id: id }, { name: 'Replaced' }, { returnDocument: 'after' });
+```
+
+### Query Operators
+
+```typescript
+// Comparison
+{ age: { $eq: 25 } }     { age: { $ne: 25 } }
+{ age: { $gt: 18 } }     { age: { $lt: 65 } }
+{ age: { $gte: 18 } }    { age: { $lte: 65 } }
+{ status: { $in: ['active', 'pending'] } }
+{ status: { $nin: ['deleted'] } }
+
+// Logical
+{ $and: [{ age: { $gte: 18 } }, { active: true }] }
+{ $or: [{ status: 'active' }, { admin: true }] }
+{ $not: { status: 'deleted' } }
+
+// Element
+{ email: { $exists: true } }
+{ type: { $type: 'string' } }
+
+// Array
+{ tags: { $all: ['mongodb', 'database'] } }
+{ scores: { $elemMatch: { $gte: 80, $lt: 90 } } }
+{ tags: { $size: 3 } }
+
+// Regex
+{ name: { $regex: /^Al/i } }
+```
+
+### Update Operators
+
+```typescript
+{ $set: { name: 'New Name' } }
+{ $unset: { tempField: '' } }
+{ $inc: { count: 1 } }
+{ $mul: { price: 1.1 } }
+{ $min: { low: 50 } }        { $max: { high: 100 } }
+{ $push: { tags: 'new' } }   { $pull: { tags: 'old' } }
+{ $addToSet: { tags: 'unique' } }
+{ $pop: { queue: 1 } }       // Remove last
+{ $pop: { queue: -1 } }      // Remove first
+{ $rename: { old: 'new' } }
+{ $currentDate: { lastModified: true } }
+```
+
+### Aggregation Pipeline
+
+```typescript
+const results = await collection.aggregate([
+  { $match: { status: 'active' } },
+  { $group: { _id: '$category', total: { $sum: '$amount' } } },
+  { $sort: { total: -1 } },
+  { $limit: 10 },
+  { $project: { category: '$_id', total: 1, _id: 0 } },
+]).toArray();
+```
+
+**Supported stages:** `$match`, `$project`, `$group`, `$sort`, `$limit`, `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`, `$replaceRoot`, `$set`, `$unionWith`, `$out`, `$merge`
+
+`$lookup` supports the equality form and a bounded correlated pipeline form with
+`let`, an optional `$match` using `$expr`/`$and`/`$eq`, and an optional following
+`$limit`. Correlated string equality predicates can use a full-key or subset
+foreign equality index to reduce candidates when available. Candidates are
+paged, the complete expression remains authoritative, and `$limit` counts only
+exact expression matches. Other BSON value shapes use the bounded scan path.
+Mixed `localField`/`foreignField` plus `pipeline` lookups and other inner stages
+are rejected explicitly. Complete filter trees are validated before data is
+read, and query nesting plus aggregation work are bounded.
+
+A leading `$match` narrows the pipeline's source load instead of filtering
+after it: only matching documents are materialized, using an equality index when
+one serves the filter and a bounded scan otherwise. Filter shapes the query
+matcher cannot pre-compile fall back to the unnarrowed load, so results are
+unchanged. The materialization limit therefore applies to the matched set, which
+is what lets `countDocuments(filter)` run against collections larger than it.
+
+**Group accumulators:** `$sum`, `$avg`, `$min`, `$max`, `$first`, `$last`, `$push`, `$addToSet`, `$count`
+
+### Indexes
+
+```typescript
+await collection.createIndex({ email: 1 }, { unique: true });
+await collection.createIndex({ name: 1, age: -1 });    // compound
+await collection.createIndex({ field: 1 }, { sparse: true });
+const indexes = await collection.listIndexes().toArray();
+await collection.dropIndex('email_1');
+await collection.dropIndexes();  // drop all except _id
+```
+
+> 🛡️ **Unique indexes are enforced at the engine level.** Duplicate values are rejected with a `DuplicateKey` error (code 11000) *before* the document is written to disk — on `insertOne`, `updateOne`, `findAndModify`, and upserts. Index definitions and entries are committed with native storage and survive restart.
+
+NoSQLDB supports ascending and descending index keys with `name`, `unique`,
+`sparse`, and `expireAfterSeconds` options. It accepts `background` as a
+validated no-op and index version `v: 2`. Unsupported options, including
+`partialFilterExpression`, `collation`, and `hidden`, are rejected before any
+index in the request is created. Native maintenance expires eligible BSON dates
+and date arrays in bounded batches, preserving publication holds and active
+snapshots.
+
+`find()` and collection `aggregate()` accept `hint` as an index name (including
+`_id_`) or an exact ascending/descending key pattern. Key-pattern order matters;
+if several indexes share a key pattern, use a name. The selected active scalar
+index supplies every candidate, using safe full-key or leading-prefix equality
+bounds, or a full scan of that index. The complete predicate still runs, and explicit sorting,
+projection, skip, and limit retain their normal semantics. Index traversal uses
+bounded pages from a pinned committed root across client requests. Unsorted results have no guaranteed BSON value order.
+
+```typescript
+await collection.createIndex({ organizationId: 1, userId: 1 }, { name: 'organization_user' });
+const page = await collection.find({ organizationId: 'org-1' }, {
+  hint: 'organization_user', sort: { userId: 1, _id: 1 }, skip: 20, limit: 10,
+}).toArray();
+const count = await collection.countDocuments({ organizationId: 'org-1' }, {
+  hint: 'organization_user',
+});
+```
+
+Unknown or quarantined indexes, malformed/ambiguous patterns, `$natural`, and
+hints on missing collections or views fail explicitly. Forced multikey traversal
+is unsupported and rejects; unhinted array queries keep their existing scan
+behavior. Sparse hints intentionally exclude documents absent from that index,
+including for empty filters and counts. A hint is never silently replaced by a
+collection scan or another index.
+
+Hinted transaction reads construct the selected index from the existing bounded
+transaction snapshot plus buffered writes; they never fetch candidate documents
+from live storage. Read-only aggregate source pipelines also use that transaction
+view. Foreign-collection stages (`$lookup`, `$unionWith`) and writing stages
+(`$out`, `$merge`), including stages inside `$facet`, reject within transactions.
+Nontransaction execution uses the streaming and bounded-resource paths below.
+
+### Scalable query execution
+
+Collections have no fixed total-document ceiling on the nontransaction `find`,
+`count`, `distinct`, `update`, `delete`, and `findAndModify` paths. Result cursors
+read bounded pages instead of retaining the whole result. Multi-document writes
+visit each source document once, including when updates move indexed values.
+Index publication stages changed keys instead of copying the complete collection
+index engine for each write.
+
+Nontransaction aggregation pipelines composed of `$match`, `$project`, `$unset`,
+`$set`, `$addFields`, `$replaceRoot`, `$replaceWith`, `$skip`, `$limit`, `$sort`,
+`$group`, `$count`, `$unwind`, `$lookup`, `$unionWith`, and `$facet` also operate
+beyond 10,000 input or output documents.
+Counts use exact collection metadata where applicable, otherwise stream matching
+records. A limit bounds the work needed to find the requested number of matches.
+Without a limit, exact counts continue to EOF. Hints, deadlines and empty-result
+shapes remain supported; signed BSON count overflow and resource exhaustion
+reject explicitly. Exact counts never substitute estimates, and transaction
+counts retain the snapshot admission limits described below.
+Grouping accumulates one group at a time after an external sort; constant-key
+groups stream directly. Group accumulator semantics follow the documented local
+expression surface; this does not add the complete MongoDB aggregation language.
+Unwind retains one input while expanding arrays across batches. Lookup scans
+bounded foreign pages or indexed candidates, then assembles one byte-bounded
+result document. Unindexed joins can still require repeated foreign scans.
+Facet branches replay a shared input buffer or temporary spool; their combined
+result must fit the BSON document budget.
+
+Scalar ordered indexes can satisfy complete sort keys after equality fields,
+including reverse traversal and mixed compound directions. This path currently
+requires distinct full index keys to preserve stable equal-key ordering. Arrays,
+unsupported BSON index types, and equal-key data use the general sort executor.
+Numeric comparison and scalar equality indexes share exact Int32, Int64, Double,
+and Decimal128 ordering, including large integers, signed zero, and NaNs.
+
+Small sorted limits retain top-k candidates. Larger sorts and groups use bounded
+runs in unnamed temporary files, with automatic cleanup on exhaustion, cursor
+closure, cancellation, errors, and process exit. Configure the shared resources
+through `NoSqlDbServer`:
+
+```typescript
+const server = new NoSqlDbServer({
+  storage: 'file',
+  storagePath: '/path/to/database',
+  query: {
+    sortBufferBytes: 4 * 1024 * 1024,
+    maxSortSpillBytes: 4 * 1024 * 1024 * 1024,
+    maxConcurrentSorts: 4,
+  },
+});
+```
+
+`sortBufferBytes` is an encoded-input target, not an exact allocator heap limit;
+a single BSON document may exceed the target. The spill budget includes retained
+cursor files, facet input spools, and simultaneous merge input/output. Exhausting resource admission
+returns an explicit error instead of truncating results. Cursor continuations
+share a 256 MiB accounting budget. One continuation admits at most 160 MiB plus
+4 KiB, including pinned query state, changed-document overlays and bounded
+large-index-key candidates. Wire batches and pending document pages retain their
+16 MiB limits. `distinct`
+results and individual group documents must fit their BSON response/document
+byte budgets. The 10,000-operation wire batch limit still applies to each request;
+the driver can split larger input batches.
+
+Native streaming reads pin a committed root across cursor pages. Later writes do
+not change that snapshot. Current authorization and publication ownership are
+revalidated before a continuation is served.
+Ownership checks, namespace gates, byte budgets, and `maxTimeMS` remain active
+through `getMore` and cleanup.
+
+Transactions use pinned roots and changed-document overlays; the total database
+size is not a transaction snapshot limit. Complete write sets remain bounded by
+transaction and native commit byte admission. `$out` and `$merge` have no
+10,000-document output ceiling; their atomic output is subject to the same write
+budgets and rejects before publication if those budgets are exceeded. Native
+database import uses private staging for larger supported exports, then publishes
+the catalog and receipt atomically. Existing old-engine storage is rejected
+without conversion.
+
+### Comparing performance with MongoDB
+
+The repository includes [benchmark/run.ts](benchmark/run.ts), which starts fresh,
+loopback-only NoSQLDB and original MongoDB processes with isolated temporary
+storage. Supply an original `mongod` executable; the harness does not download
+one or use a MongoDB-compatible replacement as the reference server.
+
+```bash
+NOSQLDB_RUST_BINARY="$PWD/rust/target/release/rustdb" \
+  MONGODB_BINARY=/path/to/original/mongod \
+  tsx benchmark/run.ts --engine both --sizes 1000,10001,100000 \
+  --concurrency 1,16 --repetitions 3 --samples 250 --warmup 50 \
+  > .nogit/scaling-comparison.jsonl
+```
+
+Run on Linux after building the current binary and stopping competing benchmark
+or build work. Both engines use the same driver and data, `w:1`, `j:true`, local
+reads, snapshot transactions, disabled retryable writes, and one connection per
+worker. MongoDB runs as a single-voter replica set. Repetitions alternate engine
+order. `--id-type string` covers string identifiers; `--payload-bytes` changes
+record size. Full scans and transactions use the separate `--scan-samples` count
+(default 3) because they are substantially more expensive.
+
+JSON-lines output records binary hashes, host/version metadata, correctness
+failures, seed/index time, latency percentiles, throughput, process RSS and peak
+RSS, CPU ticks, and physical read/write bytes. Temporary database directories are
+retained for inspection and their paths are recorded. Failed operations remain
+visible; they must not be compared as successful fast queries. Small sample
+counts and a shared development host are diagnostic evidence, not a general
+claim of superiority over MongoDB. The [recorded comparison](benchmark/readme.md)
+includes both measured improvements and remaining gaps.
+
+### Database & Admin
+
+```typescript
+await db.listCollections().toArray();
+await db.createCollection('new');
+await db.dropCollection('old');
+await db.dropDatabase();
+await db.stats();
+
+const admin = client.db().admin();
+await admin.listDatabases();
+await admin.ping();
+await admin.serverStatus();
+```
+
+NoSQLDB creates ordinary collections and one deliberately restricted view form.
+Capped collections, validators, collation, time-series collections, clustered
+indexes, encrypted fields, and all general view pipelines remain unsupported and
+are rejected before the database or namespace is created.
+
+### Restricted Deny-All Views
+
+The only accepted view definition is the exact deny-all pipeline below. This is
+intended for compatibility barriers such as renaming a legacy source and leaving
+its old namespace present but permanently empty:
+
+```typescript
+await db.collection('secrets').rename('secrets_v2');
+await db.createCollection('secrets', {
+  viewOn: 'secrets_v2',
+  pipeline: [{ $match: { $expr: { $eq: [1, 0] } } }],
+});
+```
+
+Both `viewOn` and `pipeline` are required. The pipeline must contain exactly one
+`$match` stage with exactly `$expr: { $eq: [1, 0] }`; empty pipelines, numeric or
+structural variants, additional stages, and additional collection-definition
+options are rejected with `InvalidOptions` (code 72) before mutation. Command
+metadata such as `$db`, `lsid`, `comment`, and API-version fields remains
+accepted. `viewOn` must identify an existing same-database collection or
+restricted view at creation time. General MongoDB views are not supported.
+
+The logical view has no physical collection. `find`, `count`, and `distinct`
+return empty results. `aggregate` starts with an empty source and still applies
+the client pipeline; `$lookup` and `$unionWith` resolve the view as empty.
+Transactions first reading a current view record an explicit empty snapshot; a
+transaction that captured a populated collection before it is renamed and
+replaced by a view keeps that original snapshot for `find`, `count`, and
+`distinct` until commit conflict handling. Inserts, updates, deletes,
+`findAndModify`, indexes, `$out`, `$merge`, rename, and other data mutations fail
+with `CommandNotSupportedOnView` (code 166). `dropCollection` is the supported
+DDL exception for removing a logical restricted view.
+
+Definitions are persisted in the physical `system.views` catalog. As in MongoDB,
+`listCollections` lists `system.views` as a physical storage collection and the
+logical namespace as type `view` with `{ viewOn, pipeline }`, read-only metadata,
+and no `idIndex`. `system.views` is reserved from direct wire reads,
+writes, index operations, create, drop, rename, and aggregation output. Whole
+database drop and trusted database export/import/digest operations handle it as
+physical catalog data. Export never materializes a view; cross-database import
+remaps the exact catalog `_id` database prefix. Startup validates databases whose
+publication lease can be acquired before listener bind; a publication-held
+database is validated on its first permit after release. Import validates before
+mutation. Malformed, oversized, noncanonical, duplicate, reserved, or colliding
+catalog state fails closed.
+
+`system.views` was not interpreted by earlier SmartDB releases. This reservation
+is a major-version compatibility boundary: before upgrading, operators must use
+the older release to rename or remove any unrelated physical `system.views`
+collection. Once upgraded, direct catalog rename or drop is intentionally
+rejected with code 166.
+
+### Bulk Operations
+
+```typescript
+const result = await collection.bulkWrite([
+  { insertOne: { document: { name: 'Bulk1' } } },
+  { updateOne: { filter: { name: 'X' }, update: { $set: { bulk: true } } } },
+  { deleteOne: { filter: { name: 'Expired' } } },
+]);
+```
+
+### Count & Distinct
+
+```typescript
+const count = await collection.countDocuments({ status: 'active' });
+const estimated = await collection.estimatedDocumentCount();
+const names = await collection.distinct('name');
+```
+
+---
+
+## Wire Protocol Commands
+
+| Category | Commands |
+|---|---|
+| **Handshake** | `hello`, `isMaster`, `ismaster` |
+| **CRUD** | `find`, `insert`, `update`, `delete`, `findAndModify`, `getMore`, `killCursors` |
+| **Aggregation** | `aggregate`, `count`, `distinct` |
+| **Indexes** | `createIndexes`, `dropIndexes`, `listIndexes` |
+| **Sessions** | `startSession`, `endSessions`, `killSessions` |
+| **Transactions** | `startTransaction`, `commitTransaction`, `abortTransaction` through driver sessions |
+| **Admin** | `ping`, `listDatabases`, `listCollections`, `drop`, `dropDatabase`, `create`, `serverStatus`, `dbStats`, `collStats`, `connectionStatus`, `renameCollection` |
+
+Advertises MongoDB wire protocol versions 0–21. The documented command surface is tested with the official `mongodb` Node.js driver version 7.5.x.
+
+OP_MSG parsing rejects unknown required flags, invalid CRC-32C checksums,
+duplicate BSON keys, noncanonical array indexes, malformed section boundaries,
+multiple body sections, duplicate or colliding document-sequence identifiers,
+and missing or non-string `$db` fields. Early command-envelope validation then
+accepts document sequences only as `insert.documents`, `update.updates`, or
+`delete.deletes`; empty, oversized, extra, mismatched, and body-colliding forms
+reject before authentication or command resources are acquired. All three accepted
+forms are consumed as the corresponding bulk command argument. Unknown optional
+flags are ignored. A message is limited to 48,000,000 bytes, each BSON document to
+16,777,216 bytes, and BSON nesting to 100 levels. One message may contain at most
+128 sections, 10,000 document-sequence documents, 100,000 BSON elements, and
+100,000 BSON document or array containers. The advertised `maxWriteBatchSize` is
+therefore 10,000.
+
+The `moreToCome` request flag is accepted only for the exact `endSessions` or
+`killSessions` cleanup envelope: an `admin` command body containing only the
+session array, `writeConcern: { w: 0 }`, and `$db: "admin"`, with no document
+sequence. It executes without a transport response and leaves the connection
+reusable. Every other `moreToCome` envelope closes before command routing or
+response-owned resource creation.
+
+Raw receive buffers and parsed requests are charged separately against a
+process-wide 256 MiB encoded-byte admission budget. A partial frame is charged by
+its incrementally reserved receive capacity, not by the length in its prefix.
+Receive leases retain their high-water charge until the buffer is dropped or
+successfully compacted, and every allocation growth is reconciled before another
+socket read. Large unread pipelines remain charged and are compacted only at
+geometric utilization thresholds; the budget is an encoded-input bound rather
+than a claim about exact allocator heap usage.
+
+### Read and Write Concerns and Wire Deadlines
+
+NoSQLDB serves every database from exactly one voting node and states its
+concern profile in those terms instead of ignoring or blanket-rejecting the
+fields:
+
+- **Write concern.** Every acknowledged write is fsynced to the write-ahead log
+  and the data file before the response is sent, so `w: 1`, `w: "majority"`
+  (the majority of one voter is that voter), and `j: true` are all satisfied by
+  the same durable commit. `w: 0` is acknowledged the same way whenever a
+  response is expected; the exact `writeConcern: { w: 0 }` `endSessions` and
+  `killSessions` envelopes still run without a transport response. `wtimeout`
+  bounds a replication wait that does not exist on one node and has no
+  additional effect. `w: N` for `N > 1` fails with `UnsatisfiableWriteConcern`
+  (code 100), tag-set modes fail with `UnknownReplWriteConcern` (code 79), and
+  `j: true` fails with `BadValue` (code 2) on the in-memory storage backend,
+  which does not journal. Write concern is accepted only on commands that
+  write (including DDL, user management, `commitTransaction`, and
+  `abortTransaction`) and is rejected with `InvalidOptions` (code 72) inside a
+  multi-statement transaction, where it belongs on the commit.
+- **Read concern.** `local`, `available`, `majority`, and `linearizable` all
+  observe the durably committed state, because nothing is acknowledged before
+  it is durable and reads never observe uncommitted transaction buffers.
+  `snapshot` is accepted only on the first statement of a multi-document
+  transaction and is served by the database-wide transaction snapshot
+  described below. Read concern is accepted on `find`, `count`, `distinct`,
+  and `aggregate` only, and `afterClusterTime`, `atClusterTime`, and
+  `afterOpTime` are rejected with `InvalidOptions` because a single node issues
+  no cluster time.
+- **Deadlines.** `maxTimeMS` attaches a cooperative deadline to the command.
+  It is checked at admission, during namespace-lock and maintenance-gate
+  waits, before `find`, `count`, and `distinct` materialize documents, between
+  documents in `insert` and `delete` batches, and immediately before a
+  transaction commit is handed to storage; expiry fails with `MaxTimeMSExpired`
+  (code 50). Database-permit waits keep their fixed internal timeout, and a
+  single storage step or an in-progress `update` batch runs to completion
+  before the next check, so a write that expires after its first documents
+  were published reports the expiry while those documents remain durable,
+  exactly like an interrupted MongoDB batch. The official driver transmits a
+  transaction's `maxCommitTimeMS` as `maxTimeMS` on `commitTransaction`; a
+  commit that expires before its batch is handed to storage publishes nothing,
+  records the transaction as aborted, and carries the
+  `UnknownTransactionCommitResult` label; the driver's commit retry then sees
+  `NoSuchTransaction` with `TransientTransactionError` and restarts the whole
+  transaction. `getMore` rejects `maxTimeMS` with `BadValue` because NoSQLDB
+  has no awaitData cursors, and a literal `maxCommitTimeMS` field is rejected
+  with `InvalidOptions`.
+
+Callers may therefore rely on a successful NoSQLDB response as a durable,
+single-node acknowledgement. They must not read it as a replica-backed
+acknowledgement: majority semantics across several voters arrive with
+replication.
+
+### Unsupported Administrative Commands
+
+NoSQLDB returns `CommandNotFound` (code 59) for the wire commands `validate`,
+`explain`, legacy `authenticate`, `buildInfo`/`buildinfo`, `hostInfo`,
+`whatsmyuri`, `getLog`, `getCmdLineOpts`, `getParameter`, `setFreeMonitoring`,
+`currentOp`, `killOp`, `top`, `profile`, `compact`, `reIndex`, `fsync`, and
+`connPoolSync`. These commands previously had placeholder success responses but
+do not yet implement their advertised MongoDB semantics. Authentication and
+authorization errors retain precedence; otherwise rejection occurs before
+database publication permits, session or transaction creation, and command
+dispatch. This restriction applies to the wire `validate` command, not the
+supported offline `--validate-data` tool. `getFreeMonitoringStatus` remains
+available and reports NoSQLDB's fixed disabled state.
+
+---
+
+## Rust Crate Architecture 🦀
+
+The Rust engine is organized as a Cargo workspace with 12 focused crates:
+
+| Crate | Purpose |
+|---|---|
+| `rustdb` | Binary entry point: TCP/Unix listener, management IPC, CLI |
+| `rustdb-config` | Server configuration types (serde, camelCase JSON) |
+| `rustdb-wire` | Wire protocol parser/encoder (OP_MSG, OP_QUERY, OP_REPLY) |
+| `rustdb-query` | Query matcher, update engine, aggregation, sort, projection |
+| `rustdb-state` | Internal deterministic storage commands, stable retry identities, and durable receipts |
+| `rustdb-kernel` | Native paged committed-log kernel with stable timelines, contiguous LSNs, strict recovery and exact receipt replay |
+| `rustdb-replication` | Internal non-serving OpenRaft 0.9.25 one-voter fresh-root foundation; not linked into the released `rustdb` server |
+| `rustdb-storage` | Native catalogs, documents, exact counts, staged imports, reclamation and bounded OpLog |
+| `rustdb-index` | Native index records, query plans, uniqueness, bounded builds and TTL |
+| `rustdb-txn` | Transaction + session management with snapshot isolation |
+| `rustdb-auth` | SCRAM-SHA-256 credential handling, user metadata persistence, RBAC checks |
+| `rustdb-commands` | 40+ command handlers wiring everything together |
+
+
+The native MVCC engine serves both memory and file storage.
+Its Rust APIs use `mvcc` modules and `Mvcc` type names independently of npm
+versions and persisted format versions. The K2 kernel stores immutable paged
+roots, typed BSON records and checksummed commit markers in one append stream.
+Snapshots pin roots; normal writes append changed pages. Descriptor-relative
+access and the enclosing native file-root lease protect the entire lifecycle.
+Ambiguous publication fences the owner until recovery. Confirmed close drains
+requests, sessions, cursors and retained workers before releasing ownership.
+
+The bounded page cache retains validated key prefixes for point lookups when
+large separators cannot fit as complete nodes. Prefix coverage grows with the
+probe length and preserves exact ordering; scans and writes use complete keys.
+This keeps unrelated small-key operations from repeatedly loading wide index
+separators without increasing the cache budget or changing the stored format.
+
+Document, catalog, exact-count, natural-order, index-entry, unique-owner,
+authentication, fencing and retry-receipt records share atomic publications.
+Transactions retain changed documents and immutable read views with byte and
+concurrency admission; they do not copy a complete database snapshot or impose a
+10,000-document base-snapshot ceiling. Reads, `getMore`, indexes and streaming
+aggregation use pinned bounded pages. Transaction sorts use the shared external
+sort executor. Successful retryable statements retain exact results, including
+generated IDs and zero-match outcomes, across restart. Failed statements do not
+receive success receipts. Session termination drains active work and retires its
+cursors.
+
+Custom indexes build in bounded batches under a writer reservation and become
+Ready together. Startup resumes interrupted builds under native ownership before
+serving. If a resumed build confirms duplicate keys or exceeds its work budget,
+its Building state remains intact and a secret-free warning identifies the need
+for explicit index repair. Reads avoid that index; indexed writes fail closed.
+Use the supported index drop/recreate operation to resolve it. Cancellation,
+corruption and uncertain publication fail startup. Held databases remain closed
+and are skipped during recovery; releasing a hold does not run extra mutations.
+Their interrupted indexes can recover on a later restart.
+
+Index names and aliases, sparse and unique constraints, empty collections,
+restricted-view catalogs and exact BSON survive supported database export/import.
+Native import replaces the entire data catalog and its publication receipt in
+one commit, preserving managed principal and allocation identities. Old pinned
+reads retain the previous catalog. Exact fenced retries append nothing; held
+replacements remain inaccessible until their exact receipt is released.
+
+The serving profile is:
+
+| Surface | Native support |
+|---|---|
+| Runtime | Linux and macOS; memory or current native file storage |
+| Wire data | `find`, `count`, `distinct`, `aggregate`, `getMore`, `killCursors`, `insert`, `update`, `delete`, `findAndModify`; supported `$out`/`$merge` |
+| Catalog/admin | Collection/database/index DDL, rename, listings, supported statistics and diagnostics, user/role administration |
+| Auth/sessions | SCRAM-SHA-256, logical sessions, snapshot transactions, commit/abort and durable retryable writes |
+| Management | Health, tenants, grants, attestation, fencing, publication holds, export/import and content digest |
+| Debug | Bounded current-session OpLog, atomic data revert, document/collection pages and dashboard |
+| Maintenance | Bounded TTL expiry, retired record reclamation, orphan import retirement and generation compaction |
+| Stopped storage | Native inspection and relocation; isolated authenticated rehearsal on its qualified platform profile |
+| Import/control admission | 100 MiB encoded import; bounded private staging and a small final catalog/receipt commit. Other control requests: 1 MiB |
+| External cluster | Replication and HA remain unsupported; the one-voter OpenRaft foundation is not linked into serving |
+
+These are operation and resource budgets, not total database/document limits.
+Unsupported options and commands reject explicitly. Imports that cannot fit one
+derived document or index entry within the native commit budget reject before
+publishing the replacement. Reclamation preserves pinned roots and retires parent
+identities only after their children have been handled. Automatic compaction
+requires at least 64 MiB of growth and 50% growth over its prior baseline.
+
+There is one serving engine and no Bitcask fallback. No historical storage or
+authentication conversion runs during startup or rehearsal. Conversion code,
+when explicitly commissioned, belongs exclusively in top-level `ts_migration/`.
+
+NoSQLDB makes no general MongoDB performance or feature-parity claim.
+Versioned packages contain Linux amd64/arm64 and macOS amd64/arm64 native
+executables through [@git.zone/tsrust](https://www.npmjs.com/package/@git.zone/tsrust).
+
+### Multi-host release artifacts
+
+Consumers obtain the matching engines from the same versioned
+`@lossless.org/nosqldb` npm tarball on npmjs or Verdaccio. It includes
+`dist_rust/rustdb_linux_amd64`, `dist_rust/rustdb_linux_arm64`,
+`dist_rust/rustdb_macos_amd64` and `dist_rust/rustdb_macos_arm64`, each accompanied
+by `<binary>.tsrust-build.json`. These provenance files contain `binarySha256`,
+the package version, Git commit and target. Verify the tarball's registry
+integrity and each executable's SHA-256 against that matching provenance file
+before installation. Both Linux artifacts are statically linked. Spark can
+extract and install these files independently of its compiled JavaScript bundle;
+NoSQLDB does not download engines at startup.
+
+Normal `tsrust` builds select only the current host's partition from `targetsByHost`. Releases use `tsrust matrix` to coordinate both partitions after the version commit exists, then publish only after native verification passes and every exact-commit binary has executed and passed strict provenance assembly.
+
+The release coordinator needs Git, Node.js, pnpm and SSH access to both configured builders. The Linux amd64 builder needs `aarch64-linux-gnu-gcc` and a registered Linux arm64 `binfmt` interpreter. Linux file storage requires kernel 5.6 or newer with `openat2` enabled. Cross-architecture file qualification requires QEMU linux-user 9.2 or newer; earlier versions cannot execute the secure path-resolution operations even when a simple executable probe passes. The Apple Silicon builder needs Rosetta. The matrix qualifies macOS first and then Linux; both partitions must pass before artifact assembly. Set these environment variables to authorized builders and their dedicated temporary roots:
+
+```bash
+export NOSQLDB_RELEASE_MACOS_SSH="release-user@mac-builder.example"
+export NOSQLDB_RELEASE_MACOS_TEMP_ROOT="/absolute/dedicated/nosqldb-release"
+export NOSQLDB_RELEASE_LINUX_SSH="release-user@linux-builder.example"
+export NOSQLDB_RELEASE_LINUX_TEMP_ROOT="/absolute/dedicated/nosqldb-release"
+```
+
+`gitzone release` first runs `pnpm run release:check-builders`, before creating a version commit or tag. It verifies the project-local tsrust version, compiles and executes the required architecture probes, and rejects missing cross-toolchains or emulation, an unsuitable macOS host, missing tools, or an unsafe remote temporary root. The release build then:
+
+1. Builds the TypeScript package and debug UI bundle from the version commit.
+2. Streams an exact Git bundle into isolated Linux and macOS SSH worker workspaces and installs each frozen lockfile.
+3. Runs the configured `release:verify-native` command on each worker: the full Rust workspace, TypeScript test checks, public API suite, and explicit-engine authentication/ownership/rehearsal tests through the worker's other packaged architecture. Tests use short, private disposable filesystem roots under `/var/tmp` on Linux and canonical `/tmp` on macOS. Linux builders must provide `/var/tmp` on a native-supported durable filesystem; tmpfs is rejected. Failures retain diagnostics and prevent assembly.
+4. Builds and executes the Linux amd64, Linux arm64, macOS arm64, and macOS amd64 binaries on their assigned workers.
+5. Retrieves bounded artifact sets and transactionally publishes the complete provenance-checked matrix into `dist_rust/`.
+
+No host address or path is stored in the repository. A failed run retains its unique local diagnostics and owner-marked remote diagnostics, then prints their paths. Remote cleanup is an owner-validated publication gate, and an incomplete matrix never replaces the prior `dist_rust/`.
+
+### Storage Engine Reliability 🔒
+
+- Atomic native publications include data, indexes, authentication, fences and
+  durable outcomes. File writes are acknowledged after durable commit.
+- Immutable roots keep reads stable through concurrent writes and compaction.
+- Checksums, frame identities and contiguous positions validate committed
+  history. Only a valid incomplete final append is repairable during owned
+  startup; complete or interior corruption is rejected.
+- Uncertain publication fences the engine until confirmed recovery.
+- Bounded maintenance reclaims unreachable records and obsolete generations
+  after their readers release them.
+- Unix listener startup preserves active sockets and non-socket targets.
+  Verified stale sockets are recoverable; cleanup checks the owned inode.
+
+### Data Integrity CLI 🔍
+
+```bash
+./dist_rust/rustdb_linux_amd64 --validate-data /path/to/data
+# {"schemaVersion":1,"databases":[{"name":"mydb","collections":["users"]}]}
+```
+
+The CLI uses the same stopped native namespace inspector. It validates storage,
+catalogs and indexes while retaining the existing native leases, without starting
+a listener or repairing the source. It returns JSON on success and a nonzero exit
+on failure. No configuration file is required. The operation has a one-hour
+deadline, 100,000 filesystem-entry and 1 TiB byte limits, and bounded native
+record/result admission. This is storage integrity evidence; it does not replace
+the full authenticated rehearsal or production ownership protocol.
+
+---
+
+## Testing Example
+
+```typescript
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { NoSqlDbServer } from '@lossless.org/nosqldb';
+import { MongoClient } from 'mongodb';
+
+let server: NoSqlDbServer;
+let client: MongoClient;
+
+tap.test('setup', async () => {
+  server = new NoSqlDbServer({ port: 27117 });
+  await server.start();
+  client = new MongoClient('mongodb://127.0.0.1:27117', { directConnection: true });
+  await client.connect();
+});
+
+tap.test('should insert and find', async () => {
+  const col = client.db('test').collection('items');
+  await col.insertOne({ name: 'Widget', price: 9.99 });
+  const item = await col.findOne({ name: 'Widget' });
+  expect(item?.price).toEqual(9.99);
+});
+
+tap.test('should track changes in oplog', async () => {
+  const oplog = await server.getOpLog();
+  expect(oplog.entries.length).toBeGreaterThan(0);
+  expect(oplog.entries[0].op).toEqual('insert');
+});
+
+tap.test('teardown', async () => {
+  await client.close();
+  await server.stop();
+});
+
+export default tap.start();
+```
+
+---
+
+## 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 [license](./license) file.
+
+**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  
+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.