@wtfalch/foundry 0.4.0 → 0.6.0

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,118 @@
+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. #184 narrows `storageLimit`/`aiLimit`'s "small and safe" to
+ * lowering or leaving a limit unchanged -- raising either one needs
+ * approval too, until a billing field exists to say what the raise costs.
+ */
+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`, and `storageLimit`/
+ * `aiLimit` in the lowering or unchanged direction), 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.
+ *
+ * A `storageLimit` or `aiLimit` change that *raises* either limit
+ * ({@link isLimitRaise} against `org`'s current value) classifies
+ * `approval`, decided in #184: "a raise of the storage or AI limit
+ * classifies `approval` until billing fields exist. A lowering stays
+ * `auto`." `storageLimit` carries two independent limits (`limitBytes`,
+ * `limitMicros`); a raise on either one is enough.
+ *
+ * `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;

package/dist/requested-changes.js

@@ -0,0 +1,125 @@
+export const REQUESTABLE_FIELDS = [
+    'calls',
+    'storageLimit',
+    'aiLimit',
+    'domain',
+    'mailTier',
+];
+/**
+ * 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 class RequestedChangeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RequestedChangeError';
+    }
+}
+/**
+ * `org` patched by `change`, scoped to exactly the one field it names --
+ * the same `{ ...current, ...patch }` shape `store/postgres.ts`'s `update`
+ * uses for a `DeclaredOrg` patch, narrowed to a single field here since a
+ * requested change only ever touches one.
+ */
+function applyRequestedChange(org, change) {
+    switch (change.field) {
+        case 'calls':
+            return { ...org, calls: { ...org.calls, enabled: change.enabled } };
+        case 'storageLimit':
+            return {
+                ...org,
+                storage: { limitBytes: change.limitBytes, limitMicros: change.limitMicros },
+            };
+        case 'aiLimit':
+            return { ...org, ai: { limitMicros: change.limitMicros } };
+        case 'domain':
+            return { ...org, domain: change.domain };
+        case 'mailTier':
+            return { ...org, mail: { ...org.mail, mode: change.mode } };
+    }
+}
+/**
+ * Whether `before` and `after` differ on the org's own billing fields --
+ * "take price changes from the org's billing fields" (#178 "How").
+ * `DeclaredOrg` carries no price field yet (billing itself is
+ * `@wtfalch/billing`, a separate package this one does not depend on), so
+ * this always returns `false` today. It exists as the one place
+ * `classifyChange` asks the question, so a later billing field lands here
+ * rather than reshaping `classifyChange`'s own contract.
+ */
+function priceChanges(_before, _after) {
+    return false;
+}
+/**
+ * Whether a `StorageConfig`/`AiConfig` limit field moved up from `before` to
+ * `after` -- both are `null`-or-bigint-string, `null` meaning uncapped
+ * (`org.ts`'s `StorageConfig`/`AiConfig` doc). `null` is the largest
+ * possible limit, so moving a capped `before` to an uncapped `after` is a
+ * raise; moving an already-uncapped `before` anywhere is never a raise
+ * (there is nothing higher to move to); two finite values compare as
+ * bigints, never as numbers, the same bigint-safety `org.ts` requires of
+ * these fields. Equal values are not a raise.
+ */
+function isLimitRaise(before, after) {
+    if (before === null)
+        return false;
+    if (after === null)
+        return true;
+    return BigInt(after) > BigInt(before);
+}
+/**
+ * `auto` when `change` is small and safe (`calls`, and `storageLimit`/
+ * `aiLimit` in the lowering or unchanged direction), 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.
+ *
+ * A `storageLimit` or `aiLimit` change that *raises* either limit
+ * ({@link isLimitRaise} against `org`'s current value) classifies
+ * `approval`, decided in #184: "a raise of the storage or AI limit
+ * classifies `approval` until billing fields exist. A lowering stays
+ * `auto`." `storageLimit` carries two independent limits (`limitBytes`,
+ * `limitMicros`); a raise on either one is enough.
+ *
+ * `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 function classifyChange(org, change, plan) {
+    if (!REQUESTABLE_FIELDS.includes(change.field)) {
+        throw new RequestedChangeError(`'${change.field}' is not a requestable field`);
+    }
+    if (plan?.plannedSteps.some((planned) => planned.step.destroys || planned.step.migrates)) {
+        return 'approval';
+    }
+    const next = applyRequestedChange(org, change);
+    if (priceChanges(org, next))
+        return 'approval';
+    switch (change.field) {
+        case 'calls':
+            return 'auto';
+        case 'storageLimit':
+            return isLimitRaise(org.storage.limitBytes, change.limitBytes) ||
+                isLimitRaise(org.storage.limitMicros, change.limitMicros)
+                ? 'approval'
+                : 'auto';
+        case 'aiLimit':
+            return isLimitRaise(org.ai.limitMicros, change.limitMicros) ? 'approval' : 'auto';
+        case 'domain':
+        case 'mailTier':
+            return 'approval';
+    }
+}

package/dist/slug.js

@@ -118,6 +118,16 @@ const PR_SUFFIX = /-pr-\d+$/;
 const STAGE_SUFFIX = /-stage$/;
 /** `<something>-calls` — a level-1 org's own calls service hostname (foundry#145's "Decided", 2026-09-27). */
 const CALLS_SUFFIX = /-calls$/;
