@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/platform-sfu.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The platform's `sfu` step (#170): the shared calls SFU (LiveKit +
+ * cloudflared, `../calls-sfu.ts`) applied from `applyPlatform` instead of by
+ * hand running `scripts/calls-sfu-deploy.mjs`. Mirrors #167's
+ * `platform-providers.ts` shape -- narrow ports, a host (archon) supplies the
+ * real implementation -- for the two things this step needs beyond
+ * `applyCallsSfu` itself:
+ *
+ * - {@link CallsSfuConnectionPort}: the SFU VM's address, SSH credentials and
+ *   host key fingerprint. A human stores these as held keys ahead of time
+ *   (#170's "Human steps") -- this package only ever reads them back, the
+ *   same way #122's original script did from the environment.
+ * - {@link CallsSfuKeysPort}: the LiveKit API key/secret pair. Unlike the
+ *   connection details, this step *mints* the pair itself, the first time,
+ *   and delivers it to held keys -- every apply after that reads the same
+ *   pair back rather than minting a second one. `executor.ts`'s
+ *   `CallsSfuPort.resolveCredentials` (the org-level calls-matrix step) reads
+ *   the same held-keys entry this delivers.
+ *
+ * {@link CallsSfuSshConnector} is the third port: opening the actual SSH
+ * session. The real one is `calls-sfu-ssh-client.ts`'s `connectCallsSfuSsh`
+ * (over `ssh2`); a host passes it as `ssh`. {@link CallsSfuConnectionPort} and
+ * {@link CallsSfuKeysPort} stay host-implemented on purpose: they read and
+ * write held keys (`@wtfalch/keys`), which only the host (archon) can reach,
+ * the same way `CoolifyPort`/`CloudflarePort`/`ZitadelPort`'s real clients
+ * live outside this package. `calls-sfu-ssh-adapter.ts`'s {@link CallsSfuSshSession} is the narrow shape
+ * a test fakes instead.
+ */
+import { type LivekitCredentials } from '../calls-sfu-keys.js';
+import { type CallsSfuSshSession } from '../calls-sfu-ssh-adapter.js';
+/** The SFU VM's own address, SSH credentials and host key fingerprint -- held keys a human stored ahead of time. */
+export interface CallsSfuConnection {
+    address: string;
+    sshUser: string;
+    sshPort: number;
+    sshPrivateKey: string;
+    /** `SHA256:...`, `hostKeyFingerprint`'s own format -- checked by `toCallsSfuHostPort`/`applyCallsSfuOverSession`. */
+    sshHostFingerprint: string;
+    /** #127's own held key, read back here rather than minted -- unrelated to the LiveKit pair this step mints. */
+    cloudflaredTunnelToken: string;
+}
+/**
+ * Read-only: `null` before a human has stored the SFU VM's connection
+ * details as held keys (#170's "Human steps"). This step never invents an
+ * address or a private key.
+ */
+export interface CallsSfuConnectionPort {
+    resolveConnection(): Promise<CallsSfuConnection | null>;
+}
+/**
+ * Where this step mints and stores the LiveKit API key/secret pair, as held
+ * keys. `resolveLivekitKeys` returns `null` before the first apply;
+ * `deliverLivekitKeys` is called exactly once, the first time this step
+ * finds nothing stored -- mirrors `FoundryStepExecutorPorts.deliverSecret`'s
+ * own "mint once, deliver, never re-mint" shape (`zitadel:app`'s
+ * `createApiApp`/`deliverSecret` pair in `executor.ts`).
+ */
+export interface CallsSfuKeysPort {
+    resolveLivekitKeys(): Promise<LivekitCredentials | null>;
+    deliverLivekitKeys(pair: LivekitCredentials): Promise<void>;
+}
+/** Opens the actual SSH session; `connectCallsSfuSsh` is the real implementation. */
+export interface CallsSfuSshConnector {
+    connect(options: {
+        address: string;
+        sshUser: string;
+        sshPort: number;
+        sshPrivateKey: string;
+        /** Verified inside the handshake, before authentication; the connector refuses a mismatch. */
+        sshHostFingerprint: string;
+    }): Promise<CallsSfuSshSession & {
+        close(): void;
+    }>;
+}
+export declare class MissingCallsSfuConnectionError extends Error {
+    constructor();
+}
+export interface CallsSfuPlatformDeps {
+    connection: CallsSfuConnectionPort;
+    keys: CallsSfuKeysPort;
+    ssh: CallsSfuSshConnector;
+    /** Overridable so a test never needs a real CSPRNG call to assert on the minted pair. */
+    mintLivekitCredentials?: () => LivekitCredentials;
+}
+/**
+ * Runs the platform's `sfu` step: resolve the connection, mint the LiveKit
+ * pair the first time (read it back on every apply after that), open the
+ * SSH session, and apply. Every part of this is safe to re-run -- minting
+ * only happens once the stored pair comes back `null`, and
+ * `applyCallsSfuOverSession` is itself idempotent -- so a second apply with
+ * the same held keys changes nothing.
+ */
+export declare function applyCallsSfuPlatformStep(deps: CallsSfuPlatformDeps): Promise<void>;

package/dist/plan/platform-sfu.js

@@ -0,0 +1,100 @@
+/**
+ * The platform's `sfu` step (#170): the shared calls SFU (LiveKit +
+ * cloudflared, `../calls-sfu.ts`) applied from `applyPlatform` instead of by
+ * hand running `scripts/calls-sfu-deploy.mjs`. Mirrors #167's
+ * `platform-providers.ts` shape -- narrow ports, a host (archon) supplies the
+ * real implementation -- for the two things this step needs beyond
+ * `applyCallsSfu` itself:
+ *
+ * - {@link CallsSfuConnectionPort}: the SFU VM's address, SSH credentials and
+ *   host key fingerprint. A human stores these as held keys ahead of time
+ *   (#170's "Human steps") -- this package only ever reads them back, the
+ *   same way #122's original script did from the environment.
+ * - {@link CallsSfuKeysPort}: the LiveKit API key/secret pair. Unlike the
+ *   connection details, this step *mints* the pair itself, the first time,
+ *   and delivers it to held keys -- every apply after that reads the same
+ *   pair back rather than minting a second one. `executor.ts`'s
+ *   `CallsSfuPort.resolveCredentials` (the org-level calls-matrix step) reads
+ *   the same held-keys entry this delivers.
+ *
+ * {@link CallsSfuSshConnector} is the third port: opening the actual SSH
+ * session. The real one is `calls-sfu-ssh-client.ts`'s `connectCallsSfuSsh`
+ * (over `ssh2`); a host passes it as `ssh`. {@link CallsSfuConnectionPort} and
+ * {@link CallsSfuKeysPort} stay host-implemented on purpose: they read and
+ * write held keys (`@wtfalch/keys`), which only the host (archon) can reach,
+ * the same way `CoolifyPort`/`CloudflarePort`/`ZitadelPort`'s real clients
+ * live outside this package. `calls-sfu-ssh-adapter.ts`'s {@link CallsSfuSshSession} is the narrow shape
+ * a test fakes instead.
+ */
+import { redactSecrets } from '../calls-sfu-deploy-support.js';
+import { mintLivekitCredentials } from '../calls-sfu-keys.js';
+import { applyCallsSfuOverSession } from '../calls-sfu-ssh-adapter.js';
+export class MissingCallsSfuConnectionError extends Error {
+    constructor() {
+        super('No SSH connection details are held for the calls SFU. Store the SFU VM’s ' +
+            'SSH key and host key fingerprint as held keys before applying the ' +
+            'platform’s sfu step (#170’s "Human steps").');
+        this.name = 'MissingCallsSfuConnectionError';
+    }
+}
+/**
+ * Runs the platform's `sfu` step: resolve the connection, mint the LiveKit
+ * pair the first time (read it back on every apply after that), open the
+ * SSH session, and apply. Every part of this is safe to re-run -- minting
+ * only happens once the stored pair comes back `null`, and
+ * `applyCallsSfuOverSession` is itself idempotent -- so a second apply with
+ * the same held keys changes nothing.
+ */
+export async function applyCallsSfuPlatformStep(deps) {
+    const connection = await deps.connection.resolveConnection();
+    if (!connection)
+        throw new MissingCallsSfuConnectionError();
+    // Every value below can echo back in an error (remote stdout/stderr, an
+    // ssh2 connect error), and the message reaches the platform audit row, so
+    // it is redacted before it leaves this function.
+    const secrets = [connection.sshPrivateKey, connection.cloudflaredTunnelToken];
+    try {
+        let pair = await deps.keys.resolveLivekitKeys();
+        if (!pair) {
+            pair = (deps.mintLivekitCredentials ?? mintLivekitCredentials)();
+            secrets.push(pair.apiKey, pair.apiSecret);
+            await deps.keys.deliverLivekitKeys(pair);
+        }
+        else {
+            secrets.push(pair.apiKey, pair.apiSecret);
+        }
+        const session = await deps.ssh.connect({
+            address: connection.address,
+            sshUser: connection.sshUser,
+            sshPort: connection.sshPort,
+            sshPrivateKey: connection.sshPrivateKey,
+            sshHostFingerprint: connection.sshHostFingerprint,
+        });
+        try {
+            const config = {
+                address: connection.address,
+                livekitApiKey: pair.apiKey,
+                livekitApiSecret: pair.apiSecret,
+                cloudflaredTunnelToken: connection.cloudflaredTunnelToken,
+            };
+            await applyCallsSfuOverSession(session, config, connection.sshHostFingerprint);
+        }
+        finally {
+            session.close();
+        }
+    }
+    catch (error) {
+        throw redactedError(error, secrets);
+    }
+}
+function redactedError(error, secrets) {
+    const original = error instanceof Error ? error : new Error(String(error));
+    const message = redactSecrets(original.message, secrets);
+    const stack = redactSecrets(original.stack ?? message, secrets);
+    if (message === original.message && stack === original.stack)
+        return original;
+    const clean = new Error(message);
+    clean.name = original.name;
+    clean.stack = stack;
+    return clean;
+}

package/dist/plan/providers-readers.js

@@ -130,6 +130,26 @@ async function withLogVolumeConfig(client, resource, recorded) {
         return resource;
     }
 }
