@push.rocks/smartdb 5.0.4 → 5.1.0

package/dist_ts/ts_smartdb/storage-root-relocation.d.ts

@@ -0,0 +1,27 @@
+export declare const localSmartDbStorageRootRelocationErrorCodes: readonly ["INVALID_REQUEST", "UNSUPPORTED", "BUSY", "NOT_FOUND", "DESTINATION_CONFLICT", "IDENTITY_MISMATCH", "STATE_CORRUPT", "IO", "RECOVERY_REQUIRED"];
+export type TLocalSmartDbStorageRootRelocationErrorCode = (typeof localSmartDbStorageRootRelocationErrorCodes)[number];
+export interface ILocalSmartDbStoppedStorageRootRelocationInput {
+    sourceFolderPath: string;
+    destinationFolderPath: string;
+    relocationId: string;
+}
+export interface ILocalSmartDbStoppedStorageRootRelocationReceipt {
+    format: 'smartdb.storage-root-relocation.receipt.v1';
+    version: 1;
+    relocationId: string;
+    sourceFolderPath: string;
+    destinationFolderPath: string;
+    providerRootId: string;
+    storageRootDevice: string;
+    storageRootInode: string;
+    receiptSha256: string;
+    sourceReceiptRetained: true;
+}
+export declare class LocalSmartDbStorageRootRelocationError extends Error {
+    readonly code: TLocalSmartDbStorageRootRelocationErrorCode;
+    constructor(codeArg: TLocalSmartDbStorageRootRelocationErrorCode);
+}
+export declare const normalizeLocalSmartDbStoppedStorageRootRelocationInput: (inputArg: ILocalSmartDbStoppedStorageRootRelocationInput) => ILocalSmartDbStoppedStorageRootRelocationInput;
+export declare const normalizeLocalSmartDbStoppedStorageRootRelocationReceipt: (valueArg: unknown, inputArg: ILocalSmartDbStoppedStorageRootRelocationInput) => ILocalSmartDbStoppedStorageRootRelocationReceipt;
+export declare const assertNoLocalSmartDbStorageRootRelocationWorkspace: (storagePathArg: string) => Promise<void>;
+export declare const isLocalSmartDbStorageRootRelocationErrorCode: (valueArg: unknown) => valueArg is TLocalSmartDbStorageRootRelocationErrorCode;

package/dist_ts/ts_smartdb/storage-root-relocation.js

