@byok-sdk/client 0.1.0

package/dist/daemon/journal/sqlite-support.d.ts

@@ -0,0 +1,96 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** Every post-construction boundary crossed before a journal handle is returned to its owner. */
+export type JournalOpenStep = 'after-open' | 'after-auto-vacuum' | 'after-wal' | 'after-foreign-keys' | 'after-synchronous' | 'after-header-read';
+/**
+ * Test-only fault seam for proving that every post-open initialization failure
+ * closes the native handle before control returns to the journal constructor.
+ */
+export interface JournalOpenFaultSeam {
+    onStep?(step: JournalOpenStep): void;
+    /** Test-only close override; production always calls `DatabaseSync.close()`. */
+    close?(db: DatabaseSync): void;
+}
+/**
+ * Initialization failed after SQLite returned a native handle, and closing
+ * that handle also failed. Callers must retain their cross-process ownership
+ * lease because the helper can no longer prove that no writer remains alive.
+ */
+export declare class JournalHandleCleanupError extends Error {
+    readonly failures: readonly unknown[];
+    constructor(message: string, failures: readonly unknown[]);
+}
+/**
+ * Whether `nodeVersion` (a `major.minor.patch` string shaped like
+ * `process.versions.node`) is new enough for `node:sqlite` to exist at all.
+ * A version-string heuristic only — `node:sqlite` shipped in 22.5.0 behind
+ * `--experimental-sqlite` and became usable unflagged later, so a runtime
+ * passing this can still fail to load the module. {@link isSqliteAvailable}
+ * is the authoritative check; this one only exists to turn the common
+ * "Node too old" case into a specific message. Unparsable input returns
+ * `true` (the `require` below is the real gate; don't false-negative on a
+ * version shape this hasn't seen).
+ */
+export declare function isSqliteCapableNodeVersion(nodeVersion: string): boolean;
+/**
+ * Synchronously load `node:sqlite` via `createRequire` rather than a dynamic
+ * `import()`. `DatabaseSync`'s entire API is synchronous, and the journal is
+ * constructed synchronously from `createDaemonWithAdapters` alongside every
+ * other daemon-local store (`DeviceStore`, `CursorStore`, ...) — an async
+ * factory here would leak into every one of those call sites for nothing.
+ * `node:sqlite` is a built-in, so `require` resolves it even from this
+ * `"type": "module"` package. Memoized: the throw is re-derived per call from
+ * the version check rather than cached, which keeps the failure message
+ * accurate without keeping a rejected value around.
+ */
+export declare function loadSqliteModule(): typeof import('node:sqlite');
+/**
+ * Whether `node:sqlite` can ACTUALLY be loaded right now. This is what the
+ * journal's own test suites use for `describe.skipIf(!isSqliteAvailable())`
+ * (the same idiom `@byok-sdk/server`'s SQLite suites already use), and what
+ * `createDaemonWithAdapters` calls before constructing a hosted journal so
+ * the refusal is a typed, up-front error instead of a cryptic
+ * `Cannot find module 'node:sqlite'` from deep inside the first append.
+ */
+export declare function isSqliteAvailable(): boolean;
+/**
+ * Open (or create) the journal database at `path` with the durability
+ * settings architecture §12.7.2 pins, in the order they have to be applied:
+ *
+ * 1. `auto_vacuum = INCREMENTAL` — MUST precede table creation. `auto_vacuum`
+ *    is only settable on a database with no schema yet; setting it afterward
+ *    is silently ignored, and `compact()`'s `PRAGMA incremental_vacuum` would
+ *    then be a no-op that reports success.
+ * 2. `journal_mode = WAL` — a reader and the single writer proceed without
+ *    blocking each other, and it is what makes "drop the instance, reopen the
+ *    same file" (the entire crash-matrix method) reliable.
+ * 3. `foreign_keys = ON` — the journal's tables are a real graph
+ *    (transition -> task -> envelope); an orphan row here is corrupted
+ *    recovery evidence, not a tolerable inconsistency.
+ * 4. `synchronous = FULL` — every ack-critical transaction fsyncs before it
+ *    reports committed. This is THE setting the "durable append then cursor
+ *    ack" ordering rests on; NORMAL would let the WAL commit land in the OS
+ *    page cache, so the cursor could advance over an envelope a power cut
+ *    then erases. Applied database-wide rather than per-transaction: the
+ *    journal's whole reason to exist is ack-critical writes, and the
+ *    maintenance paths that do not need it (checkpoint, incremental vacuum)
+ *    are off the hot path anyway.
+ *
+ * `busyTimeoutMs` bounds how long a write waits on the lock before throwing
+ * `SQLITE_BUSY` — bounded on purpose, so contention surfaces as an error the
+ * caller sees rather than an unbounded stall on the envelope path.
+ *
+ * Throws whatever `node:sqlite` throws (module load failure, a corrupt file,
+ * an unreadable directory). Every caller is `SqliteLocalTaskJournal`'s
+ * constructor, which turns each of those into its own typed error — see
+ * `sqlite-journal.ts`.
+ */
+export declare function openJournalDatabase(path: string, busyTimeoutMs: number, faults?: JournalOpenFaultSeam): DatabaseSync;
+/**
+ * Restrict the journal database and its WAL/SHM siblings to owner-only
+ * read/write. The journal holds raw task envelopes (instructions, policy) with
+ * no other access-control layer of its own, so it must not be left at whatever
+ * the process umask would give it. Call AFTER the schema exists, so the
+ * WAL/SHM files SQLite creates lazily on first write are already there; a
+ * sibling that does not exist yet is skipped rather than treated as an error.
+ */
+export declare function secureJournalFilePermissions(dbPath: string): void;

