@wtfalch/foundry 0.70.0 → 0.71.0

package/dist/plan/usage-tail-worker.js

@@ -0,0 +1,105 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { usageTailArtifactUrl } from '../platform.js';
+import { PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY, PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY, PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY, PLATFORM_USAGE_TAIL_KEY, PLATFORM_USAGE_TAIL_KEY_REF, PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY, PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY, PLATFORM_USAGE_TAIL_SCRIPT_NAME, } from './platform-diff.js';
+/** The date Cloudflare's Workers runtime compatibility is pinned to; no Workers feature here needs a later one. */
+const USAGE_TAIL_COMPATIBILITY_DATE = '2026-10-01';
+/**
+ * foundry#1024: makes the usage tail Worker true. Upload the pinned edge
+ * release (the host fetches and verifies it) and record the script at once,
+ * so a later failure is a half-made Worker foundry owns. Then hold the key
+ * (minted once, its guard recorded as soon as its value is held) and set it
+ * on the Worker. The applied values are recorded only when all of it
+ * succeeded.
+ */
+export async function provisionPlatformUsageTail(context, deps) {
+    const { platform } = context;
+    const { usageTail } = platform;
+    const recorded = context.recordedIds();
+    const edgeUrl = recorded[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY];
+    if (!edgeUrl) {
+        throw new Error(`platform:usage-tail: edge has not been applied yet (no recorded ${PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY}); the Worker is uploaded through it`);
+    }
+    const workers = await deps.workers(edgeUrl);
+    if (!usageTail.enabled) {
+        // Whatever of a (possibly half-made) deploy exists is removed; what does not exist is tolerated.
+        await workers.deleteScript(PLATFORM_USAGE_TAIL_SCRIPT_NAME);
+        await deps.deliverSecret(PLATFORM_USAGE_TAIL_KEY_REF, '');
+        for (const key of [
+            PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY,
+            PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY,
+            PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY,
+            PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY,
+        ]) {
+            context.recordScopeId(key, '');
+        }
+        context.recordScopeId(PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY, '1');
+        return {};
+    }
+    if (!usageTail.tag || !usageTail.sha256) {
+        throw new Error('platform:usage-tail: no artifact is pinned (usageTail.tag, usageTail.sha256)');
+    }
+    // ---- the key, once ------------------------------------------------------
+    // The hash is never secret, so (the same pattern `provisionPlatformEdge`
+    // uses for `EDGE_PLATFORM_KEY_HASH`) it doubles as both the undelivered
+    // marker and the final recorded value: a marker with no guard means the
+    // mint may never have reached `deliverSecret`, so it is tried again with
+    // the same hash rather than minting a second key.
+    let keyHash = recorded[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY] ?? '';
+    if (!keyHash) {
+        keyHash = recorded[PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY] ?? '';
+        let secret = keyHash ? await deps.heldKeys.resolve(PLATFORM_USAGE_TAIL_KEY_REF) : null;
+        if (!secret) {
+            secret = randomBytes(32).toString('base64url');
+            keyHash = createHash('sha256').update(secret).digest('hex');
+            context.recordScopeId(PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY, keyHash);
+            await context.persist?.();
+        }
+        await deliverKey(deps, secret);
+        context.recordScopeId(PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY, keyHash);
+        await context.persist?.();
+    }
+    // ---- the script ----------------------------------------------------------
+    await workers.uploadScript({
+        name: PLATFORM_USAGE_TAIL_SCRIPT_NAME,
+        artifactUrl: usageTailArtifactUrl(usageTail.tag),
+        artifactSha256: usageTail.sha256,
+        compatibilityDate: USAGE_TAIL_COMPATIBILITY_DATE,
+        bindings: [{ type: 'plain_text', name: 'EDGE_USAGE_URL', text: edgeUrl }],
+    });
+    // The script is foundry's from here on. Recorded now, not at the end: after
+    // a later failure the next plan must repair this Worker, not take it for a
+    // foreign one. "Fully applied" is the applied values recorded at the end.
+    context.recordScopeId(`cloudflare:worker:${PLATFORM_USAGE_TAIL_KEY}`, PLATFORM_USAGE_TAIL_SCRIPT_NAME);
+    context.recordScopeId(PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY, '');
+    await context.persist?.();
+    // The key itself is read back only to hand it to the Worker (rule 6: it
+    // never reaches an error, a log, or a plan item); edge never returns it.
+    const secretValue = await deps.heldKeys.resolve(PLATFORM_USAGE_TAIL_KEY_REF);
+    if (!secretValue) {
+        throw new Error(`platform:usage-tail: the held key (${PLATFORM_USAGE_TAIL_KEY_REF}) is gone after it was minted; hold a new one to recover`);
+    }
+    await workers.setSecrets(PLATFORM_USAGE_TAIL_SCRIPT_NAME, [
+        { name: 'EDGE_USAGE_KEY', value: secretValue, version: keyHash },
+    ]);
+    // Last, after every write the applied values depend on.
+    context.recordScopeId(PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY, usageTail.tag);
+    context.recordScopeId(PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY, usageTail.sha256);
+    return { resourceId: PLATFORM_USAGE_TAIL_SCRIPT_NAME };
+}
+/** Rule 1: delivery is tried up to `deliverAttempts` times; the error names the ref only, never the cause. */
+async function deliverKey(deps, secret) {
+    const attempts = deps.deliverAttempts ?? 3;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await deps.deliverSecret(PLATFORM_USAGE_TAIL_KEY_REF, secret);
+            return;
+        }
+        catch {
+            if (attempt >= attempts) {
+                throw new Error(`platform:usage-tail: the key (${PLATFORM_USAGE_TAIL_KEY_REF}) could not be delivered after ${attempts} tries; it went nowhere, so the next apply mints a new one`);
+            }
+            await sleep(1000 * attempt);
+        }
+    }
+}

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;
     };
 }
 /**
@@ -66,6 +69,24 @@ export interface PlatformUptimeWorker {
 }
 /** Where Archon publishes the Worker script for `tag` (a private repo; the host's `fetchArtifact` fetches it). */
 export declare function uptimeArtifactUrl(tag: string): string;
