@push.rocks/smartdb 2.15.4 → 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.4",
+  "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": {

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
 

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -5,7 +5,13 @@ export * from './ts_smartdb/index.js';
 
 // Export LocalSmartDb
 export { LocalSmartDb } from './ts_local/index.js';
-export type { ILocalSmartDbOptions, ILocalSmartDbConnectionInfo } from './ts_local/index.js';
+export type {
+  ILocalSmartDbOptions,
+  ILocalSmartDbConnectionInfo,
+  ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflineStringValueInspection,
+  TLocalSmartDbOfflineStringValueInspectionResult,
+} from './ts_local/index.js';
 
 // Export migration
 export {

package/ts/ts_local/classes.localsmartdb.ts

@@ -3,8 +3,18 @@ import * as fs from 'fs/promises';
 import * as net from 'net';
 import * as path from 'path';
 import * as os from 'os';
-import { SmartdbServer } from '../ts_smartdb/index.js';
+import {
+  RustDbBridge,
+  SmartdbServer,
+  type ILocalSmartDbOfflineStringValueInspection,
+  type ISmartDbManagementOperationOptions,
+  type TLocalSmartDbOfflineStringValueInspectionResult,
+} from '../ts_smartdb/index.js';
 import { StorageMigrator } from '../ts_migration/index.js';
+import {
+  normalizeLocalSmartDbOfflineInspectionInput,
+  validateSmartDbManagementOperationOptions,
+} from '../ts_smartdb/offline-inspection.js';
 
 /**
  * Connection information returned by LocalSmartDb.start()
@@ -60,6 +70,86 @@ export class LocalSmartDb {
     this.options = options;
   }
 
+  private static createOfflineInspectionBridge(): RustDbBridge {
+    return new RustDbBridge();
+  }
+
+  /**
+   * Inspect one exact string value while the owning LocalSmartDb engine is stopped.
+   * This starts only the Rust management sidecar and never initializes storage.
+   */
+  public static async inspectOfflineStringValue(
+    inputArg: ILocalSmartDbOfflineStringValueInspection,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<TLocalSmartDbOfflineStringValueInspectionResult> {
+    const validatedInput = normalizeLocalSmartDbOfflineInspectionInput(inputArg);
+    validateSmartDbManagementOperationOptions(optionsArg);
+    optionsArg?.signal?.throwIfAborted();
+
+    const input = normalizeLocalSmartDbOfflineInspectionInput({
+      ...validatedInput,
+      folderPath: path.resolve(validatedInput.folderPath),
+    });
+    const deadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : Date.now() + optionsArg.timeoutMs;
+    const bridge = LocalSmartDb.createOfflineInspectionBridge();
+    let operationFailed = false;
+    let operationError: unknown;
+    let result: TLocalSmartDbOfflineStringValueInspectionResult | undefined;
+    try {
+      let spawnOptions = optionsArg;
+      if (deadline !== undefined) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw new Error('SmartDB offline inspection timed out before sidecar spawn');
+        }
+        spawnOptions = {
+          signal: optionsArg?.signal,
+          timeoutMs: remainingMs,
+        };
+      }
+      if (!await bridge.spawn(spawnOptions)) {
+        throw new Error(
+          'smartdb Rust binary not found. Set SMARTDB_RUST_BINARY env var, ' +
+          'install the platform package, or build locally with `tsrust`.',
+        );
+      }
+      let commandOptions = optionsArg;
+      if (deadline !== undefined) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          throw new Error('SmartDB offline inspection timed out while starting the sidecar');
+        }
+        commandOptions = {
+          signal: optionsArg?.signal,
+          timeoutMs: remainingMs,
+        };
+      }
+      result = await bridge.inspectOfflineStringValue(input, commandOptions);
+    } catch (error) {
+      operationFailed = true;
+      operationError = error;
+    }
+
+    try {
+      await bridge.terminate({ gracePeriodMs: 0 });
+    } catch (terminationError) {
+      if (operationFailed) {
+        throw new AggregateError(
+          [operationError, terminationError],
+          'SmartDB offline inspection failed and sidecar termination was incomplete',
+          { cause: operationError },
+        );
+      }
+      throw terminationError;
+    }
+    if (operationFailed) {
+      throw operationError;
+    }
+    return result as TLocalSmartDbOfflineStringValueInspectionResult;
+  }
+
   /**
    * Generate a unique socket path in /tmp
    */

