@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/local.js

@@ -1,42 +1,147 @@
-"use strict";
 /**
  * LocalLeaseProvider — Layer 1: local durable ledger.
  *
  * Single-device, no network coordination.
  * All WOTS safety guaranteed by the local WotsWatermarkStore + LeaseJournal.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalLeaseProvider = void 0;
-const core_1 = require("@totemsdk/core");
-const core_2 = require("@totemsdk/core");
-const watermark_js_1 = require("./watermark.js");
-const journal_js_1 = require("./journal.js");
-const errors_js_1 = require("./errors.js");
+import { NoopLogger } from '@totemsdk/core';
+import { LeaseStore } from '@totemsdk/core';
+import { WotsWatermarkStore, flatIndex } from './watermark.js';
+import { LeaseJournal } from './journal.js';
+import { LeaseNotFoundError, InvalidLeaseTransitionError, DeviceRangeViolationError, IndicesUnavailableError, } from './errors.js';
 function randomId() {
     if (typeof crypto !== 'undefined' && crypto.randomUUID) {
         return crypto.randomUUID();
     }
     return Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
-class LocalLeaseProvider {
-    constructor(storage, logger = new core_1.NoopLogger(), deviceId = 'local') {
+export class LocalLeaseProvider {
+    constructor(storage, logger = new NoopLogger(), deviceId = 'local') {
         this.logger = logger;
         this._initialized = false;
-        this.watermark = new watermark_js_1.WotsWatermarkStore(storage, logger);
-        this.leaseStore = new core_2.LeaseStore(storage, logger);
-        this.journal = new journal_js_1.LeaseJournal(storage, logger);
+        this.initializePromise = null;
+        this.mutationTail = Promise.resolve();
+        this.watermark = new WotsWatermarkStore(storage, logger);
+        this.leaseStore = new LeaseStore(storage, logger);
+        this.journal = new LeaseJournal(storage, logger);
         this.deviceId = deviceId;
+        this.cas = LocalLeaseProvider.detectCas(storage);
+    }
+    static detectCas(storage) {
+        const candidate = storage;
+        return typeof candidate.conditionalUpdate === 'function' ? candidate : undefined;
     }
     async initialize() {
         if (this._initialized)
             return;
+        if (!this.initializePromise) {
+            this.initializePromise = this.initializeOnce().catch((error) => {
+                this.initializePromise = null;
+                throw error;
+            });
+        }
+        await this.initializePromise;
+    }
+    async initializeOnce() {
+        await this.journal.initialize();
         await this.watermark.initialize();
         await this.leaseStore.initialize();
-        await this.journal.initialize();
+        await this.reconcileDurableSafetyState();
         await this.recoverExpiredReservations();
         await this.burnUnresolvedReservations();
         this._initialized = true;
     }
+    /**
+     * Rebuild the no-reuse watermark from immutable journal history and leases.
+     * The journal is audit authority; the watermark remains allocation authority.
+     */
+    async reconcileDurableSafetyState() {
+        const entries = this.journal.getAll();
+        const latestBySlot = new Map();
+        const latestByReservation = new Map();
+        for (const entry of entries) {
+            latestBySlot.set(`${entry.treeId}:${entry.wotsIndex}`, entry);
+            if (entry.reservationId)
+                latestByReservation.set(entry.reservationId, entry);
+        }
+        for (const entry of latestBySlot.values()) {
+            await this.watermark.markUnavailable(entry.treeId, entry.indices, entry.status);
+        }
+        const leases = this.leaseStore.getAll();
+        const leaseIds = new Set(leases.map((lease) => lease.leaseId));
+        for (const entry of latestByReservation.values()) {
+            if (entry.status !== 'reserved' || leaseIds.has(entry.reservationId))
+                continue;
+            await this.journal.append({
+                ...entry,
+                status: 'burned',
+                timestamp: Date.now(),
+            });
+            await this.watermark.markUnavailable(entry.treeId, entry.indices, 'burned');
+        }
+        for (const lease of leases) {
+            const treeId = lease.treeId ?? 'default';
+            const latest = this.journal.getByReservation(lease.leaseId);
+            if (!latest) {
+                const status = lease.status === 'finalized'
+                    ? 'committed'
+                    : lease.status === 'cancelled'
+                        ? 'burned'
+                        : lease.status === 'expired'
+                            ? 'reserved-expired'
+                            : 'reserved';
+                await this.journal.append({
+                    treeId,
+                    branchId: 'default',
+                    wotsIndex: flatIndex(lease.indices),
+                    indices: lease.indices,
+                    status,
+                    reservationId: lease.leaseId,
+                    ...(lease.txId !== undefined ? { txId: lease.txId } : {}),
+                    timestamp: lease.createdAt,
+                    deviceId: this.deviceId,
+                });
+                await this.watermark.markUnavailable(treeId, lease.indices, status);
+                continue;
+            }
+            if (latest.status === 'committed' && lease.status !== 'finalized') {
+                await this.leaseStore.updateStatus(lease.leaseId, 'finalized');
+            }
+            else if (latest.status === 'burned' && lease.status !== 'cancelled') {
+                await this.leaseStore.updateStatus(lease.leaseId, 'cancelled');
+            }
+            else if (latest.status === 'reserved-expired' && lease.status !== 'expired') {
+                await this.leaseStore.updateStatus(lease.leaseId, 'expired');
+            }
+            else if (latest.status === 'reserved' && lease.status === 'finalized') {
+                await this.journal.append({
+                    treeId,
+                    branchId: 'default',
+                    wotsIndex: flatIndex(lease.indices),
+                    indices: lease.indices,
+                    status: 'committed',
+                    reservationId: lease.leaseId,
+                    ...(lease.txId !== undefined ? { txId: lease.txId } : {}),
+                    timestamp: Date.now(),
+                    deviceId: this.deviceId,
+                });
+                await this.watermark.markUnavailable(treeId, lease.indices, 'committed');
+            }
+            else if (latest.status === 'reserved' && lease.status === 'cancelled') {
+                await this.journal.append({
+                    treeId,
+                    branchId: 'default',
+                    wotsIndex: flatIndex(lease.indices),
+                    indices: lease.indices,
+                    status: 'burned',
+                    reservationId: lease.leaseId,
+                    timestamp: Date.now(),
+                    deviceId: this.deviceId,
+                });
+                await this.watermark.markUnavailable(treeId, lease.indices, 'burned');
+            }
+        }
+    }
     /** Burn all active (non-expired) leases that have no matching treeId.
      *  On restart, leases with missing treeId (from before the treeId field was added)
      *  must be burned to prevent index reuse. */