+/**
+ * #164: the org's own recorded Agora app's live `AGORA_*` env vars, as
+ * `config.env`, so `diff.ts`'s `planAgora` can compare them with what
+ * `executor.ts` would write. Gated on `recorded` mapping this exact uuid onto
+ * the `agora` kind, like {@link withLogVolumeConfig}. Unlike that read, a
+ * failure here is not swallowed: a plan that cannot see the live config must
+ * fail, not report it as missing.
+ */
+async function withAgoraEnvConfig(client, resource, recorded) {
+    if (resource.kind !== 'application' || !recorded[resource.key]?.startsWith('agora:')) {
+        return resource;
+    }
+    const envs = await client.listEnvs(resource.key);
+    const env = {};
+    for (const e of envs) {
+        if (!e.is_preview && e.key.startsWith('AGORA_'))
+            env[e.key] = e.value;
+    }
+    return { ...resource, config: { ...resource.config, env } };
+}
 /** `@wtfalch/providers`' own `LiveResource` (`resource.ts`) has no `system` field — foundry's adds it at this boundary. */
 function toFoundryResources(system, resources) {
     return resources.map((r) => ({ system, kind: r.kind, key: r.key, config: r.config }));
@@ -157,7 +177,8 @@ export class ProvidersCoolifyReader {
             this.resolveRecordedIds(orgId),
         ]);
         const withLogConfig = await Promise.all(toFoundryResources('coolify', resources).map((r) => withLogVolumeConfig(this.client, r, recorded)));
