@danceiny/gotry 0.2.0-rc.31 → 0.2.0-rc.33

package/dist/src/tenant-state/errors.js

@@ -0,0 +1,108 @@
+/**
+ * Typed failures of the per-tenant state layer (AaaS A1, docs/rfc/aaas-rfc.md §4.2).
+ *
+ * `code` is the stable surface: callers branch on it or on `instanceof`, never on
+ * messages. Every class maps to an availability outcome and never to silent
+ * success: a holder that cannot prove it still owns a tenant must stop
+ * acknowledging writes for it.
+ */
+export class TenantStateError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+/** Another holder has an unexpired lease. Carries the record so a router can forward to that owner. */
+export class LeaseHeldError extends TenantStateError {
+    record;
+    constructor(record) {
+        super('GOTRY_TENANT_LEASE_HELD', `lease ${record.key} is held by ${record.owner} at epoch ${record.epoch}`);
+        this.record = record;
+    }
+}
+/** The caller does not hold the lease any more (expired, taken over, or never held). Terminal for that holder. */
+export class LeaseLostError extends TenantStateError {
+    constructor(message) {
+        super('GOTRY_TENANT_LEASE_LOST', message);
+    }
+}
+/** The write path must not acknowledge: this process cannot prove it still owns the tenant. */
+export class FencedError extends TenantStateError {
+    reason;
+    constructor(reason, key, epoch) {
+        super('GOTRY_TENANT_FENCED', `tenant ${key} epoch ${epoch} is fenced: ${reason}`);
+        this.reason = reason;
+    }
+}
+/** The lease store could not be reached or answered with a contention failure. Owners keep their local deadline and fail closed when it passes. */
+export class LeaseStoreUnavailableError extends TenantStateError {
+    constructor(message, options) {
+        super('GOTRY_TENANT_LEASE_STORE_UNAVAILABLE', message, options);
+    }
+}
+/** An organization or tenant id is not in the fixed, path-safe format (threat S-3). */
+export class InvalidTenantIdError extends TenantStateError {
+    constructor(message) {
+        super('GOTRY_TENANT_ID_INVALID', message);
+    }
+}
+/** The durable store failed or could not be reached. Replication lag grows; a stricter durability mode would refuse writes. */
+export class DurableStoreUnavailableError extends TenantStateError {
+    constructor(message, options) {
+        super('GOTRY_TENANT_DURABLE_STORE_UNAVAILABLE', message, options);
+    }
+}
+/** A durable copy exists but cannot be trusted: a failed checksum, integrity, tenant or fold check. */
+export class RestoreVerificationError extends TenantStateError {
+    skipped;
+    constructor(message, skipped = []) {
+        super('GOTRY_TENANT_RESTORE_INVALID', message);
+        this.skipped = skipped;
+    }
+}
+/** Something else wrote into this holder's own epoch prefix: the single-writer invariant is broken. */
+export class CopyConflictError extends TenantStateError {
+    constructor(message) {
+        super('GOTRY_TENANT_COPY_CONFLICT', message);
+    }
+}
+/** The tenant is being handed off: in-flight work finishes, new work is refused and should be retried on the next owner. */
+export class TenantDrainingError extends TenantStateError {
+    constructor(key) {
+        super('GOTRY_TENANT_DRAINING', `tenant ${key} is being handed off`);
+    }
+}
+/**
+ * A handoff gave up waiting for calls that were already running. The tenant serves again, nothing was flushed or released,
+ * and the caller decides: retry later, or abandon the tenant and give up its writes since the last snapshot. Waiting for
+ * ever would hold the lease for ever, because it is renewed through the drain.
+ */
+export class DrainTimeoutError extends TenantStateError {
+    inFlight;
+    timeoutMs;
+    constructor(key, inFlight, timeoutMs) {
+        super('GOTRY_TENANT_DRAIN_TIMEOUT', `tenant ${key} still had ${inFlight} call(s) running after ${timeoutMs} ms of draining`);
+        this.inFlight = inFlight;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** The router was closed; no tenant can be opened through it any more. */
+export class RouterClosedError extends TenantStateError {
+    constructor() {
+        super('GOTRY_TENANT_ROUTER_CLOSED', 'the tenant router is closed');
+    }
+}
+/**
+ * This replica already holds as many tenants as it was configured to. Each open tenant costs file descriptors (about
+ * three) and memory; past the process's descriptor limit every tenant, and every socket, would start failing at once.
+ * The request is refused before the lease or any file is touched and belongs on another replica or later.
+ */
+export class ReplicaAtCapacityError extends TenantStateError {
+    limit;
+    constructor(limit) {
+        super('GOTRY_TENANT_REPLICA_AT_CAPACITY', 'this replica is serving as many tenants as it is configured to');
+        this.limit = limit;
+    }
+}

package/dist/src/tenant-state/ids.js

@@ -0,0 +1,101 @@
+/**
+ * Tenant and organization identifiers of the AaaS state layer.
+ *
+ * A ledger tenant is one end user; an organization is the deploying party
+ * (hotelbyte's own vocabulary calls that a "tenant"). The tenant id is derived
+ * in the trusted seam from the authenticated principal and is never accepted
+ * from payloads, tools or the model. Every filesystem path of the layer is built
+ * from ids that passed the validators below and from nothing else (threat S-3).
+ */
+import { createHmac } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { InvalidTenantIdError } from './errors.js';
+const ORGANIZATION_ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const LEDGER_TENANT_ID = /^t-[0-9a-f]{32}$/;
+const MIN_ORGANIZATION_KEY_BYTES = 32;
+const MAX_CLAIM_BYTES = 512;
+const CLAIM_SEPARATOR = Buffer.from([0]);
+export function assertOrganizationId(value) {
+    if (typeof value !== 'string' || !ORGANIZATION_ID.test(value)) {
+        throw new InvalidTenantIdError('organization id must be 1-63 characters of [a-z0-9-] starting with [a-z0-9]');
+    }
+    return value;
+}
+export function assertLedgerTenantId(value) {
+    if (typeof value !== 'string' || !LEDGER_TENANT_ID.test(value)) {
+        throw new InvalidTenantIdError('ledger tenant id must be "t-" followed by 32 lowercase hex digits');
+    }
+    return value;
+}
+function claimBytes(name, value) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new InvalidTenantIdError(`${name} must be a non-empty string`);
+    if (value.includes('\u0000'))
+        throw new InvalidTenantIdError(`${name} must not contain NUL`);
+    const bytes = Buffer.from(value, 'utf8');
+    // A lone surrogate is replaced by U+FFFD on encoding, and two different subjects would then share one tenant.
+    if (bytes.toString('utf8') !== value)
+        throw new InvalidTenantIdError(`${name} must be well-formed Unicode`);
+    if (bytes.byteLength > MAX_CLAIM_BYTES)
+        throw new InvalidTenantIdError(`${name} must be at most ${MAX_CLAIM_BYTES} bytes`);
+    return bytes;
+}
+/**
+ * `t-` + the first 128 bits of HMAC-SHA256(K_org, issuer ‖ 0x00 ‖ subject).
+ *
+ * `issuer` and `subject` are matched byte for byte as the identity provider
+ * issued them; this layer does no Unicode normalization. `organizationKey` is
+ * the per-organization server-side key, so ids are neither guessable nor
+ * reversible by anyone who only sees a subject.
+ */
+export function deriveLedgerTenantId(organizationKey, issuer, subject) {
+    if (!(organizationKey instanceof Uint8Array) || organizationKey.byteLength < MIN_ORGANIZATION_KEY_BYTES) {
+        throw new InvalidTenantIdError(`organization key must be at least ${MIN_ORGANIZATION_KEY_BYTES} bytes`);
+    }
+    const mac = createHmac('sha256', organizationKey)
+        .update(claimBytes('issuer', issuer))
+        .update(CLAIM_SEPARATOR)
+        .update(claimBytes('subject', subject))
+        .digest('hex');
+    return `t-${mac.slice(0, 32)}`;
+}
+const CACHE_PARTITION_CONTEXT = Buffer.from('gotry/prompt-cache-partition/v1', 'utf8');
+const CACHE_PARTITION_LABEL = /^pc-[0-9a-f]{32}$/;
+export function assertPromptCachePartition(value) {
+    if (typeof value !== 'string' || !CACHE_PARTITION_LABEL.test(value)) {
+        throw new InvalidTenantIdError('prompt cache partition must be "pc-" followed by 32 lowercase hex digits');
+    }
+    return value;
+}
+/**
+ * `pc-` + the first 128 bits of HMAC-SHA256(K_org, context ‖ 0x00 ‖ ledger tenant id).
+ *
+ * The label that goes into every planner prompt of one tenant, ahead of any tenant-controlled or tenant-derived byte
+ * (docs/rfc/aaas-rfc.md §4.8, threat S-16). A provider caches by prompt prefix; with this label placed after the shared
+ * instructions, the longest prefix two tenants can share ends before it. It is derived under the organization key with
+ * its own context string, so it is stable for one tenant on every replica (the tenant's own cache stays warm across a
+ * handoff), cannot be computed by anyone without the key, and is not the ledger tenant id the metrics and paths use.
+ */
+export function derivePromptCachePartition(organizationKey, ledgerTenantId) {
+    if (!(organizationKey instanceof Uint8Array) || organizationKey.byteLength < MIN_ORGANIZATION_KEY_BYTES) {
+        throw new InvalidTenantIdError(`organization key must be at least ${MIN_ORGANIZATION_KEY_BYTES} bytes`);
+    }
+    const mac = createHmac('sha256', organizationKey)
+        .update(CACHE_PARTITION_CONTEXT)
+        .update(CLAIM_SEPARATOR)
+        .update(assertLedgerTenantId(ledgerTenantId))
+        .digest('hex');
+    return `pc-${mac.slice(0, 32)}`;
+}
+/** The lease key of one tenant: `<organization>/<ledger tenant>`. */
+export function leaseKeyFor(organizationId, ledgerTenantId) {
+    return `${assertOrganizationId(organizationId)}/${assertLedgerTenantId(ledgerTenantId)}`;
+}
+/**
+ * The ownership and replication unit of one tenant on a replica. The directory
+ * holds a complete state root (`gotry-state/gotry-state.db` plus planner files),
+ * so the existing `openDb(root, ledgerTenantId)` opens it unchanged.
+ */
+export function tenantRootFor(stateRoot, organizationId, ledgerTenantId) {
+    return join(resolve(stateRoot), 'orgs', assertOrganizationId(organizationId), 'tenants', assertLedgerTenantId(ledgerTenantId));
+}

package/dist/src/tenant-state/index.js

@@ -0,0 +1,11 @@
+/**
+ * The per-tenant state layer of the AaaS line (docs/rfc/aaas-rfc.md): a single writer per tenant,
+ * fenced by a lease epoch, with epoch-scoped durable copies. Outside the kernel.
+ */
+export * from './durable-store.js';
+export * from './epoch-copies.js';
+export * from './errors.js';
+export * from './ids.js';
+export * from './lease-store.js';
+export * from './tenant-lease.js';
+export * from './tenant-router.js';

package/dist/src/tenant-state/lease-store.js

@@ -0,0 +1,203 @@
+/**
+ * Lease store of the AaaS state layer (docs/rfc/aaas-rfc.md §4.2, decision Q3).
+ *
+ * One record per tenant says which replica may write that tenant's ledger and at
+ * which epoch. The contract is a linearizable compare-and-set per key:
+ *
+ *   - `acquire` succeeds only when no record exists or the record has expired on
+ *     the STORE's clock, and then moves the epoch from n to n + 1;
+ *   - `renew` keeps the epoch and succeeds only for the current, unexpired holder;
+ *   - `release` expires the lease at once and keeps the epoch (the epoch floor);
+ *   - epochs never decrease, and records are never deleted.
+ *
+ * Integrity of the tenant's data does not rest on clocks: durable copies are
+ * scoped by epoch (A1.2), so a stale holder can cost availability but cannot make
+ * its writes authoritative. The store's clock only decides who may try next.
+ *
+ * `SqliteLeaseStore` is the reference implementation: one SQLite file whose write
+ * lock serializes writers across processes on one host. It is what the offline
+ * suites and single-host drills run against. The production binding (hotel-be
+ * MySQL, one row per tenant, CAS on the primary) must pass the same conformance
+ * suite before it is used.
+ */
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { LeaseHeldError, LeaseLostError, LeaseStoreUnavailableError, TenantStateError } from './errors.js';
+export const MIN_LEASE_TTL_MS = 100;
+export const MAX_LEASE_TTL_MS = 10 * 60_000;
+const MAX_TEXT_LENGTH = 200;
+export function assertLeaseTtl(ttlMs) {
+    if (!Number.isInteger(ttlMs) || ttlMs < MIN_LEASE_TTL_MS || ttlMs > MAX_LEASE_TTL_MS) {
+        throw new RangeError(`lease ttl must be an integer within [${MIN_LEASE_TTL_MS}, ${MAX_LEASE_TTL_MS}] ms, got ${String(ttlMs)}`);
+    }
+}
+function assertText(name, value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_TEXT_LENGTH) {
+        throw new RangeError(`${name} must be a non-empty string of at most ${MAX_TEXT_LENGTH} characters`);
+    }
+}
+function assertEpoch(epoch) {
+    if (!Number.isInteger(epoch) || epoch < 1)
+        throw new RangeError(`epoch must be a positive integer, got ${String(epoch)}`);
+}
+function toRecord(row) {
+    return { key: row.key, owner: row.owner, epoch: row.epoch, leaseUntilMs: row.lease_until_ms, forgottenAtEpoch: row.forgotten_at_epoch };
+}
+/**
+ * The storage-level triggers carry the invariants a buggy caller must not be able
+ * to break: epochs move by exactly one, the forgotten floor never moves back, and
+ * a lease row (the epoch floor of its tenant) is never deleted.
+ */
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS leases (
+  key TEXT PRIMARY KEY,
+  owner TEXT NOT NULL,
+  epoch INTEGER NOT NULL CHECK (epoch >= 1),
+  lease_until_ms INTEGER NOT NULL,
+  forgotten_at_epoch INTEGER NOT NULL DEFAULT 0
+) WITHOUT ROWID;
+CREATE TABLE IF NOT EXISTS lease_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  key TEXT NOT NULL,
+  op TEXT NOT NULL CHECK (op IN ('acquire', 'renew', 'release', 'forget')),
+  owner TEXT NOT NULL,
+  epoch INTEGER NOT NULL,
+  at_ms INTEGER NOT NULL
+);
+CREATE TRIGGER IF NOT EXISTS leases_epoch_forward_only
+BEFORE UPDATE OF epoch ON leases
+WHEN NEW.epoch <> OLD.epoch AND NEW.epoch <> OLD.epoch + 1
+BEGIN SELECT RAISE(ABORT, 'lease epoch moves forward by exactly one'); END;
+CREATE TRIGGER IF NOT EXISTS leases_forgotten_floor_forward_only
+BEFORE UPDATE OF forgotten_at_epoch ON leases
+WHEN NEW.forgotten_at_epoch < OLD.forgotten_at_epoch
+BEGIN SELECT RAISE(ABORT, 'the forgotten floor never moves back'); END;
+CREATE TRIGGER IF NOT EXISTS leases_never_deleted
+BEFORE DELETE ON leases
+BEGIN SELECT RAISE(ABORT, 'a lease row is the epoch floor of its tenant and is never deleted'); END;
+`;
+export class SqliteLeaseStore {
+    db;
+    nowMs;
+    constructor(options) {
+        mkdirSync(dirname(options.path), { recursive: true });
+        this.db = new Database(options.path);
+        this.nowMs = options.nowMs ?? Date.now;
+        // busy_timeout before anything contendable: sibling processes must wait for the write lock, not fail at once.
+        this.db.pragma('busy_timeout = 5000');
+        this.immediate(() => { this.db.exec(SCHEMA); });
+    }
+    close() {
+        this.db.close();
+    }
+    async read(key) {
+        assertText('key', key);
+        const row = this.guard(() => this.selectRow(key));
+        return row ? toRecord(row) : null;
+    }
+    async acquire(key, owner, ttlMs) {
+        assertText('key', key);
+        assertText('owner', owner);
+        assertLeaseTtl(ttlMs);
+        return this.immediate(() => {
+            const now = this.nowMs();
+            const row = this.selectRow(key);
+            if (row && row.lease_until_ms > now)
+                throw new LeaseHeldError(toRecord(row));
+            const epoch = row ? row.epoch + 1 : 1;
+            if (row) {
+                this.db.prepare('UPDATE leases SET owner = ?, epoch = ?, lease_until_ms = ? WHERE key = ?').run(owner, epoch, now + ttlMs, key);
+            }
+            else {
+                this.db.prepare('INSERT INTO leases (key, owner, epoch, lease_until_ms) VALUES (?, ?, ?, ?)').run(key, owner, epoch, now + ttlMs);
+            }
+            this.log(key, 'acquire', owner, epoch, now);
+            return { record: this.mustSelect(key), ttlMs };
+        });
+    }
+    async renew(key, owner, epoch, ttlMs) {
+        assertText('key', key);
+        assertText('owner', owner);
+        assertEpoch(epoch);
+        assertLeaseTtl(ttlMs);
+        return this.immediate(() => {
+            const now = this.nowMs();
+            const row = this.requireHolder(key, owner, epoch, now);
+            this.db.prepare('UPDATE leases SET lease_until_ms = ? WHERE key = ?').run(now + ttlMs, row.key);
+            this.log(key, 'renew', owner, epoch, now);
+            return { record: this.mustSelect(key), ttlMs };
+        });
+    }
+    async release(key, owner, epoch) {
+        assertText('key', key);
+        assertText('owner', owner);
+        assertEpoch(epoch);
+        return this.immediate(() => {
+            const now = this.nowMs();
+            const row = this.selectRow(key);
+            if (!row || row.owner !== owner || row.epoch !== epoch)
+                throw new LeaseLostError(`${key}: epoch ${epoch} is not held by ${owner}`);
+            this.db.prepare('UPDATE leases SET lease_until_ms = ? WHERE key = ?').run(Math.min(row.lease_until_ms, now), key);
+            this.log(key, 'release', owner, epoch, now);
+            return this.mustSelect(key);
+        });
+    }
+    async markForgotten(key, owner, epoch) {
+        assertText('key', key);
+        assertText('owner', owner);
+        assertEpoch(epoch);
+        return this.immediate(() => {
+            const now = this.nowMs();
+            const row = this.requireHolder(key, owner, epoch, now);
+            this.db.prepare('UPDATE leases SET forgotten_at_epoch = ? WHERE key = ?').run(Math.max(row.forgotten_at_epoch, epoch), key);
+            this.log(key, 'forget', owner, epoch, now);
+            return this.mustSelect(key);
+        });
+    }
+    /** Audit trail for suites: every granted operation in order. Not part of the LeaseStore contract. */
+    history(key) {
+        const rows = (key === undefined
+            ? this.db.prepare('SELECT key, op, owner, epoch, at_ms FROM lease_log ORDER BY id').all()
+            : this.db.prepare('SELECT key, op, owner, epoch, at_ms FROM lease_log WHERE key = ? ORDER BY id').all(key));
+        return rows.map(row => ({ key: row.key, op: row.op, owner: row.owner, epoch: row.epoch, atMs: row.at_ms }));
+    }
+    requireHolder(key, owner, epoch, now) {
+        const row = this.selectRow(key);
+        if (!row || row.owner !== owner || row.epoch !== epoch)
+            throw new LeaseLostError(`${key}: epoch ${epoch} is not held by ${owner}`);
+        if (row.lease_until_ms <= now)
+            throw new LeaseLostError(`${key}: the lease of epoch ${epoch} expired`);
+        return row;
+    }
+    selectRow(key) {
+        return this.db.prepare('SELECT key, owner, epoch, lease_until_ms, forgotten_at_epoch FROM leases WHERE key = ?').get(key);
+    }
+    mustSelect(key) {
+        const row = this.selectRow(key);
+        if (!row)
+            throw new LeaseStoreUnavailableError(`${key}: lease row vanished inside its transaction`);
+        return toRecord(row);
+    }
+    log(key, op, owner, epoch, atMs) {
+        this.db.prepare('INSERT INTO lease_log (key, op, owner, epoch, at_ms) VALUES (?, ?, ?, ?, ?)').run(key, op, owner, epoch, atMs);
+    }
+    /** Contention is an availability problem of the store; every other failure is a real error and passes through. */
+    guard(fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            if (error instanceof TenantStateError)
+                throw error;
+            const code = error?.code;
+            if (typeof code === 'string' && code.startsWith('SQLITE_BUSY')) {
+                throw new LeaseStoreUnavailableError('lease store is busy', { cause: error });
+            }
+            throw error;
+        }
+    }
+    immediate(fn) {
+        return this.guard(() => this.db.transaction(fn).immediate());
+    }
+}

package/dist/src/tenant-state/tenant-lease.js

@@ -0,0 +1,150 @@
+/**
+ * The holder side of a tenant lease (docs/rfc/aaas-rfc.md §4.2, items 2, 4 and 6).
+ *
+ * A replica owns a tenant between a successful `acquire` and the first of: an
+ * explicit `release`, a refused `renew`, or the local fence deadline. The deadline
+ * is measured on the replica's monotonic clock from BEFORE the request was sent,
+ * so the round trip, the store's clock and any skew between the two clocks only
+ * make the holder stop earlier:
+ *
+ *     fence = sentAt + grantedTtl - margin
+ *
+ * `assertHeld()` is the synchronous gate of the write path. A write is
+ * acknowledged only if the gate passes before it and after it.
+ *
+ * What the local fence cannot see is a frozen clock: a process paused between its
+ * check and its acknowledgement. That case is covered by the durable layer, whose
+ * copies are scoped by epoch, not by this class.
+ */
+import { performance } from 'node:perf_hooks';
+import { FencedError, LeaseLostError } from './errors.js';
+import { assertLeaseTtl } from './lease-store.js';
+export const systemMonotonicClock = { nowMs: () => performance.now() };
+export class TenantLease {
+    key;
+    replicaId;
+    epoch;
+    /** Durable copies of epochs up to this one are dead; fixed for the whole tenure, because only the holder can raise it. */
+    forgottenAtEpoch;
+    store;
+    clock;
+    ttlMs;
+    marginMs;
+    fenceAtMs;
+    state = 'held';
+    tail = Promise.resolve();
+    constructor(options, clock, record, fenceAtMs) {
+        this.key = options.key;
+        this.replicaId = options.replicaId;
+        this.epoch = record.epoch;
+        this.forgottenAtEpoch = record.forgottenAtEpoch;
+        this.store = options.store;
+        this.clock = clock;
+        this.ttlMs = options.ttlMs;
+        this.marginMs = options.marginMs;
+        this.fenceAtMs = fenceAtMs;
+    }
+    /**
+     * @throws LeaseHeldError when another holder has an unexpired lease
+     * @throws LeaseStoreUnavailableError when the store cannot be reached
+     */
+    static async acquire(options) {
+        assertLeaseTtl(options.ttlMs);
+        if (!Number.isInteger(options.marginMs) || options.marginMs < 0 || options.marginMs >= options.ttlMs) {
+            throw new RangeError(`lease margin must be an integer within [0, ttl), got ${String(options.marginMs)} for ttl ${options.ttlMs}`);
+        }
+        const clock = options.clock ?? systemMonotonicClock;
+        const sentAt = clock.nowMs();
+        const grant = await options.store.acquire(options.key, options.replicaId, options.ttlMs);
+        if (grant.record.owner !== options.replicaId || grant.record.key !== options.key) {
+            throw new LeaseLostError(`${options.key}: the store granted the lease to ${grant.record.owner}`);
+        }
+        const lease = new TenantLease(options, clock, grant.record, sentAt + grant.ttlMs - options.marginMs);
+        if (lease.fenceAtMs <= clock.nowMs()) {
+            // The round trip consumed the usable part of the lease; hand it back instead of holding an already fenced epoch.
+            await lease.release().catch(() => undefined);
+            throw new LeaseLostError(`${options.key}: the grant of epoch ${grant.record.epoch} was consumed by the round trip`);
+        }
+        return lease;
+    }
+    /** The synchronous gate of the write path. */
+    assertHeld() {
+        if (this.state === 'released')
+            throw this.fenced('lease_released');
+        if (this.state === 'lost')
+            throw this.fenced('lease_lost');
+        if (this.clock.nowMs() >= this.fenceAtMs)
+            throw this.fenced('lease_expired_locally');
+    }
+    isHeld() {
+        try {
+            this.assertHeld();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Milliseconds until the local fence; zero or negative once fenced. */
+    remainingMs() {
+        return this.fenceAtMs - this.clock.nowMs();
+    }
+    /**
+     * Extends the lease; the epoch stays. A refusal is terminal for this holder. Any other
+     * failure leaves the deadline untouched: the holder fails closed when it passes, and a
+     * later successful renewal resumes it, because an unchanged epoch means nobody else held it.
+     */
+    renew() {
+        return this.serialize(async () => {
+            if (this.state !== 'held')
+                throw this.fenced(this.state === 'released' ? 'lease_released' : 'lease_lost');
+            const sentAt = this.clock.nowMs();
+            try {
+                const grant = await this.store.renew(this.key, this.replicaId, this.epoch, this.ttlMs);
+                if (grant.record.epoch !== this.epoch || grant.record.owner !== this.replicaId) {
+                    throw new LeaseLostError(`${this.key}: renewal answered for epoch ${grant.record.epoch}`);
+                }
+                this.fenceAtMs = Math.max(this.fenceAtMs, sentAt + grant.ttlMs - this.marginMs);
+            }
+            catch (error) {
+                if (error instanceof LeaseLostError)
+                    this.state = 'lost';
+                throw error;
+            }
+        });
+    }
+    /**
+     * Graceful handoff step: stop acknowledging first, then tell the store, so the next owner
+     * can start at once. If the store cannot be reached the lease simply expires; the error is
+     * rethrown so the caller knows the handoff degraded to waiting out the TTL.
+     */
+    release() {
+        return this.serialize(async () => {
+            if (this.state !== 'held')
+                return;
+            this.state = 'released';
+            try {
+                await this.store.release(this.key, this.replicaId, this.epoch);
+            }
+            catch (error) {
+                if (error instanceof LeaseLostError)
+                    return;
+                throw error;
+            }
+        });
+    }
+    /** Marks every durable copy up to this epoch dead (forget). Requires a lease that is provably held. */
+    async markForgotten() {
+        this.assertHeld();
+        return this.store.markForgotten(this.key, this.replicaId, this.epoch);
+    }
+    fenced(reason) {
+        return new FencedError(reason, this.key, this.epoch);
+    }
+    /** Renewals and the release of one holder run one at a time, in call order. */
+    serialize(step) {
+        const run = this.tail.then(step, step);
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}