+/**
+ * `<something>-agora` — a level-1 org's own Agora hostname
+ * (`<slug>-agora.oikos.host`, foundry#164, the 2026-09-24 layout,
+ * foundry#14). Every org's Agora is always on (#164 "How": no new field on
+ * `DeclaredOrg` to opt out of it), so this is not an opt-in reservation the
+ * way `CALLS_SUFFIX` guards a feature an org can decline -- any slug ending
+ * `-agora` collides with *every* org's own Agora hostname the moment it is
+ * taken, not just one that turns a feature on.
+ */
+const AGORA_SUFFIX = /-agora$/;
 /**
  * Validates a candidate org slug against every rule #28 decided. Returns
  * `null` when the slug is acceptable, or a {@link SlugRejection} naming
@@ -138,10 +148,13 @@ export function validateSlug(slug) {
             message: `slug '${slug}' is reserved by the estate (#28) and cannot be taken by an org`,
         };
     }
-    if (STAGE_SUFFIX.test(slug) || PR_SUFFIX.test(slug) || CALLS_SUFFIX.test(slug)) {
+    if (STAGE_SUFFIX.test(slug) ||
+        PR_SUFFIX.test(slug) ||
+        CALLS_SUFFIX.test(slug) ||
+        AGORA_SUFFIX.test(slug)) {
         return {
             reason: 'environment-suffix',
-            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>' or '-calls') reserved for another org's own hostname (#28, #145) — 'acme-calls' is only legal as acme's calls hostname, never as an org slug in its own right`,
+            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls' or '-agora') reserved for another org's own hostname (#28, #145, #164) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, never as an org slug in its own right`,
         };
     }
     return null;

package/dist/store/audit.js

@@ -6,7 +6,7 @@ import { foundryAuditEvents } from './schema.js';
  */
 export function createPostgresAuditLog(db) {
     return {
-        async recordPlan({ actor, orgId, plan, at }) {
+        async recordPlan({ actor, orgId, plan, target, at }) {
             await db.insert(foundryAuditEvents).values({
                 at,
                 kind: 'plan',
@@ -14,9 +14,10 @@ export function createPostgresAuditLog(db) {
                 actorDisplay: actor.display,
                 orgId,
                 plan,
+                target: target ?? null,
             });
         },
-        async recordApply({ actor, orgId, plan, outcome, reason, at }) {
+        async recordApply({ actor, orgId, plan, outcome, reason, target, at }) {
             await db.insert(foundryAuditEvents).values({
                 at,
                 kind: 'apply',
@@ -26,6 +27,7 @@ export function createPostgresAuditLog(db) {
                 outcome,
                 reason: reason ?? null,
                 plan,
+                target: target ?? null,
             });
         },
         async recordDestroy({ actor, orgId, outcome, reason, at }) {

package/dist/store/postgres.d.ts

@@ -1,5 +1,5 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
-import type { DeclaredOrgStore } from '../store.js';
+import type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from '../store.js';
 /**
  * The host's own drizzle handle or a transaction open on it, same shape
  * `@wtfalch/keys`'s `HeldKeysDb` uses: postgres-js in a real host, PGlite in
@@ -48,3 +48,31 @@ export declare class DeclaredOrgError extends Error {
  * decide; `update` still merges and stores any other patch as given.
  */
 export declare function createPostgresDeclaredOrgStore(db: FoundryStoreDb): DeclaredOrgStore;
+/**
+ * Thrown by `put` when `validatePlatform` (`../platform.js`) refuses the
+ * platform given to it -- same "throw with a reason" shape
+ * {@link DeclaredOrgError} gives `create`/`update`.
+ */
+export declare class PlatformError extends Error {
+    constructor(message: string);
+}
+/**
+ * `PlatformStore` (`../store.ts`) on Postgres, for #166: get and put the one
+ * {@link DeclaredPlatform}, beside `createPostgresDeclaredOrgStore` above.
+ * `put` validates with `../platform.js`'s `validatePlatform` and then
+ * upserts onto the fixed singleton row `migrations/0016_platform.sql`
+ * declares -- the first call creates it, every later call replaces it, and
+ * the table's own `check (id)` constraint is what actually refuses a second
+ * row, not this function.
+ */
+export declare function createPostgresPlatformStore(db: FoundryStoreDb): PlatformStore;
+/**
+ * `RequestedChangeStore` (`../store.ts`) on Postgres, for #178: classify and
+ * store a company's own requested setting change on its declared org, beside
+ * `createPostgresDeclaredOrgStore` and `createPostgresPlatformStore` above.
+ * `create` classifies with `../requested-changes.js`'s `classifyChange`
+ * against the `org` given to it -- this store never loads the org itself,
+ * the same "caller already has it" choice `PlatformStore.put`'s `platform`
+ * argument makes -- and stores the result as the request's initial `state`.
+ */
+export declare function createPostgresRequestedChangeStore(db: FoundryStoreDb): RequestedChangeStore;