@substrat-run/control-plane-api 0.147.0 → 0.148.0

package/dist/store-releases.d.ts

@@ -0,0 +1,147 @@
+/**
+ * A store kind's releases: stored, canaried, rolled out and rolled back (D-63, #2300).
+ *
+ * The bytes live outside the directory, content-addressed under `<kind>/<sha256>`, where the
+ * sha256 is `storeKindReleaseDigest` of the bundle, computed here when it arrives and again by
+ * the ensurer before every upload of it, restore and rollback included. The directory holds who
+ * uploaded which release from which commit, every rollout, and the current good release
+ * (`store-kind-releases.ts` in the kernel).
+ *
+ * A rollout is one request across a fleet. It holds the kind exclusively for its whole length,
+ * renewing the hold before every upload, so no push or serve rebuilds a script between the
+ * rollout's read and its upload, and two rollouts never interleave. It canaries the release on the
+ * platform's own object first, and no vertical's script moves unless every reserved operation
+ * answered there. Then it moves each vertical that ever declared the kind, at most
+ * {@link ROLLOUT_VERTICALS_PER_REQUEST} uploads per request. A bigger fleet ends the request
+ * `paused`, and posting the same rollout (or rollback) again continues it, walking past the scripts
+ * already there. A request that stops on a failure ends `failed` or `diverged`. One request walks at
+ * most {@link ROLLOUT_FLEET_MAX} verticals, a rollback included, until #2312.
+ */
+import { type PlatformActorId, type ReservedStoreOperation, type ScopeStoreNeed, type StoreKindRegistration } from '@substrat-run/contracts';
+import { type HostAdmin, type StoreKindRolloutAction, type StoreKindRolloutRecord } from '@substrat-run/kernel';
+import type { ScopeStoreEnsurerOptions, StoreKindReleaseArtifact } from './store-script.js';
+/** Where a release's bytes are kept: an object store keyed by kind and sha256. */
+export interface StoreReleaseBytes {
+    get(key: string): Promise<Uint8Array | undefined>;
+    put(key: string, bytes: Uint8Array): Promise<void>;
+}
+/** The key a release's bytes are stored under. */
+export declare const storeReleaseKey: (kind: string, sha256: string) => string;
+/** How long a rollout's exclusive hold lives between renewals. */
+export declare const ROLLOUT_HOLD_TTL_MS: number;
+/**
+ * How long a push's or a serve's shared hold lives. It is renewed before each kind's upload; one
+ * kind's upload (a settings read and at most one upload per script) must fit inside it, or a
+ * rollout could take the kind before that upload lands. The same lease as a rollout's.
+ */
+export declare const PUSH_HOLD_TTL_MS: number;
+/**
+ * The verticals one rollout request moves. Each costs a settings read and at most one upload,
+ * plus a hold renewal, so a request stays well inside a Worker invocation's subrequest budget.
+ * A fleet bigger than this is moved over several requests (the rollout answers `complete: false`).
+ */
+export declare const ROLLOUT_VERTICALS_PER_REQUEST = 100;
+/**
+ * The most verticals one rollout walks. Every one costs a settings read and a hold renewal even
+ * when it is already at the release, so a bigger fleet would outrun one invocation; it is refused
+ * (409) rather than left unable to converge, and that blocks a rollback too. Raising it needs a
+ * cursor on the rollout row: #2312.
+ */
+export declare const ROLLOUT_FLEET_MAX = 300;
+type LoadRelease = ScopeStoreEnsurerOptions['loadRelease'];
+/**
+ * A release bundle as uploaded or as stored, decoded and judged: the upload body's shape, the
+ * decoded size cap, and the Python kind's module rule. Refusals are 422 (413 for the size).
+ */
+export declare function decodeStoreKindRelease(raw: unknown): Omit<StoreKindReleaseArtifact, 'sha256'>;
+/**
+ * Store a release's bytes and record them (D-63: bytes may be published before the pin lands).
+ * The bytes go first, so a recorded release always has bytes; a retry of the same bundle writes
+ * the same key and records nothing new.
+ */
+export declare function storeKindRelease(input: {
+    admin: HostAdmin;
+    actor: PlatformActorId;
+    bytes: StoreReleaseBytes;
+    kind: string;
+    body: unknown;
+}): Promise<import("@substrat-run/kernel").StoreKindReleaseRecord>;
+/**
+ * The ensurer's loader over the stored bytes: a named release, or the kind's current good one.
+ * Each answer carries the sha256 it was read as, which the ensurer holds the bytes to.
+ */
+export declare function storedReleaseLoader(input: {
+    admin: HostAdmin;
+    actor: PlatformActorId;
+    bytes: StoreReleaseBytes;
+}): LoadRelease;
+/** The reserved calls a canary makes, at the canary script. */
+export type CanaryCall = (target: {
+    scriptName: string;
+    objectName: string;
+}, operation: ReservedStoreOperation, input?: unknown) => Promise<unknown>;
+/**
+ * A canary object's name. Each id comes from a mint of its own, so its 80 random bits are fresh
+ * from `crypto.getRandomValues`: the shared mint would make the second id the first plus one
+ * within a millisecond, and either id would then give the other away.
+ */
+export declare const canaryObjectName: (binding: string) => string;
+/**
+ * Every reserved operation, on a fresh object of the platform's own (D-63): its tenant and scope
+ * ids are new ulids, from the runtime's CSPRNG, never in the directory, and its vertical segment
+ * is no vertical's. Each answer is parsed by the call and asserted here; the first that is not
+ * what an object holding no data answers fails the canary. The object is wiped at the end.
+ */
+export declare function canaryStoreRelease(input: {
+    call: CanaryCall;
+    scriptName: string;
+    binding?: string;
+}): Promise<void>;
+export interface StoreKindRolloutDeps {
+    admin: HostAdmin;
+    actor: PlatformActorId;
+    registration: StoreKindRegistration;
+    sha256: string;
+    action: StoreKindRolloutAction;
+    /**
+     * Move one vertical's scripts of the kind to `to` (the push's ensurer, with `to`). Answers
+     * whether anything was uploaded: false for a script already there, built the same way.
+     */
+    ensure: (input: {
+        vertical: string;
+        stores: readonly ScopeStoreNeed[];
+        to: string;
+    }) => Promise<boolean>;
+    /** Put `to` in the kind's canary script; answers its name. */
+    ensureCanary: (to: string) => Promise<{
+        scriptName: string;
+    }>;
+    callCanary: CanaryCall;
+    /** For a test: a smaller batch than {@link ROLLOUT_VERTICALS_PER_REQUEST}. */
+    perRequest?: number;
+}
+export interface StoreKindRolloutResult {
+    rollout: StoreKindRolloutRecord;
+    /** The verticals whose scripts this request uploaded. */
+    moved: string[];
+    /** False when verticals remain: post the same rollout again. */
+    complete: boolean;
+}
+/**
+ * Move every script of a kind to a stored, pinned release (D-63): hold, canary, then each
+ * vertical. A failure after a vertical moved returns every vertical it reached to the release
+ * the rollout started from, rehashing those bytes as it uploads them, and ends `failed`. It ends
+ * `diverged` instead, naming what is where, when there is nothing to return to (a kind's first
+ * rollout), when returning would lower the stored schema, or when a return fails: the next
+ * rollout or rollback converges every script. The hold is renewed before every upload, the
+ * returns included, and a hold that cannot be renewed stops everything at once: another holder
+ * may be moving the same scripts, so nothing is returned either. The hold is released however it
+ * ends.
+ *
+ * Each request uploads at most `perRequest` scripts. A vertical already at the release is
+ * walked past without counting, so posting the same rollout again continues where the last
+ * request stopped, and a fleet of any size within {@link ROLLOUT_FLEET_MAX} converges.
+ */
+export declare function runStoreKindRollout(deps: StoreKindRolloutDeps): Promise<StoreKindRolloutResult>;
+export {};
+//# sourceMappingURL=store-releases.d.ts.map

