@wtfalch/foundry 0.62.0 → 0.64.0

package/dist/plan/plan-apply.js

@@ -4,6 +4,7 @@ import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { sfuSlotPorts } from '../calls-sfu.js';
 import { ORG_SERVICE_SCHEMAS, heldEnvRef, ownsServices, validateHosting } from '../org.js';
 import { PLATFORM_SERVICE_KEYS } from '../platform.js';
+import { recordedFrom, releaseKeys } from '../release/state.js';
 import { AlreadyRunningError, StepFailedError } from '../runner/errors.js';
 import { StaleLeaseError, } from '../store.js';
 import { entryHasDatabase } from '../worker-app-config.js';
@@ -36,8 +37,9 @@ import { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesF
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF, PLATFORM_BACKUP_S3_STORAGE_SCOPE_KEY, } from './platform-providers.js';
 import { privatePageGateKey } from './private-pages.js';
 import { CLOUDFLARE_TUNNEL_APPS_HOSTNAMES_SCOPE_KEY, CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, } from './proxy-labels.js';
-import { runSubjectRelease } from './release-host.js';
+import { finishStageCopy, runSubjectRelease, } from './release-host.js';
 import { remoteDatabaseFactsFrom, remoteDatabaseKeys } from './remote-database.js';
+import { STAGE_COPY_LOCK_MS, claimStageCopyLock, parseStageCopyLock, stageCopyLockValue, } from './stage-copy-host.js';
 import { liveWorkerApps, workerAppTraceScopeKeys } from './worker-app.js';
 import { liveWorkers, workerTraceScopeKeys } from './worker.js';
 /** #441: the lease scope that serializes every mutation of one company, and the one for the shared platform. */
@@ -45,6 +47,8 @@ const companyScope = (orgId) => `company:${orgId}`;
 const PLATFORM_SCOPE = 'platform';
 /** A lease nobody renews: long enough for one apply, short enough that a dead worker's scope frees itself. The fence stops a slow worker that outlives it. */
 const DEFAULT_LEASE_TTL_MS = 30 * 60 * 1000;
