@push.rocks/smartdb 2.18.1 → 3.0.1

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

@@ -5,6 +5,9 @@ export interface ISmartDbHealth {
     resourceFencingVersion?: 1;
     resourceFencingSupported?: boolean;
     resourceFencingRequiresDrain?: true;
+    allocationFencingVersion?: 1;
+    allocationFencingSupported?: boolean;
+    allocationFencingRequiresDrain?: true;
     publicationHoldVersion: 1;
     publicationHoldSupported: boolean;
     publicationHoldRequiresExternalDrain: boolean;
@@ -39,7 +42,7 @@ export type TLocalSmartDbOfflineStringValueInspectionResult = {
     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 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", "EALLOCATION_EXPECTED_ABSENT_CONFLICT", "EALLOCATION_REQUIRED", "EALLOCATION_MISMATCH", "EALLOCATION_GENERATION_EXHAUSTED", "EALLOCATION_DEPROVISIONED"];
 export type TSmartDbResourceFenceErrorCode = (typeof smartDbResourceFenceErrorCodes)[number];
 export interface ISmartDbResourceFence {
     version: 1;
@@ -49,7 +52,7 @@ export interface ISmartDbResourceFence {
     payloadSha256: string;
 }
 export interface ISmartDbResourceFenceReceipt extends ISmartDbResourceFence {
-    kind: 'smartdb.database.replace.v1' | 'smartdb.database.delete.v1' | 'smartdb.database.ensure.v1';
+    kind: 'smartdb.database.replace.v1' | 'smartdb.database.delete.v1' | 'smartdb.database.ensure.v1' | 'smartdb.database.allocate.v1';
     /** Digest of the canonical payload interpretation derived by SmartDB. */
     effectivePayloadSha256: string;
     provider?: 'smartdb';
@@ -62,6 +65,33 @@ export interface ISmartDbResourceFenceReceipt extends ISmartDbResourceFence {
     publicationCapabilitySha256?: string;
     /** Present only while publication is held; never returned after release. */
     publicationCapability?: string;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
+}
+export interface ISmartDbDatabaseAllocationIdentity {
+    version: 1;
+    provider: 'smartdb';
+    state: 'active';
+    databaseName: string;
+    username: string;
+    allocationId: string;
+    generation: number;
+    principalId: string;
+    resourceIdSha256: string;
+    bindingSha256: string;
+    receiptSha256: string;
+}
+export interface ISmartDbDatabaseAllocationLifecycle {
+    version: 1;
+    provider: 'smartdb';
+    state: 'allocating' | 'active' | 'deprovisioning' | 'deprovisioned';
+    databaseName: string;
+    username: string;
+    allocationId: string;
+    generation: number;
+    principalId: string;
+    resourceIdSha256: string;
+    bindingSha256: string;
+    receiptSha256: string;
 }
 export interface ISmartDbHeldPublicationReceipt extends ISmartDbResourceFenceReceipt {
     provider: 'smartdb';
@@ -94,6 +124,7 @@ export interface ISmartDbDatabaseResourceFenceState {
     scopeId: string;
     highestToken: number;
     publicationState: 'requested' | 'publishing' | 'held' | 'released';
+    allocation?: ISmartDbDatabaseAllocationLifecycle;
 }
 export declare class SmartDbResourceFenceError extends Error {
     readonly code: TSmartDbResourceFenceErrorCode;
@@ -108,6 +139,11 @@ export interface ISmartDbDatabaseTenantInput {
 }
 export interface ISmartDbEnsureDatabaseTenantInput extends ISmartDbDatabaseTenantInput {
     fence: ISmartDbResourceFence;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
+}
+export interface ISmartDbAllocateDatabaseTenantInput extends ISmartDbDatabaseTenantInput {
+    expectedAbsent: true;
+    fence: ISmartDbResourceFence;
 }
 export interface ISmartDbDeleteDatabaseTenantInput {
     databaseName: string;
@@ -121,6 +157,7 @@ export interface ISmartDbDeleteDatabaseTenantInput {
      */
     username?: string;
     fence?: ISmartDbResourceFence;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
     /** Keep the database data plane closed until commitDatabasePublication. */
     holdPublication?: boolean;
 }
@@ -135,10 +172,15 @@ export interface ISmartDbDatabaseTenantDescriptor {
     authSource: string;
     mongodbUri?: string;
     resourceFence?: ISmartDbResourceFenceReceipt;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
 }
 export interface ISmartDbEnsureDatabaseTenantResult extends ISmartDbDatabaseTenantDescriptor {
     resourceFence: ISmartDbResourceFenceReceipt;
 }
+export interface ISmartDbAllocateDatabaseTenantResult extends ISmartDbDatabaseTenantDescriptor {
+    resourceFence: ISmartDbResourceFenceReceipt;
+    allocation: ISmartDbDatabaseAllocationIdentity;
+}
 export interface ISmartDbDeleteDatabaseTenantResult {
     databaseName: string;
     /**
@@ -154,6 +196,7 @@ export interface ISmartDbDeleteDatabaseTenantResult {
      */
     usersPreserved?: boolean;
     resourceFence?: ISmartDbResourceFenceReceipt;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
 }
 export interface ISmartDbDatabaseExportCollection {
     name: string;
@@ -206,6 +249,7 @@ export interface ISmartDbImportDatabaseInput {
      */
     username?: string;
     fence?: ISmartDbResourceFence;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
     /** Keep the database data plane closed until commitDatabasePublication. */
     holdPublication?: boolean;
 }
@@ -214,5 +258,6 @@ export interface ISmartDbImportDatabaseResult {
     collections: number;
     documents: number;
     resourceFence?: ISmartDbResourceFenceReceipt;
+    allocation?: ISmartDbDatabaseAllocationIdentity;
 }
 export type TSmartDbCommitDatabasePublicationResult = ISmartDbImportDatabaseResult | ISmartDbDeleteDatabaseTenantResult;

package/dist_ts/ts_smartdb/service-types.js

@@ -11,6 +11,11 @@ export const smartDbResourceFenceErrorCodes = [
     'EFENCE_PUBLICATION_HELD',
     'EFENCE_CAPABILITY_MISMATCH',
     'EFENCE_NOT_HELD',
+    'EALLOCATION_EXPECTED_ABSENT_CONFLICT',
+    'EALLOCATION_REQUIRED',
+    'EALLOCATION_MISMATCH',
+    'EALLOCATION_GENERATION_EXHAUSTED',
+    'EALLOCATION_DEPROVISIONED',
 ];
 export class SmartDbResourceFenceError extends Error {
     constructor(codeArg, messageArg, causeArg) {
@@ -23,11 +28,11 @@ export const normalizeSmartDbResourceFenceError = (errorArg) => {
     const error = errorArg instanceof Error
         ? errorArg
         : new Error(String(errorArg));
-    const match = /^(EFENCE_[A-Z_]+):\s*(.*)$/s.exec(error.message);
+    const match = /^((?:EFENCE|EALLOCATION)_[A-Z_]+):\s*(.*)$/s.exec(error.message);
     if (!match ||
         !smartDbResourceFenceErrorCodes.includes(match[1])) {
         return error;
     }
     return new SmartDbResourceFenceError(match[1], match[2], error);
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS10eXBlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3RzX3NtYXJ0ZGIvc2VydmljZS10eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUEwQ0EsTUFBTSxDQUFDLE1BQU0sOEJBQThCLEdBQUc7SUFDNUMsaUJBQWlCO0lBQ2pCLGNBQWM7SUFDZCx1QkFBdUI7SUFDdkIsb0JBQW9CO0lBQ3BCLDBCQUEwQjtJQUMxQiwyQkFBMkI7SUFDM0Isc0JBQXNCO0lBQ3RCLHNCQUFzQjtJQUN0QixhQUFhO0lBQ2IseUJBQXlCO0lBQ3pCLDRCQUE0QjtJQUM1QixpQkFBaUI7Q0FDVCxDQUFDO0FBc0VYLE1BQU0sT0FBTyx5QkFBMEIsU0FBUSxLQUFLO0lBR2xELFlBQ0UsT0FBdUMsRUFDdkMsVUFBa0IsRUFDbEIsUUFBa0I7UUFFbEIsS0FBSyxDQUFDLEdBQUcsT0FBTyxLQUFLLFVBQVUsRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxDQUFDLENBQUM7UUFDeEQsSUFBSSxDQUFDLElBQUksR0FBRywyQkFBMkIsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLENBQUMsTUFBTSxrQ0FBa0MsR0FBRyxDQUNoRCxRQUFpQixFQUNWLEVBQUU7SUFDVCxNQUFNLEtBQUssR0FDVCxRQUFRLFlBQVksS0FBSztRQUN2QixDQUFDLENBQUMsUUFBUTtRQUNWLENBQUMsQ0FBQyxJQUFJLEtBQUssQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQztJQUNsQyxNQUFNLEtBQUssR0FBRyw2QkFBNkIsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0lBQ2hFLElBQ0UsQ0FBQyxLQUFLO1FBQ04sQ0FBQyw4QkFBOEIsQ0FBQyxRQUFRLENBQ3RDLEtBQUssQ0FBQyxDQUFDLENBQW1DLENBQzNDLEVBQ0QsQ0FBQztRQUNELE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUNELE9BQU8sSUFBSSx5QkFBeUIsQ0FDbEMsS0FBSyxDQUFDLENBQUMsQ0FBbUMsRUFDMUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxFQUNSLEtBQUssQ0FDTixDQUFDO0FBQ0osQ0FBQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS10eXBlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3RzX3NtYXJ0ZGIvc2VydmljZS10eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUE2Q0EsTUFBTSxDQUFDLE1BQU0sOEJBQThCLEdBQUc7SUFDNUMsaUJBQWlCO0lBQ2pCLGNBQWM7SUFDZCx1QkFBdUI7SUFDdkIsb0JBQW9CO0lBQ3BCLDBCQUEwQjtJQUMxQiwyQkFBMkI7SUFDM0Isc0JBQXNCO0lBQ3RCLHNCQUFzQjtJQUN0QixhQUFhO0lBQ2IseUJBQXlCO0lBQ3pCLDRCQUE0QjtJQUM1QixpQkFBaUI7SUFDakIsc0NBQXNDO0lBQ3RDLHNCQUFzQjtJQUN0QixzQkFBc0I7SUFDdEIsa0NBQWtDO0lBQ2xDLDJCQUEyQjtDQUNuQixDQUFDO0FBcUdYLE1BQU0sT0FBTyx5QkFBMEIsU0FBUSxLQUFLO0lBR2xELFlBQ0UsT0FBdUMsRUFDdkMsVUFBa0IsRUFDbEIsUUFBa0I7UUFFbEIsS0FBSyxDQUFDLEdBQUcsT0FBTyxLQUFLLFVBQVUsRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxDQUFDLENBQUM7UUFDeEQsSUFBSSxDQUFDLElBQUksR0FBRywyQkFBMkIsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLE9BQU8sQ0FBQztJQUN0QixDQUFDO0NBQ0Y7QUFFRCxNQUFNLENBQUMsTUFBTSxrQ0FBa0MsR0FBRyxDQUNoRCxRQUFpQixFQUNWLEVBQUU7SUFDVCxNQUFNLEtBQUssR0FDVCxRQUFRLFlBQVksS0FBSztRQUN2QixDQUFDLENBQUMsUUFBUTtRQUNWLENBQUMsQ0FBQyxJQUFJLEtBQUssQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQztJQUNsQyxNQUFNLEtBQUssR0FBRyw2Q0FBNkMsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0lBQ2hGLElBQ0UsQ0FBQyxLQUFLO1FBQ04sQ0FBQyw4QkFBOEIsQ0FBQyxRQUFRLENBQ3RDLEtBQUssQ0FBQyxDQUFDLENBQW1DLENBQzNDLEVBQ0QsQ0FBQztRQUNELE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUNELE9BQU8sSUFBSSx5QkFBeUIsQ0FDbEMsS0FBSyxDQUFDLENBQUMsQ0FBbUMsRUFDMUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxFQUNSLEtBQUssQ0FDTixDQUFDO0FBQ0osQ0FBQyxDQUFDIn0=

package/package.json

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

package/readme.md

@@ -272,7 +272,11 @@ const server = new SmartdbServer({
   storage: 'memory',        // 'memory' or 'file' (default: 'memory')
   storagePath: './data',     // Required when storage is 'file'
 });
-await server.start();
+const startupController = new AbortController();
+await server.start({
+  signal: startupController.signal,
+  timeoutMs: 30_000,
+});
 console.log(server.port); // Actual bound port while running
 console.log(server.getConnectionUri()); // mongodb://127.0.0.1:<actual-port>
 
@@ -346,6 +350,8 @@ Supported built-in role names are `root`, `read`, `readWrite`, `dbAdmin`, `userA
 
 On Linux, startup performs one narrow compatibility migration before the Rust engine opens `usersPath`: an effective-user-owned, single-link regular file with the exact legacy mode `0644` is changed to `0600`. Current `0600` files are left unchanged. Symlinks, hard links, unexpected modes or ownership, unsafe parent directories, cross-device targets, and identity changes remain fail-closed errors.
 
+Legacy v0 JSON collections are converted into hidden sibling staging directories. SmartDB fsyncs every generated file and the staging directory before atomically publishing a complete v1 collection, while the v0 files remain unchanged. Cancellation removes unpublished staging and preserves the v0 input. Startup fails closed if it finds staging left by an unclean process exit or an incomplete published target, so neither state is mistaken for a complete migration.
+
 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.
@@ -394,13 +400,21 @@ const released = await server.commitDatabasePublication({
 
 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.
 
-Coordinators that do not yet have their own durable record can call `getDatabaseResourceFenceState({ databaseName })` before creating it. File-backed SmartDB returns the durable scope, highest token, and current publication phase, or `null` only when both fence state and its durable marker are absent. The inspection never returns mutation IDs, receipts, payload digests, binding digests, or publication capabilities. Treat any active phase, identity mismatch, corrupt state, unsupported storage, or unsafe token as a hard stop rather than creating coordinator state.
+Coordinators that do not yet have their own durable record can call `getDatabaseResourceFenceState({ databaseName })` before creating it. File-backed SmartDB returns the durable scope, highest token, current publication phase, and allocation lifecycle/identity when the name is allocation-managed, or `null` only when both fence state and its durable marker are absent. The inspection never returns mutation IDs, mutation payload digests, publication receipts, or publication capabilities. Treat any active phase, identity mismatch, corrupt state, unsupported storage, or unsafe token as a hard stop rather than creating coordinator state.
+
+### Authoritative Database Allocation
+
+`allocateDatabaseTenant()` is the create-only control-plane API for permanently allocation-managed database names. It is available only when `allocationFencingVersion === 1`, `allocationFencingSupported === true`, and `allocationFencingRequiresDrain === true`. The request requires literal `expectedAbsent: true`, an `ISmartDbResourceFence`, and the tenant database, username, and password. `roles` is optional and defaults to `['readWrite', 'dbAdmin']`. SmartDB proves database-root and auth-principal absence while holding the database resource lock, maintenance write gate, and a bounded cross-process reservation on the durable auth store, then returns an `ISmartDbAllocateDatabaseTenantResult`; its `.allocation` field is the durable `ISmartDbDatabaseAllocationIdentity`. Exact fence replay returns the same allocation ID, generation, principal ID, and receipt digests.
+
+Pass the returned `allocation` identity to every later `ensureDatabaseTenant()`, `importDatabase()`, and `deleteDatabaseTenant()` request for that name. Managed import and delete requests also require the exact allocation `username`; the identity alone is insufficient. Each distinct managed mutation requires a strictly newer fence token; the current token is accepted only for exact receipt replay or continuation, and older receipts become explicitly stale after advancement. Held publication receipts carry the allocation into `commitDatabasePublication()`. Managed requests without it and unmanaged requests with it fail closed. Deprovision persists `deprovisioning`, durably deletes the exact marked root, atomically removes only the exact principal, then persists a permanent `deprovisioned` tombstone. A later allocation requires a newer fence token, increments generation, and receives a fresh allocation and principal identity. Wire data access is available only while active and only to the current allocation principal; database/user ownership-changing wire commands are rejected.
+
+The provider marker `.__rustdb_allocation.json` is created and preserved by SmartDB, never accepted from an import payload, and never included in logical exports. The resource lock uses the distinct `smartdb-resource-allocation-managed-v1` marker. Pre-allocation binaries, including 2.18.1, interpret that lock marker as invalid and fail closed. Consequently, N-1 rollback of a storage root after allocation fencing has touched a name is intentionally unavailable; restore the allocation-aware binary rather than removing or editing provider metadata.
 
 `exportDatabase()` drains live MongoDB wire commands for the selected database and holds an exclusive local and cross-process database lease while producing the snapshot. The export is therefore consistent across all collections. It enforces server ceilings while visiting documents instead of first materializing an unbounded database; callers can request lower `maxEncodedBytes`, `maxCollections`, `maxDocuments`, and `maxIndexes` limits. The result emits canonical MongoDB Extended JSON so every BSON type, including 64-bit integers, survives the JSON management channel exactly. `importDatabase()` accepts canonical or relaxed Extended JSON. Database migration clients should preserve the exported objects as JSON values and must not coerce Extended JSON numeric wrappers into JavaScript numbers.
 
 `getDatabaseContentDigest()` computes a bounded, database-name-independent SHA-256 over collection names, exact BSON document bytes, and persisted index specifications. Collection, document, and index enumeration order is normalized; BSON field order and compound-index key order remain significant. `ISmartDbGetDatabaseContentDigestInput` accepts `databaseName` and optional `ISmartDbDatabaseContentDigestLimits` fields `maxScannedBsonBytes`, `maxCollections`, `maxDocuments`, and `maxIndexes`. Callers may lower the server ceilings of 96 MiB scanned BSON, 10,000 collections, 1,000,000 documents, and 100,000 indexes. The `ISmartDbDatabaseContentDigest` result reports format `smartdb.database.content-digest.v1`, algorithm `sha256`, the lowercase digest, and exact scan counters.
 
-The lifecycle-critical health and fence-state inspections, digest, export, import, publication-commit, tenant-ensure, and tenant-delete methods accept optional `ISmartDbManagementOperationOptions` with `signal?: AbortSignal` and `timeoutMs?: number`. `timeoutMs`, when provided, must be a positive safe integer. Cancellation and deadlines are fail-stop: SmartDB attempts to terminate the Rust engine before rejecting. Once termination is confirmed, the operation cannot continue after the caller releases ownership. If termination itself fails, the rejection is a `SmartDbManagementOperationTerminationError`; bridge ownership is retained and the service owner must retry `stop()` until it succeeds. After any cancellation or deadline, restart SmartDB before accepting more traffic.
+`SmartdbServer.start()` and the lifecycle-critical health, fence-state, digest, export, import, publication-commit, tenant-allocation, tenant-ensure, and tenant-delete methods accept optional `ISmartDbManagementOperationOptions` with `signal?: AbortSignal` and `timeoutMs?: number`. `timeoutMs`, when provided, must be a positive safe integer no greater than `2,147,483,647`. Startup applies both cancellation and one deadline across legacy storage migration, sidecar spawn, auth metadata migration, and database readiness. Cancellation and deadlines are fail-stop once the sidecar is owned: SmartDB attempts to terminate the Rust engine before rejecting. Once termination is confirmed, the operation cannot continue after the caller releases ownership. If termination itself fails, the rejection retains bridge ownership and the service owner must retry `stop()` until it succeeds. After cancellation or deadline termination, restart SmartDB before accepting more traffic.
 
 ```typescript
 const controller = new AbortController();
@@ -426,7 +440,7 @@ await client.db('admin').command({ usersInfo: 'reader' });
 
 | Method / Property | Type | Description |
 |---|---|---|
-| `start()` | `Promise<void>` | Start the server (spawns Rust binary) |
+| `start(options?)` | `Promise<void>` | Start under one optional cancellation/deadline budget; join partial sidecars before rejection or retain ownership for `stop()` retry if termination fails |
 | `stop()` | `Promise<void>` | Wait for active startup work, then stop the server and confirm Rust bridge cleanup, including partial startup cleanup |
 | `getConnectionUri()` | `string` | Get the active `mongodb://` URI; before start and after stop, port `0` remains unresolved |
 | `running` | `boolean` | Whether the server is currently running |
@@ -440,6 +454,7 @@ await client.db('admin').command({ usersInfo: 'reader' });
 | `getCollections(db?)` | `Promise<ICollectionInfo[]>` | List all collections with counts |
 | `getDocuments(db, coll, limit?, skip?)` | `Promise<IDocumentsResult>` | Browse documents with pagination |
 | `getHealth(options?)` | `Promise<ISmartDbHealth>` | Read readiness and explicit publication-hold capability fields with optional fail-stop cancellation/deadline ownership |
+| `allocateDatabaseTenant(params, options?)` | `Promise<ISmartDbAllocateDatabaseTenantResult>` | Authoritatively allocate an absent file-backed tenant and return its durable allocation identity; supports fail-stop cancellation and deadlines |
 | `ensureDatabaseTenant(params, options?)` | `Promise<ISmartDbEnsureDatabaseTenantResult>` | Idempotently ensure an exact fenced tenant; supports fail-stop cancellation and deadlines |
 | `getDatabaseResourceFenceState(params, options?)` | `Promise<ISmartDbDatabaseResourceFenceState \| null>` | Safely inspect a file-backed database fence high-water mark and publication phase without exposing receipts or capability material; supports fail-stop cancellation and deadlines |
 | `getDatabaseContentDigest(params, options?)` | `Promise<ISmartDbDatabaseContentDigest>` | Compute a bounded, database-name-independent digest over exact BSON documents and persisted index specifications; supports fail-stop cancellation and deadlines |

package/readme.plan.md

@@ -77,6 +77,8 @@ Provable property: "PSS is a function of live data, not of history."
 - **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)

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -40,11 +40,15 @@ export type {
   ISmartDbCommitDatabasePublicationInput,
   ISmartDbManagementOperationOptions,
   ISmartDbDatabaseResourceFenceState,
+  ISmartDbDatabaseAllocationIdentity,
+  ISmartDbDatabaseAllocationLifecycle,
   TSmartDbCommitDatabasePublicationResult,
   TSmartDbResourceFenceErrorCode,
   ISmartDbDatabaseTenantInput,
   ISmartDbEnsureDatabaseTenantInput,
   ISmartDbEnsureDatabaseTenantResult,
+  ISmartDbAllocateDatabaseTenantInput,
+  ISmartDbAllocateDatabaseTenantResult,
   ISmartDbDeleteDatabaseTenantInput,
   ISmartDbRotateDatabaseTenantPasswordInput,
   ISmartDbDatabaseTenantDescriptor,

package/ts/ts_migration/classes.authmetadatamigrationrunner.ts

@@ -3,6 +3,7 @@ import {
   type IAuthMetadataPermissionMigrationBridge,
   type TAuthMetadataPermissionMigrationStatus,
 } from './migrators/v1_auth_metadata_permissions.js';
+import type { ISmartDbManagementOperationOptions } from '../ts_smartdb/service-types.js';
 
 const authMetadataMigrations = [migrateV1AuthMetadataPermissions] as const;
 
@@ -15,11 +16,12 @@ export class AuthMetadataMigrationRunner {
 
   public async run(
     bridgeArg: IAuthMetadataPermissionMigrationBridge,
+    optionsArg?: ISmartDbManagementOperationOptions,
   ): Promise<TAuthMetadataMigrationRunnerStatus> {
     if (process.platform !== 'linux') return 'not-applicable';
     let status: TAuthMetadataPermissionMigrationStatus = 'not-present';
     for (const migration of authMetadataMigrations) {
-      status = await migration(bridgeArg, this.usersPath);
+      status = await migration(bridgeArg, this.usersPath, optionsArg);
     }
     return status;
   }

package/ts/ts_migration/classes.storagemigrator.ts

@@ -1,5 +1,5 @@
-import * as fs from 'fs';
-import * as path from 'path';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { migrateV0ToV1 } from './migrators/v0_to_v1.js';
 
 /**
@@ -28,12 +28,14 @@ export class StorageMigrator {
   /**
    * Run any needed migrations. Safe to call even if storage is already current.
    */
-  async run(): Promise<void> {
-    if (!fs.existsSync(this.storagePath)) {
+  async run(signalArg?: AbortSignal): Promise<void> {
+    signalArg?.throwIfAborted();
+    if (!await this.pathExists(this.storagePath)) {
       return; // No data yet — nothing to migrate
     }
 
-    const version = this.detectVersion();
+    const version = await this.detectVersion(signalArg);
+    signalArg?.throwIfAborted();
 
     if (version === 1) {
       return; // Already current
@@ -43,7 +45,8 @@ export class StorageMigrator {
       console.log(`[smartdb] Detected v0 (JSON) storage format at ${this.storagePath}`);
       console.log(`[smartdb] Running migration v0 → v1 (Bitcask binary format)...`);
 
-      const deletableFiles = await migrateV0ToV1(this.storagePath);
+      const deletableFiles = await migrateV0ToV1(this.storagePath, signalArg);
+      signalArg?.throwIfAborted();
 
       if (deletableFiles.length > 0) {
         console.log(`[smartdb] Migration v0 → v1 complete.`);
@@ -63,33 +66,49 @@ export class StorageMigrator {
    * v0: {db}/{coll}.json files exist
    * v1: {db}/{coll}/data.rdb directories exist
    */
-  private detectVersion(): TStorageVersion {
-    const entries = fs.readdirSync(this.storagePath, { withFileTypes: true });
+  private async detectVersion(signalArg?: AbortSignal): Promise<TStorageVersion> {
+    signalArg?.throwIfAborted();
+    const entries = await fs.readdir(this.storagePath, { withFileTypes: true });
+    let hasLegacyCollections = false;
 
     for (const entry of entries) {
+      signalArg?.throwIfAborted();
       if (!entry.isDirectory()) continue;
       if (entry.name.startsWith('.__rustdb_')) continue;
 
       const dbDir = path.join(this.storagePath, entry.name);
-      const dbEntries = fs.readdirSync(dbDir, { withFileTypes: true });
+      const dbEntries = await fs.readdir(dbDir, { withFileTypes: true });
 
       for (const dbEntry of dbEntries) {
-        if (dbEntry.name.startsWith('.__rustdb_')) continue;
-        // v1: subdirectory with data.rdb
-        if (dbEntry.isDirectory()) {
-          const dataRdb = path.join(dbDir, dbEntry.name, 'data.rdb');
-          if (fs.existsSync(dataRdb)) {
-            return 1;
-          }
+        signalArg?.throwIfAborted();
+        if (
+          dbEntry.isDirectory()
+          && dbEntry.name.startsWith('.__rustdb_migration_')
+        ) {
+          throw new Error(
+            `SmartDB legacy migration staging is orphaned: ${path.join(dbDir, dbEntry.name)}`,
+          );
         }
+        if (dbEntry.name.startsWith('.__rustdb_')) continue;
         // v0: .json file (not .indexes.json)
         if (dbEntry.isFile() && dbEntry.name.endsWith('.json') && !dbEntry.name.endsWith('.indexes.json')) {
-          return 0;
+          hasLegacyCollections = true;
         }
       }
     }
 
-    // Empty or unrecognized — treat as v1 (fresh start)
-    return 1;
+    // A mixed layout is an interrupted/resumable migration, not proof that the
+    // complete storage root is already current.
+    return hasLegacyCollections ? 0 : 1;
+  }
+
+  private async pathExists(pathArg: string): Promise<boolean> {
+    try {
+      await fs.stat(pathArg);
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+      throw error;
+    }
   }
 }

package/ts/ts_migration/index.ts

@@ -1,4 +1,5 @@
 export { StorageMigrator } from './classes.storagemigrator.js';
+export { SmartDbStorageMigrationCleanupError } from './migrators/v0_to_v1.js';
 export {
   AuthMetadataMigrationRunner,
   type IAuthMetadataPermissionMigrationBridge,