@wtfalch/foundry 0.3.0 → 0.5.0

package/dist/plan/index.d.ts

@@ -1,10 +1,27 @@
-export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, } from './live.js';
-export { readLiveResources } from './live.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, } from './live.js';
+export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
-export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan-apply.js';
+export type { PlatformPlanDetail } from './platform-diff.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+export type { HeldKeyResolver, OrgPlatformReadiness } from './platform-org.js';
+export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
+export type { PlatformOrgClientFactories } from './platform-org-ports.js';
+export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
+export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './platform-providers.js';
+export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './platform-providers.js';
+export { createZitadelAdminMinter } from './zitadel-machine-user.js';
+export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
 export type { ScopeResolver, RecordedIds } from './providers-readers.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
-export type { CoolifyPort, CloudflarePort, ZitadelPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './executor.js';
+export type { AgoraHostPort, AgoraHostValues } from './agora.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, } from './executor.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/index.js

@@ -1,5 +1,15 @@
-export { readLiveResources } from './live.js';
+export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
-export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan-apply.js';
+export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
+export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+// #171: how a host signs files management requests with the delivered key.
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './platform-providers.js';
+export { createZitadelAdminMinter } from './zitadel-machine-user.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';
 export { ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/jobs-scheduler-http.d.ts

@@ -0,0 +1,29 @@
+import type { JobsSchedulerPort } from './executor.js';
+/**
+ * #173: the real {@link JobsSchedulerPort}, a thin client over the jobs
+ * scheduler's admin HTTP API (https://github.com/wtfalch/jobs README, "The
+ * admin API", `POST /admin/projects`). The scheduler ships no SDK for this,
+ * so it is plain `fetch`.
+ *
+ * `adminToken` is the scheduler's `SCHEDULER_ADMIN_TOKEN` (`coolifyJobs`
+ * generates it and hands it to the host through `deliverSecret`); the host
+ * resolves it and builds this client. This package holds no credential of
+ * its own. The token and the credentials in a response never appear in a
+ * thrown error -- only the status and the scheduler's own `error` text,
+ * which the API builds from the name and URLs alone.
+ */
+export declare class HttpJobsSchedulerClient implements JobsSchedulerPort {
+    private readonly adminToken;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(baseUrl: string, adminToken: string, fetchImpl?: typeof fetch);
+    registerProject(input: {
+        name: string;
+        baseUrl: string;
+        alertUrl?: string;
+    }): Promise<{
+        id: string;
+        secret?: string;
+        syncKey?: string;
+    }>;
+}

package/dist/plan/jobs-scheduler-http.js

@@ -0,0 +1,50 @@
+/**
+ * #173: the real {@link JobsSchedulerPort}, a thin client over the jobs
+ * scheduler's admin HTTP API (https://github.com/wtfalch/jobs README, "The
+ * admin API", `POST /admin/projects`). The scheduler ships no SDK for this,
+ * so it is plain `fetch`.
+ *
+ * `adminToken` is the scheduler's `SCHEDULER_ADMIN_TOKEN` (`coolifyJobs`
+ * generates it and hands it to the host through `deliverSecret`); the host
+ * resolves it and builds this client. This package holds no credential of
+ * its own. The token and the credentials in a response never appear in a
+ * thrown error -- only the status and the scheduler's own `error` text,
+ * which the API builds from the name and URLs alone.
+ */
+export class HttpJobsSchedulerClient {
+    adminToken;
+    fetchImpl;
+    baseUrl;
+    constructor(baseUrl, adminToken, fetchImpl = fetch) {
+        this.adminToken = adminToken;
+        this.fetchImpl = fetchImpl;
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    async registerProject(input) {
+        const response = await this.fetchImpl(`${this.baseUrl}/admin/projects`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${this.adminToken}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(input),
+        });
+        const body = await response.json().catch(() => undefined);
+        const fields = typeof body === 'object' && body !== null ? body : {};
+        if (response.status !== 200 && response.status !== 201) {
+            const detail = typeof fields.error === 'string' ? `: ${fields.error}` : '';
+            throw new Error(`jobs scheduler: POST /admin/projects answered ${response.status}${detail}`);
+        }
+        if (typeof fields.id !== 'string' || fields.id.length === 0) {
+            throw new Error(`jobs scheduler: POST /admin/projects answered ${response.status} with no project id`);
+        }
+        // 200 is a repeat call: the scheduler returns just the id, never a secret.
+        if (response.status === 200)
+            return { id: fields.id };
+        return {
+            id: fields.id,
+            secret: typeof fields.secret === 'string' ? fields.secret : undefined,
+            syncKey: typeof fields.syncKey === 'string' ? fields.syncKey : undefined,
+        };
+    }
+}

package/dist/plan/live.d.ts

@@ -1,6 +1,6 @@
 import type { OrgId } from '../org.js';
 /**
- * One resource as seen live in one of foundry's six systems.
+ * One resource as seen live in one of foundry's seven systems.
  *
  * `key` is unique within `(system, kind)`. Per-org singleton resources
  * (issuer, mail, chat, storage's spend limit, AI's budget, the cms site, the
@@ -13,9 +13,22 @@ import type { OrgId } from '../org.js';
  * is keyed however that system names it, so it can still be matched, or left
  * {@link https://github.com/wtfalch/foundry/issues/10 unmanaged}, by
  * `computePlanDetail`.
+ *
+ * #173 adds the seventh system, `jobs`: not a resource Coolify, Cloudflare or
+ * any of the others reports, but the jobs scheduler's own admin API
+ * (https://github.com/wtfalch/jobs, jobs#62) -- an org's registration with it,
+ * keyed by the {@link OrgId} like every other per-org singleton.
  */
 export interface LiveResource {
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms';
+    /**
+     * `'sfu'` (#170) has no reader wired below -- there is no cheap way to
+     * probe the calls SFU VM's own state over SSH during planning, so
+     * `platform-diff.ts`'s `planSfu` always plans its step when
+     * `DeclaredPlatform.sfu.enabled` is true, rather than diffing against a
+     * live resource the way every other system here does. It is still part of
+     * this union so `StepAction.system` (`diff.ts`) can name it.
+     */
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu';
     kind: string;
     key: string;
     config: Record<string, unknown>;
@@ -64,3 +77,39 @@ export interface LiveReaders {
 }
 /** Every live resource foundry can see for `orgId`, across all six systems. */
 export declare function readLiveResources(orgId: OrgId, readers: LiveReaders): Promise<LiveResource[]>;
+/**
+ * #167: one narrow interface per system reading the shared platform's own
+ * resources (`platform.ts`'s `DeclaredPlatform`) -- the platform-scoped
+ * counterpart to {@link ZitadelReader}/{@link CoolifyReader}/
+ * {@link CloudflareReader} above. There is no {@link OrgId} to scope a read
+ * by: `DeclaredPlatform` is one record, not one per org, so `listResources`
+ * here takes no argument at all.
+ *
+ * `cloudflare` is wired for #167's own `cloudflare:zone` step
+ * (`platform-diff.ts`'s `planApexZone`); #173 adds `coolify`, for the jobs
+ * scheduler's own Coolify app (`platform-diff.ts`'s `planJobs`). The rest of
+ * the platform's eventual surface (`platform-diff.ts`'s own doc comment:
+ * "every other service ... is left for its own issue to plan") adds a reader
+ * here, and to {@link PlatformLiveReaders} and {@link readLivePlatformResources}
+ * below, as each service's own step lands -- the same way `LiveReaders` above
+ * grew from three readers to six across #19, #27 and #80.
+ */
+export interface PlatformCloudflareReader {
+    listResources(): Promise<LiveResource[]>;
+}
+/** #173: the platform's own Coolify-hosted jobs scheduler (`platform-diff.ts`'s `planJobs`). */
+export interface PlatformCoolifyReader {
+    listResources(): Promise<LiveResource[]>;
+}
+export interface PlatformLiveReaders {
+    cloudflare: PlatformCloudflareReader;
+    /**
+     * Optional so every #167-era caller -- everything that plans/applies only
+     * the apex zone -- is unaffected. Without one the scheduler could never be
+     * seen live, so `planJobs` plans no step and reports the scheduler as
+     * blocked (an `unmanaged` item) rather than re-planning it forever.
+     */
+    coolify?: PlatformCoolifyReader;
+}
+/** Every live resource foundry can see for the platform, across every wired reader (#167, #173). */
+export declare function readLivePlatformResources(readers: PlatformLiveReaders): Promise<LiveResource[]>;

package/dist/plan/live.js

@@ -10,3 +10,11 @@ export async function readLiveResources(orgId, readers) {
     ]);
     return [...zitadel, ...coolify, ...cloudflare, ...files, ...ai, ...cms];
 }
+/** Every live resource foundry can see for the platform, across every wired reader (#167, #173). */
+export async function readLivePlatformResources(readers) {
+    const [cloudflare, coolify] = await Promise.all([
+        readers.cloudflare.listResources(),
+        readers.coolify ? readers.coolify.listResources() : Promise.resolve([]),
+    ]);
+    return [...cloudflare, ...coolify];
+}

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

@@ -1,10 +1,14 @@
 import type { PlanApply } from '../apply.js';
 import type { DeclaredOrg, OrgId } from '../org.js';
-import type { Plan } from '../plan.js';
+import type { Plan, PlanStep } from '../plan.js';
+import type { DeclaredPlatform } from '../platform.js';
 import type { AppliedState } from '../state.js';
-import type { DeclaredOrgStore } from '../store.js';
+import type { DeclaredOrgStore, PlatformStore } from '../store.js';
+import { type AgoraHostPort } from './agora.js';
 import { type StepAction } from './diff.js';
-import { type LiveReaders, type LiveResource } from './live.js';
+import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
+import { type HeldKeyResolver } from './platform-org.js';
+import type { CallsSfuConnectionPort } from './platform-sfu.js';
 /** Who did it, for `@wtfalch/audit`'s "who, when, the plan, the result" (#9, #19). */
 export interface AuditActor {
     readonly id: string;
@@ -27,6 +31,8 @@ export interface AuditLog {
         actor: AuditActor;
         orgId: OrgId;
         plan: Plan;
+        /** `'platform'` for the shared platform's plan (#167), whose `orgId` is the owner org's; absent for an org's own. */
+        target?: 'platform';
         at: Date;
     }): Promise<void>;
     recordApply(entry: {
@@ -35,6 +41,8 @@ export interface AuditLog {
         plan: Plan;
         outcome: 'applied' | 'refused' | 'failed';
         reason?: string;
+        /** `'platform'` for the shared platform's apply (#167), whose `orgId` is the owner org's; absent for an org's own. */
+        target?: 'platform';
         at: Date;
     }): Promise<void>;
     /** `FoundryPlanApply.destroy`'s own record -- no `Plan` involved, so this is its own entry shape rather than a reuse of `recordApply`'s. */
@@ -61,6 +69,13 @@ export interface AuthzGate {
      * own permission rather than reusing `canApply`.
      */
     canDestroy(actor: AuditActor, orgId: OrgId): Promise<boolean>;
+    /**
+     * Gates `applyPlatform` (#167): changing the shared platform every org
+     * runs on is a stronger action than applying one org, so it is its own
+     * permission. Optional so an existing host that only gates orgs keeps
+     * compiling; a gate without it refuses every platform apply.
+     */
+    canApplyPlatform?(actor: AuditActor): Promise<boolean>;
 }
 /**
  * What {@link StepExecutor.execute} needs beyond the {@link StepAction}
@@ -108,6 +123,13 @@ export interface StepExecutionContext {
      * scope key can never collide with the `system:kind:key` form.
      */
     recordScopeId(key: string, id: string): void;
+    /**
+     * Writes every id recorded so far to the store now, not only at the end of
+     * the run. For an id that must survive a crash mid-step: the ai key's id
+     * between its mint and its delivery. The end-of-run write is a superset of
+     * this one, since both write the same map.
+     */
+    persistScopeIds(): Promise<void>;
 }
 /**
  * Makes one {@link StepAction} true against a real system. No implementation
@@ -121,6 +143,58 @@ export interface StepExecutor {
         resourceId?: string;
     } | undefined>;
 }
+/**
+ * #167: {@link StepExecutionContext}'s platform-scoped counterpart -- what
+ * {@link PlatformStepExecutor.execute} needs beyond the {@link StepAction}
+ * itself, for the shared platform (`platform.ts`'s `DeclaredPlatform`) rather
+ * than one `DeclaredOrg`. A separate type rather than a reuse of
+ * `StepExecutionContext`: that type's `org` field is read directly by every
+ * real executor method in `executor.ts`, so widening it to also carry a
+ * platform would touch that whole file, which is out of scope here -- #167
+ * ships the plan/apply frame only, proven against fakes, the same way #19
+ * shipped org plan/apply before #20 wired `FoundryStepExecutor` against it.
+ */
+export interface PlatformStepExecutionContext {
+    readonly platform: DeclaredPlatform;
+    /** {@link StepExecutionContext.recordedIds}, for the platform's own run. */
+    recordedIds(): Readonly<Record<string, string>>;
+    /** {@link StepExecutionContext.recordScopeId}, for the platform's own run. */
+    recordScopeId(key: string, id: string): void;
+    /**
+     * Writes every id recorded so far to the platform's applied state now,
+     * rather than when the run ends or throws, so a crash between two calls
+     * cannot lose an id a provider already created. Optional: a caller that
+     * builds its own context (tests) may omit it.
+     */
+    persist?(): Promise<void>;
+}
+/** {@link StepExecutor}, for the platform (#167) rather than an org. */
+export interface PlatformStepExecutor {
+    /**
+     * Steps this executor cannot run, as fixed text (part of the stale-plan
+     * comparison, so it must not vary per call). The planner reports each as an
+     * unmanaged item and plans no step for it, the way a blocked Agora is
+     * reported, instead of planning a step that throws on every apply.
+     */
+    blockedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
+        auth?: string;
+        files?: string;
+        integrations?: string;
+        ai?: string;
+        archon?: string;
+        mail?: string;
+    }>;
+    /**
+     * Steps whose live state differs from the declared one in a way the recorded
+     * ids cannot show, read from the live system on each plan.
+     */
+    driftedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
+        archon?: boolean;
+    }>;
+    execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
+        resourceId?: string;
+    } | undefined>;
+}
 /**
  * One resource `FoundryPlanApply.destroy` has decided to tear down: an entry
  * from `AppliedState.serviceIds` (`resourceKey`'s `system:kind:key` form, or
@@ -168,6 +242,22 @@ export declare class NotAuthorizedError extends Error {
 export declare class NotATestOrgError extends Error {
     constructor(orgId: OrgId);
 }
+/** #167: {@link DeclaredOrgNotFoundError}, for the platform's own singleton record (#166). */
+export declare class DeclaredPlatformNotFoundError extends Error {
+    constructor();
+}
+/** #167: {@link StalePlanError}, for `planPlatform`/`applyPlatform`. */
+export declare class PlatformStalePlanError extends Error {
+    constructor();
+}
+/**
+ * #167: {@link ConfirmationRequiredError}, for `applyPlatform` -- typed as
+ * the literal word `platform` rather than a declared name, since
+ * {@link DeclaredPlatform} has no `displayName` of its own to type (#166).
+ */
+export declare class PlatformConfirmationRequiredError extends Error {
+    constructor();
+}
 export interface FoundryPlanApplyOptions {
     store: DeclaredOrgStore;
     readers: LiveReaders;
@@ -177,8 +267,51 @@ export interface FoundryPlanApplyOptions {
     authz: AuthzGate;
     /** The operator running this plan/apply — every audit row's "who" (#9, #19). */
     actor: AuditActor;
+    /** Host-supplied Agora values (#164). Optional: without it, or if it throws, the Agora is reported blocked and every other step still plans. */
+    agora?: AgoraHostPort;
+    /**
+     * #173: true when the host's executor was built with a `jobsScheduler`
+     * port. Optional, and false without it: each hosted org's registration with
+     * the jobs scheduler is then reported blocked instead of planned, so the
+     * step never runs (and fails) where no scheduler is deployed.
+     */
+    jobsScheduler?: boolean;
+    /**
+     * #177: true when the host's executor was built with its own `filesOrganisation`
+     * / `aiOrganisation` port. Without one, the org step needs the platform's
+     * key, so it is blocked while `platform.heldKeys` is absent or does not hold it.
+     */
+    filesOrganisation?: boolean;
+    aiOrganisation?: boolean;
     /** Overridable for tests; defaults to `() => new Date()`. */
     now?: () => Date;
+    /**
+     * #167: dependencies for planning/applying the shared platform (#166)
+     * alongside an org. Optional so an org-only caller — every #19-era caller,
+     * including every existing org test in this file — is unaffected;
+     * `planPlatform`/`applyPlatform` throw a plain `Error` if called without
+     * this set.
+     */
+    platform?: {
+        store: PlatformStore;
+        readers: PlatformLiveReaders;
+        executor: PlatformStepExecutor;
+        /**
+         * #170: read-only look at the held SFU connection. When the platform
+         * declares the SFU but this is absent, or resolves `null`, the plan
+         * reports the SFU as blocked (in `unmanaged`) instead of planning a step
+         * that would throw and halt every step after it.
+         */
+        sfuConnection?: CallsSfuConnectionPort;
+        /**
+         * #177: Archon's held keys. An org plan resolves the platform's files,
+         * AI and jobs keys through it and blocks the org step (naming the ref,
+         * never a value) while one is not held. Absent: every service without a
+         * host-supplied port is blocked (`filesOrganisation`, `aiOrganisation`,
+         * `jobsScheduler` on the options), never planned to fail at apply.
+         */
+        heldKeys?: HeldKeyResolver;
+    };
 }
 /**
  * The #19 implementation of {@link PlanApply}: computes a plan against live
@@ -194,10 +327,30 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly audit;
     private readonly authz;
     private readonly actor;
+    private readonly agora;
+    private readonly jobsScheduler;
+    private readonly hostFiles;
+    private readonly hostAi;
     private readonly now;
+    private readonly platformDeps;
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    /**
+     * #167: {@link plan}, for the shared platform (#166) rather than an org --
+     * there is no id to pass, since `DeclaredPlatform` is one singleton record.
+     */
+    planPlatform(): Promise<Plan>;
+    /**
+     * #167: {@link apply}, for the platform. `plan.orgId` is the platform's own
+     * `ownerOrgId` (`toPlatformPlan`'s own doc comment), so the same
+     * `AuditLog`/`AuthzGate` seams `apply` uses need no platform-specific
+     * shape of their own. `confirmedName` must be the literal word `platform`
+     * rather than a declared name -- `DeclaredPlatform` has none.
+     */
+    applyPlatform(plan: Plan, confirmedName: string): Promise<{
+        serviceIds: Record<string, string>;
+    }>;
     /**
      * Deletes every resource foundry recorded for `id`, in reverse creation
      * order, then the declared org and its applied state themselves (goal
@@ -211,7 +364,43 @@ export declare class FoundryPlanApply implements PlanApply {
      */
     destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
     private refuse;
+    private refusePlatform;
     private refuseDestroy;
     private runSteps;
     private computeFreshPlan;
+    /**
+     * #177: an org's plan reads the shared platform's own addresses and
+     * readiness through the very `platform` deps `planPlatform`/`applyPlatform`
+     * already use. With no platform wired or declared, {@link
+     * DEFAULT_ORG_PLATFORM_READINESS} reports every service not ready, so every
+     * org step that needs one is blocked.
+     */
+    private orgPlatformReadiness;
+    /**
+     * #177: `AgoraHostValues` from the applied platform, the same
+     * `platformDeps` {@link orgPlatformReadiness} reads -- but only when the
+     * host supplies no `agora` port of its own. An explicit `agora` (#164)
+     * always wins, unchanged, so a host that already has its own values
+     * (perhaps not yet wired to this platform) keeps them.
+     */
+    private orgAgoraHost;
+    /** #167: `FoundryPlanApplyOptions.platform`, or a plain `Error` naming what's missing. */
+    private requirePlatformDeps;
+    private computeFreshPlatformPlan;
+    private sfuBlockedReason;
+    /**
+     * {@link runSteps}, for the platform. The ids the steps return are recorded
+     * in `PlatformStore`'s applied state (`system:kind:key`, like an org's
+     * `serviceIds`), so a later plan finds a resource by its recorded id even
+     * when a provider's list has not caught up with a create.
+     */
+    private runPlatformSteps;
 }
+/**
+ * #9 (resolved): whether any step in a plan needs its name typed before
+ * `apply` runs it. Shared by `apply` (the org's `displayName`) and
+ * `applyPlatform` (the literal word `platform`, #167) so the platform gets
+ * the identical gate an org already has, proven end-to-end above, rather
+ * than a second copy that could drift from it.
+ */
+export declare function planNeedsConfirmation(steps: readonly PlanStep[]): boolean;