@moldesk/core 0.0.4 → 0.0.6

package/dist/cloud/manage.test.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { getMoldeskPaths } from "@moldesk/runtime";
+import { executeCloudCacheDeletion, listCloudCaches, planCloudCacheDeletion } from "./manage.js";
+import { CloudJournal } from "./state.js";
+const dirs = [];
+const RUN = "2026-10-13T11-55-45-123Z-0a1b2c3d-1111-2222-3333-444455556666";
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+function box() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk manage "));
+    dirs.push(home);
+    const paths = getMoldeskPaths({ MOLDESK_HOME: home });
+    const volumes = new Map();
+    const state = { failDelete: false, stickyDelete: false, deleted: [] };
+    const provider = {
+        name: "runpod",
+        listVolumes: async () => [...volumes.values()],
+        getVolume: async (id) => volumes.get(id) ?? null,
+        deleteVolume: async (id) => {
+            if (state.failDelete)
+                throw new Error("provider down");
+            if (!state.stickyDelete)
+                volumes.delete(id);
+            state.deleted.push(id);
+            return { id, alreadyAbsent: false };
+        },
+    };
+    const journal = CloudJournal.open(paths);
+    const seed = (model, volumeId, owned = true, key = "k".repeat(64)) => {
+        volumes.set(volumeId, { id: volumeId, name: "n", sizeGb: 40, dataCenterId: "DC-1", type: "STANDARD" });
+        if (owned) {
+            const intent = journal.recordResourceIntent({ role: "volume" });
+            if (!journal.findOwnedByProviderId(volumeId))
+                journal.recordResourceCreated(intent.intentId, volumeId);
+        }
+        journal.upsertCache({ accountScope: "acct", datacenterId: "DC-1", volumeId, model, modelVersion: "1", cacheKey: key, layoutRevision: "1", manifestDigest: "m", cachePath: "/workspace/x", sizeBytes: null, checksumManifestDigest: null });
+    };
+    const deps = { provider, paths, accountScope: "acct" };
+    return { journal, volumes, state, seed, deps };
+}
+describe("cache management", () => {
+    it("lists caches with whether the provider still has the volume", async () => {
+        const b = box();
+        b.seed("boltz", "vol1");
+        b.volumes.delete("vol1");
+        b.seed("other", "vol2");
+        const listing = await listCloudCaches(b.deps);
+        expect(listing.map((entry) => [entry.cache.model, entry.volumeExists])).toEqual([["boltz", false], ["other", true]]);
+    });
+    it("plans exactly the volumes for one model", async () => {
+        const b = box();
+        b.seed("boltz", "vol1");
+        b.seed("other", "vol2");
+        const plan = await planCloudCacheDeletion("boltz", b.deps);
+        expect(plan).toEqual({ model: "boltz", volumes: [{ volumeId: "vol1", datacenterId: "DC-1", sizeGb: 40, cacheKeys: ["k".repeat(64)] }], blockers: [] });
+    });
+    it("blocks deletion while a run uses the volume or another model shares it", async () => {
+        const b = box();
+        b.seed("boltz", "vol1");
+        b.journal.createJob({ runId: RUN, accountScope: "acct", quoteDigest: "q", cachePolicy: "persistent", deadlineAt: "2099-01-01T00:00:00.000Z", manifestDigest: "m" });
+        b.journal.updateJob(RUN, { volumeId: "vol1", stage: "running" });
+        b.seed("other", "vol1", true, "j".repeat(64));
+        const plan = await planCloudCacheDeletion("boltz", b.deps);
+        expect(plan.blockers.join(" ")).toMatch(/still using volume vol1/);
+        expect(plan.blockers.join(" ")).toMatch(/also holds caches for: other/);
+        await expect(executeCloudCacheDeletion(plan, b.deps)).rejects.toMatchObject({ code: "CLOUD_CACHE_IN_USE" });
+        expect(b.state.deleted).toEqual([]);
+    });
+    it("deletes an owned volume, verifies it is gone, and removes the cache row", async () => {
+        const b = box();
+        b.seed("boltz", "vol1");
+        const result = await executeCloudCacheDeletion(await planCloudCacheDeletion("boltz", b.deps), b.deps);
+        expect(result).toEqual({ deleted: [{ volumeId: "vol1" }], failed: [] });
+        expect(b.volumes.size).toBe(0);
+        expect(b.journal.listCaches()).toHaveLength(0);
+        expect(b.journal.findOwnedByProviderId("vol1")).toBeUndefined();
+    });
+    it("refuses to delete a volume this installation did not create", async () => {
+        const b = box();
+        b.seed("boltz", "vol1", false);
+        const result = await executeCloudCacheDeletion(await planCloudCacheDeletion("boltz", b.deps), b.deps);
+        expect(result.deleted).toEqual([]);
+        expect(result.failed[0].reason).toMatch(/did not create/);
+        expect(b.state.deleted).toEqual([]);
+        expect(b.journal.listCaches()).toHaveLength(1);
+    });
+    it("reports provider failures and a volume that still exists after deletion, keeping the journal truthful", async () => {
+        const b = box();
+        b.seed("boltz", "vol1");
+        b.state.failDelete = true;
+        const failed = await executeCloudCacheDeletion(await planCloudCacheDeletion("boltz", b.deps), b.deps);
+        expect(failed.failed[0].reason).toMatch(/provider down/);
+        expect(b.journal.listCaches()).toHaveLength(1);
+        b.state.failDelete = false;
+        b.state.stickyDelete = true;
+        const sticky = await executeCloudCacheDeletion(await planCloudCacheDeletion("boltz", b.deps), b.deps);
+        expect(sticky.failed[0].reason).toMatch(/still lists the volume/);
+        expect(b.journal.listCaches()).toHaveLength(1);
+    });
+});

