@wtfalch/foundry 0.46.0 → 0.48.0

package/dist/plan/stage-isolation.js

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto';
+const SECRET_NAME = /(KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|KEK|DATABASE_URL)/;
+const URL_NAME = /(_URL|_URI|_UPSTREAM|_ISSUER)$/;
+const ID_NAME = /(_ID|_ORGANI[SZ]ATION_ID)$/;
+/** The class of an env name, from its spelling. */
+export function envClass(name) {
+    if (SECRET_NAME.test(name))
+        return 'secret';
+    if (URL_NAME.test(name))
+        return 'url';
+    if (ID_NAME.test(name))
+        return 'id';
+    return 'literal';
+}
+/** `AB_*` matches by prefix; anything else matches exactly. */
+function globMatches(pattern, name) {
+    return pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : pattern === name;
+}
+const matchesAny = (patterns, name) => patterns.some((p) => globMatches(p, name));
+const MAIL_NAME = /^(MAIL_|LETTERMINT_|SMTP_)/;
+/** Env names (or `PREFIX_*`) each kind of stage app may hold. A name not here is refused. */
+export const STAGE_ALLOWLIST = {
+    boule: [
+        'APP_URL',
+        'BOULE_ORG_NAME',
+        'AUTH_ISSUER',
+        'AUTH_ORGANIZATION_ID',
+        'AUTH_CLIENT_ID',
+        'AUTH_APP_KEY',
+        'AUTH_COOKIE_SECRET',
+        'DATABASE_URL',
+        'DATABASE_URL_OWNER',
+        'LOG_DIR',
+        'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY',
+        'REPORTING_*',
+        'AUTHZ_BOOTSTRAP_OPERATOR*',
+        'AUTHZ_FIRST_OWNER*',
+        'CUSTOMERS_ORGANISATION_ID',
+        'ARCHON_URL',
+        'ARCHON_ORG_ID',
+        'ARCHON_CREDENTIAL',
+        'ARCHON_BRIDGE_SECRET',
+        'AUTHZ_PEER_PASSWORD_OPERATOR',
+        'OWNER_SEED_SECRET',
+    ],
+    agora: ['AGORA_CONFIG', 'SIGNIN_UPSTREAM', 'LOG_DIR'],
+    archon: [
+        'APP_URL',
+        'AUTH_ISSUER',
+        'AUTH_ORGANIZATION_ID',
+        'CI_ORGANIZATION_ID',
+        'AUTH_CLIENT_ID',
+        'AUTH_APP_KEY',
+        'AUTH_COOKIE_SECRET',
+        'DATABASE_URL',
+        'DATABASE_URL_OWNER',
+        'AUTHZ_DATABASE_URL',
+        'BOULE_URL',
+        'ARCHON_BRIDGE_SECRET',
+        'REPORTING_SITE',
+        'KEYSTORE_KEK',
+        'LOG_LEVEL',
+        'LOG_DIR',
+        'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY',
+    ],
+    customer: [
+        'LOG_DIR',
+        'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY',
+        'APP_URL',
+        'APP_ENVIRONMENT',
+        'DATABASE_URL',
+        'DATABASE_URL_OWNER',
+        'AUTH_ISSUER',
+        'AUTH_ORGANIZATION_ID',
+        'AUTH_CLIENT_ID',
+        'AUTH_APP_KEY',
+        'AUTH_COOKIE_SECRET',
+        'FILES_URL',
+        'FILES_ORGANISATION_ID',
+        'FILES_API_KEY',
+        'AI_URL',
+        'AI_ORGANISATION_ID',
+        'AI_API_KEY',
+        'AI_WEBHOOK_SECRET',
+        'JOBS_SCHEDULER_URL',
+        'JOBS_SIGNING_SECRET',
+        'JOBS_SYNC_KEY',
+        'ANALYTICS_URL',
+        'ANALYTICS_SITE_KEY',
+    ],
+};
+/** Names no stage holds, whatever the app. */
+const DENY_COMMON = [
+    'LETTERMINT_API_TOKEN',
+    'MAIL_ADMIN_*',
+    'MAIL_SMTP_*',
+    'OFFBOARDING_SERVICES',
+    'CHAT_ADMIN_INSTANCES',
+    'COOLIFY_*',
+    'CF_*',
+    'CLOUDFLARE_*',
+    'ZITADEL_*',
+    'TUNNEL_TOKEN',
+    'CUSTOMERS_DIRECTORY_CREDENTIAL',
+    'FOUNDRY_*',
+    'INTEGRATIONS_*',
+    'KEYSTORE_KEK_PREVIOUS',
+    'UPTIME_*',
+    'JOBS_ADMIN_TOKEN',
+    'CUSTOMER_GRANTS',
+    'DEPLOYMENT_CAPABILITIES',
+    'CHARGE_TOKEN',
+    'USAGE_TOKEN',
+    'RELEASE_TICK_TOKEN',
+    'ARCHON_SETUP_CODE',
+    'ARCHON_FIRST_OWNER_LINK',
+    'MAINTENANCE_BYPASS_TOKEN',
+];
+const DENY_BY_KIND = {
+    boule: ['JOBS_*', 'EDGE_*'],
+    agora: [
+        'AGORA_*_UPSTREAM',
+        'AGORA_MAIL_UPSTREAM',
+        'AGORA_FILES_UPSTREAM',
+        'AGORA_CHAT_UPSTREAM',
+        'AGORA_MATRIX_UPSTREAM',
+        'AGORA_MAS_UPSTREAM',
+        'AGORA_CALLS_UPSTREAM',
+        'MESSAGING_*',
+        'MAIL_PROJECT_ID',
+        'FILES_PROJECT_ID',
+        'AGORA_UPDATE_FEED_URL',
+    ],
+    archon: ['FILES_*', 'AI_*', 'JOBS_*', 'KEYS_*', 'EDGE_*'],
+    customer: ['EDGE_*', 'KEYS_*'],
+};
+/** Whether `name` is on the deny list of `kind`. */
+export function isDenied(kind, name) {
+    return matchesAny(DENY_COMMON, name) || matchesAny(DENY_BY_KIND[kind], name);
+}
+/** Whether `name` is on the allowlist of `kind`. Mail names are checked by A5 only. */
+export function isAllowed(kind, name) {
+    return matchesAny(STAGE_ALLOWLIST[kind], name);
+}
+/**
+ * Env that stage holds with the same value as production, on purpose. Each entry says why that cannot write
+ * to production. A name not here must differ from every production value.
+ */
+export const SHARED_WITH_PROD = {
+    AUTH_ISSUER: 'stage signs in through the same issuer by decision; it holds no ZITADEL management token, and an OIDC client cannot write users',
+    AUTH_ORGANIZATION_ID: 'same issuer organisation as AUTH_ISSUER; an id, not a credential',
+    CI_ORGANIZATION_ID: 'an id of the same issuer organisation; not a credential',
+    CUSTOMERS_ORGANISATION_ID: 'an id of the customers organisation in the same issuer; not a credential',
+    BOULE_ORG_NAME: 'a display name',
+    ARCHON_ORG_ID: 'the exact copy of the database holds the same organisation rows',
+    'AUTHZ_BOOTSTRAP_OPERATOR*': 'who may operate stage; an address, not a credential',
+    'AUTHZ_FIRST_OWNER*': 'who owns stage; an address, not a credential',
+    FILES_URL: 'the files service is shared; stage reaches it only with its own organisation and key',
+    AI_URL: 'the ai service is shared; stage reaches it only with its own organisation and key',
+    JOBS_SCHEDULER_URL: 'the jobs service is shared; stage reaches it only with its own project and signing secret',
+    ANALYTICS_URL: 'the analytics collector is shared; stage reports under its own site key',
+};
+/** Whether `name` may equal production's value. */
+export const isSharedWithProd = (name) => Object.keys(SHARED_WITH_PROD).some((p) => globMatches(p, name));
+const LIVE_MODE_KEY = /(^|[^a-z0-9])(sk|rk)_live_|^live_/;
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const URL_HOST = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/?#]*@)?([^/?#:]+)/i;
+const hostOf = (value) => URL_HOST.exec(value)?.[1]?.toLowerCase() ?? null;
+/**
+ * The violations of stage isolation, as `<code>:<name>`; empty when stage is isolated. Names only: an env
+ * name or a resource kind, never a value.
+ *  - A1 allowlist: `env_not_allowed`. A2 deny list: `env_denied`.
+ *  - A3 values: `value_shared` (a secret, url or id equals a production value), `shared_differs` (a name on
+ *    {@link SHARED_WITH_PROD} differs from production's), `live_mode_key`.
+ *  - A4 names: `resource_shared`, `host_is_prod_internal`.
+ *  - A5 mail: `mail_not_sink`, `mail_token`.
+ */
+export function assertStageIsolated(input) {
+    const { kind, prod, stage } = input;
+    const sink = input.sinkMail ?? {};
+    const out = new Set();
+    const prodByName = new Map();
+    for (const item of prod.env)
+        prodByName.set(item.name, item);
+    const prodHashes = new Set();
+    const prodRefs = new Set();
+    const prodHosts = new Set((prod.internalHosts ?? []).map((h) => h.toLowerCase()));
+    for (const item of prod.env) {
+        if (item.class === 'literal')
+            continue;
+        if (item.value) {
+            prodHashes.add(sha256(item.value));
+            const host = hostOf(item.value);
+            if (host)
+                prodHosts.add(host);
+        }
+        if (item.ref)
+            prodRefs.add(item.ref);
+    }
+    for (const item of stage.env) {
+        const { name } = item;
+        const isMail = MAIL_NAME.test(name);
+        if (isMail) {
+            if (item.value !== sink[name]) {
+                out.add(`${name === 'LETTERMINT_API_TOKEN' ? 'mail_token' : 'mail_not_sink'}:${name}`);
+            }
+        }
+        if (isDenied(kind, name))
+            out.add(`env_denied:${name}`);
+        else if (!isMail && !isAllowed(kind, name))
+            out.add(`env_not_allowed:${name}`);
+        if (item.value !== undefined && LIVE_MODE_KEY.test(item.value))
+            out.add(`live_mode_key:${name}`);
+        if (item.class === 'literal')
+            continue;
+        const shared = isSharedWithProd(name);
+        const counterpart = prodByName.get(name);
+        if (shared) {
+            const same = item.value !== undefined && counterpart?.value !== undefined
+                ? item.value === counterpart.value
+                : item.ref === counterpart?.ref;
+            if (counterpart && !same)
+                out.add(`shared_differs:${name}`);
+            continue;
+        }
+        if (item.value && prodHashes.has(sha256(item.value)))
+            out.add(`value_shared:${name}`);
+        if (item.ref && prodRefs.has(item.ref))
+            out.add(`value_shared:${name}`);
+        const host = item.value ? hostOf(item.value) : null;
+        if (host && prodHosts.has(host))
+            out.add(`host_is_prod_internal:${name}`);
+    }
+    const prodResources = new Set(Object.values(prod.resources));
+    for (const [resourceKind, value] of Object.entries(stage.resources)) {
+        if (prodResources.has(value))
+            out.add(`resource_shared:${resourceKind}`);
+    }
+    return [...out].sort();
+}
+/** The sha256 of the stage env name set plus the resource set: what `bg.<id>.stageisolation` records. */
+export function stageIsolationHash(stage) {
+    const names = stage.env.map((e) => e.name).sort();
+    const resources = Object.entries(stage.resources)
+        .map(([k, v]) => `${k}=${v}`)
+        .sort();
+    return sha256(JSON.stringify({ names, resources }));
+}

