@push.rocks/smartdb 2.12.2 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdb",
-  "version": "2.12.2",
+  "version": "2.13.0",
   "private": false,
   "description": "A MongoDB-compatible embedded database server with wire protocol support, backed by a high-performance Rust engine.",
   "exports": {
@@ -15,11 +15,11 @@
     "@api.global/typedserver": "^8.4.6",
     "@design.estate/dees-element": "^2.2.4",
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsbundle": "^2.10.4",
-    "@git.zone/tsrun": "^2.0.4",
-    "@git.zone/tsrust": "^1.4.1",
+    "@git.zone/tsbundle": "^2.11.2",
+    "@git.zone/tsrun": "^2.0.5",
+    "@git.zone/tsrust": "^1.6.0",
     "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.1.1",
     "mongodb": "^7.1.1"
   },
   "dependencies": {

package/readme.md

@@ -314,7 +314,53 @@ Authentication verifies SCRAM credentials, denies unauthenticated commands, and
 
 Supported built-in role names are `root`, `read`, `readWrite`, `dbAdmin`, `userAdmin`, `clusterMonitor`, plus `readAnyDatabase`, `readWriteAnyDatabase`, `dbAdminAnyDatabase`, and `userAdminAnyDatabase`. When `usersPath` is set, SmartDB persists SCRAM credential material atomically and does not store plaintext passwords.
 
-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.
+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.
+
+### Durable Database Publication Holds
+
+File-backed SmartDB can keep a replaced or deleted database closed after the local mutation is durable and until a downstream coordinator confirms its own fsync. Check the explicit health contract before using this flow:
+
+```typescript
+const health = await server.getHealth();
+if (
+  health.publicationHoldVersion !== 1 ||
+  !health.publicationHoldSupported ||
+  health.publicationHoldRequiresExternalDrain
+) {
+  throw new Error('SmartDB publication holds are unavailable');
+}
+```
+
+Set `holdPublication: true` on an exact fenced `importDatabase()` or `deleteDatabaseTenant()` operation. The result contains a held `resourceFence` with a one-time `publicationCapability`. Treat that capability as a secret: do not log it or persist it outside protected control-plane state. After downstream state is durable, submit the exact receipt to `commitDatabasePublication()`:
+
+```typescript
+import type { ISmartDbHeldPublicationReceipt } from '@push.rocks/smartdb';
+
+const held = await server.importDatabase({
+  databaseName: 'tenant_a',
+  source: snapshot,
+  username: 'tenant_a_user',
+  fence: {
+    version: 1,
+    scopeId: 'corestore-node-1.tenant-a',
+    token: 42,
+    mutationId: 'restore-42',
+    payloadSha256: controlPlanePayloadSha256,
+  },
+  holdPublication: true,
+});
+
+const receipt = held.resourceFence as ISmartDbHeldPublicationReceipt;
+await persistAndFsyncDownstreamState(receipt);
+const released = await server.commitDatabasePublication({
+  databaseName: 'tenant_a',
+  resourceFence: receipt,
+});
+```
+
+The held barrier survives restart and blocks wire commands, transactions, startup recovery, compaction, index restoration, and close-time hint writes for that database while unrelated databases remain available. Commit is exact and idempotent. A successful commit removes the raw capability from durable state and retains only protected verification material. Provider/root identity, durable fenced-mode markers, and bounded startup validation make copied, missing, corrupt, or legacy-active publication state fail closed. A higher fencing token compacts resolved older receipts, so long-lived coordinators do not exhaust receipt capacity.
 
 Basic user management commands are available for authenticated users with `root` or `userAdmin` privileges:
 
@@ -345,6 +391,10 @@ await client.db('admin').command({ usersInfo: 'reader' });
 | `revertToSeq(seq, dryRun?)` | `Promise<IRevertResult>` | Revert to a specific oplog sequence (must be within retained oplog history) |
 | `getCollections(db?)` | `Promise<ICollectionInfo[]>` | List all collections with counts |
 | `getDocuments(db, coll, limit?, skip?)` | `Promise<IDocumentsResult>` | Browse documents with pagination |
+| `getHealth()` | `Promise<ISmartDbHealth>` | Read readiness and explicit publication-hold capability fields |
+| `importDatabase(params)` | `Promise<ISmartDbImportDatabaseResult>` | Durably replace one database, optionally leaving publication held |
+| `deleteDatabaseTenant(params)` | `Promise<ISmartDbDeleteDatabaseTenantResult>` | Durably delete an exact tenant database/user, optionally leaving publication held |
+| `commitDatabasePublication(params)` | `Promise<TSmartDbCommitDatabasePublicationResult>` | Idempotently release an exact held publication receipt |
 
 ### LocalSmartDb
 

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -25,6 +25,9 @@ export type {
   ISmartDbHealth,
   ISmartDbResourceFence,
   ISmartDbResourceFenceReceipt,
+  ISmartDbHeldPublicationReceipt,
+  ISmartDbCommitDatabasePublicationInput,
+  TSmartDbCommitDatabasePublicationResult,
   TSmartDbResourceFenceErrorCode,
   ISmartDbDatabaseTenantInput,
   ISmartDbEnsureDatabaseTenantInput,

package/ts/ts_smartdb/index.ts

@@ -29,6 +29,9 @@ export type {
   ISmartDbHealth,
   ISmartDbResourceFence,
   ISmartDbResourceFenceReceipt,
+  ISmartDbHeldPublicationReceipt,
+  ISmartDbCommitDatabasePublicationInput,
+  TSmartDbCommitDatabasePublicationResult,
   TSmartDbResourceFenceErrorCode,
   ISmartDbDatabaseTenantInput,
   ISmartDbEnsureDatabaseTenantInput,

package/ts/ts_smartdb/resource-fencing.ts

@@ -9,12 +9,14 @@ export type TSmartDbEffectivePayloadInputV1 =
       source: ISmartDbDatabaseExport;
       /** Exact exclusive tenant owner; omission retains the legacy v1 digest. */
       username?: string;
+      holdPublication?: boolean;
     }
   | {
       version: 1;
       kind: 'smartdb.database.delete.v1';
       databaseName: string;
-      username: string;
+      username?: string;
+      holdPublication?: boolean;
     }
   | {
       version: 1;
@@ -212,6 +214,12 @@ export const createSmartDbEffectivePayloadSha256V1 = (
       ) {
         throw new TypeError('SmartDB exact replace username must be a string');
       }
+      if (
+        inputArg.holdPublication !== undefined &&
+        typeof inputArg.holdPublication !== 'boolean'
+      ) {
+        throw new TypeError('SmartDB holdPublication must be a Boolean');
+      }
       effectivePayload = {
         version: 1,
         kind: inputArg.kind,
@@ -220,8 +228,12 @@ export const createSmartDbEffectivePayloadSha256V1 = (
         ...(inputArg.username === undefined
           ? {}
           : { username: inputArg.username }),
+        ...(inputArg.holdPublication === true
+          ? { holdPublication: true }
+          : {}),
       };
-      useTypedEncoding = inputArg.username !== undefined;
+      useTypedEncoding =
+        inputArg.username !== undefined || inputArg.holdPublication === true;
       break;
     case 'smartdb.database.ensure.v1': {
       if (typeof inputArg.username !== 'string') {
@@ -256,15 +268,28 @@ export const createSmartDbEffectivePayloadSha256V1 = (
       break;
     }
     case 'smartdb.database.delete.v1':
-      if (typeof inputArg.username !== 'string') {
-        throw new TypeError('SmartDB exact delete username must be a string');
+      if (
+        inputArg.username !== undefined &&
+        typeof inputArg.username !== 'string'
+      ) {
+        throw new TypeError('SmartDB exact delete username must be a string when supplied');
+      }
+      if (
+        inputArg.holdPublication !== undefined &&
+        typeof inputArg.holdPublication !== 'boolean'
+      ) {
+        throw new TypeError('SmartDB holdPublication must be a Boolean');
       }
       effectivePayload = {
         version: 1,
         kind: inputArg.kind,
         databaseName: inputArg.databaseName,
-        username: inputArg.username,
-        rawDatabaseOnly: false,
+        ...(inputArg.username === undefined
+          ? { rawDatabaseOnly: true }
+          : { username: inputArg.username, rawDatabaseOnly: false }),
+        ...(inputArg.holdPublication === true
+          ? { holdPublication: true }
+          : {}),
       };
       break;
     default:

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

@@ -15,6 +15,8 @@ import type {
   ISmartDbDatabaseExport,
   ISmartDbImportDatabaseInput,
   ISmartDbImportDatabaseResult,
+  ISmartDbCommitDatabasePublicationInput,
+  TSmartDbCommitDatabasePublicationResult,
 } from './service-types.js';
 
 export type {
@@ -30,6 +32,9 @@ export type {
   ISmartDbDatabaseExport,
   ISmartDbImportDatabaseInput,
   ISmartDbImportDatabaseResult,
+  ISmartDbHeldPublicationReceipt,
+  ISmartDbCommitDatabasePublicationInput,
+  TSmartDbCommitDatabasePublicationResult,
 } from './service-types.js';
 
 /**
@@ -155,6 +160,10 @@ type TSmartDbCommands = {
     params: ISmartDbImportDatabaseInput;
     result: ISmartDbImportDatabaseResult;
   };
+  commitDatabasePublication: {
+    params: ISmartDbCommitDatabasePublicationInput;
+    result: TSmartDbCommitDatabasePublicationResult;
+  };
   getOpLog: {
     params: { sinceSeq?: number; limit?: number; db?: string; collection?: string };
     result: IOpLogResult;
@@ -254,6 +263,14 @@ function buildLocalPaths(): string[] {
 
   return paths;
 }
+export function getRustDbAllocatorEnv(
+  environment: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  return {
+    MIMALLOC_ARENA_EAGER_COMMIT: environment.MIMALLOC_ARENA_EAGER_COMMIT ?? '0',
+    MIMALLOC_ALLOW_LARGE_OS_PAGES: environment.MIMALLOC_ALLOW_LARGE_OS_PAGES ?? '0',
+  };
+}
 
 /**
  * Bridge between TypeScript SmartdbServer and the Rust binary.
@@ -271,6 +288,7 @@ export class RustDbBridge extends EventEmitter {
       platformPackagePrefix: '@push.rocks/smartdb',
       localPaths: buildLocalPaths(),
       maxPayloadSize: 100 * 1024 * 1024, // database exports/imports can be larger than command replies
+      env: getRustDbAllocatorEnv(),
     });
 
     // Forward events from the inner bridge
@@ -383,6 +401,19 @@ export class RustDbBridge extends EventEmitter {
     }
   }
 
+  public async commitDatabasePublication(
+    params: ISmartDbCommitDatabasePublicationInput,
+  ): Promise<TSmartDbCommitDatabasePublicationResult> {
+    try {
+      return await this.bridge.sendCommand(
+        'commitDatabasePublication',
+        params,
+      ) as TSmartDbCommitDatabasePublicationResult;
+    } catch (error) {
+      throw normalizeSmartDbResourceFenceError(error);
+    }
+  }
+
   public async getOpLog(params: {
     sinceSeq?: number;
     limit?: number;

package/ts/ts_smartdb/server/SmartdbServer.ts

@@ -21,6 +21,8 @@ import type {
   ISmartDbDatabaseExport,
   ISmartDbImportDatabaseInput,
   ISmartDbImportDatabaseResult,
+  ISmartDbCommitDatabasePublicationInput,
+  TSmartDbCommitDatabasePublicationResult,
 } from '../service-types.js';
 
 /**
@@ -298,6 +300,13 @@ export class SmartdbServer {
     return this.bridge.importDatabase(params);
   }
 
+  /** Release an exact held database publication after downstream fsync. */
+  async commitDatabasePublication(
+    params: ISmartDbCommitDatabasePublicationInput,
+  ): Promise<TSmartDbCommitDatabasePublicationResult> {
+    return this.bridge.commitDatabasePublication(params);
+  }
+
   /**
    * Get readiness/health details for long-running service use.
    */
@@ -310,6 +319,9 @@ export class SmartdbServer {
         resourceFencingVersion: this.options.storage === 'file' ? 1 : undefined,
         resourceFencingSupported: this.options.storage === 'file' ? false : undefined,
         resourceFencingRequiresDrain: this.options.storage === 'file' ? true : undefined,
+        publicationHoldVersion: 1,
+        publicationHoldSupported: false,
+        publicationHoldRequiresExternalDrain: false,
         authEnabled: Boolean(this.options.auth?.enabled),
         authUsers: this.options.auth?.users?.length ?? 0,
         usersPathConfigured: Boolean(this.options.auth?.usersPath),

package/ts/ts_smartdb/service-types.ts

@@ -5,6 +5,9 @@ export interface ISmartDbHealth {
   resourceFencingVersion?: 1;
   resourceFencingSupported?: boolean;
   resourceFencingRequiresDrain?: true;
+  publicationHoldVersion: 1;
+  publicationHoldSupported: boolean;
+  publicationHoldRequiresExternalDrain: boolean;
   authEnabled?: boolean;
   authUsers?: number;
   usersPathConfigured?: boolean;
@@ -23,6 +26,9 @@ export const smartDbResourceFenceErrorCodes = [
   'EFENCE_STATE_CORRUPT',
   'EFENCE_RECEIPT_LIMIT',
   'EFENCE_BUSY',
+  'EFENCE_PUBLICATION_HELD',
+  'EFENCE_CAPABILITY_MISMATCH',
+  'EFENCE_NOT_HELD',
 ] as const;
 
 export type TSmartDbResourceFenceErrorCode =
@@ -44,6 +50,34 @@ export interface ISmartDbResourceFenceReceipt
     | 'smartdb.database.ensure.v1';
   /** Digest of the canonical payload interpretation derived by SmartDB. */
   effectivePayloadSha256: string;
+  provider?: 'smartdb';
+  resourceIdSha256?: string;
+  holdPublication?: true;
+  publicationState?: 'held' | 'released';
+  bindingSha256?: string;
+  resultSha256?: string;
+  receiptSha256?: string;
+  publicationCapabilitySha256?: string;
+  /** Present only while publication is held; never returned after release. */
+  publicationCapability?: string;
+}
+
+export interface ISmartDbHeldPublicationReceipt
+  extends ISmartDbResourceFenceReceipt {
+  provider: 'smartdb';
+  resourceIdSha256: string;
+  holdPublication: true;
+  publicationState: 'held';
+  bindingSha256: string;
+  resultSha256: string;
+  receiptSha256: string;
+  publicationCapabilitySha256: string;
+  publicationCapability: string;
+}
+
+export interface ISmartDbCommitDatabasePublicationInput {
+  databaseName: string;
+  resourceFence: ISmartDbHeldPublicationReceipt;
 }
 
 export class SmartDbResourceFenceError extends Error {
@@ -107,6 +141,8 @@ export interface ISmartDbDeleteDatabaseTenantInput {
    */
   username?: string;
   fence?: ISmartDbResourceFence;
+  /** Keep the database data plane closed until commitDatabasePublication. */
+  holdPublication?: boolean;
 }
 
 export interface ISmartDbRotateDatabaseTenantPasswordInput {
@@ -168,6 +204,8 @@ export interface ISmartDbImportDatabaseInput {
    */
   username?: string;
   fence?: ISmartDbResourceFence;
+  /** Keep the database data plane closed until commitDatabasePublication. */
+  holdPublication?: boolean;
 }
 
 export interface ISmartDbImportDatabaseResult {
@@ -176,3 +214,7 @@ export interface ISmartDbImportDatabaseResult {
   documents: number;
   resourceFence?: ISmartDbResourceFenceReceipt;
 }
+
+export type TSmartDbCommitDatabasePublicationResult =
+  | ISmartDbImportDatabaseResult
+  | ISmartDbDeleteDatabaseTenantResult;