syntaur 0.11.0 → 0.13.0

package/dist/db/leases-db.d.ts

@@ -0,0 +1,178 @@
+import Database from 'better-sqlite3';
+
+/**
+ * Resource leases database module.
+ *
+ * Shares `~/.syntaur/syntaur.db` with `session-db.ts` and `proof-db.ts`. Each
+ * module owns its own schema-version row in the shared `meta` table and creates
+ * `meta` with `IF NOT EXISTS` so init order is irrelevant and standalone init
+ * (e.g. in a leases-only test DB) is safe.
+ *
+ * Concurrency model:
+ *   - `journal_mode = WAL` allows concurrent readers and one writer.
+ *   - `busy_timeout = 5000` lets SQLite absorb short lock contention internally.
+ *   - All mutating ops run inside `db.transaction(fn).immediate()` which issues
+ *     `BEGIN IMMEDIATE` — acquires the reserved lock up-front so two concurrent
+ *     writers serialize cleanly.
+ *
+ * Atomic claim uses the tuple-subquery form (the bundled SQLite is built
+ * without `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`, so `UPDATE...ORDER BY...LIMIT...
+ * RETURNING` is a syntax error — verified empirically).
+ *
+ * Timestamp invariant: every timestamp written from this module is produced by
+ * `nowIso()` which calls `new Date().toISOString()` (canonical UTC, lexicographic-
+ * safe). Lexicographic `<=` comparisons in SQL rely on this. The CLI never
+ * accepts user-supplied timestamps. A future caller writing a non-canonical
+ * timestamp would silently misorder `<=` checks.
+ */
+
+type MemberStatus = 'idle' | 'leased' | 'retired';
+type LeaseState = 'active' | 'released' | 'expired' | 'revoked';
+interface InventoryRow {
+    slug: string;
+    kind: string;
+    display_name: string | null;
+    default_ttl_s: number;
+    created_at: string;
+}
+interface InventoryMemberRow {
+    inventory_slug: string;
+    member_id: string;
+    status: MemberStatus;
+    generation: number;
+    metadata_json: string | null;
+    last_used_at: string | null;
+    retired_at: string | null;
+}
+interface LeaseRow {
+    lease_id: string;
+    inventory_slug: string;
+    member_id: string;
+    member_gen: number;
+    state: LeaseState;
+    granted_at: string;
+    expires_at: string;
+    released_at: string | null;
+    requested_for: string | null;
+}
+interface LeaseEventRow {
+    id: number;
+    lease_id: string;
+    event: string;
+    at: string;
+    detail_json: string | null;
+}
+interface InventoryDetail {
+    inventory: InventoryRow;
+    members: InventoryMemberRow[];
+    active_leases: LeaseRow[];
+}
+interface CreateInventoryInput {
+    slug: string;
+    kind: string;
+    display_name?: string;
+    default_ttl_s: number;
+}
+interface AddMemberInput {
+    inventory_slug: string;
+    member_id: string;
+    metadata?: Record<string, unknown>;
+}
+interface ClaimResult {
+    lease_id: string;
+    inventory_slug: string;
+    member_id: string;
+    member_gen: number;
+    granted_at: string;
+    expires_at: string;
+    metadata: Record<string, unknown> | null;
+}
+interface ListLeasesFilter {
+    inventory?: string;
+    state?: LeaseState;
+}
+declare class NoIdleMemberError extends Error {
+    readonly inventorySlug: string;
+    constructor(inventorySlug: string);
+}
+declare class StaleLeaseError extends Error {
+    readonly leaseId: string;
+    constructor(leaseId: string);
+}
+declare class NotFoundError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+declare class LeaseContentionError extends Error {
+    readonly inventorySlug: string;
+    constructor(inventorySlug: string);
+}
+declare class MemberInUseError extends Error {
+    readonly inventorySlug: string;
+    readonly memberId: string;
+    constructor(inventorySlug: string, memberId: string);
+}
+declare class DuplicateInventoryError extends Error {
+    readonly slug: string;
+    constructor(slug: string);
+}
+declare class DuplicateMemberError extends Error {
+    readonly inventorySlug: string;
+    readonly memberId: string;
+    constructor(inventorySlug: string, memberId: string);
+}
+/** Canonical UTC ISO 8601 timestamp. Lexicographic-safe for SQL `<=` checks. */
+declare function nowIso(): string;
+/**
+ * Initialize the leases database. Idempotent — repeated calls return the same
+ * singleton handle. Pass an explicit `dbPath` for tests; defaults to
+ * `~/.syntaur/syntaur.db`. Safe to run standalone (creates its own `meta` table).
+ */
+declare function initLeasesDb(dbPath?: string): Database.Database;
+declare function getLeasesDb(): Database.Database;
+declare function closeLeasesDb(): void;
+declare function resetLeasesDb(): void;
+declare function createInventory(input: CreateInventoryInput): InventoryRow;
+declare function listInventories(): InventoryRow[];
+declare function getInventoryDetail(slug: string): InventoryDetail | null;
+declare function addMember(input: AddMemberInput): InventoryMemberRow;
+declare function retireMember(inventorySlug: string, memberId: string): void;
+/**
+ * Claim an idle member of `slug`. Atomic — uses `BEGIN IMMEDIATE` so two
+ * concurrent claimants serialize. Returns lease metadata or throws
+ * `NoIdleMemberError` if the inventory has nothing claimable after sweeping.
+ */
+declare function claimLease(slug: string, ttl_s: number, requested_for?: string): ClaimResult;
+declare function releaseLease(lease_id: string): void;
+/**
+ * Extend a lease's TTL from NOW. Refuses if the lease is no longer active,
+ * already past its wall-clock expiry, or its bound member generation has
+ * advanced.
+ */
+declare function extendLease(lease_id: string, ttl_s: number): {
+    new_expires_at: string;
+};
+declare function getLease(lease_id: string): LeaseRow | null;
+declare function listLeases(filter?: ListLeasesFilter): LeaseRow[];
+/**
+ * Sweep expired leases across ALL inventories. Idempotent; safe to run
+ * concurrently with claims (`BEGIN IMMEDIATE` serializes writers).
+ * Returns the number of leases newly transitioned to `expired`.
+ */
+declare function gcExpiredLeases(): number;
+/**
+ * Administrative force-release. Bypasses the lease's `state = 'active'` check
+ * (humans force-releasing an already-expired-but-not-yet-released lease is
+ * fine), but CAS-guards the member free on the lease's bound `member_gen`.
+ * This prevents stomping a member that's currently held by a *different*
+ * active lease (i.e. the targeted lease is already terminal and the slot has
+ * been re-claimed).
+ *
+ * Returns `member_freed: true` if the member was actually idled by this call,
+ * `false` if a newer claim has already taken the slot.
+ */
+declare function forceReleaseLease(lease_id: string): {
+    member_freed: boolean;
+};
+
+export { type AddMemberInput, type ClaimResult, type CreateInventoryInput, DuplicateInventoryError, DuplicateMemberError, type InventoryDetail, type InventoryMemberRow, type InventoryRow, LeaseContentionError, type LeaseEventRow, type LeaseRow, type LeaseState, type ListLeasesFilter, MemberInUseError, type MemberStatus, NoIdleMemberError, NotFoundError, StaleLeaseError, addMember, claimLease, closeLeasesDb, createInventory, extendLease, forceReleaseLease, gcExpiredLeases, getInventoryDetail, getLease, getLeasesDb, initLeasesDb, listInventories, listLeases, nowIso, releaseLease, resetLeasesDb, retireMember };