package/dist/store-releases.d.ts.map

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

package/dist/store-releases.js

@@ -0,0 +1,298 @@
+/**
+ * A store kind's releases: stored, canaried, rolled out and rolled back (D-63, #2300).
+ *
+ * The bytes live outside the directory, content-addressed under `<kind>/<sha256>`, where the
+ * sha256 is `storeKindReleaseDigest` of the bundle, computed here when it arrives and again by
+ * the ensurer before every upload of it, restore and rollback included. The directory holds who
+ * uploaded which release from which commit, every rollout, and the current good release
+ * (`store-kind-releases.ts` in the kernel).
+ *
+ * A rollout is one request across a fleet. It holds the kind exclusively for its whole length,
+ * renewing the hold before every upload, so no push or serve rebuilds a script between the
+ * rollout's read and its upload, and two rollouts never interleave. It canaries the release on the
+ * platform's own object first, and no vertical's script moves unless every reserved operation
+ * answered there. Then it moves each vertical that ever declared the kind, at most
+ * {@link ROLLOUT_VERTICALS_PER_REQUEST} uploads per request. A bigger fleet ends the request
+ * `paused`, and posting the same rollout (or rollback) again continues it, walking past the scripts
+ * already there. A request that stops on a failure ends `failed` or `diverged`. One request walks at
+ * most {@link ROLLOUT_FLEET_MAX} verticals, a rollback included, until #2312.
+ */
+import { STORE_RELEASE_MAX_BYTES, scopeStoreCanaryObjectName, storeKindReleaseDigest, storeKindReleaseUpload, } from '@substrat-run/contracts';
+import { ControlPlaneError } from '@substrat-run/control-plane-client';
+import { createUlid, ulid } from '@substrat-run/kernel';
+import { assertPythonKindModules } from './store-entry.js';
+/** The key a release's bytes are stored under. */
+export const storeReleaseKey = (kind, sha256) => `${kind}/${sha256}`;
+/** How long a rollout's exclusive hold lives between renewals. */
+export const ROLLOUT_HOLD_TTL_MS = 10 * 60_000;
+/**
+ * How long a push's or a serve's shared hold lives. It is renewed before each kind's upload; one
+ * kind's upload (a settings read and at most one upload per script) must fit inside it, or a
+ * rollout could take the kind before that upload lands. The same lease as a rollout's.
+ */
+export const PUSH_HOLD_TTL_MS = 10 * 60_000;
+/**
+ * The verticals one rollout request moves. Each costs a settings read and at most one upload,
+ * plus a hold renewal, so a request stays well inside a Worker invocation's subrequest budget.
+ * A fleet bigger than this is moved over several requests (the rollout answers `complete: false`).
+ */
+export const ROLLOUT_VERTICALS_PER_REQUEST = 100;
+/**
+ * The most verticals one rollout walks. Every one costs a settings read and a hold renewal even
+ * when it is already at the release, so a bigger fleet would outrun one invocation; it is refused
+ * (409) rather than left unable to converge, and that blocks a rollback too. Raising it needs a
+ * cursor on the rollout row: #2312.
+ */
+export const ROLLOUT_FLEET_MAX = 300;
+const decodeBase64 = (text) => {
+    let binary;
+    try {
+        binary = atob(text);
+    }
+    catch {
+        throw new ControlPlaneError(422, 'a release module is not base64');
+    }
+    return Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+};
+/**
+ * A release bundle as uploaded or as stored, decoded and judged: the upload body's shape, the
+ * decoded size cap, and the Python kind's module rule. Refusals are 422 (413 for the size).
+ */
+export function decodeStoreKindRelease(raw) {
+    const parsed = storeKindReleaseUpload.safeParse(raw);
+    if (!parsed.success) {
+        throw new ControlPlaneError(422, `not a store kind release: ${parsed.error.issues.map((i) => i.message).join('; ')}`);
+    }
+    let total = 0;
+    const modules = parsed.data.modules.map((module) => {
+        const content = decodeBase64(module.contentBase64);
+        total += content.byteLength;
+        if (total > STORE_RELEASE_MAX_BYTES) {
+            throw new ControlPlaneError(413, `a store kind release carries at most ${STORE_RELEASE_MAX_BYTES} module bytes`);
+        }
+        return { name: module.name, content };
+    });
+    const release = { sourceCommit: parsed.data.sourceCommit, entry: parsed.data.entry, modules };
+    try {
+        assertPythonKindModules(release);
+    }
+    catch (e) {
+        throw new ControlPlaneError(422, e instanceof Error ? e.message : String(e));
+    }
+    return release;
+}
+/** The stored form: the upload body again, so one decoder reads both. */
+function encodeStoreKindRelease(release) {
+    const base64 = (bytes) => {
+        let text = '';
+        for (let i = 0; i < bytes.length; i += 0x8000)
+            text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+        return btoa(text);
+    };
+    return new TextEncoder().encode(JSON.stringify({
+        sourceCommit: release.sourceCommit,
+        entry: release.entry,
+        modules: release.modules.map((m) => ({ name: m.name, contentBase64: base64(m.content) })),
+    }));
+}
+/**
+ * Store a release's bytes and record them (D-63: bytes may be published before the pin lands).
+ * The bytes go first, so a recorded release always has bytes; a retry of the same bundle writes
+ * the same key and records nothing new.
+ */
+export async function storeKindRelease(input) {
+    const release = decodeStoreKindRelease(input.body);
+    const sha256 = await storeKindReleaseDigest(release).catch((e) => {
+        throw new ControlPlaneError(422, e instanceof Error ? e.message : String(e));
+    });
+    const held = await input.admin.getStoreKindRelease(input.actor, input.kind, sha256);
+    if (held && held.sourceCommit !== release.sourceCommit) {
+        throw new ControlPlaneError(409, `release ${sha256} of '${input.kind}' is stored as built from ${held.sourceCommit}`);
+    }
+    if (!held)
+        await input.bytes.put(storeReleaseKey(input.kind, sha256), encodeStoreKindRelease(release));
+    return input.admin.recordStoreKindRelease(input.actor, { kind: input.kind, sha256, sourceCommit: release.sourceCommit });
+}
+/**
+ * The ensurer's loader over the stored bytes: a named release, or the kind's current good one.
+ * Each answer carries the sha256 it was read as, which the ensurer holds the bytes to.
+ */
+export function storedReleaseLoader(input) {
+    return async ({ kind, sha256 }) => {
+        const wanted = sha256 ?? (await input.admin.storeKindState(input.actor, kind)).current?.sha256;
+        if (!wanted)
+            return undefined;
+        const raw = await input.bytes.get(storeReleaseKey(kind, wanted));
+        if (!raw)
+            return undefined;
+        let json;
+        try {
+            json = JSON.parse(new TextDecoder().decode(raw));
+        }
+        catch {
+            throw new ControlPlaneError(422, `kind '${kind}' release ${wanted} is stored as something other than a release`);
+        }
+        return { ...decodeStoreKindRelease(json), sha256: wanted };
+    };
+}
+/**
+ * A canary object's name. Each id comes from a mint of its own, so its 80 random bits are fresh
+ * from `crypto.getRandomValues`: the shared mint would make the second id the first plus one
+ * within a millisecond, and either id would then give the other away.
+ */
+export const canaryObjectName = (binding) => scopeStoreCanaryObjectName(createUlid()(), createUlid()(), binding);
+const tablesOf = (answer) => answer.tables;
+/**
+ * Every reserved operation, on a fresh object of the platform's own (D-63): its tenant and scope
+ * ids are new ulids, from the runtime's CSPRNG, never in the directory, and its vertical segment
+ * is no vertical's. Each answer is parsed by the call and asserted here; the first that is not
+ * what an object holding no data answers fails the canary. The object is wiped at the end.
+ */
+export async function canaryStoreRelease(input) {
+    const target = { scriptName: input.scriptName, objectName: canaryObjectName(input.binding ?? 'CANARY') };
+    const step = async (operation, check, body) => {
+        let answer;
+        try {
+            answer = await input.call(target, operation, body);
+        }
+        catch (e) {
+            throw new ControlPlaneError(502, `canary refused: ${operation} failed (${e instanceof Error ? e.message : String(e)})`);
+        }
+        const wrong = check(answer);
+        if (wrong)
+            throw new ControlPlaneError(502, `canary refused: ${operation} ${wrong}`);
+        return answer;
+    };
+    const ok = () => null;
+    await step('substrat.size', ok);
+    const exported = tablesOf(await step('substrat.export', (a) => (tablesOf(a).some((t) => t.rows.length > 0) ? 'exported rows from an object holding none' : null)));
+    await step('substrat.import', (a) => (a.tables === exported.length ? null : `imported ${a.tables} of ${exported.length} tables`), { tables: exported });
+    await step('substrat.export', (a) => (JSON.stringify(tablesOf(a)) === JSON.stringify(exported) ? null : 'did not export what it imported'));
+    await step('substrat.erase', (a) => (a.erased === 0 ? null : 'erased rows of a subject the object never held'), { subjectId: ulid() });
+    await step('substrat.wipe', ok);
+    await step('substrat.export', (a) => (tablesOf(a).some((t) => t.rows.length > 0) ? 'still holds rows after its wipe' : null));
+}
+const message = (e) => (e instanceof Error ? e.message : String(e));
+const schemaOf = (registration, sha256) => sha256 === null ? undefined : registration.releases.find((pin) => pin.sha256 === sha256)?.schema;
+/** The hold lapsed, or another holder ended the rollout: nothing more may be moved under it. */
+class HoldLost extends ControlPlaneError {
+    constructor(kind) {
+        super(409, `the hold on kind '${kind}' lapsed or its rollout was ended by another; post the rollout again to converge it`);
+    }
+}
+/**
+ * Move every script of a kind to a stored, pinned release (D-63): hold, canary, then each
+ * vertical. A failure after a vertical moved returns every vertical it reached to the release
+ * the rollout started from, rehashing those bytes as it uploads them, and ends `failed`. It ends
+ * `diverged` instead, naming what is where, when there is nothing to return to (a kind's first
+ * rollout), when returning would lower the stored schema, or when a return fails: the next
+ * rollout or rollback converges every script. The hold is renewed before every upload, the
+ * returns included, and a hold that cannot be renewed stops everything at once: another holder
+ * may be moving the same scripts, so nothing is returned either. The hold is released however it
+ * ends.
+ *
+ * Each request uploads at most `perRequest` scripts. A vertical already at the release is
+ * walked past without counting, so posting the same rollout again continues where the last
+ * request stopped, and a fleet of any size within {@link ROLLOUT_FLEET_MAX} converges.
+ */
+export async function runStoreKindRollout(deps) {
+    const { admin, actor, registration, sha256 } = deps;
+    const kind = registration.kind;
+    const holder = ulid();
+    if (!(await admin.holdStoreKind(actor, { kind, holder, mode: 'exclusive', ttlMs: ROLLOUT_HOLD_TTL_MS }))) {
+        throw new ControlPlaneError(409, `kind '${kind}' is being rolled out or a vertical declaring it is being pushed; try again shortly`);
+    }
+    try {
+        const declared = await admin.storeKindDeclarations(actor, kind);
+        if (declared.unreadable.length > 0) {
+            throw new ControlPlaneError(409, `kind '${kind}' cannot be rolled out: ${declared.unreadable.join(', ')} ha${declared.unreadable.length === 1 ? 's a version' : 've versions'} whose stores cannot be named`);
+        }
+        if (declared.verticals.length > ROLLOUT_FLEET_MAX) {
+            throw new ControlPlaneError(409, `kind '${kind}' is declared by ${declared.verticals.length} verticals; a ${deps.action} walks at most ${ROLLOUT_FLEET_MAX}, so neither a rollout nor a rollback can run until rollouts page with a cursor (#2312)`);
+        }
+        const row = await admin.beginStoreKindRollout(actor, { kind, sha256, action: deps.action, holder });
+        const end = (state, detail) => admin.finishStoreKindRollout(actor, { kind, seq: row.seq, holder, state, detail });
+        const renew = async () => {
+            const held = await admin.holdStoreKind(actor, { kind, holder, mode: 'exclusive', ttlMs: ROLLOUT_HOLD_TTL_MS, renew: true, rolloutSeq: row.seq });
+            if (!held)
+                throw new HoldLost(kind);
+        };
+        try {
+            await deps.ensureCanary(sha256).then(({ scriptName }) => canaryStoreRelease({ call: deps.callCanary, scriptName }));
+        }
+        catch (e) {
+            // No vertical's script moved; the current release stays. A row the end cannot write (the
+            // hold lapsed) reads as diverged, which is what it then is.
+            await end('failed', message(e)).catch(() => undefined);
+            throw e;
+        }
+        const targets = declared.verticals.map((v) => ({ vertical: v.vertical, stores: v.stores.map((s) => ({ binding: s.binding, kind })) }));
+        const budget = deps.perRequest ?? ROLLOUT_VERTICALS_PER_REQUEST;
+        // Every vertical walked: the ones moved now, and the ones an earlier request moved.
+        const reached = [];
+        const moved = [];
+        for (const target of targets) {
+            if (moved.length >= budget) {
+                const rest = targets.length - reached.length;
+                const rollout = await end('paused', `this request moved ${moved.length}; ${rest} vertical(s) not walked yet: post the same ${deps.action} again`);
+                return { rollout, moved, complete: false };
+            }
+            try {
+                await renew();
+                reached.push(target.vertical);
+                if (await deps.ensure({ vertical: target.vertical, stores: target.stores, to: sha256 }))
+                    moved.push(target.vertical);
+            }
+            catch (e) {
+                const detail = e instanceof HoldLost
+                    ? { state: 'diverged', text: `Nothing was returned: ${reached.join(', ') || 'no vertical'} may run ${sha256}.` }
+                    : await restore(deps, row.fromSha256, reached, targets, renew);
+                await end(detail.state, `${target.vertical}: ${message(e)}. ${detail.text}`).catch(() => undefined);
+                throw new ControlPlaneError(e instanceof ControlPlaneError ? e.status : 502, `rollout of '${kind}' to ${sha256} stopped at ${target.vertical} (${message(e)}). ${detail.text}`);
+            }
+        }
+        return { rollout: await end('good', null), moved, complete: true };
+    }
+    finally {
+        await admin.releaseStoreKindHold(actor, { kind, holder }).catch(() => undefined);
+    }
+}
+/**
+ * Return every vertical a failed rollout reached to the release it started from, where that is
+ * allowed, renewing the hold before each upload. A hold that cannot be renewed stops the return.
+ */
+async function restore(deps, from, reached, verticals, renew) {
+    if (reached.length === 0)
+        return { state: 'failed', text: 'No vertical moved.' };
+    if (from === null) {
+        return { state: 'diverged', text: `There is no earlier release to return to; ${reached.join(', ')} may run ${deps.sha256}.` };
+    }
+    const leaving = schemaOf(deps.registration, deps.sha256);
+    const returning = schemaOf(deps.registration, from);
+    if (leaving === undefined || returning === undefined || returning < leaving) {
+        return {
+            state: 'diverged',
+            text: `Returning to ${from} would lower the stored schema (${leaving} to ${returning}), so ${reached.join(', ')} may run ${deps.sha256}.`,
+        };
+    }
+    const stuck = [];
+    for (const [i, vertical] of reached.entries()) {
+        try {
+            await renew();
+        }
+        catch {
+            return { state: 'diverged', text: `The hold was lost while returning; ${reached.slice(i).join(', ')} may run ${deps.sha256}.` };
+        }
+        const target = verticals.find((v) => v.vertical === vertical);
+        try {
+            await deps.ensure({ vertical, stores: target.stores, to: from });
+        }
+        catch (e) {
+            stuck.push(`${vertical} (${message(e)})`);
+        }
+    }
+    return stuck.length === 0
+        ? { state: 'failed', text: `${reached.join(', ')} returned to ${from}.` }
+        : { state: 'diverged', text: `Could not return ${stuck.join(', ')} to ${from}.` };
+}
+//# sourceMappingURL=store-releases.js.map

