@wtfalch/foundry 0.16.15 → 0.17.0

package/dist/apply.d.ts

@@ -1,6 +1,14 @@
 import type { OrgId } from './org.js';
 import type { Plan } from './plan.js';
 import type { AppliedState } from './state.js';
+/** One destroy step starting, finishing or failing; `index` counts from 1 up to `total`. */
+export interface DestroyProgress {
+    step: string;
+    index: number;
+    total: number;
+    status: 'started' | 'finished' | 'failed';
+    error?: string;
+}
 /**
  * The plan/apply seam https://github.com/wtfalch/foundry/issues/19
  * implements.
@@ -37,5 +45,18 @@ export interface PlanApply {
      * declared org in place with whatever remains recorded, 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` will run, in order, for a test org (same refusal as
+     * `destroy`: any other org throws). Read-only. A stopped destroy's
+     * finished and failed steps are `AppliedState.destroy`. `steps` are exactly
+     * what `destroy` runs, in order; `kept` lists the adopted resources it
+     * leaves alone (archon#271). Refuses when an adopted record cannot be read.
+     */
+    planDestroy(id: OrgId): Promise<{
+        steps: string[];
+        kept: string[];
+    }>;
 }

package/dist/bootstrap/bootstrap.d.ts

@@ -1,4 +1,5 @@
-import type { PlatformLiveReaders, PlatformStepExecutor } from '../plan/index.js';
+import type { Plan } from '../plan.js';
+import type { PlatformLiveReaders, PlatformStepExecutor, StepSystem } from '../plan/index.js';
 import type { FoundryPlatformStepExecutorOptions } from '../plan/platform-providers.js';
 import type { FoundryStoreDb } from '../store/postgres.js';
 import type { BootstrapCompany, BootstrapOwner } from './declare.js';
