@parcha/pi-durable-disk 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/place.d.ts

@@ -0,0 +1,236 @@
+import type { Delegation } from "disk";
+import { PdaError } from "./errors.js";
+import { type RunRecord } from "./status.js";
+import { type EnsureOptions, type HostBox, type HostDriver, type SupervisorControl } from "./supervise.js";
+export type PlaceKill = "process" | "box";
+/** The run's paths in the place: its id, its directory, and the `work` and `store` under it. */
+export type PlacePaths = {
+    id: string;
+    root: string;
+    work: string;
+    store: string;
+};
+/**
+ * How the run stood when a runner ended: the instance's own report, or `run.json` as it left it. `status` is the run's
+ * word: `complete` when it delivered, else `failed`. `models`, on any status: the role-to-model ids the run's live parts
+ * chose (`lead`, `eyes`, ...), when the app reported a plain object of strings; absent otherwise, never `{}` in its place.
+ */
+export type PlaceOutcome = {
+    status: string;
+    generation: number | null;
+    code?: string | null;
+    message?: string;
+    record?: unknown;
+    storeSha256?: string;
+    models?: Record<string, string>;
+};
+/** How a runner ended. `exit`: the exit code or signal (local), or the host's status (`stopped`, `failed`, `gone`) or `SIGKILL` when the place killed it (archil). */
+export type PlaceExit = {
+    exit: number | string | null;
+    signal: string | null;
+    outcome?: PlaceOutcome;
+    stderr: string;
+};
+/** One instance of the run in a place. `epoch`: 1 on a plain directory; on a disk, the generation the instance opens. */
+export type PlaceRunner = {
+    epoch: number;
+    pid?: number;
+    exited: Promise<PlaceExit>;
+};
+/** What a runner is handed: its number in the run, its environment, and for a place with a token, the attempt's mount token. */
+export type RunnerOrder = {
+    gen: number;
+    env: Record<string, string>;
+    stdin?: string;
+};
+/** What the place reads of the run, the way it reads it: `run.json`, and on a disk the run's delegations. */
+/**
+ * What the place reads of the run, the way it reads it: `run.json`; on a disk, the run's delegations; and the boxes the
+ * place made for its runners, each as a receipt (`HostBox`: provider, kind, from, to, list price per second and where
+ * that price was read), when its host driver makes boxes. A box the place released stays listed with its end.
+ */
+export type PlaceStatus = {
+    record: RunRecord | null;
+    delegations?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned" | "isPending">[];
+    boxes?: HostBox[];
+};
+/** What a recovery did. A takeover on a disk lists what it revoked, and `ms` is the whole of it (revoke and start). */
+export type PlaceRecovery = {
+    runner: PlaceRunner;
+    restored?: {
+        checkpoint: string;
+        head: number;
+    };
+    replayed?: {
+        from: number;
+        to: number;
+    };
+    revoked?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned">[];
+    ms?: number;
+};
+/**
+ * What a runner announces to its supervisor: a crossing it took, or a request to be killed at one (it parks there until
+ * the kill). `signals-failed` is the place's own last word when it could not read the requests: it ends the iterator,
+ * which never rejects. `code` is the failing read's error code when it has one (CONTROL_API_FAILED for a read that timed
+ * out), else SIGNALS_FAILED.
+ */
+export type PlaceSignal = {
+    kind: "crossing" | "kill-request";
+    crossing: {
+        point: string;
+        n: number;
+        pid?: number;
+        info?: Record<string, unknown>;
+    };
+    /** The attempt's nonce the runner wrote into its request, lifted out of `crossing`: the supervisor honors a kill request only with the nonce it minted for that attempt. */
+    nonce?: string;
+} | {
+    kind: "signals-failed";
+    code: string;
+    message: string;
+};
+/**
+ * What the supervisor hands a place factory: the run's paths as it computed them, how to take the boxes the run made,
+ * and where attempt n's runner writes its kill request (a file of the supervisor's machine).
+ */
+export type PlaceContext = {
+    paths: PlacePaths;
+    self?: string;
+    destroyBoxes?: () => void | Promise<void>;
+    requestFile?: (attempt: number) => string;
+};
+/**
+ * Where an attempt's runner records (its RECORD_DIR, in the place) and how the place brings that recording home. For a
+ * place whose runners cannot write the supervisor's recording directory.
+ */
+export interface PlaceRecordHome {
+    /** The directory, in the place, attempt `attempt`'s runner records into. */
+    dir(attempt: number): string;
+    /**
+     * Brings home into `into` what the runners recorded: blobs first, then the new whole lines of each `.spool/*.jsonl`.
+     * Idempotent; `final` is the call after the runner ended, when nothing is still landing.
+     */
+    bringHome(into: string, options?: {
+        final?: boolean;
+    }): Promise<void>;
+    /** How far the place's clock is from the supervisor's, when it knows. */
+    readonly clockSkewMs?: number;
+}
+export interface Place {
+    /** `local` or `archil`, for the recording's lines. */
+    readonly name: string;
+    readonly paths: PlacePaths;
+    /** A place whose instance opens a claim mints each attempt's mount token: the supervisor passes it as the runner's stdin, never in argv or env. */
+    token?(attempt: number): string | undefined | Promise<string | undefined>;
+    /** What this place can lose. */
+    readonly kills: ReadonlyArray<PlaceKill>;
+    start(order: RunnerOrder): Promise<PlaceRunner>;
+    /**
+     * Where attempt `attempt`'s runner writes its kill request, as a path in the place (the supervisor puts it in the
+     * runner's order). A place with `signals` has it, and `signals(attempt)` reads what is written there.
+     */
+    requestFile?(attempt: number): string;
+    /**
+     * The kill requests (and crossings) attempt `attempt`'s runner announces. The supervisor stops reading with `return()`
+     * once the runner has exited, and `return()` ends a pending `next()`.
+     */
+    signals?(attempt: number): AsyncIterable<PlaceSignal>;
+    /** Takes the runner away abruptly, as a crash would. Safe on a runner that is already gone. */
+    kill(runner: PlaceRunner, kind: PlaceKill): Promise<void>;
+    status?(): Promise<PlaceStatus>;
+    /** Kills `last` if it still runs, then starts the next runner. */
+    recover(last: PlaceRunner, kind: PlaceKill, order: RunnerOrder): Promise<PlaceRecovery>;
+    checkpoint?(): Promise<{
+        taken: boolean;
+        heldBy?: string;
+    }>;
+    move?(to: Place): Promise<Record<string, unknown>>;
+    /** Lets the run go: stops what still runs (its commands too) and removes what the place made for it (tokens), never the run's directory. */
+    release(): Promise<void>;
+    /** A place whose runners record where the supervisor cannot read says where, and brings the recording home. */
+    readonly recordHome?: PlaceRecordHome;
+}
+export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED" | "BOX_GONE" | "CARRY_FAILED" | "BLOB_MISMATCH" | "DIRS_REFUSED";
+export declare class PlaceError extends PdaError {
+    constructor(code: PlaceErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface LocalPlaceOptions {
+    /** The app module `run --app` loads. */
+    app: string;
+    /** The run's directory. Default: the context's `paths.root`. */
+    root?: string;
+    /** The instance program; `run` and its flags are appended. Default: this Node and the package's CLI. */
+    command?: string[];
+    /** Extra flags for `run` (heartbeat periods, a park threshold). */
+    runArgs?: string[];
+}
+/**
+ * The run on a directory of this machine: each runner is `pi-durable-disk run --dir <root> --id <id> --app <app>`, a
+ * child in its own process group, with `{ PATH, ...order.env }` and nothing else of this process's environment. No disk,
+ * no key and no token. A process kill is SIGKILL to the group, and the next runner resumes the run from the directory; a
+ * box kill also takes the boxes the run made (`destroyBoxes`), so `kills` has `box` only when the context gives that.
+ * A runner's outcome is the instance's `{"outcome":...}` line on stdout, or, without one, `run.json` as it left it.
+ */
+export declare function localPlace(options: LocalPlaceOptions): (ctx: PlaceContext) => Place;
+export interface ArchilPlaceOptions {
+    disk: string;
+    region: string;
+    /**
+     * The disk's control API (`archilControl`). The place holds it; no instance ever does. With `listObjects` (as
+     * `archilControl` has), the place has `recordHome`.
+     */
+    control: SupervisorControl & Partial<RecordControl>;
+    /**
+     * The driver that runs the instance (`localHost`, `dockerHost`, `daytonaHost`), set up with the app the instance runs.
+     * Its `kill` and `kills` are the place's.
+     */
+    host: HostDriver;
+    /** The run's id on the disk. Default: the context's `paths.id`. */
+    id?: string;
+    /** Where the driver mounts runs, for `paths`. Default: the driver's `mountRoot`, else /mnt/archil. */
+    mountRoot?: string;
+    /** More for each start's `ensureRunning`: the run directory's owner (`create`), token prefix and TTL, timeouts. */
+    ensure?: Omit<EnsureOptions, "control" | "demand" | "mountToken">;
+    /** How often a runner's host status is read. Default 1 s. */
+    pollMs?: number;
+    /** How long a start waits on a mount another start has in flight. Default 60 s. */
+    startTimeoutMs?: number;
+    /** How often `signals` reads the attempt's kill request over S3. Default 500 ms (the runner waits at its crossing). */
+    signalPollMs?: number;
+    /**
+     * How long those reads may fail (anything but a missing object) without a break before the iterator yields one
+     * `signals-failed` and ends. Default 60 s.
+     */
+    signalFailMs?: number;
+}
+/** The listing `recordHome` reads the run's recordings with: S3 ListObjects, each object's size when the API gives it. */
+export interface RecordControl {
+    listObjects(prefix: string, options?: {
+        recursive?: boolean;
+    }): Promise<{
+        objects: {
+            key: string;
+            size?: number;
+        }[];
+    }>;
+}
+/**
+ * Every byte of `bytes` to `fd`: a write may take fewer bytes than it was given, so it goes on from where the last one
+ * stopped. A write that takes none fails, as one that throws (a full disk) does.
+ */
+export declare function writeAll(fd: number, bytes: Uint8Array, write?: (fd: number, bytes: Uint8Array, offset: number, length: number) => number): void;
+/**
+ * The run on an Archil disk, its instance run by a host driver. `token(attempt)` mints the attempt's mount token through
+ * the place's control, and the runner it is handed to mounts with it. A start is `ensureRunning` (it creates the run's
+ * directory with `ensure.create` and writes the start mark) with that token and the order's environment. A kill is the
+ * driver's `kill`: `process` or `box`, whichever the driver takes. A recovery is the takeover: the dead holder's
+ * delegations revoked (its lease counts as expired, since the place killed it) and the next instance started, which
+ * `revoked` and `ms` report. A runner writes its kill request in the run's directory (`requestFile`), and `signals` reads
+ * it over S3. A runner ends when the driver no longer reports it running, or when the place killed it; its
+ * outcome is `run.json` read over S3, with `code`, `message`, `record` and `storeSha256` from the detail of the last
+ * status the app set. `release` stops every instance it started and removes every token it minted; the run's directory
+ * stays (`deleteRunTree`).
+ */
+export declare function archilPlace(options: ArchilPlaceOptions): (ctx: PlaceContext) => Place;