package/dist/cloud/quote.d.ts

@@ -0,0 +1,131 @@
+import type { CloudCatalog } from "@moldesk/runtime";
+import type { CloudSpec, ModelManifestV1 } from "@moldesk/registry";
+import type { CloudCachePolicy } from "./state.js";
+export declare const QUOTE_VERSION = 1;
+/** Approvals older than this are refused; the user must see a fresh quote. */
+export declare const APPROVAL_MAX_AGE_MS: number;
+/** A price rise above this fraction since approval requires a new approval. */
+export declare const PRICE_TOLERANCE = 0.1;
+/** Storage amounts below these absolute rises are noise, not a material change (USD). */
+export declare const STORAGE_NOISE_FLOOR_USD = 0.01;
+export declare const RECURRING_NOISE_FLOOR_USD_PER_MONTH = 0.1;
+/** Shown prominently before approval and must be explicitly acknowledged: there is no independent shutdown service. */
+export declare const LIFETIME_RISK_WARNING = "If MoleculeDesk closes or loses connection, your Runpod Pod may keep running and charging. Automatic shutdown is not guaranteed. Check your Runpod dashboard and terminate any remaining Pod.";
+export declare const STORAGE_CHARGES_WARNING = "Persistent caching keeps a network volume. Storage charges continue until you delete it (`moldesk cloud cache delete`, or in the Runpod dashboard).";
+export type CloudAcknowledgment = "lifetime-risk" | "storage-charges";
+export interface QuoteWarning {
+    id: CloudAcknowledgment;
+    text: string;
+}
+export declare const DEFAULT_MAX_LIFETIME_SECONDS = 3600;
+export declare const DEFAULT_PREP_CPU: {
+    readonly id: "cpu3c";
+    readonly vcpuCount: 2;
+};
+export interface QuoteRange {
+    minSeconds: number;
+    maxSeconds: number;
+}
+export interface CloudQuote {
+    version: typeof QUOTE_VERSION;
+    /** Digest of everything the user consents to; excludes volatile prices and retrieval time. */
+    id: string;
+    provider: string;
+    retrievedAt: string;
+    model: string;
+    modelVersion: string;
+    cachePolicy: CloudCachePolicy;
+    gpu: {
+        id: string;
+        name: string;
+        memoryGb: number;
+        priceUsdPerHour: number;
+    };
+    datacenterId: string;
+    cpu?: {
+        id: string;
+        vcpuCount: number;
+        priceUsdPerHour: number;
+    };
+    images: {
+        gpu: string;
+        cpu: string;
+    };
+    upload: {
+        files: number;
+        bytes: number;
+    };
+    maxLifetimeSeconds: number;
+    maxBudgetUsd: number;
+    cost: {
+        /** Hourly rate times the approved lifetime for every paid compute role. A ceiling, not a spend cap. */
+        worstCaseComputeUsd: number;
+        /** Container disk for the machines' lifetime; `null` when the provider publishes no rate. */
+        temporaryStorage: {
+            diskGb: number;
+            machines: number;
+            worstCaseUsd: number | null;
+        };
+        /** Retained network volume; billed monthly until deleted. `null` when the provider publishes no rate. */
+        recurringStorage: {
+            recurring: boolean;
+            volumeGb: number | null;
+            usdPerMonth: number | null;
+        };
+        /** What `maxBudgetUsd` is compared against: compute plus any temporary storage with a known rate. */
+        worstCaseBudgetedUsd: number;
+    };
+    /** Exactly what the budget guard covers, what it does not, and which costs have no known figure. */
+    budgetCoverage: {
+        counted: string[];
+        notCounted: string[];
+        unknown: string[];
+    };
+    /** `null` means no measured estimate exists; it is never guessed. */
+    timing: {
+        preparation: QuoteRange | null;
+        inference: QuoteRange | null;
+        transfer: QuoteRange | null;
+    };
+    /** Every warning here must be acknowledged by the user for the approval to be valid. */
+    warnings: QuoteWarning[];
+    disclosures: string[];
+    bindings: {
+        manifestDigest: string;
+        inputs: Array<{
+            role: string;
+            sha256: string;
+        }>;
+    };
+}
+export interface QuoteInputs {
+    provider: string;
+    manifest: ModelManifestV1;
+    cloud: CloudSpec;
+    catalog: CloudCatalog;
+    cachePolicy: CloudCachePolicy;
+    gpuId?: string;
+    datacenterId?: string;
+    maxBudgetUsd: number;
+    maxLifetimeSeconds: number;
+    inputs: Array<{
+        role: string;
+        sha256: string;
+        sizeBytes: number;
+    }>;
+    /** Datacenter of a compatible retained volume; persistent runs must stay there. */
+    existingVolumeDatacenterId?: string;
+}
+/** Pure: builds the quote shown to the user. Rejects over-budget quotes before anything is provisioned. */
+export declare function buildQuote(input: QuoteInputs): CloudQuote;
+export interface CloudApproval {
+    quoteId: string;
+    approvedAt: string;
+    /** Warning ids the user explicitly acknowledged; must include every `quote.warnings` id. */
+    acknowledged: CloudAcknowledgment[];
+}
+/**
+ * Verifies that what was approved is what is about to be provisioned: same quote id, not expired,
+ * and no material price rise or location change since. Throws before any resource is created.
+ */
+export declare function assertApprovalValid(approved: CloudQuote, approval: CloudApproval, fresh: CloudQuote, now?: Date): void;