-        return applyRecordedIds(withLogConfig, recorded);
+        const withAgoraConfig = await Promise.all(withLogConfig.map((r) => withAgoraEnvConfig(this.client, r, recorded)));
+        return applyRecordedIds(withAgoraConfig, recorded);
     }
 }
 /**

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

@@ -0,0 +1,34 @@
+import type { ZitadelPort } from './executor.js';
+/**
+ * #168: the real {@link ZitadelPort.mintAdminMachineUser}. `@wtfalch/providers`
+ * has no machine-user support, so this speaks ZITADEL's v1 management and
+ * admin APIs directly, with the same request shape as providers'
+ * `ZitadelClient.call` (bearer token, JSON in and out, `x-zitadel-orgid` for
+ * the target org, optional instance-host headers, a typed error on a non-ok
+ * response). The calls follow ZITADEL's published API reference and have not
+ * been run against a live instance.
+ *
+ *  1. `POST /management/v1/users/_search` finds the machine user by user name.
+ *  2. `POST /management/v1/users/machine` creates it when absent.
+ *  3. `POST /admin/v1/members` grants `IAM_OWNER` (409 means already granted).
+ *  4. `POST /management/v1/users/{id}/pats` adds a token, which ZITADEL
+ *     returns once.
+ *
+ * `token` is the bearer for the new instance, so it must belong to a caller
+ * allowed to create users and instance members (for example the instance's
+ * bootstrap machine user). The minted token is returned to the caller and
+ * never logged or put in an error.
+ */
+export declare class ZitadelHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface ZitadelMinterOptions {
+    /** The new instance's base URL, e.g. `https://auth.companyincluded.com`. */
+    url: string;
+    /** Bearer token allowed to create users and add instance members there. */
+    token: string;
+    fetchImpl?: typeof fetch;
+    instanceHost?: string;
+}
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser'>;

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