+/**
+ * foundry#1024: the usage tail Worker that meters every company Worker's
+ * use. `@wtfalch/edge`'s `packages/service/src/usage-tail-worker.ts` has no
+ * imports and builds to `usage-tail-worker.js`; foundry deploys the pinned
+ * build and never builds it, the same `tag`/`sha256` pin
+ * {@link PlatformUptimeWorker} uses. Both empty means nothing is pinned yet,
+ * and the planner reports that instead of planning the step. It has no
+ * hostname: it answers no request, only the tail events Cloudflare delivers.
+ */
+export interface PlatformUsageTailWorker {
+    enabled: boolean;
+    /** An edge release tag, `v1.2.3`. */
+    tag: string;
+    /** Lower-case hex SHA-256 of `usage-tail-worker.js` at that tag. */
+    sha256: string;
+}
+/** Where edge publishes the Worker script for `tag` (the host's `fetchArtifact` fetches it). */
+export declare function usageTailArtifactUrl(tag: string): string;
 /**
  * The shared services a declared platform names, decided in #165, plus
  * `edge` (#317, F7): the service that mints an entry's own edge key and
@@ -137,6 +158,8 @@ export interface DeclaredPlatform {
     coolify: PlatformService;
     /** foundry#542: the outside prober Worker; see {@link PlatformUptimeWorker}. */
     uptime: PlatformUptimeWorker;
