@wtfalch/foundry 0.70.1 → 0.72.0

package/dist/plan/zitadel-login-policy.js

@@ -29,7 +29,22 @@ const SECOND_FACTOR_SETTINGS = {
     passwordlessType: 'PASSWORDLESS_TYPE_ALLOWED',
     mfaInitSkipLifetime: '0s',
 };
+/**
+ * What {@link ZitadelPort.setCustomersLoginPolicy} sets: a superset of what any customer app needs, so one
+ * policy serves every app of the customers org. `allowRegister` is not here: `customers.signUp` owns it.
+ */
+const CUSTOMERS_POLICY_SETTINGS = {
+    forceMfa: false,
+    allowExternalIdp: false,
+    allowUsernamePassword: true,
+    passwordlessType: 'PASSWORDLESS_TYPE_ALLOWED',
+};
 const SECOND_FACTORS = ['SECOND_FACTOR_TYPE_OTP', 'SECOND_FACTOR_TYPE_U2F'];
+/**
+ * The customers policy also keeps the emailed code as a second factor, and never removes it: the email-code
+ * session check may need it. The login app narrows the factors it offers an app.
+ */
+const CUSTOMERS_SECOND_FACTORS = [...SECOND_FACTORS, 'SECOND_FACTOR_TYPE_OTP_EMAIL'];
 const MULTI_FACTORS = ['MULTI_FACTOR_TYPE_U2F_WITH_VERIFICATION'];
 /** ZITADEL leaves false booleans and zero durations out of a read. */
 const isZeroDuration = (value) => value === undefined || (typeof value === 'string' && /^0+(\.0+)?s$/.test(value));
@@ -90,56 +105,67 @@ export function createZitadelLoginPolicy(options) {
         }
         return settings;
     };
