@wtfalch/foundry 0.62.0 → 0.63.0

package/dist/plan/stage-copy-host.d.ts

@@ -0,0 +1,104 @@
+import type { StageCopyOutcome } from '../release/run.js';
+import type { BlueGreenSubject } from './blue-green.js';
+import type { ReleaseContext } from './release-host.js';
+import { type StageCopyPortDeps } from './stage-copy-port.js';
+import { type StageCopyCoolify, type StageCopyPort, type StageCopyTimeouts } from './stage-copy.js';
+/** What the host supplies for the copy (`FoundryStepExecutorPorts.stageCopy`). Foundry builds the port itself. */
+export interface StageCopyHostConfig {
+    fetchDump: StageCopyPortDeps['fetchDump'];
+    /** The registered backup storage the production schedule saves to. */
+    storageUuid: string;
+}
+/** Everything one subject's copy needs, built by the executor that knows the subject's recorded keys. */
+export interface StageCopyHostPorts {
+    restore: StageCopyPort;
+    coolify: StageCopyCoolify;
+    org: {
+        slug: string;
+    };
+    storageUuid: string;
+    secret: (value: string) => void;
+    /** The name in the backup keys; goes into dump errors. */
+    databaseKey: string;
+    /** Recorded key of production's Coolify database; null: the subject has none. */
+    databaseScopeKey: string | null;
+    /** Recorded key of its backup schedule; null or unrecorded: the schedule is found live. */
+    backupScopeKey: string | null;
+    projectScopeKey: string;
+    serverScopeKey: string;
+    timeouts?: StageCopyTimeouts;
+    /** Lock length and heartbeat; tests shorten them. */
+    lockMs?: number;
+    heartbeatMs?: number;
+    now?: () => number;
+}
+/** A copy can take ~45 minutes: the lock outlives it, and the lease is renewed every five minutes meanwhile. */
+export declare const STAGE_COPY_LOCK_MS: number;
+export declare const STAGE_COPY_HEARTBEAT_MS: number;
+/** Builds the ports for a subject, or `undefined` when the host supplies no `stageCopy`. */
+export declare function buildStageCopyHostPorts(input: {
+    host: StageCopyHostConfig | undefined;
+    coolify: StageCopyCoolify;
+    context: Pick<ReleaseContext, 'recordedIds'>;
+    org: {
+        slug: string;
+    };
+    secret: (value: string) => void;
+    databaseKey: string;
+    databaseScopeKey: string | null;
+    backupScopeKey: string | null;
+    projectScopeKey: string;
+    serverScopeKey: string;
+}): StageCopyHostPorts | undefined;
+/** The recorded lock value: `<expiry ms>|<request id>|<run id>`. The run id tells a run from a later re-claim. */
+export declare const stageCopyLockValue: (expiry: number, requestId: number | string, runId: string) => string;
+/** The parts of a recorded lock value; absent parts are undefined. */
+export declare function parseStageCopyLock(value: string | undefined): {
+    expiry: number;
+    requestId?: string;
+    runId?: string;
+};
+/**
+ * Takes the copy's own lock `bg.<id>.stagecopylock` and persists it, unless a live one is recorded. The caller
+ * holds the lease that fences the persist. A copy then runs without the org's lease, guarded by this lock alone.
+ */
+export declare function claimStageCopyLock(input: {
+    subjectId: string;
+    context: ReleaseContext;
+    requestId: number | string;
+    /** This run's token, written into the lock. */
+    runId: string;
+    now?: () => number;
+    lockMs?: number;
+}): Promise<'claimed' | 'busy'>;
+/**
+ * Runs one `copy_prod_to_stage` or `undo_stage_copy` request. Exclusion: the recorded lock
+ * `bg.<id>.stagecopylock` (`<expiry ms>|<request id>`, one hour). The caller normally took it already
+ * ({@link claimStageCopyLock}, under the org's lease) and runs this without that lease; a lock for this request
+ * that is already live counts as taken. Otherwise it is taken here, persisted before anything starts, and
+ * removed in the same persist as the result, so a second process leaves the request open while it is held.
+ * `renew` is called every five minutes to keep the lock alive and throws when it was taken over.
+ * `bg.<id>.stagecopyhandled` is written in that same persist: a crash before the request is consumed replays
+ * into a consume, not a second copy.
+ *
+ * A failure halfway leaves what `stageCopy`/`undoStageCopy` documents (the new database deleted, stage on its
+ * own database). The lock is dropped and persisted; if that persist fails the lock expires on its own.
+ * A failure after the switch (recording the result, or recording an adopted switch) is not a failure of the
+ * copy: stage runs on the new database, the records are in memory, and the caller's persist lands them. It is
+ * reported as `ok`, so the request is not retried at once. If that persist fails too (or the process dies),
+ * nothing is recorded and the lock lapses; the request then runs again, but `stageCopy` first finds the switch
+ * from stage's live env and records it (kept = the recorded database) without copying again. The guarantee is
+ * "never a second copy over a landed switch", not "always recorded on the first try".
+ * Every outcome is a reason, a step or an id: no URL, no secret, no cause text.
+ */
+export declare function runStageCopyRequest(input: {
+    subject: Pick<BlueGreenSubject, 'id' | 'base' | 'database'>;
+    context: ReleaseContext;
+    ports: StageCopyHostPorts | undefined;
+    renew: () => Promise<void>;
+}, request: {
+    mode: 'copy' | 'undo';
+    requestId: number;
+    actor: string;
+    runId?: string;
+}): Promise<StageCopyOutcome>;