+    /** foundry#1024: the usage tail Worker; see {@link PlatformUsageTailWorker}. */
+    usageTail: PlatformUsageTailWorker;
     /**
      * foundry#544: which Healthchecks instance manages the heartbeat checks
      * for every piece of scheduled work foundry sets up (the uptime Worker,

package/dist/platform.js

@@ -4,6 +4,10 @@ import { validateBlueGreen, validateDomain } from './org.js';
 export function uptimeArtifactUrl(tag) {
     return `https://github.com/wtfalch/archon/releases/download/${tag}/archon-uptime-worker.js`;
 }
+/** Where edge publishes the Worker script for `tag` (the host's `fetchArtifact` fetches it). */
+export function usageTailArtifactUrl(tag) {
+    return `https://github.com/wtfalch/edge/releases/download/${tag}/usage-tail-worker.js`;
+}
 export const PLATFORM_SERVICE_KEYS = [
     'auth',
     'mail',
@@ -87,6 +91,16 @@ export function validatePlatform(platform) {
     if (uptime.sha256 && !/^[0-9a-f]{64}$/.test(uptime.sha256)) {
         return 'uptime.sha256 must be 64 lower-case hex characters';
     }
+    const { usageTail } = platform;
+    if (Boolean(usageTail.tag.trim()) !== Boolean(usageTail.sha256.trim())) {
+        return 'usageTail.tag and usageTail.sha256 must be set together: a pin is both';
+    }
+    if (usageTail.tag && !/^v[0-9A-Za-z][0-9A-Za-z.+_-]*$/.test(usageTail.tag)) {
+        return `usageTail.tag '${usageTail.tag}' must be a release tag such as v1.2.3`;
+    }
+    if (usageTail.sha256 && !/^[0-9a-f]{64}$/.test(usageTail.sha256)) {
+        return 'usageTail.sha256 must be 64 lower-case hex characters';
+    }
     // #491: declared, never discovered -- a present-but-blank id is refused the
     // same way `serverIpv4`'s blank string is, rather than being read as unset.
     if (platform.mail.lettermintProjectId != null && !platform.mail.lettermintProjectId.trim()) {

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;

package/dist/store/postgres.js

@@ -815,6 +815,11 @@ function rowToPlatform(row) {
             gitRef: row.coolifyGitRef,
         },
         uptime: { enabled: row.uptimeEnabled, tag: row.uptimeTag, sha256: row.uptimeSha256 },
+        usageTail: {
+            enabled: row.usageTailEnabled,
+            tag: row.usageTailTag,
+            sha256: row.usageTailSha256,
+        },
         heartbeatsProvider: row.heartbeatsProvider,
     };
 }
@@ -867,6 +872,9 @@ function platformToRow(platform) {
         uptimeEnabled: platform.uptime.enabled,
         uptimeTag: platform.uptime.tag,
         uptimeSha256: platform.uptime.sha256,
+        usageTailEnabled: platform.usageTail.enabled,
+        usageTailTag: platform.usageTail.tag,
+        usageTailSha256: platform.usageTail.sha256,
         heartbeatsProvider: platform.heartbeatsProvider,
     };
 }

package/dist/store/schema.d.ts

@@ -2173,6 +2173,8 @@ export declare const foundryDeclaredPlatform: import("drizzle-orm/pg-core").PgTa
             data: {
                 steps?: number[];
                 stepHoldMinutes?: number;
+                advance?: "time" | "signal" | "approval";
+                staffFirst?: boolean;
             } | null;
             driverParam: unknown;
             notNull: false;
@@ -2188,6 +2190,8 @@ export declare const foundryDeclaredPlatform: import("drizzle-orm/pg-core").PgTa
             $type: {
                 steps?: number[];
                 stepHoldMinutes?: number;
+                advance?: "time" | "signal" | "approval";
+                staffFirst?: boolean;
             } | null;
         }>;
         edgeEnabled: import("drizzle-orm/pg-core").PgColumn<{
@@ -2445,6 +2449,57 @@ export declare const foundryDeclaredPlatform: import("drizzle-orm/pg-core").PgTa
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        usageTailEnabled: import("drizzle-orm/pg-core").PgColumn<{
+            name: "usage_tail_enabled";
+            tableName: "foundry_declared_platform";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        usageTailTag: import("drizzle-orm/pg-core").PgColumn<{
+            name: "usage_tail_tag";
+            tableName: "foundry_declared_platform";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        usageTailSha256: import("drizzle-orm/pg-core").PgColumn<{
+            name: "usage_tail_sha256";
+            tableName: "foundry_declared_platform";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         heartbeatsProvider: import("drizzle-orm/pg-core").PgColumn<{
             name: "heartbeats_provider";
             tableName: "foundry_declared_platform";

package/dist/store/schema.js

@@ -231,6 +231,10 @@ export const foundryDeclaredPlatform = pgTable('foundry_declared_platform', {
     uptimeEnabled: boolean('uptime_enabled').notNull().default(true),
     uptimeTag: text('uptime_tag').notNull().default(''),
     uptimeSha256: text('uptime_sha256').notNull().default(''),
+    /** foundry#1024, `migrations/0070_platform_usage_tail.sql`: the usage tail Worker and its artifact pin. */
+    usageTailEnabled: boolean('usage_tail_enabled').notNull().default(false),
+    usageTailTag: text('usage_tail_tag').notNull().default(''),
+    usageTailSha256: text('usage_tail_sha256').notNull().default(''),
     /** foundry#544, `migrations/0053_heartbeats_provider.sql`: which Healthchecks instance manages the heartbeat checks, decoupled from `hcEnabled` above. */
     heartbeatsProvider: text('heartbeats_provider').notNull().default('self-hosted'),
     /** `migrations/0018_platform_apply.sql`: the platform's applied state, `system:kind:key` to provider id. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",