@totemsdk/wots-lease 1.0.0 → 1.0.2

package/dist/cjs/hybrid.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * HybridLeaseProvider — recommended production default.
+ *
+ * Always uses local first, then gates on node cert and/or quorum attestation
+ * for transactions above a configurable value threshold.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HybridLeaseProvider = void 0;
+const certificate_js_1 = require("./certificate.js");
+class HybridLeaseProvider {
+    constructor(config) {
+        this.local = config.local;
+        this.node = config.node;
+        this.quorum = config.quorum;
+        this.onchain = config.onchain;
+        this.threshold = config.threshold ?? Infinity;
+        this.certificateSigner = config.certificateSigner;
+    }
+    isHighValue(params) {
+        if (!params.valueHint)
+            return false;
+        const val = parseFloat(params.valueHint);
+        return !isNaN(val) && val >= this.threshold;
+    }
+    async reserveKeyUse(params) {
+        // Cross-instance/restore safety (RFC-013 §8/§9): before a high-value
+        // reservation, anchor the local cursor to the on-chain watermark so a second
+        // instance of the same seed cannot be handed a leaf we already used.
+        if (this.isHighValue(params) && this.onchain) {
+            try {
+                await this.onchain.syncLeaseJournal();
+            }
+            catch {
+                // Chain unreachable — local monotonic watermark still guards reuse.
+            }
+        }
+        const reservation = await this.local.reserveKeyUse(params);
+        if (this.isHighValue(params)) {
+            // Layer 4 — quorum attestation over the SAME local slot.
+            if (this.quorum) {
+                try {
+                    const attestations = await this.quorum.attestKeyUse(params, reservation.indices);
+                    const certificate = {
+                        reservationId: reservation.reservationId,
+                        treeId: params.treeId,
+                        branchId: params.branchId,
+                        deviceId: params.deviceId,
+                        indices: reservation.indices,
+                        purpose: params.purpose,
+                        payloadHash: params.payloadHash,
+                        issuedBy: this.certificateSigner?.name ?? 'p2p-quorum',
+                        issuedAt: Date.now(),
+                        expiresAt: reservation.expiresAt,
+                        signature: '',
+                        attestations,
+                    };
+                    certificate.signature = this.certificateSigner
+                        ? await (0, certificate_js_1.signCertificate)(this.certificateSigner, certificate)
+                        : '';
+                    return { ...reservation, certificate };
+                }
+                catch {
+                    // Quorum unavailable — fall through to node / local only.
+                }
+            }
+            // Layer 3 — personal lookup node certificate.
+            if (this.node) {
+                try {
+                    const nodeReservation = await this.node.reserveKeyUse(params);
+                    return { ...reservation, certificate: nodeReservation.certificate };
+                }
+                catch {
+                    // Node unavailable — continue with local only
+                }
+            }
+        }
+        return reservation;
+    }
+    commitKeyUse(reservationId, txId) {
+        return this.local.commitKeyUse(reservationId, txId);
+    }
+    burnReservation(reservationId, reason) {
+        return this.local.burnReservation(reservationId, reason);
+    }
+    getLocalWatermark(treeId) {
+        return this.local.getLocalWatermark(treeId);
+    }
+    async publishWatermark(treeId) {
+        // Anchor to the chain first (authoritative cross-instance cursor), then the
+        // personal node, then the local no-op.
+        if (this.onchain) {
+            try {
+                await this.onchain.publishWatermark(treeId);
+                return;
+            }
+            catch {
+                // fall through
+            }
+        }
+        if (this.node) {
+            try {
+                await this.node.publishWatermark(treeId);
+                return;
+            }
+            catch {
+                // fall through
+            }
+        }
+        await this.local.publishWatermark(treeId);
+    }
+    async syncLeaseJournal() {
+        // Read the authoritative on-chain cursor first so a restore/second instance
+        // advances past every leaf published by anyone holding this seed.
+        if (this.onchain) {
+            try {
+                return await this.onchain.syncLeaseJournal();
+            }
+            catch {
+                // fall through
+            }
+        }
+        if (this.node) {
+            try {
+                return await this.node.syncLeaseJournal();
+            }
+            catch {
+                // fall through
+            }
+        }
+        return this.local.syncLeaseJournal();
+    }
+    async verifyLeaseCertificate(cert) {
+        if (!cert)
+            return this.local.verifyLeaseCertificate(cert);
+        // Locally-assembled quorum certificates authenticate against our issuer.
+        if (cert.issuedBy === (this.certificateSigner?.name ?? 'p2p-quorum')) {
+            return (0, certificate_js_1.certificateSignatureVerified)(cert, this.certificateSigner);
+        }
+        if (this.node)
+            return this.node.verifyLeaseCertificate(cert);
+        return false;
+    }
+}
+exports.HybridLeaseProvider = HybridLeaseProvider;

