@push.rocks/smartdb 5.0.0 → 5.0.2

package/dist_ts/ts_smartdb/service-types.js

@@ -59,4 +59,4 @@ export const normalizeSmartDbResourceFenceError = (errorArg) => {
     }
     return new SmartDbResourceFenceError(match[1], match[2], error);
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS10eXBlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3RzX3NtYXJ0ZGIvc2VydmljZS10eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUErQ0EsTUFBTSxDQUFDLE1BQU0sOEJBQThCLEdBQUc7SUFDNUMsaUJBQWlCO0lBQ2pCLGNBQWM7SUFDZCx1QkFBdUI7SUFDdkIsb0JBQW9CO0lBQ3BCLDBCQUEwQjtJQUMxQiwyQkFBMkI7SUFDM0Isc0JBQXNCO0lBQ3RCLHNCQUFzQjtJQUN0QixhQUFhO0lBQ2IseUJBQXlCO0lBQ3pCLDRCQUE0QjtJQUM1QixpQkFBaUI7SUFDakIsc0NBQXNDO0lBQ3RDLHNCQUFzQjtJQUN0QixzQkFBc0I7SUFDdEIsa0NBQWtDO0lBQ2xDLDJCQUEyQjtDQUNuQixDQUFDO0FBdUdYLE1BQU0sQ0FBQyxNQUFNLDBDQUEwQyxHQUFHO0lBQ3hELHdCQUF3QjtJQUN4Qiw0QkFBNEI7SUFDNUIsaUJBQWlCO0lBQ2pCLHdCQUF3QjtJQUN4QiwwQkFBMEI7Q0FDbEIsQ0FBQztBQUtYLE1BQU0sT0FBTyxxQ0FBc0MsU0FBUSxLQUFLO0lBRzlELFlBQ0UsT0FBbUQsRUFDbkQsVUFBa0IsRUFDbEIsUUFBa0I7UUFFbEIsS0FBSyxDQUFDLEdBQUcsT0FBTyxLQUFLLFVBQVUsRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxDQUFDLENBQUM7UUFDeEQsSUFBSSxDQUFDLElBQUksR0FBRyx1Q0FBdUMsQ0FBQztRQUNwRCxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLENBQUMsTUFBTSw4Q0FBOEMsR0FBRyxDQUM1RCxRQUFpQixFQUNqQixPQUFpQixFQUNWLEVBQUU7SUFDVCxNQUFNLEtBQUssR0FDVCxRQUFRLFlBQVksS0FBSztRQUN2QixDQUFDLENBQUMsUUFBUTtRQUNWLENBQUMsQ0FBQyxJQUFJLEtBQUssQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQztJQUNsQyxJQUNFLE9BQU8sT0FBTyxLQUFLLFFBQVE7V0FDeEIsQ0FBQywwQ0FBMEMsQ0FBQyxRQUFRLENBQ3JELE9BQXFELENBQ3RELEVBQ0QsQ0FBQztRQUNELE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUNELE9BQU8sSUFBSSxxQ0FBcUMsQ0FDOUMsT0FBcUQsRUFDckQsS0FBSyxDQUFDLE9BQU8sRUFDYixLQUFLLENBQ04sQ0FBQztBQUNKLENBQUMsQ0FBQztBQXdDRixNQUFNLE9BQU8seUJBQTBCLFNBQVEsS0FBSztJQUdsRCxZQUNFLE9BQXVDLEVBQ3ZDLFVBQWtCLEVBQ2xCLFFBQWtCO1FBRWxCLEtBQUssQ0FBQyxHQUFHLE9BQU8sS0FBSyxVQUFVLEVBQUUsRUFBRSxFQUFFLEtBQUssRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDO1FBQ3hELElBQUksQ0FBQyxJQUFJLEdBQUcsMkJBQTJCLENBQUM7UUFDeEMsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7SUFDdEIsQ0FBQztDQUNGO0FBRUQsTUFBTSxDQUFDLE1BQU0sa0NBQWtDLEdBQUcsQ0FDaEQsUUFBaUIsRUFDVixFQUFFO0lBQ1QsTUFBTSxLQUFLLEdBQ1QsUUFBUSxZQUFZLEtBQUs7UUFDdkIsQ0FBQyxDQUFDLFFBQVE7UUFDVixDQUFDLENBQUMsSUFBSSxLQUFLLENBQUMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUM7SUFDbEMsTUFBTSxLQUFLLEdBQUcsNkNBQTZDLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNoRixJQUNFLENBQUMsS0FBSztRQUNOLENBQUMsOEJBQThCLENBQUMsUUFBUSxDQUN0QyxLQUFLLENBQUMsQ0FBQyxDQUFtQyxDQUMzQyxFQUNELENBQUM7UUFDRCxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFDRCxPQUFPLElBQUkseUJBQXlCLENBQ2xDLEtBQUssQ0FBQyxDQUFDLENBQW1DLEVBQzFDLEtBQUssQ0FBQyxDQUFDLENBQUMsRUFDUixLQUFLLENBQ04sQ0FBQztBQUNKLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS10eXBlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3RzX3NtYXJ0ZGIvc2VydmljZS10eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUEwRUEsTUFBTSxDQUFDLE1BQU0sOEJBQThCLEdBQUc7SUFDNUMsaUJBQWlCO0lBQ2pCLGNBQWM7SUFDZCx1QkFBdUI7SUFDdkIsb0JBQW9CO0lBQ3BCLDBCQUEwQjtJQUMxQiwyQkFBMkI7SUFDM0Isc0JBQXNCO0lBQ3RCLHNCQUFzQjtJQUN0QixhQUFhO0lBQ2IseUJBQXlCO0lBQ3pCLDRCQUE0QjtJQUM1QixpQkFBaUI7SUFDakIsc0NBQXNDO0lBQ3RDLHNCQUFzQjtJQUN0QixzQkFBc0I7SUFDdEIsa0NBQWtDO0lBQ2xDLDJCQUEyQjtDQUNuQixDQUFDO0FBdUdYLE1BQU0sQ0FBQyxNQUFNLDBDQUEwQyxHQUFHO0lBQ3hELHdCQUF3QjtJQUN4Qiw0QkFBNEI7SUFDNUIsaUJBQWlCO0lBQ2pCLHdCQUF3QjtJQUN4QiwwQkFBMEI7Q0FDbEIsQ0FBQztBQUtYLE1BQU0sT0FBTyxxQ0FBc0MsU0FBUSxLQUFLO0lBRzlELFlBQ0UsT0FBbUQsRUFDbkQsVUFBa0IsRUFDbEIsUUFBa0I7UUFFbEIsS0FBSyxDQUFDLEdBQUcsT0FBTyxLQUFLLFVBQVUsRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxDQUFDLENBQUM7UUFDeEQsSUFBSSxDQUFDLElBQUksR0FBRyx1Q0FBdUMsQ0FBQztRQUNwRCxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLENBQUMsTUFBTSw4Q0FBOEMsR0FBRyxDQUM1RCxRQUFpQixFQUNqQixPQUFpQixFQUNWLEVBQUU7SUFDVCxNQUFNLEtBQUssR0FDVCxRQUFRLFlBQVksS0FBSztRQUN2QixDQUFDLENBQUMsUUFBUTtRQUNWLENBQUMsQ0FBQyxJQUFJLEtBQUssQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQztJQUNsQyxJQUNFLE9BQU8sT0FBTyxLQUFLLFFBQVE7V0FDeEIsQ0FBQywwQ0FBMEMsQ0FBQyxRQUFRLENBQ3JELE9BQXFELENBQ3RELEVBQ0QsQ0FBQztRQUNELE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUNELE9BQU8sSUFBSSxxQ0FBcUMsQ0FDOUMsT0FBcUQsRUFDckQsS0FBSyxDQUFDLE9BQU8sRUFDYixLQUFLLENBQ04sQ0FBQztBQUNKLENBQUMsQ0FBQztBQXdDRixNQUFNLE9BQU8seUJBQTBCLFNBQVEsS0FBSztJQUdsRCxZQUNFLE9BQXVDLEVBQ3ZDLFVBQWtCLEVBQ2xCLFFBQWtCO1FBRWxCLEtBQUssQ0FBQyxHQUFHLE9BQU8sS0FBSyxVQUFVLEVBQUUsRUFBRSxFQUFFLEtBQUssRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDO1FBQ3hELElBQUksQ0FBQyxJQUFJLEdBQUcsMkJBQTJCLENBQUM7UUFDeEMsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7SUFDdEIsQ0FBQztDQUNGO0FBRUQsTUFBTSxDQUFDLE1BQU0sa0NBQWtDLEdBQUcsQ0FDaEQsUUFBaUIsRUFDVixFQUFFO0lBQ1QsTUFBTSxLQUFLLEdBQ1QsUUFBUSxZQUFZLEtBQUs7UUFDdkIsQ0FBQyxDQUFDLFFBQVE7UUFDVixDQUFDLENBQUMsSUFBSSxLQUFLLENBQUMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUM7SUFDbEMsTUFBTSxLQUFLLEdBQUcsNkNBQTZDLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNoRixJQUNFLENBQUMsS0FBSztRQUNOLENBQUMsOEJBQThCLENBQUMsUUFBUSxDQUN0QyxLQUFLLENBQUMsQ0FBQyxDQUFtQyxDQUMzQyxFQUNELENBQUM7UUFDRCxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFDRCxPQUFPLElBQUkseUJBQXlCLENBQ2xDLEtBQUssQ0FBQyxDQUFDLENBQW1DLEVBQzFDLEtBQUssQ0FBQyxDQUFDLENBQUMsRUFDUixLQUFLLENBQ04sQ0FBQztBQUNKLENBQUMsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdb",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "private": false,
   "description": "A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.",
   "exports": {
@@ -42,6 +42,12 @@
     "readme.md",
     "third-party-notices.md"
   ],
