@byok-sdk/client 0.1.0

package/dist/daemon/git-workspace-store.d.ts

@@ -0,0 +1,49 @@
+import type { GitErrorCategory, GitWorkspaceObservation } from './git-workspace';
+export type GitWorkspacePhase = 'preparing' | 'active' | 'completed' | 'failed' | 'cancelled' | 'interrupted' | 'salvage';
+export interface GitWorkspaceLedgerRecord {
+    workspaceId: string;
+    taskId: string;
+    workspaceDir: string;
+    sessionRef?: string;
+    phase: GitWorkspacePhase;
+    baseline?: string;
+    current?: string;
+    commitsSinceBaseline: number;
+    staged: number;
+    unstaged: number;
+    untracked: number;
+    conflicted: number;
+    createdAt: string;
+    updatedAt: string;
+    errorCategory?: GitErrorCategory;
+}
+export interface GitWorkspaceLedger {
+    version: 1;
+    records: GitWorkspaceLedgerRecord[];
+}
+/** Private, versioned, serialized recovery ledger for local Git workspaces. */
+export declare class GitWorkspaceStore {
+    readonly storeDir: string;
+    readonly filePath: string;
+    private queue;
+    private readonly maxRecords;
+    constructor(storeDir: string, options?: {
+        maxRecords?: number;
+    });
+    initialize(): Promise<void>;
+    list(): Promise<GitWorkspaceLedgerRecord[]>;
+    get(workspaceId: string): Promise<GitWorkspaceLedgerRecord | undefined>;
+    findBySession(sessionRef: string): Promise<GitWorkspaceLedgerRecord | undefined>;
+    findBySessionAnyPhase(sessionRef: string): Promise<GitWorkspaceLedgerRecord | undefined>;
+    attachSession(workspaceId: string, sessionRef: string): Promise<void>;
+    upsert(record: GitWorkspaceLedgerRecord): Promise<void>;
+    updateObservation(workspaceId: string, observation: GitWorkspaceObservation, phase?: GitWorkspacePhase, errorCategory?: GitErrorCategory): Promise<void>;
+    /** Marks old preparation/active records interrupted without reviving protocol tasks. */
+    reconcile(validate?: (record: GitWorkspaceLedgerRecord) => Promise<boolean>): Promise<void>;
+    private prune;
+    private enqueue;
+    private load;
+    private save;
+}
+export declare const GIT_WORKSPACE_LEDGER_FILE = "git-workspaces.json";
+export declare const GIT_WORKSPACE_LEDGER_MAX_RECORDS = 500;

package/dist/daemon/git-workspace.d.ts

