@push.rocks/smartdb 2.15.3 → 2.16.0

package/dist_ts/ts_smartdb/service-types.d.ts

@@ -15,6 +15,30 @@ export interface ISmartDbHealth {
     collectionCount: number;
     uptimeSeconds?: number;
 }
+export interface ILocalSmartDbOfflineInspectionLimits {
+    maximumDataFileBytes: number;
+    maximumWalFileBytes: number;
+    maximumRecords: number;
+    maximumRecordBytes: number;
+    maximumResultBytes: number;
+}
+export interface ILocalSmartDbOfflineStringValueInspection {
+    folderPath: string;
+    databaseName: string;
+    collectionName: string;
+    match: {
+        field: string;
+        value: string;
+    };
+    valueField: string;
+    limits: ILocalSmartDbOfflineInspectionLimits;
+}
+export type TLocalSmartDbOfflineStringValueInspectionResult = {
+    status: 'not-found';
+} | {
+    status: 'found';
+    value: string;
+};
 export declare const smartDbResourceFenceErrorCodes: readonly ["EFENCE_REQUIRED", "EFENCE_STALE", "EFENCE_SCOPE_MISMATCH", "EFENCE_UNSUPPORTED", "EFENCE_MUTATION_MISMATCH", "EFENCE_OWNERSHIP_MISMATCH", "EFENCE_STATE_CORRUPT", "EFENCE_RECEIPT_LIMIT", "EFENCE_BUSY", "EFENCE_PUBLICATION_HELD", "EFENCE_CAPABILITY_MISMATCH", "EFENCE_NOT_HELD"];
 export type TSmartDbResourceFenceErrorCode = (typeof smartDbResourceFenceErrorCodes)[number];
 export interface ISmartDbResourceFence {

package/dist_ts/ts_smartdb/service-types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdb",
-  "version": "2.15.3",
+  "version": "2.16.0",
   "private": false,
   "description": "A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.",
   "exports": {
@@ -39,7 +39,8 @@
     "assets/**/*",
     "cli.js",
     ".smartconfig.json",
-    "readme.md"
+    "readme.md",
+    "third-party-notices.md"
   ],
   "keywords": [
     "mongodb-compatible",

package/readme.md

@@ -470,6 +470,59 @@ const db = new LocalSmartDb({
 | `getConnectionUri()` | `string` | Get the connection URI |
 | `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 |
+
+#### Offline String-Value Inspection
+
+`inspectOfflineStringValue()` is a Linux-only operational API for reading one metadata value while the owning `LocalSmartDb` engine is stopped. Other platforms reject the call because the reader requires Linux `openat2` descriptor traversal. It starts only the Rust management sidecar: it does not start a database listener, run storage migrations, repair tails, replay or truncate the WAL, compact data, or persist hints.
+
+```typescript
+import { LocalSmartDb } from '@push.rocks/smartdb';
+
+const result = await LocalSmartDb.inspectOfflineStringValue({
+  folderPath: '/var/lib/myapp/smartdb',
+  databaseName: 'myapp',
+  collectionName: 'MetadataDoc',
+  match: {
+    field: 'key',
+    value: 'migrationStateV1',
+  },
+  valueField: 'value',
+  limits: {
+    maximumDataFileBytes: 16 * 1024 * 1024,
+    maximumWalFileBytes: 16 * 1024 * 1024,
+    maximumRecords: 100_000,
+    maximumRecordBytes: 1024 * 1024,
+    maximumResultBytes: 1024 * 1024,
+  },
+}, {
+  timeoutMs: 5000,
+});
+
+if (result.status === 'found') {
+  console.log(result.value);
+}
+```
+
+The result is only `{ status: 'not-found' }` or `{ status: 'found', value: string }`. No other document fields cross the management boundary. The reader validates descriptor-safe paths, the current data/WAL format, CRCs and live-record semantics, applies any bounded uncommitted WAL overlay in memory, and rejects ambiguous matches, corruption, exceeded limits, symlinks, an engine-owned storage root, or files that change during inspection.
+
+The TypeScript API enforces these bounds before creating the sidecar or serializing the IPC request:
+
+| Input | Enforced range |
+|---|---|
+| `folderPath` | 1 to 4096 UTF-8 bytes before and after absolute resolution; no control characters |
+| `databaseName`, `collectionName` | 1 to 255 UTF-8 bytes; one canonical path component; no controls, slash, or backslash |
+| `match.field`, `valueField` | 1 to 255 UTF-8 bytes; no control characters |
+| `match.value` | 0 to 1,048,576 UTF-8 bytes and no larger than `maximumRecordBytes` |
+| Complete serialized request | At most 2,097,152 bytes |
+| `timeoutMs` | 1 to 2,147,483,647 milliseconds |
+| `maximumDataFileBytes` | 64 to 268,435,456 bytes |
+| `maximumWalFileBytes` | 64 to 67,108,864 bytes |
+| `maximumRecords` | 1 to 1,000,000 data/WAL items |
+| `maximumRecordBytes` | 22 to 17,825,792 bytes |
+| `maximumResultBytes` | 1 to 16,777,216 bytes |
+
+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.
 
 ### SmartdbDebugServer