package/dist/plan/stage-copy-host.js

@@ -0,0 +1,259 @@
+import { randomUUID } from 'node:crypto';
+import { releaseKeys } from '../release/state.js';
+import { StaleLeaseError } from '../store.js';
+import { bgKey } from './blue-green.js';
+import { withTimeout } from './call-timeout.js';
+import { createStageCopyPort } from './stage-copy-port.js';
+import { StageCopyFailedError, StageCopyRefusedError, stageCopy, undoStageCopy, } from './stage-copy.js';
+/** A copy can take ~45 minutes: the lock outlives it, and the lease is renewed every five minutes meanwhile. */
+export const STAGE_COPY_LOCK_MS = 60 * 60_000;
+export const STAGE_COPY_HEARTBEAT_MS = 5 * 60_000;
+const CALL_MS = 30_000;
+/** Builds the ports for a subject, or `undefined` when the host supplies no `stageCopy`. */
+export function buildStageCopyHostPorts(input) {
+    const { host, coolify } = input;
+    if (!host)
+        return undefined;
+    const restore = createStageCopyPort({
+        // Read live on each call: production's address is never held or recorded.
+        productionUrls: async () => {
+            const uuid = input.databaseScopeKey
+                ? input.context.recordedIds()[input.databaseScopeKey]
+                : undefined;
+            if (!uuid)
+                return [];
+            const database = await coolify.getDatabase(uuid);
+            return database.internal_db_url ? [database.internal_db_url] : [];
+        },
+        fetchDump: host.fetchDump,
+    });
+    return {
+        restore,
+        coolify,
+        org: input.org,
+        storageUuid: host.storageUuid,
+        secret: input.secret,
+        databaseKey: input.databaseKey,
+        databaseScopeKey: input.databaseScopeKey,
+        backupScopeKey: input.backupScopeKey,
+        projectScopeKey: input.projectScopeKey,
+        serverScopeKey: input.serverScopeKey,
+    };
+}
+function lockHeld(value, now) {
+    const expiry = Number((value ?? '').split('|')[0]);
+    return Number.isFinite(expiry) && expiry > now;
+}
+/** The recorded lock value: `<expiry ms>|<request id>|<run id>`. The run id tells a run from a later re-claim. */
+export const stageCopyLockValue = (expiry, requestId, runId) => `${expiry}|${requestId}|${runId}`;
+/** The parts of a recorded lock value; absent parts are undefined. */
+export function parseStageCopyLock(value) {
+    const [expiry, requestId, runId] = (value ?? '').split('|');
+    return {
+        expiry: Number(expiry),
+        ...(requestId ? { requestId } : {}),
+        ...(runId ? { runId } : {}),
+    };
+}
+/**
+ * Takes the copy's own lock `bg.<id>.stagecopylock` and persists it, unless a live one is recorded. The caller
+ * holds the lease that fences the persist. A copy then runs without the org's lease, guarded by this lock alone.
+ */
+export async function claimStageCopyLock(input) {
+    const keys = releaseKeys(input.subjectId);
+    const now = input.now ?? Date.now;
+    if (lockHeld(input.context.recordedIds()[keys.stageCopyLock], now()))
+        return 'busy';
+    input.context.recordScopeId(keys.stageCopyLock, stageCopyLockValue(now() + (input.lockMs ?? STAGE_COPY_LOCK_MS), input.requestId, input.runId));
+    await input.context.persist();
+    return 'claimed';
+}
+/** Whether a step of the run finished after the switch: stage already runs on the other database. */
+const switched = (record) => record.steps.some((s) => (s.step === 'switch' || s.step === 'adopt') && s.outcome === 'ok');
+/**
+ * Runs one `copy_prod_to_stage` or `undo_stage_copy` request. Exclusion: the recorded lock
+ * `bg.<id>.stagecopylock` (`<expiry ms>|<request id>`, one hour). The caller normally took it already
+ * ({@link claimStageCopyLock}, under the org's lease) and runs this without that lease; a lock for this request
+ * that is already live counts as taken. Otherwise it is taken here, persisted before anything starts, and
+ * removed in the same persist as the result, so a second process leaves the request open while it is held.
+ * `renew` is called every five minutes to keep the lock alive and throws when it was taken over.
+ * `bg.<id>.stagecopyhandled` is written in that same persist: a crash before the request is consumed replays
+ * into a consume, not a second copy.
+ *
+ * A failure halfway leaves what `stageCopy`/`undoStageCopy` documents (the new database deleted, stage on its
+ * own database). The lock is dropped and persisted; if that persist fails the lock expires on its own.
+ * A failure after the switch (recording the result, or recording an adopted switch) is not a failure of the
+ * copy: stage runs on the new database, the records are in memory, and the caller's persist lands them. It is
+ * reported as `ok`, so the request is not retried at once. If that persist fails too (or the process dies),
+ * nothing is recorded and the lock lapses; the request then runs again, but `stageCopy` first finds the switch
+ * from stage's live env and records it (kept = the recorded database) without copying again. The guarantee is
+ * "never a second copy over a landed switch", not "always recorded on the first try".
+ * Every outcome is a reason, a step or an id: no URL, no secret, no cause text.
+ */
+export async function runStageCopyRequest(input, request) {
+    const { subject, context, ports } = input;
+    if (!ports)
+        return { outcome: 'refused', reason: 'no-copy-port' };
+    const id = subject.id;
+    const keys = releaseKeys(id);
+    const now = ports.now ?? Date.now;
+    const requestId = String(request.requestId);
+    const recordedNow = context.recordedIds();
+    // Its result was already persisted by an earlier run that crashed before the request was consumed.
+    if (recordedNow[keys.stageCopyHandled] === requestId) {
+        return { outcome: 'ok', detail: request.mode === 'copy' ? 'copy' : 'undo', recorded: true };
+    }
+    const lock = recordedNow[keys.stageCopyLock];
+    // Mine means this run's token, not only this request: a re-claim after the lock lapsed is another run.
+    const parsed = parseStageCopyLock(lock);
+    const mine = lockHeld(lock, now()) &&
+        request.runId !== undefined &&
+        parsed.requestId === requestId &&
+        parsed.runId === request.runId;
+    if (!mine) {
+        const claimed = await claimStageCopyLock({
+            subjectId: id,
+            context,
+            requestId,
+            runId: request.runId ?? randomUUID(),
+            now,
+            ...(ports.lockMs !== undefined ? { lockMs: ports.lockMs } : {}),
+        });
+        if (claimed === 'busy')
+            return { outcome: 'busy' };
+    }
+    let stale = false;
+    const heartbeat = setInterval(() => {
+        input.renew().catch(() => {
+            stale = true;
+        });
+    }, ports.heartbeatMs ?? STAGE_COPY_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    const recorded = () => context.recordedIds();
+    // The last persist of a successful run carries the result, the handled mark and the lock's removal together.
+    const finalKey = request.mode === 'copy' ? bgKey.stageCopy(id) : bgKey.stageKept(id);
+    const base = {
+        subject,
+        recorded,
+        record: (key, value) => {
+            context.recordScopeId(key, value);
+            if (key === finalKey && (request.mode === 'copy' || value === '')) {
+                context.recordScopeId(keys.stageCopyHandled, requestId);
+                context.forgetId(keys.stageCopyLock);
+            }
+        },
+        persist: async () => {
+            try {
+                await context.persist();
+            }
+            catch (error) {
+                // A persist refused because the lock is another run's must not be read as a failed record.
+                if (error instanceof StaleLeaseError)
+                    stale = true;
+                throw error;
+            }
+        },
+        coolify: ports.coolify,
+        secret: ports.secret,
+        requestedBy: request.actor,
+        now,
+        ...(ports.timeouts ? { timeouts: ports.timeouts } : {}),
+    };
+    let outcome;
+    try {
+        const run = request.mode === 'copy'
+            ? await stageCopy({
+                ...base,
+                org: ports.org,
+                production: await resolveProduction(input.subject, context, ports),
+                restore: ports.restore,
+                projectUuid: recorded()[ports.projectScopeKey],
+                serverUuid: recorded()[ports.serverScopeKey],
+            })
+            : await undoStageCopy({ ...base, restore: ports.restore });
+        outcome = {
+            outcome: 'ok',
+            detail: request.mode === 'copy' ? (run.dumpExecutionId ?? 'copy') : 'undo',
+            recorded: request.mode === 'copy',
+        };
+    }
+    catch (error) {
+        if (stale) {
+            // Another run holds the lock now: record nothing, report it below.
+            outcome = { outcome: 'busy' };
+        }
+        else if (error instanceof StageCopyFailedError && switched(error.record)) {
+            outcome = {
+                outcome: 'ok',
+                detail: request.mode === 'copy' ? (error.record.dumpExecutionId ?? 'copy') : 'undo',
+                recorded: request.mode === 'copy',
+            };
+            console.error('stage copy: stage runs on the new database but recording it failed');
+        }
+        else {
+            await dropLock(context, keys, requestId);
+            if (error instanceof StageCopyRefusedError) {
+                outcome = { outcome: 'refused', reason: error.reason };
+            }
+            else if (error instanceof StageCopyFailedError) {
+                const failed = [...error.record.steps].reverse().find((s) => s.outcome === 'failed');
+                outcome = { outcome: 'failed', step: failed?.step ?? 'unknown' };
+            }
+            else {
+                console.error(`stage copy: request failed (${error instanceof Error ? error.name : 'unknown'})`);
+                outcome = { outcome: 'failed', step: 'unexpected' };
+            }
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+    // A lock that could not be kept means another run may hold the copy now: report it, not an outcome.
+    if (stale)
+        throw new StaleLeaseError('stage copy');
+    return outcome;
+}
+/** Undoes the in-memory marks of a run that did not finish and persists the lock's removal. */
+async function dropLock(context, keys, requestId) {
+    if (context.recordedIds()[keys.stageCopyHandled] === requestId) {
+        context.forgetId(keys.stageCopyHandled);
+    }
+    context.forgetId(keys.stageCopyLock);
+    try {
+        await context.persist();
+    }
+    catch (error) {
+        // The lock expires on its own; the next run waits for that.
+        console.error(`stage copy: removing the lock failed (${error instanceof Error ? error.name : 'unknown'})`);
+    }
+}
+async function resolveProduction(subject, context, ports) {
+    if (!subject.database || !ports.databaseScopeKey)
+        return null;
+    const recorded = context.recordedIds();
+    const databaseUuid = recorded[ports.databaseScopeKey];
+    if (!databaseUuid)
+        return null;
+    let backupUuid = ports.backupScopeKey ? recorded[ports.backupScopeKey] : undefined;
+    if (!backupUuid) {
+        let schedules;
+        try {
+            schedules = await withTimeout('stage copy: list the backup schedules', CALL_MS, () => ports.coolify.listDatabaseBackups(databaseUuid));
+        }
+        catch (error) {
+            console.error(`stage copy: reading the backup schedules failed (${error instanceof Error ? error.name : 'unknown'})`);
+            return null;
+        }
+        backupUuid = schedules.find((s) => s.enabled !== false &&
+            s.save_s3 &&
+            (s.s3_storage_uuid === undefined || s.s3_storage_uuid === ports.storageUuid))?.uuid;
+    }
+    if (!backupUuid)
+        return null;
+    return {
+        databaseKey: ports.databaseKey,
+        databaseUuid,
+        backupUuid,
+        storageUuid: ports.storageUuid,
+    };
+}

package/dist/plan/stage-copy.js

@@ -217,6 +217,30 @@ async function deleteQuietly(base, cfg, uuid) {
         logFailure('deleting a database', error);
     }
 }
+/**
+ * The copy database stage really runs on when the records name another: a database with the copy prefix whose
+ * address is stage's live owner URL. Unreadable databases do not count. `undefined`: none.
+ */
+async function switchedWithoutRecord(base, cfg, recordedDbId, liveOwnerUrl) {
+    const live = dbIdentity(liveOwnerUrl);
+    if (live === null)
+        return undefined;
+    const prefix = COPY_PREFIX(base.subject.base);
+    const listed = await withTimeout('stage copy: list databases', cfg.callMs, () => base.coolify.listDatabases());
+    for (const database of listed) {
+        if (database.uuid === recordedDbId || !database.name.startsWith(prefix))
+            continue;
+        try {
+            const { internal_db_url: url } = await withTimeout('stage copy: read a database', cfg.callMs, () => base.coolify.getDatabase(database.uuid));
+            if (url !== undefined && dbIdentity(url) === live)
+                return database.uuid;
+        }
+        catch (error) {
+            logFailure('reading a database', error);
+        }
+    }
+    return undefined;
+}
 function checkInput(base) {
     requireText('requestedBy', base.requestedBy);
     requireText('subject.id', base.subject.id);
@@ -297,6 +321,26 @@ export async function stageCopy(input) {
     const run = new Run(input.requestedBy, input.now ?? Date.now, stageDbId);
     const pgName = pgNameOf(subject.base);
     const runtimeRole = `${pgName}_rt`;
+    // An earlier run may have switched stage and lost its records (the persist failed, or the process died). Stage
+    // then runs on a copy database the records do not name. Record that switch instead of copying again, so the
+    // database stage ran on stays the undo target and no second copy is made.
+    const earlierId = await switchedWithoutRecord(input, cfg, stageDbId, liveOwnerUrl);
+    if (earlierId) {
+        run.liveDatabaseId = earlierId;
+        run.ok('adopt');
+        input.record(bgKey.stageKept(id), stageDbId);
+        input.record(bgKey.stageDatabase(id), earlierId);
+        input.record(bgKey.stageCopy(id), `${new Date(run.now()).toISOString()}|adopted|ok`);
+        try {
+            await input.persist();
+        }
+        catch (error) {
+            logFailure('recording the database stage runs on', error);
+            throw run.fail('record', 'stage runs on the new database but recording it failed');
+        }
+        run.ok('record');
+        return run.record();
+    }
     let dump;
     try {
         dump = await dumpNow(coolify, {

package/dist/plan/stage-env.d.ts

@@ -15,8 +15,17 @@ export interface StageSignIn {
 }
 /** The names a stage's own sign-in sets; a change to one of them redeploys stage. */
 export declare const STAGE_SIGN_IN_NAMES: readonly string[];
+/**
+ * Agora's stage config: production's `AGORA_CONFIG` (written by `desiredAgoraEnv`, so the shape follows the
+ * builder production uses) with the stage client id, chat and calls off, and only the fields named here. Files
+ * ids, the in-app sign-in flag and any other field production's builder adds later are left out, so nothing
+ * that points at production leaks through. `null` when production's value is not a JSON object.
+ */
+export declare function stageAgoraConfig(prodConfig: string, stageClientId: string): string | null;
 export interface StageEnvInput {
     kind: StageKind;
+    /** Agora only: the id of the stage's own sign-in client. Without it an Agora stage gets no `AGORA_CONFIG`. */
+    stageClientId?: string;
     /** Where the stage app is reached: its own container address, since stage has no hostname. */
     appUrl: string;
     logDir: string;

package/dist/plan/stage-env.js

@@ -25,6 +25,36 @@ export const STAGE_SIGN_IN_NAMES = [
 ];
 /** The shortest `AUTH_APP_KEY` the broker accepts. */
 const MIN_APP_KEY_LENGTH = 32;
+/**
+ * Agora's stage config: production's `AGORA_CONFIG` (written by `desiredAgoraEnv`, so the shape follows the
+ * builder production uses) with the stage client id, chat and calls off, and only the fields named here. Files
+ * ids, the in-app sign-in flag and any other field production's builder adds later are left out, so nothing
+ * that points at production leaks through. `null` when production's value is not a JSON object.
+ */
+export function stageAgoraConfig(prodConfig, stageClientId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(prodConfig);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const prod = parsed;
+    const keep = (name) => prod[name] === undefined ? {} : { [name]: prod[name] };
+    return JSON.stringify({
+        ...keep('name'),
+        ...keep('theme'),
+        ...keep('issuer'),
+        clientId: stageClientId,
+        ...keep('organisationId'),
+        ...keep('mailProjectId'),
+        ...keep('messagingProjectId'),
+        chat: { enabled: false },
+        calls: { enabled: false },
+    });
+}
 /**
  * The env of a stage app, built from the kind's allowlist and never from a copy of the live app's env. Every
  * name is allowed and none is denied, or this throws a fixed text with the name.
@@ -60,6 +90,14 @@ export function buildStageEnv(input) {
     }
     for (const { key, value } of input.signIn?.env ?? [])
         set(key, value);
+    // Agora's stage config is production's with the stage client; `SIGNIN_UPSTREAM` is never written: it names
+    // production's login, and the stage host is not bound there, so stage signs in through the issuer.
+    const prodAgoraConfig = prod.get('AGORA_CONFIG');
+    if (kind === 'agora' && prodAgoraConfig !== undefined && input.stageClientId) {
+        const config = stageAgoraConfig(prodAgoraConfig, input.stageClientId);
+        if (config)
+            set('AGORA_CONFIG', config);
+    }
     for (const key of MINTED) {
         const wanted = prod.has(key) || (input.signIn !== undefined && key === 'AUTH_COOKIE_SECRET');
         if (wanted && isAllowed(kind, key))

package/dist/plan/stage-guards.d.ts

@@ -1,3 +1,5 @@
+import { type StageServicesPort } from './stage-services.js';
+import { type StageSignInPort } from './stage-signin.js';
 /**
  * The guards that must hold before stage gets an exact copy of production (campaign T3 section 5, G2 and G3).
  * Each is checked here and recorded under a `bg.<id>.…` scope key only after it was verified live. Nothing in
@@ -104,14 +106,22 @@ export declare function stageProbesRecord(result: StageProbeResult, isolationHas
 export interface StageGate {
     /** The stage host the gate covers. */
     hostname: string;
-    /** Makes the gate (no bypass and no service-token rule) and returns its id. */
+    /**
+     * Makes the gate (no bypass and no service-token rule) and returns its id. `membersHash` is the hash of the
+     * list it was made with, present only when the members were read; recorded as `bg.<id>.stagegatemembers`.
+     */
     create: () => Promise<{
         id: string;
+        membersHash?: string;
     }>;
 }
 export interface StageGuardDeps {
     probes?: StageProbePort;
+    /** Stage's own sign-in client, broker entry key and app key. Absent: not set up, and the copy waits. */
+    signIn?: StageSignInPort;
     gate?: StageGate;
+    /** Stage's own files, ai and jobs organisations and keys. A service with no port is recorded absent, never minted. */
+    services?: StageServicesPort;
 }
 /** The key of the stage gate in the company (a DNS label, like a declared gate's). */
 export declare const stageGateKey: (id: string) => string;
@@ -122,3 +132,49 @@ export declare function stageGuardsReady(recorded: Readonly<Record<string, strin
     ready: boolean;
     missing: string[];
 };
+/** Milliseconds the host may take to name the people holding `releases:preview`. */
+export declare const STAGE_MEMBERS_TIMEOUT_MS = 10000;
+/** What the host answers for the people who may open stage: `releases:preview` holders of `orgId` (`platform` for Archon). */
+export type ReleasePreviewMembers = (input: {
+    orgId: string;
+}) => Promise<{
+    emails: string[];
+}>;
+/** Trimmed, lower-case, unique and sorted; anything that is not an email address is dropped. */
+export declare function normaliseEmails(list: readonly unknown[]): string[];
+/** The hash recorded for a sorted list. */
+export declare const membersHash: (sorted: readonly string[]) => string;
+/**
+ * The stage gate's list: `owners` always, plus the people `read` names. `members` is false when the read failed,
+ * timed out or the host has no port; the list is then the owners alone. One fixed log line names the subject and
+ * the error name, never an address.
+ */
+export declare function stageGateEmails(input: {
+    label: string;
+    subjectId: string;
+    orgId: string;
+    owners: readonly string[];
+    read?: ReleasePreviewMembers;
+    timeoutMs?: number;
+}): Promise<{
+    emails: string[];
+    members: boolean;
+}>;
+/**
+ * One release tick for one subject whose stage gate is recorded: the gate's list becomes owners plus the people
+ * holding `releases:preview`. Nothing is done while the read fails, the list is unchanged since the last write
+ * (`bg.<id>.stagegatemembers`) or the Access call fails; the hash is recorded only after the Access call
+ * succeeded. Never throws.
+ */
+export declare function syncStageGateMembers(input: {
+    label: string;
+    subjectId: string;
+    orgId: string;
+    owners: readonly string[];
+    read?: ReleasePreviewMembers;
+    recorded: Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    setPeople?: (gateId: string, emails: string[]) => Promise<void>;
+    timeoutMs?: number;
+}): Promise<void>;