@@ -0,0 +1,211 @@
+import * as plugins from './plugins.js';
+export const localSmartDbStorageRootRelocationErrorCodes = [
+    'INVALID_REQUEST',
+    'UNSUPPORTED',
+    'BUSY',
+    'NOT_FOUND',
+    'DESTINATION_CONFLICT',
+    'IDENTITY_MISMATCH',
+    'STATE_CORRUPT',
+    'IO',
+    'RECOVERY_REQUIRED',
+];
+export class LocalSmartDbStorageRootRelocationError extends Error {
+    constructor(codeArg) {
+        super(`SmartDB stopped storage-root relocation failed with code ${codeArg}`);
+        this.name = 'LocalSmartDbStorageRootRelocationError';
+        this.code = codeArg;
+    }
+}
+const relocationInputKeys = [
+    'sourceFolderPath',
+    'destinationFolderPath',
+    'relocationId',
+];
+const relocationReceiptKeys = [
+    'format',
+    'version',
+    'relocationId',
+    'sourceFolderPath',
+    'destinationFolderPath',
+    'providerRootId',
+    'storageRootDevice',
+    'storageRootInode',
+    'receiptSha256',
+    'sourceReceiptRetained',
+];
+const maximumFolderPathBytes = 4095;
+const maximumRelocationIdBytes = 256;
+const maximumU64Decimal = '18446744073709551615';
+const receiptDigestDomain = 'smartdb.storage-root-relocation.receipt.v1\0';
+const relocationError = (codeArg) => new LocalSmartDbStorageRootRelocationError(codeArg);
+const isPlainExactDataObject = (valueArg, keysArg) => {
+    if (typeof valueArg !== 'object'
+        || valueArg === null
+        || Array.isArray(valueArg)
+        || Object.getPrototypeOf(valueArg) !== Object.prototype) {
+        return false;
+    }
+    const ownKeys = Reflect.ownKeys(valueArg);
+    if (ownKeys.length !== keysArg.length
+        || ownKeys.some((keyArg) => typeof keyArg !== 'string' || !keysArg.includes(keyArg))) {
+        return false;
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+    return keysArg.every((keyArg) => {
+        const descriptor = descriptors[keyArg];
+        return descriptor !== undefined
+            && descriptor.enumerable
+            && Object.prototype.hasOwnProperty.call(descriptor, 'value');
+    });
+};
+const isValidUnicodeScalarString = (valueArg) => {
+    for (let index = 0; index < valueArg.length; index++) {
+        const code = valueArg.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = valueArg.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff)
+                return false;
+            index++;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+};
+const isNestedPath = (parentArg, childArg) => {
+    const relative = plugins.path.relative(parentArg, childArg);
+    return relative !== ''
+        && relative !== '..'
+        && !relative.startsWith(`..${plugins.path.sep}`)
+        && !plugins.path.isAbsolute(relative);
+};
+const normalizeFolderPath = (valueArg) => {
+    if (typeof valueArg !== 'string'
+        || !plugins.path.isAbsolute(valueArg)
+        || !isValidUnicodeScalarString(valueArg)
+        || [...valueArg].some(characterArg => /\p{Cc}/u.test(characterArg))) {
+        throw relocationError('INVALID_REQUEST');
+    }
+    const initialBytes = plugins.buffer.Buffer.byteLength(valueArg, 'utf8');
+    if (initialBytes < 1 || initialBytes > maximumFolderPathBytes) {
+        throw relocationError('INVALID_REQUEST');
+    }
+    const normalized = plugins.path.resolve(valueArg);
+    const normalizedBytes = plugins.buffer.Buffer.byteLength(normalized, 'utf8');
+    if (normalizedBytes < 1
+        || normalizedBytes > maximumFolderPathBytes
+        || plugins.path.parse(normalized).root === normalized
+        || !isValidUnicodeScalarString(normalized)
+        || [...normalized].some(characterArg => /\p{Cc}/u.test(characterArg))) {
+        throw relocationError('INVALID_REQUEST');
+    }
+    return normalized;
+};
+export const normalizeLocalSmartDbStoppedStorageRootRelocationInput = (inputArg) => {
+    if (!isPlainExactDataObject(inputArg, relocationInputKeys)) {
+        throw relocationError('INVALID_REQUEST');
+    }
+    const sourceFolderPath = normalizeFolderPath(inputArg.sourceFolderPath);
+    const destinationFolderPath = normalizeFolderPath(inputArg.destinationFolderPath);
+    const sourceFolderPathBytes = plugins.buffer.Buffer.byteLength(sourceFolderPath, 'utf8');
+    const destinationFolderPathBytes = plugins.buffer.Buffer.byteLength(destinationFolderPath, 'utf8');
+    if (sourceFolderPath === destinationFolderPath
+        || isNestedPath(sourceFolderPath, destinationFolderPath)
+        || isNestedPath(destinationFolderPath, sourceFolderPath)
+        || destinationFolderPathBytes > sourceFolderPathBytes) {
+        throw relocationError('INVALID_REQUEST');
+    }
+    if (typeof inputArg.relocationId !== 'string'
+        || plugins.buffer.Buffer.byteLength(inputArg.relocationId, 'utf8') > maximumRelocationIdBytes
+        || !/^[A-Za-z0-9][A-Za-z0-9._:@-]*$/.test(inputArg.relocationId)) {
+        throw relocationError('INVALID_REQUEST');
+    }
+    return {
+        sourceFolderPath,
+        destinationFolderPath,
+        relocationId: inputArg.relocationId,
+    };
+};
+const receiptDigest = (receiptArg) => plugins.crypto
+    .createHash('sha256')
+    .update(receiptDigestDomain, 'utf8')
+    .update(JSON.stringify(receiptArg), 'utf8')
+    .digest('hex');
+const isCanonicalU64Decimal = (valueArg) => typeof valueArg === 'string'
+    && /^(?:0|[1-9][0-9]{0,19})$/.test(valueArg)
+    && (valueArg.length < 20 || valueArg <= maximumU64Decimal);
+const isLowercaseSha256 = (valueArg) => typeof valueArg === 'string' && /^[0-9a-f]{64}$/.test(valueArg);
+export const normalizeLocalSmartDbStoppedStorageRootRelocationReceipt = (valueArg, inputArg) => {
+    if (!isPlainExactDataObject(valueArg, relocationReceiptKeys)) {
+        throw relocationError('RECOVERY_REQUIRED');
+    }
+    const receipt = valueArg;
+    if (receipt.format !== 'smartdb.storage-root-relocation.receipt.v1'
+        || receipt.version !== 1
+        || receipt.relocationId !== inputArg.relocationId
+        || receipt.sourceFolderPath !== inputArg.sourceFolderPath
+        || receipt.destinationFolderPath !== inputArg.destinationFolderPath
+        || !isLowercaseSha256(receipt.providerRootId)
+        || !isCanonicalU64Decimal(receipt.storageRootDevice)
+        || !isCanonicalU64Decimal(receipt.storageRootInode)
+        || !isLowercaseSha256(receipt.receiptSha256)
+        || receipt.sourceReceiptRetained !== true) {
+        throw relocationError('RECOVERY_REQUIRED');
+    }
+    const withoutDigest = {
+        format: receipt.format,
+        version: receipt.version,
+        relocationId: receipt.relocationId,
+        sourceFolderPath: receipt.sourceFolderPath,
+        destinationFolderPath: receipt.destinationFolderPath,
+        providerRootId: receipt.providerRootId,
+        storageRootDevice: receipt.storageRootDevice,
+        storageRootInode: receipt.storageRootInode,
+        sourceReceiptRetained: receipt.sourceReceiptRetained,
+    };
+    if (receiptDigest(withoutDigest) !== receipt.receiptSha256) {
+        throw relocationError('RECOVERY_REQUIRED');
+    }
+    return { ...withoutDigest, receiptSha256: receipt.receiptSha256 };
+};
+export const assertNoLocalSmartDbStorageRootRelocationWorkspace = async (storagePathArg) => {
+    const storagePath = plugins.path.resolve(storagePathArg);
+    const internalPath = plugins.path.join(storagePath, '.__rustdb_internal');
+    const workspacePath = plugins.path.join(internalPath, 'storage-root-relocation');
+    try {
+        const storage = await plugins.fs.stat(storagePath);
+        if (!storage.isDirectory()) {
+            throw new Error('not a directory');
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+    }
+    try {
+        const internal = await plugins.fs.lstat(internalPath);
+        if (internal.isSymbolicLink() || !internal.isDirectory()) {
+            throw new Error('not a safe directory');
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+    }
+    try {
+        await plugins.fs.lstat(workspacePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+    }
+    throw new Error('SmartDB storage-root relocation recovery must complete before startup');
+};
+export const isLocalSmartDbStorageRootRelocationErrorCode = (valueArg) => typeof valueArg === 'string'
+    && localSmartDbStorageRootRelocationErrorCodes.includes(valueArg);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZS1yb290LXJlbG9jYXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy90c19zbWFydGRiL3N0b3JhZ2Utcm9vdC1yZWxvY2F0aW9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBRXhDLE1BQU0sQ0FBQyxNQUFNLDJDQUEyQyxHQUFHO0lBQ3pELGlCQUFpQjtJQUNqQixhQUFhO0lBQ2IsTUFBTTtJQUNOLFdBQVc7SUFDWCxzQkFBc0I7SUFDdEIsbUJBQW1CO0lBQ25CLGVBQWU7SUFDZixJQUFJO0lBQ0osbUJBQW1CO0NBQ1gsQ0FBQztBQXdCWCxNQUFNLE9BQU8sc0NBQXVDLFNBQVEsS0FBSztJQUcvRCxZQUFtQixPQUFvRDtRQUNyRSxLQUFLLENBQUMsNERBQTRELE9BQU8sRUFBRSxDQUFDLENBQUM7UUFDN0UsSUFBSSxDQUFDLElBQUksR0FBRyx3Q0FBd0MsQ0FBQztRQUNyRCxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLG1CQUFtQixHQUFHO0lBQzFCLGtCQUFrQjtJQUNsQix1QkFBdUI7SUFDdkIsY0FBYztDQUNOLENBQUM7QUFDWCxNQUFNLHFCQUFxQixHQUFHO0lBQzVCLFFBQVE7SUFDUixTQUFTO0lBQ1QsY0FBYztJQUNkLGtCQUFrQjtJQUNsQix1QkFBdUI7SUFDdkIsZ0JBQWdCO0lBQ2hCLG1CQUFtQjtJQUNuQixrQkFBa0I7SUFDbEIsZUFBZTtJQUNmLHVCQUF1QjtDQUNmLENBQUM7QUFDWCxNQUFNLHNCQUFzQixHQUFHLElBQUksQ0FBQztBQUNwQyxNQUFNLHdCQUF3QixHQUFHLEdBQUcsQ0FBQztBQUNyQyxNQUFNLGlCQUFpQixHQUFHLHNCQUFzQixDQUFDO0FBQ2pELE1BQU0sbUJBQW1CLEdBQUcsOENBQThDLENBQUM7QUFFM0UsTUFBTSxlQUFlLEdBQUcsQ0FDdEIsT0FBb0Qs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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdb",
-  "version": "5.0.4",
+  "version": "5.1.0",
   "private": false,
   "description": "A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.",
   "exports": {

package/readme.hints.md

@@ -1,5 +1,14 @@
 # smartdb hints
 
+## Stopped Storage-Root Relocation
+
+- `LocalSmartDb.relocateStoppedStorageRoot()` is the only supported path-changing operation. It uses a dedicated serialized mutating sidecar runner; do not route it through the disposable offline-inspection helper. A bridge whose termination is unconfirmed remains in the static cleanup gate, and no later relocation may spawn until cleanup succeeds.
+- Rust owns the descriptor-relative operation in `rust/crates/rustdb/src/storage_root_relocation.rs`. It never constructs `RustDb`. The fixed journal phases are `preparing`, `prepared`, `exchanged`, `providerPublished`, `sentinelPublished`, and `cleaned`; retries reconcile the exact source-root/destination-absent-or-receipt topology or source-receipt/destination-root topology before continuing.
+- The destination receipt is published with `RENAME_NOREPLACE`, then exchanged with the source root using `RENAME_EXCHANGE`. Provider and sentinel replacement also uses checked exchanges, retaining each previous object in the workspace until the replacement is durable and verified. The original root inode ends at the destination and the original receipt inode remains at the source indefinitely. Parent, root, internal, lock, provider, and sentinel identities are revalidated around publication.
+- Eligibility is intentionally narrow: Linux, one supported local filesystem, exact current owner/provider/sentinel metadata, no auth path digest, and no resource receipt, allocation, retired lock, durable database/transaction workspace, database marker, symlink, unknown entry, or unsafe ownership/mode/link profile. Missing metadata is rejected and never initialized by relocation.
+- Both TypeScript startup paths check for `.__rustdb_internal/storage-root-relocation` before `StorageMigrator`. Rust checks immediately after securely opening an existing root and repeats the descriptor-relative check after acquiring the owner lock, before storage initialization. This closes the interval where a relocation can create its workspace and release the lock after startup's first inspection. Occupancy or inspection ambiguity is a startup error; only an exact relocation retry performs recovery.
+- Completed roots retain the SmartDB 5.0.1 provider/sentinel JSON shape, changing only their storage-root path digest. Interrupted state requires 5.1.0 or newer. Exact replay lasts only while the destination remains current; a later relocation supersedes the old source/destination tuple.
+
 ## Restricted Deny-All Views
 
 - `rustdb-commands/src/views.rs` is the sole owner of `system.views` parsing, bounds, canonical `_id_` metadata validation, exact deny-all pipeline validation, and authoritative namespace classification. There is intentionally no mutable cross-command view cache; aggregate and transaction commit reuse one immutable authoritative catalog per database for that operation.

package/readme.md

@@ -354,7 +354,7 @@ Legacy v0 JSON collections are converted into hidden sibling staging directories
 
 Persisted users also carry a random principal identity and a monotonic generation. SmartDB reloads and resolves that identity for every authenticated command, so password or role changes take effect immediately and stale sockets are rejected. Deleting and recreating the same username creates a different principal; an old connection cannot inherit the replacement user's authority. Cross-process user updates are serialized through the persisted users-file lock.
 
-Single-node transactions are supported through official MongoDB driver sessions. Writes with `startTransaction` and `autocommit: false` are buffered per logical session, reads inside the transaction see the buffered overlay, `commitTransaction` applies the write set with conflict checks, and `abortTransaction` discards it. Live logical sessions remain resumable across socket disconnects. Bounded background cleanup aborts expired transactions, removes expired sessions, and releases publication leases; explicit `endSessions` and `killSessions` do the same for their active transactions.
+Single-node transactions are supported through official MongoDB driver sessions. `find`, `count`, `distinct`, `insert`, `update`, `findAndModify`, and `delete` use the transaction snapshot and buffered write set; `commitTransaction` applies that write set with conflict checks, and `abortTransaction` discards it. After applicable authentication, authorization, and allocation-policy checks, collection, database, and index DDL, user-management mutations, and aggregate pipelines ending in `$out` or `$merge` reject transaction envelopes with `OperationNotSupportedInTransaction` (code 263) before session or transaction creation, maintenance gates, or mutation. Live logical sessions remain resumable across socket disconnects. Bounded background cleanup aborts expired transactions, removes expired sessions, and releases publication leases; explicit `endSessions` and `killSessions` do the same for their active transactions.
 
 ### Durable Database Publication Holds
 
@@ -539,9 +539,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.relocateStoppedStorageRoot(input, options?)` | `Promise<ILocalSmartDbStoppedStorageRootRelocationReceipt>` | Atomically relocate one eligible stopped Linux file-storage root and retain a source receipt |
 | `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 |
 
+#### 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 is Linux-only and requires the source root, source parent, and destination parent to be trusted descriptor-safe objects on the same supported local filesystem. The supplied source and destination must be absolute and resolve to distinct, non-root, non-nested paths, and the destination must be absent. The trusted parents may differ.
+
+```typescript
+import { LocalSmartDb } from '@push.rocks/smartdb';
+
+const receipt = await LocalSmartDb.relocateStoppedStorageRoot({
+  sourceFolderPath: '/var/lib/myapp/harness-controller/smartdb',
+  destinationFolderPath: '/var/lib/myapp/hcon/smartdb',
+  relocationId: 'move-2026-08-17-1',
+}, {
+  timeoutMs: 30_000,
+});
+
+// Start only the destination. The source is now the retained receipt file.
+const db = new LocalSmartDb({ 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. The normalized destination path may not be longer in UTF-8 bytes than the normalized source path, so every root-relative path accepted by SmartDB 5.0.1 at the source remains no longer after relocation. `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 SmartDB management operations.
+
+The returned exact receipt has this shape:
+
+```typescript
+interface ILocalSmartDbStoppedStorageRootRelocationReceipt {
+  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. SmartDB does not remove that source receipt. Data, WAL, hint, and index bytes are not copied or rewritten. `providerRootId`, root device/inode, and every provider/sentinel field are preserved; only `storageRootSha256` changes to the destination's canonical path digest. This leaves a completed destination compatible with SmartDB 5.0.1.
+
+Relocation deliberately supports only the plain, unbound `LocalSmartDb` topology. The existing owner lock, `provider-identity.json`, and resource-fencing sentinel must all be present; the operation never creates missing ownership metadata. A provider identity containing `authUsersPathSha256` is unsupported. Any durable fence receipt or capability, allocation state, retired fence lock, database mutation/transaction journal, allocation/publication marker, symlink, unknown entry, unsafe mode/owner/link count, exhausted scan bound, active owner, or ambiguous identity fails closed.
+
+The operation journals phases `preparing`, `prepared`, `exchanged`, `providerPublished`, `sentinelPublished`, and `cleaned`. If a call returns `RECOVERY_REQUIRED`, stop all startup attempts and retry the exact same normalized source path, destination path, and `relocationId` with SmartDB 5.1.0 or newer. Startup rejects any relocation-workspace occupancy and does not mutate or recover it. Do not delete, rename, edit, or replace either path between attempts. An interrupted relocation requires 5.1.0-or-newer recovery even though a completed root remains 5.0.1-compatible.
+
+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 `LocalSmartDbStorageRootRelocationError` with a code-only union: `INVALID_REQUEST`, `UNSUPPORTED`, `BUSY`, `NOT_FOUND`, `DESTINATION_CONFLICT`, `IDENTITY_MISMATCH`, `STATE_CORRUPT`, `IO`, or `RECOVERY_REQUIRED`. Error messages and causes do not include supplied paths. Timeout, abort, write, exit, or malformed-response failures after command dispatch are always `RECOVERY_REQUIRED`; exact retry is the only recovery action.
+
 #### 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.

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -14,6 +14,13 @@ export type {
   ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
+  ILocalSmartDbStoppedStorageRootRelocationInput,
+  ILocalSmartDbStoppedStorageRootRelocationReceipt,
+  TLocalSmartDbStorageRootRelocationErrorCode,
+} from './ts_local/index.js';
+export {
+  LocalSmartDbStorageRootRelocationError,
+  localSmartDbStorageRootRelocationErrorCodes,
 } from './ts_local/index.js';
 
 // Export migration

package/ts/ts_local/classes.localsmartdb.ts

@@ -4,20 +4,32 @@ import * as net from 'net';
 import * as path from 'path';
 import * as os from 'os';
 import {
-  RustDbBridge,
   SmartdbServer,
   type ILocalSmartDbOfflinePhysicalNamespaceInspection,
   type ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
+  type ILocalSmartDbStoppedStorageRootRelocationInput,
+  type ILocalSmartDbStoppedStorageRootRelocationReceipt,
   type ILocalSmartDbOfflineStringValueInspection,
   type ISmartDbManagementOperationOptions,
   type TLocalSmartDbOfflineStringValueInspectionResult,
 } from '../ts_smartdb/index.js';
+import {
+  RustDbBridge,
+  rustDbBridgeStorageRootRelocation,
+} from '../ts_smartdb/rust-db-bridge.js';
 import { StorageMigrator } from '../ts_migration/index.js';
 import {
   normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput,
   normalizeLocalSmartDbOfflineInspectionInput,
   validateSmartDbManagementOperationOptions,
 } from '../ts_smartdb/offline-inspection.js';
+import {
+  assertNoLocalSmartDbStorageRootRelocationWorkspace,
+  isLocalSmartDbStorageRootRelocationErrorCode,
+  LocalSmartDbStorageRootRelocationError,
+  normalizeLocalSmartDbStoppedStorageRootRelocationInput,
+  normalizeLocalSmartDbStoppedStorageRootRelocationReceipt,
+} from '../ts_smartdb/storage-root-relocation.js';
 
 /**
  * Connection information returned by LocalSmartDb.start()
@@ -65,6 +77,8 @@ export interface ILocalSmartDbOptions {
  * ```
  */
 export class LocalSmartDb {
+  private static storageRootRelocationGate: Promise<void> = Promise.resolve();
+  private static storageRootRelocationBridge: RustDbBridge | undefined;
   private options: ILocalSmartDbOptions;
   private server: SmartdbServer | null = null;
   private generatedSocketPath: string | null = null;
@@ -77,6 +91,141 @@ export class LocalSmartDb {
     return new RustDbBridge();
   }
 
+  private static createStorageRootRelocationBridge(): RustDbBridge {
+    return new RustDbBridge();
+  }
+
+  private static async withStorageRootRelocationGate<TResult>(
+    operationArg: () => Promise<TResult>,
+  ): Promise<TResult> {
+    const previous = LocalSmartDb.storageRootRelocationGate;
+    let release!: () => void;
+    LocalSmartDb.storageRootRelocationGate = new Promise<void>((resolveArg) => {
+      release = resolveArg;
+    });
+    await previous;
+    try {
+      return await operationArg();
+    } finally {
+      release();
+    }
+  }
+
+  private static remainingManagementTimeout(
+    deadlineArg: number | undefined,
+  ): number | undefined {
+    if (deadlineArg === undefined) return undefined;
+    const remaining = deadlineArg - Date.now();
+    if (remaining <= 0) {
+      throw new LocalSmartDbStorageRootRelocationError('IO');
+    }
+    return remaining;
+  }
+
+  /**
+   * Relocate one stopped, plain file-storage root without starting its engine.
+   */
+  public static async relocateStoppedStorageRoot(
+    inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ILocalSmartDbStoppedStorageRootRelocationReceipt> {
+    let input: ILocalSmartDbStoppedStorageRootRelocationInput;
+    try {
+      input = normalizeLocalSmartDbStoppedStorageRootRelocationInput(inputArg);
+      validateSmartDbManagementOperationOptions(optionsArg);
+    } catch (error) {
+      if (error instanceof LocalSmartDbStorageRootRelocationError) throw error;
+      throw new LocalSmartDbStorageRootRelocationError('INVALID_REQUEST');
+    }
+    if (optionsArg?.signal?.aborted) {
+      throw new LocalSmartDbStorageRootRelocationError('IO');
+    }
+    if (process.platform !== 'linux') {
+      throw new LocalSmartDbStorageRootRelocationError('UNSUPPORTED');
+    }
+    const deadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : Date.now() + optionsArg.timeoutMs;
+
+    return LocalSmartDb.withStorageRootRelocationGate(async () => {
+      const retainedBridge = LocalSmartDb.storageRootRelocationBridge;
+      if (retainedBridge) {
+        try {
+          await retainedBridge.terminate({ gracePeriodMs: 0 });
+        } catch {
+          throw new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+        if (!retainedBridge.ownershipReleased) {
+          throw new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+        if (LocalSmartDb.storageRootRelocationBridge === retainedBridge) {
+          LocalSmartDb.storageRootRelocationBridge = undefined;
+        }
+      }
+
+      let bridge: RustDbBridge | undefined;
+      let receipt: ILocalSmartDbStoppedStorageRootRelocationReceipt | undefined;
+      let operationError: LocalSmartDbStorageRootRelocationError | undefined;
+      try {
+        bridge = LocalSmartDb.createStorageRootRelocationBridge();
+        LocalSmartDb.storageRootRelocationBridge = bridge;
+        const spawnTimeout = LocalSmartDb.remainingManagementTimeout(deadline);
+        const spawned = await bridge.spawn({
+          ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+          ...(spawnTimeout === undefined ? {} : { timeoutMs: spawnTimeout }),
+        });
+        if (!spawned) {
+          throw new LocalSmartDbStorageRootRelocationError('IO');
+        }
+        const commandTimeout = LocalSmartDb.remainingManagementTimeout(deadline);
+        const result = await bridge[rustDbBridgeStorageRootRelocation](input, {
+          ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+          ...(commandTimeout === undefined ? {} : { timeoutMs: commandTimeout }),
+        });
+        receipt = normalizeLocalSmartDbStoppedStorageRootRelocationReceipt(result, input);
+      } catch (error) {
+        if (error instanceof LocalSmartDbStorageRootRelocationError) {
+          operationError = error;
+        } else {
+          const requestWasDispatched = error instanceof Error
+            && 'requestId' in error
+            && typeof error.requestId === 'string';
+          if (
+            requestWasDispatched
+            && error instanceof Error
+            && 'responseErrorCode' in error
+            && isLocalSmartDbStorageRootRelocationErrorCode(error.responseErrorCode)
+          ) {
+            operationError = new LocalSmartDbStorageRootRelocationError(error.responseErrorCode);
+          } else {
+            operationError = new LocalSmartDbStorageRootRelocationError(
+              requestWasDispatched ? 'RECOVERY_REQUIRED' : 'IO',
+            );
+          }
+        }
+      }
+
+      if (bridge) {
+        try {
+          await bridge.terminate({ gracePeriodMs: 0 });
+          if (!bridge.ownershipReleased) {
+            throw new Error('termination was not confirmed');
+          }
+          if (LocalSmartDb.storageRootRelocationBridge === bridge) {
+            LocalSmartDb.storageRootRelocationBridge = undefined;
+          }
+        } catch {
+          operationError = new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+      }
+      if (operationError) throw operationError;
+      if (!receipt) {
+        throw new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+      }
+      return receipt;
+    });
+  }
+
   private static async runOfflineInspection<
     TInput extends { folderPath: string },
     TResult,
@@ -261,6 +410,7 @@ export class LocalSmartDb {
     await LocalSmartDb.cleanStaleSockets();
 
     // Run storage migration before starting the Rust engine
+    await assertNoLocalSmartDbStorageRootRelocationWorkspace(this.options.folderPath);
     const migrator = new StorageMigrator(this.options.folderPath);
     await migrator.run();
 

package/ts/ts_local/index.ts

@@ -8,3 +8,12 @@ export type {
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
 } from '../ts_smartdb/service-types.js';
+export type {
+  ILocalSmartDbStoppedStorageRootRelocationInput,
+  ILocalSmartDbStoppedStorageRootRelocationReceipt,
+  TLocalSmartDbStorageRootRelocationErrorCode,
+} from '../ts_smartdb/storage-root-relocation.js';
+export {
+  LocalSmartDbStorageRootRelocationError,
+  localSmartDbStorageRootRelocationErrorCodes,
+} from '../ts_smartdb/storage-root-relocation.js';

package/ts/ts_smartdb/index.ts

@@ -81,5 +81,14 @@ export {
   normalizeSmartDbResourceFenceError,
   smartDbResourceFenceErrorCodes,
 } from './service-types.js';
+export type {
+  ILocalSmartDbStoppedStorageRootRelocationInput,
+  ILocalSmartDbStoppedStorageRootRelocationReceipt,
+  TLocalSmartDbStorageRootRelocationErrorCode,
+} from './storage-root-relocation.js';
+export {
+  LocalSmartDbStorageRootRelocationError,
+  localSmartDbStorageRootRelocationErrorCodes,
+} from './storage-root-relocation.js';
 export type { TSmartDbEffectivePayloadInputV1 } from './resource-fencing.js';
 export { createSmartDbEffectivePayloadSha256V1 } from './resource-fencing.js';

package/ts/ts_smartdb/plugins.ts

@@ -1,8 +1,10 @@
 // node native scope
 import * as buffer from 'node:buffer';
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 
-export { buffer, crypto };
+export { buffer, crypto, fs, path };
 
 // @push.rocks scope
 import * as smartrust from '@push.rocks/smartrust';