portal-mojo 0.2.19 → 0.2.21

package/src/admin/deployments/WebAppRollbackDialog.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useMe } from '../../client/runtime';
+import { getDeployment, getHistory, getRelease, resolveAppAuthority, getSummary, getWebApp, rollback } from './api';
+import { assertOwner, isInteractive } from './permissions';
+import { rollbackEligible } from './deployment-state';
+import { makeReceipt, receiptsFor, saveReceipt, settleReceipt } from './receipts';
+import { useDeploymentObservation, useDeploymentOwner } from './useDeploymentObservation';
+import { ErrorNotice, Status, useWrite } from './shared';
+import type { DeploymentStatus, Release, WebAppObject } from './types';
+export function WebAppRollbackDialog({ app, release, onClose, onBusy, onChanged }: {
+    app: WebAppObject;
+    release?: Release;
+    onClose: () => void;
+    onBusy: (v: boolean) => void;
+    onChanged: () => void;
+}) {
+    const s = useDeploymentOwner(), me = useMe(), w = useWrite(s.owner, s.signal, onBusy);
+    const pending = receiptsFor(s.owner).find(r => r.kind === 'rollback' && r.app === app.id && r.submitted && !r.settled);
+    const [start, setStart] = useState(0), [selection, setSelection] = useState<Release | undefined>(release), [confirmation, setConfirmation] = useState('');
+    const [tracked, setTracked] = useState<DeploymentStatus | null>(() => pending?.deployment && pending.release ? { deployment: pending.deployment, webapp: app.id, release: pending.release, version: '', status: 'unknown', terminal: false, success: false, detail: '', created: '', started: '', finished: '', targets: [], rollback_targets: [] } : null);
+    const [reconciled, setReconciled] = useState(false), [acknowledgement, setAcknowledgement] = useState('');
+    const q = useQuery({ queryKey: ['deployments', s.key, app.id, 'rollback-targets', start], queryFn: async ({ signal }) => ({ summary: await getSummary(s.owner, app.id, signal), releases: await getHistory(s.owner, app.id, 'release', start, signal) }), retry: false });
+    const selected = selection, target = selected?.id ?? 0;
+    const observation = useDeploymentObservation(s.owner, tracked ? String(tracked.deployment) : null, signal => getDeployment(s.owner, tracked!.deployment, app.id, tracked!.release, signal), d => d.terminal);
+    const execute = () => w.run(async () => {
+        if (!selected || confirmation !== `${app.slug}/${selected.version}` || !q.data || q.isError) return;
+        const [object, summary, fresh] = await Promise.all([getWebApp(s.owner, app.id, s.signal), getSummary(s.owner, app.id, s.signal), getRelease(s.owner, target, app.id, s.signal)]);
+        if (object.group.id !== app.group.id) throw new Error('App ownership changed');
+        const authority = await resolveAppAuthority(s.owner, me.data, object, 'custom', s.signal);
+        if (!isInteractive() || !authority.custom) throw new Error('Exact app authority is unavailable');
+        if (!rollbackEligible(fresh, summary.current_release) || fresh.version !== selected.version) throw new Error('Target changed; refresh and confirm again');
+        assertOwner(s.owner, s.signal);
+        const receipt = makeReceipt(s.owner, 'rollback', `${app.id}:${target}`, app.id, String(target));
+        const result = await rollback(s.owner, receipt, app.id, target, app.group.id, s.signal);
+        saveReceipt({ ...receipt, deployment: result.deployment, release: target });
+        setTracked(result); setConfirmation(''); onChanged();
+    });
+    const uncertain = receiptsFor(s.owner).find(r => r.kind === 'rollback' && r.app === app.id && r.submitted && !r.settled && !r.deployment);
+    const reconcile = () => w.run(async () => {
+        if (!uncertain) return;
+        const summary = await getSummary(s.owner, app.id, s.signal), history = await getHistory(s.owner, app.id, 'deployment', 0, s.signal);
+        const matches = history.items.filter(a => (a as import('./types').Attempt).release?.id === Number(uncertain.target) && Date.parse(a.created) >= (uncertain.submittedAt ?? 0) - 1000) as import('./types').Attempt[];
+        if (matches.length === 1) {
+            const match = matches[0]!, status = await getDeployment(s.owner, match.id, app.id, Number(uncertain.target), s.signal);
+            saveReceipt({ ...uncertain, deployment: status.deployment, release: status.release, settled: status.terminal }); setTracked(status);
+        } else {
+            setConfirmation('');
+            if (summary.current_release?.id === Number(uncertain.target)) throw new Error('The target is already the current desired pointer. Refresh its deployment evidence instead of dispatching another rollback.');
+            setReconciled(true);
+        }
+    });
+    const acknowledge = () => {
+        if (!uncertain || !reconciled || acknowledgement !== `${app.slug}/unknown-outcome`) return;
+        saveReceipt({ ...uncertain, settled: true, acknowledged: true }); setReconciled(false); setAcknowledgement(''); setConfirmation('');
+    };
+    const outcome = observation.value ?? tracked, notified = useRef(new Set<number>());
+    useEffect(() => {
+        if (!outcome?.terminal) return;
+        setTracked(current => current?.deployment === outcome.deployment && current !== outcome ? outcome : current);
+        const receipt = receiptsFor(s.owner).find(r => r.kind === 'rollback' && r.app === app.id && r.deployment === outcome.deployment);
+        if (receipt && !receipt.settled) settleReceipt(receipt);
+        if (!notified.current.has(outcome.deployment)) { notified.current.add(outcome.deployment); onChanged(); }
+    }, [outcome?.deployment, outcome?.terminal, onChanged]);
+    const succeeded = outcome?.terminal === true && outcome.success === true && outcome.status === 'live';
+    const releases = (q.data?.releases.items ?? []) as Release[], eligible = releases.filter(r => rollbackEligible(r, q.data!.summary.current_release));
+    return <div className="modal-pad admin-deployments"><h2 className="modal-title">{succeeded ? 'Rollback complete' : tracked ? 'Rollback progress' : `Roll back ${app.display_name || app.slug}`}</h2>{!tracked && <p className="modal-message">Choose a verified release to deploy. A failed rollout can leave mixed nodes.</p>}
+        {!tracked && <>
+            {q.isError && <ErrorNotice>Release observation unavailable. Refresh before choosing a target.</ErrorNotice>}
+            <label>Verified release<select value={target} disabled={w.busy || q.isFetching} onChange={e => { setSelection(releases.find(r => r.id === Number(e.target.value))); setConfirmation(''); }}><option value={0}>Choose a version</option>{selected && !eligible.some(r => r.id === target) && <option value={target}>{selected.version} · selected</option>}{eligible.map(r => <option key={r.id} value={r.id}>{r.version} · {r.status}</option>)}</select></label>
+            <div className="deployment-pagination" aria-label="Release history pagination"><span className="dim">{q.data ? `${q.data.releases.count ? start + 1 : 0}–${Math.min(start + releases.length, q.data.releases.count)} of ${q.data.releases.count} registered releases` : 'Loading releases…'}</span><div className="deployment-actions"><button className="btn" disabled={w.busy || q.isFetching || start === 0} onClick={() => setStart(value => Math.max(0, value - 25))}>Newer releases</button><button className="btn" disabled={w.busy || q.isFetching || !q.data || start + 25 >= q.data.releases.count} onClick={() => setStart(value => value + 25)}>Older releases</button><button className="btn" disabled={w.busy || q.isFetching} onClick={() => void q.refetch()}>Refresh releases</button></div></div>
+            {q.data && !eligible.length && <p className="dim">No eligible rollback target on this page.</p>}
+            {selected && <label>Type {app.slug}/{selected.version}<input value={confirmation} disabled={w.busy} onChange={e => setConfirmation(e.target.value)}/></label>}
+        </>}
+        {uncertain && <div className="deployment-confirm"><p>A previous rollback may have persisted. Observe it before another decision.</p><button className="btn" disabled={w.busy} onClick={() => void reconcile()}>Observe uncertain rollback</button>{reconciled && <><p>No unique matching attempt was observed in bounded history. A new rollback can overlap the earlier operation. Acknowledge this unknown outcome, then review and type the app/version again to consent to a new operation.</p><label>Type {app.slug}/unknown-outcome<input value={acknowledgement} disabled={w.busy} onChange={e => setAcknowledgement(e.target.value)}/></label><button className="btn" disabled={w.busy || acknowledgement !== `${app.slug}/unknown-outcome`} onClick={acknowledge}>Acknowledge unknown outcome</button></>}</div>}
+        {w.error && <ErrorNotice>{w.error}</ErrorNotice>}
+        {succeeded ? <div className="deployment-result" role="status"><strong>{outcome.version || selected?.version || 'Selected release'}</strong> <Status value="live"/><p>Deployment completed.</p></div> : tracked && <p role="status">Deployment {tracked.deployment}: <Status value={outcome?.status ?? 'unknown'}/></p>}
+        {['error', 'stopped'].includes(observation.state) && <p className="text-warn">{succeeded ? 'Latest refresh unavailable. Showing the last observed result.' : 'Observation unavailable; outcome unconfirmed. Refresh only observes.'}</p>}
+        {!succeeded && outcome?.detail && <p>{outcome.detail}</p>}
+        <div className="modal-actions"><button className="btn" disabled={w.busy} onClick={onClose}>{tracked ? 'Close' : 'Cancel'}</button>{tracked ? <button className="btn" disabled={w.busy || observation.state === 'observing'} onClick={observation.refresh}>Refresh exact deployment</button> : <button className="btn btn-primary" disabled={w.busy || q.isFetching || q.isError || !q.data || !selected || !rollbackEligible(selected, q.data.summary.current_release) || confirmation !== `${app.slug}/${selected.version}`} onClick={() => void execute()}>Confirm rollback</button>}</div>
+    </div>;
+}

