@wtfalch/foundry 0.16.16 → 0.17.0

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);
 }
@@ -323,6 +342,27 @@ export interface FoundryPlanApplyOptions {
     aiOrganisation?: 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`
@@ -379,10 +419,49 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly hostFiles;
     private readonly hostAi;
     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 +469,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 +501,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;