@wtfalch/foundry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/apply.d.ts

@@ -0,0 +1,27 @@
+import type { OrgId } from './org.js';
+import type { Plan } from './plan.js';
+import type { AppliedState } from './state.js';
+/**
+ * The plan/apply seam https://github.com/wtfalch/foundry/issues/19
+ * implements.
+ *
+ * Decided in #9 (resolved): plan then apply, with the org's name typed for
+ * anything destructive, and an apply refused when its plan no longer
+ * matches reality. #19 adds: an authz permission gates an apply, and
+ * `@wtfalch/audit` records every plan and apply — who, when, the plan, the
+ * result.
+ */
+export interface PlanApply {
+    /** Reads live state from Zitadel, Coolify and Cloudflare and diffs it
+     * against the declared org (#19 "Done when"). */
+    plan(id: OrgId): Promise<Plan>;
+    /**
+     * Runs exactly the plan it was given.
+     *
+     * @param confirmedOrgName The org's name as typed by the operator,
+     * required whenever `plan` contains a step with `destroys` or `migrates`
+     * true (#9). Implementations must refuse to apply when the live state a
+     * fresh plan would compute no longer matches this `plan` (#9, #10).
+     */
+    apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+}

package/dist/apply.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, DeclaredOrg, } from './org.js';
+export { validateBuyerIdentity } from './org.js';
+export type { SlugRejectionReason, SlugRejection } from './slug.js';
+export { validateSlug, RESERVED_SLUGS } from './slug.js';
+export type { Checkpoint, LastApplied, AppliedState } from './state.js';
+export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
+export type { DeclaredOrgStore } from './store.js';
+export type { PlanApply } from './apply.js';
+export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export type { FoundryStoreDb } from './store/postgres.js';
+export { declaredOrgs, foundryAppliedState, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, } from './store/schema.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, StepAction, PlannedStep, PlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, FoundryPlanApplyOptions, } from './plan/index.js';
+export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan/index.js';
+export type { RunnerDb } from './runner/db.js';
+export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
+export { createJobRunner } from './runner/runner.js';
+export type { CreateJobRunnerOptions, JobRunner, RunFailure, RunRecord, RunStatus, RunStepsOptions, RunnerStep, } from './runner/types.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { validateBuyerIdentity } from './org.js';
+export { validateSlug, RESERVED_SLUGS } from './slug.js';
+export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export { declaredOrgs, foundryAppliedState, } from './store/schema.js';
+export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan/index.js';
+export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
+export { createJobRunner } from './runner/runner.js';

package/dist/migrations/0001_declared_org.sql