package/dist/plan/worker-app.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { WORKER_APP_HYPERDRIVE_BINDING, WORKER_APP_KEYS_SECRET, WORKER_APP_KEYS_URL_VAR, workerAppHostId, } from '../worker-app-config.js';
+import { WORKER_APP_HYPERDRIVE_BINDING, WORKER_APP_KEYS_SECRET, WORKER_APP_KEYS_URL_VAR, workerAppHasBuild, workerAppHostId, } from '../worker-app-config.js';
 import { entryAuthEnv } from './broker-entries.js';
 import { workerAppHostname } from './hostnames.js';
 import { appStepKey } from './platform-diff.js';
@@ -315,6 +315,8 @@ export function planWorkerApps(org, recordedIds, input) {
             description: `${at} is blocked, not planned: ${why}`,
             key,
         });
+        if (!workerAppHasBuild(app))
+            continue;
         if (!input.available) {
             block('the host supplies no WorkerAppPort');
             continue;

package/dist/refuse-org.d.ts

@@ -0,0 +1,7 @@
+import { type DeclaredOrg, type OrgRefusal } from './org.js';
+/**
+ * The first refusal of the whole-company validation a store write runs for
+ * hosting (every entry, its sign-in included), customers and the blue/green of Boule and Agora, or `null`. Locked
+ * names are the org's own; the platform's service names are not known here.
+ */
+export declare function refuseOrg(org: DeclaredOrg): OrgRefusal | null;

package/dist/refuse-org.js

@@ -0,0 +1,12 @@
+import { refuseBuiltinBlueGreen, refuseCustomers, refuseHosting, } from './org.js';
+import { hostingNames } from './plan/locked-hostnames.js';
+/**
+ * The first refusal of the whole-company validation a store write runs for
+ * hosting (every entry, its sign-in included), customers and the blue/green of Boule and Agora, or `null`. Locked
+ * names are the org's own; the platform's service names are not known here.
+ */
+export function refuseOrg(org) {
+    return (refuseHosting(org.hosting, hostingNames(org, [])) ??
+        refuseCustomers(org) ??
+        refuseBuiltinBlueGreen(org));
+}

package/dist/release/decide.d.ts

@@ -92,4 +92,9 @@ export declare function decide(input: {
     stepHoldMinutes?: number | undefined;
     now: Date;
     observation: Observation;
+    /**
+     * The app has no reporting health read (a static app). Only hard fails count: it never reports a relative
+     * fail, steps up by time, and the window closes after its minimum time.
+     */
+    hardOnly?: boolean;
 }): Decision;

package/dist/release/decide.js

@@ -150,7 +150,7 @@ export function decide(input) {
                 r = rollback(r, now, 'deploy timeout');
         }
         else {
-            const health = observation.health;
+            const health = input.hardOnly ? null : observation.health;
             const newC = health?.colors[rel.to] ?? { requests: 0, errors: 0 };
             const atWindow = r.window.kind === 'window' || r.window.kind === 'cap';
             let baseline = null;
@@ -162,6 +162,8 @@ export function decide(input) {
             let verdict;
             if (hard || hardRate)
                 verdict = 'hard_fail';
+            else if (input.hardOnly)
+                verdict = 'pass';
             else if (!health || baseline === null || newC.requests < RELATIVE_MIN_REQUESTS)
                 verdict = 'inconclusive';
             else
@@ -200,11 +202,13 @@ export function decide(input) {
                     }
                     else {
                         const required = Math.max(1, Math.ceil(health?.daily.requestsPerDay ?? 0));
-                        const closable = health !== null &&
-                            baseline !== null &&
-                            elapsed >= WINDOW_MIN_HOURS * HOUR &&
-                            newC.requests >= required &&
-                            rate(newC) <= baseline + ERROR_RATE_MARGIN;
+                        const closable = input.hardOnly
+                            ? elapsed >= WINDOW_MIN_HOURS * HOUR
+                            : health !== null &&
+                                baseline !== null &&
+                                elapsed >= WINDOW_MIN_HOURS * HOUR &&
+                                newC.requests >= required &&
+                                rate(newC) <= baseline + ERROR_RATE_MARGIN;
                         if (closable) {
                             out.effects.push({ kind: 'stop', color: rel.from });
                             r = { ...r, window: { kind: 'passed', at: now.toISOString() }, release: null };

package/dist/release/health.d.ts

@@ -39,10 +39,15 @@ export declare function readReleaseHealth(input: {
     headers?: Record<string, string>;
     fetchImpl?: typeof fetch;
 }): Promise<HealthRead | null>;
-/** An HTTP check of the color's health path on its own address. */
+/**
+ * An HTTP check of the color's health path on its own address. A redirect is a failure: it is how a login
+ * wall (Cloudflare Access) answers a machine. With `expectJson` the body must also parse as JSON, so a login page served with 200 is not read as a healthy color.
+ */
 export declare function checkColorAddress(input: {
     address: string;
     healthPath: string | null;
     headers?: Record<string, string>;
+    /** True for an app whose health path answers JSON; false for a static app's `/`. */
+    expectJson?: boolean;
     fetchImpl?: typeof fetch;
 }): Promise<'ok' | 'failed'>;

package/dist/release/health.js

@@ -45,14 +45,22 @@ export async function readReleaseHealth(input) {
         return null;
     }
 }
-/** An HTTP check of the color's health path on its own address. */
+/**
+ * An HTTP check of the color's health path on its own address. A redirect is a failure: it is how a login
+ * wall (Cloudflare Access) answers a machine. With `expectJson` the body must also parse as JSON, so a login page served with 200 is not read as a healthy color.
+ */
 export async function checkColorAddress(input) {
     try {
         const res = await (input.fetchImpl ?? fetch)(new URL(input.healthPath ?? '/', input.address), {
             ...(input.headers ? { headers: input.headers } : {}),
+            redirect: 'manual',
             signal: AbortSignal.timeout(ADDRESS_CHECK_TIMEOUT_MS),
         });
-        return res.ok ? 'ok' : 'failed';
+        if (!res.ok)
+            return 'failed';
+        if (input.expectJson)
+            await res.json();
+        return 'ok';
     }
     catch {
         // Unreachable counts as a failed check.

package/dist/release/run.d.ts

@@ -37,4 +37,6 @@ export declare function runRelease(input: {
     };
     now: Date;
     deps: ReleaseDeps;
+    /** No reporting health read: only hard fails count (see `decide`). */
+    hardOnly?: boolean;
 }): Promise<ReleaseRunResult>;

package/dist/release/run.js

@@ -16,7 +16,7 @@ export async function runRelease(input) {
     const actions = open.map((r) => r.action);
     const range = healthRange(recorded, now);
     const target = recorded.release?.to ?? null;
-    const health = range ? await deps.readHealth(range) : null;
+    const health = range && !input.hardOnly ? await deps.readHealth(range) : null;
     const seen = target
         ? await deps.observeColor(target)
         : { status: 'other', address: 'unchecked' };
@@ -27,6 +27,7 @@ export async function runRelease(input) {
         stepHoldMinutes: input.entry.stepHoldMinutes,
         now,
         observation: { health, ...seen },
+        ...(input.hardOnly ? { hardOnly: true } : {}),
     });
     for (const effect of decision.effects)
         await deps.effect(effect);

package/dist/requested-changes.d.ts

@@ -1,4 +1,5 @@
-import { type DeclaredOrg, type MailMode, type OrgId } from './org.js';
+import type { BuildJson } from './build-json.js';
+import { type CustomersConfig, type DeclaredOrg, type HostingEntry, type MailMode, type OrgId } from './org.js';
 import type { PlanDetail } from './plan/diff.js';
 /**
  * The whitelist of `DeclaredOrg` fields a company's own Boule can request a
@@ -15,7 +16,7 @@ import type { PlanDetail } from './plan/diff.js';
  * 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' | 'customers' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier';
+export type RequestableField = 'calls' | 'customers' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier' | 'app' | 'build';
 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 {
@@ -52,12 +53,34 @@ export interface MailTierChange {
     field: 'mailTier';
     mode: MailMode;
 }
+/**
+ * Put or remove one hosting entry of the company's own app (`org.ts`'s `HostingEntry`).
+ * `before` and `after` are the entry as the requester saw it and as it should be (null when absent).
+ * `customers` is the switches after the change when the request changes them, else null.
+ * Archon validates the whole company; {@link classifyChange} does not look at the org for this kind.
+ */
+export interface AppChange {
+    field: 'app';
+    key: string;
+    op: 'put' | 'remove';
+    before: HostingEntry | null;
+    after: HostingEntry | null;
+    customers: CustomersConfig | null;
+}
+/** Deploy one release of the company's app from its `build.json` (`build-json.ts`). */
+export interface BuildChange {
+    field: 'build';
+    key: string;
+    repo: string;
+    release: string;
+    build: BuildJson;
+}
 /**
  * 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 | CustomersChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange;
+export type RequestedChangeValue = CallsChange | CustomersChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange | AppChange | BuildChange;
 /**
  * `auto`: nothing further is required -- archon may carry the request
  * straight into a plan and apply it. `approval`: a human must approve the
@@ -72,7 +95,21 @@ export type ChangeClassification = 'auto' | 'approval';
  * 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';
+export type RequestedChangeState = 'auto' | 'needs_approval' | 'approved' | 'rejected' | 'applied' | 'applying' | 'failed';
+/** Why an `app` or `build` request is `failed`. */
+export type FailureCode = 'replaced' | 'refused' | 'busy' | 'timed_out' | 'apply_error';
+/** Who asked: a person in Boule, or a release build. `requestedBy` keeps the raw principal id for audit. */
+export type RequestedBy = {
+    via: 'boule';
+    person: {
+        id: string;
+        name: string;
+    };
+} | {
+    via: 'build';
+    repo: string;
+    release: string;
+};
 /**
  * One company-requested change to its own declared org, as stored --
  * `migrations/0017_requested_changes.sql`'s `foundry_requested_changes`
@@ -85,6 +122,15 @@ export interface RequestedChange {
     requestedBy: string;
     createdAt: string;
     state: RequestedChangeState;
+    /** Null for rows made before `app` and `build` requests. */
+    requester: RequestedBy | null;
+    idempotencyKey: string | null;
+    reason: {
+        code: FailureCode;
+        message: string;
+        replacedBy?: number;
+    } | null;
+    updatedAt: string;
 }
 /**
  * Thrown by {@link classifyChange} (and by the requested-change store's

package/dist/requested-changes.js

@@ -1,4 +1,4 @@
-import { validateCustomers } from './org.js';
+import { validateCustomers, } from './org.js';
 export const REQUESTABLE_FIELDS = [
     'calls',
     'customers',
@@ -6,6 +6,8 @@ export const REQUESTABLE_FIELDS = [
     'aiLimit',
     'domain',
     'mailTier',
+    'app',
+    'build',
 ];
 /**
  * Thrown by {@link classifyChange} (and by the requested-change store's
@@ -42,6 +44,9 @@ function applyRequestedChange(org, change) {
             return { ...org, domain: change.domain };
         case 'mailTier':
             return { ...org, mail: { ...org.mail, mode: change.mode } };
+        case 'app':
+        case 'build':
+            return org;
     }
 }
 /**
@@ -115,6 +120,9 @@ export function classifyChange(org, change, plan) {
     if (!REQUESTABLE_FIELDS.includes(change.field)) {
         throw new RequestedChangeError(`'${change.field}' is not a requestable field`);
     }
+    // Archon validates the whole company for these; nothing waits for approval.
+    if (change.field === 'app' || change.field === 'build')
+        return 'auto';
     if (change.field === 'customers') {
         validateCustomersChange(change);
         // The org after the change must still pass the rule apply checks, for example open registration

package/dist/store/postgres.d.ts

@@ -1,4 +1,5 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { OrgRefusal, OrgRefusalCode } from '../org.js';
 import { type ReleaseStore } from '../release/state.js';
 import { type AppliedVersionsStore, type DeclaredOrgStore, type PlatformStore, type RequestedChangeStore } from '../store.js';
 /**
@@ -38,7 +39,10 @@ export declare function uniqueViolationConstraint(error: unknown): string | unde
  * is that throw.
  */
 export declare class DeclaredOrgError extends Error {
-    constructor(message: string);
+    /** Set when a hosting or customers validator refused the write: which rule, and where in the org. */
+    readonly code?: OrgRefusalCode;
+    readonly path?: string;
+    constructor(message: string, refusal?: Pick<OrgRefusal, 'code' | 'path'>);
 }
 /**
  * `DeclaredOrgStore` (`../store.ts`) on Postgres, for #18: create, read and