package/dist/cjs/index.d.ts

@@ -0,0 +1,17 @@
+export type { UnavailableReason, SigningIndices, LeaseStatus, TreeWatermark, WotsWatermarkState, LeaseCertificate, LeaseReservation, ReserveParams, LocalWatermark, WatermarkSeed, SeedWatermarkOptions, ConflictRecord, SyncResult, WotsLeaseProvider, JournalEntry, DeviceKeyRange, PersonalLeaseNodeConfig, QuorumAttestation, QuorumPeer, CertificateSigner, P2PQuorumLeaseProviderConfig, OnchainWatermarkProviderConfig, } from './types.js';
+export { WotsWatermarkStore, flatIndex, fromFlatIndex, } from './watermark.js';
+export { LeaseJournal } from './journal.js';
+export { LocalLeaseProvider } from './local.js';
+export { seedLeaseWatermark, exportLeaseWatermark } from './seed.js';
+export type { SeedLeaseWatermarkParams } from './seed.js';
+export { AxiaLeaseProvider } from './axia.js';
+export type { AxiaLeaseProviderConfig } from './axia.js';
+export { HybridLeaseProvider } from './hybrid.js';
+export type { HybridLeaseProviderConfig } from './hybrid.js';
+export { PersonalLeaseNodeProvider, P2PQuorumLeaseProvider, OnchainWatermarkProvider, } from './stubs.js';
+export { P2PQuorumLeaseProvider as QuorumLeaseProvider } from './quorum.js';
+export { OnchainWatermarkProvider as ChainWatermarkProvider } from './onchain.js';
+export { allocateDeviceRange, deviceSlotForAddressIndex } from './device.js';
+export { WatermarkMonotonicityError, WatermarkExhaustedError, WatermarkSeedRegressionError, WatermarkSeedRequiredError, LeaseNotFoundError, IndicesUnavailableError, PersonalLeaseNodeNotConfiguredError, P2PQuorumNotImplementedError, OnchainWatermarkNotImplementedError, QuorumUnavailableError, QuorumConflictError, OnchainWatermarkError, DeviceRangeViolationError, } from './errors.js';
+export { ReplicatedLeaseJournalBackup } from './replicated-backup.js';
+export type { LeaseJournalRestoreTarget } from './replicated-backup.js';

