@substrat-run/control-plane-api 0.159.0 → 0.161.0

package/dist/wire-upload.js

@@ -0,0 +1,141 @@
+/**
+ * The uploader's half of RFC wire-signing step 2 (follow-on 3): what one upload gives the deployment
+ * it goes to, and the capability record of it (§5, §6, §7, Q8).
+ *
+ * A deployment is given both issuers' public key lists, its own dispatch name for the audience
+ * check and the state `dual`, all plain configuration, rewritten on every upload. Nothing is given
+ * until the control plane's `WIRE_KEYS_ROLLOUT` says so: unset or `off` gives no deployment lists,
+ * `canary:<vertical>` gives them to that one vertical's deployments only (the single canary the RFC
+ * puts first in each environment), and `fleet` to every deployment. A setting that cannot be read
+ * gives nothing. So with the setting unset, every upload is what it was before this existed.
+ *
+ * The lists are judged before they are given, by the function the platform's entry loads them with
+ * (`wireUploadSettings`), so a deployment is never given lists its verifier would refuse: the upload
+ * gives nothing instead, and says why. No code here can give a state other than `dual`: moving a
+ * deployment to `signed-only` is the flip, a later and separate step.
+ *
+ * Every upload has a record, given lists or not, written from what the uploader built: whether the
+ * bundle carries the platform's entry (which holds the verifier), the state, the audience and the key
+ * ids, or why nothing was given. The vertical never declares any of it.
+ */
+import { verticalSlug } from '@substrat-run/contracts';
+import { wireUploadSettings, wireVerificationKeys, WIRE_ENVELOPE_VERSION, WIRE_UPLOAD_STATE } from '@substrat-run/contracts/wire-signing';
+import { platformEntrySkipReason } from './platform-entry.js';
+const CANARY = 'canary:';
+/**
+ * The rollout setting's one reading. Unset, empty or `off` is off; `fleet` is every deployment;
+ * `canary:<vertical>` is one vertical, named as the registry names it. Anything else is refused
+ * with the reason, a second vertical in a canary included: the RFC's canary is one, before the rest.
+ */
+export function wireKeysRolloutOf(value) {
+    if (value === undefined || value === null)
+        return { kind: 'off' };
+    if (typeof value !== 'string')
+        return { refused: 'the rollout setting is not text' };
+    const text = value.trim();
+    if (text === '' || text === 'off')
+        return { kind: 'off' };
+    if (text === 'fleet')
+        return { kind: 'fleet' };
+    if (!text.startsWith(CANARY))
+        return { refused: 'the rollout setting is `off`, `canary:<vertical>` or `fleet`' };
+    const vertical = text.slice(CANARY.length).trim();
+    if (/[,\s]/.test(vertical))
+        return { refused: 'a canary names one vertical' };
+    if (!verticalSlug.safeParse(vertical).success)
+        return { refused: 'a canary names a vertical by its registry slug' };
+    return { kind: 'canary', vertical };
+}
+/**
+ * What the upload of `bundle` to the script `deploymentRef`, a deployment of `vertical`, gives it
+ * under `settings`, and the record of it. Gives nothing while the rollout is off or leaves the
+ * vertical out, while the setting cannot be read, or while the lists would not load.
+ */
+export async function wireUploadFor(settings, upload) {
+    return wireUploadGiven(settings, { vertical: upload.vertical, deploymentRef: upload.deploymentRef, entry: wireEntryOf(upload.bundle) });
+}
+/** Whether a bundle carries the platform's entry, which holds the verifier, as a record states it. */
+export function wireEntryOf(bundle) {
+    const skipped = platformEntrySkipReason(bundle) ?? null;
+    return { envelope: skipped === null ? WIRE_ENVELOPE_VERSION : null, entrySkipped: skipped };
+}
+/**
+ * `wireUploadFor` from a bundle's entry state already known (`wireEntryOf`, or a record of the
+ * script's upload): what the settings give the script now, and the record of it. The fleet walk's
+ * reading of the same rule, so a walked script and an uploaded one are given the same.
+ */
+export async function wireUploadGiven(settings, upload) {
+    const { vertical, deploymentRef } = upload;
+    const entry = { envelope: upload.entry.envelope, entrySkipped: upload.entry.entrySkipped };
+    const nothing = (withheld, refusal = null) => ({
+        vertical,
+        deploymentRef,
+        bindings: [],
+        record: { ...entry, state: 'legacy-only', audience: null, routerKids: [], platformKids: [], withheld },
+        refusal,
+    });
+    const rollout = wireKeysRolloutOf(settings?.rollout);
+    if ('refused' in rollout)
+        return nothing('rollout-refused', rollout.refused);
+    if (rollout.kind === 'off')
+        return nothing('unconfigured');
+    if (rollout.kind === 'canary' && rollout.vertical !== vertical)
+        return nothing('not-in-rollout');
+    try {
+        const given = await wireUploadSettings({
+            routerKeys: settings?.routerKeys ?? '',
+            platformKeys: settings?.platformKeys ?? '',
+            audience: deploymentRef,
+        });
+        return {
+            vertical,
+            deploymentRef,
+            bindings: given.settings.map((setting) => ({ type: 'plain_text', ...setting })),
+            record: { ...entry, state: WIRE_UPLOAD_STATE, audience: deploymentRef, routerKids: given.routerKids, platformKids: given.platformKids, withheld: null },
+            refusal: null,
+        };
+    }
+    catch (error) {
+        return nothing('lists-refused', await refusedList(settings, error));
+    }
+}
+/**
+ * Whether the settings themselves are refused: the rollout setting does not parse, or, where it gives
+ * lists to anything, the lists do not load. `null` when they are usable, `off` included. An upload under
+ * refused settings gives nothing and says why; the fleet walk refuses the whole pass instead, since
+ * giving nothing to every script would withdraw the lists fleet-wide. The decision is the uploader's
+ * own (`wireUploadGiven`, asked for a deployment inside the rollout), so the two cannot drift; the
+ * reason names the setting, never a key.
+ */
+export async function wireSettingsRefusal(settings) {
+    const rollout = wireKeysRolloutOf(settings?.rollout);
+    const vertical = 'refused' in rollout || rollout.kind !== 'canary' ? 'wire-settings-check' : rollout.vertical;
+    const given = await wireUploadGiven(settings, { vertical, deploymentRef: 'wire-settings-check', entry: { envelope: 1, entrySkipped: null } });
+    const withheld = given.record.withheld;
+    return given.refusal !== null && (withheld === 'rollout-refused' || withheld === 'lists-refused') ? { withheld, reason: given.refusal } : null;
+}
+/**
+ * Why the lists were refused, naming the setting to fix: each list is loaded alone, and the first
+ * that fails is named with its problem. When each loads alone (a key in both, or an audience the
+ * encoder would not carry), the refusal is the one given. The parser's messages are fixed text
+ * naming a problem, never a key.
+ */
+async function refusedList(settings, error) {
+    const problem = (e) => (e instanceof Error ? e.message : 'the list did not load').replace(/^a store public key/, 'a public key');
+    for (const [name, router, platform] of [
+        ['WIRE_ROUTER_PUBLIC_KEYS', settings?.routerKeys, undefined],
+        ['WIRE_PLATFORM_PUBLIC_KEYS', undefined, settings?.platformKeys],
+    ]) {
+        const list = router ?? platform;
+        if (!list?.trim())
+            return `${name} lists no key`;
+        try {
+            await wireVerificationKeys({ router, platform });
+        }
+        catch (e) {
+            return `${name}: ${problem(e)}`;
+        }
+    }
+    return problem(error);
+}
+//# sourceMappingURL=wire-upload.js.map