package/ts/ts_local/index.ts

@@ -1,2 +1,7 @@
 export { LocalSmartDb } from './classes.localsmartdb.js';
 export type { ILocalSmartDbOptions, ILocalSmartDbConnectionInfo } from './classes.localsmartdb.js';
+export type {
+  ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflineStringValueInspection,
+  TLocalSmartDbOfflineStringValueInspectionResult,
+} from '../ts_smartdb/service-types.js';

package/ts/ts_smartdb/index.ts

@@ -36,6 +36,9 @@ export type {
   ISmartDbCommitDatabasePublicationInput,
   ISmartDbManagementOperationOptions,
   ISmartDbDatabaseResourceFenceState,
+  ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflineStringValueInspection,
+  TLocalSmartDbOfflineStringValueInspectionResult,
   TSmartDbCommitDatabasePublicationResult,
   TSmartDbResourceFenceErrorCode,
   ISmartDbDatabaseTenantInput,

package/ts/ts_smartdb/offline-inspection.ts

@@ -0,0 +1,241 @@
+import * as plugins from './plugins.js';
+import type {
+  ILocalSmartDbOfflineStringValueInspection,
+  ISmartDbManagementOperationOptions,
+} from './service-types.js';
+
+export const localSmartDbOfflineInspectionBounds = {
+  maximumFolderPathBytes: 4096,
+  maximumNamespaceComponentBytes: 255,
+  maximumFieldNameBytes: 255,
+  maximumMatchValueBytes: 1024 * 1024,
+  maximumRequestBytes: 2 * 1024 * 1024,
+  maximumTimeoutMs: 2_147_483_647,
+  limits: {
+    maximumDataFileBytes: { minimum: 64, maximum: 256 * 1024 * 1024 },
+    maximumWalFileBytes: { minimum: 64, maximum: 64 * 1024 * 1024 },
+    maximumRecords: { minimum: 1, maximum: 1_000_000 },
+    maximumRecordBytes: { minimum: 22, maximum: 17 * 1024 * 1024 },
+    maximumResultBytes: { minimum: 1, maximum: 16 * 1024 * 1024 },
+  },
+} as const;
+
+const inputKeys = new Set([
+  'folderPath',
+  'databaseName',
+  'collectionName',
+  'match',
+  'valueField',
+  'limits',
+]);
+const matchKeys = new Set(['field', 'value']);
+const limitKeys = [
+  'maximumDataFileBytes',
+  'maximumWalFileBytes',
+  'maximumRecords',
+  'maximumRecordBytes',
+  'maximumResultBytes',
+] as const;
+const limitKeySet = new Set<string>(limitKeys);
+const requestStructuralBytes = plugins.buffer.Buffer.byteLength(
+  '{"folderPath":,"databaseName":,"collectionName":,"match":{"field":,"value":},"valueField":,"limits":{"maximumDataFileBytes":,"maximumWalFileBytes":,"maximumRecords":,"maximumRecordBytes":,"maximumResultBytes":}}',
+  'utf8',
+);
+const requestEnvelopeBytes = plugins.buffer.Buffer.byteLength(
+  '{"id":"req_9007199254740991","method":"inspectOfflineStringValue","params":}',
+  'utf8',
+);
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const rejectUnknownEnumerableKeys = (
+  valueArg: object,
+  allowedKeysArg: Set<string>,
+  labelArg: string,
+): void => {
+  for (const key in valueArg) {
+    if (!allowedKeysArg.has(key)) {
+      throw new TypeError(`LocalSmartDb offline inspection ${labelArg} contains unknown key '${key}'`);
+    }
+  }
+};
+
+const encodedJsonStringBytes = (valueArg: string): number => {
+  let bytes = 2;
+  for (let index = 0; index < valueArg.length; index++) {
+    const code = valueArg.charCodeAt(index);
+    if (
+      code === 0x22
+      || code === 0x5c
+      || code === 0x08
+      || code === 0x09
+      || code === 0x0a
+      || code === 0x0c
+      || code === 0x0d
+    ) {
+      bytes += 2;
+    } else if (code <= 0x1f) {
+      bytes += 6;
+    } else if (code <= 0x7f) {
+      bytes += 1;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = valueArg.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index++;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+
+const validateString = (
+  valueArg: unknown,
+  labelArg: string,
+  minimumBytesArg: number,
+  maximumBytesArg: number,
+  rejectControlsArg: boolean,
+): void => {
+  if (typeof valueArg !== 'string') {
+    throw new TypeError(`LocalSmartDb offline inspection ${labelArg} must be a string`);
+  }
+  const bytes = plugins.buffer.Buffer.byteLength(valueArg, 'utf8');
+  if (bytes < minimumBytesArg || bytes > maximumBytesArg) {
+    throw new RangeError(
+      `LocalSmartDb offline inspection ${labelArg} must be between ${minimumBytesArg} and ${maximumBytesArg} UTF-8 bytes`,
+    );
+  }
+  if (rejectControlsArg) {
+    for (const character of valueArg) {
+      if (/\p{Cc}/u.test(character)) {
+        throw new TypeError(
+          `LocalSmartDb offline inspection ${labelArg} must not contain control characters`,
+        );
+      }
+    }
+  }
+};
+
+export const normalizeLocalSmartDbOfflineInspectionInput = (
+  inputArg: ILocalSmartDbOfflineStringValueInspection,
+): ILocalSmartDbOfflineStringValueInspection => {
+  if (!isRecord(inputArg as unknown)) {
+    throw new TypeError('LocalSmartDb offline inspection input must be an object');
+  }
+  rejectUnknownEnumerableKeys(inputArg, inputKeys, 'input');
+  const inputRecord = inputArg as unknown as Record<string, unknown>;
+  const match = inputRecord.match;
+  if (!isRecord(match)) {
+    throw new TypeError('LocalSmartDb offline inspection match must be an object');
+  }
+  rejectUnknownEnumerableKeys(match, matchKeys, 'match');
+  const limits = inputRecord.limits;
+  if (!isRecord(limits)) {
+    throw new TypeError('LocalSmartDb offline inspection limits must be an object');
+  }
+  rejectUnknownEnumerableKeys(limits, limitKeySet, 'limits');
+
+  const normalized = {
+    folderPath: inputRecord.folderPath,
+    databaseName: inputRecord.databaseName,
+    collectionName: inputRecord.collectionName,
+    match: {
+      field: match.field,
+      value: match.value,
+    },
+    valueField: inputRecord.valueField,
+    limits: {
+      maximumDataFileBytes: limits.maximumDataFileBytes,
+      maximumWalFileBytes: limits.maximumWalFileBytes,
+      maximumRecords: limits.maximumRecords,
+      maximumRecordBytes: limits.maximumRecordBytes,
+      maximumResultBytes: limits.maximumResultBytes,
+    },
+  } as unknown as ILocalSmartDbOfflineStringValueInspection;
+
+  const bounds = localSmartDbOfflineInspectionBounds;
+  validateString(normalized.folderPath, 'folderPath', 1, bounds.maximumFolderPathBytes, true);
+  for (const [label, value] of [
+    ['databaseName', normalized.databaseName],
+    ['collectionName', normalized.collectionName],
+  ] as const) {
+    validateString(value, label, 1, bounds.maximumNamespaceComponentBytes, true);
+    if (value === '.' || value === '..' || value.includes('/') || value.includes('\\')) {
+      throw new TypeError(
+        `LocalSmartDb offline inspection ${label} must be one canonical path component`,
+      );
+    }
+  }
+  validateString(normalized.match.field, 'match.field', 1, bounds.maximumFieldNameBytes, true);
+  validateString(normalized.valueField, 'valueField', 1, bounds.maximumFieldNameBytes, true);
+  validateString(
+    normalized.match.value,
+    'match.value',
+    0,
+    bounds.maximumMatchValueBytes,
+    false,
+  );
+
+  for (const key of limitKeys) {
+    const value = normalized.limits[key];
+    const range = bounds.limits[key as keyof typeof bounds.limits];
+    if (!Number.isSafeInteger(value) || value < range.minimum || value > range.maximum) {
+      throw new RangeError(
+        `LocalSmartDb offline inspection limits.${key} must be a safe integer between ${range.minimum} and ${range.maximum}`,
+      );
+    }
+  }
+  if (plugins.buffer.Buffer.byteLength(normalized.match.value, 'utf8') > normalized.limits.maximumRecordBytes) {
+    throw new RangeError(
+      'LocalSmartDb offline inspection match.value must not exceed limits.maximumRecordBytes',
+    );
+  }
+
+  let requestBytes = requestEnvelopeBytes
+    + requestStructuralBytes
+    + encodedJsonStringBytes(normalized.folderPath)
+    + encodedJsonStringBytes(normalized.databaseName)
+    + encodedJsonStringBytes(normalized.collectionName)
+    + encodedJsonStringBytes(normalized.match.field)
+    + encodedJsonStringBytes(normalized.match.value)
+    + encodedJsonStringBytes(normalized.valueField);
+  for (const key of limitKeys) {
+    requestBytes += String(normalized.limits[key]).length;
+  }
+  if (requestBytes > bounds.maximumRequestBytes) {
+    throw new RangeError(
+      `LocalSmartDb offline inspection request exceeds the ${bounds.maximumRequestBytes}-byte serialized limit`,
+    );
+  }
+  return normalized;
+};
+
+export const validateSmartDbManagementOperationOptions = (
+  optionsArg?: ISmartDbManagementOperationOptions,
+): void => {
+  if (optionsArg === undefined) return;
+  if (!isRecord(optionsArg as unknown)) {
+    throw new TypeError('SmartDB management operation options must be an object');
+  }
+  if (
+    optionsArg.timeoutMs !== undefined
+    && (
+      !Number.isSafeInteger(optionsArg.timeoutMs)
+      || optionsArg.timeoutMs <= 0
+      || optionsArg.timeoutMs > localSmartDbOfflineInspectionBounds.maximumTimeoutMs
+    )
+  ) {
+    throw new RangeError(
+      `SmartDB management operation timeoutMs must be an integer between 1 and ${localSmartDbOfflineInspectionBounds.maximumTimeoutMs}`,
+    );
+  }
+};

package/ts/ts_smartdb/rust-db-bridge.ts

@@ -3,6 +3,10 @@ import * as path from 'path';
 import * as url from 'url';
 import { EventEmitter } from 'events';
 import { normalizeSmartDbResourceFenceError } from './service-types.js';
+import {
+  normalizeLocalSmartDbOfflineInspectionInput,
+  validateSmartDbManagementOperationOptions,
+} from './offline-inspection.js';
 import type {
   ISmartDbHealth,
   ISmartDbDatabaseTenantInput,
@@ -19,6 +23,8 @@ import type {
   ISmartDbCommitDatabasePublicationInput,
   ISmartDbManagementOperationOptions,
   ISmartDbDatabaseResourceFenceState,
+  ILocalSmartDbOfflineStringValueInspection,
+  TLocalSmartDbOfflineStringValueInspectionResult,
   TSmartDbCommitDatabasePublicationResult,
 } from './service-types.js';
 
@@ -39,6 +45,9 @@ export type {
   ISmartDbCommitDatabasePublicationInput,
   ISmartDbManagementOperationOptions,
   ISmartDbDatabaseResourceFenceState,
+  ILocalSmartDbOfflineInspectionLimits,
+  ILocalSmartDbOfflineStringValueInspection,
+  TLocalSmartDbOfflineStringValueInspectionResult,
   TSmartDbCommitDatabasePublicationResult,
 } from './service-types.js';
 
@@ -139,6 +148,10 @@ export interface ISmartDbMetrics {
  * Type-safe command definitions for the RustDb IPC protocol.
  */
 type TSmartDbCommands = {
+  inspectOfflineStringValue: {
+    params: ILocalSmartDbOfflineStringValueInspection;
+    result: TLocalSmartDbOfflineStringValueInspectionResult;
+  };
   transitionAuthMetadataPermissions: {
     params: { usersPath: string; expectedMode: number; targetMode: number };
     result: { status: TAuthMetadataPermissionTransitionStatus };
@@ -334,13 +347,70 @@ export class RustDbBridge extends EventEmitter {
    * Spawn the Rust binary in management mode.
    * Returns true if the binary was found and spawned successfully.
    */
-  public async spawn(): Promise<boolean> {
-    const spawned = await this.bridge.spawn();
-    if (spawned) {
-      this.terminationConfirmed = false;
-      this.terminationFailure = undefined;
+  public async spawn(optionsArg?: ISmartDbManagementOperationOptions): Promise<boolean> {
+    validateSmartDbManagementOperationOptions(optionsArg);
+    if (optionsArg?.signal?.aborted) {
+      throw new plugins.smartrust.RustBridgeRequestError(
+        'SmartDB Rust sidecar spawn was aborted before it started',
+        {
+          code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+          method: 'spawn',
+          cause: optionsArg.signal.reason,
+        },
+      );
+    }
+
+    this.terminationConfirmed = false;
+    this.terminationFailure = undefined;
+    const spawnPromise = this.bridge.spawn();
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let abortHandler: (() => void) | undefined;
+    const cancellationPromise = new Promise<never>((_resolveArg, rejectArg) => {
+      if (optionsArg?.timeoutMs !== undefined) {
+        timeout = setTimeout(() => {
+          rejectArg(new plugins.smartrust.RustBridgeRequestError(
+            `SmartDB Rust sidecar spawn timed out after ${optionsArg.timeoutMs}ms`,
+            {
+              code: 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
+              method: 'spawn',
+            },
+          ));
+        }, optionsArg.timeoutMs);
+      }
+      if (optionsArg?.signal) {
+        abortHandler = () => {
+          rejectArg(new plugins.smartrust.RustBridgeRequestError(
+            'SmartDB Rust sidecar spawn was aborted',
+            {
+              code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
+              method: 'spawn',
+              cause: optionsArg.signal!.reason,
+            },
+          ));
+        };
+        optionsArg.signal.addEventListener('abort', abortHandler, { once: true });
+      }
+    });
+
+    try {
+      const spawned = await Promise.race([spawnPromise, cancellationPromise]);
+      if (!spawned) {
+        await this.terminate({ gracePeriodMs: 0 });
+      }
+      return spawned;
+    } catch (error) {
+      try {
+        await this.terminate({ gracePeriodMs: 0 });
+      } catch (terminationError) {
+        throw new SmartDbManagementOperationTerminationError(error, terminationError);
+      }
+      throw error;
+    } finally {
+      if (timeout) clearTimeout(timeout);
+      if (abortHandler && optionsArg?.signal) {
+        optionsArg.signal.removeEventListener('abort', abortHandler);
+      }
     }
-    return spawned;
   }
 
   /**
@@ -431,6 +501,24 @@ export class RustDbBridge extends EventEmitter {
 
   // --- Convenience methods for each management command ---
 
+  public async inspectOfflineStringValue(
+    inputArg: ILocalSmartDbOfflineStringValueInspection,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<TLocalSmartDbOfflineStringValueInspectionResult> {
+    const input = normalizeLocalSmartDbOfflineInspectionInput(inputArg);
+    validateSmartDbManagementOperationOptions(optionsArg);
+    try {
+      return await this.bridge.sendCommand(
+        'inspectOfflineStringValue',
+        input,
+        optionsArg,
+      ) as TLocalSmartDbOfflineStringValueInspectionResult;
+    } catch (error) {
+      await this.awaitManagementOperationTermination(error);
+      throw error;
+    }
+  }
+
   public async transitionAuthMetadataPermissions(
     usersPathArg: string,
     expectedModeArg: number,

package/ts/ts_smartdb/service-types.ts

@@ -16,6 +16,30 @@ export interface ISmartDbHealth {
   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 const smartDbResourceFenceErrorCodes = [
   'EFENCE_REQUIRED',
   'EFENCE_STALE',