package/src/admin/deployments/WebAppUploadPanel.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useRef, useState } from 'react';
+import { usingMockTransport, useMe } from '../../client/runtime';
+import { completeUpload, getDeployment, reconcileUploadCompletion, resolveAppAuthority, getWebApp, registerUpload } from './api';
+import { isInteractive } from './permissions';
+import { buildManifest, manifestEqual, putReleaseFiles } from './upload';
+import { makeReceipt, receiptsFor, saveReceipt, settleReceipt } from './receipts';
+import { useDeploymentObservation, useDeploymentOwner } from './useDeploymentObservation';
+import { DeploymentHelp, ErrorNotice, Status, useWrite } from './shared';
+import type { DeploymentStatus, WebAppObject } from './types';
+
+export function WebAppUploadPanel({ app, onClose, onBusy, onChanged }: {
+    app: WebAppObject;
+    onClose?: () => void;
+    onBusy?: (v: boolean) => void;
+    onChanged?: () => void;
+}) {
+    const s = useDeploymentOwner(), me = useMe(), w = useWrite(s.owner, s.signal, onBusy);
+    const files = useRef<File[]>([]);
+    const existing = receiptsFor(s.owner).find(r => r.kind === 'upload' && r.app === app.id && !r.settled);
+    const [version, setVersion] = useState(existing?.target ?? '');
+    const [fileCount, setFileCount] = useState(0), [progress, setProgress] = useState('');
+    const [tracked, setTracked] = useState<{ deployment: number; release: number } | null>(
+        existing?.deployment && existing.release ? { deployment: existing.deployment, release: existing.release } : null,
+    );
+    const [reconciliation, setReconciliation] = useState<Awaited<ReturnType<typeof reconcileUploadCompletion>> | null>(null);
+    const [consent, setConsent] = useState('');
+    const [lastTerminal, setLastTerminal] = useState<DeploymentStatus | null>(null);
+    const observe = useDeploymentObservation(s.owner, tracked ? String(tracked.deployment) : null,
+        signal => getDeployment(s.owner, tracked!.deployment, app.id, tracked!.release, signal), d => d.terminal);
+    const completionSubmitted = !!existing && ['completion_submitted', 'observing'].includes(existing.uploadPhase ?? '');
+
+    const checkAuthority = async () => {
+        const object = await getWebApp(s.owner, app.id, s.signal);
+        const authority = await resolveAppAuthority(s.owner, me.data, object, 'release', s.signal);
+        if (!isInteractive() || object.group.id !== app.group.id || !authority.release)
+            throw new Error('Exact app release authority unavailable');
+    };
+    const upload = () => w.run(async () => {
+        if (completionSubmitted) throw new Error('Completion was already submitted. Observe its deployment before a new decision.');
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(version))
+            throw new Error('Use a version of 1–128 letters, numbers, dots, dashes or underscores');
+        await checkAuthority();
+        setProgress('Hashing selected files…');
+        const manifest = await buildManifest(files.current, s.signal);
+        const receipt = makeReceipt(s.owner, 'upload', `${app.id}:${version}`, app.id, version);
+        if (receipt.manifest && !manifestEqual(receipt.manifest, manifest))
+            throw new Error('Reselect the identical normalized files and checksums for this pending version');
+        const frozen = saveReceipt({ ...receipt, manifest });
+        setProgress('Registering immutable release…');
+        const registration = await registerUpload(s.owner, frozen, app.id, app.group.id, version, manifest, s.signal);
+        const registered = saveReceipt({ ...frozen, release: registration.release, uploadPhase: 'registered' });
+        setProgress('Uploading checksum-bound files…');
+        const put = usingMockTransport() ? (await import('../../client/deployments-mock')).deploymentMockStorageFetch : fetch;
+        await putReleaseFiles(files.current, manifest, registration.uploads, s.signal,
+            n => setProgress(`${n}/${manifest.length} files uploaded`), put);
+        setProgress('Verifying release and starting deployment…');
+        const result = await completeUpload(s.owner, registered, registration.release, app.id, app.group.id, s.signal);
+        setTracked({ deployment: result.deployment, release: registration.release });
+        files.current = []; setFileCount(0);
+        setProgress('Completion accepted; observing exact deployment.');
+    });
+    const reconcile = () => w.run(async () => {
+        const receipt = existing ?? receiptsFor(s.owner).find(r => r.kind === 'upload' && r.app === app.id && r.target === version);
+        if (!receipt) throw new Error('No submitted completion receipt is available');
+        const result = await reconcileUploadCompletion(s.owner, receipt, s.signal);
+        setReconciliation(result); setConsent('');
+        if (result.status) setTracked({ deployment: result.status.deployment, release: result.status.release });
+        setProgress(result.status ? 'Matching exact deployment observed.' : 'No unique matching attempt was established. Completion outcome remains unknown.');
+    });
+    const renewConsent = () => w.run(async () => {
+        if (!reconciliation || consent !== `${app.slug}/${version}`) return;
+        await checkAuthority();
+        const fresh = await reconcileUploadCompletion(s.owner, reconciliation.receipt, s.signal);
+        if (fresh.signature !== reconciliation.signature || (fresh.status && !fresh.status.terminal)) {
+            setReconciliation(fresh); setConsent('');
+            if (fresh.status) setTracked({ deployment: fresh.status.deployment, release: fresh.status.release });
+            throw new Error('Deployment evidence changed or is active. Review it before another deployment decision.');
+        }
+        saveReceipt({ ...fresh.receipt, operation: crypto.randomUUID(), uploadPhase: 'registered',
+            completionSubmittedAt: undefined, completionBaseline: undefined, deployment: undefined,
+            submitted: false, submittedAt: undefined, settled: false });
+        setTracked(null); setReconciliation(null); setLastTerminal(null); setConsent('');
+        files.current = []; setFileCount(0);
+        setProgress('New deployment consent recorded. Reselect the identical artifact and deliberately upload/deploy again.');
+    });
+    const forTracked = (value: DeploymentStatus | null | undefined) => value && tracked && value.deployment === tracked.deployment && value.release === tracked.release && value.webapp === app.id ? value : null;
+    // A later exact terminal observation outranks an earlier reconciliation read.
+    const outcome = forTracked(observe.value) ?? forTracked(lastTerminal) ?? forTracked(reconciliation?.status);
+    const succeeded = outcome?.terminal === true && outcome.success === true && outcome.status === 'live';
+    const notified = useRef(new Set<number>());
+    useEffect(() => { if (observe.value?.terminal) setLastTerminal(observe.value); }, [observe.value]);
+    useEffect(() => {
+        if (!observe.value?.terminal) return;
+        const receipt = receiptsFor(s.owner).find(r => r.kind === 'upload' && r.app === app.id && r.deployment === observe.value?.deployment);
+        if (receipt && !receipt.settled) settleReceipt(receipt);
+        if (!notified.current.has(observe.value.deployment)) {
+            notified.current.add(observe.value.deployment); onChanged?.();
+        }
+    }, [observe.value?.deployment, observe.value?.terminal, onChanged]);
+    const lockedFiles = w.busy || !!tracked || completionSubmitted;
+    const mayRenew = !!reconciliation && (!reconciliation.status ||
+        (reconciliation.status.terminal && !reconciliation.status.success));
+    if (succeeded) return <div className="deployment-stack">
+        <div className="deployment-result" role="status"><strong>{outcome.version || version}</strong> <Status value="live"/><p>Deployment completed.</p></div>
+        {['error', 'stopped'].includes(observe.state) && <p className="text-warn">Latest refresh unavailable. Showing the last observed result.</p>}
+        <div className="modal-actions">{onClose && <button className="btn" disabled={w.busy} onClick={onClose}>Close upload</button>}<button className="btn" disabled={w.busy || observe.state === 'observing'} onClick={observe.refresh}>Refresh exact deployment</button></div>
+    </div>;
+    return <div>
+        <label>Release version<input value={version} disabled={w.busy || !!tracked || !!existing} onChange={e => setVersion(e.target.value)} /></label>
+        <label>Built files<input type="file" multiple disabled={lockedFiles} onChange={e => { files.current = Array.from(e.target.files ?? []); setFileCount(files.current.length); }} /></label>
+        <label>Built folder<input type="file" multiple {...{ webkitdirectory: '', directory: '' }} disabled={lockedFiles} onChange={e => {
+            files.current = Array.from(e.target.files ?? []).map(file => {
+                const copy = new File([file], file.name, { type: file.type, lastModified: file.lastModified });
+                Object.defineProperty(copy, 'webkitRelativePath', { value: (file.webkitRelativePath || file.name).split('/').slice(1).join('/') || file.name });
+                return copy;
+            }); setFileCount(files.current.length);
+        }} /></label>
+        <p>{fileCount} files selected <DeploymentHelp label="Upload limits and resume">Default limits are 5000 files and 1 GiB; this installation may set lower limits. Reselect and rehash the identical files to resume an upload that has not submitted completion.</DeploymentHelp></p>
+        {existing && !tracked && !completionSubmitted && <p>Pending version {existing.target}. Signed URLs were discarded; identical manifest registration remints them.</p>}
+        {completionSubmitted && !tracked && <p role="status">Completion may already have started a deployment. Re-registering or sending completion again can start another rollout. Reconcile the recorded release first.</p>}
+        {w.error && <ErrorNotice>{w.error}</ErrorNotice>}
+        {progress && !tracked && <p role="status">{progress}</p>}
+        {tracked ? <><p>Deployment {tracked.deployment}: <Status value={outcome?.status ?? 'unknown'} />{['error', 'stopped'].includes(observe.state) && ' · Observation unavailable; outcome unconfirmed'}</p><button className="btn" disabled={w.busy} onClick={observe.refresh}>Refresh exact deployment</button></> :
+            !completionSubmitted && <button className="btn btn-primary" disabled={w.busy || !fileCount || !version} onClick={() => void upload()}>Upload and deploy verified release</button>}
+        {(completionSubmitted || tracked) && <button className="btn" disabled={w.busy} onClick={() => void reconcile()}>Reconcile submitted completion</button>}
+        {onClose && <div className="modal-actions"><button className="btn" disabled={w.busy} onClick={onClose}>Close upload</button></div>}
+        {mayRenew && <div className="deployment-confirm"><p>The prior completion may have run. Starting again is a new deployment decision and can overlap an unobserved attempt. This does not erase or retry the earlier operation.</p>
+            <label>New deployment consent: type {app.slug}/{version}<input value={consent} disabled={w.busy} onChange={e => setConsent(e.target.value)} /></label>
+            <button className="btn" disabled={w.busy || consent !== `${app.slug}/${version}`} onClick={() => void renewConsent()}>Consent to a new deployment attempt</button>
+        </div>}
+    </div>;
+}