+    /**
+     * Makes the org's login policy hold `want` and exactly these factor lists, writing nothing when it already
+     * does. Any setting not in `want` is copied back as it is. An org on the instance default gets its own
+     * policy (POST); a custom one is changed by PUT, then by adding the missing factors before removing the
+     * extra ones, so the org is never left with no second factor it needs.
+     */
+    async function conform(orgId, want, wantSecond, wantMulti) {
+        const data = await call('GET', orgId, undefined);
+        const policy = data.policy ?? {};
+        const isDefault = data.isDefault === true || policy.isDefault === true;
+        const secondFactors = stringList(policy.secondFactors);
+        const multiFactors = stringList(policy.multiFactors);
+        const settingsDiffer = Object.entries(want).some(([key, value]) => typeof value === 'boolean'
+            ? (policy[key] === true) !== value
+            : value === '0s'
+                ? !isZeroDuration(policy[key])
+                : policy[key] !== value);
+        const factorsDiffer = !sameSet(secondFactors, wantSecond) || !sameSet(multiFactors, wantMulti);
+        if (!isDefault && !settingsDiffer && !factorsDiffer)
+            return { changed: false };
+        const settings = { ...settingsOf(policy), ...want };
+        if (isDefault) {
+            // The org's own policy, written whole: the factor lists go in the same body.
+            await call('POST', orgId, {
+                ...settings,
+                secondFactors: wantSecond,
+                multiFactors: wantMulti,
+                idps: (policy.idps ?? []).map((idp) => ({
+                    idpId: idp.idpId,
+                    ownerType: 'IDP_OWNER_TYPE_SYSTEM',
+                })),
+            });
+            return { changed: true };
+        }
+        if (settingsDiffer)
+            await call('PUT', orgId, settings);
+        const factorPath = '/management/v1/policies/login';
+        for (const type of wantSecond.filter((t) => !secondFactors.includes(t))) {
+            await call('POST', orgId, { type }, `${factorPath}/second_factors`);
+        }
+        for (const type of wantMulti.filter((t) => !multiFactors.includes(t))) {
+            await call('POST', orgId, { type }, `${factorPath}/multi_factors`);
+        }
+        for (const type of secondFactors.filter((t) => !wantSecond.includes(t))) {
+            await call('DELETE', orgId, undefined, `${factorPath}/second_factors/${encodeURIComponent(type)}`);
+        }
+        for (const type of multiFactors.filter((t) => !wantMulti.includes(t))) {
+            await call('DELETE', orgId, undefined, `${factorPath}/multi_factors/${encodeURIComponent(type)}`);
+        }
+        return { changed: true };
+    }
     return {
         async enforceSecondFactor(orgId) {
             if (!orgId)
                 throw new Error('enforceSecondFactor: orgId is required');
-            const data = await call('GET', orgId, undefined);
-            const policy = data.policy ?? {};
-            const isDefault = data.isDefault === true || policy.isDefault === true;
-            const secondFactors = stringList(policy.secondFactors);
-            const multiFactors = stringList(policy.multiFactors);
-            const want = SECOND_FACTOR_SETTINGS;
-            const settingsDiffer = (policy.forceMfa === true) !== want.forceMfa ||
-                (policy.allowRegister === true) !== want.allowRegister ||
-                (policy.allowExternalIdp === true) !== want.allowExternalIdp ||
-                (policy.allowUsernamePassword === true) !== want.allowUsernamePassword ||
-                policy.passwordlessType !== want.passwordlessType ||
-                !isZeroDuration(policy.mfaInitSkipLifetime);
-            const factorsDiffer = !sameSet(secondFactors, SECOND_FACTORS) || !sameSet(multiFactors, MULTI_FACTORS);
-            if (!isDefault && !settingsDiffer && !factorsDiffer)
-                return { changed: false };
-            const settings = { ...settingsOf(policy), ...want };
-            if (isDefault) {
-                // The org's own policy, written whole: the factor lists go in the same body.
-                await call('POST', orgId, {
-                    ...settings,
-                    secondFactors: SECOND_FACTORS,
-                    multiFactors: MULTI_FACTORS,
-                    idps: (policy.idps ?? []).map((idp) => ({
-                        idpId: idp.idpId,
-                        ownerType: 'IDP_OWNER_TYPE_SYSTEM',
-                    })),
-                });
-                return { changed: true };
-            }
-            if (settingsDiffer)
-                await call('PUT', orgId, settings);
-            // Add before remove, so the org is never left with no second factor.
-            const factorPath = '/management/v1/policies/login';
-            for (const type of SECOND_FACTORS.filter((t) => !secondFactors.includes(t))) {
-                await call('POST', orgId, { type }, `${factorPath}/second_factors`);
-            }
-            for (const type of MULTI_FACTORS.filter((t) => !multiFactors.includes(t))) {
-                await call('POST', orgId, { type }, `${factorPath}/multi_factors`);
-            }
-            for (const type of secondFactors.filter((t) => !SECOND_FACTORS.includes(t))) {
-                await call('DELETE', orgId, undefined, `${factorPath}/second_factors/${encodeURIComponent(type)}`);
-            }
-            for (const type of multiFactors.filter((t) => !MULTI_FACTORS.includes(t))) {
-                await call('DELETE', orgId, undefined, `${factorPath}/multi_factors/${encodeURIComponent(type)}`);
-            }
-            return { changed: true };
+            return conform(orgId, SECOND_FACTOR_SETTINGS, SECOND_FACTORS, MULTI_FACTORS);
+        },
+        async setCustomersLoginPolicy(orgId) {
+            if (!orgId)
+                throw new Error('setCustomersLoginPolicy: orgId is required');
+            return conform(orgId, CUSTOMERS_POLICY_SETTINGS, CUSTOMERS_SECOND_FACTORS, MULTI_FACTORS);
         },
         async closeSelfRegistration(orgId) {
             if (!orgId)

package/dist/plan/zitadel-machine-user.d.ts

@@ -78,6 +78,13 @@ export declare class ZitadelLoginClientRoleConflictError extends Error {
 }
 /** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
 export declare const ORG_DIRECTORY_READER_ROLE = "ORG_OWNER_VIEWER";
+/**
+ * Boule removes a customer with this credential (boule#495). ZITADEL's narrowest built-in organisation role
+ * that holds `user.delete` is `ORG_USER_MANAGER`; it cannot be cut down to delete alone (it also lets the
+ * holder change users in that organisation). It is granted in the customers organisation only, never in the
+ * company's.
+ */
+export declare const ORG_DIRECTORY_USER_MANAGER_ROLE = "ORG_USER_MANAGER";
 /**
  * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
  * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
@@ -88,6 +95,12 @@ export declare class ZitadelDirectoryRoleConflictError extends Error {
     readonly roles: readonly string[];
     constructor(userId: string, roles: readonly string[]);
 }
+/**
+ * The organisation role of the broker's registrar user in each organisation it serves: it may make
+ * projects there, and a project it makes it owns. No member, user or login-policy rights, which
+ * `ORG_OWNER` would add.
+ */
+export declare const REGISTRAR_ROLE = "ORG_PROJECT_CREATOR";
 export interface ZitadelMinterOptions {
     /** The new instance's base URL, e.g. `https://auth.companyincluded.com`. */
     url: string;
@@ -96,4 +109,4 @@ export interface ZitadelMinterOptions {
     fetchImpl?: typeof fetch;
     instanceHost?: string;
 }
-export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'mintOrgDirectoryReader' | 'revokeOrgDirectoryReader'>;
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'mintOrgDirectoryReader' | 'revokeOrgDirectoryReader' | 'ensureOrgDirectoryRoles' | 'ensureRegistrarUser' | 'mintRegistrarToken'>;

package/dist/plan/zitadel-machine-user.js

@@ -86,6 +86,14 @@ export class ZitadelLoginClientRoleConflictError extends Error {
 }
 /** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
 export const ORG_DIRECTORY_READER_ROLE = 'ORG_OWNER_VIEWER';
+/**
+ * Boule removes a customer with this credential (boule#495). ZITADEL's narrowest built-in organisation role
+ * that holds `user.delete` is `ORG_USER_MANAGER`; it cannot be cut down to delete alone (it also lets the
+ * holder change users in that organisation). It is granted in the customers organisation only, never in the
+ * company's.
+ */
+export const ORG_DIRECTORY_USER_MANAGER_ROLE = 'ORG_USER_MANAGER';
+const ORG_DIRECTORY_ROLES = [ORG_DIRECTORY_READER_ROLE, ORG_DIRECTORY_USER_MANAGER_ROLE];
 /**
  * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
  * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
@@ -95,12 +103,20 @@ export class ZitadelDirectoryRoleConflictError extends Error {
     userId;
     roles;
     constructor(userId, roles) {
-        super(`ZITADEL machine user ${userId} already exists with organisation role(s) [${roles.join(', ') || 'none'}], not only [${ORG_DIRECTORY_READER_ROLE}] -- refusing to reuse it as a directory reader`);
+        super(`ZITADEL machine user ${userId} already exists with organisation role(s) [${roles.join(', ') || 'none'}], not only [${ORG_DIRECTORY_ROLES.join(', ')}] -- refusing to reuse it as a directory reader`);
         this.userId = userId;
         this.roles = roles;
         this.name = 'ZitadelDirectoryRoleConflictError';
     }
 }
+/** Each call to ZITADEL gives up after this long. */
+const CALL_TIMEOUT_MS = 30_000;
+/**
+ * The organisation role of the broker's registrar user in each organisation it serves: it may make
+ * projects there, and a project it makes it owns. No member, user or login-policy rights, which
+ * `ORG_OWNER` would add.
+ */
+export const REGISTRAR_ROLE = 'ORG_PROJECT_CREATOR';
 export function createZitadelAdminMinter(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     async function call(method, path, body, orgId) {
@@ -119,6 +135,7 @@ export function createZitadelAdminMinter(options) {
                 ...(orgId ? { 'x-zitadel-orgid': orgId } : {}),
             },
             body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
         });
         const text = await response.text();
         let data = {};
@@ -306,21 +323,12 @@ export function createZitadelAdminMinter(options) {
         if (!userId)
             throw new Error('ZITADEL did not return the machine user id');
         if (existing) {
-            const members = await call('POST', '/management/v1/orgs/me/members/_search', { queries: [{ userIdQuery: { userId } }] }, orgId);
-            const roles = (members.result ?? [])
-                .filter((m) => m.userId === userId)
-                .flatMap((m) => m.roles ?? []);
-            if (roles.some((role) => role !== ORG_DIRECTORY_READER_ROLE)) {
+            const roles = await memberRoles(orgId, userId);
+            if (roles.some((role) => !ORG_DIRECTORY_ROLES.includes(role))) {
                 throw new ZitadelDirectoryRoleConflictError(userId, roles);
             }
         }
-        try {
-            await call('POST', '/management/v1/orgs/me/members', { userId, roles: [ORG_DIRECTORY_READER_ROLE] }, orgId);
-        }
-        catch (e) {
-            if (!(e instanceof ZitadelHttpError && e.status === 409))
-                throw e;
-        }
+        await ensureOrgDirectoryRoles(orgId, userId);
         await revokeAllPats(orgId, userId);
         const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, orgId);
         const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
@@ -329,6 +337,78 @@ export function createZitadelAdminMinter(options) {
         }
         return { userId, token: pat.token, patId };
     }
+    /**
+     * The broker's registrar user: a machine user of its own in `orgIds[0]` (found by `userName`, else made)
+     * holding {@link REGISTRAR_ROLE} in every org of `orgIds`, each grant added only when the org does not
+     * have it yet (a 409 is the same). Mints no token, so it is safe to repeat whenever an org joins the
+     * list. Calls follow ZITADEL's published v1 management API and have not been run against a live
+     * instance.
+     */
+    async function ensureRegistrarUser(orgIds, input) {
+        const home = orgIds[0];
+        if (!home)
+            throw new Error('the registrar user needs at least one organisation');
+        const found = await call('POST', '/management/v1/users/_search', {
+            queries: [
+                { userNameQuery: { userName: input.userName, method: 'TEXT_QUERY_METHOD_EQUALS' } },
+            ],
+        }, home);
+        let userId = found.result?.[0]?.id;
+        if (!userId) {
+            const created = await call('POST', '/management/v1/users/machine', {
+                userName: input.userName,
+                name: input.name,
+                accessTokenType: 'ACCESS_TOKEN_TYPE_BEARER',
+            }, home);
+            userId = typeof created.userId === 'string' ? created.userId : undefined;
+        }
+        if (!userId)
+            throw new Error('ZITADEL did not return the machine user id');
+        for (const orgId of new Set(orgIds)) {
+            try {
+                await call('POST', '/management/v1/orgs/me/members', { userId, roles: [REGISTRAR_ROLE] }, orgId);
+            }
+            catch (e) {
+                if (!(e instanceof ZitadelHttpError && e.status === 409))
+                    throw e;
+            }
+        }
+        return { userId };
+    }
+    /** A fresh token for the registrar user; every token it holds is revoked first, so one stays live. */
+    async function mintRegistrarToken(homeOrgId, userId) {
+        await revokeAllPats(homeOrgId, userId);
+        const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, homeOrgId);
+        const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
+        if (typeof pat.token !== 'string' || pat.token === '' || !patId) {
+            throw new Error(`ZITADEL returned no token for machine user ${userId}`);
+        }
+        return { token: pat.token, patId };
+    }
+    /**
+     * The directory user's roles in one organisation: {@link ORG_DIRECTORY_ROLES}, set whether it is a member
+     * yet or not (a 409 on the add means it is, and the roles are then replaced with a `PUT`). Calls follow
+     * ZITADEL's published v1 management API and have not been run against a live instance.
+     */
+    async function ensureOrgDirectoryRoles(orgId, userId) {
+        try {
+            await call('POST', '/management/v1/orgs/me/members', { userId, roles: ORG_DIRECTORY_ROLES }, orgId);
+        }
+        catch (e) {
+            if (!(e instanceof ZitadelHttpError && e.status === 409))
+                throw e;
+            // The PUT replaces every role, so the roles a person added stay: ours join the existing set.
+            const existing = await memberRoles(orgId, userId);
+            await call('PUT', `/management/v1/orgs/me/members/${userId}`, { roles: [...existing, ...ORG_DIRECTORY_ROLES.filter((r) => !existing.includes(r))] }, orgId);
+        }
+    }
+    /** The organisation roles one user holds in an organisation. */
+    async function memberRoles(orgId, userId) {
+        const members = await call('POST', '/management/v1/orgs/me/members/_search', { queries: [{ userIdQuery: { userId } }] }, orgId);
+        return (members.result ?? [])
+            .filter((m) => m.userId === userId)
+            .flatMap((m) => m.roles ?? []);
+    }
     /** Deletes every PAT of a user; a PAT already gone (404) is the outcome wanted. */
     async function revokeAllPats(orgId, userId) {
         for (const patId of await listPats(orgId, userId)) {
@@ -342,7 +422,10 @@ export function createZitadelAdminMinter(options) {
         }
     }
     return {
+        ensureRegistrarUser,
+        mintRegistrarToken,
         mintOrgDirectoryReader,
+        ensureOrgDirectoryRoles,
         revokeOrgDirectoryReader: revokeAllPats,
         mintAdminMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_OWNER').then(({ userId, token }) => ({ userId, token })),
         mintLoginClientMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_LOGIN_CLIENT'),

package/dist/platform.d.ts

@@ -20,6 +20,9 @@ export interface PlatformArchonService extends PlatformService {
     blueGreen?: {
         steps?: number[];
         stepHoldMinutes?: number;
+        advance?: 'time' | 'signal' | 'approval';
+        /** Archon's switch only: `{ steps: [100], staffFirst: true }` deploys the idle copy and waits for `open`. */
+        staffFirst?: boolean;
     };
 }
 /**

package/dist/release/fanout.d.ts

@@ -0,0 +1,77 @@
+import { type ReleaseStore } from './state.js';
+/** The built-in apps Company Included releases from Archon and then copies to every customer org. */
+export type FanOutApp = 'boule' | 'agora';
+export type FanOutOrgState = 'waiting' | 'deploying' | 'done' | 'failed';
+/** C1: what Archon shows for one app's fan-out. */
+export interface BuiltinFanOut {
+    digest: string | null;
+    done: boolean;
+    orgs: Array<{
+        orgId: string;
+        slug: string;
+        state: FanOutOrgState;
+        at: string | null;
+        reason: string | null;
+    }>;
+}
+/** Applied-state scope keys of one app's fan-out (on the owner org). */
+export declare function fanOutKeys(app: FanOutApp): {
+    /** The commit being copied. */
+    digest: string;
+    /** The commit whose copy finished on every org. */
+    done: string;
+    orgPrefix: string;
+    /** `<state>|<ISO time>|<org id>|<fixed reason>` */
+    org: (slug: string) => string;
+};
+/** C1: where the fan-out of the owner's Boule or Agora stands, from the owner org's applied state. */
+export declare function readBuiltinFanOut(store: Pick<ReleaseStore, 'getScopeIds'>, ownerOrgId: string, app: FanOutApp): Promise<BuiltinFanOut>;
+/**
+ * The commit the owner's copy runs when it is fully live: one colour at 100 %, the other at 0, no release
+ * running and no open step window. Null otherwise.
+ */
+export declare function fullyLiveDigest(ids: Readonly<Record<string, string>>, app: FanOutApp): string | null;
+export type FanOutDeployResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface FanOutDeps {
+    ownerOrgId: string;
+    app: FanOutApp;
+    /** Whether the owner's `org.<app>.blueGreen` is declared. */
+    ownerDeclares: boolean;
+    store: Pick<ReleaseStore, 'openRequests' | 'consumeRequests' | 'appendEvents'>;
+    /** The owner org's recorded ids now. */
+    readIds(): Promise<Record<string, string>>;
+    /** Persists scope keys on the owner org (null removes one), under a short lease. */
+    write(writes: Record<string, string | null>): Promise<void>;
+    /** Every other org that has the built-in app, in any order. Never the owner. */
+    targets(): Promise<Array<{
+        orgId: string;
+        slug: string;
+    }>>;
+    /** Puts the org's copy on `sha` in place and waits for the deployment. Fixed-text reasons only. */
+    deploy(target: {
+        orgId: string;
+        slug: string;
+    }, sha: string): Promise<FanOutDeployResult>;
+    now: () => Date;
+    /** Each deploy is abandoned after this long (default 12 minutes). */
+    deployTimeoutMs?: number;
+}
+export declare const FANOUT_DEPLOY_TIMEOUT_MS: number;
+export interface FanOutRun {
+    /** Why nothing deployed, or `deployed`, `done`, `stopped`. Fixed text. */
+    outcome: string;
+    deployed: string[];
+    failed: string | null;
+}
+/**
+ * One fan-out pass for one app (release tick, after the owner's release ran). Deploys each other org's copy at
+ * the owner's live commit, in slug order, and stops at the first failure. Every org is deployed in this pass
+ * unless one fails; a pass that dies halfway leaves the finished orgs `done` and the interrupted one `deploying`,
+ * which the next pass deploys again (a deploy of the same commit is safe to repeat).
+ */
+export declare function runBuiltinFanOut(deps: FanOutDeps): Promise<FanOutRun>;

package/dist/release/fanout.js

@@ -0,0 +1,177 @@
+import { recordedFrom } from './state.js';
+const COMMIT = /^[0-9a-f]{40}$/;
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const STATES = ['waiting', 'deploying', 'done', 'failed'];
+/** Applied-state scope keys of one app's fan-out (on the owner org). */
+export function fanOutKeys(app) {
+    const p = `fanout.${app}`;
+    return {
+        /** The commit being copied. */
+        digest: `${p}.digest`,
+        /** The commit whose copy finished on every org. */
+        done: `${p}.done`,
+        orgPrefix: `${p}.org.`,
+        /** `<state>|<ISO time>|<org id>|<fixed reason>` */
+        org: (slug) => `${p}.org.${slug}`,
+    };
+}
+function assertApp(app) {
+    if (app !== 'boule' && app !== 'agora')
+        throw new Error('invalid fan-out app');
+}
+function parseOrg(ids, key, slug) {
+    if (!SLUG.test(slug))
+        return null;
+    const [state, at, orgId, ...rest] = (ids[key] ?? '').split('|');
+    if (!state || !STATES.includes(state) || !orgId)
+        return null;
+    return {
+        orgId,
+        slug,
+        state: state,
+        at: at || null,
+        reason: rest.join('|') || null,
+    };
+}
+function readFrom(ids, app) {
+    const k = fanOutKeys(app);
+    const orgs = Object.keys(ids)
+        .filter((key) => key.startsWith(k.orgPrefix))
+        .map((key) => parseOrg(ids, key, key.slice(k.orgPrefix.length)))
+        .filter((o) => o !== null)
+        .sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+    const digest = ids[k.digest] ?? null;
+    return { digest, done: digest !== null && ids[k.done] === digest, orgs };
+}
+/** C1: where the fan-out of the owner's Boule or Agora stands, from the owner org's applied state. */
+export async function readBuiltinFanOut(store, ownerOrgId, app) {
+    assertApp(app);
+    return readFrom(await store.getScopeIds(ownerOrgId), app);
+}
+/**
+ * The commit the owner's copy runs when it is fully live: one colour at 100 %, the other at 0, no release
+ * running and no open step window. Null otherwise.
+ */
+export function fullyLiveDigest(ids, app) {
+    const r = recordedFrom({ ...ids }, app);
+    if (!r || r.release !== null)
+        return null;
+    const other = r.live === 'blue' ? 'green' : 'blue';
+    if (r.weights[r.live] !== 100 || r.weights[other] !== 0)
+        return null;
+    if (!['idle', 'passed', 'rolled_back'].includes(r.window.kind))
+        return null;
+    const digest = r.digests[r.live];
+    return digest && COMMIT.test(digest) ? digest : null;
+}
+export const FANOUT_DEPLOY_TIMEOUT_MS = 12 * 60_000;
+async function bounded(run, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ ok: false, reason: 'deployment timed out' }), ms);
+    });
+    try {
+        return await Promise.race([run, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * One fan-out pass for one app (release tick, after the owner's release ran). Deploys each other org's copy at
+ * the owner's live commit, in slug order, and stops at the first failure. Every org is deployed in this pass
+ * unless one fails; a pass that dies halfway leaves the finished orgs `done` and the interrupted one `deploying`,
+ * which the next pass deploys again (a deploy of the same commit is safe to repeat).
+ */
+export async function runBuiltinFanOut(deps) {
+    const { app } = deps;
+    assertApp(app);
+    const k = fanOutKeys(app);
+    const none = (outcome) => ({ outcome, deployed: [], failed: null });
+    const retries = (await deps.store.openRequests({ orgId: deps.ownerOrgId, entryKey: app })).filter((r) => r.action.kind === 'fanout_retry');
+    if (retries.length > 0) {
+        const failedNow = readFrom(await deps.readIds(), app).orgs.filter((o) => o.state === 'failed');
+        const writes = {};
+        for (const o of failedNow)
+            writes[k.org(o.slug)] = `waiting|${deps.now().toISOString()}|${o.orgId}|`;
+        if (Object.keys(writes).length > 0)
+            await deps.write(writes);
+        await deps.store.consumeRequests(retries.map((r) => r.id));
+    }
+    if (!deps.ownerDeclares)
+        return none('owner has no blue/green copy');
+    const ids = await deps.readIds();
+    const digest = fullyLiveDigest(ids, app);
+    if (!digest)
+        return none('owner copy is not fully live on one commit');
+    if (ids[k.done] === digest)
+        return none('commit already copied');
+    const targets = [...(await deps.targets())]
+        .filter((t) => t.orgId !== deps.ownerOrgId && SLUG.test(t.slug))
+        .sort((a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
+    const stamp = deps.now().toISOString();
+    const current = readFrom(ids, app);
+    const fresh = current.digest !== digest;
+    const sync = {};
+    if (fresh) {
+        sync[k.digest] = digest;
+        sync[k.done] = null;
+    }
+    const states = new Map(current.orgs.map((o) => [o.slug, o]));
+    for (const o of current.orgs) {
+        if (!targets.some((t) => t.slug === o.slug))
+            sync[k.org(o.slug)] = null;
+    }
+    for (const t of targets) {
+        const have = states.get(t.slug);
+        if (fresh || !have || have.orgId !== t.orgId) {
+            sync[k.org(t.slug)] = `waiting|${stamp}|${t.orgId}|`;
+            states.set(t.slug, { ...t, state: 'waiting', at: stamp, reason: null });
+        }
+    }
+    if (Object.keys(sync).length > 0)
+        await deps.write(sync);
+    const run = { outcome: 'done', deployed: [], failed: null };
+    for (const t of targets) {
+        const state = states.get(t.slug)?.state;
+        if (state === 'done')
+            continue;
+        if (state === 'failed')
+            return { ...run, outcome: 'stopped', failed: t.slug };
+        await deps.write({ [k.org(t.slug)]: `deploying|${deps.now().toISOString()}|${t.orgId}|` });
+        let result;
+        try {
+            result = await bounded(deps.deploy(t, digest), deps.deployTimeoutMs ?? FANOUT_DEPLOY_TIMEOUT_MS);
+        }
+        catch (error) {
+            console.error(`fanout ${app}: deploy threw ${error instanceof Error ? error.name : 'Error'}`);
+            result = { ok: false, reason: 'deployment failed' };
+        }
+        const at = deps.now().toISOString();
+        if (result.ok) {
+            await deps.write({ [k.org(t.slug)]: `done|${at}|${t.orgId}|` });
+            run.deployed.push(t.slug);
+            await record(deps, { at, kind: 'fanout_done', reason: t.slug });
+            continue;
+        }
+        const reason = result.reason.replace(/\|/g, ' ').slice(0, 120);
+        await deps.write({ [k.org(t.slug)]: `failed|${at}|${t.orgId}|${reason}` });
+        await record(deps, { at, kind: 'fanout_failed', reason: `${t.slug}: ${reason}` });
+        return { ...run, outcome: 'stopped', failed: t.slug };
+    }
+    await deps.write({ [k.done]: digest });
+    return run;
+}
+async function record(deps, event) {
+    try {
+        await deps.store.appendEvents({
+            orgId: deps.ownerOrgId,
+            entryKey: deps.app,
+            events: [event],
+        });
+    }
+    catch {
+        // The history is a record, not a gate: the state above already says what happened.
+        console.error(`fanout ${deps.app}: recording a history line failed`);
+    }
+}

package/dist/release/run.js

@@ -28,7 +28,8 @@ export async function runRelease(input) {
         };
     }
     const k = releaseKeys(entryKey);
-    const all = await store.openRequests({ orgId, entryKey });
+    // `fanout_retry` belongs to the built-in fan-out (`fanout.ts`), which consumes it; this run leaves it open.
+    const all = (await store.openRequests({ orgId, entryKey })).filter((r) => r.action.kind !== 'fanout_retry');
     // A stage request whose result was persisted before a crash is consumed, never run a second time.
     const handledId = ids[k.stageCopyHandled];
     const replayed = all.filter((r) => isStageCopyAction(r.action) && String(r.id) === handledId);

package/dist/release/state.d.ts

@@ -66,7 +66,7 @@ export declare function releaseKeys(entry: string): {
 };
 export declare function formatWeights(w: Record<Color, number>): string;
 export declare function parseWeights(value: string | undefined): Record<Color, number> | null;
-export declare const RELEASE_EVENT_KINDS: readonly ["promote", "step", "check", "pause", "resume", "step_now", "approve", "open", "rollback", "passed", "hard_fail"];
+export declare const RELEASE_EVENT_KINDS: readonly ["promote", "step", "check", "pause", "resume", "step_now", "approve", "open", "rollback", "passed", "hard_fail", "fanout_done", "fanout_failed"];
 /** What `foundry_release_events.payload` holds: a line's fields besides `at` and `kind`. */
 export declare const releaseEventPayload: z.ZodObject<{
     percent: z.ZodOptional<z.ZodNumber>;
@@ -100,6 +100,8 @@ export declare const releaseEventKind: z.ZodEnum<{
     resume: "resume";
     step_now: "step_now";
     approve: "approve";
+    fanout_done: "fanout_done";
+    fanout_failed: "fanout_failed";
 }>;
 /** The window JSON is the C2 state plus the active release's `release` field. */
 export declare function parseWindow(value: string | undefined): {

package/dist/release/state.js

@@ -78,6 +78,8 @@ export const RELEASE_EVENT_KINDS = [
     'rollback',
     'passed',
     'hard_fail',
+    'fanout_done',
+    'fanout_failed',
 ];
 /** What `foundry_release_events.payload` holds: a line's fields besides `at` and `kind`. */
 export const releaseEventPayload = z.object({
@@ -216,6 +218,7 @@ const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('deploy_stage'), ref: z.string().regex(STAGE_REF_PATTERN) }),
     z.object({ kind: z.literal('copy_prod_to_stage') }),
     z.object({ kind: z.literal('undo_stage_copy') }),
+    z.object({ kind: z.literal('fanout_retry') }),
 ]);
 /** C2: ask the runner to apply an action on its next run. Archon audits it. */
 export async function requestReleaseAction(store, input) {

package/dist/release/types.d.ts

@@ -107,8 +107,16 @@ export type ReleaseAction = {
     kind: 'copy_prod_to_stage';
 } | {
     kind: 'undo_stage_copy';
+}
+/** Owner org, entry key `boule` or `agora`: continue the built-in fan-out from the org that failed. */
+ | {
+    kind: 'fanout_retry';
 };
-export type ReleaseEventKind = 'promote' | 'step' | 'check' | 'pause' | 'resume' | 'step_now' | 'approve' | 'open' | 'rollback' | 'passed' | 'hard_fail';
+export type ReleaseEventKind = 'promote' | 'step' | 'check' | 'pause' | 'resume' | 'step_now' | 'approve' | 'open' | 'rollback' | 'passed' | 'hard_fail'
+/** The built-in fan-out put an org's copy on the live commit (`reason` is the org slug). */
+ | 'fanout_done'
+/** The built-in fan-out stopped at an org (`reason` is `<slug>: <fixed text>`). */
+ | 'fanout_failed';
 /** C1: one line of a release's history, written by the release run (`foundry_release_events`). */
 export interface ReleaseEvent {
     at: string;