@eir-labs/coltrane 0.6.2 → 0.7.3

package/dist/src/worker.d.ts

@@ -0,0 +1,228 @@
+import { type AgentInvoker } from "./runtime.js";
+import { type Registry } from "./registry.js";
+import { type OutputStore } from "./outputs.js";
+import { type GigCheckpoint, type RunIdentity } from "./reuse.js";
+import type { Standard } from "./composition.js";
+import type { LoadedGenome } from "./loader.js";
+/** Where the org store is, and who is working. */
+export interface WorkerContext {
+    baseUrl: string;
+    anonKey: string;
+    /** The seated agent's ctk_ capability token — claim/genome/fail all speak through it. */
+    agentToken: string;
+    /** Lease label recorded on the claimed row (defaults to worker:<acting_for> store-side). */
+    worker?: string;
+}
+/** The claim RPC's payload: everything the worker needs to run the row it now leases. */
+export interface ClaimedGig {
+    gig_id: string;
+    standard_slug: string;
+    standard_version: number | null;
+    mode: string;
+    input: Record<string, unknown>;
+    acting_for: string;
+    /**
+     * The human seat's verdicts, keyed by chair role — present on a RE-claim of a gig that
+     * parked. The approve RPC writes them onto the row's manifest and re-queues it; the claim
+     * hands them back here, and each entry carries the verdict AND who gave it, because the
+     * approval seals under the approving principal's name rather than the worker's.
+     */
+    approvals?: Record<string, {
+        verdict: Record<string, unknown>;
+        approved_by?: string;
+    }> | null;
+}
+/**
+ * The worker's durable state root: `checkpoints/` for the resume records, `outputs/` + `refs/`
+ * for the sealed rows those records name — the sibling layout `createCheckpointStore` documents.
+ *
+ * BOTH halves have to outlive the process. A worker is a short-lived consumer: it claims one
+ * row and exits, and the approved re-claim is a DIFFERENT process. A checkpoint whose outputs
+ * the next process cannot read refuses the resume it exists to permit, so the run would be
+ * paid for twice — which is the whole cost this store exists to avoid.
+ */
+export declare function workerStateRoot(): string;
+/** Default worker-state TTL, in days. A checkpoint older than this is presumed abandoned. */
+export declare const DEFAULT_WORKER_STATE_TTL_DAYS = 7;
+/** Resolve the reaper TTL from `COLTRANE_WORKER_STATE_TTL_DAYS`, falling back to the default. */
+export declare function workerStateTtlDays(): number;
+export interface ReapOptions {
+    /** Age threshold in days. State whose mtime is older than this is eligible. Defaults to `workerStateTtlDays()`. */
+    ttlDays?: number;
+    /** "Now", in epoch ms, for the age comparison. Defaults to `Date.now()` at call time (never module load). */
+    now?: number;
+}
+export interface ReapResult {
+    /** gig ids whose checkpoint (+ siblings) were removed for being older than the TTL. */
+    checkpoints_removed: string[];
+    /** gig ids whose orphan output/refs rows (no live checkpoint) were removed for age. */
+    orphans_removed: string[];
+    /** How many checkpoint files were inspected and KEPT (fresh, or load-bearing). */
+    kept: number;
+    /** Non-fatal per-file errors, so a partial sweep is visible without throwing. */
+    errors: string[];
+}
+/**
+ * Bound the worker state root's growth. The runtime deletes a checkpoint on SUCCESS, but a
+ * FAILED / awaiting-approval / abandoned gig leaves its `checkpoints/<gig>.json` (plus the
+ * `outputs/<gig>.jsonl` + `refs/<gig>.jsonl` it names) behind forever — an unbounded disk
+ * leak. This drops what is old enough to be presumed abandoned.
+ *
+ * WHAT IT TOUCHES:
+ *  - A `checkpoints/<gig>.json` whose MTIME is older than the TTL, together with that gig's
+ *    sibling `outputs/<gig>.jsonl` and `refs/<gig>.jsonl` — they are dead weight once the
+ *    checkpoint that named them is gone.
+ *  - An ORPHAN `outputs/<gig>.jsonl` / `refs/<gig>.jsonl` (no checkpoint file for that gig at
+ *    all — e.g. a completed gig whose checkpoint was already dropped on success) older than the
+ *    TTL. This is the other half of the leak: success removes the checkpoint but leaves the rows.
+ *
+ * WHAT IT NEVER TOUCHES:
+ *  - Any gig whose checkpoint is FRESHER than the TTL. A parked / awaiting-approval gig's
+ *    checkpoint is LOAD-BEARING for the approved resume, and the TTL is the "reasonable window"
+ *    that protects it — the reaper cannot see the org store's row status locally, so mtime is
+ *    the proxy: recent state is kept. A fresh checkpoint's outputs are never swept even if the
+ *    outputs file itself looks old (a restore-only resume re-touches the checkpoint but appends
+ *    no new rows), because the sweep is driven from checkpoint age, not output age.
+ *
+ * Best-effort by construction: every filesystem op is caught and recorded in `errors`; the
+ * function never throws, so a reap failure can never fail the claim it runs ahead of.
+ */
+export declare function reapWorkerState(root: string, opts?: ReapOptions): ReapResult;
+export type WorkOnceResult = {
+    claimed: false;
+} | {
+    claimed: true;
+    gig_id: string;
+    /** `awaiting_approval` is its own outcome: a run that reached a human chair is neither
+     *  finished nor broken, and calling it either would be a lie the operator acts on. */
+    status: "complete" | "failed" | "awaiting_approval";
+    outputs_count?: number;
+    error?: string;
+    /** Present iff awaiting_approval: the human chair the run parked at. */
+    awaiting?: {
+        phase: string;
+        role: string;
+    };
+};
+export interface WorkOnceDeps {
+    /** Build the chair invoker against the STORE registry (types the org's outputs seal to). */
+    makeInvoke(registry: Registry, genome: LoadedGenome): AgentInvoker;
+    /** Progress line sink (CLI wires stderr); silent by default. */
+    log?(line: string): void;
+}
+/** Atomically claim the oldest runnable gig (queued, or running with an expired lease) the
+ *  seated agent's chair contract authorizes. Null means the queue holds nothing for us. */
+export declare function claimNextGig(ctx: WorkerContext): Promise<ClaimedGig | null>;
+/**
+ * Release the lease on a PARKED gig: the row goes `awaiting_approval` and its lease clears, so
+ * an approval can re-queue it immediately instead of waiting the lease out. Deliberately NOT
+ * `gig_fail` — a run waiting on a person is not a failed run, and recording it as one both lies
+ * to the operator and takes the row out of the approve→requeue path.
+ *
+ * False means the store did not record the release — including a store that has not deployed
+ * the RPC yet. The run's own drained header already carries `awaiting_approval`, so an absent
+ * release is a missing convenience, not a lost fact, and must not fail the claim.
+ */
+export declare function parkGig(ctx: WorkerContext, gig_id: string): Promise<boolean>;
+/** Record a failed run on the claimed row. True iff the store recorded it (row was running). */
+export declare function failGig(ctx: WorkerContext, gig_id: string, error: string): Promise<boolean>;
+/**
+ * One sealed row as `coltrane_mcp_gig_outputs` hands it back — the sink's view of an output.
+ *
+ * NARROWER than an `OutputRecord`, and the gap is the whole difficulty: the sink returns no
+ * `core_type`, no `domain`, no `primitive`, no `domain_type_version` and no `from_role`. Every
+ * one of the first four is folded into `content_sha`, so they are RE-DERIVED from the loaded
+ * genome the way the seal boundary derives them, and the re-derivation is then proved against
+ * the sha the sink recorded. A row that no longer hashes to its claimed sha is refused.
+ */
+export interface DrainedOutput {
+    id: string;
+    domain_type: string;
+    agent_slug: string;
+    phase?: string | null;
+    content_sha: string;
+    input_shas?: readonly (string | null)[] | null;
+    created_at: string;
+    data: Record<string, unknown>;
+}
+/** A reconstruction either produced a checkpoint or refused, and a refusal always says why. */
+export type DrainResumeState = {
+    ok: true;
+    checkpoint: GigCheckpoint;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The sink's sealed rows for one gig. `[]` covers "no drain to read" as well as "nothing drained". */
+export declare function fetchDrainedOutputs(ctx: WorkerContext, gig_id: string): Promise<{
+    rows: DrainedOutput[];
+    error?: string;
+}>;
+/**
+ * The `genome_hash` the sink recorded on this gig's drained HEADER.
+ *
+ * This is the only identity a drained gig carries, and reading it is what keeps the
+ * reconstruction from being a splice. `genomeHash` folds the standard's whole phase graph and
+ * every bound agent's type surface — chair `depends_on`, `input_contract`, an added or removed
+ * phase — none of which reaches an individual row's `content_sha`. Without this check a
+ * pipeline could be re-wired between the park and the approval and the restored outputs would
+ * be consumed by chairs that never produced them, with nothing in the manifest recording it.
+ *
+ * STATED GAP: the header carries no `producers_sha`, so a rewritten agent `method` (or a
+ * rewritten skill under a stable version) is invisible to this path — the very hole
+ * `RunIdentity.producers_sha` exists to close for a LOCAL checkpoint. A drain-reconstructed
+ * resume is therefore a weaker gate than a local one by exactly that much, and the strongest
+ * available check is the one applied: the sink's structural hash plus a per-row re-seal.
+ */
+export declare function fetchDrainedGenomeHash(ctx: WorkerContext, gig_id: string): Promise<{
+    genome_hash?: string;
+    error?: string;
+}>;
+/**
+ * Turn the sink's sealed rows into a resume checkpoint — or refuse, with a reason.
+ *
+ * ALL-OR-NOTHING, in two passes. Pass one derives and verifies every row while nothing is
+ * durable; pass two writes. A gig whose second row fails must not leave its first one in the
+ * local store seeding a half-resume, which is the same invariant #243 gave a single chair, one
+ * scope up.
+ *
+ * ROLE MAPPING. The sink does not record `from_role`, so each row is mapped to a chair by
+ * `phase` + the chair's SEAT: `agent_slug` for an agent chair, the skill slug for a skill-backed
+ * one, and name-agnostically for a human chair (its record seals under the approving principal,
+ * whom the genome cannot know). The row's `domain_type` narrows further — a chair that does not
+ * seal that type is not a candidate. Zero candidates or MORE THAN ONE both refuse: a guess about
+ * which chair produced a sealed output is a guess about the provenance chain.
+ *
+ * SHA VERIFICATION. Every row is re-sealed under the derived core/primitive/domain and the sha
+ * compared to the one the sink recorded. A mismatch refuses the WHOLE reconstruction — a sink
+ * row that no longer hashes to its claimed sha must never silently seed a resume, and one such
+ * row is evidence about the sink, not about that row alone.
+ */
+export declare function resumeStateFromDrain(args: {
+    gig_id: string;
+    standard: Standard;
+    identity: RunIdentity;
+    rows: readonly DrainedOutput[];
+    outputs: OutputStore;
+}): DrainResumeState;
+/**
+ * Map the claim's per-role approval entries onto runGig's two arguments.
+ *
+ * The store keys each verdict by ROLE (a standard may hold more than one human chair) while
+ * runGig takes a single `approved_by` for the run. So the name is read from the entry for the
+ * chair this claim will actually reach — the first human chair the checkpoint does not already
+ * hold — and falls back to the first entry when that is not discernible. Attribution on a seal
+ * is not decoration: the approval output carries it as its `agent_slug`.
+ */
+export declare function approvalWiring(approvals: ClaimedGig["approvals"], standard: Standard, completedRoles?: readonly string[]): {
+    approvals?: Record<string, Record<string, unknown>>;
+    approved_by?: string;
+};
+/** One unit of work: claim → load the org genome (as the agent) → run under the claimed
+ *  gig's id → results drain via the org drain key (engine drain layer, env-configured), or
+ *  the failure is recorded. Never throws for a run failure — a thrown claim/store error
+ *  means the worker itself could not speak to the store.
+ *
+ *  A run that reaches an unapproved human chair PARKS: the row is released (parkGig) and the
+ *  outcome is `awaiting_approval` — its own status, because it is neither finished nor broken. */
+export declare function workOnce(ctx: WorkerContext, deps: WorkOnceDeps): Promise<WorkOnceResult>;