@aron98/load-lock 0.0.0-stage → 0.1.0

package/dist/core/state.d.ts

@@ -0,0 +1,203 @@
+/**
+ * load-lock core: a pure, synchronous state machine for the machine-wide
+ * counting semaphore. No I/O here — the daemon drives timers, process
+ * liveness checks, journaling and persistence. All mutations are serialized
+ * by construction (single-threaded event loop of the daemon), so every
+ * handle() call is atomic with respect to every other call. Notably,
+ * execution association (start_job) is atomic with respect to reclamation:
+ * a start either observes a live claimed permit and transitions it, or fails.
+ *
+ * Permit lifecycle (see docs/ARCHITECTURE.md):
+ *   acquire --grant--> held(phase=claimed, start deadline)
+ *   offer --claim----> held(phase=claimed, start deadline)
+ *   claimed --start_job-------> held(phase=running_tracked, pid+pgid tracked)
+ *   claimed --mark_started----> held(phase=running_untracked, heartbeat lease)
+ *   running_* --job end-------> released (automatic or explicit, idempotent)
+ *   claimed past deadline ----> released (reclaimed)
+ *   untracked lease expired --> released (reclaimed)
+ *
+ * Invariants (covered by tests):
+ *  - used(pool) = sum(weights of held) + sum(weights of offered) <= capacity,
+ *    except temporarily after a capacity decrease (holders always finish).
+ *  - Queue admission is strict FIFO per pool.
+ *  - Offers reserve capacity; an expired/declined offer passes capacity to
+ *    the next waiter and the request becomes `paused` (never auto-recycled).
+ *  - Tokens (offer/permit) are opaque and single-use; only owners ever see
+ *    them; terminal states invalidate them (kept briefly for idempotency).
+ *  - acquire() is idempotent per (agentId, opKey) while a request is live.
+ *  - A forgotten release cannot permanently block the queue: every held
+ *    permit has an automatic exit (start deadline, tracked process death, or
+ *    untracked lease). A known-running tracked job is never revoked on
+ *    duration alone.
+ */
+import { AcquireParams, AcquireResult, CancelParams, CancelResult, ClaimResult, ConfigHistoryEntry, ConfigureParams, ConfigureResult, EntrySnapshot, EntryState, GetConfigResult, HolderDiag, JournalEntry, MachineConfig, MachineEvent, OwnerEntrySnapshot, PermitPhase, RejoinParams, ReleaseResult, StatusResult } from "../shared/protocol.js";
+export declare const LONG_HOLD_MS: number;
+export declare function defaultConfig(): MachineConfig;
+interface Entry {
+    id: string;
+    pool: string;
+    agentId: string;
+    agentLabel?: string;
+    cwd?: string;
+    opKey: string;
+    reason: string;
+    weight: number;
+    state: EntryState;
+    since: number;
+    offerToken?: string;
+    offerExpiresAt?: number;
+    permitToken?: string;
+    phase?: PermitPhase;
+    startDeadline?: number;
+    pid?: number;
+    pgid?: number;
+    pidStartTime?: string;
+    startedAt?: number;
+    leaseDeadline?: number;
+    lastSeen?: number;
+    enqueuedAt?: number;
+}
+export declare class Machine {
+    config: MachineConfig;
+    private entries;
+    private byKey;
+    private offerTokens;
+    private permitTokens;
+    private queues;
+    private expiredOffers;
+    private events;
+    private nextEventId;
+    private clock;
+    startedAt: number;
+    constructor(clock?: () => number, config?: MachineConfig);
+    now(): number;
+    private pushEvent;
+    /** Events with id > since, newest last. */
+    eventsSince(since: number, agentId?: string, limit?: number): MachineEvent[];
+    latestEventId(): number;
+    private emit;
+    snapshot(e: Entry): EntrySnapshot;
+    private ownerSnapshot;
+    private position;
+    private poolNames;
+    private capacity;
+    /** Weight currently consuming capacity (held + offered). */
+    used(pool: string): number;
+    private liveEntryByOpKey;
+    /**
+     * Fill capacity from the FIFO queue. Strict FIFO: the head of the queue is
+     * admitted only if it fits; otherwise we stop (no bypassing heavier
+     * requests by lighter ones behind them).
+     */
+    private admit;
+    /** Remove an entry from its pool queue if present. */
+    private dequeue;
+    /** Remove op-key association and invalidate live tokens (terminal-ish). */
+    private retire;
+    private newPermit;
+    acquire(p: AcquireParams): AcquireResult;
+    claim(offerToken: string): ClaimResult;
+    /** Daemon-side claim by request id (used for bounded waits). */
+    claimByRequestId(requestId: string): {
+        entry: OwnerEntrySnapshot;
+    };
+    /**
+     * Associate a claimed permit with a real process. Atomic with respect to
+     * reclamation: succeeds only if the permit is held and still in a startable
+     * phase; afterwards the permit is protected by process tracking instead of
+     * the start deadline. Callers that spawn the job first must kill it if this
+     * call fails (see `load-lock run` / run_with_permit helpers).
+     */
+    startJob(permitToken: string, pid: number, pgid?: number, pidStartTime?: string): OwnerEntrySnapshot;
+    /**
+     * Explicit "I started the work, but I cannot associate a process".
+     * The untracked lease applies: renewed by automatic adapter heartbeats,
+     * reclaimed when the owning agent is gone. Documented weaker guarantee.
+     */
+    markStarted(permitToken: string): OwnerEntrySnapshot;
+    /** Adapter heartbeat: extends untracked leases and records agent liveness. */
+    heartbeat(agentId: string): void;
+    /** Idempotent release: a second release returns the terminal state. */
+    release(permitToken: string): ReleaseResult;
+    /**
+     * Daemon-internal release with positive evidence of job death (tracked).
+     * Never expires a permit whose process is merely unknown — callers must
+     * only invoke this with confirmed death of pid/pgid.
+     */
+    autoRelease(entryId: string, cause: string): void;
+    /**
+     * Reclaim: start deadline exceeded, untracked lease expired, or admin
+     * force-release. Frees capacity for the queue.
+     */
+    private reclaim;
+    private finish;
+    /** Expire one offered entry (timer-driven or claim-time). */
+    private expireOffer;
+    /** Nearest future deadline of any kind, or null. The daemon arms timers with this. */
+    nextExpiry(): number | null;
+    /** Called by the daemon at each tick: expire offers, reclaim stale permits, prune. */
+    tick(now: number): void;
+    /** Drop terminal entries (and their idempotency token mappings) after 1h. */
+    private prune;
+    private rememberExpired;
+    decline(offerToken: string): void;
+    rejoin(p: RejoinParams): OwnerEntrySnapshot;
+    cancel(p: CancelParams): CancelResult;
+    pending(agentId: string): {
+        offers: OwnerEntrySnapshot[];
+        queue: OwnerEntrySnapshot[];
+        paused: OwnerEntrySnapshot[];
+        held: OwnerEntrySnapshot[];
+    };
+    /** All outstanding offers (owner-scoped snapshots) — for cwd-matched wakeup. */
+    allOffers(): OwnerEntrySnapshot[];
+    status(pool?: string): StatusResult;
+    /** Held permits — input for daemon liveness sweeps and CLI recovery. */
+    heldEntries(): (EntrySnapshot & {
+        pgid?: number;
+    })[];
+    entryByPermit(permitToken: string): Entry | undefined;
+    private heldByPermit;
+    entryById(requestId: string): {
+        state: EntryState;
+        phase?: PermitPhase;
+    } & EntrySnapshot;
+    ownerSnapshotById(requestId: string): OwnerEntrySnapshot | undefined;
+    offerTokenOf(requestId: string): string | undefined;
+    /** Admin (CLI recovery) force-release of a held permit — reclaims capacity. */
+    adminRelease(requestId: string): void;
+    /**
+     * Recovery diagnostics for held permits. `liveness(pid, pgid, pidStartTime)`
+     * is supplied by the daemon (reads /proc). Returns holder + job info and
+     * which automatic cleanup applies. Long holds are flagged, never revoked
+     * here.
+     */
+    diagnose(liveness: (e: {
+        pid?: number;
+        pgid?: number;
+        pidStartTime?: string;
+    }) => boolean | null): HolderDiag[];
+    get_config(): GetConfigResult;
+    configure(p: ConfigureParams): ConfigureResult;
+    history: ConfigHistoryEntry[];
+    /** Held permits to persist for conservative restart reconciliation. */
+    journalEntries(): JournalEntry[];
+    /**
+     * Restore held permits after a daemon restart (conservative reconciliation):
+     *  - tracked: re-check liveness via the supplied probe; dead => release,
+     *    alive => keep (same token, so a late explicit release still works).
+     *  - claimed: keep the start deadline (reclaimed by tick if already past).
+     *  - untracked: keep, with a FRESH lease window from restore time.
+     * Queued/offered requests are deliberately NOT restored — queued agents
+     * re-acquire (documented restart behavior).
+     */
+    restore(journal: JournalEntry[], liveness: (e: {
+        pid?: number;
+        pgid?: number;
+        pidStartTime?: string;
+    }) => boolean | null): {
+        kept: number;
+        releasedDead: number;
+    };
+}
+export {};