@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/{computer/host → workspace}/install-job.d.ts

@@ -1,6 +1,6 @@
 import { type Workspace } from "@cloudflare/computer";
 import type { Scheduler } from "@dynamicagents/core/alarm";
-import { type InstallPlan, type InstallState } from "../install.js";
+import { type InstallPlan, type InstallState } from "./install.js";
 import type { WorkspaceWakeHandlers } from "./wake.js";
 export interface InstallJobDeps {
     storage: DurableObjectStorage;
@@ -22,9 +22,30 @@ export interface InstallJobDeps {
     waitUntil: (promise: Promise<unknown>) => void;
     /** A container was replaced, so nothing believed about it still holds. */
     containerGone: () => Promise<void>;
+    /**
+     * Storage entries the host keeps about a tree an install finished, written in
+     * the same write as that install's verdict — nothing can read the one without
+     * the other.
+     */
+    installedRecords: (tree: {
+        dir: string;
+        fingerprint: string;
+        at: number;
+    }) => Record<string, unknown>;
+    /** After that write: an install exited 0, so this container holds the tree. */
+    installed: (tree: {
+        dir: string;
+        fingerprint: string;
+        at: number;
+    }) => Promise<void>;
     tag: () => string;
     id: () => string;
 }
+/** Where an install goes: the checkout, and the repository for its override. */
+export interface InstallTarget {
+    dir: string;
+    repo?: string;
+}
 export declare class InstallJob {
     #private;
     private readonly deps;
@@ -48,6 +69,34 @@ export declare class InstallJob {
     armIfTreeMissing(): Promise<void>;
     /** Where the last install ran, for the container setup's marker read. */
     dir(): Promise<string | undefined>;
+    /** Where the last install ran, and for which repository's override. */
+    target(): Promise<InstallTarget | undefined>;
+    /**
+     * The fingerprint an install into `target` would write as its marker, from the
+     * checkout as it stands — `null` when there is nothing to install there.
+     */
+    fingerprintFor(target: InstallTarget): Promise<string | null>;
+    /** What `dir`'s install inputs hash to — see `rootFingerprint`. */
+    rootFingerprint(dir: string): Promise<string | null>;
+    /** The tree this container holds, if a finished install says it does. */
+    tree(): Promise<{
+        dir: string;
+        fingerprint: string | null;
+        at: number;
+    } | undefined>;
+    /**
+     * Record a tree this container came up holding — restored with a snapshot of
+     * the container that installed it — as if this container had installed it.
+     *
+     * Only for a tree whose marker the setup read and matched against the checkout
+     * as it stands; see `./deps-snapshot.ts`. So the last install's context moves
+     * to it too: a checkout that moved since that install would otherwise read as
+     * missing its tree, and arm an install that finds the tree already there.
+     */
+    adopt(tree: {
+        dir: string;
+        fingerprint: string;
+    }): Promise<void>;
     /** The container went away, and its tree with it. */
     containerGone(): Promise<void>;
     /**
@@ -71,7 +120,7 @@ export declare class InstallJob {
      *
      * Called from `repo_clone` through the repo plugin's `afterCheckout` hook, so
      * it runs inside a model turn and must not block on the install — 225 seconds
-     * for slack-gatekeeper, against a chunk step that dies at ten minutes.
+     * for slack-gatekeeper, against a turn that is cut at fifteen minutes.
      *
      * That caller is a model turn, which lives long enough to hold the drain handed
      * to `ctx.waitUntil` below. **A short-lived caller cannot**, which is why an
@@ -102,7 +151,7 @@ export declare class InstallJob {
     /**
      * When a reinstall was queued, if one is waiting to run.
      *
-     * Read by {@link file://../advisory.ts deriveAdvisories}, which is the only
+     * Read by {@link file://./advisory.ts deriveAdvisories}, which is the only
      * caller that needs it: a `failed` record with a repair already queued is a
      * transient condition wearing a permanent record's clothes.
      */
@@ -112,7 +161,7 @@ export declare class InstallJob {
      *
      * `clearArmed` first and unconditionally: this handler runs for minutes, and
      * the stamp left in place is what a second arming would recognise as its own.
-     * `startInstall`'s in-flight guard would catch a double, but the cheaper
+     * The reservation in `#beginInstall` would catch a double, but the cheaper
      * answer is not to schedule one.
      */
     onRun(): Promise<void>;