@starci/hfs 4.11.22 → 4.12.2

package/runtime/engine/db/machine.d.mts

@@ -0,0 +1,1746 @@
+import type { SqlDb, SqlRow, SqlRunResult } from './sqlite-types.mjs';
+import type { Recovery, ResilientDb } from './machine-connection.mjs';
+import { pidAlive } from '../../scripts/lib/pid-alive.mjs';
+import { releaseObservedProvisionLock, renewProvisionLock, releaseProvisionLock } from './provision-lock.mjs';
+export { MACHINE_BUSY_CODE, isMachineBusy, isBusyError } from './machine-connection.mjs';
+type Env = NodeJS.ProcessEnv;
+/** Camel-case columns passed through to a table (the pass-through writers: seat, terminal, worktree ...). */
+type Fields = Record<string, unknown>;
+/** What the read-only functions need of a handle: the connection (a writer, a reader and an observer all have one). */
+type Reader = {
+    db: SqlDb;
+};
+/** One registered ledger (a row of the ledgers table, camel-cased). */
+export interface Ledger {
+    ledgerId: string;
+    name: string;
+    product: string | null;
+    repoRoot: string;
+    file: string;
+    state: string;
+    schemaVersion: number | null;
+    registeredAt: number;
+    seenAt: number;
+    retiredAt: number | null;
+    retiredReason: string | null;
+}
+/** The options every way of opening machine.sqlite shares. */
+export interface OpenMachineOptions {
+    file?: string | null;
+    env?: Env;
+    now?: () => number;
+    checkpointer?: boolean;
+    tempDirs?: string[] | null;
+}
+/** One machine_logs row to append. */
+export interface LogRow {
+    actor: string;
+    kind: unknown;
+    msg?: unknown;
+    level?: string;
+    controller?: string | null;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    jobId?: string | null;
+    attemptId?: number | string | null;
+    actionId?: string | null;
+    traceId?: string | null;
+    spanId?: string | null;
+    data?: unknown;
+    refs?: unknown;
+    src?: string | null;
+    at?: number;
+}
+/** One push to record. */
+export interface PushInput {
+    repoRoot: string;
+    branch?: string | null;
+    head: string;
+    fromSha?: string | null;
+    toSha?: string | null;
+    result: string;
+    reason?: unknown;
+    failureSignature?: string | null;
+    ms?: number | null;
+    actionId?: string | null;
+    scan?: unknown;
+    stdout?: unknown;
+    stderr?: unknown;
+}
+/** One land-gate run to record. */
+export interface LandRunInput {
+    ticketId?: string | null;
+    lane?: string | null;
+    spanId?: string;
+    parentSpanId?: string | null;
+    commitSha: string;
+    commits?: unknown;
+    landedSha?: string | null;
+    result: string;
+    reason?: string | null;
+    pushId?: number | null;
+    specs?: unknown;
+    stdout?: unknown;
+    stderr?: unknown;
+    startedAt?: number;
+    finishedAt?: number;
+}
+/** The handle's own state and fenced transaction, before its typed functions are bound. */
+export interface MachineCore {
+    schema: string;
+    file: string;
+    path: string;
+    db: ResilientDb;
+    env: Env;
+    now: () => number;
+    live: boolean;
+    readOnly: boolean;
+    checkpointer: boolean;
+    transaction<T>(fn: (db: SqlDb) => T): T;
+    /** Retries that recovered on this handle ({where, retries, at}); close() records them as one machine_logs warn row. */
+    recovered: Recovery[];
+    close(): void;
+    tempDirs: string[];
+}
+/** A typed function of the API bound to a handle: fn(handle, ...args) becomes handle.fn(...args). */
+type Bound<F> = F extends (m: never, ...args: infer A) => infer R ? (...args: A) => R : never;
+/** The typed functions on a writer or reader handle. */
+export type MachineApi = {
+    [K in keyof typeof API]: Bound<(typeof API)[K]>;
+};
+/** A machine.sqlite handle: openMachine, openMachineReader and withMachine hand it out. */
+export type Machine = MachineCore & MachineApi;
+/** The observation-only handle: the supported reads, no recovery or incident writes. */
+export interface MachineObserverCore {
+    schema: string;
+    file: string;
+    path: string;
+    readOnly: true;
+    db: ResilientDb;
+    recovered: Recovery[];
+    close(): void;
+}
+/** The reads an observer binds. */
+declare const OBSERVER_READS: () => {
+    listLedgers: typeof listLedgers;
+    services: (m: Reader) => {
+        lastProbe: unknown;
+    }[];
+    seats: (m: Reader) => SqlRow[];
+    providerHealth: (m: Reader) => SqlRow[];
+    logs: typeof logs;
+    latestMetrics: (m: Reader, { kind, ledgerId, workflowId }?: {
+        kind?: string;
+        ledgerId?: string | null;
+        workflowId?: string | null;
+    }) => {
+        data: unknown;
+    } | null;
+    throttleState: (m: Reader) => {
+        slotTargets: unknown;
+        priorities: unknown;
+    } | null;
+    poolBackoff: (m: Reader, pool?: string | null) => SqlRow | SqlRow[] | null;
+    quotas: (m: Reader) => SqlRow[];
+    hostLeases: (m: Reader) => SqlRow[];
+    budgets: (m: Reader) => SqlRow[];
+};
+export type MachineObserver = MachineObserverCore & {
+    [K in keyof ReturnType<typeof OBSERVER_READS>]: Bound<ReturnType<typeof OBSERVER_READS>[K]>;
+};
+export declare const MACHINE_SCHEMA = "starci/machine@1";
+export declare const MACHINE_VERSION = 3;
+/** Test seam: STARCI_MACHINE_BUSY_TIMEOUT_MS (a positive integer) replaces the writer's busy_timeout; unset in production. */
+export declare const INIT_SQL_FILE: string;
+export declare const CONTROLLERS: readonly string[];
+/**
+ * Overrides the per-host state base itself (machine.sqlite, projects/, archive/), the one seam starciLocalRoot reads. Debug probes and
+ * throwaway repos point this at a temp directory so they never touch the real
+ * <runtime root>/.runtime and leak fake ledgers/workflows into it (2026-09-30 incident: probe-*, dbg-ask-*, dbg-env*
+ * repos left six fake-worker ledgers in the live store). STARCI_PROJECTS_ROOT (ledger-db.mjs) and
+ * STARCI_TEST_MACHINE_FILE (TEST_REGISTRY_ENV) are narrower overrides that still win over this one when set.
+ */
+export { LOCAL_ROOT_ENV, starciLocalRoot } from '../runtime-root.mjs';
+/** <local root>/projects: one directory per ledger (decision Q1). */
+export declare const localProjectsRoot: (env?: Env) => string;
+/** The explicit test registry: a machine.sqlite that replaces the host's for this process tree (e2e/setup/isolated-registry.mjs). */
+export declare const TEST_REGISTRY_ENV = "STARCI_TEST_MACHINE_FILE";
+/** True when `file` sits under the OS temp directory or the configured temp root, as written or as its realpath. */
+export declare function isUnderTempDir(file: unknown, { env, tempDirs }?: {
+    env?: Env;
+    tempDirs?: string[];
+}): boolean;
+/**
+ * machine.sqlite for `env`: TEST_REGISTRY_ENV when set; else <starciLocalRoot>/machine.sqlite (beside projects/) — except inside a node --test
+ * process tree whose runtime root is not under the temp directory, which gets a shared temp registry instead.
+ */
+export declare const machineFileFor: (env?: Env) => string;
+export declare const newTraceId: () => string;
+export declare const newSpanId: () => string;
+export { pidAlive };
+/**
+ * The rev of the runtime this process runs, as its callers know it: '<HEAD committer time, ms, 13 digits>:<short sha>' of
+ * the harness checkout, which the caller computes and passes in (`rev`,
+ * `writerRev`, `sourceRev`). The db never spawns git: with no rev passed the default is STARCI_RUNTIME_REV, else
+ * 'unknown'. The time prefix orders two revs, so a writer can refuse a store row written by a NEWER runtime (MB-15);
+ * 'unknown' sorts before every real rev.
+ */
+export declare function runtimeRev(): string;
+/**
+ * Open machine.sqlite read-write (creating it from schema/machine.sql on an empty file). Every connection runs wal_autocheckpoint=0;
+ * `checkpointer:true` marks the reconciler engine's connection, the only one allowed to call checkpoint(), and only while
+ * the engine_leader row names it (header).
+ */
+export declare function openMachine({ file, env, now, checkpointer, tempDirs }?: OpenMachineOptions): Machine;
+/** Open machine.sqlite read-only (query_only); null when the file does not exist yet. */
+export declare function openMachineReader({ file, env, now }?: Pick<OpenMachineOptions, "file" | "env" | "now">): Machine | null;
+/** Observation-only reads: supported schemas, bounded retries and diagnostics without incident or recovery writes. */
+export declare function openMachineObserver({ file, env, now }?: Pick<OpenMachineOptions, "file" | "env" | "now">): MachineObserver | null;
+/** fn(handle) over a writer, closed afterwards. */
+export declare function withMachine<T>(fn: (m: Machine) => T, options?: OpenMachineOptions): T;
+/** fn(handle) over a reader; `fallback` when the store does not exist or cannot be read — but a corrupt store is thrown, never hidden. */
+export declare function readMachine<T>(fn: (m: Machine) => T, fallback?: null, options?: Pick<OpenMachineOptions, 'file' | 'env' | 'now'>): T | null;
+export declare function readMachine<T, F>(fn: (m: Machine) => T, fallback: F, options?: Pick<OpenMachineOptions, 'file' | 'env' | 'now'>): T | F;
+/** Store bytes (Buffer | string | file path via {file}) in the blob store and record the blobs row. Returns the sha. */
+declare function putMachineBlob(m: MachineCore, content: unknown, { mediaType, pinned }?: {
+    mediaType?: string;
+    pinned?: boolean;
+}): string;
+/** A JSON value as `{json, sha}`: inline when it fits `limit`, else a small stub inline and the full value as a blob. */
+declare function jsonOrBlob(m: MachineCore, value: unknown, limit?: number): {
+    json: string | null;
+    sha: string | null;
+};
+/** The full JSON value behind a jsonOrBlob stub ({truncated, sha256}); the value itself otherwise. */
+export declare function fullJson(value: unknown): unknown;
+/**
+ * Register (or refresh) a ledger. `ledgerId` is the ledger's own meta.ledger_id. A new row needs name and repoRoot;
+ * `file` defaults to projectLedgerFile(ledgerId). The live registry refuses a ledger file under the OS temp directory
+ * (returns {registered:false, refused}); nothing is written then.
+ */
+/** What registerLedger reports: registered, or refused with the reason (and a code when typed). */
+export interface RegisterLedgerResult {
+    ledgerId: string;
+    registered: boolean;
+    file?: string;
+    code?: string;
+    refused?: string;
+}
+declare function registerLedger(m: MachineCore, { ledgerId, name, repoRoot, file, product, schemaVersion }?: {
+    ledgerId?: string | null;
+    name?: string | null;
+    repoRoot?: string | null;
+    file?: string | null;
+    product?: string | null;
+    schemaVersion?: number | string | null;
+}): RegisterLedgerResult;
+/**
+ * The ledger for a repository root, name or id; null when unregistered. `create:true` with repoRoot (and name) mints a
+ * new ledger id, registers it at projectLedgerFile(id) and returns it — the caller then creates runtime.sqlite there
+ * with meta.ledger_id = ledgerId.
+ */
+declare function resolveLedger(m: MachineCore, { ledgerId, name, repoRoot, create, product }?: {
+    ledgerId?: string | null;
+    name?: string | null;
+    repoRoot?: string | null;
+    create?: boolean;
+    product?: string | null;
+}): Ledger | null;
+declare function listLedgers(m: Reader, { state, includeRetired }?: {
+    state?: string | null;
+    includeRetired?: boolean;
+}): Ledger[];
+declare function touchLedger(m: MachineCore, ledgerId: string, { at }?: {
+    at?: number;
+}): boolean;
+declare function setLedgerState(m: MachineCore, ledgerId: string, state: string, { reason }?: {
+    reason?: string | null;
+}): boolean;
+declare function upsertRepository(m: MachineCore, { repoRoot, name, role, ledgerId, defaultBranch, remote }: {
+    repoRoot: string;
+    name: string;
+    role: string;
+    ledgerId?: string | null;
+    defaultBranch?: string | null;
+    remote?: string | null;
+}): SqlRunResult;
+/**
+ * Run fn({ledger, db}) over every registered ledger opened READ-ONLY, one at a time (B8: no ATTACH-UNION). A ledger that
+ * cannot be opened yields {ledger, error}. Returns the array of results.
+ */
+declare function forEachLedger<T>(m: MachineCore, fn: (context: {
+    ledger: Ledger;
+    db: SqlDb;
+}) => T, { state }?: {
+    state?: string;
+}): Array<{
+    ledger: Ledger;
+    result: T;
+} | {
+    ledger: Ledger;
+    error: string;
+}>;
+/** Manual queries only: ATTACH up to 9 ledgers read-only to this handle as l0..l8. Returns the attached names. */
+declare function attachLedgers(m: MachineCore, ledgers?: Ledger[]): {
+    ledgerId: string;
+    name: string;
+    product: string | null;
+    repoRoot: string;
+    file: string;
+    state: string;
+    schemaVersion: number | null;
+    registeredAt: number;
+    seenAt: number;
+    retiredAt: number | null;
+    retiredReason: string | null;
+    alias: string;
+}[];
+/** Append one sup_events row; the digest chain is computed here (JS), inside the caller's or a new transaction. */
+declare function supEvent(m: MachineCore, { entityType, entityId, kind, payload, spanId, at, eventId }: {
+    entityType?: string;
+    entityId?: string | number;
+    kind: string;
+    payload?: unknown;
+    spanId?: string | null;
+    at?: number;
+    eventId?: string | null;
+}): {
+    seq: number;
+    eventId: string;
+    digest: string;
+};
+declare function supEvents(m: Reader, { kind, kinds, entityType, entityId, since, limit, order }?: {
+    kind?: string | null;
+    kinds?: string[] | null;
+    entityType?: string | null;
+    entityId?: string | number | null;
+    since?: number | null;
+    limit?: number;
+    order?: string;
+}): {
+    payload: unknown;
+}[];
+declare const newestSupEvent: (m: Reader, kind: string) => {
+    payload: unknown;
+} | null;
+declare function upsertSupJob(m: MachineCore, { jobId, traceId, kind, role, cluster, title, status, lane, files, brief, payload }: {
+    jobId: string;
+    traceId?: string | null;
+    kind: string;
+    role?: string;
+    cluster?: string | null;
+    title: string;
+    status?: string;
+    lane?: string | null;
+    files?: unknown;
+    brief?: string | null;
+    payload?: unknown;
+}): SqlRunResult;
+declare function setSupJobStatus(m: MachineCore, jobId: string, status: string, { payload }?: {
+    payload?: unknown;
+}): boolean;
+declare const supJob: (m: Reader, jobId: string) => {
+    files: unknown;
+    payload: unknown;
+} | null;
+declare function listSupJobs(m: Reader, { status, statuses, kind }?: {
+    status?: string | null;
+    statuses?: string[] | null;
+    kind?: string | null;
+}): {
+    files: unknown;
+    payload: unknown;
+}[];
+declare function acquireSupLeases(m: MachineCore, jobId: string, paths: string[], { ttlMs }?: {
+    ttlMs?: number;
+}): {
+    ok: boolean;
+    conflicts: ({
+        path: string | undefined;
+        holder: any;
+    } | null)[];
+} | {
+    ok: boolean;
+    conflicts?: never;
+};
+declare const releaseSupLeases: (m: MachineCore, jobId: string) => number;
+declare function startSupAttempt(m: MachineCore, { jobId, spanId, parentSpanId, ...rest }: {
+    jobId: string;
+    spanId?: string;
+    parentSpanId?: string | null;
+    [column: string]: unknown;
+}): {
+    attemptId: number;
+    dispatchSeq: number;
+    spanId: string;
+};
+declare const updateSupAttempt: (m: MachineCore, attemptId: number, fields: Fields) => boolean;
+declare const latestSupAttempt: (m: Reader, jobId: string) => SqlRow | null;
+declare function recordSupReport(m: MachineCore, { attemptId, jobId, outcome, report, reportText }: {
+    attemptId: number;
+    jobId: string;
+    outcome: string;
+    report?: unknown;
+    reportText?: string | null;
+}): {
+    reportId: number;
+    reportSha: string | null;
+};
+declare const supReports: (m: Reader, { jobId, unconsumed }?: {
+    jobId?: string | null;
+    unconsumed?: boolean;
+}) => {
+    report: unknown;
+}[];
+declare const consumeSupReport: (m: MachineCore, reportId: number) => boolean;
+/**
+ * Open a Supervisor Decision Item, idempotent on its key (MB-07: '<kind>:<entity>:<signature>:<head>', no empty part).
+ * Returns {diId, created}. An existing open item with the same key is returned unchanged.
+ */
+declare function openSupDecision(m: MachineCore, { keyParts, kind, decider, summary, ledgerId, workflowId, entityType, entityId, openedBy, dueAt, escalateTo, evidence, options, allowedVerbs, payload }: {
+    keyParts: Record<string, unknown>;
+    kind: string;
+    decider?: string;
+    summary: string;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    entityType?: string | null;
+    entityId?: string | null;
+    openedBy?: string;
+    dueAt?: number | null;
+    escalateTo?: string | null;
+    evidence?: unknown;
+    options?: unknown;
+    allowedVerbs?: unknown;
+    payload?: unknown;
+}): {
+    diId: any;
+    created: boolean;
+    status: any;
+};
+declare function setSupDecision(m: MachineCore, diId: string, { status, by, verb, choice, rationale, result, supersededBy, spanId }: {
+    status: string;
+    by?: string | null;
+    verb?: string | null;
+    choice?: string | null;
+    rationale?: string | null;
+    result?: unknown;
+    supersededBy?: string | null;
+    spanId?: string;
+}): {
+    changed: boolean;
+    decisionId: string | null;
+};
+declare const markSupDecisionDelivered: (m: MachineCore, diId: string) => boolean;
+declare function listSupDecisions(m: Reader, { open, kind }?: {
+    open?: boolean;
+    kind?: string | null;
+}): {
+    keyParts: unknown;
+    payload: unknown;
+    evidence: unknown;
+}[];
+declare function openOwed(m: MachineCore, { owedId, kind, subject, cluster, dueAt, detail }: {
+    owedId: string;
+    kind: string;
+    subject: string;
+    cluster?: string | null;
+    dueAt?: number | null;
+    detail?: unknown;
+}): {
+    owedId: string;
+    created: boolean;
+    state: any;
+};
+declare const ackOwed: (m: MachineCore, owedId: string, { by }?: {
+    by?: string;
+}) => boolean;
+declare function upsertLearning(m: MachineCore, { itemId, kind, parentId, title, state, sourceRef, lane, landedSha, detail }: {
+    itemId: string;
+    kind: string;
+    parentId?: string | null;
+    title: string;
+    state?: string | null;
+    sourceRef?: string | null;
+    lane?: string | null;
+    landedSha?: string | null;
+    detail?: unknown;
+}): SqlRunResult;
+declare function upsertBridge(m: MachineCore, { bridgeId, ledgerId, action, state, approvedBy, detail }: {
+    bridgeId: string;
+    ledgerId?: string | null;
+    action: string;
+    state: string;
+    approvedBy?: string | null;
+    detail?: unknown;
+}): SqlRunResult;
+declare function recordSupMessage(m: MachineCore, { msgId, direction, channel, chatId, messageId, from, to, via, text, ok, at }: {
+    msgId?: string;
+    direction: string;
+    channel: string;
+    chatId?: string | null;
+    messageId?: string | null;
+    from?: string | null;
+    to?: string | null;
+    via?: string | null;
+    text: string;
+    ok?: boolean | null;
+    at?: number;
+}): string;
+declare const supMessages: (m: Reader, { direction, unread, limit }?: {
+    direction?: string | null;
+    unread?: boolean;
+    limit?: number;
+}) => SqlRow[];
+declare function setSupSignal(m: MachineCore, { scope, key, value, token, holderPid, expiresAt }: {
+    scope: string;
+    key?: string;
+    value?: unknown;
+    token?: string | null;
+    holderPid?: number;
+    expiresAt?: number | null;
+}): SqlRunResult;
+declare const supSignal: (m: Reader, scope: string, key?: string) => {
+    value: unknown;
+} | null;
+declare function recordMachineLlmUsage(m: MachineCore, { subjectType, supAttemptId, turnRef, spanId, provider, requestModel, responseModel, source, ...counts }: {
+    subjectType: string;
+    supAttemptId?: number | null;
+    turnRef?: string | null;
+    spanId?: string | null;
+    provider: string;
+    requestModel?: string | null;
+    responseModel?: string | null;
+    source?: string;
+    [count: string]: unknown;
+}): number;
+/** A long-lived runtime process starts (MB-04, G1). Returns run_id. */
+declare function startProcessRun(m: MachineCore, { role, pid, rev, epoch, parentActionId, startReason }: {
+    role: string;
+    pid?: number;
+    rev?: string;
+    epoch?: number | null;
+    parentActionId?: string | null;
+    startReason?: string;
+}): number;
+declare const heartbeatProcessRun: (m: MachineCore, runId: number, { draining }?: {
+    draining?: boolean | null;
+}) => boolean;
+/** A process run ends, once (trigger process_runs_end_once). exitReason: clean|reload-handover|crash|killed|lost-lease|stopped|unknown. */
+declare function endProcessRun(m: MachineCore, runId: number, { exitCode, exitReason, killedBy }: {
+    exitCode?: number | null;
+    exitReason: string;
+    killedBy?: string | null;
+}): boolean;
+declare const openProcessRuns: (m: Reader, { role }?: {
+    role?: string | null;
+}) => SqlRow[];
+declare const leaderOf: (m: Reader, name?: string) => SqlRow | null;
+/**
+ * Acquire or renew the leader lease (fencing epoch). A fresh/expired lease is taken with a new epoch and a leader_history
+ * row; renewal by the holder keeps the epoch. Returns {leader:boolean, epoch, row}.
+ */
+declare function acquireLeader(m: MachineCore, { name, holder, pid, leaseMs, rev, processRunId, handover }: {
+    name?: string;
+    holder: string;
+    pid?: number;
+    leaseMs: number;
+    rev?: string;
+    processRunId?: number | null;
+    handover?: boolean;
+}): {
+    leader: boolean;
+    epoch: any;
+    renewed: boolean;
+    holder?: never;
+    pid?: never;
+} | {
+    leader: boolean;
+    epoch: any;
+    holder: any;
+    pid: any;
+    renewed?: never;
+};
+/** Renew only if still the holder at `epoch` (fence). Also records pass stats. */
+declare function renewLeader(m: MachineCore, { name, epoch, leaseMs, passes, lastPassMs, lastError, draining }: {
+    name?: string;
+    epoch: number;
+    leaseMs: number;
+    passes?: number | null;
+    lastPassMs?: number | null;
+    lastError?: string | null | undefined;
+    draining?: boolean | null;
+}): boolean;
+/** Release the lease held at `epoch`; closes its leader_history row with the reason (reload|lost|killed|stop|crash). */
+declare function releaseLeader(m: MachineCore, { name, epoch, reason }: {
+    name?: string;
+    epoch: number;
+    reason?: string;
+}): boolean;
+declare const cursorOf: (m: Reader, ledgerId: string) => any;
+declare const setCursor: (m: MachineCore, ledgerId: string, lastSeq: number) => SqlRunResult;
+declare const cursors: (m: Reader) => SqlRow[];
+declare function enqueue(m: MachineCore, { controller, key, dueAt, reason }: {
+    controller: string;
+    key: string;
+    dueAt?: number;
+    reason?: string | null;
+}): SqlRunResult;
+declare const requeue: (m: MachineCore, { controller, key, dueAt, error }: {
+    controller: string;
+    key: string;
+    dueAt: number;
+    error?: string | null;
+}) => boolean;
+/** MB-01: the schedule row of a periodic duty; created with next_due_at = now + interval when absent (never "first run now"). */
+declare function ensureSchedule(m: MachineCore, { controller, duty, intervalMs, firstDueAt }: {
+    controller: string;
+    duty: string;
+    intervalMs: number;
+    firstDueAt?: number | null;
+}): SqlRow | undefined;
+/** Claim a due duty (no overlap): true when this caller should run it now. */
+/**
+ * Claim a due duty (no overlap): true when this caller should run it now. A claim whose holder process is dead, or that
+ * is older than `ttlMs` (default: the interval, at least 1 h), is released first, so a crashed run never blocks the duty.
+ */
+declare function claimSchedule(m: MachineCore, { controller, duty, actionId, pid, ttlMs, alive }: {
+    controller: string;
+    duty: string;
+    actionId?: string | null;
+    pid?: number;
+    ttlMs?: number | null;
+    alive?: (pid: number) => boolean;
+}): boolean;
+declare function finishSchedule(m: MachineCore, { controller, duty, result, digest, nextDueAt }: {
+    controller: string;
+    duty: string;
+    result?: string;
+    digest?: string | null;
+    nextDueAt?: number | null;
+}): boolean;
+declare const schedules: (m: Reader) => SqlRow[];
+/** Record an action intent (idempotent on id). */
+declare function actionIntent(m: MachineCore, { id, controller, duty, key, verb, argvDigest, epoch, observedGeneration, spanId, traceId, mode, ledgerId, workflowId, jobId, attemptId }: {
+    id?: string | null;
+    controller: string;
+    duty?: string | null;
+    key?: string | null;
+    verb?: string | null;
+    argvDigest?: string | null;
+    epoch?: number | null;
+    observedGeneration?: number | null;
+    spanId?: string;
+    traceId?: string | null;
+    mode?: string | null;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    jobId?: string | null;
+    attemptId?: number | string | null;
+}): string;
+declare const actionRunning: (m: MachineCore, id: string, { requestId, childRunId }?: {
+    requestId?: string | null;
+    childRunId?: number | string | null;
+}) => boolean;
+/**
+ * Finish an action (MB-03): `result` is kept IN FULL as a blob (result_sha); result_json holds only a ≤8 KiB summary.
+ * stdout/stderr are stored in full as blobs.
+ */
+declare function actionFinish(m: MachineCore, id: string, { state, exitCode, result: rawResult, summary: rawSummary, stdout, stderr, errorSignature }: {
+    state?: string;
+    exitCode?: number | null;
+    result?: unknown;
+    summary?: unknown;
+    stdout?: unknown;
+    stderr?: unknown;
+    errorSignature?: string | null;
+}): boolean;
+declare const actionOf: (m: MachineCore, id: string) => {
+    result: unknown;
+} | null;
+declare function actions(m: MachineCore, { controller, state, sinceMs, limit }?: {
+    controller?: string | null;
+    state?: string | null;
+    sinceMs?: number | null;
+    limit?: number;
+}): {
+    result: unknown;
+}[];
+declare function actionStep(m: MachineCore, actionId: string, { step, ms, ok, detail }: {
+    step: string;
+    ms?: number | null;
+    ok?: boolean | null;
+    detail?: unknown;
+}): number;
+declare const controllerModes: (m: Reader) => Record<string, string>;
+/** Change a controller mode: a mode_changes row first (who and why, G6), then controller_modes (trigger enforces the order). */
+declare function setControllerMode(m: MachineCore, { controller, mode, by, reason }: {
+    controller: string;
+    mode: string;
+    by: string;
+    reason: string;
+}): {
+    changed: boolean;
+    mode: string;
+    from?: never;
+} | {
+    changed: boolean;
+    from: any;
+    mode: string;
+};
+/** Open an SLA episode for (entity,state) unless one is open (G3). Returns the episode id. */
+declare function openSlaEpisode(m: MachineCore, { entity, state, code, severity, ledgerId, workflowId, slaMs, enteredAt }: {
+    entity: string;
+    state: string;
+    code: string;
+    severity?: string;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    slaMs: number;
+    enteredAt?: number;
+}): number;
+declare const markSlaViolated: (m: MachineCore, episodeId: number) => boolean;
+declare const markSlaReported: (m: MachineCore, episodeId: number, { diId }?: {
+    diId?: string | null;
+}) => boolean;
+declare function clearSla(m: MachineCore, { entity, state, reason }: {
+    entity: string;
+    state?: string | null;
+    reason?: string;
+}): number;
+declare function recordViolation(m: MachineCore, { code, severity, entity, ledgerId, workflowId, episodeId, diId, lessonId, detail }: {
+    code: string;
+    severity?: string;
+    entity: string;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    episodeId?: number | null;
+    diId?: string | null;
+    lessonId?: string | null;
+    detail?: unknown;
+}): number;
+/** Set a service's state; a change appends service_events (G5). */
+declare function setService(m: MachineCore, { name, kind, state, pid, port, url, probe, quarantinedUntil, action, actionId, probeMs, probeError }: {
+    name: string;
+    kind: string;
+    state: string;
+    pid?: number | null;
+    port?: number | null;
+    url?: string | null;
+    probe?: unknown;
+    quarantinedUntil?: number | null;
+    action?: string | null;
+    actionId?: string | null;
+    probeMs?: number | null;
+    probeError?: string | null;
+}): {
+    changed: boolean;
+    from: any;
+};
+declare const recordProbe: (m: MachineCore, { name, ok, latencyMs, detail }: {
+    name: string;
+    ok: boolean;
+    latencyMs?: number | null;
+    detail?: unknown;
+}) => SqlRunResult;
+declare const services: (m: Reader) => {
+    lastProbe: unknown;
+}[];
+declare const upsertSeat: (m: MachineCore, seat: Fields) => SqlRunResult;
+declare const seatOf: (m: Reader, seatId: string) => {
+    detail: unknown;
+} | null;
+declare const seats: (m: Reader) => SqlRow[];
+/** One delivery attempt to a seat (G11, MB-02); the trigger counts consecutive input failures on the seat. */
+declare function recordDelivery(m: MachineCore, { messageKind, messageRef, ledgerId, seatId, terminalHandle, channel, outcome, turnId, detail }: {
+    messageKind: string;
+    messageRef: unknown;
+    ledgerId?: string | null;
+    seatId?: string | null;
+    terminalHandle?: string | null;
+    channel: string;
+    outcome: string;
+    turnId?: number | null;
+    detail?: unknown;
+}): number;
+/**
+ * MB-05: count one wake of a seat. The outcome becomes a deliveries row; the deliveries trigger keeps
+ * seats.input_failures_consecutive / _total (a refused input adds one, a delivered one resets). A seat whose
+ * terminal changed starts from zero. Returns {failures, since, replace} with replace at `max` in a row.
+ */
+declare function recordSeatInput(m: MachineCore, { seatId, terminal, action, messageKind, messageRef, channel, role, max, detail }: {
+    seatId: string;
+    terminal?: string | null;
+    action: string;
+    messageKind?: string;
+    messageRef?: string;
+    channel?: string;
+    role?: string;
+    max?: number;
+    detail?: string | null;
+}): {
+    failures: number;
+    since: any;
+    replace: boolean;
+};
+declare function seatTranscriptSnapshot(m: MachineCore, { seatId, terminalHandle, text }: {
+    seatId: string;
+    terminalHandle?: string | null;
+    text: unknown;
+}): string;
+declare const upsertTerminal: (m: MachineCore, terminal: Fields) => SqlRunResult;
+declare const closeTerminal: (m: MachineCore, handle: string, { by, verified }?: {
+    by?: string | null;
+    verified?: boolean;
+}) => boolean;
+/**
+ * Take a host lock (replaces connectors/*.lock and *.starting.json): succeeds when free, released, expired, or already
+ * ours. Returns {ok, holder?}.
+ */
+declare function acquireHostLock(m: MachineCore, { name, holder, pid, ttlMs, processRunId, state, retainExpired }: {
+    name: string;
+    holder?: string | null;
+    pid?: number;
+    ttlMs?: number;
+    processRunId?: number | null;
+    state?: string;
+    retainExpired?: boolean;
+}): {
+    ok: boolean;
+    holder: SqlRow;
+} | {
+    ok: boolean;
+    holder?: never;
+};
+declare const renewHostLock: (m: MachineCore, { name, pid, ttlMs, state }: {
+    name: string;
+    pid?: number;
+    ttlMs?: number;
+    state?: string | undefined;
+}) => boolean;
+declare const releaseHostLock: (m: MachineCore, { name, pid, force }: {
+    name: string;
+    pid?: number;
+    force?: boolean;
+}) => boolean;
+declare const hostLock: (m: Reader, name: string) => SqlRow | null;
+declare function claimResource(m: MachineCore, { resourcePath, kind, ownerActionId, ownerPid, ownerRunId, hasJunctions }: {
+    resourcePath: string;
+    kind: string;
+    ownerActionId?: string | null;
+    ownerPid?: number;
+    ownerRunId?: number | null;
+    hasJunctions?: boolean;
+}): number;
+declare const releaseClaim: (m: MachineCore, claimId: number) => boolean;
+declare const throttleState: (m: Reader) => {
+    slotTargets: unknown;
+    priorities: unknown;
+} | null;
+/** Write the current throttle row (MB-15: writer + rev). A mode change appends throttle_events first (G7). */
+declare function setThrottle(m: MachineCore, { mode, effectiveCap, heavyCap, running, freeRamPct, freeRamMb, cpuPct, cpuHot, reason, writer, writerRev, slotTargets, priorities, sample }: {
+    mode: string;
+    effectiveCap?: number | null;
+    heavyCap?: number | null;
+    running?: number | null;
+    freeRamPct?: number | null;
+    freeRamMb?: number | null;
+    cpuPct?: number | null;
+    cpuHot?: boolean | number | null;
+    reason?: string | null;
+    writer: string;
+    writerRev?: string;
+    slotTargets?: unknown;
+    priorities?: unknown;
+    sample?: unknown;
+}): {
+    changed: boolean;
+    refused: string;
+    from: any;
+} | {
+    changed: boolean;
+    from: any;
+    refused?: never;
+};
+declare const recordThrottleDecision: (m: MachineCore, { ledgerId, workflowId, jobId, reason, waitedMs }: {
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    jobId?: string | null;
+    reason: string;
+    waitedMs?: number | null;
+}) => number;
+declare const releaseThrottleDecision: (m: MachineCore, seq: number) => boolean;
+declare const recordHostSample: (m: MachineCore, sample: Fields) => number;
+declare function setProviderHealth(m: MachineCore, { provider, status, failureKind, strikes, strikeLimit, circuitOpenUntil, reason, ledgerId, attemptId, detail }: {
+    provider: string;
+    status: string;
+    failureKind?: string | null;
+    strikes?: number;
+    strikeLimit?: number | null;
+    circuitOpenUntil?: number | null;
+    reason?: string | null;
+    ledgerId?: string | null;
+    attemptId?: string | null;
+    detail?: unknown;
+}): {
+    changed: boolean;
+};
+declare const providerHealth: (m: Reader) => SqlRow[];
+declare const poolBackoff: (m: Reader, pool?: string | null) => SqlRow | SqlRow[] | null;
+declare const setPoolBackoff: (m: MachineCore, { pool, untilAt, strikes, reason }: {
+    pool: string;
+    untilAt?: number | null;
+    strikes?: number;
+    reason?: string | null;
+}) => SqlRunResult;
+declare const clearPoolBackoff: (m: MachineCore, pool: string) => boolean;
+declare const setQuota: (m: MachineCore, { provider, window, used, limitValue, resetAt, source }: {
+    provider: string;
+    window: string;
+    used?: number | null;
+    limitValue?: number | null;
+    resetAt?: number | null;
+    source?: string | null;
+}) => SqlRunResult;
+declare const quotas: (m: Reader) => SqlRow[];
+declare const reserveProvider: (m: import("./sqlite-types.mjs").StoreHandle, { provider, account, attemptId, role, model, maxParallel, scope, quota, estimate, override }?: import("./provider-reservations.mjs").ReserveOptions) => {
+    ok: boolean;
+    reason: string;
+    reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+    reused?: never;
+    running?: never;
+    maxParallel?: never;
+} | {
+    ok: boolean;
+    reason: string;
+    reused: boolean;
+    reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+    running?: never;
+    maxParallel?: never;
+} | {
+    ok: boolean;
+    reason: string;
+    running: number;
+    maxParallel: number;
+    reservation?: never;
+    reused?: never;
+}, providerReservations: (m: import("./sqlite-types.mjs").StoreHandle, { provider, account, activeOnly, tier, limit }?: import("./provider-reservations.mjs").ReservationFilter) => import("./provider-reservations.mjs").ProviderReservation[], providerReservationUsage: (m: import("./sqlite-types.mjs").StoreHandle, { provider, account }?: {
+    provider?: string | null | undefined;
+    account?: string;
+}) => {
+    running: number;
+    reservations: import("./provider-reservations.mjs").ProviderReservation[];
+    observed: true;
+}, markProviderReservation: (m: import("./sqlite-types.mjs").StoreHandle, { id, fence, attemptId, provider, account, model, role, state, launchIdentity, hostRequestId, handle, pid }?: import("./provider-reservations.mjs").MarkOptions) => {
+    ok: boolean;
+    reason: string;
+    reservation?: never;
+} | {
+    ok: boolean;
+    reason: string;
+    reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+} | {
+    ok: boolean;
+    reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+    reason?: never;
+}, releaseProviderReservation: (m: import("./sqlite-types.mjs").StoreHandle, { id, fence, attemptId, proof }?: import("./provider-reservations.mjs").ReservationKey & {
+    proof?: import("./provider-reservations.mjs").ReservationProof | null;
+}) => {
+    ok: boolean;
+    reason: string;
+    reused?: never;
+    reservation?: never;
+} | {
+    ok: boolean;
+    reused: boolean;
+    reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+    reason?: never;
+} | {
+    ok: boolean;
+    reason: string;
+    reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+    reused?: never;
+};
+/** Host leases (the machine side of a ledger's two-phase reserve): drop by token. */
+declare function releaseHostLeases(m: MachineCore, tokens: unknown): {
+    ok: true;
+    released: number;
+};
+declare const setBudget: (m: MachineCore, { scopeKey, limitValue, window }: {
+    scopeKey: string;
+    limitValue: number;
+    window?: string | null;
+}) => SqlRunResult;
+/** Reserve units against a budget; refuses when used+reserved+units > limit. */
+declare function reserveBudget(m: MachineCore, { scopeKey, ledgerId, jobId, units }: {
+    scopeKey: string;
+    ledgerId: string;
+    jobId: string;
+    units: number;
+}): {
+    ok: boolean;
+    reason: string;
+    already?: never;
+    budget?: never;
+} | {
+    ok: boolean;
+    already: boolean;
+    reason?: never;
+    budget?: never;
+} | {
+    ok: boolean;
+    reason: string;
+    budget: SqlRow;
+    already?: never;
+} | {
+    ok: boolean;
+    reason?: never;
+    already?: never;
+    budget?: never;
+};
+/** Settle a reservation: `used` units move to used_value, the rest is returned. */
+declare function settleBudget(m: MachineCore, { scopeKey, ledgerId, jobId, used }: {
+    scopeKey: string;
+    ledgerId: string;
+    jobId: string;
+    used?: number | null;
+}): boolean;
+declare const budgets: (m: Reader) => SqlRow[];
+declare const startGcRun: (m: MachineCore, { trigger, actionId, collectors, startedAt }?: {
+    trigger?: string;
+    actionId?: string | null;
+    collectors?: unknown;
+    startedAt?: number;
+}) => number;
+/** Finish a GC run; the full report is a blob (G4). */
+declare function finishGcRun(m: MachineCore, runId: number, { freedBytes, counts, errors, report, finishedAt }?: {
+    freedBytes?: number | null;
+    counts?: unknown;
+    errors?: unknown;
+    report?: unknown;
+    finishedAt?: number;
+}): boolean;
+/** One thing GC touched (G4, MB-14). `outcome` is the final fate; a retry sets nextTryAt past the grace window. */
+declare const recordGcItem: (m: MachineCore, item: Fields) => number;
+declare function gcMark(m: MachineCore, runId: number, entries: Array<{
+    sha256: string;
+    source: string;
+    pinned?: boolean;
+}>): number;
+declare const gcRuns: (m: Reader, { limit }?: {
+    limit?: number;
+}) => SqlRow[];
+declare function upsertLane(m: MachineCore, { name, worktreePath, branch, baseSha, headSha, owner, supJobId, state }: {
+    name: string;
+    worktreePath: string;
+    branch: string;
+    baseSha?: string | null;
+    headSha?: string | null;
+    owner: string;
+    supJobId?: string | null;
+    state?: string;
+}): SqlRunResult;
+declare function setLaneState(m: MachineCore, name: string, state: string, { reportText, headSha }?: {
+    reportText?: string | null;
+    headSha?: string | null;
+}): boolean;
+declare const laneOf: (m: Reader, name: string) => SqlRow | null;
+declare const lanes: (m: Reader, { state }?: {
+    state?: string | null;
+}) => SqlRow[];
+/** Enqueue a land ticket (replaces the land queue dirs). The lane row is created when absent (FK). */
+declare function enqueueLand(m: MachineCore, { ticketId, lane, commitSha, commits, requestedBy }: {
+    ticketId?: string;
+    lane?: string | null;
+    commitSha: string;
+    commits?: unknown;
+    requestedBy?: string;
+}): string;
+/** The head of the queue enters the gate when nothing is running. Returns the ticket, or {busy: running ticket}. */
+/** requested_by 'pid:<n>' names the process that waits for and then runs the ticket. */
+declare function claimLandGate(m: MachineCore, { ticketId, alive }: {
+    ticketId: string;
+    alive?: (pid: number) => boolean;
+}): {
+    ok: boolean;
+    busy: SqlRow;
+    behind?: never;
+    ticket?: never;
+} | {
+    ok: boolean;
+    behind: any;
+    busy?: never;
+    ticket?: never;
+} | {
+    ok: boolean;
+    ticket: SqlRow | undefined;
+    busy?: never;
+    behind?: never;
+};
+declare const finishLandTicket: (m: MachineCore, ticketId: string, state: string) => boolean;
+declare const landQueue: (m: Reader, { open }?: {
+    open?: boolean;
+}) => SqlRow[];
+/** One land-gate run with full stdout/stderr blobs. */
+declare function recordLandRun(m: MachineCore, { ticketId, lane, spanId, parentSpanId, commitSha, commits, landedSha, result, reason, pushId, specs, stdout, stderr, startedAt, finishedAt }: LandRunInput): number;
+/**
+ * The core record of one land in ONE transaction, idempotent on spanId (a replay from the outbox or a second try never
+ * doubles it): the lane row when absent, the push row, the land_runs row, the lane head and the log line (its data gets
+ * runId). {runId, pushId, duplicate}.
+ */
+declare function recordLandOutcome(m: MachineCore, { spanId, lane, push, run, laneHead, log: logRow }: {
+    spanId: string;
+    lane?: string | null;
+    push?: PushInput | null;
+    run: LandRunInput;
+    laneHead?: string | null;
+    log?: (LogRow & {
+        data?: Record<string, unknown>;
+    }) | null;
+}): {
+    runId: number;
+    pushId: number | null;
+    duplicate: boolean;
+};
+declare const landRuns: (m: Reader, { lane, limit }?: {
+    lane?: string | null;
+    limit?: number;
+}) => SqlRow[];
+/** One push (G8, MB-03): a refusal needs a stable failure signature; logs are full blobs. */
+declare function recordPush(m: MachineCore, { repoRoot, branch, head, fromSha, toSha, result, reason, failureSignature, ms, actionId, scan, stdout, stderr }: PushInput): number;
+declare const pushes: (m: Reader, { repoRoot, limit }?: {
+    repoRoot?: string | null;
+    limit?: number;
+}) => SqlRow[];
+declare const removedWorktree: (m: MachineCore, wtPath: string, { error, archivedRef }?: {
+    error?: string | null;
+    archivedRef?: string | null;
+}) => boolean;
+/**
+ * The worktree registry (scripts/machine/worktree-registry.mjs and the worktree api files are its callers): reserve a row for a worktree about to be created,
+ * atomically against the per-repo cap. BEGIN IMMEDIATE: two dispatches never both take the last slot. `cap` null: no cap.
+ * {ok, live} | {ok:false, reason:'worktree-cap', live, cap}
+ */
+declare function reserveWorktree(m: MachineCore, wt: Fields & {
+    path: string;
+    repoRoot: string;
+}, { cap }?: {
+    cap?: number | null;
+}): {
+    ok: boolean;
+    reason: string;
+    live: number;
+    cap: number;
+} | {
+    ok: boolean;
+    live: number;
+    reason?: never;
+    cap?: never;
+};
+/** Live (not removed) registry rows, optionally of one repo. */
+declare const liveWorktrees: (m: Reader, { repoRoot }?: {
+    repoRoot?: string | null;
+}) => SqlRow[];
+declare const worktreeRow: (m: Reader, wtPath: string) => SqlRow | null;
+/** Every repo the registry ever held a worktree of. */
+declare const worktreeRepos: (m: Reader) => string[];
+/** A reservation whose `git worktree add` failed: the row goes, nothing was created. */
+/** A GC collector's resume point (machine_meta gc_cursor:<name>): where its last bounded pass stopped, or null. */
+declare const gcCursor: (m: Reader, name: string) => any;
+declare const setGcCursor: (m: MachineCore, name: string, value: unknown) => boolean;
+/** The worktree GC's stop mark (a removal changed the main checkout): {at, damage, path} or null. set(null) clears it. */
+declare const worktreeGcStop: (m: Reader) => unknown;
+declare const setWorktreeGcStop: (m: MachineCore, stop: unknown) => boolean;
+declare const dropWorktree: (m: MachineCore, wtPath: string) => boolean;
+declare const upsertEnvServer: (m: MachineCore, server: Fields) => SqlRunResult;
+declare const envServer: (m: Reader, serverId: string) => SqlRow | null;
+declare const envServers: (m: Reader, { live }?: {
+    live?: boolean;
+}) => SqlRow[];
+declare const upsertUatSlot: (m: MachineCore, slot: Fields) => SqlRunResult;
+declare const releaseUatSlot: (m: MachineCore, slotId: string) => boolean;
+declare const connectorOf: (m: Reader, name: string) => {
+    config: unknown;
+    cursor: unknown;
+} | null;
+declare const upsertAsk: (m: MachineCore, ask: Fields) => SqlRunResult;
+/**
+ * Append machine_logs rows ({actor, kind, msg, level?, controller?, ledgerId?, workflowId?, jobId?, attemptId?, actionId?,
+ * traceId?, spanId?, data?, refs?, src?, at?}). `src` is a unique idempotency key (a duplicate is skipped). data larger than
+ * 64 KiB goes to a blob. Returns the number written.
+ */
+declare function log(m: MachineCore, rows: LogRow | null | undefined | ReadonlyArray<LogRow | null | undefined>): number;
+declare function logs(m: Reader, { actor, kind, level, ledgerId, workflowId, jobId, since, search, limit }?: {
+    actor?: string | null;
+    kind?: string | null;
+    level?: string | null;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    jobId?: string | null;
+    since?: number | null;
+    search?: string | null;
+    limit?: number;
+}): {
+    data: unknown;
+    refs: unknown;
+}[];
+/** Retention (DBTREE B6): debug rows older than 14 days, the rest older than 90 days. Returns rows deleted. */
+declare function pruneLogs(m: MachineCore, { debugMs, restMs }?: {
+    debugMs?: number;
+    restMs?: number;
+}): number;
+declare function recordMetrics(m: MachineCore, { kind, ledgerId, workflowId, windowMs, subject, data }: {
+    kind: string;
+    ledgerId?: string | null;
+    workflowId?: string | null;
+    windowMs?: number | null;
+    subject?: string | null;
+    data: unknown;
+}): number;
+/** A notification, deduplicated on dedupeKey (replaces telegram-sent.json). Returns {id, duplicate}. */
+declare function recordNotification(m: MachineCore, { channel, kind, text, media, mediaType, sentAt, delivery, ref, dedupeKey }: {
+    channel: string;
+    kind: string;
+    text: string;
+    media?: unknown;
+    mediaType?: string;
+    sentAt?: number | null;
+    delivery?: string | null;
+    ref?: string | null;
+    dedupeKey?: string | null;
+}): {
+    id: number;
+    duplicate: boolean;
+};
+declare function projectCatalog(m: MachineCore, { agents, models, sourceRev }: {
+    agents?: Array<{
+        agent: string;
+        provider?: string | null;
+        spawnCard?: string | null;
+        cliName?: string | null;
+    }>;
+    models?: Array<{
+        profile: string;
+        agent?: string | null;
+        model?: string | null;
+        pool?: string | null;
+        maxParallel?: number | null;
+        roles?: unknown;
+        cost?: unknown;
+    }>;
+    sourceRev?: string;
+}): {
+    agents: number;
+    models: number;
+};
+/**
+ * The ONE checkpoint of machine.sqlite: PASSIVE, on the checkpointer handle (openMachine({checkpointer:true}), the engine),
+ * and only while the engine_leader row `name` still names `holder` at `epoch` with a live lease. A standby, a draining or a
+ * superseded engine gets {skipped} and checkpoints nothing, so two engines never checkpoint back to back (WAL-reset bug).
+ * Returns {busy, log, checkpointed} or {skipped: reason}.
+ */
+declare function checkpoint(m: MachineCore, { name, holder, epoch }?: {
+    name?: string;
+    holder?: string;
+    epoch?: number | string;
+}): SqlRow | undefined;
+/** machine_meta as an object. */
+declare const meta: (m: Reader) => Record<string, string>;
+/** withMachine(API[op](m, ...args)); when the store refuses it, the write goes to the outbox. {ok, value} | {ok:false, deferred, error}. */
+export declare function writeOrDefer(op: string, args?: unknown[], { env, file }?: {
+    env?: Env;
+    file?: string | null;
+}): {
+    ok: boolean;
+    value: unknown;
+    deferred?: never;
+    error?: never;
+} | {
+    ok: boolean;
+    deferred: string;
+    error: string;
+    value?: never;
+};
+/**
+ * Apply every outbox line through its typed writer (each in its own transaction). A line that fails again goes back to
+ * the outbox; a claimed file of a dead flusher is taken over. {flushed, failed, pending}.
+ */
+declare function flushOutbox(m: MachineCore): {
+    flushed: number;
+    failed: number;
+    pending: string;
+    busy: string;
+} | {
+    flushed: number;
+    failed: number;
+    pending: string | null;
+    busy?: never;
+};
+declare const API: {
+    insert: (m: MachineCore, table: string, row: Fields, opts?: {
+        orIgnore?: boolean;
+    }) => SqlRunResult;
+    upsert: (m: MachineCore, table: string, row: Fields, keys: readonly string[]) => SqlRunResult;
+    update: (m: MachineCore, table: string, set: Fields, where: Fields) => SqlRunResult;
+    putMachineBlob: typeof putMachineBlob;
+    jsonOrBlob: typeof jsonOrBlob;
+    meta: (m: Reader) => Record<string, string>;
+    checkpoint: typeof checkpoint;
+    registerLedger: typeof registerLedger;
+    resolveLedger: typeof resolveLedger;
+    listLedgers: typeof listLedgers;
+    touchLedger: typeof touchLedger;
+    setLedgerState: typeof setLedgerState;
+    upsertRepository: typeof upsertRepository;
+    forEachLedger: typeof forEachLedger;
+    attachLedgers: typeof attachLedgers;
+    supEvent: typeof supEvent;
+    supEvents: typeof supEvents;
+    newestSupEvent: (m: Reader, kind: string) => {
+        payload: unknown;
+    } | null;
+    upsertSupJob: typeof upsertSupJob;
+    setSupJobStatus: typeof setSupJobStatus;
+    supJob: (m: Reader, jobId: string) => {
+        files: unknown;
+        payload: unknown;
+    } | null;
+    listSupJobs: typeof listSupJobs;
+    acquireSupLeases: typeof acquireSupLeases;
+    releaseSupLeases: (m: MachineCore, jobId: string) => number;
+    supLeases: (m: Reader) => SqlRow[];
+    startSupAttempt: typeof startSupAttempt;
+    updateSupAttempt: (m: MachineCore, attemptId: number, fields: Fields) => boolean;
+    latestSupAttempt: (m: Reader, jobId: string) => SqlRow | null;
+    recordSupReport: typeof recordSupReport;
+    supReports: (m: Reader, { jobId, unconsumed }?: {
+        jobId?: string | null;
+        unconsumed?: boolean;
+    }) => {
+        report: unknown;
+    }[];
+    consumeSupReport: (m: MachineCore, reportId: number) => boolean;
+    openSupDecision: typeof openSupDecision;
+    setSupDecision: typeof setSupDecision;
+    markSupDecisionDelivered: (m: MachineCore, diId: string) => boolean;
+    listSupDecisions: typeof listSupDecisions;
+    openOwed: typeof openOwed;
+    ackOwed: (m: MachineCore, owedId: string, { by }?: {
+        by?: string;
+    }) => boolean;
+    closeOwed: (m: MachineCore, owedId: string) => boolean;
+    listOwed: (m: Reader, { open }?: {
+        open?: boolean;
+    }) => {
+        detail: unknown;
+    }[];
+    upsertLearning: typeof upsertLearning;
+    listLearning: (m: Reader, { kind }?: {
+        kind?: string | null;
+    }) => {
+        detail: unknown;
+    }[];
+    recordOwnerRuling: (m: MachineCore, { rulingId, saidAt, channel, verbatim, paraphrase, appliesTo, contractRef, recordedBy }: {
+        rulingId?: string;
+        saidAt: number | string;
+        channel?: string | null;
+        verbatim: string;
+        paraphrase?: string | null;
+        appliesTo?: string | null;
+        contractRef?: string | null;
+        recordedBy?: string | null;
+    }) => string;
+    upsertBridge: typeof upsertBridge;
+    recordSupMessage: typeof recordSupMessage;
+    supMessages: (m: Reader, { direction, unread, limit }?: {
+        direction?: string | null;
+        unread?: boolean;
+        limit?: number;
+    }) => SqlRow[];
+    markSupMessagesRead: (m: MachineCore, ids: Iterable<string>) => number;
+    setSupSignal: typeof setSupSignal;
+    supSignal: (m: Reader, scope: string, key?: string) => {
+        value: unknown;
+    } | null;
+    clearSupSignal: (m: MachineCore, scope: string, key?: string) => boolean;
+    recordMachineLlmUsage: typeof recordMachineLlmUsage;
+    startProcessRun: typeof startProcessRun;
+    heartbeatProcessRun: (m: MachineCore, runId: number, { draining }?: {
+        draining?: boolean | null;
+    }) => boolean;
+    endProcessRun: typeof endProcessRun;
+    openProcessRuns: (m: Reader, { role }?: {
+        role?: string | null;
+    }) => SqlRow[];
+    processRuns: (m: MachineCore, { role, sinceMs, limit }?: {
+        role?: string | null;
+        sinceMs?: number | null;
+        limit?: number;
+    }) => SqlRow[];
+    leaderOf: (m: Reader, name?: string) => SqlRow | null;
+    acquireLeader: typeof acquireLeader;
+    renewLeader: typeof renewLeader;
+    releaseLeader: typeof releaseLeader;
+    leaderHistory: (m: Reader, { limit }?: {
+        limit?: number;
+    }) => SqlRow[];
+    cursorOf: (m: Reader, ledgerId: string) => any;
+    setCursor: (m: MachineCore, ledgerId: string, lastSeq: number) => SqlRunResult;
+    cursors: (m: Reader) => SqlRow[];
+    enqueue: typeof enqueue;
+    dueQueue: (m: MachineCore, { controller, limit }?: {
+        controller?: string | null;
+        limit?: number;
+    }) => SqlRow[];
+    queueRows: (m: Reader) => SqlRow[];
+    dequeue: (m: MachineCore, controller: string, key: string) => boolean;
+    requeue: (m: MachineCore, { controller, key, dueAt, error }: {
+        controller: string;
+        key: string;
+        dueAt: number;
+        error?: string | null;
+    }) => boolean;
+    ensureSchedule: typeof ensureSchedule;
+    claimSchedule: typeof claimSchedule;
+    finishSchedule: typeof finishSchedule;
+    schedules: (m: Reader) => SqlRow[];
+    actionIntent: typeof actionIntent;
+    actionRunning: (m: MachineCore, id: string, { requestId, childRunId }?: {
+        requestId?: string | null;
+        childRunId?: number | string | null;
+    }) => boolean;
+    actionFinish: typeof actionFinish;
+    markStaleActionsUnknown: (m: MachineCore, { olderThanMs, exceptEpoch }?: {
+        olderThanMs?: number;
+        exceptEpoch?: number | null;
+    }) => number;
+    actionOf: (m: MachineCore, id: string) => {
+        result: unknown;
+    } | null;
+    actions: typeof actions;
+    actionStep: typeof actionStep;
+    controllerModes: (m: Reader) => Record<string, string>;
+    setControllerMode: typeof setControllerMode;
+    modeChanges: (m: Reader, { limit }?: {
+        limit?: number;
+    }) => SqlRow[];
+    openSlaEpisode: typeof openSlaEpisode;
+    markSlaViolated: (m: MachineCore, episodeId: number) => boolean;
+    markSlaReported: (m: MachineCore, episodeId: number, { diId }?: {
+        diId?: string | null;
+    }) => boolean;
+    clearSla: typeof clearSla;
+    openSla: (m: Reader) => SqlRow[];
+    recordViolation: typeof recordViolation;
+    clearViolation: (m: MachineCore, violationId: number) => boolean;
+    setService: typeof setService;
+    recordProbe: (m: MachineCore, { name, ok, latencyMs, detail }: {
+        name: string;
+        ok: boolean;
+        latencyMs?: number | null;
+        detail?: unknown;
+    }) => SqlRunResult;
+    services: (m: Reader) => {
+        lastProbe: unknown;
+    }[];
+    serviceEvents: (m: MachineCore, { name, sinceMs }?: {
+        name?: string | null;
+        sinceMs?: number;
+    }) => SqlRow[];
+    upsertSeat: (m: MachineCore, seat: Fields) => SqlRunResult;
+    seatOf: (m: Reader, seatId: string) => {
+        detail: unknown;
+    } | null;
+    seats: (m: Reader) => SqlRow[];
+    recordDelivery: typeof recordDelivery;
+    recordSeatInput: typeof recordSeatInput;
+    startSeatTurn: (m: MachineCore, { seatId, wokenByDelivery, spanId }: {
+        seatId: string;
+        wokenByDelivery?: number | null;
+        spanId?: string;
+    }) => number;
+    endSeatTurn: (m: MachineCore, turnId: number, { endReason, actionsCount }?: {
+        endReason?: string;
+        actionsCount?: number | null;
+    }) => boolean;
+    seatTranscriptSnapshot: typeof seatTranscriptSnapshot;
+    upsertTerminal: (m: MachineCore, terminal: Fields) => SqlRunResult;
+    closeTerminal: (m: MachineCore, handle: string, { by, verified }?: {
+        by?: string | null;
+        verified?: boolean;
+    }) => boolean;
+    acquireHostLock: typeof acquireHostLock;
+    renewHostLock: (m: MachineCore, { name, pid, ttlMs, state }: {
+        name: string;
+        pid?: number;
+        ttlMs?: number;
+        state?: string | undefined;
+    }) => boolean;
+    releaseHostLock: (m: MachineCore, { name, pid, force }: {
+        name: string;
+        pid?: number;
+        force?: boolean;
+    }) => boolean;
+    releaseObservedProvisionLock: typeof releaseObservedProvisionLock;
+    renewProvisionLock: typeof renewProvisionLock;
+    releaseProvisionLock: typeof releaseProvisionLock;
+    hostLock: (m: Reader, name: string) => SqlRow | null;
+    hostLocks: (m: Reader) => SqlRow[];
+    claimResource: typeof claimResource;
+    releaseClaim: (m: MachineCore, claimId: number) => boolean;
+    sweptClaim: (m: MachineCore, claimId: number, { error }?: {
+        error?: string | null;
+    }) => boolean;
+    liveClaims: (m: Reader) => SqlRow[];
+    upsertAgentSession: (m: MachineCore, session: Fields) => SqlRunResult;
+    throttleState: (m: Reader) => {
+        slotTargets: unknown;
+        priorities: unknown;
+    } | null;
+    setThrottle: typeof setThrottle;
+    throttleEvents: (m: MachineCore, { sinceMs }?: {
+        sinceMs?: number;
+    }) => SqlRow[];
+    recordThrottleDecision: (m: MachineCore, { ledgerId, workflowId, jobId, reason, waitedMs }: {
+        ledgerId?: string | null;
+        workflowId?: string | null;
+        jobId?: string | null;
+        reason: string;
+        waitedMs?: number | null;
+    }) => number;
+    releaseThrottleDecision: (m: MachineCore, seq: number) => boolean;
+    recordHostSample: (m: MachineCore, sample: Fields) => number;
+    hostSamples: (m: MachineCore, { kind, sinceMs }?: {
+        kind?: string;
+        sinceMs?: number;
+    }) => SqlRow[];
+    setProviderHealth: typeof setProviderHealth;
+    providerHealth: (m: Reader) => SqlRow[];
+    poolBackoff: (m: Reader, pool?: string | null) => SqlRow | SqlRow[] | null;
+    setPoolBackoff: (m: MachineCore, { pool, untilAt, strikes, reason }: {
+        pool: string;
+        untilAt?: number | null;
+        strikes?: number;
+        reason?: string | null;
+    }) => SqlRunResult;
+    clearPoolBackoff: (m: MachineCore, pool: string) => boolean;
+    setQuota: (m: MachineCore, { provider, window, used, limitValue, resetAt, source }: {
+        provider: string;
+        window: string;
+        used?: number | null;
+        limitValue?: number | null;
+        resetAt?: number | null;
+        source?: string | null;
+    }) => SqlRunResult;
+    quotas: (m: Reader) => SqlRow[];
+    reserveProvider: (m: import("./sqlite-types.mjs").StoreHandle, { provider, account, attemptId, role, model, maxParallel, scope, quota, estimate, override }?: import("./provider-reservations.mjs").ReserveOptions) => {
+        ok: boolean;
+        reason: string;
+        reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+        reused?: never;
+        running?: never;
+        maxParallel?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        reused: boolean;
+        reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+        running?: never;
+        maxParallel?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        running: number;
+        maxParallel: number;
+        reservation?: never;
+        reused?: never;
+    };
+    providerReservations: (m: import("./sqlite-types.mjs").StoreHandle, { provider, account, activeOnly, tier, limit }?: import("./provider-reservations.mjs").ReservationFilter) => import("./provider-reservations.mjs").ProviderReservation[];
+    providerReservationUsage: (m: import("./sqlite-types.mjs").StoreHandle, { provider, account }?: {
+        provider?: string | null | undefined;
+        account?: string;
+    }) => {
+        running: number;
+        reservations: import("./provider-reservations.mjs").ProviderReservation[];
+        observed: true;
+    };
+    markProviderReservation: (m: import("./sqlite-types.mjs").StoreHandle, { id, fence, attemptId, provider, account, model, role, state, launchIdentity, hostRequestId, handle, pid }?: import("./provider-reservations.mjs").MarkOptions) => {
+        ok: boolean;
+        reason: string;
+        reservation?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+    } | {
+        ok: boolean;
+        reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+        reason?: never;
+    };
+    releaseProviderReservation: (m: import("./sqlite-types.mjs").StoreHandle, { id, fence, attemptId, proof }?: import("./provider-reservations.mjs").ReservationKey & {
+        proof?: import("./provider-reservations.mjs").ReservationProof | null;
+    }) => {
+        ok: boolean;
+        reason: string;
+        reused?: never;
+        reservation?: never;
+    } | {
+        ok: boolean;
+        reused: boolean;
+        reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+        reason?: never;
+    } | {
+        ok: boolean;
+        reason: string;
+        reservation: import("./provider-reservations.mjs").ProviderReservation | null;
+        reused?: never;
+    };
+    upsertGuardJob: (m: MachineCore, { jobId, ledgerId, workflowId, attemptId, allow, hooks, ttlMs }: {
+        jobId: string;
+        ledgerId?: string | null;
+        workflowId?: string | null;
+        attemptId?: string | null;
+        allow: unknown;
+        hooks?: unknown;
+        ttlMs?: number;
+    }) => SqlRunResult;
+    guardJob: (m: MachineCore, jobId: string) => {
+        allow: unknown;
+        hooks: unknown;
+    } | null;
+    releaseGuardJob: (m: MachineCore, jobId: string) => boolean;
+    recordGuardRefusal: (m: MachineCore, refusal: Fields) => number;
+    releaseHostLeases: typeof releaseHostLeases;
+    release: typeof releaseHostLeases;
+    hostLeases: (m: Reader) => SqlRow[];
+    setBudget: (m: MachineCore, { scopeKey, limitValue, window }: {
+        scopeKey: string;
+        limitValue: number;
+        window?: string | null;
+    }) => SqlRunResult;
+    reserveBudget: typeof reserveBudget;
+    settleBudget: typeof settleBudget;
+    budgets: (m: Reader) => SqlRow[];
+    startGcRun: (m: MachineCore, { trigger, actionId, collectors, startedAt }?: {
+        trigger?: string;
+        actionId?: string | null;
+        collectors?: unknown;
+        startedAt?: number;
+    }) => number;
+    finishGcRun: typeof finishGcRun;
+    recordGcItem: (m: MachineCore, item: Fields) => number;
+    addGcItem: (m: MachineCore, item: Fields) => number;
+    updateGcItem: (m: MachineCore, itemId: number, fields: Fields) => boolean;
+    gcItems: (m: Reader, { runId, open, collector, limit }?: {
+        runId?: number | null;
+        open?: boolean;
+        collector?: string | null;
+        limit?: number;
+    }) => SqlRow[];
+    gcMark: typeof gcMark;
+    addGcMarks: typeof gcMark;
+    gcRuns: (m: Reader, { limit }?: {
+        limit?: number;
+    }) => SqlRow[];
+    markMachineBlobArchived: (m: MachineCore, { sha256: sha, archivedAt, archiveRef }: {
+        sha256: string;
+        archivedAt?: number;
+        archiveRef: string;
+    }) => boolean;
+    pruneSeatSnapshots: (m: MachineCore, { now, seatMs }: {
+        now?: number;
+        seatMs: number;
+    }) => number;
+    upsertLane: typeof upsertLane;
+    setLaneState: typeof setLaneState;
+    laneOf: (m: Reader, name: string) => SqlRow | null;
+    lanes: (m: Reader, { state }?: {
+        state?: string | null;
+    }) => SqlRow[];
+    enqueueLand: typeof enqueueLand;
+    claimLandGate: typeof claimLandGate;
+    finishLandTicket: (m: MachineCore, ticketId: string, state: string) => boolean;
+    landQueue: (m: Reader, { open }?: {
+        open?: boolean;
+    }) => SqlRow[];
+    recordLandRun: typeof recordLandRun;
+    recordLandOutcome: typeof recordLandOutcome;
+    landRuns: (m: Reader, { lane, limit }?: {
+        lane?: string | null;
+        limit?: number;
+    }) => SqlRow[];
+    recordPush: typeof recordPush;
+    pushes: (m: Reader, { repoRoot, limit }?: {
+        repoRoot?: string | null;
+        limit?: number;
+    }) => SqlRow[];
+    flushOutbox: typeof flushOutbox;
+    upsertWorktree: (m: MachineCore, wt: Fields & {
+        path: string;
+    }) => SqlRunResult;
+    removedWorktree: (m: MachineCore, wtPath: string, { error, archivedRef }?: {
+        error?: string | null;
+        archivedRef?: string | null;
+    }) => boolean;
+    reserveWorktree: typeof reserveWorktree;
+    liveWorktrees: (m: Reader, { repoRoot }?: {
+        repoRoot?: string | null;
+    }) => SqlRow[];
+    worktreeRow: (m: Reader, wtPath: string) => SqlRow | null;
+    worktreeRepos: (m: Reader) => string[];
+    dropWorktree: (m: MachineCore, wtPath: string) => boolean;
+    worktreeGcStop: (m: Reader) => unknown;
+    setWorktreeGcStop: (m: MachineCore, stop: unknown) => boolean;
+    gcCursor: (m: Reader, name: string) => any;
+    setGcCursor: (m: MachineCore, name: string, value: unknown) => boolean;
+    upsertEnvServer: (m: MachineCore, server: Fields) => SqlRunResult;
+    envServer: (m: Reader, serverId: string) => SqlRow | null;
+    envServers: (m: Reader, { live }?: {
+        live?: boolean;
+    }) => SqlRow[];
+    upsertUatSlot: (m: MachineCore, slot: Fields) => SqlRunResult;
+    uatSlots: (m: Reader, { live }?: {
+        live?: boolean;
+    }) => SqlRow[];
+    releaseUatSlot: (m: MachineCore, slotId: string) => boolean;
+    upsertConnector: (m: MachineCore, { name, kind, state, pid, port, publicUrl, config, cursor }: {
+        name: string;
+        kind?: string | null;
+        state?: string | null;
+        pid?: number | null;
+        port?: number | null;
+        publicUrl?: string | null;
+        config?: unknown;
+        cursor?: unknown;
+    }) => SqlRunResult;
+    connectorOf: (m: Reader, name: string) => {
+        config: unknown;
+        cursor: unknown;
+    } | null;
+    upsertAsk: (m: MachineCore, ask: Fields) => SqlRunResult;
+    log: typeof log;
+    logs: typeof logs;
+    pruneLogs: typeof pruneLogs;
+    recordMetrics: typeof recordMetrics;
+    latestMetrics: (m: Reader, { kind, ledgerId, workflowId }?: {
+        kind?: string;
+        ledgerId?: string | null;
+        workflowId?: string | null;
+    }) => {
+        data: unknown;
+    } | null;
+    recordNotification: typeof recordNotification;
+    notificationSent: (m: Reader, dedupeKey: string) => boolean;
+    markNotificationSent: (m: MachineCore, id: number, { delivery }?: {
+        delivery?: string;
+    }) => boolean;
+    recordArchive: (m: MachineCore, archive: Fields) => SqlRunResult;
+    projectCatalog: typeof projectCatalog;
+};
+/** Every typed function at module level too: fn(handle, ...args) — blob-gc and callers holding a handle. */
+export { putMachineBlob, meta, checkpoint, registerLedger, resolveLedger, listLedgers, setLedgerState, upsertRepository, forEachLedger, attachLedgers, supEvent, supEvents, newestSupEvent, upsertSupJob, setSupJobStatus, supJob, listSupJobs, acquireSupLeases, releaseSupLeases, startSupAttempt, updateSupAttempt, latestSupAttempt, recordSupReport, supReports, consumeSupReport, openSupDecision, setSupDecision, markSupDecisionDelivered, listSupDecisions, ackOwed, upsertLearning, recordSupMessage, supMessages, setSupSignal, supSignal, recordMachineLlmUsage, startProcessRun, heartbeatProcessRun, endProcessRun, openProcessRuns, leaderOf, acquireLeader, renewLeader, releaseLeader, cursorOf, setCursor, cursors, enqueue, requeue, ensureSchedule, claimSchedule, finishSchedule, schedules, actionIntent, actionRunning, actionFinish, actionOf, actions, controllerModes, setControllerMode, openSlaEpisode, markSlaViolated, markSlaReported, clearSla, recordViolation, setService, recordProbe, services, upsertSeat, seatOf, seats, recordDelivery, recordSeatInput, seatTranscriptSnapshot, upsertTerminal, closeTerminal, acquireHostLock, renewHostLock, releaseHostLock, hostLock, claimResource, releaseClaim, throttleState, setThrottle, recordThrottleDecision, releaseThrottleDecision, recordHostSample, setProviderHealth, providerHealth, poolBackoff, setPoolBackoff, clearPoolBackoff, setQuota, quotas, setBudget, budgets, startGcRun, finishGcRun, recordGcItem, gcRuns, upsertLane, laneOf, lanes, enqueueLand, claimLandGate, finishLandTicket, landQueue, recordLandRun, recordLandOutcome, landRuns, recordPush, pushes, flushOutbox, removedWorktree, reserveWorktree, liveWorktrees, worktreeRow, worktreeRepos, dropWorktree, worktreeGcStop, setWorktreeGcStop, gcCursor, setGcCursor, upsertEnvServer, envServer, envServers, upsertUatSlot, releaseUatSlot, connectorOf, upsertAsk, log, logs, recordMetrics };
+export { reserveProvider, providerReservations, providerReservationUsage, markProviderReservation, releaseProviderReservation };
+/** Best-effort machine log line from anywhere (never throws): opens, appends, closes. */
+export declare function machineLog(row: LogRow, { env }?: {
+    env?: Env;
+}): number;