package/dist/wire-upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-upload.js","sourceRoot":"","sources":["../src/wire-upload.ts"],"names":[],"mappings":"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"}

package/dist/wire-walk.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The fleet walk (RFC wire-signing follow-on 4): bring every deployed script's key lists, audience
+ * and state to what the control plane gives now, so that a key listed, rotated, dropped or withdrawn
+ * reaches every script, not only the ones an upload happens to reach. A vertical's serving script is
+ * uploaded again at each promote, but a version's own script (its archive script, which a preview is
+ * routed to) is uploaded once, at its push, and nothing else ever rewrites it.
+ *
+ * A person runs it, a pass at a time, and it reports before it changes anything:
+ *
+ * - **Dry run by default.** Without `apply` a pass only reads: the settings write is unreachable, no
+ *   operational failure is filed and no hold is released.
+ * - **Bounded and resumable.** A pass walks at most `limit` scripts in a fixed order (verticals by
+ *   slug; each one's serving script, then its versions' scripts by id) and answers the cursor the next
+ *   pass starts from, `null` when the fleet is done. A vertical deleted since it was listed, or named by
+ *   a saved cursor, is passed over.
+ * - **Only scripts it can attribute.** The inventory is the registry's: a vertical's serving script and
+ *   each of its versions' scripts. A script the registry does not name is never touched, nor is one
+ *   whose name is the platform's own.
+ * - **No call it does not need.** A script whose record already says it was given what the settings give
+ *   now is not read. A script with no record, which the settings give nothing, is not read either: in an
+ *   environment where the rollout was never set, a pass makes no call to the runtime at all. A
+ *   **confirming** pass (`confirm`) reads every recorded script instead, trusting no record; a held
+ *   script, and one with no record that nothing is given or that is skipped, it leaves unread as well.
+ * - **Only a script that verifies is given lists by it.** A script with no record is read back first, on
+ *   every pass that reaches it (no verdict is kept between passes: pushing it again gives it a record);
+ *   one that runs without the platform's entry is skipped (`no-entry`), never recorded as verifying.
+ * - **One script's failure is that script's.** It is reported, recorded as an operational failure by
+ *   reason, and the pass goes on.
+ * - **A script it cannot vouch for is held.** When the read after an update differs, or the serve moved
+ *   under it, the script's record is marked held, with the binding names that differed, and later passes
+ *   leave it alone until a person names it in `release`, or an upload of it writes a fresh record.
+ *
+ * Each script it changes writes its capability record and that record's admin row in one directory
+ * transaction (`recordWireAuth`), and each pass writes one `walkWireAuth` row. The settings write is
+ * `wire-settings.ts`. Do not run the walk while a push or promote of the same vertical is in flight,
+ * and end with a confirming pass.
+ */
+import { type PlatformActorId } from '@substrat-run/contracts';
+import type { HostAdmin } from '@substrat-run/kernel';
+import type { FetchVerticalModulesFn } from './deploy.js';
+import { type WireSettingsApi } from './wire-settings.js';
+import { type WireUploadSettings } from './wire-upload.js';
+/** A pass walks this many scripts when it names no limit. */
+export declare const WIRE_WALK_LIMIT_DEFAULT = 25;
+/** A pass walks at most this many scripts. */
+export declare const WIRE_WALK_LIMIT_MAX = 50;
+/** A pass releases at most this many held scripts. */
+export declare const WIRE_WALK_RELEASE_MAX = 50;
+/**
+ * Where a pass starts: inside a vertical, after its serving script (`after` empty) or after one of its
+ * versions (`after` that version's id, whatever its spelling: the publish route takes any id).
+ */
+export interface WireWalkCursor {
+    readonly vertical: string;
+    readonly after: string;
+}
+/**
+ * A cursor as a pass answers it, or `null` for one that is not one. Opaque to a caller. A slug never
+ * holds a `|`, so the first one ends it, and everything after it is the position.
+ */
+export declare function parseWireWalkCursor(text: string): WireWalkCursor | null;
+/** What a pass did, or in a dry run would do, with one script. */
+export type WireWalkAction = 
+/** Its record says it was given what the settings give now: not read. */
+'current'
+/** No record, and the settings give it nothing: not read. */
+ | 'unrecorded'
+/** Held by an earlier pass and not released: not read. */
+ | 'held'
+/** Not given lists, for `reason`: `no-entry`, a script with no record that runs without the platform's entry. */
+ | 'skipped'
+/** Read: it already carries what the settings give now. Applied, its record is refreshed. */
+ | 'unchanged'
+/** A dry run: these settings would change. */
+ | 'would-change'
+/** Updated, verified and recorded. */
+ | 'updated'
+/** Not done, for `reason`; held as well when the reason says the script could not be vouched for. */
+ | 'failed';
+export interface WireWalkScript {
+    readonly deploymentRef: string;
+    readonly vertical: string;
+    readonly versionId: string | null;
+    readonly kind: 'serving' | 'version';
+    readonly action: WireWalkAction;
+    /** The settings that differ (`would-change`, `updated`), by name. */
+    readonly changes?: readonly string[];
+    /**
+     * Why it failed (`concurrent-change`, `serve-in-flight`, `verify`, `entry-unknown`, `settings`,
+     * `settings-refused` or `record`), or was skipped (`no-entry`).
+     */
+    readonly reason?: string;
+    /** For `verify`: the binding names that differed. Never a value. */
+    readonly bindings?: readonly string[];
+    /** For `verify`: how many more bindings differed than `bindings` names (it keeps the first `WALK_HOLD_BINDINGS_MAX`). */
+    readonly more?: number;
+    /** Whether the pass left the script held. */
+    readonly held?: true;
+    /** Whether it was held and a person released it for this pass. */
+    readonly released?: true;
+}
+export interface WireWalkPass {
+    readonly apply: boolean;
+    /** The cursor the pass started from, `null` for the start of the fleet. */
+    readonly from: string | null;
+    /** Where the next pass starts, or `null` when this one reached the end of the fleet. */
+    readonly next: string | null;
+    readonly scripts: readonly WireWalkScript[];
+}
+export interface WireWalkDeps {
+    readonly admin: HostAdmin;
+    readonly actor: PlatformActorId;
+    readonly settings: WireUploadSettings | undefined;
+    readonly api: WireSettingsApi;
+    /** Reads a script's modules back, to learn whether a script with no record carries the platform's entry. */
+    readonly fetchModules?: FetchVerticalModulesFn;
+    /** Records a script's failure as an operational failure: names, reasons and binding names only. */
+    readonly fail: (entry: {
+        readonly vertical: string;
+        readonly version: string | null;
+        readonly stage: string;
+        readonly message: string;
+    }) => void;
+    readonly now?: () => Date;
+}
+/** Run one pass. Never throws for one script's failure; throws only for a directory read that fails. */
+export declare function runWireWalk(deps: WireWalkDeps, input: {
+    readonly apply: boolean;
+    readonly cursor: WireWalkCursor | null;
+    readonly limit: number;
+    readonly release: readonly string[];
+    /** A confirming pass: read every recorded script, never trusting its record (no `current`). */
+    readonly confirm?: boolean;
+    /**
+     * Where each script's result is put as soon as it is known: the caller's, so a pass that ends in a
+     * throw still says what it did. Defaults to a fresh list.
+     */
+    readonly sink?: WireWalkScript[];
+}): Promise<WireWalkPass>;
+//# sourceMappingURL=wire-walk.d.ts.map

