@wtfalch/foundry 0.16.16 → 0.17.1

package/dist/plan/index.d.ts

@@ -2,16 +2,20 @@ export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, File
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
+export type { StepSystem } from './step-system.js';
+export { stepSystemOf } from './step-system.js';
 export type { PlatformPlanDetail } from './platform-diff.js';
-export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_NAMES_KEY, PLATFORM_NAMES_KEY_REF, PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF, } from './platform-diff.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export type { PlatformOrgClientFactories } from './platform-org-ports.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export type { AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot } from './adopt.js';
+export { AdoptRefusedError } from './adopt.js';
 export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
-export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, PlatformNamesDeps, PlatformNamesRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';

package/dist/plan/index.js

@@ -1,8 +1,10 @@
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, } from './platform-diff.js';
+export { stepSystemOf } from './step-system.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_NAMES_KEY, PLATFORM_NAMES_KEY_REF, PLATFORM_NAMES_CLOUDFLARE_TOKEN_REF, } from './platform-diff.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export { AdoptRefusedError } from './adopt.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
 // #171: how a host signs files management requests with the delivered key.

package/dist/plan/live.d.ts

@@ -26,9 +26,11 @@ export interface LiveResource {
      * `platform-diff.ts`'s `planSfu` always plans its step when
      * `DeclaredPlatform.sfu.enabled` is true, rather than diffing against a
      * live resource the way every other system here does. It is still part of
-     * this union so `StepAction.system` (`diff.ts`) can name it.
+     * this union so `StepAction.system` (`diff.ts`) can name it. `'names'`
+     * (#317) is the same: a names key has no live lookup of its own, the same
+     * shape `ai`/`files` entry keys already follow.
      */
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu';
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'names';
     kind: string;
     key: string;
     config: Record<string, unknown>;
@@ -48,6 +50,11 @@ export interface ZitadelReader {
 }
 export interface CoolifyReader {
     listResources(orgId: OrgId): Promise<LiveResource[]>;
+    /**
+     * Reads one Coolify project by its uuid, for an org that records none yet
+     * (adopt, archon#271). Optional: without it nothing can be adopted.
+     */
+    listProject?(projectUuid: string): Promise<LiveResource[]>;
 }
 export interface CloudflareReader {
     listResources(orgId: OrgId): Promise<LiveResource[]>;

package/dist/plan/login-host.d.ts

@@ -21,8 +21,19 @@ import type { DeclaredOrg } from '../org.js';
  * `RESERVED_AUTH_AND_ENVIRONMENTS` already reserves the `auth` *slug* so no
  * org's own `<slug>.oikos.host` can collide with this subdomain, the same
  * way `AGORA_SUFFIX` reserves `-agora`.
+ *
+ * #488: `auth.<domain>` is refused when it would equal `platformAuthHostname`
+ * -- the platform's own org, declared with-domain on the platform's own
+ * domain, would otherwise compute the shared ZITADEL instance's own login
+ * host (`platform.auth.hostname`, e.g. `auth.companyincriminated.com` ->
+ * `auth.companyincluded.com`). Archon's login-host write throws on that
+ * duplicate host (`archon`'s `validateLoginHostRegistry`); if it were ever
+ * written instead, `auth`'s own `company-host.ts` denies every request
+ * through a duplicate host, the shared one included. `platformAuthHostname`
+ * is `null` when the caller has none to compare against (no platform
+ * declared, or sign-in not ready yet), in which case this never refuses.
  */
-export declare function loginHostnameFor(org: DeclaredOrg): string;
+export declare function loginHostnameFor(org: DeclaredOrg, platformAuthHostname?: string | null): string;
 /**
  * One entry in zitadel-login's own `LOGIN_HOST_BINDINGS`
  * (`auth/docs/company-login-hosts.md`) -- a single-line JSON document naming
@@ -66,7 +77,7 @@ export interface LoginHostBindingsPort {
  * on the next run.
  */
 export declare const LOGIN_BINDING_SCOPE_KEY = "login_host_binding";
-/** The org's recorded app client ids (hosted app, each entry's own, cms, agora), sorted. */
+/** The org's recorded app client ids (hosted app, each entry's own, cms, agora, boule), deduplicated and sorted. */
 export declare function loginHostClientIds(recorded: Readonly<Record<string, string>>): string[];
 /** The host plus its sorted client ids, as recorded under {@link LOGIN_BINDING_SCOPE_KEY}. */
 export declare function loginBindingState(host: string, clientIds: readonly string[]): string;

package/dist/plan/login-host.js

@@ -1,4 +1,5 @@
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, } from './agora.js';
+import { BOULE_CLIENT_ID_SCOPE_KEY } from './boule.js';
 /**
  * #267: what both the planner (`diff.ts`) and the executor (`executor.ts`)
  * need to agree on for an org's own company login host -- the hostname and
@@ -21,12 +22,30 @@ import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE
  * `RESERVED_AUTH_AND_ENVIRONMENTS` already reserves the `auth` *slug* so no
  * org's own `<slug>.oikos.host` can collide with this subdomain, the same
  * way `AGORA_SUFFIX` reserves `-agora`.
+ *
+ * #488: `auth.<domain>` is refused when it would equal `platformAuthHostname`
+ * -- the platform's own org, declared with-domain on the platform's own
+ * domain, would otherwise compute the shared ZITADEL instance's own login
+ * host (`platform.auth.hostname`, e.g. `auth.companyincriminated.com` ->
+ * `auth.companyincluded.com`). Archon's login-host write throws on that
+ * duplicate host (`archon`'s `validateLoginHostRegistry`); if it were ever
+ * written instead, `auth`'s own `company-host.ts` denies every request
+ * through a duplicate host, the shared one included. `platformAuthHostname`
+ * is `null` when the caller has none to compare against (no platform
+ * declared, or sign-in not ready yet), in which case this never refuses.
  */
-export function loginHostnameFor(org) {
+export function loginHostnameFor(org, platformAuthHostname = null) {
     // `issuer.usesDomain` is the issuer's opt-in into the org's domain
     // (`org.ts`'s `IssuerConfig`): a domain alone never moves it, so a domain
     // with `usesDomain` false stays on the tier 1 host.
-    return org.domain && org.issuer.usesDomain ? `auth.${org.domain}` : `${org.slug}-auth.oikos.host`;
+    if (org.domain && org.issuer.usesDomain) {
+        const host = `auth.${org.domain}`;
+        if (platformAuthHostname && host === platformAuthHostname) {
+            return `${org.slug}-auth.oikos.host`;
+        }
+        return host;
+    }
+    return `${org.slug}-auth.oikos.host`;
 }
 /**
  * Scope id holding what the binding was last written with
@@ -36,18 +55,18 @@ export function loginHostnameFor(org) {
  * on the next run.
  */
 export const LOGIN_BINDING_SCOPE_KEY = 'login_host_binding';
-/** The org's recorded app client ids (hosted app, each entry's own, cms, agora), sorted. */
+/** The org's recorded app client ids (hosted app, each entry's own, cms, agora, boule), deduplicated and sorted. */
 export function loginHostClientIds(recorded) {
-    return [
+    const ids = [
         recorded[APP_CLIENT_ID_SCOPE_KEY],
         recorded[CMS_CLIENT_ID_SCOPE_KEY],
         recorded[AGORA_CLIENT_ID_SCOPE_KEY],
+        recorded[BOULE_CLIENT_ID_SCOPE_KEY],
         ...Object.entries(recorded)
             .filter(([key]) => key.startsWith(ENTRY_CLIENT_ID_SCOPE_PREFIX))
             .map(([, id]) => id),
-    ]
-        .filter((id) => Boolean(id))
-        .sort();
+    ].filter((id) => Boolean(id));
+    return [...new Set(ids)].sort();
 }
 /** The host plus its sorted client ids, as recorded under {@link LOGIN_BINDING_SCOPE_KEY}. */
 export function loginBindingState(host, clientIds) {

package/dist/plan/plan-apply.d.ts

@@ -1,9 +1,11 @@
-import type { PlanApply } from '../apply.js';
+import type { DestroyProgress, PlanApply } from '../apply.js';
 import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, PlanStep } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
+import type { JobRunner } from '../runner/types.js';
 import type { AppliedState } from '../state.js';
-import type { AppliedVersionsStore, DeclaredOrgStore, PlatformStore } from '../store.js';
+import { type AppliedVersionsStore, type DeclaredOrgStore, type PlatformStore } from '../store.js';
+import { type AdoptCandidate, type AdoptInput, type AdoptPlan } from './adopt.js';
 import { type AgoraHostPort } from './agora.js';
 import { type StepAction } from './diff.js';
 import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
@@ -50,6 +52,16 @@ export interface AuditLog {
         target?: 'platform';
         at: Date;
     }): Promise<void>;
+    /** `FoundryPlanApply.adopt` and `release` (archon#271): no `Plan` is applied, so this is its own entry. `entryKey` names the hosting entry. */
+    recordAdoption(entry: {
+        actor: AuditActor;
+        orgId: OrgId;
+        action: 'adopt' | 'release';
+        entryKey: string;
+        outcome: 'adopted' | 'released' | 'refused';
+        reason?: string;
+        at: Date;
+    }): Promise<void>;
     /** `FoundryPlanApply.destroy`'s own record -- no `Plan` involved, so this is its own entry shape rather than a reuse of `recordApply`'s. */
     recordDestroy(entry: {
         actor: AuditActor;
@@ -249,6 +261,13 @@ export interface StepDestroyer {
         readonly recordedIds: Readonly<Record<string, string>>;
     }): Promise<void>;
 }
+/** #441: another apply, destroy, adopt or release holds the lease for this company or the platform. Nothing ran; try again when it finishes. */
+export declare class MutationInProgressError extends Error {
+    readonly scope: string;
+    readonly heldUntil: Date;
+    /** @param heldUntil when the holder's lease runs out if it is never released. */
+    constructor(scope: string, heldUntil: Date);
+}
 export declare class DeclaredOrgNotFoundError extends Error {
     constructor(orgId: OrgId);
 }
@@ -314,6 +333,12 @@ export interface FoundryPlanApplyOptions {
      * reported blocked instead of planned.
      */
     broker?: boolean;
+    /**
+     * #318: true when the host's executor was built with a `WorkersPort`.
+     * Optional, and false without it: each entry's `edge` Worker is then
+     * reported blocked instead of planned.
+     */
+    edgeWorkers?: boolean;
     /**
      * #177: true when the host's executor was built with its own `filesOrganisation`
      * / `aiOrganisation` port. Without one, the org step needs the platform's
@@ -321,8 +346,35 @@ export interface FoundryPlanApplyOptions {
      */
     filesOrganisation?: boolean;
     aiOrganisation?: boolean;
+    /**
+     * #317: true when the host's executor was built with a `NamesPort`.
+     * Optional, and false without it: each entry's `uses.names` step is then
+     * reported blocked instead of planned to fail.
+     */
+    names?: boolean;
     /** Overridable for tests; defaults to `() => new Date()`. */
     now?: () => Date;
+    /** #441: how long a mutation lease lasts before another caller may take it over. Defaults to 30 minutes. */
+    leaseTtlMs?: number;
+    /**
+     * #441 (part b): a durable, DB-row-backed record of `apply`, `destroy`,
+     * `adopt` and `release` for one org, held under the same mutation lease
+     * above rather than instead of it -- the lease is what actually keeps two
+     * holders from running `fn` at once (`withRunnerSerialization`'s own doc
+     * comment explains why the runner cannot safely take that job on its
+     * own). Optional, and a no-op without it -- every existing caller of this
+     * constructor is unaffected, and the lease alone still serializes every
+     * mutation the way it already did (#441, part a).
+     *
+     * What it adds: a row that never expires on a timer the way the lease
+     * does, so a crashed holder leaves something a host can see and query
+     * (`JobRunner.currentRun`/`getRun`) rather than nothing but a scope that
+     * quietly frees itself. Resuming after a crash reuses that row's id
+     * rather than starting a fresh one. Pass the same host-supplied
+     * `JobRunner` (`createJobRunner`, migrated with `runner/schema.ts`) that a
+     * host may also poll directly for progress.
+     */
+    runner?: JobRunner;
     /**
      * #253: appends a history row every time `runSteps` records a new
      * version as applied, beside the single-snapshot `store.putAppliedState`
@@ -376,13 +428,54 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly jobsScheduler;
     private readonly loginHostBindings;
     private readonly broker;
+    private readonly edgeWorkers;
     private readonly hostFiles;
     private readonly hostAi;
+    private readonly hostNames;
     private readonly now;
+    private readonly leaseTtlMs;
     private readonly appliedVersions;
     private readonly platformDeps;
+    private readonly runner;
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
+    /**
+     * Archon#271: what adopting a live app and database into entry
+     * `input.entryKey` would do. A read, like {@link plan}: it reads the project
+     * through the reader and changes nothing. A mismatch is reported in the
+     * result, with no steps. Needs the apply permission, since it reads a
+     * project the caller names.
+     */
+    planAdopt(id: OrgId, input: AdoptInput): Promise<AdoptPlan>;
+    /**
+     * Archon#271: the live apps and databases in `projectUuid` this org has not
+     * recorded, for Changes' "Live, not theirs". A read, but it needs the apply
+     * permission: it reads a project the caller names.
+     */
+    adoptCandidates(id: OrgId, entryKey: string, projectUuid?: string): Promise<AdoptCandidate[]>;
+    /**
+     * Archon#271: records an app and database that already run in Coolify as
+     * entry `input.entryKey`'s resources, so the next plan finds them and plans
+     * no create. Verifies first and refuses on a mismatch or an entry that is
+     * already applied or held by another org. Same permission as {@link apply}.
+     * It never calls an executor: nothing in Coolify changes. Nothing redeploys
+     * here, but the next normal plan may propose updates to the adopted app
+     * that do (see `adopt.ts`); show that plan before applying it. Two
+     * concurrent adopts of one resource are not locked against each other.
+     */
+    adopt(id: OrgId, input: AdoptInput): Promise<AppliedState>;
+    /**
+     * Archon#271: the undo of {@link adopt}. Drops the entry's recorded Coolify
+     * ids and its `adopted.<entryKey>` snapshot (and `coolify_project` when
+     * adopt recorded it and no other Coolify id remains). It leaves the
+     * declaration alone: the entry goes back to declared and not applied, so the
+     * next plan creates it, exactly as before adopt. The host then adopts it
+     * again or removes the entry from the declaration. Deletes and stops nothing
+     * in Coolify. Only an adopted entry can be released. Same permission as
+     * {@link apply}. Every path writes an audit row.
+     */
+    release(id: OrgId, entryKey: string): Promise<AppliedState>;
+    private computeAdopt;
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
     /**
      * After an org apply: gives the platform files runner a changed share-domain
@@ -390,9 +483,10 @@ export declare class FoundryPlanApply implements PlanApply {
      * declared orgs) without a platform pass. Touches only the share hosts and
      * redeploys the runner; the platform files step itself never runs here.
      * Skips quietly for an actor who may not apply the platform, and when the
-     * platform files step was never applied. There is no platform lock, so the
-     * service ids are re-read just before the write and only the share-domains
-     * key is recorded. A failure is rethrown naming that the org part succeeded.
+     * platform files step was never applied. It holds the platform lease for
+     * the refresh and fences its write with it; while another platform change
+     * holds the lease it skips (this class has no log), and the next platform
+     * apply does the refresh. Only the share-domains key is recorded. A failure is rethrown naming that the org part succeeded.
      */
     private refreshPlatformFilesShare;
     /**
@@ -421,7 +515,60 @@ export declare class FoundryPlanApply implements PlanApply {
      * declared org in place with whatever remains recorded in its applied
      * state, so a retried `destroy` only tears down what's left.
      */
-    destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
+    destroy(id: OrgId, confirmedOrgName: string, options?: {
+        onProgress?: (event: DestroyProgress) => void;
+    }): Promise<void>;
+    /** The steps `destroy` runs for `id`, in order. Refuses a non-test org like `destroy` does; writes no audit row since it changes nothing. */
+    planDestroy(id: OrgId): Promise<{
+        steps: string[];
+        kept: string[];
+    }>;
+    /**
+     * #441 (part b): records `fn`'s run in the durable runner, when one is
+     * configured, and calls it. Must run with the mutation lease already
+     * held -- every one of this method's four callers (`apply`, `destroy`,
+     * `adopt`, `release`) calls it from inside its own `withMutationLease`
+     * callback, never around it. The reason is `JobRunner.runSteps` itself:
+     * it checkpoints a run's one step (the literal id `'mutate'`, the same
+     * for all four callers so they share one row per org) by a plain read of
+     * the row followed by a later blind write, with nothing to stop two
+     * concurrent calls for the same `runId` from both reading "not yet
+     * checkpointed" and both calling `fn` -- the runner sequences and
+     * checkpoints (its own doc comment), it does not itself exclude a second
+     * caller the way the lease's atomic acquire does. Holding the lease first
+     * is what makes it safe to reuse an existing, not-yet-succeeded run
+     * ({@link JobRunner.currentRun}) rather than refuse it outright: by the
+     * time this method runs, this caller is already the lease's sole holder,
+     * so any row `currentRun` finds can only be a previous, now-abandoned
+     * attempt (the lease's own atomic acquire already refused a second live
+     * caller before either of them got here) -- reusing it is the resume #9
+     * calls "a human decides when to call it again", not a race.
+     *
+     * Two *first* attempts for the same org can still race the insert itself
+     * when neither has an existing row yet -- `JobRunner.enqueueApply`'s own
+     * unique constraint decides it at the database level, a real race rather
+     * than one decided by this process's await order, and the loser's
+     * {@link AlreadyRunningError} is refused and audited through `refuse`,
+     * the same as a lost lease. In practice this needs two lease holders at
+     * once to reach it, which the lease itself already prevents; it is this
+     * method's defence against a bug in the lease's own acquire path, not
+     * the primary lock.
+     *
+     * `fn`'s result is threaded out through a closure, since
+     * {@link RunnerStep.run} returns nothing.
+     */
+    private withRunnerSerialization;
+    /**
+     * #441: runs `fn` while holding the one mutation lease for `scope`, so two
+     * `FoundryPlanApply` instances on one store never run provider steps for the
+     * same company or platform at once. A second caller is refused with
+     * {@link MutationInProgressError}; `fn` gets the lease as the fence its
+     * store writes carry, so a worker that lost the lease cannot overwrite the
+     * newer holder's state. Both refusals are audited through `refuse`.
+     */
+    private withMutationLease;
+    /** #441: before each provider step, extends the lease; a holder that lost it stops here, before the step runs. */
+    private renewLease;
     private refuse;
     private refusePlatform;
     private refuseDestroy;