@@ -29,6 +30,8 @@ export interface RootCredentials {
 /** What Archon's onboarding screen shows: one event per phase or round. */
 export interface BootstrapProgress {
     phase: 'declare' | 'plan' | 'apply' | 'done';
+    /** The system the event touches: the steps' own when a round's steps share one, `postgres` for a declare, `foundry` otherwise. */
+    system: StepSystem;
     round?: number;
     message: string;
     steps?: string[];
@@ -100,6 +103,8 @@ export declare class Redactor {
     addDeep(value: unknown, depth?: number, seen?: Set<unknown>): void;
     text(input: string): string;
 }
+/** The one system every step of `plan` touches, or `foundry` when they differ or there are none. */
+export declare function roundSystem(plan: Plan): StepSystem;
 /** Wraps the secret-carrying ports inside one step's deps so what they deliver or resolve is redacted. */
 export declare function guardStepDeps(executor: BootstrapExecutorDeps | undefined, redactor: Redactor, deliverSecret: (ref: string, secret: string) => Promise<void>, heldKeys: BootstrapPlatformDeps['heldKeys']): BootstrapExecutorDeps;
 /**

package/dist/bootstrap/bootstrap.js

@@ -61,6 +61,12 @@ const unusedOrgExecutor = {
         throw new Error('bootstrapPlatform never destroys an org');
     },
 };
+/** The one system every step of `plan` touches, or `foundry` when they differ or there are none. */
+export function roundSystem(plan) {
+    const systems = new Set(plan.steps.map((s) => s.system));
+    const [only] = systems;
+    return systems.size === 1 && only ? only : 'foundry';
+}
 const unusedOrgReader = { listResources: async () => [] };
 /** The audit log with every free-text field run through the redactor before it is stored. */
 function redactingAudit(inner, redactor) {
@@ -76,6 +82,10 @@ function redactingAudit(inner, redactor) {
             plan: plan(entry.plan),
             ...(entry.reason === undefined ? {} : { reason: redactor.text(entry.reason) }),
         }),
+        recordAdoption: (entry) => inner.recordAdoption({
+            ...entry,
+            ...(entry.reason === undefined ? {} : { reason: redactor.text(entry.reason) }),
+        }),
         recordDestroy: (entry) => inner.recordDestroy({
             ...entry,
             ...(entry.reason === undefined ? {} : { reason: redactor.text(entry.reason) }),
@@ -189,20 +199,29 @@ export async function bootstrapPlatform(input, deps) {
         const orgStore = createPostgresDeclaredOrgStore(deps.db);
         const platformStore = createPostgresPlatformStore(deps.db);
         if (await orgStore.get(COMPANY_INCLUDED_ORG_ID)) {
-            emit({ phase: 'declare', message: 'declared org already written' });
+            emit({ phase: 'declare', system: 'postgres', message: 'declared org already written' });
         }
         else {
             await orgStore.create(declaredCompanyOrg(input.company, input.owner));
-            emit({ phase: 'declare', message: `declared org "${input.company.name}" written` });
+            emit({
+                phase: 'declare',
+                system: 'postgres',
+                message: `declared org "${input.company.name}" written`,
+            });
         }
         const existing = await platformStore.get();
         if (existing) {
-            emit({ phase: 'declare', message: `declared platform already written for ${existing.apex}` });
+            emit({
+                phase: 'declare',
+                system: 'postgres',
+                message: `declared platform already written for ${existing.apex}`,
+            });
             // Only serverIpv4, through the validating `put`; no other field is touched.
             if (input.serverIpv4 && input.serverIpv4 !== existing.serverIpv4) {
                 await platformStore.put({ ...existing, serverIpv4: input.serverIpv4 });
                 emit({
                     phase: 'declare',
+                    system: 'postgres',
                     message: `declared platform serverIpv4 set to ${input.serverIpv4}`,
                 });
             }
@@ -211,6 +230,7 @@ export async function bootstrapPlatform(input, deps) {
             await platformStore.put(declaredPlatformFor(input.company.apex, input.serverIpv4));
             emit({
                 phase: 'declare',
+                system: 'postgres',
                 message: `declared platform written for ${input.company.apex}`,
             });
         }
@@ -278,12 +298,14 @@ export async function bootstrapPlatform(input, deps) {
             maxRounds: deps.maxRounds,
             onPlan: (round, plan) => emit({
                 phase: 'plan',
+                system: roundSystem(plan),
                 round,
                 message: `round ${round}: ${plan.steps.length} step(s) planned`,
                 steps: plan.steps.map((s) => s.description),
             }),
             onApplied: (round, plan) => emit({
                 phase: 'apply',
+                system: roundSystem(plan),
                 round,
                 message: `round ${round}: applied`,
                 steps: plan.steps.map((s) => s.description),
@@ -310,6 +332,7 @@ export async function bootstrapPlatform(input, deps) {
         };
         emit({
             phase: 'done',
+            system: 'foundry',
             message: driven.failed
                 ? `stopped: ${result.failed?.message}`
                 : `${result.applied.length} step(s) applied, ${blocked.length} blocked`,

package/dist/bootstrap/declare.d.ts

@@ -1,6 +1,16 @@
 import type { DeclaredOrg, OrgId, OwnerIdentity } from '../org.js';
 import type { DeclaredPlatform } from '../platform.js';
-/** Company Included's own org id, the same literal `test/fakes.ts`'s `basePlatform()` uses for `ownerOrgId`. */
+/**
+ * Company Included's own org id, the same literal `test/fakes.ts`'s
+ * `basePlatform()` uses for `ownerOrgId`. Must be a uuid: Archon's company
+ * pages resolve a declared org only by uuid (archon issue #40,
+ * `src/lib/companies/index.ts`'s `getCompany`/`isUuid`), so a non-uuid id
+ * 404s every one of them, Company Included's included (foundry#435).
+ * `migrations/0040_company_included_uuid.sql` rewrites the live row and
+ * every column that references it from the old literal
+ * `org_company_included` to this value; this constant and that migration's
+ * literal must agree.
+ */
 export declare const COMPANY_INCLUDED_ORG_ID: OrgId;
 export declare const DEFAULT_GIT_REF = "main";
 /**

package/dist/bootstrap/declare.js

@@ -1,8 +1,18 @@
 import { validateOwners } from '../org.js';
 import { PLATFORM_SERVICE_KEYS, defaultPlatformHostname } from '../platform.js';
 import { VERSIONS } from './versions.js';
-/** Company Included's own org id, the same literal `test/fakes.ts`'s `basePlatform()` uses for `ownerOrgId`. */
-export const COMPANY_INCLUDED_ORG_ID = 'org_company_included';
+/**
+ * Company Included's own org id, the same literal `test/fakes.ts`'s
+ * `basePlatform()` uses for `ownerOrgId`. Must be a uuid: Archon's company
+ * pages resolve a declared org only by uuid (archon issue #40,
+ * `src/lib/companies/index.ts`'s `getCompany`/`isUuid`), so a non-uuid id
+ * 404s every one of them, Company Included's included (foundry#435).
+ * `migrations/0040_company_included_uuid.sql` rewrites the live row and
+ * every column that references it from the old literal
+ * `org_company_included` to this value; this constant and that migration's
+ * literal must agree.
+ */
+export const COMPANY_INCLUDED_ORG_ID = 'e4d20889-a63d-42b6-b670-2bdd4472449b';
 export const DEFAULT_GIT_REF = 'main';
 /**
  * The Stalwart image tag the platform's mail step runs. `platform.mail.gitRef`

package/dist/index.d.ts

@@ -2,19 +2,24 @@ export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig
 export { APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, appEntry, ownerMailboxes, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateSite, } from './org.js';
 export type { DeclaredPlatform, PlatformService, PlatformServiceKey } from './platform.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
+import { type PinnedVersions } from './bootstrap/versions.js';
+export type { PinnedVersions };
+export declare const PINNED_VERSIONS: Readonly<PinnedVersions>;
 export type { RequestableField, CallsChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
-export type { Checkpoint, LastApplied, AppliedState } from './state.js';
+export type { Checkpoint, LastApplied, AppliedState, DestroyRecord, DestroyStepRecord, } from './state.js';
 export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
-export type { AppliedVersion, AppliedVersionsStore, DeclaredOrgStore, PlatformStore, RequestedChangeStore, StaleUpdate, UpdateOptions, } from './store.js';
-export type { PlanApply } from './apply.js';
+export type { AppliedVersion, AppliedVersionsStore, DeclaredOrgStore, HeldLease, MutationLease, PlatformStore, RequestedChangeStore, StaleUpdate, UpdateOptions, } from './store.js';
+export { StaleLeaseError } from './store.js';
+export type { PlanApply, DestroyProgress } from './apply.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
-export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, PlanDetail, PlatformPlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, PlatformPlanDetail, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
+export { AdoptRefusedError } from './plan/index.js';
 export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, 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_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';

package/dist/index.js

@@ -1,10 +1,17 @@
 export { APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, appEntry, ownerMailboxes, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateSite, } from './org.js';
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
+// archon#273: the pinned platform service versions the planner deploys, so a
+// host can show declared against running. Readonly: it is the planner's own
+// object, not a copy.
+import { VERSIONS } from './bootstrap/versions.js';
+export const PINNED_VERSIONS = VERSIONS;
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
+export { StaleLeaseError } from './store.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
+export { AdoptRefusedError } from './plan/index.js';
 export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, 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_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';

package/dist/migrations/0038_calls_version_pin.sql

@@ -0,0 +1,8 @@
+-- @wtfalch/foundry: #259 -- per-org calls Matrix version pin, holding an
+-- org's Synapse/MAS release during an ordered rollout. Null holds no pin:
+-- the stack follows versions.json, same as every org today. Mirrors
+-- src/store/schema.ts's `declaredOrgs` table additions.
+
+alter table foundry_declared_orgs
+  add column if not exists calls_version_pin_synapse text,
+  add column if not exists calls_version_pin_mas text;

package/dist/migrations/0039_destroy_record.sql

@@ -0,0 +1,7 @@
+-- @wtfalch/foundry: which steps of a destroy have finished, and which failed.
+-- Sits beside `0002_applied_state.sql`'s `checkpoints` (an apply's finished
+-- steps) and is read the same way, from the org's applied state. `DestroyRecord`
+-- in `state.ts`. Null until a destroy has started; a destroy that finishes
+-- deletes the org and this row with it.
+
+alter table foundry_applied_state add column if not exists destroy jsonb;

package/dist/migrations/0040_company_included_uuid.sql

@@ -0,0 +1,72 @@
+-- @wtfalch/foundry: Company Included's declared org id was minted by hand as
+-- the literal 'org_company_included' rather than a uuid (bootstrap/declare.ts).
+-- Archon resolves a declared org only by uuid (archon issue #40, `isUuid` in
+-- `src/lib/companies/index.ts`'s `getCompany`), so every company page for our
+-- own company 404s (foundry#435). This rewrites the live row, and every
+-- column across this package's own tables that carries that same literal, to
+-- the uuid `declare.ts`'s `COMPANY_INCLUDED_ORG_ID` now exports. The two
+-- literals below must agree with that constant.
+--
+-- Idempotent: every statement is a no-op once the row has already moved,
+-- because each WHERE clause only ever matches the old literal. Safe for a
+-- still-running old release during the rolling deploy: nothing outside this
+-- package's own one-time `bootstrapPlatform` idempotency check
+-- (`bootstrap.ts`'s `orgStore.get(COMPANY_INCLUDED_ORG_ID)`) reads this id as
+-- a hardcoded literal rather than from the declared platform row it is
+-- already running against (`plan/platform-providers.ts`'s
+-- `context.platform.ownerOrgId`), and Company Included's platform is already
+-- bootstrapped -- that check has nothing left to do either way.
+--
+-- `foundry_applied_state` and `foundry_requested_changes` both carry a
+-- foreign key to `foundry_declared_orgs (id)` with no `ON UPDATE CASCADE`,
+-- so the primary key cannot move while they still point at the old value.
+-- Each is dropped and re-added around the rewrite rather than made
+-- permanently cascading, which would let a future bug silently rename an
+-- org's rows out from under its history instead of failing loudly.
+-- (`foundry_adoptions` is gone -- 0032 dropped it -- so it needs no such
+-- treatment here.)
+
+alter table foundry_applied_state drop constraint if exists foundry_applied_state_org_fkey;
+alter table foundry_requested_changes drop constraint if exists foundry_requested_changes_org_fkey;
+
+update foundry_declared_orgs
+   set id = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where id = 'org_company_included';
+
+update foundry_applied_state
+   set org_id = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where org_id = 'org_company_included';
+
+update foundry_requested_changes
+   set org_id = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where org_id = 'org_company_included';
+
+update foundry_runs
+   set org_id = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where org_id = 'org_company_included';
+
+update foundry_audit_events
+   set org_id = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where org_id = 'org_company_included';
+
+update foundry_declared_platform
+   set owner_org_id = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where owner_org_id = 'org_company_included';
+
+update foundry_applied_versions
+   set service = 'e4d20889-a63d-42b6-b670-2bdd4472449b'
+ where service = 'org_company_included';
+
+do $$
+begin
+  if not exists (select 1 from pg_constraint where conname = 'foundry_applied_state_org_fkey') then
+    alter table foundry_applied_state
+      add constraint foundry_applied_state_org_fkey foreign key (org_id)
+      references foundry_declared_orgs (id);
+  end if;
+  if not exists (select 1 from pg_constraint where conname = 'foundry_requested_changes_org_fkey') then
+    alter table foundry_requested_changes
+      add constraint foundry_requested_changes_org_fkey foreign key (org_id)
+      references foundry_declared_orgs (id);
+  end if;
+end $$;

package/dist/migrations/0041_company_included_uuid_keys.sql

@@ -0,0 +1,132 @@
+-- @wtfalch/foundry: migration 0040 moved Company Included's declared org id
+-- from the literal 'org_company_included' to the uuid
+-- 'e4d20889-a63d-42b6-b670-2bdd4472449b' in every org_id (and org_id-shaped)
+-- column, but never looked inside a jsonb value. A hosting step's key is
+-- `<orgId>:<entryKey>` (platform-diff.ts's `appStepKey`), recorded as
+-- `foundry_applied_state.service_ids`'s own keys
+-- (`coolify:app:<orgId>:<entryKey>`, `cloudflare:access:<orgId>:<entryKey>`)
+-- and as `foundry_runs.step_ids` array entries of the identical shape. After
+-- 0040, the planner looks for `coolify:app:e4d20889-...:<entry>`, finds
+-- nothing under the still-literal key, and can plan to create Company
+-- Included's Coolify apps a second time (#452).
+--
+-- `foundry_runs.checkpoints` carries the same step strings
+-- (`runner/runner.ts`'s `Checkpoint.step`) and is compared by exact string
+-- against `step_ids` to decide what a resumed run has already done
+-- (`done.has(stepId)`); rewriting `step_ids` alone would make an
+-- already-completed step look undone and run it again. `failure.step` names
+-- which step actually failed, same shape. `foundry_applied_state.checkpoints`
+-- and `.destroy` (`state.ts`'s `Checkpoint`/`DestroyRecord`) carry the same
+-- step strings too, as history rather than anything matched against, but are
+-- rewritten the same way so nothing here still reads as Company Included's
+-- old id.
+--
+-- Every WHERE clause below matches only a key, array element or `step` field
+-- that still contains the old literal, so a second run is a no-op.
+
+update foundry_applied_state
+   set service_ids = (
+         select coalesce(
+                  jsonb_object_agg(
+                    replace(key, 'org_company_included', 'e4d20889-a63d-42b6-b670-2bdd4472449b'),
+                    value
+                  ),
+                  '{}'::jsonb
+                )
+           from jsonb_each(service_ids)
+       )
+ where exists (
+         select 1 from jsonb_object_keys(service_ids) k
+          where k like '%org_company_included%'
+       );
+
+update foundry_applied_state
+   set checkpoints = (
+         select coalesce(
+                  jsonb_agg(
+                    case
+                      when (c ->> 'step') like '%org_company_included%'
+                      then jsonb_set(c, '{step}',
+                             to_jsonb(replace(c ->> 'step', 'org_company_included',
+                                               'e4d20889-a63d-42b6-b670-2bdd4472449b')))
+                      else c
+                    end
+                  ),
+                  '[]'::jsonb
+                )
+           from jsonb_array_elements(checkpoints) as c
+       )
+ where exists (
+         select 1 from jsonb_array_elements(checkpoints) c
+          where (c ->> 'step') like '%org_company_included%'
+       );
+
+update foundry_applied_state
+   set destroy = jsonb_set(
+         destroy,
+         '{steps}',
+         (select coalesce(
+                   jsonb_agg(
+                     case
+                       when (s ->> 'step') like '%org_company_included%'
+                       then jsonb_set(s, '{step}',
+                              to_jsonb(replace(s ->> 'step', 'org_company_included',
+                                                'e4d20889-a63d-42b6-b670-2bdd4472449b')))
+                       else s
+                     end
+                   ),
+                   '[]'::jsonb
+                 )
+            from jsonb_array_elements(destroy -> 'steps') as s)
+       )
+ where destroy is not null
+   and exists (
+         select 1 from jsonb_array_elements(destroy -> 'steps') s
+          where (s ->> 'step') like '%org_company_included%'
+       );
+
+update foundry_runs
+   set step_ids = (
+         select coalesce(
+                  jsonb_agg(
+                    replace(elem, 'org_company_included', 'e4d20889-a63d-42b6-b670-2bdd4472449b')
+                  ),
+                  '[]'::jsonb
+                )
+           from jsonb_array_elements_text(step_ids) as elem
+       )
+ where exists (
+         select 1 from jsonb_array_elements_text(step_ids) e
+          where e like '%org_company_included%'
+       );
+
+update foundry_runs
+   set checkpoints = (
+         select coalesce(
+                  jsonb_agg(
+                    case
+                      when (c ->> 'step') like '%org_company_included%'
+                      then jsonb_set(c, '{step}',
+                             to_jsonb(replace(c ->> 'step', 'org_company_included',
+                                               'e4d20889-a63d-42b6-b670-2bdd4472449b')))
+                      else c
+                    end
+                  ),
+                  '[]'::jsonb
+                )
+           from jsonb_array_elements(checkpoints) as c
+       )
+ where exists (
+         select 1 from jsonb_array_elements(checkpoints) c
+          where (c ->> 'step') like '%org_company_included%'
+       );
+
+update foundry_runs
+   set failure = jsonb_set(
+         failure,
+         '{step}',
+         to_jsonb(replace(failure ->> 'step', 'org_company_included',
+                           'e4d20889-a63d-42b6-b670-2bdd4472449b'))
+       )
+ where failure is not null
+   and (failure ->> 'step') like '%org_company_included%';

package/dist/migrations/0042_mutation_leases.sql

@@ -0,0 +1,12 @@
+-- @wtfalch/foundry: the lock behind `FoundryPlanApply`'s apply, destroy, adopt
+-- and release (#441). One row per scope: `company:<orgId>` or `platform`.
+-- `token` is the fencing token; a row is never deleted, so it only rises, and
+-- a stale holder's `putAppliedState` / `putServiceIds` is refused by
+-- comparing against it. A released lease has `expires_at` set to now.
+
+create table if not exists foundry_mutation_leases (
+  scope text primary key,
+  token bigint not null,
+  holder text not null,
+  expires_at timestamptz not null
+);

package/dist/org.d.ts

@@ -129,6 +129,27 @@ export interface ChatConfig {
 export interface CallsConfig {
     enabled: boolean;
     usesDomain: boolean;
+    /**
+     * #259: holds this org's calls Matrix stack on an older Synapse/MAS
+     * release during an ordered rollout, instead of whatever
+     * `versions.json` currently pins. `null`/absent follows the pinned
+     * release, same as today.
+     *
+     * Declared and validated here; not yet read anywhere a tag is actually
+     * applied. `executor.ts`'s `coolifyCalls` only ever sets Synapse's/MAS's
+     * image tag at creation (its own comment: "#251: only on create --
+     * nothing here patches `docker_registry_image_tag` on an app
+     * `findOrCreateCallsApp` found already running") -- there is no patch-
+     * and-redeploy path for an existing org's stack yet, pinned or not. A
+     * rollout mechanism needs that path before this field can hold anything
+     * back; building it is outside this change (#259's own "Human steps"
+     * raises a related open question about Coolify's auto-deploy that bears
+     * on the same path).
+     */
+    versionPin?: {
+        synapse?: string;
+        mas?: string;
+    } | null;
 }
 /**
  * The issuer's per-service opt-in into the org's `domain` fact.
@@ -157,6 +178,17 @@ export interface IssuerConfig {
 export interface SiteConfig {
     enabled: boolean;
     usesDomain: boolean;
+    /**
+     * The org's own skin repo for `plan/executor.ts`'s `cmsSite` site app
+     * (#245) -- `null` (the default) builds the shared `@wtfalch/cms` repo's
+     * `apps/site`, same sample skin as before this field existed. Only the
+     * repo the site app builds from; the cms admin app behind it always
+     * builds from the shared repo. Where the skin finally lives (an
+     * org-owned repo vs. a cms theme document served at runtime) is still
+     * undecided in https://github.com/wtfalch/cms/issues/55 -- this field and
+     * its default are the only part built until that closes.
+     */
+    repo?: string | null;
 }
 /**
  * A ZITADEL OIDC application kind foundry can provision inside an org's
@@ -333,8 +365,10 @@ export declare const AI_ENTRY_ENV_NAMES: readonly ["AI_URL", "AI_ORGANISATION_ID
  * env and one collection per name in `collections`. A name is uppercase
  * `[A-Z0-9_]`; its id is delivered as `FILES_COLLECTION_<NAME>_ID`.
  * `permissions` is a subset of {@link FILES_ENTRY_PERMISSIONS}, which is also
- * the default. `shareHost` asks for `share.<domain>`; it is reported blocked
- * until the platform files host serves that name.
+ * the default. `shareHost` asks for `share.<domain>`: foundry routes and
+ * publishes that name through the org's tunnel, delivers `FILES_SHARE_ORIGIN`
+ * and passes it to files. The platform files runner must still serve the
+ * host (a Coolify domain and `FILES_PUBLIC_HOSTS`); the plan warns of that.
  */
 export interface EntryFiles {
     collections: string[];
@@ -356,8 +390,18 @@ export interface HostingEntryUses {
  * looks like a secret. `{ from }` names a value the plan already mints.
  */
 export type EnvValue = string | {
-    from: AppEnvSource;
-};
+    from: Exclude<AppEnvSource, 'sharedSecret'>;
+} | EnvSharedSecret;
+/**
+ * A secret foundry generates once and holds under an org-scoped ref. Every
+ * entry of the same org that names the same `name` gets the same value; an
+ * entry of another org never does. It is written to the entry's env only, and
+ * never reaches a plan, a log or an error.
+ */
+export interface EnvSharedSecret {
+    from: 'sharedSecret';
+    name: string;
+}
 /** The org's `app` entry: today's one app. */
 export declare function appEntry(hosting: HostingConfig): HostingEntry | undefined;
 /**
@@ -367,8 +411,19 @@ export declare function appEntry(hosting: HostingConfig): HostingEntry | undefin
  * sends from. Each is read from `StepExecutionContext.recordedIds()` in
  * `executor.ts`'s `pushAppEnv`, never minted again there.
  */
-export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain';
+export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain' | 'sharedSecret' | 'platformMailKey';
+/**
+ * Two sources are secrets. `sharedSecret` is {@link EnvSharedSecret}.
+ * `platformMailKey` is the platform's held Lettermint key, handed over as the
+ * value of the declared env name (the platform's own apps call it
+ * `LETTERMINT_API_TOKEN`). Any hosting entry of any customer org may name it
+ * (William, 2026-10-04): mail is Lettermint, and the key is the platform's.
+ */
 export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
+/** The sources whose value is a secret: resolved at apply time, never recorded. */
+export declare const SECRET_APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
+/** The held-key ref of an org's shared secret. */
+export declare const sharedSecretRef: (orgId: string, name: string) => string;
 /**
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
  * shape as `validateBuyerIdentity` below.
@@ -405,8 +460,19 @@ export declare function validateDomain(domain: string): string | null;
  * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
  *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
  *   `zitadel:app:cms` key, and the two would overwrite each other.
+ * - `site.repo`, if set, must be a repo under `wtfalch` (#245), the same
+ *   `REPO` rule {@link validateHostingEntry} already holds `HostingEntry.repo`
+ *   to.
  */
 export declare function validateSite(org: DeclaredOrg): string | null;
+/**
+ * #259: `calls.versionPin` holds this org's calls Matrix stack on an older
+ * release during an ordered rollout. A pin is a tag, held to the same
+ * "no floating tag" rule the pinned releases in `versions.json` already
+ * follow ({@link floatingTagBlocked}) -- a pin that floats would defeat the
+ * reason to pin at all.
+ */
+export declare function validateCalls(org: DeclaredOrg): string | null;
 /**
  * Per-org SSO. Decided to exist in #14 ("Also in scope") and its resolved
  * research #3 ("per-org SSO code exists unused"); nothing about its
@@ -590,9 +656,20 @@ export declare function ownerMailboxRecorded(box: OwnerMailbox, recordedIds: Rea
  * two rules `validateHosting` already applies to `issuerApps`' names, for
  * the same reason: a duplicate or blank entry can never mean anything
  * different from leaving it out.
+ *
+ * A domain plus `mail.mode === 'received'` is tier 2 (own domain, MX stays
+ * at Google or Microsoft), which William dropped on 2026-10-04 (#422):
+ * only tier 1 (no domain) and tier 3 (own domain, `hosted`) are offered.
+ * Refused unless `opts.allowExistingTier2` says this exact combination was
+ * already the stored state before this write -- `store/postgres.ts`'s
+ * `update` passes that for an org already grandfathered into tier 2, so a
+ * patch that does not touch `domain` or `mail.mode` still goes through.
+ * `create` never passes it: a brand new org cannot already be grandfathered.
  */
 export declare function validateMail(org: Pick<DeclaredOrg, 'mail' | 'domain'> & {
     owners?: readonly OwnerIdentity[];
+}, opts?: {
+    allowExistingTier2?: boolean;
 }): string | null;
 /**
  * The form an app foundry does not own takes. Decided in #7's `#15`