package/dist/wire-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-walk.d.ts","sourceRoot":"","sources":["../src/wire-walk.ts"],"names":[],"mappings":"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"}

package/dist/wire-walk.js

@@ -0,0 +1,339 @@
+/**
+ * The fleet walk (RFC wire-signing follow-on 4): bring every deployed script's key lists, audience
+ * and state to what the control plane gives now, so that a key listed, rotated, dropped or withdrawn
+ * reaches every script, not only the ones an upload happens to reach. A vertical's serving script is
+ * uploaded again at each promote, but a version's own script (its archive script, which a preview is
+ * routed to) is uploaded once, at its push, and nothing else ever rewrites it.
+ *
+ * A person runs it, a pass at a time, and it reports before it changes anything:
+ *
+ * - **Dry run by default.** Without `apply` a pass only reads: the settings write is unreachable, no
+ *   operational failure is filed and no hold is released.
+ * - **Bounded and resumable.** A pass walks at most `limit` scripts in a fixed order (verticals by
+ *   slug; each one's serving script, then its versions' scripts by id) and answers the cursor the next
+ *   pass starts from, `null` when the fleet is done. A vertical deleted since it was listed, or named by
+ *   a saved cursor, is passed over.
+ * - **Only scripts it can attribute.** The inventory is the registry's: a vertical's serving script and
+ *   each of its versions' scripts. A script the registry does not name is never touched, nor is one
+ *   whose name is the platform's own.
+ * - **No call it does not need.** A script whose record already says it was given what the settings give
+ *   now is not read. A script with no record, which the settings give nothing, is not read either: in an
+ *   environment where the rollout was never set, a pass makes no call to the runtime at all. A
+ *   **confirming** pass (`confirm`) reads every recorded script instead, trusting no record; a held
+ *   script, and one with no record that nothing is given or that is skipped, it leaves unread as well.
+ * - **Only a script that verifies is given lists by it.** A script with no record is read back first, on
+ *   every pass that reaches it (no verdict is kept between passes: pushing it again gives it a record);
+ *   one that runs without the platform's entry is skipped (`no-entry`), never recorded as verifying.
+ * - **One script's failure is that script's.** It is reported, recorded as an operational failure by
+ *   reason, and the pass goes on.
+ * - **A script it cannot vouch for is held.** When the read after an update differs, or the serve moved
+ *   under it, the script's record is marked held, with the binding names that differed, and later passes
+ *   leave it alone until a person names it in `release`, or an upload of it writes a fresh record.
+ *
+ * Each script it changes writes its capability record and that record's admin row in one directory
+ * transaction (`recordWireAuth`), and each pass writes one `walkWireAuth` row. The settings write is
+ * `wire-settings.ts`. Do not run the walk while a push or promote of the same vertical is in flight,
+ * and end with a confirming pass.
+ */
+import { errorCodeOf, instant, LIST_PAGE_MAX, PLATFORM_SCRIPT_NAMES, storedDeployManifest, verticalSlug as verticalSlugSchema, WALK_HOLD_BINDINGS_MAX, } from '@substrat-run/contracts';
+import { PLATFORM_ENTRY_MODULE } from './platform-entry.js';
+import { applyWireSettings, CONCURRENT_RETRIES } from './wire-settings.js';
+import { wireEntryOf, wireUploadGiven } from './wire-upload.js';
+/** A pass walks this many scripts when it names no limit. */
+export const WIRE_WALK_LIMIT_DEFAULT = 25;
+/** A pass walks at most this many scripts. */
+export const WIRE_WALK_LIMIT_MAX = 50;
+/** A pass releases at most this many held scripts. */
+export const WIRE_WALK_RELEASE_MAX = 50;
+const PAGE = 50;
+const GONE = Symbol('gone');
+/** The cursor's position inside a vertical just after its serving script: nothing after the `|`. */
+const AFTER_SERVING = '';
+/**
+ * A cursor as a pass answers it, or `null` for one that is not one. Opaque to a caller. A slug never
+ * holds a `|`, so the first one ends it, and everything after it is the position.
+ */
+export function parseWireWalkCursor(text) {
+    const at = text.indexOf('|');
+    if (at <= 0)
+        return null;
+    const vertical = text.slice(0, at);
+    if (!verticalSlugSchema.safeParse(vertical).success)
+        return null;
+    return { vertical, after: text.slice(at + 1) };
+}
+const cursorText = (vertical, after) => `${vertical}|${after}`;
+/** The registry's scripts in walk order, from `from` on: each vertical's serving script, then its versions' scripts. */
+async function* inventory(admin, actor, from) {
+    /** A directory read of one vertical, or `gone` when the vertical no longer exists (deleted since it was listed, or named by a saved cursor). */
+    const ofVertical = async (read) => {
+        try {
+            return await read();
+        }
+        catch (error) {
+            if (errorCodeOf(error) === 'not_found')
+                return GONE;
+            throw error;
+        }
+    };
+    async function* scriptsOf(vertical, after) {
+        const serving = await ofVertical(() => admin.verticalServing(actor, vertical));
+        if (serving === GONE)
+            return;
+        const servingRef = serving && !PLATFORM_SCRIPT_NAMES.has(serving.ref) ? serving.ref : null;
+        if (after === null && servingRef !== null) {
+            yield { vertical, deploymentRef: servingRef, versionId: serving.versionId, kind: 'serving', cursor: cursorText(vertical, AFTER_SERVING) };
+        }
+        let cursor = after !== null && after !== AFTER_SERVING ? after : undefined;
+        for (;;) {
+            const versions = await ofVertical(() => admin.listVersions(actor, vertical, { limit: PAGE, ...(cursor ? { cursor } : {}) }));
+            if (versions === GONE)
+                return;
+            for (const v of versions) {
+                const ref = v.deploymentRef;
+                if (ref === null || ref === servingRef || PLATFORM_SCRIPT_NAMES.has(ref))
+                    continue;
+                yield { vertical, deploymentRef: ref, versionId: v.id, kind: 'version', cursor: cursorText(vertical, v.id) };
+            }
+            if (versions.length < PAGE)
+                return;
+            cursor = versions.at(-1).id;
+        }
+    }
+    let slugCursor;
+    if (from) {
+        yield* scriptsOf(from.vertical, from.after);
+        slugCursor = from.vertical;
+    }
+    for (;;) {
+        const verticals = await admin.listVerticals(actor, { limit: PAGE, ...(slugCursor ? { cursor: slugCursor } : {}) });
+        for (const v of verticals)
+            yield* scriptsOf(v.slug, null);
+        if (verticals.length < PAGE)
+            return;
+        slugCursor = verticals.at(-1).slug;
+    }
+}
+/** Whether a record already holds what a given record says, in what a script carries: the state, the audience and the key ids. */
+function carriesAlready(stored, given) {
+    const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+    return (stored.state === given.state &&
+        stored.audience === given.audience &&
+        same(stored.routerKids, given.routerKids) &&
+        same(stored.platformKids, given.platformKids));
+}
+/** Run one pass. Never throws for one script's failure; throws only for a directory read that fails. */
+export async function runWireWalk(deps, input) {
+    const { admin, actor, settings, api } = deps;
+    const now = deps.now ?? (() => new Date());
+    const release = new Set(input.apply ? input.release : []);
+    const recordsBy = async (vertical) => {
+        const held = new Map();
+        let cursor;
+        for (;;) {
+            const page = await admin.listWireAuth(actor, { reach: { fleet: true }, verticalSlug: vertical, limit: LIST_PAGE_MAX, ...(cursor ? { cursor } : {}) });
+            for (const r of page)
+                held.set(r.deploymentRef, r);
+            if (page.length < LIST_PAGE_MAX)
+                return held;
+            cursor = page.at(-1).deploymentRef;
+        }
+    };
+    const records = new Map();
+    const recordsOf = async (vertical) => {
+        let held = records.get(vertical);
+        if (held)
+            return held;
+        held = await recordsBy(vertical);
+        records.clear(); // one vertical at a time: the walk moves through them in order
+        records.set(vertical, held);
+        return held;
+    };
+    const record = (script, rec, versionId = script.versionId) => admin.recordWireAuth(actor, { deploymentRef: script.deploymentRef, verticalSlug: script.vertical, versionId, record: rec, recordedAt: now().toISOString() });
+    /**
+     * Whether the script carries the platform's entry, which holds the verifier, read back from the
+     * script itself: its modules must hold the entry module, and its own bundle must be one the entry
+     * wraps. `no-manifest` when it cannot be told; `no-entry` when the script runs without one.
+     */
+    const entryOf = async (script) => {
+        if (!deps.fetchModules || script.versionId === null)
+            return 'no-manifest';
+        const manifestJson = await admin.versionManifest(actor, script.vertical, script.versionId);
+        if (!manifestJson)
+            return 'no-manifest';
+        const manifest = storedDeployManifest.parse(JSON.parse(manifestJson));
+        const modules = await deps.fetchModules(script.deploymentRef);
+        if (!modules.some((m) => m.name === PLATFORM_ENTRY_MODULE))
+            return 'no-entry';
+        const entry = wireEntryOf({ entry: manifest.entry, modules });
+        return entry.envelope === null ? 'no-entry' : entry;
+    };
+    const walkOne = async (script) => {
+        const stored = (await recordsOf(script.vertical)).get(script.deploymentRef);
+        const wasHeld = stored?.record.walkHold !== undefined;
+        const base = { deploymentRef: script.deploymentRef, vertical: script.vertical, versionId: script.versionId, kind: script.kind };
+        if (wasHeld && !release.has(script.deploymentRef))
+            return { ...base, action: 'held' };
+        /** A failure: reported, and recorded as an operational failure when the pass applies (a dry run attempts nothing). */
+        const failed = (reason, message, extra = {}) => {
+            if (input.apply) {
+                deps.fail({ vertical: script.vertical, version: script.versionId, stage: reason, message: `the wire walk did not bring '${script.deploymentRef}' current: ${message}` });
+            }
+            return { ...base, action: 'failed', reason, ...extra };
+        };
+        /**
+         * Mark the script held: a script the walk wrote and could not confirm is never left without one.
+         * It holds the record as it stands now, read again (an upload's record written during the pass
+         * included, which the hold keeps and marks), or, with none, a record that claims no lists
+         * (`unverified`). It keeps the first `WALK_HOLD_BINDINGS_MAX` binding names and counts the rest.
+         * A write that fails is tried once more; answers whether the hold was written, and the failure the
+         * walk reports says so when it was not.
+         */
+        const hold = async (entry, reason, bindings) => {
+            const once = async () => {
+                const latest = (await recordsBy(script.vertical)).get(script.deploymentRef);
+                const known = latest
+                    ? (({ walkHold: _previous, ...rest }) => rest)(latest.record)
+                    : { ...entry, state: 'legacy-only', audience: null, routerKids: [], platformKids: [], withheld: 'unverified' };
+                const kept = bindings.slice(0, WALK_HOLD_BINDINGS_MAX);
+                const more = bindings.length - kept.length;
+                const walkHold = { reason, bindings: [...kept], ...(more > 0 ? { more } : {}), at: instant.parse(now().toISOString()) };
+                // Under the version the record it marks names: an upload's record keeps its upload's version.
+                await record(script, { ...known, walkHold }, latest ? latest.versionId : script.versionId);
+            };
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    await once();
+                    return true;
+                }
+                catch {
+                    // Tried once more, then reported.
+                }
+            }
+            return false;
+        };
+        /** Binding names for a person to read: the first `WALK_HOLD_BINDINGS_MAX`, and how many more. */
+        const named = (bindings) => bindings.length > WALK_HOLD_BINDINGS_MAX
+            ? `${bindings.slice(0, WALK_HOLD_BINDINGS_MAX).join(', ')} and ${bindings.length - WALK_HOLD_BINDINGS_MAX} more`
+            : bindings.join(', ');
+        const holdNote = (held) => (held ? 'held until a person looks' : 'and the hold itself could not be written: look at it now');
+        try {
+            let entry = stored ? { envelope: stored.record.envelope, entrySkipped: stored.record.entrySkipped } : null;
+            if (!entry) {
+                // No record: an upload from before records existed, or one whose record was not written. The
+                // settings decide whether it needs reading at all; whether it carries the entry needs its bundle.
+                const probe = await wireUploadGiven(settings, { vertical: script.vertical, deploymentRef: script.deploymentRef, entry: { envelope: 1, entrySkipped: null } });
+                if (probe.bindings.length === 0)
+                    return { ...base, action: 'unrecorded' };
+                const read = await entryOf(script);
+                if (read === 'no-manifest')
+                    return failed('entry-unknown', 'no record, and no stored manifest to read its entry from: upload it again');
+                // It runs without the platform's entry, so nothing in it verifies: it is not given lists, nor
+                // recorded as verifying. Pushing it again wraps it.
+                if (read === 'no-entry')
+                    return { ...base, action: 'skipped', reason: 'no-entry' };
+                entry = read;
+            }
+            const given = await wireUploadGiven(settings, { vertical: script.vertical, deploymentRef: script.deploymentRef, entry });
+            // Refused settings give nothing, and nothing is not a withdrawal to write: the route refuses such a
+            // pass before it starts, and a script never acts on one here either.
+            // The route refuses a pass under refused settings before it starts, so what is refused here is
+            // this script alone (its name is not one the lists can be given as an audience).
+            if (given.refusal !== null)
+                return failed('settings-refused', `the lists are refused for this script (${given.refusal}): nothing was written`);
+            if (!input.confirm && stored && !stored.record.walkHold && carriesAlready(stored.record, given.record))
+                return { ...base, action: 'current' };
+            let outcome;
+            try {
+                outcome = await applyWireSettings(api, script.deploymentRef, given.bindings.map((b) => ({ name: b.name, text: b.text })), {
+                    apply: input.apply,
+                    ...(script.kind === 'serving' && script.versionId !== null
+                        ? {
+                            servedVersion: script.versionId,
+                            servedVersionAfter: async () => (await admin.verticalServing(actor, script.vertical))?.versionId ?? null,
+                        }
+                        : {}),
+                });
+            }
+            catch (error) {
+                // The settings API's own messages name the script and a status, never a value.
+                return failed('settings', error instanceof Error ? error.message : 'the settings call failed');
+            }
+            switch (outcome.outcome) {
+                case 'would-change':
+                    return { ...base, action: 'would-change', changes: outcome.changes };
+                case 'unchanged':
+                case 'updated': {
+                    if (input.apply) {
+                        try {
+                            await record(script, given.record);
+                        }
+                        catch {
+                            return failed('record', 'its settings are current, but its record was not written');
+                        }
+                    }
+                    return outcome.outcome === 'updated' ? { ...base, action: 'updated', changes: outcome.changes } : { ...base, action: 'unchanged' };
+                }
+                case 'concurrent-change':
+                    return failed('concurrent-change', `its bindings changed between reads ${CONCURRENT_RETRIES} times; nothing was written`);
+                case 'serve-in-flight': {
+                    if (!outcome.written)
+                        return failed('serve-in-flight', 'it does not run the version the directory says it serves; nothing was written: promote again, then walk');
+                    const held = await hold(entry, 'serve-in-flight', []);
+                    return failed('serve-in-flight', `the served version moved while it was updated, ${holdNote(held)}; ${held ? 'promote again, then release it' : 'promote again'}`, held ? { held: true } : {});
+                }
+                case 'verify': {
+                    const held = await hold(entry, 'verify', outcome.bindings);
+                    return failed('verify', `after its update, these bindings read differently: ${named(outcome.bindings)}; ${holdNote(held)}`, {
+                        bindings: outcome.bindings.slice(0, WALK_HOLD_BINDINGS_MAX),
+                        ...(outcome.bindings.length > WALK_HOLD_BINDINGS_MAX ? { more: outcome.bindings.length - WALK_HOLD_BINDINGS_MAX } : {}),
+                        ...(held ? { held: true } : {}),
+                    });
+                }
+            }
+        }
+        catch {
+            // A read for this one script (its stored manifest, its modules) failed. Its text is not echoed:
+            // nothing here vouches that it carries no value.
+            return failed('entry-unknown', 'its stored manifest or its modules could not be read');
+        }
+    };
+    /**
+     * One script, and whether a person's release of it took: only a script that was held and came out
+     * current (its fresh record, with no hold, written) is `released`; one that failed again stays held.
+     */
+    const walkReleasing = async (script) => {
+        const result = await walkOne(script);
+        const wasHeld = (await recordsOf(script.vertical)).get(script.deploymentRef)?.record.walkHold !== undefined;
+        const current = result.action === 'updated' || result.action === 'unchanged';
+        return wasHeld && release.has(script.deploymentRef) && current ? { ...result, released: true } : result;
+    };
+    const scripts = input.sink ?? [];
+    let next = null;
+    const fleet = inventory(admin, actor, input.cursor);
+    try {
+        let step = await fleet.next();
+        while (!step.done) {
+            const script = step.value;
+            scripts.push(await walkReleasing(script));
+            if (scripts.length >= input.limit) {
+                // Looked one ahead, so the pass that ends on the fleet's last script answers `null`. A look
+                // that fails does not undo a pass that is done: the next one starts after its last script.
+                try {
+                    step = await fleet.next();
+                    next = step.done ? null : script.cursor;
+                }
+                catch {
+                    next = script.cursor;
+                }
+                break;
+            }
+            step = await fleet.next();
+        }
+    }
+    finally {
+        await fleet.return(undefined).catch(() => undefined);
+    }
+    return { apply: input.apply, from: input.cursor ? cursorText(input.cursor.vertical, input.cursor.after) : null, next, scripts };
+}
+//# sourceMappingURL=wire-walk.js.map