package/dist/daemon/journal/storage-policy.d.ts

@@ -0,0 +1,368 @@
+/**
+ * `LocalStoragePolicy`, the watermark state machine, and the classified GC
+ * engine (architecture §12.7.2.1).
+ *
+ * §12.7.2 gives the daemon a database it must not lose. This file is the other
+ * half of that promise: a machine that runs out of disk cannot commit an
+ * ack-critical transaction, and a daemon that keeps acking mailbox rows it
+ * cannot durably record is losing tasks. So local storage stops being an
+ * operational afterthought and becomes an admission-control input.
+ *
+ * Three shapes here are load-bearing:
+ *
+ * - **The state machine is §12.7.2.1's table, not a threshold check.** Four
+ *   states with distinct *behaviours*: `normal` runs unhurried maintenance;
+ *   `pressure` alerts and cleans only what can be rebuilt; `hard-pressure`
+ *   stops taking NEW work while everything that finishes existing work keeps
+ *   running; `emergency` refuses to ack at all. The difference between
+ *   `hard-pressure` and `emergency` is the whole design: one declines offers
+ *   (a task the dispatcher can place elsewhere), the other freezes the cursor
+ *   (a task the mailbox will redeliver). Neither deletes anything to make room.
+ * - **Cleanup is ordered and bounded, and it cannot name protected data.**
+ *   The order is §12.7.2.1's 1-5, verbatim. The categories are
+ *   {@link CleanableCategory}, which has no member for an unacked envelope, a
+ *   `Running` task, an unconfirmed terminal, a recovery-marked row, a user
+ *   workspace, or quarantine evidence — so no amount of pressure can express
+ *   deleting one. Under pressure the order is TRUNCATED to its rebuildable
+ *   prefix rather than extended: being short of disk is the worst moment to
+ *   start deleting durable records, and the two cheap categories are the ones
+ *   that give space back immediately.
+ * - **Everything measurable is injected.** Usage comes from the journal, free
+ *   space from a provider (`fs.statfs` in production), time from a clock, and
+ *   the cadence from a caller-driven `tick()`. There is no wall-clock race
+ *   anywhere in this file's behaviour, which is what lets the S3.4 disk-pressure
+ *   matrix assert state transitions instead of waiting for them.
+ */
+import type { CategoryUsage, CleanableCategory, CleanupCandidate, CleanupResult, CompactResult, LocalStorageUsage, LocalTaskJournal, StorageCategory } from './journal';
+/** §12.7.2.1's recommended soft watermark: "达到约 80% budget". */
+export declare const DEFAULT_SOFT_BUDGET_RATIO = 0.8;
+/** §12.7.2.1's recommended hard watermark: "达到约 90% budget". */
+export declare const DEFAULT_HARD_BUDGET_RATIO = 0.9;
+/**
+ * Free bytes below which one ack-critical transaction can no longer be
+ * guaranteed, i.e. §12.7.2.1's `emergency` trigger. Sized for a WAL frame
+ * batch plus the checkpoint headroom a `synchronous=FULL` commit needs, not
+ * for a single row — a commit that cannot grow the WAL fails as surely as one
+ * that cannot grow the database.
+ */
+export declare const DEFAULT_ACK_CRITICAL_RESERVE_BYTES: number;
+/** Upper bound on how many candidates one cleanup pass may act on. Bounded so a pass cannot monopolise the journal's single writer. */
+export declare const DEFAULT_CLEANUP_BATCH_LIMIT = 64;
+/** Upper bound on freelist pages one compaction pass returns to the filesystem. */
+export declare const DEFAULT_INCREMENTAL_VACUUM_PAGES = 64;
+/** Unhurried maintenance cadence while `normal` — §12.7.2.1's "常规低频 GC/compaction". */
+export declare const DEFAULT_NORMAL_COMPACTION_INTERVAL_MS: number;
+/** The accelerated cadence §12.7.2.1 asks for at `pressure` and above ("加快 journal compaction"). */
+export declare const DEFAULT_PRESSURE_COMPACTION_INTERVAL_MS: number;
+/**
+ * Per-category retention, as milliseconds between something becoming garbage
+ * and becoming ELIGIBLE for automatic cleanup (§12.7.5).
+ *
+ * `confirmed-journal` is deliberately the longest: pruning a journal row also
+ * drops its idempotency receipt, so its retention MUST outlast the mailbox
+ * redelivery window, or a very late redelivery would re-append an envelope
+ * this device already finished. `orphan-artifact` carries §12.7.5's 24-hour
+ * grace period, which is the reference scan's safety margin, not a guess.
+ */
+export declare const DEFAULT_RETENTION_MS: Readonly<Record<CleanableCategory, number>>;
+/**
+ * Log rotation parameters (§12.7.2.1 lists them among a `LocalStoragePolicy`'s
+ * minimum contents).
+ *
+ * This SDK does not own the daemon's log writer — the host does. These are
+ * therefore the CONTRACT a host's rotator reads, and the reason they live here
+ * rather than in host config is that the rotated files they produce become
+ * `rotated-log` cleanup candidates governed by the same retention above. Two
+ * separate numbers for "when to rotate" and "when to delete" is exactly how a
+ * disk fills up with files nobody owns.
+ */
+export interface LogRotationPolicy {
+    /** Rotate the active log once it exceeds this size. */
+    readonly maxFileBytes: number;
+    /** How many rotated generations to keep before the oldest becomes a `rotated-log` cleanup candidate. */
+    readonly keepFiles: number;
+}
+export declare const DEFAULT_LOG_ROTATION: LogRotationPolicy;
+/** Bounded compaction scheduling — see {@link LocalStoragePressureEngine.tick}. */
+export interface CompactionPolicy {
+    readonly incrementalVacuumPages: number;
+    readonly normalIntervalMs: number;
+    readonly pressureIntervalMs: number;
+}
+/**
+ * The host-injected policy, resolved and validated (§12.7.2.1: "由 host/daemon
+ * config 注入，至少包含 `maxStoreBytes`、`minFreeBytes`、soft/hard watermark、
+ * 各数据类别的 retention、workspace policy 与 log rotation").
+ */
+export interface LocalStoragePolicy {
+    /** Total bytes this daemon's store directory may occupy. The budget the soft/hard ratios apply to. */
+    readonly maxStoreBytes: number;
+    /** Free bytes on the store's filesystem below which this device is at HARD pressure regardless of its own budget. */
+    readonly minFreeBytes: number;
+    /** Free bytes below which this device is at SOFT pressure. Defaults to twice {@link minFreeBytes}, so pressure engages one doubling before the floor. */
+    readonly softMinFreeBytes: number;
+    readonly softBudgetRatio: number;
+    readonly hardBudgetRatio: number;
+    readonly ackCriticalReserveBytes: number;
+    readonly retentionMs: Readonly<Record<CleanableCategory, number>>;
+    readonly logRotation: LogRotationPolicy;
+    readonly cleanupBatchLimit: number;
+    readonly compaction: CompactionPolicy;
+}
+/** What a host actually writes. Everything but the two budget numbers has a §12.7.2.1 default. */
+export interface LocalStoragePolicyInput {
+    maxStoreBytes: number;
+    minFreeBytes: number;
+    softMinFreeBytes?: number;
+    softBudgetRatio?: number;
+    hardBudgetRatio?: number;
+    ackCriticalReserveBytes?: number;
+    retentionMs?: Partial<Record<CleanableCategory, number>>;
+    logRotation?: Partial<LogRotationPolicy>;
+    cleanupBatchLimit?: number;
+    compaction?: Partial<CompactionPolicy>;
+}
+/**
+ * Thrown when a storage policy is internally inconsistent or out of range.
+ *
+ * Rejected at CONSTRUCTION, before a daemon exists, for the same reason
+ * `JournalUnavailableError` is: a policy whose hard watermark sits below its
+ * soft one, or whose budget is zero, produces a daemon that behaves plausibly
+ * until the day it matters. There is no clamping and no "closest sensible
+ * value" here — a misconfigured durability policy is a configuration bug to
+ * fix, not a number to guess at.
+ */
+export declare class LocalStoragePolicyError extends Error {
+    constructor(field: string, reason: string);
+}
+/**
+ * Thrown by {@link LocalStoragePressureEngine.assertAckCriticalAllowed} while
+ * the device is in `emergency`.
+ *
+ * Thrown from the daemon's envelope handler, BEFORE the journal append, which
+ * is what makes it §12.7.2.1's "fail-closed，不 ack 新 mailbox row": the
+ * handler rejects, so `ConnectionManager` records a stall instead of advancing
+ * the cursor, so the mailbox keeps the row and redelivers it. The task is not
+ * lost — it is left where it is still safe, which is the cloud.
+ */
+export declare class LocalStorageEmergencyError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Validate and fill in a host's policy. The ONE place a `LocalStoragePolicy`
+ * comes into existence, so every consumer downstream can treat its fields as
+ * already checked.
+ */
+export declare function resolveLocalStoragePolicy(input: LocalStoragePolicyInput): LocalStoragePolicy;
+/**
+ * When something that became garbage at `since` becomes eligible for automatic
+ * cleanup. The ONE place retention turns into a timestamp, so a producer
+ * calling `enqueueCleanupCandidate` and this engine consuming it agree by
+ * construction rather than by two matching constants.
+ */
+export declare function cleanupEligibleAt(policy: LocalStoragePolicy, category: CleanableCategory, since: Date): string;
+/**
+ * §12.7.2.1's four states, verbatim:
+ *
+ * | state | trigger | behaviour |
+ * | --- | --- | --- |
+ * | `normal` | below soft | unhurried GC/compaction |
+ * | `pressure` | ≥ soft budget, or free below the soft minimum | alert; clean only rebuildable/expired categories; accelerate compaction |
+ * | `hard-pressure` | ≥ hard budget, or free below the hard minimum | stop admitting new ordinary tasks; terminal/truth flush, delete, export and recovery all continue |
+ * | `emergency` | one ack-critical transaction can no longer be guaranteed | fail closed: do not ack new mailbox rows; preserve existing recovery evidence |
+ */
+export type StoragePressureState = 'normal' | 'pressure' | 'hard-pressure' | 'emergency';
+export interface StorageMeasurement {
+    readonly usage: LocalStorageUsage;
+    readonly freeBytes: number;
+}
+/**
+ * The state machine itself — a pure function of policy, measurement, and
+ * whether an ack-critical write has already been observed to fail.
+ *
+ * Evaluated worst-first: `emergency` is not "very bad pressure", it is a
+ * different claim (the next commit may not land), so it is decided before any
+ * budget arithmetic. `latchedFailure` exists because the cheapest evidence
+ * that a transaction cannot complete is one that already did not: a disk-full
+ * error from an ack-critical write is a fact, where free-space arithmetic is
+ * an estimate.
+ */
+export declare function computePressureState(policy: LocalStoragePolicy, measurement: StorageMeasurement, latchedFailure?: string): StoragePressureState;
+/**
+ * §12.7.2.1's cleanup order, 1-5:
+ *
+ * 1. expired upload/download temp files and rebuildable caches;
+ * 2. rotated logs past their retention;
+ * 3. journal rows for tasks whose terminal the cloud confirmed and that carry
+ *    no recovery marker — **compact first, then batch delete**;
+ * 4. host-marked ephemeral workspaces for tasks already terminal;
+ * 5. orphan artifacts, after a reference scan plus grace period.
+ *
+ * Under pressure the order is TRUNCATED to steps 1-2, not extended. Steps 3-5
+ * touch durable records, need a compaction or a reference scan first, and give
+ * their space back slowly; steps 1-2 are pure rebuildable garbage and give it
+ * back immediately. Deleting durable evidence is exactly the wrong reflex when
+ * the disk is nearly full, so it stays on the unhurried `normal` cadence where
+ * a mistake is recoverable.
+ */
+export declare function cleanupOrderFor(state: StoragePressureState): readonly CleanableCategory[];
+/** What a {@link CleanupExecutor} did with one candidate. Mirrors {@link CleanupResult} minus the bookkeeping the engine fills in. */
+export interface CleanupExecution {
+    readonly outcome: 'deleted' | 'skipped' | 'failed';
+    readonly bytesReclaimed?: number;
+    readonly error?: string;
+}
+/**
+ * Performs one candidate's actual deletion.
+ *
+ * A seam rather than a method because the journal owns metadata and the
+ * filesystem owns bytes, and the crash window BETWEEN them (delete the file,
+ * die before marking; mark, die before deleting) is S3.4 point 12. Keeping
+ * them separate is what lets that window be tested at all.
+ *
+ * It receives a {@link CleanupCandidate}, whose `category` is a
+ * {@link CleanableCategory} — so an executor cannot be handed protected data
+ * even by a caller trying to.
+ */
+export type CleanupExecutor = (candidate: CleanupCandidate) => Promise<CleanupExecution>;
+/** `confirmed-journal` candidates address a journal task, not a path. This prefix is that distinction, spelled out. */
+export declare const JOURNAL_TASK_REF_PREFIX = "task:";
+/**
+ * The default cleanup worker: filesystem removal for the four path-addressed
+ * categories, and a delegated journal prune for `confirmed-journal`.
+ *
+ * Two deliberate behaviours:
+ *
+ * - **A missing path is `deleted`, not `failed`.** That is S3.4 point 12's
+ *   first order (file gone, metadata not yet marked) converging on retry: the
+ *   retry finds nothing to do and says so, rather than looping forever on a
+ *   candidate whose work is already done.
+ * - **A relative `ref` is refused.** Cleanup resolves paths against nothing —
+ *   a relative ref would delete whatever the daemon's cwd happens to make it,
+ *   which is not a bug worth having once.
+ */
+export declare function createFilesystemCleanupExecutor(options?: {
+    readonly pruneJournalTask?: (taskId: string) => Promise<boolean>;
+}): CleanupExecutor;
+/** What the status surface renders, and what a `tick()` hands back. */
+export interface StorageStatusSnapshot {
+    readonly state: StoragePressureState;
+    readonly measuredAt: string;
+    readonly budgetBytes: number;
+    readonly usedBytes: number;
+    readonly freeBytes: number;
+    readonly categories: Readonly<Record<StorageCategory, CategoryUsage>>;
+    readonly lastCompaction?: CompactResult & {
+        readonly at: string;
+    };
+}
+export type StoragePressureEvent = 
+/** §12.7.2.1's "发出告警" — emitted on every transition, including back down to `normal`. */
+{
+    readonly kind: 'state-changed';
+    readonly from: StoragePressureState;
+    readonly to: StoragePressureState;
+    readonly snapshot: StorageStatusSnapshot;
+} | {
+    readonly kind: 'cleanup';
+    readonly result: CleanupResult;
+    readonly category: CleanableCategory;
+} | {
+    readonly kind: 'compaction';
+    readonly result: CompactResult;
+};
+export interface StorageTickResult {
+    readonly state: StoragePressureState;
+    readonly snapshot: StorageStatusSnapshot;
+    readonly cleaned: readonly CleanupResult[];
+    readonly compaction?: CompactResult;
+}
+export interface TimerLike {
+    setInterval(handler: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface LocalStoragePressureEngineOptions {
+    readonly policy: LocalStoragePolicy | LocalStoragePolicyInput;
+    readonly journal: LocalTaskJournal;
+    /** Free bytes on the store's filesystem. `fs.statfs` in production (see {@link createStatfsFreeBytesProvider}); a fixed number under test. */
+    readonly freeBytesProvider: () => number | Promise<number>;
+    /** Performs deletions. Defaults to {@link createFilesystemCleanupExecutor}. */
+    readonly executor?: CleanupExecutor;
+    readonly clock?: () => Date;
+    readonly onEvent?: (event: StoragePressureEvent) => void;
+    /** Reports only the scheduler's own maintenance pass outcome; never includes task-domain failures. */
+    readonly onMaintenanceOutcome?: (outcome: 'success' | 'failure') => void;
+    /** Injected so `start()`'s periodic driver is substitutable; the matrix never uses it and drives {@link LocalStoragePressureEngine.tick} directly. */
+    readonly timers?: TimerLike;
+}
+/**
+ * Drives §12.7.2.1: measure, decide the state, clean in order, compact within
+ * bounds — and answer the two questions the rest of the daemon asks
+ * ({@link admissionGuard}, {@link assertAckCriticalAllowed}).
+ *
+ * The cadence is a caller-driven {@link tick}. `start()` merely arranges for
+ * something to call it periodically, so a host with its own scheduler can skip
+ * it entirely, and the disk-pressure matrix can advance state deterministically
+ * with no timer at all. Nothing here runs on the envelope or task hot path:
+ * the only two things the hot path calls are the two synchronous questions,
+ * both of which read a field.
+ */
+export declare class LocalStoragePressureEngine {
+    #private;
+    readonly policy: LocalStoragePolicy;
+    constructor(options: LocalStoragePressureEngineOptions);
+    get state(): StoragePressureState;
+    /** The last measured snapshot, or `undefined` before the first {@link tick}. */
+    snapshot(): StorageStatusSnapshot | undefined;
+    /**
+     * §12.7.2.1's hard-pressure row, as a `TaskRunnerDeps.admissionGuard`:
+     * "停止接收新的普通 task；仍允许 terminal/truth flush、删除、导出、doctor 与
+     * 恢复操作".
+     *
+     * The decline is RETRYABLE because pressure is a property of this device at
+     * this moment — a dispatcher re-routing the task to another device genuinely
+     * helps, and the same device may take it in a minute. Nothing in this method
+     * touches the disk; it reads the state the last tick computed, so an offer
+     * arriving between ticks is answered instantly.
+     */
+    admissionGuard(): {
+        readonly admit: true;
+    } | {
+        readonly admit: false;
+        readonly reason: string;
+        readonly retryable: boolean;
+    };
+    /** Throws {@link LocalStorageEmergencyError} while in `emergency`. Called immediately before every ack-critical journal append. */
+    assertAckCriticalAllowed(): void;
+    /**
+     * Latch `emergency` from an ack-critical write that ACTUALLY failed.
+     *
+     * A commit that returned `SQLITE_FULL` is stronger evidence than any free-space
+     * estimate, and it must not be forgotten on the next tick just because the
+     * arithmetic happens to look survivable. The latch clears only when a tick
+     * measures a genuinely `normal` device — not `pressure`, not `hard-pressure`:
+     * coming back from "the disk refused a write" requires actual headroom, not a
+     * borderline reading.
+     */
+    noteAckCriticalFailure(reason: string): void;
+    /**
+     * One maintenance pass: measure, transition, clean in order, compact if due.
+     *
+     * Ordered this way on purpose — the cleanup pass acts on the state THIS
+     * measurement produced, so a device that just crossed into pressure cleans on
+     * the same tick it alerts, rather than one cadence later.
+     */
+    tick(): Promise<StorageTickResult>;
+    /** Begin periodic ticking. A host with its own scheduler need never call this. */
+    start(): void;
+    stop(): Promise<void>;
+}
+/**
+ * Production free-space provider: bytes available to an unprivileged process
+ * on the filesystem holding `dir`.
+ *
+ * `bavail`, not `bfree` — the reserved blocks `bfree` includes are not space
+ * this daemon can write into, and treating them as headroom is how a device
+ * discovers it is out of disk at commit time instead of at measurement time.
+ */
+export declare function createStatfsFreeBytesProvider(dir: string): () => Promise<number>;

package/dist/daemon/long-poll-transport.d.ts

@@ -0,0 +1,142 @@
+import { type Envelope } from '@byok-sdk/protocol';
+import { AuthManager } from './auth-manager';
+export interface LongPollClientOptions {
+    serverUrl: string;
+    auth: AuthManager;
+    getCursor: () => number | undefined;
+    onEnvelope: (envelope: Envelope) => void;
+    /** Called once the device is found to be revoked (401 surfaced through {@link AuthManager}) — the loop stops itself rather than retrying. */
+    onRevoked?: () => void;
+    /**
+     * M4 Phase 4 (version-negotiation drill fix), scope narrowed by finding F1:
+     * called ONLY for a batch entry that failed to parse because its `type`
+     * is entirely unrecognized (`parseMessage` throwing
+     * {@link UnknownMessageTypeError} — mirrors `ws-transport.ts`'s identical
+     * per-frame tolerance for that SPECIFIC failure) and which still carries a
+     * numeric envelope-level `seq` AND a recognizably task-class `type` (a
+     * `task.` prefix — see `extractSkippableSeq`'s own doc comment for why a
+     * `conn.*`-shaped or type-less entry is deliberately excluded, mirroring
+     * F2's "conn.* is never cursor-tracked" rule), so the caller can advance
+     * its cursor/watermark past it even though there is no real `Envelope` to
+     * hand to `onEnvelope`. Without this, a persistently-redelivered
+     * unrecognized-type entry (the real server retains and redelivers an
+     * un-acked envelope, protocol §9) would keep reappearing at the same
+     * cursor position forever.
+     *
+     * Finding F1: a RECOGNIZED type that fails schema validation
+     * ({@link EnvelopeValidationError} — e.g. a `task.offer` whose
+     * `PermissionPolicy` rejects an unknown constraint) is deliberately NOT
+     * reported here. That failure is a genuinely malformed control message,
+     * not forward-compat tolerance — forwarding its `seq` here would
+     * permanently ack a message the daemon never actually understood (the
+     * server would stop redelivering it, silently stranding whatever it was
+     * offering). The WS path never had this hazard (an unparseable WS frame
+     * has no skip-side cursor bookkeeping at all — see
+     * `ws-transport.ts` — so it simply gets redelivered later); this callback
+     * being scoped to `UnknownMessageTypeError` only is what makes long-poll
+     * match that same "no silent permanent ack" property for real. Optional
+     * only for constructor/test convenience — `ConnectionManager` always
+     * supplies it.
+     */
+    onSkippedSeq?: (seq: number) => void;
+    /**
+     * Finding R1 (cross-model re-review — the F1 fix alone was NOT-CLOSED):
+     * called for a batch entry whose `type` WAS recognized but whose payload
+     * failed schema validation ({@link EnvelopeValidationError}) — a genuine
+     * delivery failure at that specific seq, not forward-compat tolerance
+     * (contrast {@link onSkippedSeq}, which is scoped to the opposite case,
+     * an entirely unrecognized type). F1's own fix — simply not forwarding
+     * this seq to `onSkippedSeq` — turned out to be insufficient on its own:
+     * a LATER valid envelope in the same or a later batch would still
+     * silently advance the durable cursor PAST this seq once its own handler
+     * succeeded, since nothing had told `ConnectionManager` this seq needed
+     * the same stall treatment a thrown handler failure already gets — an
+     * INDIRECT permanent ack, one hop removed from the exact bug F1 set out
+     * to fix. `ConnectionManager` (`noteValidationFailure`) engages
+     * `stalledAtSeq` for this seq the same way `process()`'s own catch block
+     * does for a real thrown handler — freezing `dedupWatermark()` at the
+     * durable cursor (so the server's retain-and-redeliver semantics,
+     * protocol §9, keep this seq alive) and, via that SAME existing
+     * machinery, holding back the cursor for anything else delivered after it
+     * in the same batch too, exactly as a real handler failure already would.
+     * Optional only for constructor/test convenience — `ConnectionManager`
+     * always supplies it.
+     */
+    onValidationFailedSeq?: (seq: number) => void;
+    /**
+     * Finding P2 (Fix 2a): true while a `task.*` envelope's handler has failed
+     * and hasn't yet been successfully reprocessed
+     * (`ConnectionManager.stalledAtSeq`). While true, `getCursor()` stays
+     * frozen below the actual delivery watermark (see
+     * `ConnectionManager.dedupWatermark`'s own doc comment) — so a non-empty
+     * response here doesn't mean "new events arrived", it can just as well
+     * mean "the whole post-cursor backlog got re-pulled again with no
+     * progress". Without a backoff for that case (distinct from "zero
+     * events"), a persistently-failing handler made this loop spin at RTT
+     * against the server. Optional only for constructor/test convenience —
+     * `ConnectionManager` always supplies it.
+     */
+    isStalled?: () => boolean;
+    /** Backoff between failed poll attempts (network/HTTP errors), AND between cycles that made no cursor progress while stalled (finding P2/Fix 2a — see {@link isStalled}). The reference server holds each successful, non-stalled request open ~50s itself (protocol §8), so this only matters when a request errors outright or is stalled. Default 2s. */
+    retryDelayMs?: number;
+    /** Deterministic delay authority for automatic failed/stalled cycles. */
+    retryDelayForAttempt?: (attempt: number, baseDelayMs: number) => number;
+    onOperationalOutcome?: (outcome: 'success' | 'failure') => void;
+    /**
+     * Minimum delay before the next request when a poll comes back with zero
+     * events. The reference server holds each request open ~50s waiting for
+     * something to happen, which throttles the loop for free; a server that
+     * (like this SDK's own test stub) responds immediately instead would
+     * otherwise make this a tight busy-loop. Default 250ms.
+     */
+    idleDelayMs?: number;
+}
+/**
+ * Protocol §8 long-poll fallback: `GET /byok/events?cursor=N` in a loop,
+ * used while WS connectivity is unavailable (see `ConnectionManager`), plus
+ * `POST /byok/messages` for the daemon's own outbound envelopes while in
+ * this mode (finding F6 — long-poll is a full transport, not receive-only:
+ * see docs/protocol.md §8).
+ *
+ * Design B (finding N4): this is a stateless drainer, symmetric with
+ * `WsTransport.sendNow` — it holds no outbound queue of its own.
+ * `ConnectionManager` owns the single shared outbox both transports drain
+ * from (so a transport switch never strands a queued envelope);
+ * `postBatch` is a single POST attempt, reporting back whether the server
+ * accepted it. All retry/backoff policy (and re-checking which transport is
+ * currently active) lives in the caller (`ConnectionManager.drainOutbox`).
+ */
+export declare class LongPollClient {
+    private readonly opts;
+    private running;
+    /**
+     * Finding R1: seqs this loop has already `console.warn`'d about for a
+     * validation-failed (recognized-type, invalid-payload) entry — a poison
+     * entry is redelivered on every poll cycle for as long as it stalls the
+     * cursor (protocol §9), so without this the SAME warning would repeat
+     * every ~poll-interval, forever, for one persistently-malformed message.
+     * Never cleared: once a seq is fixed (a corrected redelivery is
+     * processed), the server never redelivers that seq again, so there is
+     * nothing left to re-warn about for it either. Soft-capped — this is a
+     * pathological/rare path (unlike a per-task hot structure), so on the
+     * rare chance a connection somehow accumulates an unreasonable number of
+     * distinct poisoned seqs, this is simply cleared outright (accepting a
+     * handful of possible re-warnings) rather than carrying any per-entry
+     * eviction bookkeeping for a case this unlikely.
+     */
+    private readonly warnedValidationFailureSeqs;
+    constructor(opts: LongPollClientOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * POST one batch of envelopes to `/byok/messages` (finding F6/protocol
+     * §8.2) — a single attempt, no internal retry loop. Every envelope in
+     * `envelopes` is routed through the server's single inbound gate
+     * (`ConnectionHub.handleInbound`), so a resend of the SAME batch (same
+     * envelope `id`s — the caller must never rebuild them) is deduped
+     * server-side into a safe no-op rather than reprocessed (§9). Returns
+     * `true` once the server has accepted the batch.
+     */
+    postBatch(envelopes: Envelope[]): Promise<boolean>;
+    private loop;
+}