package/src/admin/deployments/api.ts

@@ -0,0 +1,158 @@
+import { mojoCall, isReauthRequired, requestFreshAuth } from '../../client/runtime';
+import { MojoError } from '../../client/errors';
+import { appActionsRefused, refuseAppActions } from './authority-state';
+import type { FetchOpts } from '../../client/client';
+import { projectAttempt, projectBootstrap, projectDeployment, projectOperation, projectOptions, projectPlatform, projectPlatformAttempt, projectPrecheck, projectRelease, projectSummaries, projectSummary, projectWebAppObject, record, text, positiveId, list, uuid } from './sanitize';
+import { assertOwner, webAppAuthority, type DeploymentOwner } from './permissions';
+import { appUnsettled, receiptsFor, saveReceipt, singleFlight, type ActionReceipt } from './receipts';
+import type { BackendGlobalUser } from '../fleet/access';
+import type { WebAppObject } from './types';
+import type { ApiAction, CreateProfile, ManifestEntry, OnboardingOperation } from './types';
+const ROOT = '/api/edge';
+function privateError(error: unknown): Error { if (error instanceof DOMException && error.name === 'AbortError')
+    return new DOMException('Deployment owner changed', 'AbortError'); const status = error && typeof error === 'object' && 'status' in error && typeof error.status === 'number' ? error.status : 0; return new MojoError(status === 440 ? 'Fresh authentication required' : status === 403 ? 'Deployment observation or action denied' : 'Deployment request unavailable; outcome may be unknown', status); }
+export async function safeCall<T>(owner: DeploymentOwner, path: string, project: (v: unknown) => T, opts: FetchOpts = {}): Promise<T> { assertOwner(owner, opts.signal); try {
+    const body = await mojoCall(path, {
+        ...opts, unscoped: true, beforeSend: () => { assertOwner(owner, opts.signal); opts.beforeSend?.(); }
+    });
+    assertOwner(owner, opts.signal);
+    return project(body.data);
+}
+catch (error) {
+    throw privateError(error);
+} }
+export const getBootstrap = (o: DeploymentOwner, signal?: AbortSignal) => safeCall(o, '/api/account/admin/bootstrap', projectBootstrap, { signal });
+export const getPlatform = (o: DeploymentOwner, signal?: AbortSignal) => safeCall(o, '/api/account/admin/platform', projectPlatform, { params: { sections: 'deployments,api' }, signal });
+export const getWebApps = (o: DeploymentOwner, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/summaries`, projectSummaries, { signal });
+export const getSummary = (o: DeploymentOwner, id: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/summary`, v => { const s = projectSummary(v); if (s.webapp.id !== id)
+    throw new Error('App identity changed'); return s; }, { params: { webapp: id }, signal });
+export const getWebApp = (o: DeploymentOwner, id: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/${id}`, v => { const s = projectWebAppObject(v); if (s.id !== id || !s.group.id)
+    throw new Error('App ownership unavailable'); return s; }, { params: { graph: 'default' }, signal });
+export const getMember = (o: DeploymentOwner, group: number, signal?: AbortSignal) => safeCall(o, `/api/group/${group}/member`, v => { const r = record(v), p = record(r.permissions); return { permissions: Object.fromEntries(['view_dns', 'manage_dns', 'security', 'manage_webapp'].filter(k => Object.hasOwn(p, k)).map(k => [k, p[k]])) }; }, { signal });
+export async function resolveAppAuthority(o: DeploymentOwner, user: BackendGlobalUser | undefined, app: WebAppObject, kind: 'custom' | 'workflow' | 'release', signal?: AbortSignal) { const base = webAppAuthority(user, app); return base[kind] ? base : webAppAuthority(user, app, await getMember(o, app.group.id, signal)); }
+export async function getHistory(o: DeploymentOwner, app: number, kind: 'release' | 'deployment', start = 0, signal?: AbortSignal, size = kind === 'release' ? 25 : 15) { const body = await mojoCall(`${ROOT}/${kind}`, {
+    unscoped: true, signal, params: {
+        webapp: app, graph: 'list', sort: '-created', start, size: Math.max(1, Math.min(100, Math.floor(size)))
+    }, beforeSend: () => assertOwner(o, signal)
+}).catch(error => { throw privateError(error); }); assertOwner(o, signal); return { items: list(body.data, Math.max(1, Math.min(100, Math.floor(size)))).map(v => kind === 'release' ? projectRelease(v) : projectAttempt(v)), count: typeof body.count === 'number' ? body.count : 0 }; }
+export const getDeployment = (o: DeploymentOwner, id: number, app: number, release: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/release/deployment/${id}`, v => { const d = projectDeployment(v); if (d.deployment !== id || d.webapp !== app || d.release !== release)
+    throw new Error('Deployment identity mismatch'); return d; }, { signal });
+/** Generic graphs omit the parent: bind the read through both exact server filters. */
+export const getAttempt = (o: DeploymentOwner, id: number, app: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/deployment`, v => {
+    const rows = list(v, 2); const row = projectAttempt(rows[0]);
+    if (!positiveId(id) || !positiveId(app) || rows.length !== 1 || row.id !== id || !row.release?.id) throw new Error('Attempt unavailable in this WebApp');
+    return row;
+}, { params: { webapp: app, id, graph: 'default', start: 0, size: 1 }, signal });
+export const getRelease = (o: DeploymentOwner, id: number, app: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/release`, v => {
+    const rows = list(v, 2); const row = projectRelease(rows[0]);
+    if (!positiveId(id) || !positiveId(app) || rows.length !== 1 || row.id !== id) throw new Error('Release unavailable in this WebApp');
+    return row;
+}, { params: { webapp: app, id, graph: 'default', start: 0, size: 1 }, signal });
+export async function write<T>(o: DeploymentOwner, r: ActionReceipt, path: string, body: Record<string, unknown>, project: (v: unknown) => T, signal?: AbortSignal): Promise<T> { assertOwner(o, signal); if (appActionsRefused(o, r.app))
+    throw new Error('App actions were refused. Refresh safe state and establish a new session before another mutation.'); if (appUnsettled(o, r.app, r.key))
+    throw new Error('Another app operation has an unknown outcome. Refresh its exact status before continuing.'); if (['rollback', 'profile'].includes(r.kind) && r.submitted && !r.settled)
+    throw new Error(r.kind === 'profile' ? 'Settings save outcome is unknown. Reload saved settings before making another save.' : 'Rollback delivery is unknown. Observe summary/history; no rollback was replayed.'); saveReceipt({
+    ...r, submitted: true, submittedAt: r.submittedAt ?? Date.now()
+}); return singleFlight(`${o.actor}:${r.app || r.key}`, async () => { try {
+    return await safeCall(o, path, project, {
+        method: 'POST', body, signal, ...(r.kind === 'api' ? { idempotencyKey: r.operation } : {})
+    });
+}
+catch (error) {
+    if (isReauthRequired(error)) {
+        saveReceipt({ ...r, submitted: false, ...(r.kind === 'profile' ? { settled: true } : {}) });
+        await requestFreshAuth();
+        throw new Error('Authentication renewed or cancelled. Refresh authoritative state and explicitly confirm again; nothing was replayed.');
+    }
+    if (error instanceof MojoError && error.status === 403 && r.app)
+        refuseAppActions(o, r.app);
+    if (error && typeof error === 'object' && 'status' in error && [400, 401, 403, 404, 409, 440].includes(Number(error.status)))
+        saveReceipt({ ...r, settled: r.kind==='upload'&&r.uploadPhase==='completion_submitted'?false:true });
+    throw new Error(error instanceof DOMException && error.name === 'AbortError' ? 'Session or view changed. The submitted operation may persist. Resume to reconcile.' : 'The operation was refused or delivery is uncertain. Refresh authoritative state before retrying.');
+} }); }
+export type WebAppProfilePatch = { display_name: string; environment: string; github_repository: string; deployment_ref: string; build_output: string };
+export function saveWebAppProfile(o: DeploymentOwner, r: ActionReceipt, app: WebAppObject, patch: WebAppProfilePatch, signal?: AbortSignal) {
+    const fields = ['display_name', 'environment', 'github_repository', 'deployment_ref', 'build_output'] as const;
+    if (r.kind !== 'profile' || r.app !== app.id || Object.keys(patch).some(key => !fields.includes(key as typeof fields[number])) || fields.some(key => typeof patch[key] !== 'string')) throw new Error('Unsupported WebApp profile fields');
+    return write(o, r, `${ROOT}/webapp/${app.id}`, Object.fromEntries(fields.map(key => [key, patch[key]])), v => {
+        const saved = projectWebAppObject(v);
+        if (saved.id !== app.id || saved.group.id !== app.group.id) throw new Error('WebApp ownership changed');
+        return saved;
+    }, signal);
+}
+export async function recoverApi(o: DeploymentOwner, r: ActionReceipt, id: string, action: ApiAction, signal?: AbortSignal) { if (!uuid(id))
+    throw new Error('Invalid deployment ID'); return write(o, r, `/api/account/admin/platform/deploy/${action}`, { deployment: id }, v => { const d = projectPlatformAttempt(record(v).deployment); if (!d.id || (action !== 'retry' && d.id !== id))
+    throw new Error('Deployment identity mismatch'); return d; }, signal); }
+export const rollback = (o: DeploymentOwner, r: ActionReceipt, app: number, release: number, group: number, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/rollback`, {
+    webapp: app, release, group
+}, v => { const d = projectDeployment(v); if (!d.deployment || d.webapp !== app || d.release !== release)
+    throw new Error('Rollback identity mismatch'); return d; }, signal);
+export const getOptions = (o: DeploymentOwner, intent: {
+    group: number;
+} | {
+    group_intent: 'new';
+}, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/options`, projectOptions, { params: intent, signal });
+export const precheckAddress = (o: DeploymentOwner, intent: {
+    group: number;
+} | {
+    group_intent: 'new';
+}, url: string, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/precheck`, projectPrecheck, { params: { ...intent, url }, signal });
+export const getOperation = (o: DeploymentOwner, id: string, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/detail`, v => { const p = projectOperation(v); if (p.operation_id !== id)
+    throw new Error('Operation identity mismatch'); return p; }, { params: { operation: id }, signal });
+export const createApp = (o: DeploymentOwner, r: ActionReceipt, p: CreateProfile, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/onboarding/create`, { ...p }, v => { const operation = projectOperation(record(v).operation); if (operation.operation_id !== p.operation_id)
+    throw new Error('Operation identity mismatch'); return operation; }, signal);
+export const chooseOnboarding = (o: DeploymentOwner, r: ActionReceipt, p: OnboardingOperation, choice: Record<string, unknown>, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/onboarding/choose`, {
+    operation: p.operation_id, revision: p.revision, step: p.cursor, choice
+}, v => { const next = projectOperation(v); if (next.operation_id !== p.operation_id)
+    throw new Error('Operation identity mismatch'); return next; }, signal);
+export const cancelOnboarding = (o: DeploymentOwner, r: ActionReceipt, id: string, signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/onboarding/cancel`, { operation: id }, projectOperation, signal);
+export const getWorkflow = (o: DeploymentOwner, app: number, group: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/onboarding/workflow`, v => { const r = record(v); return {
+    filename: '.github/workflows/deploy-webapp.yml', repository: text(r.repository), yaml: text(r.yaml, 32000)
+}; }, {
+    method: 'POST', body: { webapp: app, group }, signal
+}).catch(async (error) => { if (isReauthRequired(error)) {
+    await requestFreshAuth();
+    throw new Error('Authentication prompted. Review and explicitly generate the workflow again; nothing was replayed.');
+} throw error; });
+/** Secret never crosses a Query/Mutation cache or error object. */
+export const changeKey = (o: DeploymentOwner, r: ActionReceipt, app: number, group: number, action: 'mint' | 'rotate' | 'revoke', signal?: AbortSignal) => write(o, r, `${ROOT}/webapp/${action === 'revoke' ? 'revoke_key' : 'link_key'}`, {
+    webapp: app, group, operation_id: r.operation, ...(action === 'revoke' ? {} : { action })
+}, v => { const x = record(v); if (positiveId(x.webapp) !== app)
+    throw new Error('Key receipt identity mismatch'); return { token: typeof x.token === 'string' ? x.token.slice(0, 8192) : null, replayed: x.replayed === true }; }, signal);
+export const getKeyStatus = (o: DeploymentOwner, app: number, group: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/key_status`, v => { const r = record(v), s = record(r.status); if (positiveId(r.webapp) !== app)
+    throw new Error('Key identity mismatch'); return { linked: s.linked === true, active: s.active === true }; }, { params: { webapp: app, group }, signal });
+export const getHealth = (o: DeploymentOwner, app: number, group: number, signal?: AbortSignal) => safeCall(o, `${ROOT}/webapp/health`, v => { const r = record(v); if (positiveId(r.webapp) !== app)
+    throw new Error('Health identity mismatch'); return {
+    status: text(r.status) || 'unknown', detail: text(r.detail, 500), checked: text(r.checked)
+}; }, { params: { webapp: app, group }, signal });
+export async function registerUpload(o: DeploymentOwner, r: ActionReceipt, app: number, group: number, version: string, manifest: ManifestEntry[], signal?: AbortSignal) { const current=receiptsFor(o).find(x=>x.key===r.key)??r;if(['completion_submitted','observing'].includes(current.uploadPhase??''))throw new Error('Completion was already submitted. Reconcile its exact deployment before a new explicit deployment decision.');return write(o, r, `${ROOT}/release`, {
+    webapp: app, group, version, manifest
+}, v => { const d = record(v); if (!positiveId(d.release) || text(d.version) !== version)
+    throw new Error('Release identity mismatch'); return {
+    release: positiveId(d.release), status: text(d.status), uploads: list(d.uploads, 5000).map(v => { const u = record(v), h = record(u.headers); return {
+        path: text(u.path, 1024), url: text(u.url, 8192), headers: { 'x-amz-checksum-sha256': text(h['x-amz-checksum-sha256'], 64) }
+    }; })
+}; }, signal); }
+/** Completion is a deployment request, not an idempotent verification read. */
+export async function completeUpload(o:DeploymentOwner,r:ActionReceipt,release:number,app:number,group:number,signal?:AbortSignal){
+ return singleFlight(`upload-completion:${o.actor}:${app}`,async()=>{
+  const current=receiptsFor(o).find(x=>x.key===r.key)??r;
+  if(['completion_submitted','observing'].includes(current.uploadPhase??''))throw new Error('Completion delivery is unsettled or already observed. Reconcile before consenting to another deployment.');
+  if(current.release!==release||current.app!==app)throw new Error('Upload receipt identity changed');
+  const history=await getHistory(o,app,'deployment',0,signal,100);
+  const submitted=saveReceipt({...current,uploadPhase:'completion_submitted',completionSubmittedAt:Date.now(),completionBaseline:history.items.map(x=>x.id)});
+  const result=await write(o,submitted,`${ROOT}/release/complete`,{release,group},v=>{const d=record(v);if(positiveId(d.release)!==release||positiveId(d.webapp)!==app||!positiveId(d.deployment))throw new Error('Completion identity mismatch');return {deployment:positiveId(d.deployment),release,app};},signal);
+  saveReceipt({...submitted,uploadPhase:'observing',deployment:result.deployment});return result;
+ });
+}
+export async function reconcileUploadCompletion(o:DeploymentOwner,r:ActionReceipt,signal?:AbortSignal){
+ const current=receiptsFor(o).find(x=>x.key===r.key)??r;
+ if(current.kind!=='upload'||!current.release||!['completion_submitted','observing'].includes(current.uploadPhase??''))throw new Error('No submitted completion receipt is available');
+ const [summary,history]=await Promise.all([getSummary(o,current.app,signal),getHistory(o,current.app,'deployment',0,signal,100)]);
+ const candidates=history.items.filter(x=>{const a=x as import('./types').Attempt;return !!a.release&&a.release.id===current.release&&a.release.version===current.target&&!(current.completionBaseline??[]).includes(a.id);});
+ const id=current.deployment??(candidates.length===1?candidates[0]!.id:0);
+ const status=id?await getDeployment(o,id,current.app,current.release,signal):null;
+ const signature=JSON.stringify([summary.current_release?.id??null,history.items.map(x=>[x.id,x.status,(x as import('./types').Attempt).release?.id])]);
+ if(status)saveReceipt({...current,uploadPhase:'observing',deployment:status.deployment,settled:status.terminal});
+ return {receipt:receiptsFor(o).find(x=>x.key===current.key)!,status,signature};
+}

package/src/admin/deployments/authority-state.ts

@@ -0,0 +1,9 @@
+import { useSyncExternalStore } from 'react';
+import { ownerKey, type DeploymentOwner } from './permissions';
+const refused = new Set<string>();
+const listeners = new Set<() => void>();
+const key = (owner: DeploymentOwner, app: number) => `${ownerKey(owner)}:${app}`;
+export function refuseAppActions(owner: DeploymentOwner, app: number): void { refused.add(key(owner, app)); for (const fn of listeners)
+    fn(); }
+export function appActionsRefused(owner: DeploymentOwner, app: number): boolean { return refused.has(key(owner, app)); }
+export function useAppActionsRefused(owner: DeploymentOwner, app: number): boolean { return useSyncExternalStore(fn => { listeners.add(fn); return () => listeners.delete(fn); }, () => appActionsRefused(owner, app), () => true); }

package/src/admin/deployments/deployment-state.ts

@@ -0,0 +1,13 @@
+import type { ApiAction, PlatformAttempt, Release } from './types';
+export function apiActions(status: string): ApiAction[] { switch (status) {
+    case 'failed': return ['retry', 'verify'];
+    case 'verified':
+    case 'partial':
+    case 'unknown': return ['verify', 'converge'];
+    case 'converged': return ['verify'];
+    default: return [];
+} }
+export function rollbackEligible(release: Release, current: Release | null): boolean { return release.id > 0 && release.id !== current?.id && ['uploaded', 'live', 'superseded'].includes(release.status); }
+export function platformProof(attempt: PlatformAttempt): string { const n = attempt.node_summary; if (attempt.status === 'converged' && n.expected > 0 && n.proven === n.expected)
+    return `${n.proven}/${n.expected} restart proofs at observation`; return `${n.proven}/${n.expected} restart proofs; ${n.reported} reported, ${n.failed} failed (${attempt.status})`; }
+export function deploymentTone(status: string): string { return ['live', 'converged'].includes(status) ? 'ok' : ['failed', 'rolled_back'].includes(status) ? 'bad' : ['requested', 'queued', 'deploying', 'canary', 'fleet', 'partial', 'verified'].includes(status) ? 'warn' : 'dim'; }

package/src/admin/deployments/index.ts

@@ -0,0 +1,4 @@
+export { DeploymentsPage } from './DeploymentsPage';
+export { WebAppDetail } from './WebAppDetail';
+export { DEPLOYMENTS_PERMISSIONS } from './permissions';
+export type { WebAppSummary, PlatformAttempt, OnboardingOperation, DeploymentStatus, DeploymentsDestinations } from './types';

package/src/admin/deployments/onboarding-state.ts

@@ -0,0 +1,11 @@
+import type { OnboardingOperation } from './types';
+export const onboardingTerminal = (o: OnboardingOperation) => ['succeeded', 'failed', 'cancelled'].includes(o.status);
+export function onboardingPollable(o: OnboardingOperation): boolean { return !onboardingTerminal(o) && ['app', 'address', 'github', 'verify'].includes(o.cursor) && (o.status === 'active' || (o.status === 'waiting' && !!o.next_attempt_at)); }
+export function onboardingGeneration(o: OnboardingOperation): string { return `${o.operation_id}:${o.revision}:${o.cursor}`; }
+export function managedChoice(o: OnboardingOperation, domain: number, label: string): Record<string, unknown> | null { switch (o.cursor) {
+    case 'app': return {};
+    case 'address': return domain > 0 && /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label) ? { domain, label } : null;
+    case 'github': return { skip: true };
+    case 'verify': return {};
+    default: return null;
+} }

package/src/admin/deployments/permissions.ts

@@ -0,0 +1,37 @@
+import { backendGlobalCan, type BackendGlobalUser } from '../fleet/access';
+import { decodeJwt } from '../../client/jwt';
+import { getAccessToken, getAuthSessionRevision, getAuthSnapshot } from '../../client/auth';
+import type { Bootstrap, WebAppObject } from './types';
+export const DEPLOYMENTS_PERMISSIONS = ['sys.view_platform', 'sys.manage_platform', 'sys.admin', 'sys.view_dns', 'sys.manage_dns', 'sys.security'];
+const active = (u: BackendGlobalUser | null | undefined) => !!u && (!('is_active' in u) || u.is_active !== false);
+export const canReadApi = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['view_platform', 'manage_platform', 'admin']);
+export const canRecoverApi = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['manage_platform', 'admin']);
+export const canReadWebApps = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['view_dns', 'manage_dns', 'security']);
+export const canReadBootstrap = (u: BackendGlobalUser | null | undefined) => active(u) && backendGlobalCan(u, ['view_admin', 'manage_users', 'manage_settings', 'admin']);
+export function isInteractive(): boolean { const s = getAuthSnapshot(), c = decodeJwt(getAccessToken()); return s.authenticated && !!c && c.credential_kind !== 'api_key' && c.credential_kind !== 'group_scoped_token'; }
+export interface DeploymentOwner {
+    actor: string;
+    origin: string;
+    session: number;
+    signal?: AbortSignal;
+}
+export function deploymentOwner(): DeploymentOwner { return {
+    actor: getAuthSnapshot().uid ?? '', origin: typeof window === 'undefined' ? '' : window.location.origin, session: getAuthSessionRevision()
+}; }
+export function ownerKey(o: DeploymentOwner): string { return `${o.origin}:${o.actor}:${o.session}`; }
+export function assertOwner(o: DeploymentOwner, signal?: AbortSignal): void { signal?.throwIfAborted(); o.signal?.throwIfAborted(); const now = deploymentOwner(); if (!getAuthSnapshot().authenticated || !o.actor || ownerKey(o) !== ownerKey(now))
+    throw new DOMException('Session changed; refresh and review again', 'AbortError'); }
+/** SAVE_PERMS is the first configured RestMeta clause for writes; VIEW is read-only. */
+export function webAppAuthority(user: BackendGlobalUser | null | undefined, app: WebAppObject, member?: {
+    permissions?: Record<string, unknown>;
+} | null) {
+    const local = member ? { permissions: member.permissions } : null;
+    const can = (grants: readonly string[]) => backendGlobalCan(user, grants) || backendGlobalCan(local, grants);
+    const object = active(user) && app.id > 0 && app.group.id > 0;
+    const view = object && can(['view_dns', 'manage_dns', 'security']);
+    const save = object && can(['manage_dns', 'security']);
+    return {
+        read: view, custom: save && can(['manage_webapp']), release: save, workflow: active(user) && app.group.id > 0 && (can(['security']) || (can(['manage_webapp']) && can(['manage_dns'])))
+    };
+}
+export function canOnboard(bootstrap: Bootstrap | undefined): boolean { return !!bootstrap && (bootstrap.groups.length > 0 || bootstrap.can_create_webapp_group); }

package/src/admin/deployments/receipts.ts

@@ -0,0 +1,78 @@
+import type { CreateProfile, ManifestEntry } from './types';
+import { record, text, uuid, positiveId, list } from './sanitize';
+import type { DeploymentOwner } from './permissions';
+export interface ActionReceipt {
+    version: 1;
+    actor: string;
+    origin: string;
+    key: string;
+    operation: string;
+    kind: 'create' | 'api' | 'key' | 'rollback' | 'upload' | 'profile';
+    app: number;
+    target: string;
+    settled: boolean;
+    submitted?: boolean;
+    submittedAt?: number;
+    acknowledged?: boolean;
+    address?: {
+        domain: number;
+        label: string;
+    };
+    onboardingGroup?: number;
+    profile?: CreateProfile;
+    manifest?: ManifestEntry[];
+    release?: number;
+    deployment?: number;
+    uploadPhase?: 'registered' | 'completion_submitted' | 'observing';
+    completionSubmittedAt?: number;
+    completionBaseline?: number[];
+}
+const STORAGE = 'mojo.deployment.receipts.v1';
+const memory = new Map<string, ActionReceipt>();
+const active = new Set<string>();
+function project(v: unknown): ActionReceipt | null { const r = record(v); if (r.version !== 1 || !['create', 'api', 'key', 'rollback', 'upload', 'profile'].includes(String(r.kind)) || !uuid(r.operation) || !text(r.actor) || !text(r.origin) || !text(r.key))
+    return null; const receipt: ActionReceipt = {
+    version: 1, actor: text(r.actor), origin: text(r.origin), key: text(r.key), operation: uuid(r.operation), kind: r.kind as ActionReceipt['kind'], app: positiveId(r.app), target: text(r.target), settled: r.settled === true, submitted: r.submitted === true, submittedAt: typeof r.submittedAt === 'number' ? r.submittedAt : undefined, acknowledged: r.acknowledged === true, release: positiveId(r.release) || undefined, deployment: positiveId(r.deployment) || undefined
+}; if(positiveId(r.onboardingGroup))receipt.onboardingGroup=positiveId(r.onboardingGroup);if(r.kind==='upload'){
+    if(['registered','completion_submitted','observing'].includes(String(r.uploadPhase)))receipt.uploadPhase=r.uploadPhase as ActionReceipt['uploadPhase'];
+    if(typeof r.completionSubmittedAt==='number'&&Number.isFinite(r.completionSubmittedAt))receipt.completionSubmittedAt=r.completionSubmittedAt;
+    if(Array.isArray(r.completionBaseline))receipt.completionBaseline=list(r.completionBaseline,100).map(positiveId).filter(Boolean);
+} if (r.address) {
+    const a = record(r.address);
+    receipt.address = { domain: positiveId(a.domain), label: text(a.label, 63) };
+} if (r.kind === 'create' && r.profile) {
+    const p = record(r.profile);
+    receipt.profile = {
+        operation_id: receipt.operation, ...(positiveId(p.group) ? { group: positiveId(p.group) } : { group_intent: 'new' as const }), slug: text(p.slug, 64), display_name: text(p.display_name, 120), environment: text(p.environment, 16), bucket: text(p.bucket), github_repository: text(p.github_repository), deployment_ref: text(p.deployment_ref), build_output: text(p.build_output)
+    };
+} if (r.kind === 'upload' && Array.isArray(r.manifest))
+    receipt.manifest = list(r.manifest, 5000).map(v => { const p = record(v); return {
+        path: text(p.path, 1024), sha256: text(p.sha256, 64), size: typeof p.size === 'number' ? p.size : 0
+    }; }); return receipt; }
+function restore() { try {
+    for (const raw of JSON.parse(sessionStorage.getItem(STORAGE) ?? '[]')) {
+        const r = project(raw);
+        if (r && !memory.has(r.key))
+            memory.set(r.key, r);
+    }
+}
+catch { /* session-only fallback */ } }
+function persist() { try {
+    sessionStorage.setItem(STORAGE, JSON.stringify([...memory.values()].slice(-32)));
+}
+catch { /* receipt remains for this tab */ } }
+export function receiptsFor(owner: DeploymentOwner): ActionReceipt[] { restore(); return [...memory.values()].filter(r => r.actor === owner.actor && r.origin === owner.origin).map(r => ({ ...r })); }
+export function saveReceipt(receipt: ActionReceipt) { const safe = project(receipt); if (!safe)
+    throw new Error('Invalid deployment receipt'); memory.set(safe.key, safe); persist(); return safe; }
+export function makeReceipt(owner: DeploymentOwner, kind: ActionReceipt['kind'], scope: string, app = 0, target = ''): ActionReceipt { const key = `${owner.origin}:${owner.actor}:${kind}:${scope}`; const previous = receiptsFor(owner).find(r => r.key === key); return previous && (!previous.settled || (previous.kind==='upload'&&['completion_submitted','observing'].includes(previous.uploadPhase??''))) ? previous : saveReceipt({
+    version: 1, actor: owner.actor, origin: owner.origin, key, operation: crypto.randomUUID(), kind, app, target, settled: false
+}); }
+export function appUnsettled(owner: DeploymentOwner, app: number, except?: string): ActionReceipt | undefined { return receiptsFor(owner).find(r => r.app === app && app > 0 && !r.settled && r.key !== except); }
+export function settleReceipt(r: ActionReceipt) { saveReceipt({ ...r, settled: true }); }
+export async function singleFlight<T>(key: string, fn: () => Promise<T>): Promise<T> { if (active.has(key))
+    throw new Error('An operation for this target is already pending'); active.add(key); try {
+    return await fn();
+}
+finally {
+    active.delete(key);
+} }