@@ -0,0 +1,95 @@
+/**
+ * #168: the real {@link ZitadelPort.mintAdminMachineUser}. `@wtfalch/providers`
+ * has no machine-user support, so this speaks ZITADEL's v1 management and
+ * admin APIs directly, with the same request shape as providers'
+ * `ZitadelClient.call` (bearer token, JSON in and out, `x-zitadel-orgid` for
+ * the target org, optional instance-host headers, a typed error on a non-ok
+ * response). The calls follow ZITADEL's published API reference and have not
+ * been run against a live instance.
+ *
+ *  1. `POST /management/v1/users/_search` finds the machine user by user name.
+ *  2. `POST /management/v1/users/machine` creates it when absent.
+ *  3. `POST /admin/v1/members` grants `IAM_OWNER` (409 means already granted).
+ *  4. `POST /management/v1/users/{id}/pats` adds a token, which ZITADEL
+ *     returns once.
+ *
+ * `token` is the bearer for the new instance, so it must belong to a caller
+ * allowed to create users and instance members (for example the instance's
+ * bootstrap machine user). The minted token is returned to the caller and
+ * never logged or put in an error.
+ */
+export class ZitadelHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ZitadelHttpError';
+    }
+}
+export function createZitadelAdminMinter(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    async function call(method, path, body, orgId) {
+        const response = await fetchImpl(`${options.url}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                'content-type': 'application/json',
+                ...(options.instanceHost
+                    ? {
+                        'x-zitadel-instance-host': options.instanceHost,
+                        'x-forwarded-host': options.instanceHost,
+                        'x-forwarded-proto': 'https',
+                    }
+                    : {}),
+                ...(orgId ? { 'x-zitadel-orgid': orgId } : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            // Never echo the body: on a PAT call it could hold the token.
+            throw new ZitadelHttpError(response.status, `non-JSON response from ${path}`);
+        }
+        if (!response.ok) {
+            throw new ZitadelHttpError(response.status, String(data.message ?? response.statusText));
+        }
+        return data;
+    }
+    return {
+        async mintAdminMachineUser(orgId, input) {
+            const found = await call('POST', '/management/v1/users/_search', {
+                queries: [
+                    { userNameQuery: { userName: input.userName, method: 'TEXT_QUERY_METHOD_EQUALS' } },
+                ],
+            }, orgId);
+            const existing = found.result?.[0]?.id;
+            let userId = existing;
+            if (!userId) {
+                const created = await call('POST', '/management/v1/users/machine', {
+                    userName: input.userName,
+                    name: input.name,
+                    accessTokenType: 'ACCESS_TOKEN_TYPE_BEARER',
+                }, orgId);
+                userId = typeof created.userId === 'string' ? created.userId : undefined;
+            }
+            if (!userId)
+                throw new Error('ZITADEL did not return the machine user id');
+            try {
+                await call('POST', '/admin/v1/members', { userId, roles: ['IAM_OWNER'] });
+            }
+            catch (e) {
+                if (!(e instanceof ZitadelHttpError && e.status === 409))
+                    throw e;
+            }
+            const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, orgId);
+            if (typeof pat.token !== 'string' || pat.token === '') {
+                throw new Error(`ZITADEL returned no token for machine user ${userId}`);
+            }
+            return { userId, token: pat.token };
+        },
+    };
+}

package/dist/plan.d.ts

@@ -35,6 +35,12 @@ export interface PlanStep {
  */
 export interface UnmanagedItem {
     description: string;
+    /**
+     * Set on a platform service that is blocked, not planned: the service's name
+     * (`auth`, `mail`, `integrations`, `files`, `ai`, `jobs`, `archon`, `sfu`).
+     * Absent on a live-but-undeclared resource.
+     */
+    key?: string;
 }
 /**
  * The diff between a {@link DeclaredOrg} and live reality, computed by the

package/dist/platform.d.ts

@@ -0,0 +1,55 @@
+import type { OrgId } from './org.js';
+/**
+ * A shared service the declared platform runs, one entry per key on
+ * {@link DeclaredPlatform}. `enabled` turns the service's own provisioning
+ * on; `hostname` is where it is served (default `<service>.<apex>`,
+ * {@link defaultPlatformHostname}); `gitRef` is the release it runs, the
+ * same "declared, not discovered" shape `HostingConfig.gitBranch` uses for
+ * an org's own app (`org.ts`).
+ */
+export interface PlatformService {
+    enabled: boolean;
+    hostname: string;
+    gitRef: string;
+}
+/** The eight shared services a declared platform names, decided in #165. */
+export type PlatformServiceKey = 'auth' | 'mail' | 'sfu' | 'files' | 'ai' | 'jobs' | 'integrations' | 'archon';
+export declare const PLATFORM_SERVICE_KEYS: readonly PlatformServiceKey[];
+/**
+ * The one shared platform every org's services run on -- decided in #165 as
+ * one declared platform, owned by Company Included, with its own plan and
+ * apply, mirroring `DeclaredOrg` (`org.ts`) for the shape a human declares
+ * and foundry drives live state to match.
+ *
+ * `ownerOrgId` is Company Included's own {@link OrgId} -- the platform is not
+ * a level-1 org itself, but its resources are billed and owned by one. There
+ * is exactly one declared platform (`store/postgres.ts`'s
+ * `createPostgresPlatformStore`, `migrations/0016_platform.sql`'s singleton
+ * table); a second one is refused at the database level, not by convention.
+ */
+export interface DeclaredPlatform {
+    ownerOrgId: OrgId;
+    /** The shared apex every service defaults its hostname under, e.g. `companyincluded.com`. */
+    apex: string;
+    auth: PlatformService;
+    mail: PlatformService;
+    sfu: PlatformService;
+    files: PlatformService;
+    ai: PlatformService;
+    jobs: PlatformService;
+    integrations: PlatformService;
+    archon: PlatformService;
+}
+/** `<service>.<apex>` -- the default `hostname` for a platform service, before an operator overrides it. */
+export declare function defaultPlatformHostname(service: PlatformServiceKey, apex: string): string;
+/**
+ * `null` when `platform` is valid; otherwise the reason it is not, same
+ * shape as `org.ts`'s `validateBuyerIdentity`.
+ *
+ * - `apex` is a valid domain (`org.ts`'s `validateDomain`).
+ * - Every service's `hostname` is the apex itself or a subdomain of it -- a
+ *   platform service does not live outside the platform's own apex.
+ * - Every service's `gitRef` is non-empty once that service is `enabled` --
+ *   an enabled service with nothing to deploy is not yet declared.
+ */
+export declare function validatePlatform(platform: DeclaredPlatform): string | null;

package/dist/platform.js

@@ -0,0 +1,46 @@
+import { validateDomain } from './org.js';
+export const PLATFORM_SERVICE_KEYS = [
+    'auth',
+    'mail',
+    'sfu',
+    'files',
+    'ai',
+    'jobs',
+    'integrations',
+    'archon',
+];
+/** `<service>.<apex>` -- the default `hostname` for a platform service, before an operator overrides it. */
+export function defaultPlatformHostname(service, apex) {
+    return `${service}.${apex}`;
+}
+function serviceOf(platform, key) {
+    return platform[key];
+}
+/**
+ * `null` when `platform` is valid; otherwise the reason it is not, same
+ * shape as `org.ts`'s `validateBuyerIdentity`.
+ *
+ * - `apex` is a valid domain (`org.ts`'s `validateDomain`).
+ * - Every service's `hostname` is the apex itself or a subdomain of it -- a
+ *   platform service does not live outside the platform's own apex.
+ * - Every service's `gitRef` is non-empty once that service is `enabled` --
+ *   an enabled service with nothing to deploy is not yet declared.
+ */
+export function validatePlatform(platform) {
+    const apexReason = validateDomain(platform.apex);
+    if (apexReason)
+        return `apex invalid: ${apexReason}`;
+    for (const key of PLATFORM_SERVICE_KEYS) {
+        const service = serviceOf(platform, key);
+        if (!service.hostname.trim()) {
+            return `${key}.hostname must not be empty`;
+        }
+        if (service.hostname !== platform.apex && !service.hostname.endsWith(`.${platform.apex}`)) {
+            return `${key}.hostname '${service.hostname}' must be '${platform.apex}' or a subdomain of it`;
+        }
+        if (service.enabled && !service.gitRef.trim()) {
+            return `${key}.gitRef must not be empty once ${key}.enabled is true`;
+        }
+    }
+    return null;
+}

package/dist/requested-changes.d.ts

@@ -0,0 +1,108 @@
+import type { DeclaredOrg, MailMode, OrgId } from './org.js';
+import type { PlanDetail } from './plan/diff.js';
+/**
+ * The whitelist of `DeclaredOrg` fields a company's own Boule can request a
+ * change to (#178, map #165: "a company's Boule can request setting changes
+ * on its own declared org, and Archon applies them"). Everything else is
+ * refused by {@link classifyChange} -- there is no field this module accepts
+ * outside this list.
+ *
+ * Decided in #178 "Decide": `calls`, `storageLimit` and `aiLimit` are small
+ * and safe; `domain` and `mailTier` are full self-service too, but both are
+ * migrating steps (`plan/diff.ts`'s `planMail` moves live mail between
+ * modes; a domain move is at least as disruptive) and always need approval,
+ * never auto.
+ */
+export type RequestableField = 'calls' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier';
+export declare const REQUESTABLE_FIELDS: readonly RequestableField[];
+/** Turn the org's own calls Matrix stack (`org.ts`'s `CallsConfig.enabled`) on or off. */
+export interface CallsChange {
+    field: 'calls';
+    enabled: boolean;
+}
+/** Change the org's own spend limit on Files (`org.ts`'s `StorageConfig`). */
+export interface StorageLimitChange {
+    field: 'storageLimit';
+    limitBytes: string | null;
+    limitMicros: string | null;
+}
+/** Change the org's own spend limit on AI (`org.ts`'s `AiConfig`). */
+export interface AiLimitChange {
+    field: 'aiLimit';
+    limitMicros: string | null;
+}
+/** Change the org's own domain fact (`org.ts`'s `DeclaredOrg.domain`). */
+export interface DomainChange {
+    field: 'domain';
+    domain: string | null;
+}
+/** Move the org's mail between levels (`org.ts`'s `MailConfig.mode`). */
+export interface MailTierChange {
+    field: 'mailTier';
+    mode: MailMode;
+}
+/**
+ * One company-requested change to its own declared org, keyed by
+ * {@link RequestableField}. `classifyChange` and the store both switch on
+ * `.field`.
+ */
+export type RequestedChangeValue = CallsChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange;
+/**
+ * `auto`: nothing further is required -- archon may carry the request
+ * straight into a plan and apply it. `approval`: a human must approve the
+ * request before archon applies it.
+ */
+export type ChangeClassification = 'auto' | 'approval';
+/**
+ * A stored {@link RequestedChangeValue}'s own lifecycle. `auto` and
+ * `needs_approval` are the two states {@link classifyChange} can produce at
+ * create time -- never chosen directly; `approved`, `rejected` and
+ * `applied` are archon's own workflow carrying a `needs_approval` request
+ * onward. Foundry only stores and classifies (#178 "Why"); nothing in this
+ * package transitions a state past its initial value.
+ */
+export type RequestedChangeState = 'auto' | 'needs_approval' | 'approved' | 'rejected' | 'applied';
+/**
+ * One company-requested change to its own declared org, as stored --
+ * `migrations/0017_requested_changes.sql`'s `foundry_requested_changes`
+ * row, keyed by `id` and scoped to `orgId`.
+ */
+export interface RequestedChange {
+    id: number;
+    orgId: OrgId;
+    value: RequestedChangeValue;
+    requestedBy: string;
+    createdAt: string;
+    state: RequestedChangeState;
+}
+/**
+ * Thrown by {@link classifyChange} (and by the requested-change store's
+ * `create`, which calls it) for a `change.field` outside
+ * {@link REQUESTABLE_FIELDS} -- same "throw with a reason" shape
+ * `store/postgres.ts`'s `DeclaredOrgError` and `PlatformError` use.
+ */
+export declare class RequestedChangeError extends Error {
+    constructor(message: string);
+}
+/**
+ * `auto` when `change` is small and safe (`calls`, `storageLimit`,
+ * `aiLimit`), the plan it causes has no destructive or migrating step, and
+ * it causes no price change on `org`'s own billing fields; `approval`
+ * otherwise -- every `domain` or `mailTier` change classifies `approval`
+ * unconditionally, since #178 "Decide" calls both migrating steps that
+ * always need approval, whatever direction the change moves.
+ *
+ * `plan` is the {@link PlanDetail} `change` causes -- the caller's own diff
+ * against live reality, from the same `computePlanDetail` (`plan/diff.ts`)
+ * every other apply goes through. Any `plannedSteps` entry marked
+ * `destroys` or `migrates` classifies `approval`, whatever `change.field`
+ * says: a field-name rule only ever knows what a change usually does, not
+ * what it does to this org's actual live state today (#184 "Why"). `plan`
+ * is optional because not every caller has live state to diff against yet
+ * (`store/postgres.ts`'s `create` classifies from `org` alone); omitting it
+ * falls back to the field-name rule below, unchanged from #178.
+ *
+ * Throws {@link RequestedChangeError} for a `change.field` outside
+ * {@link REQUESTABLE_FIELDS} -- "everything else is refused" (#178 "How").
+ */
+export declare function classifyChange(org: DeclaredOrg, change: RequestedChangeValue, plan?: PlanDetail): ChangeClassification;