@@ -0,0 +1,80 @@
+export interface GitWorkspaceConfig {
+    mode: 'local-checkpoints';
+}
+export type GitErrorCategory = 'git-unavailable' | 'git-timeout' | 'git-output-limit' | 'git-command-failed' | 'workspace-root-invalid' | 'workspace-root-conflict' | 'workspace-not-owned' | 'repository-root-mismatch' | 'repository-invalid' | 'lease-busy' | 'ledger-invalid';
+export declare class GitWorkspaceError extends Error {
+    readonly category: GitErrorCategory;
+    constructor(category: GitErrorCategory, message?: string);
+}
+export interface GitCommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface GitCommandOptions {
+    cwd?: string;
+    timeout?: number;
+    maxBuffer?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export type GitRunner = (args: readonly string[], options?: GitCommandOptions) => Promise<GitCommandResult>;
+declare const DEFAULT_TIMEOUT_MS = 5000;
+declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export declare function stableGitWorkspaceOwnerId(storeDir: string, productId: string): string;
+/** A bounded, no-shell runner for the small Git command allowlist. */
+export declare const defaultGitRunner: GitRunner;
+export interface GitWorkspaceOptions {
+    run?: GitRunner;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    platform?: NodeJS.Platform;
+    ownerId?: string;
+}
+export interface GitWorkspaceObservation {
+    workspaceDir: string;
+    head?: string;
+    baseline?: string;
+    headChanged: boolean;
+    commitsSinceBaseline: number;
+    staged: number;
+    unstaged: number;
+    untracked: number;
+    conflicted: number;
+}
+export interface GitWorkspaceLease {
+    readonly workspaceDir: string;
+    readonly sessionRef?: string;
+    release(): void;
+}
+/** Local Git checkpoint manager. It never invokes a shell or mutating Git command other than init. */
+export declare class GitWorkspaceManager {
+    readonly workspaceRoot: string;
+    readonly ownerId: string;
+    private readonly run;
+    private readonly timeoutMs;
+    private readonly maxOutputBytes;
+    private readonly platform;
+    constructor(workspaceRoot: string, options?: GitWorkspaceOptions);
+    static validateConfig(value: unknown): GitWorkspaceConfig | undefined;
+    preflight(): Promise<void>;
+    ensureOwnerMarker(): Promise<void>;
+    prepareFresh(workspaceDir: string): Promise<GitWorkspaceObservation>;
+    /** Validate an already prepared repository without creating directories or running mutating Git commands. */
+    validateExisting(workspaceDir: string): Promise<GitWorkspaceObservation>;
+    observe(workspaceDir: string, baseline?: string): Promise<GitWorkspaceObservation>;
+    acquireLease(workspaceDir: string, sessionRef?: string): Promise<GitWorkspaceLease>;
+    static guidance(): string;
+    static prependGuidance(instruction: string): string;
+    private commandOptions;
+    private read;
+    private readTopLevel;
+    private assertTaskRoot;
+    private assertExistingAncestry;
+    private assertExistingTaskRoot;
+}
+export declare const GIT_WORKSPACE_OWNER_MARKER = ".byok-git-workspace-owner.json";
+export declare const LOCAL_GIT_WORKSPACE_GUIDANCE: string;
+export declare function prependGitWorkspaceGuidance(instruction: string): string;
+export declare function isGitWorkspaceConfig(value: unknown): value is GitWorkspaceConfig;
+export declare function canonicalWorkspaceRoot(value: string): Promise<string>;
+export { DEFAULT_MAX_OUTPUT_BYTES as GIT_WORKSPACE_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS as GIT_WORKSPACE_TIMEOUT_MS };

package/dist/daemon/http-client.d.ts

@@ -0,0 +1,8 @@
+import type { AuthManager } from './auth-manager';
+/**
+ * `fetch` with the current device bearer token attached. On a 401, renews
+ * the token once (reactive renewal, protocol §6.2) and retries exactly
+ * once — never loops. A second 401 (or {@link AuthManager.handleUnauthorized}
+ * throwing `DeviceRevokedError`) propagates to the caller.
+ */
+export declare function authedFetch(url: string | URL, init: RequestInit, auth: AuthManager): Promise<Response>;

package/dist/daemon/journal/journal.d.ts

@@ -0,0 +1,342 @@
+/**
+ * The daemon's durable local journal port (sprint S3.3 / architecture
+ * §12.7.2).
+ *
+ * The journal is NOT a debug log. It is the correctness precondition for
+ * acking the hosted mailbox: the cloud retires a mailbox row when the daemon's
+ * next poll carries a cursor past it (§12.7.3 — "领走即弃" means *cursor moved
+ * past*, not *read*), so the moment the cursor advances over an envelope, that
+ * envelope exists nowhere but this machine. Everything in this file exists to
+ * make "the bytes are durable" a fact the cursor can be gated on.
+ *
+ * Two shapes here are load-bearing and deliberate:
+ *
+ * - **Bounded records.** The journal stores reliability metadata and small
+ *   bounded bytes. Prompts, tool output, artifacts, workspaces, and blobs stay
+ *   on the filesystem and are referenced, never inlined (§12.7.2). An oversized
+ *   record is rejected with {@link JournalRecordTooLargeError} rather than
+ *   silently truncated — a truncated envelope is not the envelope, and a
+ *   journal that quietly stores something else than what arrived is worse than
+ *   one that refuses.
+ * - **Cleanable categories are a closed set that excludes protected data.**
+ *   §12.7.2.1's never-auto-delete list (unacked envelopes, Running/
+ *   AwaitApproval tasks, unconfirmed terminals, anything carrying a recovery
+ *   marker, user workspaces, provider secrets, quarantine evidence) is
+ *   enforced by {@link CleanableCategory} not having names for those things,
+ *   so the cleanup path cannot ask for one. A runtime filter would put the
+ *   never-delete list one bug away from deleting recovery evidence exactly
+ *   once, in production.
+ */
+/**
+ * The journal's one hash function, shared by every producer so a stored digest
+ * and a recomputed one are comparable without a second convention. `sha256:`
+ * prefixed because the algorithm has to travel with the value — an unprefixed
+ * hex string is a hash of unknown provenance the day this changes.
+ */
+export declare function journalHash(bytes: string): string;
+/**
+ * Who this daemon is, as recorded on every journal row (§12.7.2's minimum
+ * fact set, first three entries). Carried explicitly rather than captured at
+ * construction because `deviceId` is only known after `AuthManager`
+ * `loadExisting()` resolves, strictly after the journal is built.
+ */
+export interface JournalIdentity {
+    readonly tenantId: string;
+    readonly productId: string;
+    readonly deviceId: string;
+}
+/**
+ * One inbound envelope, as received from the mailbox and about to be made
+ * durable. `bytes` is the canonical v1 encoding (`encodeEnvelope`) of the
+ * envelope this daemon parsed — the frozen codec's round-trip guarantee is
+ * what makes that a faithful record — and `bytesHash` is its digest, so a
+ * later reader can tell a redelivery of the same envelope from a different
+ * envelope reusing an id.
+ */
+export interface ReceivedEnvelopeRecord {
+    readonly identity: JournalIdentity;
+    readonly envelopeId: string;
+    /** The envelope's `task_id`, when it carries one. Required whenever {@link opensTask} is true. */
+    readonly taskId?: string;
+    /** The mailbox `seq` this envelope arrived at — the received cursor (§12.7.2's minimum fact set). */
+    readonly seq: number;
+    /** Canonical v1 bytes. Bounded — see {@link JournalRecordTooLargeError}. */
+    readonly bytes: string;
+    /** `sha256:<hex>` over {@link bytes}. */
+    readonly bytesHash: string;
+    readonly receivedAt: string;
+    /**
+     * Whether this envelope OPENS a local task record, i.e. whether the same
+     * transaction must also create the `journal_task` row §12.7.3 requires
+     * ("v1 bytes 与本机 task record 已在同一个本机 transaction durable append").
+     * The caller decides this from the envelope's own type — it is the one
+     * party that already knows, and re-deriving it inside the journal would put
+     * a second copy of protocol semantics somewhere it does not belong.
+     */
+    readonly opensTask: boolean;
+}
+/**
+ * What {@link LocalTaskJournal.appendEnvelope} hands back. The cursor may
+ * advance past {@link seq} once — and only once — this exists.
+ */
+export interface JournalReceipt {
+    readonly envelopeId: string;
+    readonly seq: number;
+    readonly bytesHash: string;
+    readonly committedAt: string;
+    /**
+     * `false` when this exact envelope id was ALREADY durable and this call
+     * changed nothing — the redelivery case (§8.3's at-least-once wire means
+     * every envelope can arrive twice; a crash between commit and ack
+     * guarantees at least one will). A `false` here is a successful, correct
+     * outcome, not an error: it says the bytes are durable, which is all the
+     * cursor needed to know.
+     */
+    readonly created: boolean;
+}
+/** The admission decision for an offered task, as recorded on `journal_task`. */
+export interface AdmissionRecord {
+    readonly taskId: string;
+    readonly admitted: boolean;
+    readonly reason?: string;
+    readonly retryable?: boolean;
+    readonly claimedRuntime?: string;
+    /** Digest of the effective policy this task runs under — the policy itself is not stored (bounded records). */
+    readonly effectivePolicyHash?: string;
+    /** Filesystem reference to the task's workspace. A path, never its contents. */
+    readonly workspaceRef?: string;
+    readonly decidedAt: string;
+}
+/**
+ * One local execution-state transition. Idempotent by {@link transitionId}:
+ * a replayed transition (recovery re-running a step, a redelivered envelope
+ * driving the same move) records nothing new.
+ */
+export interface LocalTransitionRecord {
+    readonly transitionId: string;
+    readonly taskId: string;
+    readonly from?: string;
+    readonly to: string;
+    readonly occurredAt: string;
+    /** Small bounded free-form note. Not a place for tool output. */
+    readonly detail?: string;
+}
+/** Whether the cloud has confirmed the terminal this daemon produced (§12.7.3's "terminal 生成后、truth 写入前" window). */
+export type TerminalTruthState = 'pending' | 'confirmed' | 'failed';
+/**
+ * A task's terminal, as it exists locally. The PAYLOAD is not stored — only
+ * its hash, plus enough retry state to know whether the cloud has taken it.
+ */
+export interface LocalTerminalRecord {
+    readonly taskId: string;
+    readonly terminalType: 'complete' | 'failed' | 'cancelled';
+    readonly payloadHash: string;
+    readonly truthState: TerminalTruthState;
+    /** How many times delivery to the cloud has been attempted. */
+    readonly attempt: number;
+    readonly lastError?: string;
+    readonly recordedAt: string;
+}
+/** A task the journal knows about that has no terminal and no recovery marker — i.e. one this daemon was in the middle of when it stopped. */
+export interface RecoverableTask {
+    readonly taskId: string;
+    readonly envelopeId: string;
+    readonly seq: number;
+    readonly identity: JournalIdentity;
+    readonly localState: string;
+    readonly claimedRuntime?: string;
+    readonly workspaceRef?: string;
+    readonly updatedAt: string;
+}
+/**
+ * What recovery decided about a task. `interrupted` is the honest default for
+ * a daemon restart: local runtime sessions do not survive the process, so the
+ * task is recorded as interrupted rather than pretended back into life — the
+ * same semantics `GitWorkspaceStore.reconcile()` already applies to a lease
+ * whose owner is gone. Nothing here deletes anything; a row that has been
+ * through recovery carries a marker, and §12.7.2.1 forbids auto-deleting
+ * those.
+ */
+export type RecoveryDisposition = 'resumed' | 'interrupted' | 'abandoned';
+export interface RecoveryOutcome {
+    readonly disposition: RecoveryDisposition;
+    readonly reason?: string;
+    readonly occurredAt?: string;
+}
+/**
+ * The five storage categories §12.7.2.1 requires to be measured SEPARATELY —
+ * the cleanup order and the never-delete list are both category-scoped, so a
+ * single "bytes used" number cannot drive either.
+ */
+export type StorageCategory = 'journal' | 'cache' | 'log' | 'workspace' | 'quarantine';
+export interface CategoryUsage {
+    readonly bytes: number;
+    /** `true` when this is a host-reported or sampled figure rather than a measured one. */
+    readonly approximate: boolean;
+}
+export interface LocalStorageUsage {
+    readonly measuredAt: string;
+    readonly totalBytes: number;
+    readonly categories: Readonly<Record<StorageCategory, CategoryUsage>>;
+}
+/**
+ * The categories automatic cleanup may act on, in §12.7.2.1's order. This
+ * union is the never-auto-delete list's enforcement: `quarantine`,
+ * unacked envelopes, live tasks, unconfirmed terminals, recovery-marked rows,
+ * and user-designated workspaces have NO name here, so no cleanup call can
+ * name one. Adding a member is therefore a deliberate, reviewable act rather
+ * than a filter that silently stops matching.
+ */
+export type CleanableCategory = 
+/** Expired upload/download temp files and rebuildable caches. */
+'expired-temp'
+/** Rotated logs past their retention. */
+ | 'rotated-log'
+/** Journal rows for tasks whose terminal the cloud has confirmed and that carry no recovery marker. */
+ | 'confirmed-journal'
+/** Generated workspaces the HOST explicitly marked ephemeral, for tasks already terminal. */
+ | 'ephemeral-workspace'
+/** Local artifacts with no remaining reference, after a reference scan plus grace period. */
+ | 'orphan-artifact';
+export interface CleanupCandidate {
+    readonly candidateId: string;
+    readonly category: CleanableCategory;
+    /** What to act on — a filesystem path, or a journal key. Interpreted by the cleanup worker, never by the journal. */
+    readonly ref: string;
+    readonly eligibleAt: string;
+    readonly reason: string;
+    readonly attempts: number;
+    readonly lastError?: string;
+}
+export interface CleanupResult {
+    readonly candidateId: string;
+    readonly outcome: 'deleted' | 'skipped' | 'failed';
+    readonly bytesReclaimed?: number;
+    readonly error?: string;
+    readonly at: string;
+}
+export interface CompactOptions {
+    /**
+     * `passive` never blocks a concurrent reader/writer and may checkpoint
+     * nothing; `truncate` waits for the WAL to be fully applied and resets it.
+     * Both are maintenance calls and belong off the active-task hot path
+     * (§12.7.2).
+     */
+    readonly checkpoint?: 'passive' | 'truncate';
+    /** Upper bound on freelist pages returned to the filesystem this pass. Bounded so compaction cannot monopolise the single writer. */
+    readonly incrementalVacuumPages?: number;
+}
+export interface CompactResult {
+    readonly checkpointed: boolean;
+    /** WAL frames still outstanding after the checkpoint attempt — `0` means the WAL was fully applied. */
+    readonly walFramesRemaining: number;
+    readonly pagesVacuumed: number;
+    readonly durationMs: number;
+}
+/**
+ * The daemon-local durable journal (sprint S3.3's minimum API, verbatim,
+ * plus {@link close}).
+ *
+ * A port, not an implementation detail: architecture §12.7.2 lets a host
+ * inject its own backend, but only one that meets the same durability
+ * contract. `SqliteLocalTaskJournal` is the shipped production implementation;
+ * a plain JSON/JSONL store is explicitly NOT an acceptable substitute in
+ * hosted mode, because it cannot honour the one property this interface exists
+ * for — that `appendEnvelope` resolving means the bytes survived a power cut.
+ */
+export interface LocalTaskJournal {
+    /**
+     * Make one inbound envelope durable. Resolving means committed and fsynced;
+     * only then may the mailbox cursor advance past `record.seq`.
+     *
+     * Idempotent by envelope id: appending the same envelope twice returns the
+     * original receipt with `created: false` and writes nothing new. That is
+     * what makes redelivery — which the at-least-once wire guarantees will
+     * happen after any crash between commit and ack — a no-op rather than a
+     * second side effect.
+     */
+    appendEnvelope(record: ReceivedEnvelopeRecord): Promise<JournalReceipt>;
+    /** Record the admission decision for a task whose offer envelope is already durable. */
+    recordAdmission(record: AdmissionRecord): Promise<void>;
+    /** Record one local execution-state transition. Idempotent by transition id. */
+    recordTransition(record: LocalTransitionRecord): Promise<void>;
+    /** Record (or update the retry state of) a task's terminal. Idempotent by task id: a replay with the same payload hash is a no-op beyond retry bookkeeping. */
+    recordTerminal(record: LocalTerminalRecord): Promise<void>;
+    /** Tasks with no terminal and no recovery marker — what this daemon was in the middle of when it last stopped. */
+    listRecoverable(): Promise<RecoverableTask[]>;
+    /** Close out one recoverable task by writing its recovery marker. Never deletes; a marked row is on §12.7.2.1's never-auto-delete list. */
+    markRecovered(taskId: string, outcome: RecoveryOutcome): Promise<void>;
+    /** Per-category storage usage (§12.7.2.1) — the input to the watermark state machine. */
+    measureUsage(): Promise<LocalStorageUsage>;
+    /** Cleanup candidates eligible at `now`, oldest first, at most `limit`. Only {@link CleanableCategory} members can ever appear. */
+    listCleanupCandidates(now: Date, limit: number): Promise<CleanupCandidate[]>;
+    /** Record what the cleanup worker actually did with a candidate. */
+    markCleanupResult(result: CleanupResult): Promise<void>;
+    /** Bounded WAL checkpoint + incremental vacuum. Maintenance only; never on the envelope path. */
+    compact(options: CompactOptions): Promise<CompactResult>;
+    /**
+     * Release the underlying handle. Beyond S3.3's minimum API — the daemon
+     * owns this object's lifetime and has to be able to end it, and the crash
+     * matrix needs an explicit "clean shutdown" to contrast against dropping
+     * the reference without one.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Thrown when hosted journal mode is configured on a runtime that cannot
+ * provide a real SQLite backend.
+ *
+ * This is architecture §12.7.2's no-silent-downgrade rule made executable:
+ * "为兼容 Node 20 而退回的普通文件实现不能冒充 production durability." A daemon
+ * that acks a mailbox on the strength of a journal that does not fsync loses
+ * tasks only under power-cut timings — it passes every happy-path test it will
+ * ever be given. Refusing to start is the only honest behaviour, so this is
+ * thrown from CONSTRUCTION, before a single envelope has been accepted.
+ */
+export declare class JournalUnavailableError extends Error {
+    constructor(reason: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the journal database is unreadable and has been moved aside.
+ *
+ * The database is renamed (with its WAL/SHM siblings) into
+ * `<storeDir>/quarantine/`, timestamped, alongside a manifest naming the
+ * reason — and then this is thrown. Nothing is deleted and nothing is
+ * silently rebuilt: a fresh empty database opened over a corrupt one would
+ * report "no recoverable tasks" for a machine that has some, and destroy the
+ * only evidence of why. §12.7.2.1 puts quarantine on the never-auto-delete
+ * list; clearing it is an explicit operator action.
+ */
+export declare class JournalCorruptError extends Error {
+    readonly dbPath: string;
+    readonly quarantinePath: string;
+    constructor(dbPath: string, quarantinePath: string, reason: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a record exceeds the journal's per-record byte bound.
+ *
+ * The journal holds reliability metadata and small bounded bytes; large
+ * payloads live on the filesystem and are referenced (§12.7.2). Rejecting is
+ * the point — truncating would make the stored envelope a different envelope
+ * than the one acked, which is precisely the failure this whole subsystem
+ * exists to rule out.
+ */
+export declare class JournalRecordTooLargeError extends Error {
+    readonly field: string;
+    readonly actualBytes: number;
+    readonly limitBytes: number;
+    constructor(field: string, actualBytes: number, limitBytes: number);
+}
+/** Thrown when a record references a task the journal has no row for — a transition or terminal for a task whose offer envelope was never appended. Fail-closed: the alternative is inventing the missing task row, which would fabricate recovery evidence. */
+export declare class JournalUnknownTaskError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string, operation: string);
+}
+/** Thrown when the journal is used after {@link LocalTaskJournal.close}. */
+export declare class JournalClosedError extends Error {
+    constructor(operation: string);
+}

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

@@ -0,0 +1,173 @@
+import { type AdmissionRecord, type CategoryUsage, type CleanableCategory, type CleanupCandidate, type CleanupResult, type CompactOptions, type CompactResult, type JournalReceipt, type LocalStorageUsage, type LocalTaskJournal, type LocalTerminalRecord, type LocalTransitionRecord, type RecoverableTask, type RecoveryOutcome, type ReceivedEnvelopeRecord, type StorageCategory } from './journal';
+import { JournalHandleCleanupError, type JournalOpenFaultSeam } from './sqlite-support';
+export { JournalHandleCleanupError };
+/** The single database file, per §12.7.2's "建议单库 `<storeDir>/daemon.db`". */
+export declare const JOURNAL_DB_FILENAME = "daemon.db";
+/** Where a database that failed to open is moved to. On §12.7.2.1's never-auto-delete list. */
+export declare const JOURNAL_QUARANTINE_DIRNAME = "quarantine";
+/**
+ * Default per-record byte bound. Generous next to a real `task.offer` (an
+ * instruction plus a policy object — kilobytes), tight enough that an
+ * envelope carrying an inlined artifact is refused instead of turning the
+ * journal into a blob store. See {@link JournalRecordTooLargeError}.
+ */
+export declare const DEFAULT_MAX_RECORD_BYTES: number;
+/** Default bound on how long a write waits for the write lock before failing. */
+export declare const DEFAULT_JOURNAL_BUSY_TIMEOUT_MS = 5000;
+/**
+ * Named points inside a write where {@link JournalFaultSeam} may throw.
+ *
+ * These exist so the crash matrix can put a failure at an exact ordering
+ * boundary — "after the envelope row, before the task row", "after the receipt,
+ * before the commit" — deterministically, with no wall clock and no real
+ * process kill. Same DI shape as `EnsureSecureDirOptions.run`
+ * (`util/secure-dir.ts`): a seam the production path never supplies, exercised
+ * from any host.
+ */
+export type JournalFaultStep = 'append:before-begin' | 'append:after-envelope' | 'append:after-task' | 'append:after-receipt' | 'append:before-commit' | 'admission:before-commit' | 'transition:before-commit' | 'terminal:before-commit' | 'recovery:before-commit' | 'cleanup:before-commit' | 'prune:before-commit';
+export interface JournalFaultSeam {
+    /** Throw to simulate a crash or IO error at exactly this step. Return normally to proceed. */
+    onStep?(step: JournalFaultStep): void;
+}
+export interface SqliteLocalTaskJournalOptions {
+    /** The daemon's store directory. The database lives at `<storeDir>/daemon.db` and quarantine at `<storeDir>/quarantine/`. */
+    readonly storeDir: string;
+    /** Bound on waiting for the write lock. Default {@link DEFAULT_JOURNAL_BUSY_TIMEOUT_MS}. */
+    readonly busyTimeoutMs?: number;
+    /** Per-record byte bound. Default {@link DEFAULT_MAX_RECORD_BYTES}. */
+    readonly maxRecordBytes?: number;
+    /** Test seam — see {@link JournalFaultSeam}. Never supplied in production. */
+    readonly faults?: JournalFaultSeam;
+    /** Test seam for post-open/pre-return SQLite initialization failures. Never supplied in production. */
+    readonly openFaults?: JournalOpenFaultSeam;
+    /** Injected clock, so receipt/quarantine timestamps are deterministic under test. Defaults to the real one. */
+    readonly clock?: () => Date;
+}
+/** The categories `measureUsage` reports. Host-reported ones default to zero-approximate rather than being guessed at. */
+declare const HOST_REPORTED_CATEGORIES: readonly StorageCategory[];
+export declare class SqliteLocalTaskJournal implements LocalTaskJournal {
+    #private;
+    constructor(options: SqliteLocalTaskJournalOptions);
+    /**
+     * The ack-critical path. Envelope bytes, the task record it opens, and the
+     * idempotency receipt all land in ONE transaction, or none of them do.
+     *
+     * The receipt lookup happens INSIDE that transaction rather than as a cheap
+     * pre-check outside it: `BEGIN IMMEDIATE` already holds the write lock by
+     * then, so "is this a redelivery?" and "write it" cannot be separated by
+     * another writer. The duplicate answer is served from the stored receipt,
+     * so a redelivery returns the ORIGINAL commit time and hash — the caller
+     * learns the bytes are durable and that this call changed nothing, which is
+     * exactly what the cursor needed.
+     */
+    appendEnvelope(record: ReceivedEnvelopeRecord): Promise<JournalReceipt>;
+    recordAdmission(record: AdmissionRecord): Promise<void>;
+    /**
+     * Idempotent by transition id. `INSERT OR IGNORE` decides it: when the row
+     * already exists nothing is inserted AND the task's `local_state` is left
+     * alone, so replaying an old transition cannot drag a task's state
+     * backwards — which is precisely what recovery replaying a stored sequence
+     * would otherwise do.
+     */
+    recordTransition(record: LocalTransitionRecord): Promise<void>;
+    /**
+     * First terminal wins, matching the cloud's own receipt rule (§12.6.4:
+     * 不覆写第一份事实). A repeat carrying the SAME payload hash is a delivery
+     * retry and updates only the retry bookkeeping (`truth_state`, `attempt`,
+     * `last_error`); a repeat carrying a DIFFERENT hash is a second, distinct
+     * terminal for a task that already has one, and is recorded nowhere — the
+     * first fact stands.
+     */
+    recordTerminal(record: LocalTerminalRecord): Promise<void>;
+    /**
+     * What this daemon was in the middle of: a task whose offer envelope is
+     * durable, that has no terminal, that was not declined, and that recovery
+     * has not already closed out.
+     *
+     * A task with a terminal is NOT here even when the cloud has not confirmed
+     * it — that is terminal REDELIVERY (§12.7.3's "terminal 生成后、truth 写入前"
+     * row), a different track with different evidence, and folding the two
+     * together would have recovery re-admit a task that already finished.
+     */
+    listRecoverable(): Promise<RecoverableTask[]>;
+    /**
+     * Writes the recovery marker. Idempotent and additive: a task already
+     * marked is left exactly as it was (the FIRST recovery decision is the real
+     * one), and no path here deletes anything — §12.7.2.1 puts recovery-marked
+     * records on the never-auto-delete list, and this is what puts them there.
+     */
+    markRecovered(taskId: string, outcome: RecoveryOutcome): Promise<void>;
+    /**
+     * Per-category bytes (§12.7.2.1). `journal` and `quarantine` are MEASURED
+     * off the filesystem — they are this object's own footprint, so guessing
+     * would be inexcusable. `cache`/`log`/`workspace` are owned by other
+     * subsystems, so they come from whatever they last reported into
+     * `local_storage_usage`; with nothing reported the answer is an explicit
+     * zero-marked-approximate, never a fabricated estimate.
+     */
+    measureUsage(): Promise<LocalStorageUsage>;
+    /**
+     * Record what another subsystem measured for a category it owns. Beyond
+     * S3.3's minimum API and deliberately restricted to the three categories
+     * this journal does NOT measure itself — reporting a number for `journal`
+     * or `quarantine` would let a stale figure override a measured one.
+     */
+    reportCategoryUsage(category: (typeof HOST_REPORTED_CATEGORIES)[number], usage: CategoryUsage): Promise<void>;
+    /**
+     * Register something the cleanup worker may act on. Beyond S3.3's minimum
+     * API (which has no producer for the candidate table), and the only way a
+     * row gets in: `category` is typed {@link CleanableCategory}, so protected
+     * data has no spelling that would let it be enqueued in the first place.
+     */
+    enqueueCleanupCandidate(candidate: {
+        readonly candidateId: string;
+        readonly category: CleanableCategory;
+        readonly ref: string;
+        readonly eligibleAt: string;
+        readonly reason: string;
+    }): Promise<void>;
+    listCleanupCandidates(now: Date, limit: number): Promise<CleanupCandidate[]>;
+    /**
+     * `deleted`/`skipped` resolve the candidate; `failed` does NOT — it bumps
+     * the attempt count and records the error, leaving the row eligible again.
+     * That asymmetry is what makes a cleanup worker crash safe in either order:
+     * crash after deleting the file but before marking, and the candidate is
+     * retried against a file that is already gone (a no-op the worker reports as
+     * `deleted`); crash after marking but before deleting, and the metadata says
+     * resolved for something still on disk, which the next reference scan
+     * re-enqueues. Neither order can lose protected data, because protected data
+     * cannot be a candidate at all.
+     */
+    markCleanupResult(result: CleanupResult): Promise<void>;
+    /**
+     * §12.7.2.1's cleanup step 3: drop one task's journal rows, but ONLY when
+     * the cloud has confirmed its terminal and it carries no recovery marker.
+     *
+     * Beyond S3.3's minimum API, and the ONLY deletion path this journal has.
+     * The eligibility test is the first statement INSIDE the transaction that
+     * would delete, so "is this row protected?" and "delete it" cannot be
+     * separated by another writer marking it recovered in between — a check
+     * performed outside the write lock is a check that can go stale, and the row
+     * it goes stale on is recovery evidence.
+     *
+     * The idempotency receipt goes with the rows. That is deliberate and it is
+     * what `retentionMs['confirmed-journal']` exists to protect: once the receipt
+     * is gone, a redelivery of that envelope would be appended as new, so the
+     * candidate's retention MUST outlast the mailbox redelivery window
+     * (`storage-policy.ts`'s `DEFAULT_RETENTION_MS` carries the longest default
+     * of the five for exactly this reason). Keeping the receipt forever would
+     * trade that risk for an unbounded table, which is the growth this step is
+     * here to stop.
+     *
+     * Returns `false` — having deleted nothing — when the guard refuses.
+     */
+    pruneConfirmedJournalTask(taskId: string): Promise<boolean>;
+    /**
+     * WAL checkpoint plus a BOUNDED incremental vacuum. Maintenance only — it
+     * goes through the same single-writer queue as everything else, so it can
+     * never run concurrently with an ack-critical append, and `incrementalVacuumPages`
+     * caps how long one pass can hold that queue.
+     */
+    compact(options: CompactOptions): Promise<CompactResult>;
+    close(): Promise<void>;
+}