package/dist/cloud/quote.js

@@ -0,0 +1,225 @@
+import { MoldeskError } from "../errors.js";
+import { digest } from "../hash.js";
+export const QUOTE_VERSION = 1;
+/** Approvals older than this are refused; the user must see a fresh quote. */
+export const APPROVAL_MAX_AGE_MS = 15 * 60 * 1000;
+/** A price rise above this fraction since approval requires a new approval. */
+export const PRICE_TOLERANCE = 0.1;
+/** Storage amounts below these absolute rises are noise, not a material change (USD). */
+export const STORAGE_NOISE_FLOOR_USD = 0.01;
+export const RECURRING_NOISE_FLOOR_USD_PER_MONTH = 0.1;
+/** Shown prominently before approval and must be explicitly acknowledged: there is no independent shutdown service. */
+export const LIFETIME_RISK_WARNING = "If MoleculeDesk closes or loses connection, your Runpod Pod may keep running and charging. Automatic shutdown is not guaranteed. Check your Runpod dashboard and terminate any remaining Pod.";
+export const STORAGE_CHARGES_WARNING = "Persistent caching keeps a network volume. Storage charges continue until you delete it (`moldesk cloud cache delete`, or in the Runpod dashboard).";
+export const DEFAULT_MAX_LIFETIME_SECONDS = 3600;
+/** Billing months are 730 hours. */
+const HOURS_PER_MONTH = 730;
+export const DEFAULT_PREP_CPU = { id: "cpu3c", vcpuCount: 2 };
+function rejected(code, message, remediation, details) {
+    return new MoldeskError({ code, message, remediation, details });
+}
+function datacenterSupports(dc, persistent) {
+    return dc !== undefined && (!persistent || dc.networkVolumeTypes.length > 0);
+}
+/** Cheapest eligible GPU in a datacenter that can host the policy; a user's explicit choice is validated, never silently replaced. */
+function chooseGpuAndDatacenter(input) {
+    const persistent = input.cachePolicy === "persistent";
+    const dcById = new Map(input.catalog.dataCenters.map((dc) => [dc.id, dc]));
+    const eligible = input.catalog.gpus.filter((gpu) => gpu.memoryGb >= input.cloud.minVramGb && gpu.priceUsdPerHour > 0 && gpu.availability !== "NONE");
+    if (input.gpuId) {
+        const gpu = input.catalog.gpus.find((candidate) => candidate.id === input.gpuId);
+        if (!gpu)
+            throw rejected("CLOUD_GPU_UNKNOWN", `GPU "${input.gpuId}" is not in the provider catalog.`, "Pick an id from the provider's GPU catalog.");
+        if (gpu.memoryGb < input.cloud.minVramGb) {
+            throw rejected("CLOUD_GPU_INELIGIBLE", `${gpu.name} has ${gpu.memoryGb} GB VRAM; ${input.manifest.name} needs at least ${input.cloud.minVramGb} GB.`, "Choose a larger GPU.");
+        }
+    }
+    const candidates = (input.gpuId ? eligible.filter((gpu) => gpu.id === input.gpuId) : eligible).sort((a, b) => a.priceUsdPerHour - b.priceUsdPerHour);
+    for (const gpu of candidates) {
+        const options = gpu.dataCenters
+            .filter((dc) => dc.availability !== "NONE")
+            .map((dc) => dc.id)
+            .filter((id) => datacenterSupports(dcById.get(id), persistent))
+            .filter((id) => !input.datacenterId || id === input.datacenterId)
+            .filter((id) => !input.existingVolumeDatacenterId || id === input.existingVolumeDatacenterId);
+        if (options.length > 0)
+            return { gpu, datacenterId: options[0] };
+    }
+    throw rejected("CLOUD_CAPACITY_UNAVAILABLE", "No eligible GPU currently has capacity in a compatible datacenter.", "Retry later, relax --gpu/--datacenter, or use an ephemeral cache policy if a persistent volume location is the constraint. Quotes never reserve capacity.", { cachePolicy: input.cachePolicy, minVramGb: input.cloud.minVramGb });
+}
+function chooseCpu(catalog) {
+    const type = catalog.cpus.find((cpu) => cpu.id === DEFAULT_PREP_CPU.id);
+    return type ? { type, vcpuCount: Math.max(DEFAULT_PREP_CPU.vcpuCount, type.minVcpu) } : undefined;
+}
+function requiredWarnings(persistent) {
+    return [
+        { id: "lifetime-risk", text: LIFETIME_RISK_WARNING },
+        ...(persistent ? [{ id: "storage-charges", text: STORAGE_CHARGES_WARNING }] : []),
+    ];
+}
+const round = (value) => Math.round(value * 10_000) / 10_000;
+/** Pure: builds the quote shown to the user. Rejects over-budget quotes before anything is provisioned. */
+export function buildQuote(input) {
+    if (!Number.isFinite(input.maxBudgetUsd) || input.maxBudgetUsd <= 0) {
+        throw rejected("CLOUD_BUDGET_REQUIRED", "A positive maximum budget is required.", "Pass --max-budget <usd>.");
+    }
+    if (!Number.isInteger(input.maxLifetimeSeconds) || input.maxLifetimeSeconds <= 0) {
+        throw rejected("CLOUD_LIFETIME_REQUIRED", "A positive maximum lifetime in seconds is required.", "Pass --max-lifetime <seconds>.");
+    }
+    const { gpu, datacenterId } = chooseGpuAndDatacenter(input);
+    const persistent = input.cachePolicy === "persistent";
+    const hours = input.maxLifetimeSeconds / 3600;
+    let cpu;
+    if (persistent && input.cloud.cpuAssetPreparation) {
+        const chosen = chooseCpu(input.catalog);
+        if (!chosen)
+            throw rejected("CLOUD_CPU_UNAVAILABLE", `CPU type ${DEFAULT_PREP_CPU.id} is not in the provider catalog.`, "Retry later or use an ephemeral cache policy.");
+        cpu = { id: chosen.type.id, vcpuCount: chosen.vcpuCount, priceUsdPerHour: round(chosen.type.priceUsdPerVcpuHour * chosen.vcpuCount) };
+    }
+    const worstCaseComputeUsd = round((gpu.priceUsdPerHour + (cpu?.priceUsdPerHour ?? 0)) * hours);
+    // Storage: only rates the provider actually publishes are used; everything else is stated as unknown.
+    const rates = input.catalog.storageRates;
+    const machines = cpu ? 2 : 1;
+    const diskGb = input.cloud.ephemeralDiskGb;
+    const diskRate = rates?.containerDiskUsdPerGbMonth;
+    const temporaryUsd = diskRate !== undefined ? round(diskGb * machines * diskRate * (hours / HOURS_PER_MONTH)) : null;
+    const volumeRate = rates?.networkVolumeUsdPerGbMonth;
+    const volumeGb = persistent ? input.cloud.volumeGb : null;
+    const volumeMonthlyUsd = persistent && volumeRate !== undefined ? round(input.cloud.volumeGb * volumeRate) : null;
+    const worstCaseBudgetedUsd = round(worstCaseComputeUsd + (temporaryUsd ?? 0));
+    const counted = [`GPU${cpu ? " and preparation-CPU" : ""} compute at catalog rates for up to ${input.maxLifetimeSeconds}s each`];
+    const notCounted = [];
+    const unknown = [];
+    if (temporaryUsd !== null)
+        counted.push(`container disk (${diskGb} GB x ${machines} machine${machines > 1 ? "s" : ""}) at the published rate`);
+    else {
+        notCounted.push(`container disk charges (${diskGb} GB x ${machines} machine${machines > 1 ? "s" : ""})`);
+        unknown.push("container disk rate is not published by the provider's catalog API");
+    }
+    if (persistent) {
+        notCounted.push(`retained network volume storage (${input.cloud.volumeGb} GB), billed monthly until deleted${volumeMonthlyUsd !== null ? `: about $${volumeMonthlyUsd}/month` : ""}`);
+        if (volumeMonthlyUsd === null)
+            unknown.push("network volume rate is not published by the provider's catalog API");
+    }
+    notCounted.push("network transfer or any other provider fees", "charges for time beyond the lifetime limit if a machine is not terminated");
+    if (worstCaseBudgetedUsd > input.maxBudgetUsd) {
+        throw rejected("CLOUD_BUDGET_EXCEEDED", `Worst-case cost counted against the budget, $${worstCaseBudgetedUsd} (${gpu.name} at $${gpu.priceUsdPerHour}/h for up to ${input.maxLifetimeSeconds}s${temporaryUsd !== null ? " plus container disk" : ""}), exceeds the $${input.maxBudgetUsd} budget.`, "Raise --max-budget, lower --max-lifetime, or choose a cheaper GPU. The budget is a guard on this estimate, not a provider-enforced cap.", { worstCaseBudgetedUsd, maxBudgetUsd: input.maxBudgetUsd });
+    }
+    const bindings = {
+        manifestDigest: digest(input.manifest),
+        inputs: input.inputs.map((file) => ({ role: file.role, sha256: file.sha256 })),
+    };
+    const id = digest({
+        v: QUOTE_VERSION,
+        provider: input.provider,
+        model: input.manifest.name,
+        modelVersion: input.manifest.modelVersion,
+        cachePolicy: input.cachePolicy,
+        gpuId: gpu.id,
+        datacenterId,
+        cpuId: cpu?.id ?? null,
+        images: input.cloud.images,
+        maxLifetimeSeconds: input.maxLifetimeSeconds,
+        maxBudgetUsd: input.maxBudgetUsd,
+        acknowledgments: requiredWarnings(persistent).map((warning) => warning.id),
+        bindings,
+    });
+    const disclosures = [
+        `Uploads ${input.inputs.length} input file(s) (${input.inputs.reduce((total, file) => total + file.sizeBytes, 0)} bytes) to ${input.provider} in ${datacenterId}.`,
+        `MoleculeDesk enforces the ${input.maxLifetimeSeconds}s lifetime limit and terminates machines only while it is running and connected, plus a best-effort watchdog inside the machine; results may be lost if the limit is reached before download.`,
+        "Capacity and price are not reserved by this quote.",
+    ];
+    if (persistent) {
+        disclosures.push("A network volume is created or reused and kept after the run; its storage is billed until you delete it with `moldesk cloud cache delete`.");
+    }
+    else {
+        disclosures.push("Model assets are downloaded again on every run; nothing is retained after cleanup.");
+    }
+    return {
+        version: QUOTE_VERSION,
+        id,
+        provider: input.provider,
+        retrievedAt: input.catalog.retrievedAt,
+        model: input.manifest.name,
+        modelVersion: input.manifest.modelVersion,
+        cachePolicy: input.cachePolicy,
+        gpu: { id: gpu.id, name: gpu.name, memoryGb: gpu.memoryGb, priceUsdPerHour: gpu.priceUsdPerHour },
+        datacenterId,
+        ...(cpu ? { cpu } : {}),
+        images: input.cloud.images,
+        upload: { files: input.inputs.length, bytes: input.inputs.reduce((total, file) => total + file.sizeBytes, 0) },
+        maxLifetimeSeconds: input.maxLifetimeSeconds,
+        maxBudgetUsd: input.maxBudgetUsd,
+        cost: {
+            worstCaseComputeUsd,
+            temporaryStorage: { diskGb, machines, worstCaseUsd: temporaryUsd },
+            recurringStorage: { recurring: persistent, volumeGb, usdPerMonth: volumeMonthlyUsd },
+            worstCaseBudgetedUsd,
+        },
+        budgetCoverage: { counted, notCounted, unknown },
+        timing: { preparation: null, inference: null, transfer: null },
+        warnings: requiredWarnings(persistent),
+        disclosures,
+        bindings,
+    };
+}
+/**
+ * Verifies that what was approved is what is about to be provisioned: same quote id, not expired,
+ * and no material price rise or location change since. Throws before any resource is created.
+ */
+export function assertApprovalValid(approved, approval, fresh, now = new Date()) {
+    if (approval.quoteId !== approved.id) {
+        throw rejected("CLOUD_APPROVAL_MISMATCH", "The approval does not match the quote.", "Review and approve the quote again.");
+    }
+    const missing = approved.warnings.filter((warning) => !approval.acknowledged?.includes(warning.id));
+    if (missing.length > 0) {
+        throw rejected("CLOUD_ACKNOWLEDGMENT_REQUIRED", `You must acknowledge: ${missing.map((warning) => warning.text).join(" ")}`, "Re-run and explicitly accept the risk (--accept-lifetime-risk, and --accept-storage-charges for persistent caching), or answer the prompts.", { missing: missing.map((warning) => warning.id) });
+    }
+    const approvedAt = Date.parse(approval.approvedAt);
+    if (!Number.isFinite(approvedAt) || approvedAt > now.getTime() + 60_000 || now.getTime() - approvedAt > APPROVAL_MAX_AGE_MS) {
+        throw rejected("CLOUD_APPROVAL_EXPIRED", "The approval has expired.", "Review and approve a fresh quote.");
+    }
+    if (fresh.id !== approved.id) {
+        throw rejected("CLOUD_REQUOTE_REQUIRED", "Inputs, model, GPU, location or limits changed since approval.", "Review and approve the new quote.", { approvedGpu: approved.gpu.id, approvedDatacenter: approved.datacenterId, freshGpu: fresh.gpu.id, freshDatacenter: fresh.datacenterId });
+    }
+    const rate = (quote) => quote.gpu.priceUsdPerHour + (quote.cpu?.priceUsdPerHour ?? 0);
+    if (rate(fresh) > rate(approved) * (1 + PRICE_TOLERANCE)) {
+        throw rejected("CLOUD_REQUOTE_REQUIRED", `The hourly price rose from $${round(rate(approved))} to $${round(rate(fresh))} since approval.`, "Review and approve the new quote.", { approvedRate: rate(approved), freshRate: rate(fresh) });
+    }
+    assertStorageAndCoverageUnchanged(approved, fresh);
+}
+/** What the budget does and does not cover, independent of the wording of the disclosures. */
+function coverageShape(quote) {
+    return {
+        diskGb: quote.cost.temporaryStorage.diskGb,
+        machines: quote.cost.temporaryStorage.machines,
+        diskCounted: quote.cost.temporaryStorage.worstCaseUsd !== null,
+        recurring: quote.cost.recurringStorage.recurring,
+        volumeGb: quote.cost.recurringStorage.volumeGb,
+        volumeRateKnown: quote.cost.recurringStorage.usdPerMonth !== null,
+        unknownCount: quote.budgetCoverage.unknown.length,
+    };
+}
+/**
+ * Approval covers what the user saw: the same costs counted, the same costs unknown, and storage
+ * amounts no more than a tolerance higher. An unknown rate becoming known (or the reverse) changes
+ * what the budget covers, so it needs a fresh approval even if the new figure looks small.
+ */
+function assertStorageAndCoverageUnchanged(approved, fresh) {
+    const before = coverageShape(approved);
+    const after = coverageShape(fresh);
+    const changed = Object.keys(before).filter((key) => before[key] !== after[key]);
+    if (changed.length > 0) {
+        throw rejected("CLOUD_REQUOTE_REQUIRED", `Storage cost coverage changed since approval (${changed.join(", ")}): costs that were ${before.diskCounted && after.diskCounted ? "" : "unknown or "}uncounted may now be known, or the reverse.`, "Review the new quote, including what the budget covers, and approve it again.", { changed, approved: before, fresh: after });
+    }
+    const risen = (from, to, floor) => from !== null && to !== null && to > from * (1 + PRICE_TOLERANCE) && to - from >= floor;
+    if (risen(approved.cost.temporaryStorage.worstCaseUsd, fresh.cost.temporaryStorage.worstCaseUsd, STORAGE_NOISE_FLOOR_USD)) {
+        throw rejected("CLOUD_REQUOTE_REQUIRED", `Container disk cost rose from $${approved.cost.temporaryStorage.worstCaseUsd} to $${fresh.cost.temporaryStorage.worstCaseUsd} since approval.`, "Review and approve the new quote.", { approved: approved.cost.temporaryStorage.worstCaseUsd, fresh: fresh.cost.temporaryStorage.worstCaseUsd });
+    }
+    if (risen(approved.cost.recurringStorage.usdPerMonth, fresh.cost.recurringStorage.usdPerMonth, RECURRING_NOISE_FLOOR_USD_PER_MONTH)) {
+        throw rejected("CLOUD_REQUOTE_REQUIRED", `Recurring volume storage rose from $${approved.cost.recurringStorage.usdPerMonth}/month to $${fresh.cost.recurringStorage.usdPerMonth}/month since approval.`, "Review and approve the new quote.", { approved: approved.cost.recurringStorage.usdPerMonth, fresh: fresh.cost.recurringStorage.usdPerMonth });
+    }
+    if (risen(approved.cost.worstCaseBudgetedUsd, fresh.cost.worstCaseBudgetedUsd, STORAGE_NOISE_FLOOR_USD)) {
+        throw rejected("CLOUD_REQUOTE_REQUIRED", `The worst-case cost counted against the budget rose from $${approved.cost.worstCaseBudgetedUsd} to $${fresh.cost.worstCaseBudgetedUsd} since approval.`, "Review and approve the new quote.", { approved: approved.cost.worstCaseBudgetedUsd, fresh: fresh.cost.worstCaseBudgetedUsd });
+    }
+}

package/dist/cloud/quote.test.d.ts

@@ -0,0 +1 @@
+export {};