@@ -0,0 +1,61 @@
+-- @wtfalch/foundry: the declared org a human edits, stored in foundry's own
+-- database (#10: "not git" — the operator page is the only editor). Mirrors
+-- src/store/schema.ts's `declaredOrgs` table.
+--
+-- The full schema exists from day one, including columns nothing implements
+-- yet (#7 "Shape", #18 "Done when"), so a field never comes to describe
+-- something real without a column already here to say so. `apply` (#19) is
+-- what refuses a field it cannot yet make true; this migration only stores
+-- whatever the declared file says.
+--
+-- id is the opaque id foundry mints at creation (#7 "Identity", org.ts's
+-- OrgId) — never derived from Zitadel or any other live system. slug and
+-- display_name are mutable; slug additionally freezes once the org has mail
+-- (mail_mode <> 'off'), enforced in src/store/postgres.ts's `update`, not
+-- here — the two-file split (#10) makes the store, not the database, the
+-- single writer of the declared org, so the rule lives in the code path that
+-- already has to reject "combinations foundry knows are impossible" (#18)
+-- with a reason a caller can read, which a bare CHECK constraint cannot give.
+
+create table if not exists foundry_declared_orgs (
+  id                  text not null,
+  slug                text not null,
+  display_name        text not null,
+
+  -- A fact, nothing more (#7 amendment 1): recording it never starts a
+  -- service change on its own. null until the org has a domain.
+  domain              text,
+
+  -- MailConfig (org.ts). 'off' is not a decided mail state; it says mail is
+  -- not foundry's concern for this org yet, rather than the column silently
+  -- defaulting to one of the two that are.
+  mail_mode           text not null default 'off',
+  mail_uses_domain    boolean not null default false,
+
+  chat_uses_domain    boolean not null default false,
+  calls_uses_domain   boolean not null default false,
+  issuer_uses_domain  boolean not null default false,
+
+  sso_enabled         boolean not null default false,
+  guests_enabled      boolean not null default false,
+  solo_enabled        boolean not null default false,
+
+  -- null until #11's module-to-package rewrite ships (org.ts's doc on
+  -- `bespokeAppRepo`); the column exists now per #7's "full schema exists
+  -- from day one".
+  bespoke_app_repo    text,
+
+  -- AdoptedApp | null (org.ts). null when the org has no adopted app; when
+  -- it does, its form is 'bundle' (ships first) or 'repo' (declared, refused
+  -- by apply until it exists, per #7's #15 refinement comment).
+  adopted_app_form    text,
+
+  created_at          timestamptz not null default now(),
+  updated_at          timestamptz not null default now(),
+
+  constraint foundry_declared_orgs_pkey primary key (id),
+  constraint foundry_declared_orgs_mail_mode_check
+    check (mail_mode in ('off', 'received', 'hosted')),
+  constraint foundry_declared_orgs_adopted_app_form_check
+    check (adopted_app_form is null or adopted_app_form in ('bundle', 'repo'))
+);

package/dist/migrations/0002_applied_state.sql

@@ -0,0 +1,43 @@
+-- @wtfalch/foundry: foundry's own record of what has actually been made true
+-- for an org, separate from the human-edited declared org #0001 creates
+-- (#7 "Shape", #10 resolved). Mirrors src/store/schema.ts's
+-- `foundryAppliedState` table.
+--
+-- One row per org, replaced in place by an upsert (src/store/postgres.ts's
+-- `putAppliedState`) rather than appended to, matching state.ts's
+-- `AppliedState`: it is a single current snapshot, not a history. Audit rows
+-- for the history are `@wtfalch/audit`'s job (#9), not this table's.
+
+create table if not exists foundry_applied_state (
+  org_id                              text not null,
+
+  -- Record<string, string>: one id per service that takes jobs from many
+  -- orgs plus the per-org services, each keyed by that service's own name
+  -- (state.ts's `serviceIds`, https://github.com/wtfalch/foundry/issues/14
+  -- resolved research #4).
+  service_ids                         jsonb not null default '{}'::jsonb,
+
+  -- Checkpoint[]: completed steps of the current or most recent apply
+  -- (state.ts's `checkpoints`, #7 "Shape" / research #5's check-apply-with-
+  -- checkpoints shape).
+  checkpoints                         jsonb not null default '[]'::jsonb,
+
+  -- string[]: the name of every declared-org field the most recent apply
+  -- could not make true because nothing implements it yet (state.ts's
+  -- `failedFields`, #18's "Done when": "apply fails loudly and by name on
+  -- any field it cannot yet make true").
+  failed_fields                       jsonb not null default '[]'::jsonb,
+
+  -- LastApplied | null (state.ts). Both columns are null together before
+  -- this org has ever had a completed apply; never one without the other.
+  last_applied_at                     timestamptz,
+  last_applied_declared_org_version   text,
+
+  constraint foundry_applied_state_pkey primary key (org_id),
+  constraint foundry_applied_state_org_fkey foreign key (org_id)
+    references foundry_declared_orgs (id),
+  constraint foundry_applied_state_last_applied_check
+    check (
+      (last_applied_at is null) = (last_applied_declared_org_version is null)
+    )
+);

package/dist/migrations/0003_foundry_runs.sql

@@ -0,0 +1,53 @@
+-- @wtfalch/foundry ./runner: the run/lock table the job runner uses to
+-- checkpoint an apply and hold its lock as a database row, never a
+-- lockfile (#9, resolved; #17). Mirrors src/runner/schema.ts, which is not
+-- the source of truth -- this file is, following @wtfalch/keys' ./held
+-- convention (src/held/schema.ts's own header says the same of its SQL).
+--
+-- One row per apply run. `status` doubles as the lock: the partial unique
+-- index below, on (org_id) where status is not 'succeeded', means a second
+-- apply for an org that already has a run in flight -- or one that failed
+-- and has not been resolved -- is refused by Postgres itself, from any
+-- number of containers. #9's rejected alternative was a PID lockfile next
+-- to the state file, which cannot do that: "a worker can run in more than
+-- one container."
+--
+-- `step_ids` is the run's plan, fixed at enqueue time (`foundry_runs`
+-- stores no function -- a worker resuming a run supplies its own step
+-- objects again and this array is what they are checked against).
+-- `checkpoints` is the record of what has already run, in order, shaped
+-- like src/state.ts's `Checkpoint`. `failure`, once set, names the step
+-- that stopped the run and why; nothing here clears it automatically --
+-- there is no automatic retry (#9).
+--
+-- Numbered 0003 in foundry's single migration sequence. It was the runner
+-- module's own 0001 while #17, #18 and #19 were in flight in parallel
+-- branches; a host applies one ordered sequence, not one per module, so the
+-- three directories became `src/migrations` once all three merged. Nothing
+-- here depends on 0001 or 0002 -- `foundry_runs.org_id` deliberately carries
+-- no foreign key to `foundry_declared_orgs`, so a run can be recorded for an
+-- org this database has never declared.
+--
+-- Applied by whatever migrates a host's database (app-template's
+-- `scripts/migrate-and-start.sh` pattern: copied in as the host's own next
+-- numbered file, never edited in place). This module's own tests apply it
+-- directly to PGlite (src/runner/test/db.ts).
+
+create table if not exists foundry_runs (
+  id          text primary key,
+  org_id      text not null,
+  status      text not null default 'running',
+  step_ids    jsonb not null,
+  checkpoints jsonb not null default '[]',
+  failure     jsonb,
+  created_at  timestamptz not null default now(),
+  updated_at  timestamptz not null default now(),
+  constraint foundry_runs_status_check check (status in ('running', 'succeeded', 'failed')),
+  constraint foundry_runs_org_id_check check (org_id ~ '^[A-Za-z0-9_-]{1,128}$')
+);
+
+-- The lock itself: at most one non-succeeded run per org, enforced by
+-- Postgres regardless of how many containers or processes are writing.
+create unique index if not exists foundry_runs_org_lock_idx
+  on foundry_runs (org_id)
+  where status <> 'succeeded';

package/dist/migrations/0004_slug_unique.sql

@@ -0,0 +1,26 @@
+-- @wtfalch/foundry: the declared org's slug is globally unique (#28), on
+-- top of #0001's `foundry_declared_orgs` table. Mirrors
+-- src/store/schema.ts's `declaredOrgs` table, which has no index of its own
+-- to express -- drizzle-kit has no journal here (this package's convention,
+-- #0001's header), so this file, not the schema, is the index's source of
+-- truth.
+--
+-- Forced by the level-1 apex `oikos.host` being live (#28 "Why"): every
+-- level-1 org's hostname is flat off that apex (`acme.oikos.host`), so a
+-- duplicate slug is a hostname collision from the moment the second org is
+-- created, not a cosmetic clash to resolve later. src/store/postgres.ts's
+-- `create` and `update` already call src/slug.ts's `validateSlug` before
+-- this index is ever reached; the index exists to catch the race the
+-- pre-check cannot -- two concurrent creates for the same slug -- which
+-- postgres.ts maps back to the same `DeclaredOrgError` a pre-check would
+-- have thrown, per #18's rule that a caller gets a reason by name either
+-- way.
+--
+-- DNS-label validity and the reserved/environment-suffix rules are
+-- src/slug.ts's job, not a CHECK constraint's -- #0001's header already
+-- gives the reasoning for keeping "combinations foundry knows are
+-- impossible" in the code path that can explain itself, not in SQL that
+-- can't.
+
+create unique index if not exists foundry_declared_orgs_slug_idx
+  on foundry_declared_orgs (slug);

package/dist/migrations/0005_spend_limits.sql

@@ -0,0 +1,34 @@
+-- @wtfalch/foundry: an org's own spend limits for storage and AI, declared
+-- alongside everything else in `foundry_declared_orgs` (#0001) and
+-- reconciled onto Files and AI by `apply` (#27). Mirrors
+-- src/store/schema.ts's `declaredOrgs` table additions.
+--
+-- storage_limit_bytes / storage_limit_micros are the org's OWN declared
+-- limit on Files -- never Files' operator-set ceiling
+-- (files/packages/sdk/src/types.ts's `ceilingBytes`/`ceilingMicros`), which
+-- is a separate, operator-driven hard cap this table has no opinion on.
+-- ai_limit_micros is the same shape for `@wtfalch/ai`'s per-organisation
+-- budget (ai/packages/service/src/budget.ts's `limit_micros`).
+--
+-- All three are bigint-safe decimal strings of non-negative integers, stored
+-- as text like every other declared-org string field, never a numeric
+-- column -- the value only ever round-trips here, it is never computed on,
+-- and a limit can exceed what a JS `number` or this store's own arithmetic
+-- would safely hold. null means uncapped, additive with every existing row
+-- (#0001's "full schema exists from day one" pattern -- a new nullable
+-- column, not a reshape).
+--
+-- The non-negative-integer-string format is checked in
+-- src/store/postgres.ts, the same place src/slug.ts's rules are checked
+-- (#0004's header), not in a CHECK constraint here: the reason for a refusal
+-- belongs in the code path that can explain itself, same as the slug rules
+-- and the mail-freeze rule before it.
+--
+-- Spend itself (usage, money spent) is never declared (#27 "Done when") --
+-- it stays a runtime fact read live from Files' metering and AI's usage
+-- ledger, so no column for it exists here.
+
+alter table foundry_declared_orgs
+  add column if not exists storage_limit_bytes  text,
+  add column if not exists storage_limit_micros text,
+  add column if not exists ai_limit_micros       text;

package/dist/migrations/0006_buyer_identity.sql

@@ -0,0 +1,31 @@
+-- @wtfalch/foundry: the customer's own buyer identity for invoices (#67,
+-- part of #59), declared alongside everything else in `foundry_declared_orgs`
+-- (#0001). Mirrors `src/store/schema.ts`'s `declaredOrgs` table additions.
+--
+-- Shape matches `@wtfalch/invoicing`'s `Party`
+-- (invoicing/packages/invoicing/src/parties.ts) field for field, so archon
+-- can build a buyer from this row without mapping: legal_name, org_number,
+-- an address of four parts, and vat_registered. Set by archon only (#60,
+-- resolved), never by the estate's own seller identity, which lives in
+-- archon's own config, not here (#60).
+--
+-- All seven columns are nullable -- a brand new org has no buyer identity at
+-- all, the same "full schema exists from day one" pattern #0001 and #0005
+-- established: a new nullable column, never a reshape. org.ts's validation
+-- (not a CHECK constraint here, same reasoning as #0005's header) enforces:
+-- org_number is nine digits when present, the four address parts are all
+-- present or all absent, and legal_name is required once any other buyer
+-- field is set.
+--
+-- No live system ever holds a second copy of this data to reconcile against
+-- (#66: "no foundry provisioning" for the first charge+invoice flow) --
+-- archon reads this row directly at invoice time.
+
+alter table foundry_declared_orgs
+  add column if not exists legal_name           text,
+  add column if not exists org_number            text,
+  add column if not exists address_street        text,
+  add column if not exists address_postal_code   text,
+  add column if not exists address_city          text,
+  add column if not exists address_country       text,
+  add column if not exists vat_registered        boolean;

package/dist/migrations/0007_site.sql

@@ -0,0 +1,18 @@
+-- @wtfalch/foundry: an org's cms site (T10, "teach foundry that an org can
+-- declare a website"), declared alongside everything else in
+-- `foundry_declared_orgs` (#0001). Mirrors `src/store/schema.ts`'s
+-- `declaredOrgs` table additions.
+--
+-- SiteConfig (org.ts) is the same `usesDomain`-opts-into-`domain` shape as
+-- mail/chat/calls/issuer (#0001's `mail_uses_domain` etc.), plus its own
+-- on/off switch: site_enabled turns the site on at all, served on the org's
+-- `<slug>.oikos.host` hostname (src/slug.ts) by default, or on its own
+-- `domain` once site_uses_domain is true and `domain` is set.
+--
+-- Both booleans default false -- a brand new org has no cms site, the same
+-- "full schema exists from day one" pattern #0001 and #0005 established: a
+-- new column with a decided default, never a reshape.
+
+alter table foundry_declared_orgs
+  add column if not exists site_enabled     boolean not null default false,
+  add column if not exists site_uses_domain boolean not null default false;

package/dist/org.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Opaque, minted by foundry when an org is created. Keys the declared org,
+ * the applied state, every estate-wide service's id map, and the chat
+ * `server_name`.
+ *
+ * Decided in https://github.com/wtfalch/foundry/issues/7 (amendment 5),
+ * which rejected keying on Zitadel's own org id instead: the declared file
+ * is written before foundry has called Zitadel at all, so keying to Zitadel
+ * would mean an org can't exist in the file until that call happens, and
+ * replacing Zitadel later would orphan every id map.
+ */
+export type OrgId = string & {
+    readonly __brand: 'OrgId';
+};
+/**
+ * Mail hosting mode for an org's addresses, on the one shared Stalwart
+ * process every org's mail lives on (no per-org instance).
+ *
+ * Decided in #7 ("Mail") and https://github.com/wtfalch/foundry/issues/14's
+ * resolved research #2:
+ * - `received` — level 2: MX stays with Google or Microsoft, dual delivery
+ *   brings mail in, Stalwart sends as the domain.
+ * - `hosted` — level 3: Stalwart holds the domain's MX outright, reached by
+ *   a one-time copy then MX cutover from `received`.
+ * `off` is not a decided state — it exists so a declared org can say mail is
+ * not foundry's concern here, rather than the field silently defaulting.
+ */
+export type MailMode = 'off' | 'received' | 'hosted';
+/**
+ * Mail's per-service opt-in into the org's `domain` fact.
+ *
+ * Decided in #7 amendment 1: setting `domain` alone never starts a mail
+ * change. `usesDomain` is mail's own field for that, independent of
+ * `mode` — a domain can be recorded before mail is ever pointed at it.
+ */
+export interface MailConfig {
+    mode: MailMode;
+    usesDomain: boolean;
+}
+/**
+ * Chat's per-service opt-in into the org's `domain` fact.
+ *
+ * Chat is provisioned at level 1 on a wtfalch `server_name` regardless of
+ * `usesDomain` (#7 "Chat"). Flipping `usesDomain` on fires a re-key onto a
+ * new Synapse+MAS that copies rooms and messages across so history reads
+ * continuous; flipping it off reverses onto the original `server_name` —
+ * legal in the schema in both directions, but the reverse merge is not
+ * built yet (#7 amendment 3) and `apply` fails loudly on it until it is.
+ * Never fired by `domain` alone (#7 amendment 1).
+ */
+export interface ChatConfig {
+    usesDomain: boolean;
+}
+/**
+ * Calls' per-service opt-in into the org's `domain` fact, in the same shape
+ * as mail, chat and the issuer so that none of them are coupled to `domain`
+ * being set (#7 amendment 1, carried into
+ * https://github.com/wtfalch/foundry/issues/18's "Done when" list). Nothing
+ * about calls' own provisioning is decided yet beyond this.
+ */
+export interface CallsConfig {
+    usesDomain: boolean;
+}
+/**
+ * The issuer's per-service opt-in into the org's `domain` fact.
+ *
+ * Decided in #7's corrections (2): moving the issuer onto the org's own
+ * domain invalidates every passkey in the org, so it is at least as
+ * disruptive as the chat re-key and gets the same rule — `domain` alone
+ * never moves it. Doing so is a destructive step under #9's rules and needs
+ * the org's name typed before `apply` runs it.
+ */
+export interface IssuerConfig {
+    usesDomain: boolean;
+}
+/**
+ * The cms site's per-service opt-in into the org's `domain` fact, plus its
+ * own on/off switch, in the same shape as mail, chat, calls and the issuer
+ * so that recording a domain never starts a site change on its own (#7
+ * amendment 1).
+ *
+ * Decided for foundry to teach an org it can declare a website: `enabled`
+ * turns on the "standard" app form #14 names ("our code, their CMS
+ * content") -- a `@wtfalch/cms` site served on the org's `<slug>.oikos.host`
+ * hostname (`../slug.ts`) by default, or on its own `domain` once
+ * `usesDomain` is true and `DeclaredOrg.domain` is set.
+ */
+export interface SiteConfig {
+    enabled: boolean;
+    usesDomain: boolean;
+}
+/**
+ * Per-org SSO. Decided to exist in #14 ("Also in scope") and its resolved
+ * research #3 ("per-org SSO code exists unused"); nothing about its
+ * configuration is decided beyond that it can be turned on.
+ */
+export interface SsoConfig {
+    enabled: boolean;
+}
+/**
+ * Guests from other orgs. Decided to exist in #14 ("Also in scope"); its
+ * resolved research #3 notes org access needs project grants that don't
+ * exist yet, so nothing about how a guest is granted access is decided.
+ */
+export interface GuestsConfig {
+    enabled: boolean;
+}
+/**
+ * A solo person as an org of one. Explicitly left open in #7 amendment 6:
+ * whether solo earns its own field or is just an org with one member waits
+ * on #11 and #13. The field exists now, per #7's "full schema exists from
+ * day one", so that decision doesn't force a schema reshape later.
+ */
+export interface SoloConfig {
+    enabled: boolean;
+}
+/**
+ * The org's own spend limit on Files, declared here and reconciled onto
+ * Files by `apply` (#27).
+ *
+ * `limitMicros` is the org's own declared limit -- NOT Files' operator-set
+ * `ceilingMicros` (files/packages/sdk/src/types.ts:118's `QuotaSummary`,
+ * :132's `BudgetSummary`, and `UpdateOrganisationCeilingInput`), which is a
+ * separate, operator-driven hard cap this field has no opinion on and never
+ * writes to. `apply` pushes `limitBytes`/`limitMicros` onto Files as
+ * `QuotaSummary.organisation.limitBytes` / `BudgetSummary.organisation.limitMicros`.
+ *
+ * Both are bigint-safe decimal strings of non-negative integers, never
+ * converted to a number -- a limit can exceed what a JS `number` safely
+ * holds. `null` means uncapped. Spend itself (usage, money spent) is never
+ * declared (#27 "Done when"): it is a runtime fact read live from Files'
+ * metering, shown beside this limit, never stored here.
+ */
+export interface StorageConfig {
+    limitBytes: string | null;
+    limitMicros: string | null;
+}
+/**
+ * The org's own spend limit on `@wtfalch/ai`, declared here and reconciled
+ * onto AI by `apply` (#27). AI already carries a per-organisation budget with
+ * this exact shape (ai/packages/service/src/budget.ts:34's `Budget.limit_micros`);
+ * this is the declared value `apply` pushes onto it.
+ *
+ * A bigint-safe decimal string of a non-negative integer, never converted to
+ * a number. `null` means uncapped. Spend itself (usage, money spent) is
+ * never declared (#27 "Done when"): it is a runtime fact read live from AI's
+ * usage ledger, shown beside this limit, never stored here.
+ */
+export interface AiConfig {
+    limitMicros: string | null;
+}
+/**
+ * The customer's own postal address for invoicing -- all four parts or none
+ * (org.ts's `validateBuyerIdentity`), matching
+ * `@wtfalch/invoicing`'s `Address` (invoicing/packages/invoicing/src/parties.ts).
+ */
+export interface BuyerAddress {
+    street: string;
+    postalCode: string;
+    city: string;
+    country: string;
+}
+/**
+ * The customer's buyer identity for invoices (#67, part of #59), set by
+ * archon only (#60, resolved) -- the estate's own seller identity lives in
+ * archon's own config, never here. Shape matches `@wtfalch/invoicing`'s
+ * `Party` (invoicing/packages/invoicing/src/parties.ts) field for field, so
+ * archon can build a buyer from this row without mapping.
+ *
+ * All four fields are independently nullable -- a brand new org has none of
+ * them -- but not independently valid in every combination:
+ * `validateBuyerIdentity` requires `legalName` once any other field is set,
+ * an `orgNumber` of exactly nine digits when present, and an `address` with
+ * all four parts or none.
+ *
+ * No live system holds a second copy of this to reconcile against (#66: "no
+ * foundry provisioning" for the first charge+invoice flow) -- archon reads
+ * this row directly at invoice time.
+ */
+export interface BuyerIdentity {
+    legalName: string | null;
+    orgNumber: string | null;
+    address: BuyerAddress | null;
+    vatRegistered: boolean | null;
+}
+/**
+ * `null` when `buyer` is valid; otherwise the reason it is not, for a caller
+ * (the store, on `create`/`update`) to report rather than throw blind (same
+ * shape as `../slug.ts`'s `validateSlug`).
+ *
+ * - `orgNumber`, when present, is exactly nine digits (matches
+ *   `@wtfalch/invoicing`'s `orgNumberSchema`).
+ * - `address` is all four parts or none -- never partial.
+ * - `legalName` is required once any other buyer field is set; a bare
+ *   `legalName` with nothing else is valid on its own (a customer known by
+ *   name before its other details are typed).
+ */
+export declare function validateBuyerIdentity(buyer: BuyerIdentity): string | null;
+/**
+ * The form an app foundry does not own takes. Decided in #7's `#15`
+ * refinement comment:
+ * - `bundle` — a built artefact we serve on the org's domain, runs only in
+ *   the browser, and is the one that ships first.
+ * - `repo` — we build their source; declared but refused by `apply` until
+ *   it exists.
+ * The boundary this encodes: a `bundle` app reaches our services over HTTP
+ * and never server-side.
+ */
+export type AdoptedAppForm = 'bundle' | 'repo';
+/**
+ * An app whose code foundry does not own — the adopted line, the first
+ * sale. Decided in #7's `#15` schema-addition comment: added on day one
+ * because the full schema exists from day one and a retrofit would be a
+ * reshape, even though nothing is built behind it for v1.
+ */
+export interface AdoptedApp {
+    form: AdoptedAppForm;
+}
+/**
+ * The org a human declares, edited from the operator page and stored in
+ * foundry's own database — never git (#10, resolved: "The declared org
+ * lives in foundry's own database with the operator page as its editor").
+ *
+ * `apply` (see {@link PlanApply} in `./apply.ts`) reads live state from
+ * Zitadel, Coolify and Cloudflare and drives it to match this file, failing
+ * loudly and by name on any field it cannot yet make true (#7 "Shape").
+ *
+ * The full schema exists from day one, including fields nothing implements
+ * yet, so the file never comes to describe something that became real
+ * without a matching field already being here to say so (#7 "Shape").
+ */
+export interface DeclaredOrg {
+    id: OrgId;
+    /**
+     * Mutable at any time — except: once `mail.mode` is not `'off'`, the slug
+     * is frozen. The level-1 mail address is built from it
+     * (`{slug}@{wtfalch mail apex}`), and an address people cannot read aloud
+     * is not an address (#7 corrections 3). An org on its own domain is
+     * unaffected, since its addresses read the domain, not the slug.
+     */
+    slug: string;
+    /** Mutable at any time, no restrictions (#7 "Identity"). */
+    displayName: string;
+    /**
+     * A fact, nothing more. Recording a domain here never starts a service
+     * change on its own — each service above opts in for itself via its own
+     * `usesDomain` field (#7 amendment 1). An org can therefore have mail and
+     * chat on different domains at once; `apply` must report that plainly
+     * rather than treat it as an error.
+     */
+    domain: string | null;
+    mail: MailConfig;
+    chat: ChatConfig;
+    calls: CallsConfig;
+    issuer: IssuerConfig;
+    /** `enabled: false` by default -- a brand new org has no cms site. */
+    site: SiteConfig;
+    sso: SsoConfig;
+    guests: GuestsConfig;
+    solo: SoloConfig;
+    /** The org's own spend limit on Files (#27). */
+    storage: StorageConfig;
+    /** The org's own spend limit on AI (#27). */
+    ai: AiConfig;
+    /** The customer's own buyer identity for invoices (#67). `validateBuyerIdentity` above. */
+    buyer: BuyerIdentity;
+    /**
+     * A foundry-generated repo for this org's bespoke app — one of the three
+     * ways a customer can have an app, decided 2026-09-22 on the map (#14):
+     * adopted, standard, bespoke. `null` until #11's module-to-package rewrite
+     * ships; the field exists now per #7's "full schema exists from day one".
+     */
+    bespokeAppRepo: string | null;
+    /** `null` when the org has none. */
+    adoptedApp: AdoptedApp | null;
+}

package/dist/org.js

@@ -0,0 +1,29 @@
+const ORG_NUMBER_PATTERN = /^\d{9}$/;
+/**
+ * `null` when `buyer` is valid; otherwise the reason it is not, for a caller
+ * (the store, on `create`/`update`) to report rather than throw blind (same
+ * shape as `../slug.ts`'s `validateSlug`).
+ *
+ * - `orgNumber`, when present, is exactly nine digits (matches
+ *   `@wtfalch/invoicing`'s `orgNumberSchema`).
+ * - `address` is all four parts or none -- never partial.
+ * - `legalName` is required once any other buyer field is set; a bare
+ *   `legalName` with nothing else is valid on its own (a customer known by
+ *   name before its other details are typed).
+ */
+export function validateBuyerIdentity(buyer) {
+    if (buyer.orgNumber !== null && !ORG_NUMBER_PATTERN.test(buyer.orgNumber)) {
+        return `orgNumber '${buyer.orgNumber}' must be exactly nine digits`;
+    }
+    if (buyer.address !== null) {
+        const { street, postalCode, city, country } = buyer.address;
+        if (!street || !postalCode || !city || !country) {
+            return 'address must have all four parts (street, postalCode, city, country) or none';
+        }
+    }
+    const anyOtherFieldSet = buyer.orgNumber !== null || buyer.address !== null || buyer.vatRegistered !== null;
+    if (buyer.legalName === null && anyOtherFieldSet) {
+        return 'legalName is required once any other buyer field is set';
+    }
+    return null;
+}