@@ -45,46 +150,56 @@ class LocalLeaseProvider {
         for (const lease of this.leaseStore.getAll()) {
             if (lease.status === 'active' && lease.expiresAt >= now && !lease.treeId) {
                 this.logger.warn(`[LocalLeaseProvider] Burning unresolved lease ${lease.leaseId} (no treeId)`);
+                if (this.journal.getByReservation(lease.leaseId)?.status !== 'burned') {
+                    await this.journal.append({
+                        treeId: 'default',
+                        branchId: 'default',
+                        wotsIndex: flatIndex(lease.indices),
+                        indices: lease.indices,
+                        status: 'burned',
+                        reservationId: lease.leaseId,
+                        timestamp: now,
+                        deviceId: this.deviceId,
+                    });
+                }
                 await this.watermark.markUnavailable('default', lease.indices, 'burned');
                 await this.leaseStore.updateStatus(lease.leaseId, 'cancelled');
-                await this.journal.append({
-                    treeId: 'default',
-                    branchId: 'default',
-                    wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
-                    indices: lease.indices,
-                    status: 'burned',
-                    reservationId: lease.leaseId,
-                    timestamp: now,
-                    deviceId: this.deviceId,
-                });
             }
         }
     }
     async recoverExpiredReservations() {
         const now = Date.now();
         for (const lease of this.leaseStore.getAll()) {
-            if (lease.status === 'active' && lease.expiresAt < now) {
+            if (lease.status === 'expired' || (lease.status === 'active' && lease.expiresAt < now)) {
                 const treeId = lease.treeId ?? 'default';
+                if (this.journal.getByReservation(lease.leaseId)?.status !== 'reserved-expired') {
+                    await this.journal.append({
+                        treeId,
+                        branchId: 'default',
+                        wotsIndex: flatIndex(lease.indices),
+                        indices: lease.indices,
+                        status: 'reserved-expired',
+                        reservationId: lease.leaseId,
+                        timestamp: now,
+                        deviceId: this.deviceId,
+                    });
+                }
                 await this.watermark.markUnavailable(treeId, lease.indices, 'reserved-expired');
-                await this.leaseStore.updateStatus(lease.leaseId, 'expired');
-                await this.journal.append({
-                    treeId,
-                    branchId: 'default',
-                    wotsIndex: (0, watermark_js_1.flatIndex)(lease.indices),
-                    indices: lease.indices,
-                    status: 'reserved-expired',
-                    reservationId: lease.leaseId,
-                    timestamp: now,
-                    deviceId: this.deviceId,
-                });
+                if (lease.status !== 'expired')
+                    await this.leaseStore.updateStatus(lease.leaseId, 'expired');
             }
         }
     }
     async reserveKeyUse(params) {
-        if (!this._initialized)
-            await this.initialize();
-        const indices = this.watermark.getNextIndices(params.treeId);
-        return this.reserveSpecificKeyUse(params, indices);
+        return this.withMutationLock(async () => {
+            if (!this._initialized)
+                await this.initialize();
+            // Pick up any allocation made by another provider over the same storage
+            // before choosing a slot (AUD-004).
+            await this.watermark.refresh();
+            const indices = this.watermark.getNextIndices(params.treeId);
+            return this.reserveSpecificKeyUseUnlocked(params, indices);
+        });
     }
     /**
      * Reserve a specific set of indices (used by quorum coordination so every
@@ -92,23 +207,63 @@ class LocalLeaseProvider {
      * slot is already taken.
      */
     async reserveSpecificKeyUse(params, indices) {
+        return this.withMutationLock(async () => {
+            if (!this._initialized)
+                await this.initialize();
+            await this.watermark.refresh();
+            return this.reserveSpecificKeyUseUnlocked(params, indices);
+        });
+    }
+    async reserveSpecificKeyUseUnlocked(params, indices) {
         if (!this._initialized)
             await this.initialize();
         const treeId = params.treeId;
         const ttlMs = params.ttlMs ?? 120000;
         if (this.watermark.isUnavailable(treeId, indices)) {
-            throw new errors_js_1.IndicesUnavailableError(treeId, indices);
+            throw new IndicesUnavailableError(treeId, indices);
         }
         // Validate device range BEFORE marking unavailable — prevents permanent index loss
         if (params.deviceId) {
             const range = this.getDeviceRange(params.deviceId);
             if (range && (indices.addressIndex < range.start || indices.addressIndex > range.end)) {
-                throw new errors_js_1.DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
+                throw new DeviceRangeViolationError(indices.addressIndex, range.start, range.end);
             }
         }
-        await this.watermark.markUnavailable(treeId, indices, 'reserved');
         const reservationId = randomId();
         const expiresAt = Date.now() + ttlMs;
+        // Cross-instance CAS claim (AUD-004): on a durable medium shared by two
+        // provider instances over distinct adapter objects, refresh() above can
+        // race and both pick the same slot. Claim it atomically first; a lost race
+        // means another instance owns it, so the slot is not re-allocated.
+        if (this.cas) {
+            const claimKey = `totem_wots_claim:${treeId}:${flatIndex(indices)}`;
+            const claim = await this.cas.conditionalUpdate(claimKey, (current) => current
+                ? { abort: 'slot already claimed' }
+                : {
+                    next: {
+                        reservationId,
+                        ...(params.deviceId !== undefined ? { deviceId: params.deviceId } : {}),
+                        claimedAt: Date.now(),
+                    },
+                });
+            if (!claim.applied) {
+                throw new IndicesUnavailableError(treeId, indices);
+            }
+        }
+        // Write-ahead safety record: once this succeeds, recovery will never
+        // re-expose the index even if a later snapshot write fails.
+        await this.journal.append({
+            treeId,
+            branchId: params.branchId ?? 'default',
+            wotsIndex: flatIndex(indices),
+            indices,
+            status: 'reserved',
+            reservationId,
+            payloadHash: params.payloadHash,
+            timestamp: Date.now(),
+            deviceId: params.deviceId ?? this.deviceId,
+        });
+        await this.watermark.markUnavailable(treeId, indices, 'reserved');
         const lease = {
             leaseId: reservationId,
             leaseToken: reservationId,
@@ -120,35 +275,43 @@ class LocalLeaseProvider {
             leaseTTL: ttlMs,
         };
         await this.leaseStore.save(lease);
-        await this.journal.append({
-            treeId,
-            branchId: params.branchId ?? 'default',
-            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
-            indices,
-            status: 'reserved',
-            reservationId,
-            payloadHash: params.payloadHash,
-            timestamp: Date.now(),
-            deviceId: params.deviceId ?? this.deviceId,
-        });
         return { reservationId, indices, expiresAt };
     }
+    withMutationLock(operation) {
+        const run = this.mutationTail.then(operation, operation);
+        this.mutationTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
     async commitKeyUse(reservationId, txId) {
+        return this.withMutationLock(() => this.commitKeyUseUnlocked(reservationId, txId));
+    }
+    async commitKeyUseUnlocked(reservationId, txId) {
         if (!this._initialized)
             await this.initialize();
+        await this.watermark.refresh();
         const lease = this.leaseStore.get(reservationId);
         if (!lease)
-            throw new errors_js_1.LeaseNotFoundError(reservationId);
-        if (lease.status === 'finalized')
-            return;
+            throw new LeaseNotFoundError(reservationId);
         const treeId = lease.treeId ?? 'default';
         const indices = lease.indices;
-        await this.watermark.markUnavailable(treeId, indices, 'committed');
-        await this.leaseStore.updateStatus(reservationId, 'finalized');
+        const latest = this.journal.getByReservation(reservationId);
+        if (latest?.status === 'committed') {
+            if (latest.txId !== txId) {
+                throw new InvalidLeaseTransitionError(reservationId, 'committed', 'committed');
+            }
+            await this.watermark.markUnavailable(treeId, indices, 'committed');
+            if (lease.status !== 'finalized')
+                await this.leaseStore.updateStatus(reservationId, 'finalized');
+            return;
+        }
+        if (latest?.status === 'burned' || latest?.status === 'reserved-expired'
+            || lease.status === 'cancelled' || lease.status === 'expired') {
+            throw new InvalidLeaseTransitionError(reservationId, latest?.status ?? lease.status, 'committed');
+        }
         await this.journal.append({
             treeId,
             branchId: 'default',
-            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            wotsIndex: flatIndex(indices),
             indices,
             status: 'committed',
             reservationId,
@@ -156,34 +319,71 @@ class LocalLeaseProvider {
             timestamp: Date.now(),
             deviceId: this.deviceId,
         });
+        await this.watermark.markUnavailable(treeId, indices, 'committed');
+        await this.leaseStore.updateStatus(reservationId, 'finalized');
     }
     async burnReservation(reservationId, reason) {
+        return this.withMutationLock(() => this.burnReservationUnlocked(reservationId, reason));
+    }
+    async burnReservationUnlocked(reservationId, reason) {
         if (!this._initialized)
             await this.initialize();
+        await this.watermark.refresh();
         const lease = this.leaseStore.get(reservationId);
         if (!lease)
-            throw new errors_js_1.LeaseNotFoundError(reservationId);
+            throw new LeaseNotFoundError(reservationId);
         const treeId = lease.treeId ?? 'default';
         const indices = lease.indices;
-        await this.watermark.markUnavailable(treeId, indices, 'burned');
-        await this.leaseStore.updateStatus(reservationId, 'cancelled');
-        this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
+        const latest = this.journal.getByReservation(reservationId);
+        if (latest?.status === 'burned') {
+            await this.watermark.markUnavailable(treeId, indices, 'burned');
+            if (lease.status !== 'cancelled')
+                await this.leaseStore.updateStatus(reservationId, 'cancelled');
+            return;
+        }
+        if (latest?.status === 'committed' || latest?.status === 'reserved-expired'
+            || lease.status === 'finalized' || lease.status === 'expired') {
+            throw new InvalidLeaseTransitionError(reservationId, latest?.status ?? lease.status, 'burned');
+        }
         await this.journal.append({
             treeId,
             branchId: 'default',
-            wotsIndex: (0, watermark_js_1.flatIndex)(indices),
+            wotsIndex: flatIndex(indices),
             indices,
             status: 'burned',
             reservationId,
             timestamp: Date.now(),
             deviceId: this.deviceId,
         });
+        await this.watermark.markUnavailable(treeId, indices, 'burned');
+        await this.leaseStore.updateStatus(reservationId, 'cancelled');
+        this.logger.warn(`[LocalLeaseProvider] Burning reservation ${reservationId}: ${reason}`);
     }
     async getLocalWatermark(treeId) {
         if (!this._initialized)
             await this.initialize();
         return this.watermark.getLocalWatermark(treeId);
     }
+    /**
+     * Export a portable watermark seed for restore (RFC-013 §9).
+     */
+    async exportWatermark(treeId) {
+        if (!this._initialized)
+            await this.initialize();
+        return this.watermark.exportSeed(treeId);
+    }
+    /**
+     * Seed the local watermark from an exported/operator/on-chain snapshot.
+     * Forward-only by default; refuses to start below the true high-water mark.
+     */
+    async seedWatermark(seed, options) {
+        return this.withMutationLock(async () => {
+            if (!this._initialized)
+                await this.initialize();
+            await this.watermark.refresh();
+            await this.watermark.seed(seed, options);
+        });
+    }
     /** List all tree IDs known to the local watermark store. */
     listTrees() {
         return Object.keys(this.watermark.getRawState().trees);
@@ -202,8 +402,8 @@ class LocalLeaseProvider {
         if (!this._initialized)
             await this.initialize();
         const local = this.watermark.getLocalWatermark(treeId);
-        const localFlat = (0, watermark_js_1.flatIndex)({ addressIndex: local.addressCursor, l1: local.l1Cursor, l2: local.l2Cursor });
-        const remoteFlat = (0, watermark_js_1.flatIndex)({ addressIndex: remote.addressCursor, l1: remote.l1Cursor, l2: remote.l2Cursor });
+        const localFlat = flatIndex({ addressIndex: local.addressCursor, l1: local.l1Cursor, l2: local.l2Cursor });
+        const remoteFlat = flatIndex({ addressIndex: remote.addressCursor, l1: remote.l1Cursor, l2: remote.l2Cursor });
         if (remoteFlat <= localFlat)
             return false;
         await this.watermark.save(treeId, {
@@ -234,4 +434,3 @@ class LocalLeaseProvider {
         return { start: slot * 8, end: slot * 8 + 7 };
     }
 }
-exports.LocalLeaseProvider = LocalLeaseProvider;

package/dist/onchain.d.ts

@@ -23,7 +23,8 @@
 import type { WotsLeaseProvider, ReserveParams, LeaseReservation, LeaseCertificate, LocalWatermark, SyncResult, OnchainWatermarkProviderConfig } from './types.js';
 export declare class OnchainWatermarkProvider implements WotsLeaseProvider {
     private readonly chain;
-    private readonly watermarkCoinId;
+    private readonly initialWatermarkCoinId;
+    private currentCoinId;
     private readonly watermarkAddress;
     private readonly tokenId;
     private readonly amount;
@@ -31,6 +32,7 @@ export declare class OnchainWatermarkProvider implements WotsLeaseProvider {
     private readonly signer;
     private readonly statePort;
     private readonly minBlocksBetweenPublishes;
+    private readonly storage?;
     private _initialized;
     private _lastPublishBlock;
     constructor(config: OnchainWatermarkProviderConfig);