@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/enums.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-// Space operation-lifecycle axis (internal-docs/platform.md "Space"): exactly
-// these five. Serving (disabled) and deletion (deletedAt) are separate axes —
-// a disabled space can still be updating. There is no `moving`: a space IS a
-// site, so ownership changes commit in place and nothing relocates.
+// Space operation-lifecycle axis (the platform spec "Space"). Serving
+// (disabled) and deletion (deletedAt) are separate axes, so a disabled space
+// can still be updating. There is no `moving`: a space IS a site, so ownership
+// changes commit in place.
 export const spaceStatusValues = [
     "provisioning",
     "active",
@@ -11,7 +11,7 @@ export const spaceStatusValues = [
     "failed",
 ];
 export const spaceStatus = z.enum(spaceStatusValues);
-// Serving-axis disable reasons (internal-docs/platform.md "Space"). Confirmed
+// Serving-axis disable reasons (the platform spec "Space"). Confirmed
 // scan takedowns use `abuse_takedown`; infected state and claim invalidation
 // are explicit enforcement effects, not reason metadata.
 export const spaceDisabledReasonCodeValues = [
@@ -19,18 +19,16 @@ export const spaceDisabledReasonCodeValues = [
     "abuse_takedown",
     "tenant_suspended",
     "site_suspended",
-    // Space-key author delete, phase one: the holder of an unclaimed space's key
-    // took the site dark. The key survives, so the same key can restore (or
-    // claim) until the claim window expires; expiry then hard-deletes as usual.
+    // The owner, or the holder of an unclaimed space's key, deleted the Space.
+    // Serving stops while data remains retained for deliberate cleanup. An
+    // unclaimed key survives so it can restore or claim during its claim window.
     "author_removed",
 ];
 export const spaceDisabledReasonCode = z.enum(spaceDisabledReasonCodeValues);
-// SpaceTransfer status machine (internal-docs/platform.md "Transfer
-// semantics"), stored directly — there is no separate DB vocabulary. A
-// transfer is a request that the receiving side accepts; accepting moves
-// ownership in one database transaction, so there is no intermediate moving
-// state and no `failed` state. Withdraw (from-side) and decline (to-side)
-// both land on `canceled`.
+// SpaceTransfer status machine (the platform spec "Transfer semantics"),
+// stored directly with no separate DB vocabulary. Accepting moves ownership in
+// one database transaction, so there is no intermediate moving state and no
+// `failed` state. Withdraw and decline both land on `canceled`.
 export const spaceTransferStatusValues = [
     "pending_confirmation",
     "completed",
@@ -38,14 +36,21 @@ export const spaceTransferStatusValues = [
     "expired",
 ];
 export const spaceTransferStatus = z.enum(spaceTransferStatusValues);
-// A tenant is the platform-account boundary that owns every resource (internal-docs/platform.md
-// "Tenant -> Site -> Space"), Stripe-style. `main` is the single well-known
-// Stattic account (`ten_main`) all self-serve teams/users live under;
-// `platform` and `partner` are host integrations with their own user
-// directories and/or external customers; `internal` is for Stattic-operated
-// infrastructure tenants.
-export const tenantKindValues = ["main", "platform", "partner", "internal"];
+// A tenant is the platform-account boundary that owns every resource,
+// Stripe-style. `main` is the single well-known account (`ten_main`) all
+// self-serve teams/users live under; `partner` is a host integration with
+// its own user directory and/or external customers; `internal` is for
+// Spacefast-operated infrastructure tenants.
+export const tenantKindValues = ["main", "partner", "internal"];
 export const tenantKind = z.enum(tenantKindValues);
+// A tenant's mode: `live` is a real partner account provisioning real sites;
+// `test` is its linked sandbox twin — same partner API, isolated data,
+// simulated provisioning, no real wp.cloud/DNS/email. Modeled as a SEPARATE
+// tenant row linked back to its live parent via `liveTenantId`, never a column
+// filtered into every resource query (partner-operations spec §1): isolation
+// holds by construction because every resource is already `tenant_id`-scoped.
+export const tenantModeValues = ["live", "test"];
+export const tenantMode = z.enum(tenantModeValues);
 // `past_due` is the billing-grace state: mutations are rejected immediately
 // (`tenant_past_due`) but serving continues until `servingGraceUntil`, after
 // which the tenant transitions to `suspended` and goes dark.
@@ -55,40 +60,22 @@ export const tenantStatus = z.enum(tenantStatusValues);
 // (operator-only resource, `pvc_` prefix).
 export const providerClientStatusValues = ["active", "disabled"];
 export const providerClientStatus = z.enum(providerClientStatusValues);
-// The only site shape there is. Kept as a named vocabulary because the sites
-// table spells it as an enum column; a dead-code sweep removed it while that
-// column still referenced it.
-export const siteKindValues = ["static_runtime"];
-export const siteKind = z.enum(siteKindValues);
-// Whether settings and access default to the site or to each space. Same story
-// as the two vocabularies around it: a dead-code sweep took it while the
-// `sites` table's own column still named it.
-export const siteIsolationValues = ["site", "space"];
-export const siteIsolation = z.enum(siteIsolationValues);
-// Site lifecycle. A dead-code sweep removed this vocabulary while two live
-// consumers still needed it: the `sites` table's own status column and the
-// superadmin provider-site search result. `ready_pool` is a pre-provisioned
-// warm site waiting to be claimed — load-bearing now that every space draws
-// its own site from the pool.
-export const siteStatusValues = [
-    "ready_pool",
-    "active",
+// Warm-pool inventory (`site_pool`): provider sites provisioned ahead of
+// demand, with no owner yet. These statuses are the whole lifecycle a row has
+// before a space adopts it and the row is deleted. `retired` holds a legacy
+// migration source box that is never automatically promoted for deletion.
+// `cleanup_pending` is the explicit, unclaimable queue for Superadmin review.
+// This is a varchar type union, not a PostgreSQL enum, so adding a value needs
+// no database migration.
+export const poolSiteStatusValues = [
     "provisioning",
+    "ready_pool",
     "degraded",
-    "suspended",
-    "deleted",
+    "retired",
+    "cleanup_pending",
 ];
-export const siteStatus = z.enum(siteStatusValues);
-// Warm-pool inventory (`site_pool`): provider sites provisioned ahead of
-// demand, with no owner yet. A space IS a site, so these statuses are the
-// whole lifecycle a row can have before a space adopts it and the row is
-// deleted — `active`/`suspended`/`deleted` were live-space states and now live
-// on the space's own axes. `retired` holds a drained space=site migration
-// source box: not adoptable, not reapable, kept permanently — migration
-// tooling never deletes a wp.cloud site (owner ruling 2026-08-11).
-export const poolSiteStatusValues = ["provisioning", "ready_pool", "degraded", "retired"];
 export const poolSiteStatus = z.enum(poolSiteStatusValues);
-// PublishSource.kind (internal-docs/platform.md "PublishSource"): the single
+// PublishSource.kind (the platform spec "PublishSource"): the single
 // provenance axis for how a version came to exist. `variable_update` and
 // `config_update` versions are minted by cascades/config regeneration.
 export const publishSourceKindValues = [
@@ -105,7 +92,7 @@ export const publishSourceKindValues = [
 ];
 export const publishSourceKind = z.enum(publishSourceKindValues);
 export const versionStatusValues = [
-    // Spec state machine (internal-docs/platform.md "Upload Contract"):
+    // Spec state machine (the platform spec "Upload Contract"):
     // created -> uploading -> uploaded -> finalizing -> ready, with terminal
     // failed/canceled/expired. Build runs are tracked on the Build resource;
     // a building version stays `created` until upload starts.
@@ -126,14 +113,14 @@ export const versionStatusValues = [
 export const versionStatus = z.enum(versionStatusValues);
 export const gitProviderValues = ["github", "gitlab", "bitbucket", "generic"];
 export const gitProvider = z.enum(gitProviderValues);
-// Pre-ready, non-terminal statuses: a version in one of these is in flight.
+// Pre-ready, non-terminal statuses.
 export const VERSION_IN_FLIGHT_STATUSES = [
     "created",
     "uploading",
     "uploaded",
     "finalizing",
 ];
-// Build resource statuses (internal-docs/platform.md "Build", `bld_`).
+// Build resource statuses (the platform spec "Build", `bld_`).
 export const buildStatusValues = [
     "waiting_for_source",
     "uploading_source",
@@ -145,10 +132,34 @@ export const buildStatusValues = [
     "skipped",
 ];
 export const buildStatus = z.enum(buildStatusValues);
+/**
+ * The one authoritative "this build can still change on its own" set. Poll
+ * cadences, cancelability, activity checks and webhook re-enqueue gates all
+ * derive from it — never restate it.
+ */
+export const BUILD_IN_FLIGHT_STATUSES = [
+    "waiting_for_source",
+    "uploading_source",
+    "queued",
+    "running",
+];
+const buildInFlightStatusSet = new Set(BUILD_IN_FLIGHT_STATUSES);
+/**
+ * Its complement: a build that has settled and will never move again.
+ * `skipped` is terminal — a build the runner decided not to run at all.
+ */
+export const BUILD_TERMINAL_STATUSES = buildStatusValues.filter((status) => !buildInFlightStatusSet.has(status));
+const buildTerminalStatusSet = new Set(BUILD_TERMINAL_STATUSES);
+export function buildIsInFlight(status) {
+    return buildInFlightStatusSet.has(status);
+}
+export function buildIsTerminal(status) {
+    return buildTerminalStatusSet.has(status);
+}
 export const diagnosticSeverity = z.enum(["info", "warning", "error"]);
-// Upstream system a Diagnostic originated from (internal-docs/platform.md L1621). Absent when
-// the diagnostic is Stattic's own (validation, routing compile, upload policy, ...).
-export const diagnosticProvider = z.enum(["wpcloud", "dns", "registrar", "runtime"]);
+// Upstream system a Diagnostic originated from. Absent when the diagnostic is
+// Stattic's own (validation, routing compile, upload policy, ...).
+export const diagnosticProvider = z.enum(["infra", "dns", "registrar", "runtime"]);
 // Internal domain DB-column vocabularies (consumed by the control-plane schema;
 // never part of the public Domain contract, which lives in contracts/domains.ts).
 export const domainOwnershipTypeValues = [
@@ -200,9 +211,6 @@ export const safetyCategoryValues = [
 export const safetyCategory = z.enum(safetyCategoryValues);
 // Why a review item was closed (or a space taken down): the operator's verdict
 // in one word, so enforcement quality is measurable without parsing notes.
-// Confirmed-* reasons say the detection was right; the tail says it wasn't
-// (false_positive, test_detection) or the item never needed its own verdict
-// (duplicate, insufficient_evidence, other).
 export const safetyResolutionReasonValues = [
     "malware_confirmed",
     "phishing_confirmed",
@@ -216,7 +224,6 @@ export const safetyResolutionReasonValues = [
     "other",
 ];
 export const safetyResolutionReason = z.enum(safetyResolutionReasonValues);
-// 1 = suspicious, 2 = low, 3 = medium, 4 = high, 5 = critical.
 export const SAFETY_SEVERITY = {
     suspicious: 1,
     low: 2,