+/** Whether any of the subjects has a release stepping. */
+const releaseRunning = (subjects, ids) => subjects.some((s) => recordedFrom(ids, s.id)?.release != null);
 /** #441: another apply, destroy, adopt or release holds the lease for this company or the platform. Nothing ran; try again when it finishes. */
 export class MutationInProgressError extends Error {
     scope;
@@ -195,6 +199,7 @@ export class FoundryPlanApply {
     onlySteps;
     now;
     leaseTtlMs;
+    copyLeaseRetry;
     appliedVersions;
     backupGate;
     platformDeps;
@@ -238,6 +243,7 @@ export class FoundryPlanApply {
         this.onlySteps = options.onlySteps;
         this.now = options.now ?? (() => new Date());
         this.leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+        this.copyLeaseRetry = options.copyLeaseRetry ?? { tries: 10, waitMs: 30_000 };
         this.appliedVersions = options.appliedVersions;
         this.backupGate = options.backupGate;
         this.platformDeps = options.platform;
@@ -1163,22 +1169,28 @@ export class FoundryPlanApply {
      * (the live ids of the run that holds the lease). A weight the runner changed reaches every server's balancer
      * before this returns.
      */
-    async runOrgReleases(org, context, fence) {
+    async runOrgReleases(org, context, fence, copies = 'defer') {
+        const out = { deferred: false, claimed: [] };
         const store = this.releaseStore;
         const primaryUuid = context.recordedIds()[PRIMARY_SERVER_SCOPE_KEY];
         if (!store || !this.executor.releaseHost || !primaryUuid)
-            return;
-        for (const subject of blueGreenSubjects(org, context.recordedIds())) {
+            return out;
+        const subjects = blueGreenSubjects(org, context.recordedIds());
+        // A copy waits while any subject of the org has a release running: the runner must stay free to roll back.
+        if (copies === 'claim' && releaseRunning(subjects, context.recordedIds()))
+            return out;
+        for (const subject of subjects) {
             // A built-in app's names reach its balancer only once the tunnel was last written with it: until then a
             // pinned check would answer from blue whatever color it names.
             if (subject.builtin &&
                 !(context.recordedIds()[CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY] ?? '').includes(`"service":"${lbOrigin(subject)}"`)) {
                 continue;
             }
+            await this.executor.syncStageGateMembers?.(org, subject, context);
             const host = this.executor.releaseHost(org, subject, context, () => this.renewLease(fence));
             if (!host)
                 continue;
-            await runSubjectRelease({
+            const result = await runSubjectRelease({
                 store,
                 scopeOwnerId: org.id,
                 subject,
@@ -1186,21 +1198,40 @@ export class FoundryPlanApply {
                 context,
                 now: this.now(),
                 primaryUuid,
+                ...(copies === 'defer' ? { deferCopies: true } : {}),
             });
+            out.deferred ||= result.deferredCopy;
+            if (copies === 'claim' && result.copy) {
+                // The copy's own lock is taken here, under the lease; the copy then runs without it.
+                const runId = randomUUID();
+                const claim = await claimStageCopyLock({
+                    subjectId: subject.id,
+                    context,
+                    requestId: result.copy.requestId,
+                    runId,
+                });
+                if (claim === 'claimed')
+                    out.claimed.push({ subject, job: { ...result.copy, runId } });
+            }
         }
+        return out;
     }
     /** One release run for platform-archon, on the platform's live ids; see {@link runOrgReleases}. */
-    async runPlatformReleases(platform, context, fence) {
+    async runPlatformReleases(platform, context, fence, copies = 'defer') {
+        const out = { deferred: false, claimed: [] };
         const store = this.releaseStore;
         const executor = this.platformDeps?.executor;
         const subject = archonSubject(platform, ARCHON_REPO);
         const primaryUuid = context.recordedIds()[PRIMARY_SERVER_SCOPE_KEY];
         if (!store || !executor?.releaseHost || !subject || !primaryUuid)
-            return;
+            return out;
+        if (copies === 'claim' && releaseRunning([subject], context.recordedIds()))
+            return out;
+        await executor.syncStageGateMembers?.(platform, subject, context);
         const host = executor.releaseHost(platform, subject, context, () => this.renewLease(fence));
         if (!host)
-            return;
-        await runSubjectRelease({
+            return out;
+        const result = await runSubjectRelease({
             store,
             scopeOwnerId: 'platform',
             subject,
@@ -1208,21 +1239,35 @@ export class FoundryPlanApply {
             context,
             now: this.now(),
             primaryUuid,
+            ...(copies === 'defer' ? { deferCopies: true } : {}),
         });
+        out.deferred = result.deferredCopy;
+        if (copies === 'claim' && result.copy) {
+            const runId = randomUUID();
+            const claim = await claimStageCopyLock({
+                subjectId: subject.id,
+                context,
+                requestId: result.copy.requestId,
+                runId,
+            });
+            if (claim === 'claimed')
+                out.claimed.push({ subject, job: { ...result.copy, runId } });
+        }
+        return out;
     }
-    async runPlatformReleaseTick() {
+    async runPlatformReleaseTick(copies) {
         const deps = this.platformDeps;
         const platform = await deps?.store.get();
         if (!deps || !platform)
-            return;
+            return { deferred: false, claimed: [] };
         const empty = { orgId: platform.ownerOrgId, steps: [], unmanaged: [] };
         if ((await this.authz.canApplyPlatform?.(this.actor)) !== true) {
             await this.refusePlatform(empty, platform.ownerOrgId, 'not authorized to run the release tick');
             throw new NotAuthorizedError(this.actor, platform.ownerOrgId);
         }
-        await this.withMutationLease(PLATFORM_SCOPE, (reason) => this.refusePlatform(empty, platform.ownerOrgId, reason), async (fence) => {
+        return this.withMutationLease(PLATFORM_SCOPE, (reason) => this.refusePlatform(empty, platform.ownerOrgId, reason), async (fence) => {
             const serviceIds = { ...(await deps.store.getServiceIds()) };
-            await this.runPlatformReleases(platform, {
+            return this.runPlatformReleases(platform, {
                 recordedIds: () => ({ ...serviceIds }),
                 recordScopeId: (key, value) => {
                     serviceIds[key] = value;
@@ -1231,7 +1276,7 @@ export class FoundryPlanApply {
                     delete serviceIds[key];
                 },
                 persist: () => deps.store.putServiceIds({ ...serviceIds }, fence),
-            }, fence);
+            }, fence, copies);
         });
     }
     /**
@@ -1243,29 +1288,216 @@ export class FoundryPlanApply {
      */
     async runReleaseTick() {
         const results = [];
+        const settle = (target, error) => {
+            const entry = {
+                target,
+                ...(error === undefined
+                    ? {}
+                    : { error: error instanceof Error ? error.message : String(error) }),
+            };
+            const at = results.findIndex((r) => r.target === target);
+            if (at === -1)
+                results.push(entry);
+            else
+                results[at] = entry;
+        };
+        // Phase 1: every org's and the platform's release, with stage copy requests left open. A copy takes up to
+        // ~45 minutes, so no copy runs before every other release of this tick has run.
+        const copying = [];
         for (const org of await this.store.list()) {
             if (!declaresBlueGreen(org))
                 continue;
             try {
-                await this.runOrgReleaseTick(org.id);
-                results.push({ target: org.id });
+                if ((await this.runOrgReleaseTick(org.id, 'defer')).deferred) {
+                    copying.push({ target: org.id, run: () => this.runOrgStageCopies(org.id) });
+                }
+                settle(org.id, undefined);
             }
             catch (e) {
-                results.push({ target: org.id, error: e instanceof Error ? e.message : String(e) });
+                settle(org.id, e);
             }
         }
         const platform = await this.platformDeps?.store.get();
         if (platform?.archon.enabled && platform.archon.blueGreen) {
             try {
-                await this.runPlatformReleaseTick();
-                results.push({ target: 'platform' });
+                if ((await this.runPlatformReleaseTick('defer')).deferred) {
+                    copying.push({ target: 'platform', run: () => this.runPlatformStageCopies() });
+                }
+                settle('platform', undefined);
+            }
+            catch (e) {
+                settle('platform', e);
+            }
+        }
+        // Phase 2: the copies, one subject at a time. A copy takes its lock under the org's lease and runs without it.
+        for (const { target, run } of copying) {
+            try {
+                await run();
+                settle(target, undefined);
             }
             catch (e) {
-                results.push({ target: 'platform', error: e instanceof Error ? e.message : String(e) });
+                settle(target, e);
             }
         }
         return results;
     }
+    /**
+     * Phase 2 for one org: takes the copy lock of each stage copy request under the org's lease, then runs the
+     * copies after the lease is released. While a copy runs, every other tick and apply for the org goes on, a
+     * hard-fail rollback included; the copy records through short leases ({@link copyContext}).
+     */
+    async runOrgStageCopies(id) {
+        const claimed = (await this.runOrgReleaseTick(id, 'claim')).claimed;
+        if (claimed.length === 0)
+            return;
+        const org = await this.store.get(id);
+        if (!org)
+            return;
+        const target = {
+            scope: companyScope(id),
+            refuse: (reason) => this.refuse({ orgId: id, steps: [], unmanaged: [] }, reason),
+            read: async () => {
+                const state = await this.store.getAppliedState(id);
+                if (!state)
+                    return null;
+                return {
+                    ids: { ...state.serviceIds },
+                    write: (ids, fence) => this.store.putAppliedState({ ...state, serviceIds: { ...ids } }, fence),
+                };
+            },
+            host: (subject, context, renew) => this.executor.releaseHost?.(org, subject, context, renew),
+        };
+        for (const copy of claimed)
+            await this.runClaimedCopy(target, copy);
+    }
+    /** Phase 2 for platform-archon; see {@link runOrgStageCopies}. */
+    async runPlatformStageCopies() {
+        const claimed = (await this.runPlatformReleaseTick('claim')).claimed;
+        if (claimed.length === 0)
+            return;
+        const deps = this.platformDeps;
+        const platform = await deps?.store.get();
+        if (!deps || !platform)
+            return;
+        const target = {
+            scope: PLATFORM_SCOPE,
+            refuse: (reason) => this.refusePlatform({ orgId: platform.ownerOrgId, steps: [], unmanaged: [] }, platform.ownerOrgId, reason),
+            read: async () => ({
+                ids: { ...(await deps.store.getServiceIds()) },
+                write: (ids, fence) => deps.store.putServiceIds({ ...ids }, fence),
+            }),
+            host: (subject, context, renew) => deps.executor.releaseHost?.(platform, subject, context, renew),
+        };
+        for (const copy of claimed)
+            await this.runClaimedCopy(target, copy);
+    }
+    /**
+     * Runs one claimed copy with no lease held, then records its outcome and consumes the request. A lost lock
+     * throws (`StaleLeaseError`) and leaves the request open.
+     */
+    async runClaimedCopy(target, claimed) {
+        const store = this.releaseStore;
+        const { subject, job } = claimed;
+        const first = await target.read();
+        if (!store || !first)
+            return;
+        const lockKey = releaseKeys(subject.id).stageCopyLock;
+        const context = this.copyContext(target, first.ids, lockKey, job.requestId, job.runId ?? '');
+        await finishStageCopy({
+            store,
+            host: target.host(subject, context, () => context.extendLock()),
+            subject,
+            context,
+            now: this.now(),
+            job,
+        });
+    }
+    /**
+     * The recorded ids a copy reads and writes, without the org's lease. It reads a snapshot taken when the lock was
+     * claimed; each `persist` takes the lease for a moment, re-reads the stored ids and writes only the keys the
+     * copy changed, so a tick that ran in between loses nothing. The lease may be busy: it waits and tries again.
+     */
+    copyContext(target, initial, lockKey, requestId, runId) {
+        const ids = { ...initial };
+        // When the lock this run holds lapses; a beat that cannot renew it by then fails the run as stale.
+        let released = false;
+        let lockExpiry = parseStageCopyLock(initial[lockKey]).expiry;
+        const dirty = new Map();
+        let queue = Promise.resolve();
+        const serial = (fn) => {
+            const run = queue.then(fn, fn);
+            queue = run.catch(() => undefined);
+            return run;
+        };
+        const write = async (changes, tries, mustHoldLock) => {
+            for (let attempt = 1;; attempt++) {
+                const lease = await this.store.acquireMutationLease(target.scope, randomUUID(), this.leaseTtlMs);
+                if ('token' in lease) {
+                    try {
+                        const stored = await target.read();
+                        if (!stored)
+                            throw new Error('stage copy: the recorded state is gone');
+                        // Another run's lock means this run lapsed and was replaced: write nothing.
+                        // No lock is fine only after this run removed it itself (its result, or its failure path).
+                        const heldBy = stored.ids[lockKey];
+                        if (heldBy ? parseStageCopyLock(heldBy).runId !== runId : mustHoldLock || !released) {
+                            throw new StaleLeaseError(target.scope);
+                        }
+                        for (const [key, value] of changes) {
+                            if (value === null)
+                                delete stored.ids[key];
+                            else
+                                stored.ids[key] = value;
+                        }
+                        await stored.write(stored.ids, lease);
+                        if (changes.get(lockKey) === null)
+                            released = true;
+                        return true;
+                    }
+                    finally {
+                        await this.store.releaseMutationLease(lease).catch(() => undefined);
+                    }
+                }
+                if (attempt >= tries) {
+                    if (tries === 1)
+                        return false;
+                    throw new MutationInProgressError(target.scope, lease.heldUntil);
+                }
+                await new Promise((resolve) => setTimeout(resolve, this.copyLeaseRetry.waitMs));
+            }
+        };
+        return {
+            recordedIds: () => ({ ...ids }),
+            recordScopeId: (key, value) => {
+                ids[key] = value;
+                dirty.set(key, value);
+            },
+            forgetId: (key) => {
+                delete ids[key];
+                dirty.set(key, null);
+            },
+            persist: () => serial(async () => {
+                const batch = new Map(dirty);
+                await write(batch, this.copyLeaseRetry.tries, false);
+                for (const [key, value] of batch)
+                    if (dirty.get(key) === value)
+                        dirty.delete(key);
+            }),
+            // Keeps the copy's lock alive. A lock another run took over throws. A busy lease is skipped while the lock
+            // still stands; once it would lapse, a beat that cannot renew it fails the run as stale.
+            extendLock: () => serial(async () => {
+                const expiry = Date.now() + STAGE_COPY_LOCK_MS;
+                const value = stageCopyLockValue(expiry, requestId, runId);
+                if (await write(new Map([[lockKey, value]]), 1, true)) {
+                    ids[lockKey] = value;
+                    lockExpiry = expiry;
+                }
+                else if (Date.now() >= lockExpiry) {
+                    throw new StaleLeaseError(target.scope);
+                }
+            }),
+        };
+    }
     /**
      * The recurring audit sealing run (foundry#929): seals every ledger registered by an `audit:ledger` step with the
      * platform signer and has the timestamp authority stamp the new checkpoints. Foundry has no scheduler, so the host
@@ -1297,19 +1529,23 @@ export class FoundryPlanApply {
             allowed: (org) => this.authz.canApply(this.actor, org.id),
         });
     }
-    async runOrgReleaseTick(id) {
+    /**
+     * One org's release run. `defer`: stage copy requests stay open and `deferred` says whether there were any.
+     * `claim`: the copies this run decided on, each with its lock taken, for {@link runClaimedCopy}.
+     */
+    async runOrgReleaseTick(id, copies) {
         const empty = { orgId: id, steps: [], unmanaged: [] };
         if (!(await this.authz.canApply(this.actor, id))) {
             await this.refuse(empty, 'not authorized to run the release tick');
             throw new NotAuthorizedError(this.actor, id);
         }
-        await this.withMutationLease(companyScope(id), (reason) => this.refuse(empty, reason), async (fence) => {
+        return this.withMutationLease(companyScope(id), (reason) => this.refuse(empty, reason), async (fence) => {
             const org = await this.store.get(id);
             const previous = await this.store.getAppliedState(id);
             if (!org || !previous)
-                return;
+                return { deferred: false, claimed: [] };
             const serviceIds = { ...previous.serviceIds };
-            await this.runOrgReleases(org, {
+            return this.runOrgReleases(org, {
                 recordedIds: () => ({ ...serviceIds }),
                 recordScopeId: (key, value) => {
                     serviceIds[key] = value;
@@ -1318,7 +1554,7 @@ export class FoundryPlanApply {
                     delete serviceIds[key];
                 },
                 persist: () => this.store.putAppliedState({ ...previous, serviceIds: { ...serviceIds } }, fence),
-            }, fence);
+            }, fence, copies);
         });
     }
     /** An own org with calls on: the host's answer about its slot's ports. A failure or a slow answer is "not open". */
@@ -1405,6 +1641,9 @@ export class FoundryPlanApply {
             bouleArchonCredential: this.executor.bouleArchonCredentialAvailable?.() ?? false,
             ...(blueGreenServers ? { blueGreenServers } : {}),
             ...(stageSinkDown ? { stageSinkDown } : {}),
+            ...(this.executor.stageGuardPorts
+                ? { stageGuardPorts: this.executor.stageGuardPorts() }
+                : {}),
             ...(blueGreenServers && org.hosting.entries.some((e) => e.blueGreen && e.database)
                 ? {
                     remoteDatabase: remoteDatabaseFactsFrom({
@@ -1783,12 +2022,16 @@ export class FoundryPlanApply {
         const archonBlueGreen = platform.archon.enabled && platform.archon.blueGreen && executor.archonBlueGreen
             ? await executor.archonBlueGreen().catch(() => ({ servers: undefined }))
             : null;
+        const archonGuards = archonBlueGreen
+            ? (executor.archonStageGuardNames?.(platform, serviceIds, owner) ?? [])
+            : [];
         const detail = computePlatformPlanDetail(platform, live, {
             owner,
             ...(archonBlueGreen
                 ? {
                     archonBlueGreen: {
                         servers: archonBlueGreen.servers,
+                        ...(archonGuards.length > 0 ? { guards: archonGuards } : {}),
                         ...('blocked' in archonBlueGreen && archonBlueGreen.blocked
                             ? { blocked: archonBlueGreen.blocked }
                             : {}),
@@ -1816,6 +2059,7 @@ export class FoundryPlanApply {
             signIn: ownerSignInFrom(owner, recorded),
             files: ownerFilesFrom(owner, recorded),
             chat: ownerChatFrom(owner, recorded),
+            emails: owner.owners.map((o) => o.email),
         };
     }
     /**
@@ -2270,6 +2514,11 @@ function destroyStepDescriptions(targets) {
 /** Scope keys of the Coolify apps blue/green made: `bg.<entry>.app.<server>.<part>`, a database sidecar, a connector on another server, the company's stage mail sink (`stage_sink_app`). */
 const BLUE_GREEN_APP_KEY = /^(bg\.[^.:]+\.app\.[^.:]+\.[a-z]+|bgdb\.[^.:]+\.sidecar\.[^.:]+|cloudflare_tunnel_connector_app\.[^.:]+|stage_sink_app)$/;
 const BLUE_GREEN_DATABASE_KEY = /^bg\.[^.:]+\.(stagedb|stagekept)$/;
+/** Stage's own sign-in: its broker entry (with the key) goes first, then its client. */
+const BLUE_GREEN_BROKER_KEY = /^bg\.[^.:]+\.stagebroker$/;
+const BLUE_GREEN_CLIENT_KEY = /^bg\.[^.:]+\.stageclient$/;
+/** Stage's own files and ai organisations and jobs project (`bg.<entry>.stage<service>org`), and the keys in them (`…keys`, revoked first). */
+const BLUE_GREEN_SERVICE_KEY = /^bg\.[^.:]+\.stage(files|ai|jobs)(org|keys)$/;
 /** Stage's Access gate (`bg.<entry>.stagegate`), and the database route's Cloudflare parts: its Access app, its service token (also one minted and never delivered) and its DNS record (recorded as the route). */
 const BLUE_GREEN_EDGE_KEYS = [
     [/^bgdb\.[^.:]+\.access$/, 'bg-access'],
@@ -2291,6 +2540,30 @@ function blueGreenDestroyTargets(serviceIds) {
         if (id)
             targets.push({ system: 'coolify', kind: 'bg-database', key, id });
     }
+    for (const key of keys.filter((k) => BLUE_GREEN_BROKER_KEY.test(k))) {
+        const id = serviceIds[key];
+        if (id)
+            targets.push({ system: 'coolify', kind: 'bg-broker', key, id });
+    }
+    for (const key of keys.filter((k) => BLUE_GREEN_CLIENT_KEY.test(k))) {
+        const id = serviceIds[key];
+        if (id)
+            targets.push({ system: 'zitadel', kind: 'bg-client', key, id });
+    }
+    for (const part of ['keys', 'org']) {
+        for (const key of keys) {
+            const match = BLUE_GREEN_SERVICE_KEY.exec(key);
+            const id = serviceIds[key];
+            if (!match || match[2] !== part || !id)
+                continue;
+            targets.push({
+                system: match[1],
+                kind: part === 'keys' ? 'bg-keys' : 'bg-org',
+                key,
+                id,
+            });
+        }
+    }
     for (const [pattern, kind] of BLUE_GREEN_EDGE_KEYS) {
         for (const key of keys.filter((k) => pattern.test(k))) {
             const id = serviceIds[key];

package/dist/plan/platform-diff.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
+import type { DeclaredOrg, EntryImage, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
 import { type Plan, type PlanNote, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import { type BlueGreenServer } from './blue-green.js';
@@ -725,6 +725,22 @@ export declare const DEFAULT_APP_SETTINGS: AppSettings;
 export declare function appSettingsAppliedScopeKey(entryKey: string): string;
 /** The settings the app has: the marker, or the defaults when there is none. */
 export declare function appliedAppSettings(recorded: Readonly<Record<string, string>>, entryKey: string): AppSettings;
+/**
+ * The image an entry's app last ran, as `repository@digest` (no secret). `planApp` plans the step again, with a
+ * redeploy, when the entry's `image` differs from it.
+ */
+export declare function appImageAppliedScopeKey(entryKey: string): string;
+/** An entry image as one pull reference. */
+export declare function entryImageRef(image: EntryImage): string;
+/**
+ * The two image fields Coolify accepts for an entry image. Its tag rule has no `@` or `:`, so the digest goes in
+ * the name as `<repository>@sha256` and the tag holds the bare 64 hex digits (Coolify pulls `<name>:<tag>`),
+ * the same way `coolifyImageFor` writes a pinned platform image.
+ */
+export declare function entryImageFields(image: EntryImage): {
+    docker_registry_image_name: string;
+    docker_registry_image_tag: string;
+};
 /**
  * The URLs `coolifyApp` last put in the entry's Coolify `domains`
  * (`tunnelDomainList`), as a JSON array (`[]` for an internal entry). `planApp`
@@ -1188,6 +1204,8 @@ export interface PlanPlatformOptions {
     archonBlueGreen?: {
         servers: readonly BlueGreenServer[] | undefined;
         blocked?: string;
+        /** The stage guards that can be made now ({@link stageGuardInputs}); they go into the applied hash. */
+        guards?: readonly string[];
     };
     /** Whether the host supplies a Coolify reader for the platform (default `true`). */
     jobsObservable?: boolean;
@@ -1255,6 +1273,8 @@ export interface PlanPlatformOptions {
         backupExecutorMissing?: boolean;
         /** #540: why `hc` is blocked, or absent when it is not. */
         hc?: string;
+        /** Why the image registry is blocked, or absent when it is not. */
+        registry?: string;
         /**
          * #540: true once `hc` is applied but the host built the platform
          * executor with no heartbeats dependencies -- the heartbeat-checks step
@@ -1377,6 +1397,8 @@ export interface PlanPlatformOptions {
         authApps?: boolean;
         edge?: boolean;
         files?: boolean;
+        /** A usable, reachable Coolify server has no registry login for the current host and passwords. */
+        registryLogins?: boolean;
         backupStorage?: boolean;
         backupStorageBlocked?: string;
     };