package/dist/store-releases.js.map

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

package/dist/store-script.d.ts

@@ -0,0 +1,80 @@
+import { type ScopeStoreNeed, type StoreKindRegistration } from '@substrat-run/contracts';
+import { type PythonStoreKindRelease } from './store-entry.js';
+/**
+ * The binding that records which pinned release a store script runs: the release bundle's
+ * sha256 (D-63). In the entry's reserved prefix, so the kind's env never carries it.
+ */
+export declare const STORE_RELEASE_VAR = "SUBSTRAT_STORE_RELEASE";
+/**
+ * The binding that records what else the script was built from: a digest over every module the
+ * upload sent and its configuration. A changed entry, verifier, key list or flag changes it.
+ */
+export declare const STORE_BUILD_VAR = "SUBSTRAT_STORE_BUILD";
+/** One release of a kind's code, as the publish flow stores it (#2297). */
+export interface StoreKindReleaseArtifact extends PythonStoreKindRelease {
+    /** The commit the bundle was built from. A reviewer reads it; the upload checks the sha256. */
+    readonly sourceCommit: string;
+    /**
+     * The sha256 the loader read these bytes as (its storage key). When present, the bytes must
+     * hash to it, so a store that answers other bytes under a key is refused, not uploaded.
+     */
+    readonly sha256?: string;
+}
+export interface ScopeStoreEnsurerOptions {
+    accountId: string;
+    namespace: string;
+    apiToken: string;
+    /** The `caller` audience's public keys, raw Ed25519, base64url. A list, so a key can rotate. */
+    callerPublicKeys: readonly string[];
+    /** The `platform` audience's public keys, in the same form. Never one of the caller's. */
+    platformPublicKeys: readonly string[];
+    kinds?: readonly StoreKindRegistration[];
+    /**
+     * A release's bytes. With `sha256`, that release: the one the script runs, or the one a
+     * rollout moves it to. Without it, the kind's current good release (#2300). Undefined when
+     * there is none.
+     */
+    loadRelease: (input: {
+        readonly kind: string;
+        readonly vertical: string;
+        readonly sha256?: string;
+    }) => Promise<StoreKindReleaseArtifact | undefined>;
+}
+/**
+ * Put every (kind, vertical) store script a vertical's stores need in place, before the
+ * vertical's own upload (#2210, D-63). A push or a serve never moves a script to another
+ * release: only a rollout or a rollback does (#2300), and it says so with `to`.
+ *
+ * - No `to`, no script yet: it is uploaded at the kind's current good release.
+ * - No `to`, a script: it is rebuilt at the release it already runs, and uploaded again only when
+ *   what it was built from changed (the platform's entry, the verifier, a key list, a flag), so a
+ *   fix or a key rotation reaches it without a release moving.
+ * - `to`: the script is moved to that release, or left alone when it already runs it, built the
+ *   same way. Re-running a rollout therefore converges and uploads nothing twice.
+ *
+ * Every upload hashes the module bytes it is about to send and refuses (422) bytes whose
+ * sha256 the kind's registration does not pin, or that are not the release asked for. A kind
+ * with no release to run is refused (409). A script is never moved to a release whose pinned
+ * `schema` is lower than that of the release it runs (409): its objects may have migrated. The
+ * runtime's own failures are 502. Answers how many scripts were uploaded.
+ */
+export declare function createScopeStoreEnsurer(opts: ScopeStoreEnsurerOptions): (input: {
+    vertical: string;
+    stores: readonly ScopeStoreNeed[];
+    to?: string;
+}) => Promise<{
+    uploaded: number;
+}>;
+/**
+ * Put a kind's release in the platform's canary script (D-63, #2300), where it is canaried
+ * before any vertical's script moves: `scopeStoreCanaryScriptName(kind)`, built and checked as a
+ * vertical's script is, except that it may move to a lower `schema`: every canary object is fresh
+ * and wiped, so none holds migrated data. Answers the script's name.
+ */
+export declare function createStoreCanaryEnsurer(opts: ScopeStoreEnsurerOptions): (input: {
+    kind: string;
+    to: string;
+}) => Promise<{
+    scriptName: string;
+}>;
+//# sourceMappingURL=store-script.d.ts.map

package/dist/store-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-script.d.ts","sourceRoot":"","sources":["../src/store-script.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAE3B,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAwB,KAAK,sBAAsB,EAA0B,MAAM,kBAAkB,CAAC;AAE7G;;;GAGG;AACH,eAAO,MAAM,iBAAiB,2BAA6C,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,eAAe,yBAA2C,CAAC;AAExE,2EAA2E;AAC3E,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACtE,+FAA+F;IAC/F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,0FAA0F;IAC1F,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,KAAK,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzC;;;;OAIG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE;QACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;KAC1B,KAAK,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAAC;CACrD;AAYD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,WAE/C;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAM1H;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,wBAAwB,WAEhD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAWpF"}