@fungi.computer/oyster 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-replay";
 import { type AppGitPushFact, type GitPushQuestion, type GitPushVerdict } from "@fungi.computer/agar/git";
-import { type CairnId } from "@fungi.computer/cairn/id";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import type { DurableBackend } from "@fungi.computer/puffball/backend";
@@ -9,15 +8,14 @@ import type { AppMethodReply } from "@fungi.computer/agar/backend";
 import type { AppApi } from "@fungi.computer/puffball";
 import type { InvocationFrame } from "./invocation.js";
 import type { Installation } from "./apps/installation.js";
+import { type UiBootCheckOutcome } from "./boot-gate.js";
+/** Runtime validator for report-only installation UI-check outcomes. */
+export { uiBootCheckOutcomeSchema } from "./boot-gate.js";
+/** A report-only UI-check result stored with an installation operation. */
+export type { UiBootCheckOutcome } from "./boot-gate.js";
 import { type GillCall, type GillReply } from "@fungi.computer/gills";
-/** The Cairn ID family that mints and recognizes App Instance IDs (`instance_…`). */
-export declare const instanceIds: Readonly<{
-    readonly instance: import("@fungi.computer/cairn").IdCodec<"app-instance", "instance", 1>;
-}>;
-/** A stable App Instance ID minted by {@link instanceIds}. */
-export type InstanceId = CairnId<"app-instance", "instance">;
-/** Decodes a string into an {@link InstanceId}, rejecting any other ID family. */
-export declare const instanceIdSchema: Schema.Codec<InstanceId, string>;
+export { agentAvatarProjectionSchema, agentAvatarSchema, avatarFromProjection, createAgentAvatarStore, type AgentAvatarStore, } from "./agent-avatars.js";
+export { instanceIds, instanceIdSchema, type InstanceId, } from "./instance-id.js";
 /**
  * The owner that issues authority for an Instance: an `installation` of an App
  * or a `deployment`. Owner identity never changes for the life of an Instance.
@@ -31,7 +29,7 @@ export declare const ownerSchema: Schema.Struct<{
  * runs against, at a positive authority version.
  */
 export declare const selectionSchema: Schema.Struct<{
-    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly instanceId: Schema.Codec<import("./instance-id.js").InstanceId, string, never, never>;
     readonly owner: Schema.Struct<{
         readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
         readonly id: Schema.NonEmptyString;
@@ -43,7 +41,7 @@ export declare const selectionSchema: Schema.Struct<{
 /** A complete owner-issued state: a selection plus `enabled`, `disabled` or `deleted`. */
 export declare const ownerStateSchema: Schema.Struct<{
     readonly status: Schema.Literals<readonly ["enabled", "disabled", "deleted"]>;
-    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly instanceId: Schema.Codec<import("./instance-id.js").InstanceId, string, never, never>;
     readonly owner: Schema.Struct<{
         readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
         readonly id: Schema.NonEmptyString;
@@ -62,7 +60,7 @@ export declare const instanceSchema: Schema.Struct<{
     readonly stateSchema: Schema.NullOr<Schema.Number>;
     readonly desiredStatus: Schema.Literals<readonly ["enabled", "disabled", "deleted"]>;
     readonly status: Schema.Literals<readonly ["active", "disabled", "deleting", "deleted"]>;
-    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly instanceId: Schema.Codec<import("./instance-id.js").InstanceId, string, never, never>;
     readonly owner: Schema.Struct<{
         readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
         readonly id: Schema.NonEmptyString;
@@ -84,7 +82,7 @@ export type Backend = Readonly<{
     backend: DurableBackend;
 }>;
 /** The runtime owns the bounded rejection grammar, including across RPC. */
-export declare const appInstanceErrorCodeSchema: Schema.Literals<readonly ["invalid_owner_state", "invalid_invocation_facts", "revoked", "binding_not_granted", "binding_unavailable", "expired", "reentrant", "instance_identity_mismatch", "instance_owner_mismatch", "conflicting_owner_state", "stale_authority", "instance_deleted", "release_app_mismatch", "state_schema_migration_unsupported", "instance_inactive", "instance_authority_version_mismatch", "release_no_longer_matches_instance", "instance_release_mismatch", "installation_tenant_mismatch"]>;
+export declare const appInstanceErrorCodeSchema: Schema.Literals<readonly ["invalid_owner_state", "invalid_invocation_facts", "revoked", "disabled", "binding_not_granted", "binding_unavailable", "expired", "reentrant", "instance_identity_mismatch", "instance_owner_mismatch", "conflicting_owner_state", "stale_authority", "instance_deleted", "release_app_mismatch", "state_schema_migration_unsupported", "instance_inactive", "instance_authority_version_mismatch", "release_no_longer_matches_instance", "instance_release_mismatch", "installation_tenant_mismatch", ...("backend_load_failed" | "backend_construction_failed" | "ui_mount_failed" | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed")[]]>;
 /** One of the bounded {@link appInstanceErrorCodeSchema} rejection codes. */
 export type AppInstanceErrorCode = typeof appInstanceErrorCodeSchema.Type;
 /** Stable runtime failure identity; message remains presentation only. */
@@ -110,8 +108,19 @@ export type InstancePorts<Host> = Readonly<{
     write: (instance: Instance) => Effect.Effect<void, Error>;
     /** Resolve a Release ID to its verified durable backend. */
     resolve: (release: Selection["releaseId"], scope: BackendResolution<Host>) => Effect.Effect<Backend, Error>;
-    /** Abort in-flight backend work and invalidate existing connections. */
-    abort: () => Effect.Effect<void, Error>;
+    /**
+     * Host-owned backend construction gate plus UI-check report. Backend
+     * construction errors block selection; the returned UI outcome is advisory.
+     * `null` means this executor deliberately did not run a UI check. The prior
+     * schema comes from this operation's persisted read, not the candidate.
+     * Prepare asks for the UI check (`"run"`); apply proves construction again
+     * but `"reuse"`s prepare's recorded result and never opens a browser.
+     * UI artifacts are verified during preparation, not re-read on apply-only
+     * lifecycle changes; Releases and their artifacts are content-addressed.
+     */
+    boot: (backend: Backend, priorStateSchema: Instance["stateSchema"], uiCheck: "run" | "reuse") => Effect.Effect<UiBootCheckOutcome | null, Error>;
+    /** Abort in-flight work after fencing its authority and invalidate connections. */
+    abort: (reason: AppInstanceError) => Effect.Effect<void, Error>;
     /** Delete the backend's own state. */
     purge: () => Effect.Effect<void, Error>;
     /**
@@ -143,6 +152,8 @@ export type AppInstance<Host> = Readonly<{
      * changed input at the same version conflicts and older versions are stale.
      */
     apply: (input: OwnerState) => Effect.Effect<Instance, Error>;
+    /** Run the same lifecycle and boot checks without writing, aborting or purging. */
+    prepare: (input: OwnerState) => Effect.Effect<UiBootCheckOutcome | null, Error>;
     /** Admit the frame's selection and forward an HTTP request to the active backend. */
     fetch: (frame: InvocationFrame<Host>, request: Request) => Effect.Effect<Response, Error>;
     /** Admit the frame and invoke a method declared by the Release's App API. */

package/dist/index.js

@@ -1,21 +1,18 @@
 import { backgroundSyncRefusalSchema, } from "@fungi.computer/puffball/background-replay";
 import { appGitPushFactSchema, gitPushQuestionSchema, gitPushVerdictSchema, } from "@fungi.computer/agar/git";
 import * as Semaphore from "effect/Semaphore";
-import { defineIdFamily } from "@fungi.computer/cairn/id";
+import { instanceIdSchema } from "./instance-id.js";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { releaseIdSchema, appIdSchema } from "@fungi.computer/puffball/effect";
 import { appFacetRequest, appFacetResponse } from "./backend-request.js";
 import { appApiSchema } from "@fungi.computer/puffball/app";
+import { bootFailureSchema, BootGateError, } from "./boot-gate.js";
+/** Runtime validator for report-only installation UI-check outcomes. */
+export { uiBootCheckOutcomeSchema } from "./boot-gate.js";
 import { gillCallSchema, gillReplySchema, } from "@fungi.computer/gills";
-/** The Cairn ID family that mints and recognizes App Instance IDs (`instance_…`). */
-export const instanceIds = defineIdFamily({
-    family: "app-instance",
-    version: 1,
-    kinds: { instance: { prefix: "instance" } },
-});
-/** Decodes a string into an {@link InstanceId}, rejecting any other ID family. */
-export const instanceIdSchema = Schema.String.pipe(Schema.refine((value) => instanceIds.instance.is(value)));
+export { agentAvatarProjectionSchema, agentAvatarSchema, avatarFromProjection, createAgentAvatarStore, } from "./agent-avatars.js";
+export { instanceIds, instanceIdSchema, } from "./instance-id.js";
 /**
  * The owner that issues authority for an Instance: an `installation` of an App
  * or a `deployment`. Owner identity never changes for the life of an Instance.
@@ -59,7 +56,7 @@ export function selectionOf(installation) {
         owner: { kind: "installation", id: installation.installationId },
         appId: installation.release.appId,
         releaseId: installation.release.releaseId,
-        authorityVersion: installation.authorityVersion,
+        authorityVersion: installation.authority.authorityVersion,
     };
 }
 /** The runtime owns the bounded rejection grammar, including across RPC. */
@@ -67,6 +64,7 @@ export const appInstanceErrorCodeSchema = Schema.Literals([
     "invalid_owner_state",
     "invalid_invocation_facts",
     "revoked",
+    "disabled",
     "binding_not_granted",
     "binding_unavailable",
     "expired",
@@ -83,11 +81,22 @@ export const appInstanceErrorCodeSchema = Schema.Literals([
     "release_no_longer_matches_instance",
     "instance_release_mismatch",
     "installation_tenant_mismatch",
+    ...bootFailureSchema.options,
 ]);
 const APP_INSTANCE_ERROR_MESSAGES = {
+    backend_load_failed: new BootGateError("backend_load_failed").message,
+    backend_construction_failed: new BootGateError("backend_construction_failed")
+        .message,
+    ui_mount_failed: new BootGateError("ui_mount_failed").message,
+    boot_runner_unavailable: new BootGateError("boot_runner_unavailable").message,
+    boot_browser_binding_missing: new BootGateError("boot_browser_binding_missing").message,
+    boot_clone_unavailable: new BootGateError("boot_clone_unavailable").message,
+    boot_timeout: new BootGateError("boot_timeout").message,
+    boot_cleanup_failed: new BootGateError("boot_cleanup_failed").message,
     invalid_owner_state: "Invalid owner state",
     invalid_invocation_facts: "Invalid invocation facts",
     revoked: "Invocation authority revoked",
+    disabled: "App disabled",
     binding_not_granted: "Binding operation not granted",
     binding_unavailable: "Binding operation unavailable on this host",
     expired: "Invocation deadline exceeded",
@@ -136,11 +145,11 @@ export function createAppInstance(ports) {
         }
         return current;
     });
-    const apply = (input) => lock.withPermits(1)(Effect.gen(function* () {
+    const preflight = (input, readCurrent, uiCheck) => Effect.gen(function* () {
         const desired = yield* Schema.decodeUnknownEffect(ownerStateSchema)(input).pipe(Effect.mapError(() => new AppInstanceError("invalid_owner_state")));
         if (desired.instanceId !== ports.instanceId)
             return yield* failure("instance_identity_mismatch");
-        const current = yield* read;
+        const current = yield* readCurrent;
         if (current && !sameOwner(current, desired))
             return yield* failure("instance_owner_mismatch");
         const retry = current !== null &&
@@ -151,14 +160,15 @@ export function createAppInstance(ports) {
             return yield* failure("conflicting_owner_state");
         if (current && desired.authorityVersion < current.authorityVersion)
             return yield* failure("stale_authority");
-        if (current?.status === "deleted") {
+        if (current?.status === "deleted" || current?.status === "deleting") {
             if (retry && desired.status === "deleted")
-                return current;
+                return { kind: "unchanged", receipt: current };
             return yield* failure("instance_deleted");
         }
         if (retry && current.status === "active")
-            return current;
+            return { kind: "unchanged", receipt: current };
         let stateSchema = current?.stateSchema ?? null;
+        let bootCheck = null;
         if (desired.status === "enabled") {
             const resolved = yield* ports.resolve(desired.releaseId, {
                 kind: "metadata",
@@ -169,7 +179,20 @@ export function createAppInstance(ports) {
                 stateSchema !== resolved.backend.runtime.stateSchema)
                 return yield* failure("state_schema_migration_unsupported");
             stateSchema = resolved.backend.runtime.stateSchema;
+            bootCheck = yield* ports.boot(resolved, current?.stateSchema ?? null, uiCheck);
         }
+        return { kind: "apply", desired, stateSchema, bootCheck };
+    });
+    const prepare = (input) => lock.withPermits(1)(Effect.gen(function* () {
+        // The one UI check for this selection; apply reuses its result.
+        const transition = yield* preflight(input, ports.read(), "run");
+        return transition.kind === "apply" ? transition.bootCheck : null;
+    }));
+    const apply = (input) => lock.withPermits(1)(Effect.gen(function* () {
+        const transition = yield* preflight(input, read, "reuse");
+        if (transition.kind === "unchanged")
+            return transition.receipt;
+        const { desired, stateSchema } = transition;
         const next = {
             ...desired,
             desiredStatus: desired.status,
@@ -180,7 +203,7 @@ export function createAppInstance(ports) {
         };
         // Persist the exact owner fact before stopping runtime; no resource-issued version.
         yield* ports.write(next);
-        yield* ports.abort();
+        yield* ports.abort(new AppInstanceError(desired.status === "disabled" ? "disabled" : "revoked"));
         if (desired.status === "deleted")
             yield* ports.purge();
         const receipt = {
@@ -309,6 +332,7 @@ export function createAppInstance(ports) {
     }));
     return {
         syncRefused,
+        prepare,
         apply,
         fetch,
         call,

package/dist/install-release-cli.d.ts

@@ -0,0 +1,2 @@
+export declare const installReleaseUsage = "Usage: oyster install <directory|release.json> [--installation-id <name>]";
+export declare function installReleaseCommand(args: readonly string[]): Promise<void>;

package/dist/install-release-cli.js

@@ -0,0 +1,46 @@
+/** Local Release installation uses the ordinary pack uploader and owner API. */
+import { stat } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { installRelease } from "./pack.js";
+export const installReleaseUsage = "Usage: oyster install <directory|release.json> [--installation-id <name>]";
+export async function installReleaseCommand(args) {
+    const { values, positionals } = parseArgs({
+        args: [...args],
+        allowPositionals: true,
+        strict: true,
+        options: {
+            "installation-id": { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(installReleaseUsage +
+            "\nUpload a built Release and install it using OYSTER_URL and OYSTER_OWNER_KEY.\n");
+        return;
+    }
+    const [source] = positionals;
+    if (positionals.length !== 1 || source === undefined)
+        throw new Error(installReleaseUsage);
+    const url = process.env.OYSTER_URL;
+    const key = process.env.OYSTER_OWNER_KEY;
+    if (!url || !key)
+        throw new Error("Set OYSTER_URL and OYSTER_OWNER_KEY for the target Oyster. " +
+            installReleaseUsage);
+    const path = resolve(source);
+    const info = await stat(path);
+    if (!info.isDirectory() &&
+        (!info.isFile() || basename(path) !== "release.json"))
+        throw new Error("Expected a Release directory or release.json");
+    const response = await installRelease({
+        directory: info.isDirectory() ? path : dirname(path),
+        url,
+        key,
+        installationId: values["installation-id"],
+    });
+    const body = await response.text();
+    if (!response.ok)
+        throw new Error("Installation failed (" + String(response.status) + "): " + body);
+    process.stdout.write(body + "\n");
+}

package/dist/installation-client.d.ts

@@ -0,0 +1,43 @@
+import type { Release } from "@fungi.computer/puffball";
+import { type InstallationOperation } from "./installation-operations.js";
+export type InstallationCompletion = Exclude<InstallationOperation, {
+    state: "pending";
+}>;
+export type InstallationObservationBudget = Readonly<{
+    /** Upload/observation time; expiry never cancels admitted durable work. */
+    waitMs?: number;
+    /** Caller-owned budget; used unchanged unless waitMs is also explicit. */
+    signal?: AbortSignal;
+}>;
+/** Share one budget across pack uploads and the subsequent receipt observation. */
+export declare function installationObservationSignal(input: InstallationObservationBudget): AbortSignal;
+/** Observer failure supplies no installation outcome and never cancels its owner. */
+export declare class InstallationObservationError extends Error {
+    readonly requestId: string;
+    constructor(requestId: string, options?: ErrorOptions);
+}
+/** Observe one retained command, over either HTTP or the host's decoded port. */
+export declare function observeInstallation(input: Readonly<{
+    requestId: string;
+    initial: InstallationOperation | null;
+    read(): Promise<InstallationOperation | null>;
+    signal: AbortSignal;
+    pollMs?: number;
+    idle?: (ms: number, signal: AbortSignal) => Promise<void>;
+}>): Promise<InstallationCompletion>;
+/** Completed HTTP meaning shared by pack and the retained PUT selection door. */
+export declare function completedInstallationResponse(operation: InstallationCompletion): Response;
+/**
+ * Submit once and observe the correlated owner receipt. Both CLI paths use
+ * exactly this contract; no directory reads or old completed-POST branch.
+ */
+export declare function installOnOyster(input: Readonly<{
+    url: string;
+    key: string;
+    installationId: string;
+    release: Release;
+    pollMs?: number;
+    idle?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /** Once, after the owner supplies a correlated record, even after a lost ack. */
+    onAdmitted?: (operation: InstallationOperation) => void;
+}> & InstallationObservationBudget): Promise<InstallationCompletion>;

package/dist/installation-client.js

@@ -0,0 +1,178 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { addAbortListener } from "node:events";
+import * as Schema from "effect/Schema";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+import { instanceRefusalBody } from "./instance-refusal.js";
+import { installationOperationSchema, installationCommandIds, } from "./installation-operations.js";
+/**
+ * Installer-owned observer budget, matching the standalone installer's existing
+ * twenty-minute default. Not an App grant lifetime or a server execution limit.
+ */
+const DEFAULT_INSTALLATION_WAIT_MS = 20 * 60_000;
+/** Share one budget across pack uploads and the subsequent receipt observation. */
+export function installationObservationSignal(input) {
+    if (input.signal !== undefined && input.waitMs === undefined)
+        return input.signal;
+    const timer = AbortSignal.timeout(input.waitMs ?? DEFAULT_INSTALLATION_WAIT_MS);
+    return input.signal === undefined
+        ? timer
+        : AbortSignal.any([input.signal, timer]);
+}
+/** Observer failure supplies no installation outcome and never cancels its owner. */
+export class InstallationObservationError extends Error {
+    requestId;
+    constructor(requestId, options) {
+        super(`Installation outcome unconfirmed (${requestId})`, options);
+        this.requestId = requestId;
+    }
+}
+const idle = (ms, signal) => sleep(ms, undefined, { signal });
+/** Observe one retained command, over either HTTP or the host's decoded port. */
+export async function observeInstallation(input) {
+    try {
+        input.signal.throwIfAborted();
+        let operation = input.initial;
+        while (operation === null || operation.state === "pending") {
+            input.signal.throwIfAborted();
+            // The decoded RPC port has no cancellation argument. Stop THIS wait
+            // without cancelling the retained command or abandoning its late reply.
+            let listener;
+            try {
+                operation = await new Promise((resolve, reject) => {
+                    listener = addAbortListener(input.signal, () => {
+                        reject(new InstallationObservationError(input.requestId, {
+                            cause: input.signal.reason,
+                        }));
+                    });
+                    // Both late outcomes remain handled after the observer has left.
+                    Promise.resolve()
+                        .then(() => input.read())
+                        .then(resolve, reject);
+                });
+            }
+            finally {
+                listener?.[Symbol.dispose]();
+            }
+            input.signal.throwIfAborted();
+            if (operation === null || operation.state === "pending")
+                await (input.idle ?? idle)(input.pollMs ?? 5_000, input.signal);
+        }
+        return operation;
+    }
+    catch (cause) {
+        if (cause instanceof InstallationObservationError)
+            throw cause;
+        throw new InstallationObservationError(input.requestId, { cause });
+    }
+}
+/** Completed HTTP meaning shared by pack and the retained PUT selection door. */
+export function completedInstallationResponse(operation) {
+    if (operation.state === "unconfirmed")
+        throw new InstallationObservationError(operation.requestId);
+    if (operation.state === "refused")
+        return Response.json(instanceRefusalBody(operation.code), {
+            status: operation.status,
+        });
+    if (operation.installation === null)
+        return Response.json({
+            error: "installation_result_unavailable",
+            requestId: operation.requestId,
+            reference: operation.reference,
+        }, { status: 409 });
+    return Response.json(operation.installation, {
+        status: operation.creation === "replacement" ? 200 : 201,
+    });
+}
+/**
+ * Submit once and observe the correlated owner receipt. Both CLI paths use
+ * exactly this contract; no directory reads or old completed-POST branch.
+ */
+export async function installOnOyster(input) {
+    const requestId = installationCommandIds.request.generate();
+    const signal = installationObservationSignal(input);
+    const headers = {
+        Authorization: `Bearer ${input.key}`,
+        Accept: "application/json",
+    };
+    let admitted = false;
+    const decode = async (response) => {
+        const operation = installationOperationSchema.parse(await response.json());
+        if (operation.requestId !== requestId ||
+            operation.requestedInstallationId !== input.installationId ||
+            operation.release.appId !== input.release.appId ||
+            operation.release.releaseId !== input.release.releaseId ||
+            operation.release.artifact.artifactDigest !==
+                input.release.artifact.artifactDigest ||
+            (operation.state === "succeeded" &&
+                operation.installation !== null &&
+                (operation.installation.installationId !== operation.installationId ||
+                    operation.installation.appId !== input.release.appId ||
+                    operation.installation.release.releaseId !==
+                        input.release.releaseId ||
+                    operation.installation.release.artifact.artifactDigest !==
+                        input.release.artifact.artifactDigest)))
+            throw new InstallationObservationError(requestId);
+        if (!admitted) {
+            admitted = true;
+            input.onAdmitted?.(operation);
+        }
+        return operation;
+    };
+    try {
+        signal.throwIfAborted();
+        let operation = null;
+        // Catch only the transport, not a malformed authoritative acknowledgement.
+        let submitted;
+        try {
+            submitted = await fetch(new URL("/api/installations", input.url), {
+                method: "POST",
+                signal,
+                headers: {
+                    ...headers,
+                    "Content-Type": "application/json",
+                    "Idempotency-Key": requestId,
+                },
+                body: JSON.stringify({
+                    installationId: input.installationId,
+                    release: Schema.encodeUnknownSync(releaseSchema)(input.release),
+                }),
+            });
+        }
+        catch {
+            signal.throwIfAborted();
+            submitted = null;
+            // Missing acknowledgement is not permission to resubmit.
+        }
+        if (submitted?.status === 202)
+            operation = await decode(submitted);
+        else if (submitted !== null && submitted.status < 500)
+            throw new InstallationObservationError(requestId);
+        const statusUrl = new URL(`/api/installations/${encodeURIComponent(input.installationId)}/status`, input.url);
+        statusUrl.searchParams.set("requestId", requestId);
+        let observation = {
+            requestId,
+            initial: operation,
+            signal,
+            read: async () => {
+                // Like decoded RPC reads, transport errors reach the observer with
+                // their original cause; they are not an authoritative pending read.
+                const observed = await fetch(statusUrl, { headers, signal });
+                if (observed.status === 200)
+                    return decode(observed);
+                if (observed.status !== 404 && observed.status < 500)
+                    throw new InstallationObservationError(requestId);
+                return null;
+            },
+        };
+        if (input.pollMs !== undefined)
+            observation = { ...observation, pollMs: input.pollMs };
+        if (input.idle !== undefined)
+            observation = { ...observation, idle: input.idle };
+        return await observeInstallation(observation);
+    }
+    catch (cause) {
+        if (cause instanceof InstallationObservationError)
+            throw cause;
+        throw new InstallationObservationError(requestId, { cause });
+    }
+}

package/dist/installation-execution.d.ts

@@ -0,0 +1,11 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { type TenantScope } from "./tenant.js";
+import { type RetainedInstallationCommand, type InstallationOutcome } from "./installation-operations.js";
+import type { OysterHost } from "./host.js";
+/** Ordinary Worker-side verification and lifecycle I/O for one retained intent. */
+export declare function executeInstallation(host: OysterHost, input: RetainedInstallationCommand): Promise<InstallationOutcome>;
+/** A loopback export with ordinary Worker I/O, not another resource or HTTP API. */
+export declare function installationWorkerEntrypoint<Env>(hostFor: (env: Env, scope: TenantScope) => OysterHost | Promise<OysterHost>): new (ctx: ExecutionContext, env: Env) => WorkerEntrypoint<Env, unknown> & {
+    /** Execute the retained command these props name, in its tenant scope. */
+    run(): Promise<InstallationOutcome>;
+};