+  "publishConfig": {
+    "executableFiles": [
+      "./dist_rust/rustdb_linux_amd64",
+      "./dist_rust/rustdb_linux_arm64"
+    ]
+  },
   "keywords": [
     "mongodb-compatible",
     "wire protocol",

package/readme.md

@@ -540,6 +540,7 @@ const db = new LocalSmartDb({
 | `getServer()` | `SmartdbServer` | Access the underlying server |
 | `running` | `boolean` | Whether the server is running |
 | `LocalSmartDb.inspectOfflineStringValue(input, options?)` | `Promise<TLocalSmartDbOfflineStringValueInspectionResult>` | Read one exact top-level string value from stopped file storage without starting or mutating the engine |
+| `LocalSmartDb.inspectOfflinePhysicalNamespaces(input, options?)` | `Promise<ILocalSmartDbOfflinePhysicalNamespaceInspectionResult>` | Validate stopped physical file storage and return only deterministic database and collection names |
 
 #### Offline String-Value Inspection
 
@@ -593,6 +594,67 @@ The TypeScript API enforces these bounds before creating the sidecar or serializ
 
 All numeric limits must be positive safe integers. The caller must stop and retain external ownership of the `LocalSmartDb` daemon for the full call. Current storage roots additionally enforce this through SmartDB's storage-owner lock. Roots created before that lock existed rely on the caller's external single-owner coordination plus descriptor and stability validation. One `timeoutMs` budget covers sidecar lookup/spawn, readiness, and the command. Cancellation or timeout kills and reaps the disposable sidecar before the call rejects.
 
+#### Offline Physical Namespace Inspection
+
+`inspectOfflinePhysicalNamespaces()` is a Linux-only management API for validating and listing the physical database and collection namespaces in a stopped SmartDB file-storage root. It uses Linux `openat2` descriptor traversal and starts only the disposable Rust management sidecar. It never calls `SmartdbServer.start()`, opens a database listener, initializes the storage adapter, runs migration or recovery, repairs a tail, truncates a WAL, compacts data, or persists a hint.
+
+```typescript
+import { LocalSmartDb } from '@push.rocks/smartdb';
+
+const namespaces = await LocalSmartDb.inspectOfflinePhysicalNamespaces({
+  folderPath: '/var/lib/myapp/smartdb',
+  limits: {
+    maximumEntries: 100_000,
+    maximumDatabases: 4096,
+    maximumCollections: 10_000,
+    maximumIndexes: 100_000,
+    maximumDataFileBytes: 256 * 1024 * 1024,
+    maximumWalFileBytes: 64 * 1024 * 1024,
+    maximumIndexFileBytes: 16 * 1024 * 1024,
+    maximumTotalFileBytes: 1024 * 1024 * 1024 * 1024,
+    maximumRecordsPerCollection: 1_000_000,
+    maximumRecordBytes: 17 * 1024 * 1024,
+    maximumResultBytes: 16 * 1024 * 1024,
+  },
+}, {
+  timeoutMs: 30_000,
+});
+
+// {
+//   schemaVersion: 1,
+//   databases: [
+//     { name: 'myapp', collections: ['MetadataDoc', 'system.views'] },
+//   ],
+// }
+```
+
+The result is exactly `{ schemaVersion: 1, databases: Array<{ name, collections }> }`. Databases and each database's collections are sorted by physical name, empty database directories are retained, and no documents, index definitions, record identifiers, or values cross the management boundary.
+
+The accepted root must contain the current `.__rustdb_internal/storage-owner.lock`; legacy roots without that lock are rejected. The sidecar takes the shared owner lock, so an active engine causes the call to fail. Every reported collection must have the canonical complete profile of regular `data.rdb`, `wal.rdb`, and `indexes.json` files. A regular `keydir.hint` is optional and is treated only as an allowed cache file. Missing canonical files, unexpected collection entries, malformed index metadata, invalid data or WAL records, symlinks, cross-filesystem traversal, resource-limit exhaustion, and changes observed during inspection fail the complete operation. No partial result is returned and the storage tree is not mutated.
+
+Inspection performs two full bounded passes and returns only if their namespace results and retained filesystem observations agree. The entry, database, collection, index, file-byte, and record limits are enforced independently on each pass, so total validation work is at most twice the corresponding caller cap. The result-size cap applies to the single serialized result. This is a contract for the current owner-locked canonical SmartDB file-storage profile, not a claim of compatibility with arbitrary MongoDB layouts, legacy SmartDB roots, or unspecified future storage formats.
+
+All limits are required; this API supplies no defaults or compatibility aliases. TypeScript validates the following bounds before creating the sidecar and revalidates `folderPath` after resolving it to an absolute path:
+
+| Input | Enforced range |
+|---|---|
+| `folderPath` | 1 to 4096 UTF-8 bytes before and after absolute resolution; no control characters |
+| Complete serialized request | At most 2,097,152 bytes |
+| `timeoutMs` | 1 to 2,147,483,647 milliseconds |
+| `maximumEntries` | 1 to 100,000 directory entries per pass |
+| `maximumDatabases` | 1 to 4,096 databases per pass |
+| `maximumCollections` | 1 to 10,000 collections per pass |
+| `maximumIndexes` | 1 to 100,000 index definitions per pass |
+| `maximumDataFileBytes` | 64 to 268,435,456 bytes per data file |
+| `maximumWalFileBytes` | 64 to 67,108,864 bytes per WAL file |
+| `maximumIndexFileBytes` | 2 to 16,777,216 bytes per index file |
+| `maximumTotalFileBytes` | 1 to 1,099,511,627,776 aggregate canonical collection-file bytes per pass |
+| `maximumRecordsPerCollection` | 1 to 1,000,000 data records plus WAL records/commit markers per collection per pass |
+| `maximumRecordBytes` | 22 to 17,825,792 bytes per record |
+| `maximumResultBytes` | 32 to 16,777,216 serialized result bytes |
+
+Every numeric value must be a safe integer. One optional `timeoutMs` budget and `AbortSignal` cover sidecar lookup/spawn, readiness, both inspection passes, and response delivery; timeout or cancellation kills and reaps the sidecar before rejection. For a point-in-time ownership proof, the caller must exclude every engine start and other storage lifecycle change continuously from before invocation through acceptance or handoff of the returned result. The owner lock proves that the engine was stopped during inspection, but it cannot replace that caller-held lifecycle exclusion after the sidecar releases its lock.
+
 ### SmartdbDebugServer
 
 Web-based debug dashboard served via `@api.global/typedserver`. Import from the `debugserver` subpath:
@@ -853,6 +915,18 @@ const names = await collection.distinct('name');
 
 Advertises MongoDB wire protocol versions 0–21. The documented command surface is tested with the official `mongodb` Node.js driver version 7.5.x.
 
+### Read and Write Concerns
+
+SmartDB 5.x does not implement MongoDB `readConcern` or `writeConcern`
+semantics. A command containing either top-level field is rejected with
+`InvalidOptions` (code 72) before authentication, session creation, transaction
+preparation, publication-gate acquisition, or database mutation. Callers must not
+interpret a successful SmartDB 5.x response as a majority or replica-backed
+acknowledgement. The exact `writeConcern: { w: 0 }` envelope used by the official
+driver for `endSessions`, and the equivalent envelope on `killSessions`, are
+accepted only to preserve best-effort session cleanup; neither is a database-write
+acknowledgement.
+
 ---
 
 ## Rust Crate Architecture 🦀

package/readme.plan.md

@@ -1,101 +1,296 @@
-# smartdb advancement plan
+# SmartDB advancement plan
 
-Status: canonical direction, approved 2026-07-21. Reread before starting any engine work.
-Baseline: @push.rocks/smartdb 2.13.2 (TypeScript API + rustdb Rust engine, ~36k Rust LOC, 255 test fns).
+Status: canonical direction, approved 2026-08-17. Reread before starting engine or
+managed-service work.
 
-## North star
+Baseline: `@push.rocks/smartdb` 5.0.1. SmartDB is a Rust database engine with a
+TypeScript lifecycle facade, a MongoDB wire-protocol command surface, file and
+memory storage, authentication, transactions, resource fencing, and official
+MongoDB Node.js driver integration.
 
-Make smartdb a boring database:
+## Product objective
 
-- **provably crash-consistent** — recovery behavior is a written contract, enforced by a harness, not an aspiration
-- **cost proportional to change** — a write that changes nothing costs nothing; a small change costs a small amount of WAL, oplog, index, and CPU
-- **bounded** — memory, cursors, sessions, scans, and on-disk growth all have enforced ceilings
-- **self-describing** — the engine can explain its own resource usage and slow operations without external tooling
+Build SmartDB into a commercially operated, MongoDB-driver-compatible managed
+database service in this order:
 
-## Evidence base (incident ledger)
+1. truthful and provable single-node engine
+2. certified compatibility profile
+3. managed single-node service
+4. replicated high-availability service
+5. whole-database placement and migration
+6. intra-database sharding only when customer scale requires it
 
-Every track below traces to a production incident on the dcrouter hub:
+Reimplementing MongoDB-compatible server behavior is the fixed strategy. It does
+not require inventing every persistence primitive: SmartDB owns the wire,
+semantic, execution, topology, and service contracts while the storage-substrate
+decision remains evidence-driven.
 
-1. **Immortal cursors / unreaped sessions** — cursors and transaction sessions accumulated without bound. Fixed in 2.13.x (`CursorOwner`, per-cursor and global byte caps in `rustdb-commands/src/context.rs`, `remove_connection_cursors`, `take_expired_sessions`). The class stays closed only if bounded-lifecycle remains a tested invariant.
-2. **Query-vs-storage divergence** — an empty `_id_` query index was created at restart while the storage KeyDir still held documents. Queries said "not found"; inserts hit the storage-layer duplicate check (`rustdb-storage/src/memory.rs` / `file.rs` `AlreadyExists`) and threw "already exists: document '<sha>'". Mitigated in 2.13.x (index rebuild at startup, quarantine of invalid legacy unique indexes). The invariant — query layer and storage layer must never disagree after recovery — is not yet machine-checked.
-3. **Write amplification on unchanged saves** — callers re-saving identical documents caused full document rewrites plus full before/after images in the oplog (10k entries / 64MB), driving rustdb to 45–82% CPU. Currently mitigated caller-side only (change-gated persistence in the main consumer). The engine still trusts callers not to churn.
-4. **Bulk-operation ceilings** — deleteMany batch limits and command-size caps made a large startup migration exceed its deadline and forced a rollback. Bulk work is client-paced, non-resumable, and dies with its connection.
-5. **Memory disproportion** — steady-state PSS reached 40–100× live data bytes at points (dual tree+hash indexes per field, allocator retention, oplog images). No ceiling is asserted anywhere.
+## Legal and provenance gate
 
-## Track 1 — Provable durability (foundation, non-negotiable)
+The official MongoDB wire-protocol documentation and specifications carry terms
+that expressly restrict commercial database and database-as-a-service adaptation.
+This plan does not interpret those terms. Before expanding compatibility work:
 
-- Write the **recovery contract**: for a process kill at any byte offset — during WAL append, compaction, or hint write — state exactly what is durable, what may be lost, and what is rebuilt.
-- Build a **crash-fuzz harness**: property-based runner that executes randomized workloads, kills the engine at random points, restarts, and asserts the invariants:
-  1. every acknowledged write is present
-  2. no phantom documents
-  3. query indexes agree exactly with the storage KeyDir (incident 2 becomes a permanent regression class)
-  4. unique constraints hold
-  5. cursor/session tables are empty after recovery
-- Make the harness a **CI gate**: no release ships without it green.
+- obtain written legal guidance for interoperability, clean-room implementation,
+  product claims, and trademarks
+- audit the provenance of existing compatibility code and tests
+- classify disputed material for retention, independent rewrite, or quarantine
+- document which behavioral evidence and test sources implementation teams may use
+- market the service under an approved SmartDB identity and compatibility claim
 
-Provable property: "kill -9 at any moment loses at most unacknowledged writes, and recovery always converges to a consistent index/storage view."
+No compatibility feature enters a commercial release without passing this gate.
 
-## Track 2 — Write-path economics: cost proportional to change
+## Maintenance policy
+
+SmartDB 5.x is the maintenance lane for existing consumers:
 
-- **Engine-side no-op write detection** — SHIPPED in 2.14.0: update/findAndModify post-images that equal the stored document (or differ only in the volatile `_updatedAt` metadata field) skip storage, WAL, index, and oplog entirely and report `matched=1, modified=0`. Counters in `serverStatus.writes`. Caller-side gating remains defense in depth, not the architecture.
-- **Oplog diet**: replace full before/after images with `{ns, id, opType, generation, optional patch}`. Consumers that need images read storage at the generation.
-- **Background compaction** (bitcask merge) with cooldown and rate limit, bounding `data.rdb` growth under update churn.
-- **Group commit**: coalesce WAL fsyncs across concurrent writers.
+- accept security fixes, data-correctness fixes, explicit rejection of unsupported
+  behavior, and bounded operability improvements
+- do not add broad MongoDB surface area or introduce a second durability model
+- keep persisted 5.x behavior supported until a tested offline conversion or
+  snapshot/restore migration into Storage VNext exists
+- release small fixes independently when their invariants and compatibility impact
+  can be verified in isolation
 
-Provable property: "N identical saves cost O(1) WAL bytes and O(1) oplog bytes after the first."
+Storage VNext is developed behind explicit format and capability boundaries. It
+must never dual-write through both the legacy and VNext commit paths.
 
-## Track 3 — Read-path economics
+## North-star architecture
 
-- **Index-assisted top-k**: extend the bounded sorted-scan work (2.13.2) so the planner walks an index in sort order instead of scanning and heap-selecting.
-- **Maintained aggregates**: per-collection counts and sizes served from maintained state, never full scans.
-- **Reads never schedule writes**: engine principle — no read path may enqueue hint rewrites, stat persistence, or any other write work.
+### Wire gateway
 
-Provable property: "a monitoring read loop at any frequency produces zero engine writes."
+- parse and encode the declared wire profile exactly
+- validate complete command schemas before acquiring resources or mutating state
+- advertise only capabilities and limits proven by target-driver handshake tests
+- reject every unsupported command, concern, or option explicitly
 
-## Track 4 — Server-side bulk and migration primitives
+### BSON semantic core
 
-- **Uncapped bulk operations**: deleteMany/updateMany execute engine-side with internal checkpointing (by generation / seek offset), not client-paced batches under command-size caps.
-- **Streaming IPC frames** for large results, retiring the command-size failure class.
-- **Re-attachable maintenance sessions**: a migration survives client disconnect; the client re-attaches by operation id and polls progress. The incident-4 rollback class becomes impossible.
-
-Provable property: "a 10M-row migration survives a client restart and completes exactly once."
-
-## Track 5 — Memory model: bounded and measured
-
-- **k-factor target**: steady-state PSS ≤ 3× live data bytes (observed today: 40–100× under some workloads).
-- **Single index representation** per field where one suffices; lazy-build the second form on demand.
-- KeyDir compaction / shrink-to-fit after mass deletes.
-- **Soak-test CI gate**: 24h synthetic churn workload asserting PSS plateaus within the k-factor.
-- Verify mimalloc purge/decommit settings under the soak test.
-
-Provable property: "PSS is a function of live data, not of history."
-
-## Track 6 — Operability and compatibility
-
-- **serverStatus counters**: no-op writes skipped, WAL bytes written, compaction stats, live cursors/sessions, per-collection sizes — the next incident gets diagnosed from the database, not from strace.
-- **Slow-op log** with thresholds.
-- **Offline toolbox**: `rustdb verify | dump | compact | repair-doc | backup` against a data directory.
-- **On-disk format manifest** with versioning and an N-1 rollback contract: any release can downgrade one release; format changes require a migration note.
-
-Allocation fencing exception: once a database name has an allocation-managed resource-lock marker, pre-allocation binaries intentionally fail closed. N-1 rollback must restore an allocation-aware binary; deleting or rewriting provider allocation metadata is not a supported downgrade path.
-
-Provable property: "any resource question an operator asks during an incident is answerable from serverStatus or the toolbox."
-
-## Fork in the road (decision rule, written now)
-
-Keep hardening the owned engine **while the Track 1 harness stays green**. If, after Tracks 1–2 land, the harness keeps finding structural durability holes, evaluate rebasing the storage layer on a proven embedded core (redb or fjall) behind the unchanged command surface. Revisit this rule once Track 1 is merged — not before, not on gut feeling.
-
-## Sequencing
-
-- **Done**: Track 2 no-op write detection + its serverStatus counters (2.14.0).
-- **Now** (after the current consumer release wave is verified in production): Track 1 harness + recovery contract.
-- **Next**: Track 2 oplog diet + compaction; Track 4 bulk primitives.
-- **Mid-term**: Track 3 read economics; Track 5 k-factor + soak gate; Track 6 toolbox + format manifest.
-
-Format-affecting changes (oplog diet, manifest) target a major version; everything else lands in 2.14+.
-
-## Non-goals
-
-- clustering or replication beyond the current oplog consumers
-- MongoDB API parity
-- multi-process writers
+- own one implementation of BSON equality, ordering, hashing, numeric promotion,
+  null/missing behavior, array traversal, typed identifiers, projections,
+  expressions, and updates
+- feed the same semantics into queries, indexes, transactions, aggregation,
+  uniqueness checks, and change streams
+
+### Planner and executor
+
+- use one planner for find, count, update, delete, aggregate, and explain
+- stream storage-backed cursors instead of materializing complete result sets
+- enforce deadlines, cancellation, admission, and work accounting at every loop
+
+### Transactional storage kernel
+
+- own one authoritative, checksummed, monotonically ordered commit log
+- assign a stable timeline and LSN to every committed mutation
+- commit documents, DDL, catalogs, index definitions, users, retryable-write
+  outcomes, and transaction outcomes through the same atomic boundary
+- serve database-wide MVCC snapshots and deterministic checkpoint-plus-log recovery
+
+### Replication
+
+- replicate the committed Storage VNext log through a reviewed consensus design
+- use consensus terms to fence leaders; allocation fencing controls placement and
+  publication but never substitutes for data-plane consensus
+- derive majority acknowledgement, failover, snapshot installation, causal times,
+  and retry outcomes from the replicated commit history
+
+### Administration and control plane
+
+- keep RBAC-protected database administration such as `currentOp`, `killOp`,
+  `explain`, and user management available through the certified wire surface
+- keep service administration such as provisioning, placement, billing, backup,
+  restore, upgrades, and incident actions on a separate privileged API
+- start with one process per tenant or isolated replica group; shared-process
+  tenancy requires hard per-tenant admission and noisy-neighbor proof
+
+## Phase 0: contract and measurement
+
+- complete the legal and provenance gate
+- select the first exact driver, ODM, topology, command, option, and error profile
+- maintain raw-wire and target-driver handshake tests
+- publish an out-of-band machine-readable compatibility manifest
+- version engine build, wire profile, storage format, and service API independently
+- establish baseline latency, memory, disk amplification, and restart benchmarks on
+  Linux amd64 and arm64
+
+Gate: approved implementation sources and claims, an exact compatibility profile,
+and reproducible baseline measurements.
+
+## Phase 1: truthful single-node behavior
+
+- stop over-advertising MongoDB version, wire behavior, and batch limits
+- reject ignored concerns, options, commands, and successful administrative stubs
+- validate OP_MSG required flags, checksums, and no-response behavior
+- preserve complete BSON type and value identity for document and index keys
+- reconcile ambiguous point-write failures before returning control to callers
+- journal DDL and sync every required file and parent directory
+- distinguish incomplete final records from interior corruption and fail closed
+- isolate or secure all debug and privileged management surfaces
+- add an operation registry, deadlines, cancellation, real `currentOp`/`killOp`, and
+  truthful metrics
+- write acknowledgement, recovery, corruption, and supported-filesystem contracts
+
+Gate: deterministic failpoints and randomized crashes produce no acknowledged-write
+loss, phantom documents, query/storage divergence, or unique-constraint violations
+within the declared single-node fault model.
+
+## Phase 2: conformance foundation
+
+- build a legally approved behavioral comparison harness
+- fuzz raw wire framing, flags, malformed BSON, and command boundaries
+- validate commands into typed internal representations before execution
+- add exact response, error-code, error-label, and side-effect contracts
+- generate semantic corpora across BSON types, boundaries, arrays, null/missing,
+  NaN, Decimal128, projections, paths, expressions, and identifiers
+- prevent any advertised capability from expanding without associated tests
+
+Gate: no known P0/P1 mismatch in the certified profile, and every unsupported path
+rejects before side effects.
+
+## Phase 3A: storage-substrate decision
+
+Evaluate the current custom engine and permissively licensed embedded transactional
+cores against the same requirements:
+
+- crash and power-loss behavior
+- atomic batch and MVCC support
+- checkpoint, backup, and replication integration
+- memory, latency, write amplification, and restart behavior
+- format ownership, migration, licensing, and supply-chain risk
+
+Gate: one architecture decision selects exactly one authoritative durability
+boundary. Dual-WAL and dual-commit designs are prohibited.
+
+## Phase 3B: Storage VNext
+
+- add a segmented, checksummed global commit log with stable timelines and LSNs
+- encode atomic data, DDL, catalog, index-metadata, and auth batches
+- persist request deduplication, retryable-write results, and transaction outcomes
+- add database-wide MVCC read timestamps and change-proportional transactions
+- replace full index-engine clones with incremental deltas
+- add immutable checkpoints, bounded replay, and a durable format manifest
+- move compaction to a rate-limited background service
+- add group commit and real batch publication
+- define an offline 5.x migration and N-1 compatibility contract
+
+Gates:
+
+- one-document transaction cost is independent of database size
+- repeated recovery is idempotent and produces the same content digest
+- ENOSPC, EIO, short writes, and failed fsyncs yield success, explicit ambiguity, or
+  fail-closed state, never silent divergence
+- 24-hour nightly and 72-hour release-candidate soaks meet declared memory, disk,
+  and restart ceilings on both Linux architectures
+
+## Phase 4: query, index, and resource model
+
+- implement one streaming planner/executor
+- use canonical order-preserving BSON index keys
+- add range, compound-prefix, and index-ordered top-k scans
+- implement correct multikey expansion, uniqueness, and TTL execution
+- compile predicates and regular expressions once per operation
+- implement positional updates and array-filter semantics
+- add process-wide and per-tenant admission for memory, scans, connections, I/O,
+  index builds, and maintenance
+- add configurable service classes and fair scheduling
+- add only features selected by the certified compatibility profile
+
+Semantic work may proceed after Phase 2. Retryable outcomes, transaction publication,
+and durable index publication depend on Storage VNext. Unsupported local concerns
+remain rejected until Storage VNext implements them; majority concerns remain
+rejected until replication implements them.
+
+Gate: bounded-memory scans at maximum declared scale, published p99 latency and
+capacity curves, proven tenant isolation, and zero certified-profile mismatches.
+
+## Phase 5: backup, PITR, and managed single-node service
+
+- create online immutable checkpoints at exact LSNs
+- archive subsequent commit-log segments continuously
+- encrypt, checksum, and sign backup manifests with timeline, format, LSN range,
+  and key identity
+- restore into a new root, replay to an exact LSN or timestamp, verify its content
+  digest, and promote atomically
+- retain logical export/import as migration tools rather than backup primitives
+- add versioned service classes, immutable node placement, node-bound grants,
+  TLS/mTLS endpoints, credential rotation/revocation, quotas, metering, backup
+  policy, maintenance windows, audit, and idempotent asynchronous operations
+- operate one process per tenant initially
+- qualify signed images, SBOM/provenance, canaries, rollback, alerts, runbooks, and
+  security before any general-availability claim
+
+Launch order: internal alpha, private beta, then single-node GA with explicit
+availability, RPO, RTO, capacity, and compatibility limits.
+
+Gate: repeated maximum-size restore drills meet the published RPO/RTO; billing
+reconciles; upgrades and rollback/restore pass; cross-tenant network, auth, quota,
+backup, and restore isolation is proven; no plaintext secret reaches persisted or
+logged state.
+
+## Phase 6: replication and high availability
+
+- replicate the Storage VNext log across three replicas in separate failure domains
+- add terms, quorum commit, snapshot installation, log catch-up, and membership
+  changes
+- implement truthful local and majority concerns
+- publish accurate `hello` topology and election metadata
+- add causal times, retryable outcomes, idempotent transaction commits, and
+  failover-safe session behavior
+- support mixed N/N-1 rolling upgrades
+- keep one database assigned to one replica group
+
+Majority RPO 0 means a majority-acknowledged write survives loss of any one replica
+within the declared replica-group fault model.
+
+Gate: no split-brain commits under partitions; accepted histories satisfy the
+declared consistency model; leader failure meets the published RTO; and retries
+return the original outcome exactly once.
+
+## Phase 7: managed HA and compatibility expansion
+
+- place complete databases across replica groups
+- migrate a database through checkpoint transfer, log catch-up, and an atomic
+  routing-epoch change
+- permanently fence stale owners
+- add automated replica replacement and maintenance-aware failover
+- derive durable change streams from the replicated commit log
+- certify additional drivers and ODMs
+- expand aggregation, views, indexes, and administrative behavior according to
+  measured workload demand
+- publish machine-generated compatibility and SLO matrices
+
+Gate: no open P0/P1 defect in the certified surface, regional and maintenance
+exercises pass, and customer-visible incident/status processes are operational.
+
+## Phase 8: horizontal scale
+
+Scale complete databases across replica groups first. Add intra-database sharding
+only after single-group limits become a measured customer constraint:
+
+- separate router and replicated placement catalog
+- range ownership and epochs
+- snapshot-plus-log range migration
+- stale-router rejection and permanent owner fencing
+- per-shard replica groups, balancing, and range cleanup
+- cross-shard transactions only as a separately justified program
+
+Gate: migration crashes cannot create gaps, duplicates, or dual writers; stale
+routing metadata cannot mutate old ownership; shard and region chaos meet the
+published SLOs.
+
+## Release qualification
+
+Every applicable release must pass the narrowest relevant set of these gates:
+
+- raw-wire and target-driver handshake tests
+- generated semantic and certified compatibility suites
+- deterministic persistence failpoints and randomized process-kill tests
+- storage/index/content-digest reconciliation after recovery
+- 24-hour nightly and 72-hour release-candidate resource soaks
+- both published Linux architectures
+- automated backup/restore drills once backup exists
+- partition, failover, and history verification once replication exists
+- supply-chain, provenance, security, upgrade, and rollback checks for managed tiers
+
+No release may advertise a capability, durability level, topology, or operational
+limit that its release qualification did not exercise.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdb',
-  version: '5.0.0',
+  version: '5.0.2',
   description: 'A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.'
 }

package/ts/index.ts

@@ -9,6 +9,9 @@ export type {
   ILocalSmartDbOptions,
   ILocalSmartDbConnectionInfo,
   ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalSmartDbOfflinePhysicalNamespaceInspection,
+  ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
 } from './ts_local/index.js';