package/dist/cjs/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplicatedLeaseJournalBackup = exports.DeviceRangeViolationError = exports.OnchainWatermarkError = exports.QuorumConflictError = exports.QuorumUnavailableError = exports.OnchainWatermarkNotImplementedError = exports.P2PQuorumNotImplementedError = exports.PersonalLeaseNodeNotConfiguredError = exports.IndicesUnavailableError = exports.LeaseNotFoundError = exports.WatermarkSeedRequiredError = exports.WatermarkSeedRegressionError = exports.WatermarkExhaustedError = exports.WatermarkMonotonicityError = exports.deviceSlotForAddressIndex = exports.allocateDeviceRange = exports.ChainWatermarkProvider = exports.QuorumLeaseProvider = exports.OnchainWatermarkProvider = exports.P2PQuorumLeaseProvider = exports.PersonalLeaseNodeProvider = exports.HybridLeaseProvider = exports.AxiaLeaseProvider = exports.exportLeaseWatermark = exports.seedLeaseWatermark = exports.LocalLeaseProvider = exports.LeaseJournal = exports.fromFlatIndex = exports.flatIndex = exports.WotsWatermarkStore = void 0;
+var watermark_js_1 = require("./watermark.js");
+Object.defineProperty(exports, "WotsWatermarkStore", { enumerable: true, get: function () { return watermark_js_1.WotsWatermarkStore; } });
+Object.defineProperty(exports, "flatIndex", { enumerable: true, get: function () { return watermark_js_1.flatIndex; } });
+Object.defineProperty(exports, "fromFlatIndex", { enumerable: true, get: function () { return watermark_js_1.fromFlatIndex; } });
+var journal_js_1 = require("./journal.js");
+Object.defineProperty(exports, "LeaseJournal", { enumerable: true, get: function () { return journal_js_1.LeaseJournal; } });
+var local_js_1 = require("./local.js");
+Object.defineProperty(exports, "LocalLeaseProvider", { enumerable: true, get: function () { return local_js_1.LocalLeaseProvider; } });
+var seed_js_1 = require("./seed.js");
+Object.defineProperty(exports, "seedLeaseWatermark", { enumerable: true, get: function () { return seed_js_1.seedLeaseWatermark; } });
+Object.defineProperty(exports, "exportLeaseWatermark", { enumerable: true, get: function () { return seed_js_1.exportLeaseWatermark; } });
+var axia_js_1 = require("./axia.js");
+Object.defineProperty(exports, "AxiaLeaseProvider", { enumerable: true, get: function () { return axia_js_1.AxiaLeaseProvider; } });
+var hybrid_js_1 = require("./hybrid.js");
+Object.defineProperty(exports, "HybridLeaseProvider", { enumerable: true, get: function () { return hybrid_js_1.HybridLeaseProvider; } });
+var stubs_js_1 = require("./stubs.js");
+Object.defineProperty(exports, "PersonalLeaseNodeProvider", { enumerable: true, get: function () { return stubs_js_1.PersonalLeaseNodeProvider; } });
+Object.defineProperty(exports, "P2PQuorumLeaseProvider", { enumerable: true, get: function () { return stubs_js_1.P2PQuorumLeaseProvider; } });
+Object.defineProperty(exports, "OnchainWatermarkProvider", { enumerable: true, get: function () { return stubs_js_1.OnchainWatermarkProvider; } });
+var quorum_js_1 = require("./quorum.js");
+Object.defineProperty(exports, "QuorumLeaseProvider", { enumerable: true, get: function () { return quorum_js_1.P2PQuorumLeaseProvider; } });
+var onchain_js_1 = require("./onchain.js");
+Object.defineProperty(exports, "ChainWatermarkProvider", { enumerable: true, get: function () { return onchain_js_1.OnchainWatermarkProvider; } });
+var device_js_1 = require("./device.js");
+Object.defineProperty(exports, "allocateDeviceRange", { enumerable: true, get: function () { return device_js_1.allocateDeviceRange; } });
+Object.defineProperty(exports, "deviceSlotForAddressIndex", { enumerable: true, get: function () { return device_js_1.deviceSlotForAddressIndex; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "WatermarkMonotonicityError", { enumerable: true, get: function () { return errors_js_1.WatermarkMonotonicityError; } });
+Object.defineProperty(exports, "WatermarkExhaustedError", { enumerable: true, get: function () { return errors_js_1.WatermarkExhaustedError; } });
+Object.defineProperty(exports, "WatermarkSeedRegressionError", { enumerable: true, get: function () { return errors_js_1.WatermarkSeedRegressionError; } });
+Object.defineProperty(exports, "WatermarkSeedRequiredError", { enumerable: true, get: function () { return errors_js_1.WatermarkSeedRequiredError; } });
+Object.defineProperty(exports, "LeaseNotFoundError", { enumerable: true, get: function () { return errors_js_1.LeaseNotFoundError; } });
+Object.defineProperty(exports, "IndicesUnavailableError", { enumerable: true, get: function () { return errors_js_1.IndicesUnavailableError; } });
+Object.defineProperty(exports, "PersonalLeaseNodeNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.PersonalLeaseNodeNotConfiguredError; } });
+Object.defineProperty(exports, "P2PQuorumNotImplementedError", { enumerable: true, get: function () { return errors_js_1.P2PQuorumNotImplementedError; } });
+Object.defineProperty(exports, "OnchainWatermarkNotImplementedError", { enumerable: true, get: function () { return errors_js_1.OnchainWatermarkNotImplementedError; } });
+Object.defineProperty(exports, "QuorumUnavailableError", { enumerable: true, get: function () { return errors_js_1.QuorumUnavailableError; } });
+Object.defineProperty(exports, "QuorumConflictError", { enumerable: true, get: function () { return errors_js_1.QuorumConflictError; } });
+Object.defineProperty(exports, "OnchainWatermarkError", { enumerable: true, get: function () { return errors_js_1.OnchainWatermarkError; } });
+Object.defineProperty(exports, "DeviceRangeViolationError", { enumerable: true, get: function () { return errors_js_1.DeviceRangeViolationError; } });
+var replicated_backup_js_1 = require("./replicated-backup.js");
+Object.defineProperty(exports, "ReplicatedLeaseJournalBackup", { enumerable: true, get: function () { return replicated_backup_js_1.ReplicatedLeaseJournalBackup; } });

package/dist/cjs/journal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * LeaseJournal — physically append-only audit log for WOTS key-use events.
+ *
+ * Layout v1 stores one immutable record per sequence. The legacy whole-array
+ * key is retained as migration input/forensic history but is never rewritten.
+ * The SHA-256 chain format is intentionally unchanged (RFC-007 OQ3).
+ */
+import type { StorageAdapter, LoggerAdapter } from '@totemsdk/core';
+import type { JournalEntry } from './types.js';
+export declare class LeaseJournal {
+    private readonly storage;
+    private readonly logger;
+    private entries;
+    private initialized;
+    private initializePromise;
+    private appendTail;
+    constructor(storage: StorageAdapter, logger?: LoggerAdapter);
+    initialize(): Promise<void>;
+    private initializeOnce;
+    private readLegacyEntries;
+    private readPhysicalRecords;
+    private writeRecord;
+    append(entry: JournalEntry): Promise<void>;
+    private appendOne;
+    private ensureInitialized;
+    getAll(): JournalEntry[];
+    getByTree(treeId: string): JournalEntry[];
+    getByReservation(reservationId: string): JournalEntry | undefined;
+    clear(): Promise<void>;
+}

package/dist/cjs/journal.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * LeaseJournal — physically append-only audit log for WOTS key-use events.
+ *
+ * Layout v1 stores one immutable record per sequence. The legacy whole-array
+ * key is retained as migration input/forensic history but is never rewritten.
+ * The SHA-256 chain format is intentionally unchanged (RFC-007 OQ3).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeaseJournal = void 0;
+const sha256_js_1 = require("@noble/hashes/sha256.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const core_1 = require("@totemsdk/core");
+const errors_1 = require("@totemsdk/storage/errors");
+const LEGACY_STORAGE_KEY = 'totem_wots_journal';
+const ENTRY_PREFIX = 'totem_wots_journal:v1:entry:';
+const RECORD_VERSION = 1;
+const SEQUENCE_WIDTH = 16;
+const MAX_INDEX_COMPONENT = 63;
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+const KEY_PATTERN = /^(\d{16}):([0-9a-f]{64})$/;
+const STATUSES = new Set([
+    'reserved',
+    'committed',
+    'burned',
+    'reserved-expired',
+]);
+const storageTails = new WeakMap();
+function withStorageLock(storage, fn) {
+    const prior = storageTails.get(storage) ?? Promise.resolve();
+    const run = prior.then(fn, fn);
+    storageTails.set(storage, run.then(() => undefined, () => undefined));
+    return run;
+}
+/** Existing commitment format; property names/order and SHA-256 stay unchanged. */
+function hashEntry(entry) {
+    const encoder = new TextEncoder();
+    const data = {
+        t: entry.treeId,
+        b: entry.branchId,
+        i: entry.wotsIndex,
+        s: entry.status,
+        r: entry.reservationId,
+        p: entry.previousHash,
+        ts: entry.timestamp,
+        d: entry.deviceId,
+    };
+    const bytes = encoder.encode(JSON.stringify(data));
+    return (0, utils_js_1.bytesToHex)((0, sha256_js_1.sha256)(bytes));
+}
+function cloneEntry(entry) {
+    return {
+        treeId: entry.treeId,
+        branchId: entry.branchId,
+        wotsIndex: entry.wotsIndex,
+        indices: { ...entry.indices },
+        status: entry.status,
+        ...(entry.reservationId !== undefined ? { reservationId: entry.reservationId } : {}),
+        ...(entry.payloadHash !== undefined ? { payloadHash: entry.payloadHash } : {}),
+        ...(entry.txId !== undefined ? { txId: entry.txId } : {}),
+        timestamp: entry.timestamp,
+        deviceId: entry.deviceId,
+        ...(entry.previousHash !== undefined ? { previousHash: entry.previousHash } : {}),
+        ...(entry.hash !== undefined ? { hash: entry.hash } : {}),
+    };
+}
+function asObject(value, key) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid object at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function requiredString(object, field, key) {
+    const value = object[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid ${field} at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function optionalString(object, field, key) {
+    const value = object[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new errors_1.StorageError(`LeaseJournal: invalid ${field} at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function requiredInteger(object, field, key) {
+    const value = object[field];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid ${field} at ${key}`, 'corrupt', { key });
+    }
+    return value;
+}
+function validateEntry(value, key) {
+    const object = asObject(value, key);
+    const indices = asObject(object.indices, `${key}.indices`);
+    const status = requiredString(object, 'status', key);
+    if (!STATUSES.has(status)) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid status at ${key}`, 'corrupt', { key });
+    }
+    const timestamp = object.timestamp;
+    if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp < 0) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid timestamp at ${key}`, 'corrupt', { key });
+    }
+    const validated = cloneEntry({
+        treeId: requiredString(object, 'treeId', key),
+        branchId: requiredString(object, 'branchId', key),
+        wotsIndex: requiredInteger(object, 'wotsIndex', key),
+        indices: {
+            addressIndex: requiredInteger(indices, 'addressIndex', `${key}.indices`),
+            l1: requiredInteger(indices, 'l1', `${key}.indices`),
+            l2: requiredInteger(indices, 'l2', `${key}.indices`),
+        },
+        status,
+        reservationId: optionalString(object, 'reservationId', key),
+        payloadHash: optionalString(object, 'payloadHash', key),
+        txId: optionalString(object, 'txId', key),
+        timestamp,
+        deviceId: requiredString(object, 'deviceId', key),
+        previousHash: optionalString(object, 'previousHash', key),
+        hash: optionalString(object, 'hash', key),
+    });
+    const { addressIndex, l1, l2 } = validated.indices;
+    if (addressIndex > MAX_INDEX_COMPONENT || l1 > MAX_INDEX_COMPONENT || l2 > MAX_INDEX_COMPONENT) {
+        throw new errors_1.StorageError(`LeaseJournal: indices out of range at ${key}`, 'corrupt', { key });
+    }
+    const expectedIndex = addressIndex * 64 * 64 + l1 * 64 + l2;
+    if (validated.wotsIndex !== expectedIndex) {
+        throw new errors_1.StorageError(`LeaseJournal: wotsIndex/indices mismatch at ${key}`, 'corrupt', { key });
+    }
+    return validated;
+}
+function verifyChain(entries, source) {
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i];
+        if (entry.hash === undefined || !HASH_PATTERN.test(entry.hash)) {
+            throw new errors_1.StorageError(`LeaseJournal: invalid hash at ${source}[${i}]`, 'corrupt');
+        }
+        const expectedHash = hashEntry(entry);
+        if (entry.hash !== expectedHash) {
+            throw new errors_1.StorageError(`LeaseJournal: hash mismatch at ${source}[${i}]`, 'corrupt');
+        }
+        if (i === 0) {
+            if (entry.previousHash !== undefined) {
+                throw new errors_1.StorageError(`LeaseJournal: first entry has previousHash at ${source}[0]`, 'corrupt');
+            }
+        }
+        else if (entry.previousHash !== entries[i - 1].hash) {
+            throw new errors_1.StorageError(`LeaseJournal: previousHash mismatch at ${source}[${i}]`, 'corrupt');
+        }
+    }
+}
+function entriesEqual(a, b) {
+    return a.treeId === b.treeId
+        && a.branchId === b.branchId
+        && a.wotsIndex === b.wotsIndex
+        && a.indices.addressIndex === b.indices.addressIndex
+        && a.indices.l1 === b.indices.l1
+        && a.indices.l2 === b.indices.l2
+        && a.status === b.status
+        && a.reservationId === b.reservationId
+        && a.payloadHash === b.payloadHash
+        && a.txId === b.txId
+        && a.timestamp === b.timestamp
+        && a.deviceId === b.deviceId
+        && a.previousHash === b.previousHash
+        && a.hash === b.hash;
+}
+function sequenceText(sequence) {
+    return sequence.toString(10).padStart(SEQUENCE_WIDTH, '0');
+}
+function recordKey(sequence, hash) {
+    return `${ENTRY_PREFIX}${sequenceText(sequence)}:${hash}`;
+}
+function parseRecordKey(key) {
+    const relative = key.slice(ENTRY_PREFIX.length);
+    const match = KEY_PATTERN.exec(relative);
+    if (!match) {
+        throw new errors_1.StorageError(`LeaseJournal: malformed record key ${key}`, 'corrupt', { key });
+    }
+    const sequence = Number(match[1]);
+    if (!Number.isSafeInteger(sequence)) {
+        throw new errors_1.StorageError(`LeaseJournal: invalid sequence in ${key}`, 'corrupt', { key });
+    }
+    return { key, sequence, hash: match[2] };
+}
+class LeaseJournal {
+    constructor(storage, logger = new core_1.NoopLogger()) {
+        this.storage = storage;
+        this.logger = logger;
+        this.entries = [];
+        this.initialized = false;
+        this.initializePromise = null;
+        this.appendTail = Promise.resolve();
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (!this.initializePromise) {
+            this.initializePromise = withStorageLock(this.storage, () => this.initializeOnce()).catch((error) => {
+                this.initializePromise = null;
+                throw error;
+            });
+        }
+        await this.initializePromise;
+    }
+    async initializeOnce() {
+        const physical = await this.readPhysicalRecords();
+        const legacy = await this.readLegacyEntries();
+        if (legacy !== null) {
+            const commonLength = Math.min(physical.length, legacy.length);
+            for (let i = 0; i < commonLength; i += 1) {
+                if (!entriesEqual(physical[i], legacy[i])) {
+                    throw new errors_1.StorageError(`LeaseJournal: legacy/v1 divergence at sequence ${i}`, 'corrupt');
+                }
+            }
+            for (let i = physical.length; i < legacy.length; i += 1) {
+                await this.writeRecord(i, legacy[i]);
+            }
+        }
+        const replayed = legacy !== null && legacy.length > physical.length
+            ? await this.readPhysicalRecords()
+            : physical;
+        this.entries = replayed.map(cloneEntry);
+        this.initialized = true;
+    }
+    async readLegacyEntries() {
+        const raw = await this.storage.get(LEGACY_STORAGE_KEY);
+        if (raw === null)
+            return null;
+        if (!Array.isArray(raw)) {
+            throw new errors_1.StorageError('LeaseJournal: legacy journal is not an array', 'corrupt', { key: LEGACY_STORAGE_KEY });
+        }
+        const entries = raw.map((entry, index) => validateEntry(entry, `${LEGACY_STORAGE_KEY}[${index}]`));
+        verifyChain(entries, LEGACY_STORAGE_KEY);
+        return entries;
+    }
+    async readPhysicalRecords() {
+        const parsed = (await this.storage.keys())
+            .filter((key) => key.startsWith(ENTRY_PREFIX))
+            .map(parseRecordKey)
+            .sort((a, b) => a.sequence - b.sequence || a.key.localeCompare(b.key));
+        for (let i = 0; i < parsed.length; i += 1) {
+            if (i > 0 && parsed[i - 1].sequence === parsed[i].sequence) {
+                throw new errors_1.StorageError(`LeaseJournal: fork at sequence ${parsed[i].sequence}`, 'corrupt');
+            }
+            if (parsed[i].sequence !== i) {
+                throw new errors_1.StorageError(`LeaseJournal: sequence gap at ${i}`, 'corrupt');
+            }
+        }
+        const entries = [];
+        for (const descriptor of parsed) {
+            const raw = await this.storage.get(descriptor.key);
+            if (raw === null) {
+                throw new errors_1.StorageError(`LeaseJournal: listed record is missing`, 'corrupt', { key: descriptor.key });
+            }
+            const record = asObject(raw, descriptor.key);
+            const formatVersion = record.formatVersion;
+            if (formatVersion !== RECORD_VERSION) {
+                throw new errors_1.StorageError('LeaseJournal: unsupported record version', 'corrupt', {
+                    key: descriptor.key,
+                    detectedVersion: typeof formatVersion === 'number' ? formatVersion : undefined,
+                    unsupportedVersion: typeof formatVersion === 'number' ? formatVersion : undefined,
+                });
+            }
+            if (record.sequence !== descriptor.sequence) {
+                throw new errors_1.StorageError('LeaseJournal: sequence/key mismatch', 'corrupt', { key: descriptor.key });
+            }
+            const entry = validateEntry(record.entry, `${descriptor.key}.entry`);
+            if (entry.hash !== descriptor.hash) {
+                throw new errors_1.StorageError('LeaseJournal: hash/key mismatch', 'corrupt', { key: descriptor.key });
+            }
+            entries.push(entry);
+        }
+        verifyChain(entries, ENTRY_PREFIX);
+        return entries;
+    }
+    async writeRecord(sequence, entry) {
+        if (entry.hash === undefined) {
+            throw new errors_1.StorageError(`LeaseJournal: entry ${sequence} has no hash`, 'corrupt');
+        }
+        const key = recordKey(sequence, entry.hash);
+        const record = {
+            formatVersion: RECORD_VERSION,
+            sequence,
+            entry: cloneEntry(entry),
+        };
+        await this.storage.set(key, record);
+    }
+    append(entry) {
+        const run = this.appendTail.then(async () => this.appendOne(entry));
+        this.appendTail = run.catch(() => undefined);
+        return run;
+    }
+    async appendOne(input) {
+        await this.initialize();
+        await withStorageLock(this.storage, async () => {
+            // Refresh under the shared lock so multiple journal instances that share
+            // the same adapter object cannot allocate the same sequence or slot.
+            this.entries = (await this.readPhysicalRecords()).map(cloneEntry);
+            const entry = validateEntry(cloneEntry(input), 'append');
+            if (entry.status === 'reserved' && this.entries.some((existing) => existing.treeId === entry.treeId && existing.wotsIndex === entry.wotsIndex)) {
+                throw new errors_1.StorageError(`LeaseJournal: WOTS slot ${entry.treeId}/${entry.wotsIndex} is already recorded`, 'write-failed');
+            }
+            if (entry.status !== 'reserved' && entry.reservationId) {
+                const latest = [...this.entries].reverse().find((existing) => existing.reservationId === entry.reservationId);
+                if (latest?.status === entry.status) {
+                    if (latest.treeId !== entry.treeId || latest.wotsIndex !== entry.wotsIndex
+                        || (entry.status === 'committed' && latest.txId !== entry.txId)) {
+                        throw new errors_1.StorageError(`LeaseJournal: reservation ${entry.reservationId} is already ${latest.status} for a different use`, 'write-failed');
+                    }
+                    if (latest.previousHash === undefined)
+                        delete input.previousHash;
+                    else
+                        input.previousHash = latest.previousHash;
+                    input.hash = latest.hash;
+                    return;
+                }
+                if (latest && latest.status !== 'reserved') {
+                    throw new errors_1.StorageError(`LeaseJournal: reservation ${entry.reservationId} is already ${latest.status}`, 'write-failed');
+                }
+            }
+            const previous = this.entries[this.entries.length - 1];
+            if (previous?.hash !== undefined)
+                entry.previousHash = previous.hash;
+            else
+                delete entry.previousHash;
+            entry.hash = hashEntry(entry);
+            const sequence = this.entries.length;
+            const sequencePrefix = `${ENTRY_PREFIX}${sequenceText(sequence)}:`;
+            if ((await this.storage.keys()).some((key) => key.startsWith(sequencePrefix))) {
+                throw new errors_1.StorageError(`LeaseJournal: sequence ${sequence} already exists`, 'write-failed');
+            }
+            await this.writeRecord(sequence, entry);
+            this.entries.push(entry);
+            if (entry.previousHash === undefined)
+                delete input.previousHash;
+            else
+                input.previousHash = entry.previousHash;
+            input.hash = entry.hash;
+            this.logger.debug(`[LeaseJournal] ${entry.status} treeId=${entry.treeId} idx=${entry.wotsIndex} `
+                + `txId=${entry.txId ?? '-'} hash=${entry.hash.slice(0, 8)}`);
+        });
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('LeaseJournal not initialized — call initialize() first');
+        }
+    }
+    getAll() {
+        this.ensureInitialized();
+        return this.entries.map(cloneEntry);
+    }
+    getByTree(treeId) {
+        this.ensureInitialized();
+        return this.entries.filter((entry) => entry.treeId === treeId).map(cloneEntry);
+    }
+    getByReservation(reservationId) {
+        this.ensureInitialized();
+        const entry = [...this.entries].reverse().find((candidate) => candidate.reservationId === reservationId);
+        return entry ? cloneEntry(entry) : undefined;
+    }
+    async clear() {
+        throw new errors_1.StorageError('LeaseJournal is append-only and cannot be cleared', 'write-failed');
+    }
+}
+exports.LeaseJournal = LeaseJournal;