@spacefast/common 0.0.2

package/dist/contracts/domains.js

@@ -0,0 +1,1435 @@
+import { z } from "zod";
+import { AnyObjectSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, DnsInstructionSchema, mutationEnvelope, requiredActionsSchema, } from "./common.js";
+import { PrincipalRefSchema } from "./resources.js";
+// ---------------------------------------------------------------------------
+// Domain resource (internal-docs/platform.md L2387-2431). Pure inventory: a
+// canonical name owned by a tenant-local principal, plus the registrar/dns
+// facets where they apply and the verification read-model. Routing intent
+// lives on DomainBinding, provider assignment on SiteDomainAssignment.
+// ---------------------------------------------------------------------------
+// Registration (who you pay) facet — present only on apex records.
+export const domainRegistrarFacetSchema = z.object({
+    mode: z
+        .enum(["stattic", "external"])
+        .describe("Whether Spacefast manages this registration or an external registrar holds it."),
+    provider: z
+        .string()
+        .optional()
+        .describe('Wrapped registrar provider key when mode is "stattic", e.g. "wpcom".'),
+    status: z
+        .enum(["active", "pending_purchase", "pending_transfer_in", "expiring", "expired", "locked"])
+        .optional()
+        .describe("Registration lifecycle status; `expiring` is derived from the expiry date."),
+    expiresAt: z.string().datetime().optional().describe("When the registration expires."),
+    redemptionEndsAt: z
+        .string()
+        .datetime()
+        .optional()
+        .describe("End of the provider grace/redemption window after expiry."),
+    autoRenew: z.boolean().optional().describe("Whether the registration renews automatically."),
+    transferLock: z
+        .boolean()
+        .optional()
+        .describe("Whether outbound transfers are locked at the registrar."),
+});
+// DNS hosting (who answers queries) facet — present only on zone-cut-owning
+// records: the apex, or a hostname with verified NS delegation.
+export const domainDnsFacetSchema = z.object({
+    mode: z
+        .enum(["stattic", "external"])
+        .describe("Whether Spacefast hosts the authoritative zone or an external DNS provider does."),
+    managementKind: z
+        .enum(["unmanaged_external", "connected_provider", "registrar_dns", "stattic_nameservers"])
+        .optional()
+        .describe("Derived DNS management state. Additive; `mode` remains the v1 compatibility field."),
+    dnsMode: z
+        .enum(["authoritative", "adapter"])
+        .optional()
+        .describe("Hybrid DNS mode derived from `managementKind`: authoritative (Spacefast hosts the zone) or adapter (records managed/observed on the user's existing host). Additive read-model label."),
+    provider: z
+        .string()
+        .optional()
+        .describe('Wrapped DNS provider key when mode is "stattic", e.g. "route53" or "wpcom".'),
+    assignedNameservers: z
+        .array(z.string())
+        .optional()
+        .describe('Managed-zone delegation set the registrar should point at (mode "stattic").'),
+    observedNameservers: z
+        .array(z.string())
+        .optional()
+        .describe("Nameservers currently observed in public DNS; polled in both modes."),
+    snapshot: z
+        .object({
+        freshness: z.enum(["fresh", "stale", "refresh_running", "refresh_failed", "never_fetched"]),
+        lastFetchedAt: z.string().datetime().nullable(),
+        version: z.string().nullable(),
+    })
+        .optional()
+        .describe("Connected-provider record snapshot freshness for portfolio lists."),
+    lastOperation: z
+        .object({
+        id: z.string(),
+        kind: z.string(),
+        status: z.enum(["queued", "running", "observing", "succeeded", "failed", "canceled"]),
+        updatedAt: z.string().datetime(),
+    })
+        .optional()
+        .describe("Latest DNS operation summary for portfolio and recovery surfaces."),
+});
+export const domainVerificationSchema = z.object({
+    status: z
+        .enum(["not_required", "pending", "verified", "failed"])
+        .describe("Current proof of DNS control. `failed` alone never tears down compiled serving state."),
+    requiredRecords: z
+        .array(DnsInstructionSchema)
+        .optional()
+        .describe("DNS records the caller must create to prove control and route traffic."),
+    lastCheckedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .optional()
+        .describe("When observed DNS was last polled."),
+    lastVerifiedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .optional()
+        .describe("Last time this domain proved DNS control."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .optional()
+        .describe("Structured verification diagnostics with stable codes."),
+});
+export const domainHintSchema = z.object({
+    id: z.string(),
+    code: z.string(),
+    severity: z.enum(["info", "warning", "error"]),
+    painLevel: z.enum(["info", "needs_attention", "blocked", "broken", "dangerous"]),
+    subjectFacet: z.enum([
+        "dns_zone",
+        "registrar",
+        "hosting_binding",
+        "email",
+        "forwarding",
+        "provider_connection",
+    ]),
+    subjectRef: z.object({
+        domainId: z.string(),
+        zoneId: z.string().optional(),
+        bindingId: z.string().optional(),
+        connectionId: z.string().optional(),
+    }),
+    owner: z.enum(["stattic", "user", "registrar", "provider", "support", "waiting"]),
+    status: z.enum(["active", "waiting", "running", "resolved", "dismissed"]),
+    summary: z.string(),
+    description: z.string(),
+    impact: z.string(),
+    evidence: z.array(z.object({
+        label: z.string(),
+        value: z.string(),
+        observedAt: z.string().datetime().optional(),
+        source: z.enum([
+            "provider_api",
+            "public_dns",
+            "registrar",
+            "stattic_db",
+            "operation",
+            "user_input",
+        ]),
+    })),
+    suggestions: z.array(z.object({
+        label: z.string(),
+        description: z.string(),
+        action: z.discriminatedUnion("type", [
+            z.object({ type: z.literal("open_pending_action"), actionId: z.string() }),
+            z.object({ type: z.literal("run_action"), actionKind: z.string() }),
+            z.object({ type: z.literal("copy_records"), records: z.array(DnsInstructionSchema) }),
+            z.object({ type: z.literal("refresh"), target: z.string() }),
+            z.object({ type: z.literal("reconnect_provider"), connectionId: z.string() }),
+            z.object({ type: z.literal("open_external"), url: z.string().url() }),
+            z.object({ type: z.literal("wait"), retryAfter: z.string().datetime() }),
+        ]),
+        primary: z.boolean().optional(),
+        destructive: z.boolean().optional(),
+    })),
+    docsUrl: z.string().url().optional(),
+    operationId: z.string().optional(),
+    requestId: z.string().optional(),
+    providerRequestId: z.string().optional(),
+    expiresAt: z.string().datetime().optional(),
+});
+export const DomainSchema = z.object({
+    id: z.string().describe("Domain inventory record id (`dom_...`)."),
+    tenantId: z.string().describe("Tenant that owns this record (`ten_...`)."),
+    principal: PrincipalRefSchema.describe("Tenant-local principal that owns this domain: a team in the main tenant, an external customer in platform integrations."),
+    name: z
+        .string()
+        .describe("Canonical lowercase ASCII A-labels (IDNA2008/punycode), no trailing dot, no wildcard label."),
+    unicodeName: z
+        .string()
+        .optional()
+        .describe("Read-only U-label form, present only when it differs from `name`."),
+    kind: z
+        .enum(["hostname", "apex"])
+        .describe("Derived, never create input: `apex` iff `name` equals `derivedGroup`."),
+    wildcardEnabled: z
+        .boolean()
+        .describe("Whether wildcard bindings may be created under this record."),
+    derivedGroup: z
+        .string()
+        .describe("PSL registrable domain of `name`; server-computed, never client-supplied."),
+    registrar: domainRegistrarFacetSchema
+        .optional()
+        .describe("Registration facet; present only on apex records."),
+    dns: domainDnsFacetSchema
+        .optional()
+        .describe("DNS hosting facet; present only on zone-cut-owning records."),
+    verification: domainVerificationSchema.describe("Proof-of-control read model."),
+    hints: z
+        .array(domainHintSchema)
+        .optional()
+        .describe("Projected domain hints derived from diagnostics, actions, observations, and operations."),
+    createdAt: z.string().datetime().describe("When the record was created."),
+    updatedAt: z.string().datetime().describe("When the record last changed."),
+});
+export const domainListQuerySchema = cursorListQuerySchema.extend({
+    teamId: z.string().min(1).optional().describe("Filter to domains owned by one team."),
+});
+export const domainListResponseSchema = z.object({
+    data: z.array(DomainSchema),
+    pagination: CursorPaginationSchema,
+});
+export const spaceCustomDomainSchema = DomainSchema.extend({
+    source: z.literal("custom").describe("Custom domain inventory row."),
+    managed: z.literal(false),
+    deletable: z.literal(true),
+    assignable: z.literal(true),
+    primary: z.boolean().describe("Whether this custom domain binding is the space's primary URL."),
+});
+export const spaceManagedDomainSchema = z.object({
+    id: z.string().describe("Stable managed row id derived from the default hostname row."),
+    source: z.literal("managed_view_fast").describe("System-managed view.fast hostname row."),
+    managed: z.literal(true),
+    deletable: z.literal(false),
+    assignable: z.literal(false),
+    primary: z.boolean().describe("True when no custom primary domain overrides the managed URL."),
+    name: z.string().describe("Managed view.fast hostname."),
+    unicodeName: z.string().optional(),
+    kind: z.literal("hostname"),
+    publicName: z.string().describe("Left-hand public project label for the managed hostname."),
+    verification: domainVerificationSchema.extend({
+        status: z.literal("not_required"),
+    }),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const spaceDomainSchema = z.discriminatedUnion("source", [
+    spaceManagedDomainSchema,
+    spaceCustomDomainSchema,
+]);
+export const spaceDomainListResponseSchema = z.object({
+    data: z.array(spaceDomainSchema),
+    pagination: CursorPaginationSchema,
+});
+export const teamManagedDomainSchema = spaceManagedDomainSchema.extend({
+    spaceId: z.string().describe("Space that owns this managed hostname."),
+    spaceSlug: z.string().describe("Current project slug for the owning space."),
+    spaceTitle: z.string().describe("Current title for the owning space."),
+});
+export const teamManagedDomainListResponseSchema = z.object({
+    data: z.array(teamManagedDomainSchema),
+    pagination: CursorPaginationSchema,
+});
+export const domainCreateRequestSchema = z.object({
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(253)
+        .describe("Apex or concrete hostname to add to inventory; canonicalized server-side."),
+    teamId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Owning team. Defaults to the active team for sessions and the key's team."),
+});
+// Facet modes are never PATCHable: `dns.mode` changes only via POST /dns and
+// `registrar.mode` only via POST /registration. The PATCHable surface is
+// `wildcardEnabled` (and future metadata) only.
+export const domainPatchSchema = z
+    .object({
+    wildcardEnabled: z
+        .boolean()
+        .optional()
+        .describe("Allow wildcard bindings under this domain record."),
+})
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one domain field is required.",
+});
+// ---------------------------------------------------------------------------
+// DomainBinding (internal-docs/platform.md L2466-2498): a discriminated union
+// on `mode` — serve a space, redirect, or proxy an upstream.
+// ---------------------------------------------------------------------------
+// DomainBindingDiagnostic (L2508-2510): the shared Diagnostic shape plus a
+// binding-specific suggested `action`.
+export const domainBindingDiagnosticSchema = baseDiagnosticSchema.extend({
+    action: z
+        .enum(["add_dns", "wait", "verify", "confirm_move", "remove_conflict", "contact_support"])
+        .optional()
+        .describe("Suggested next step to resolve this binding diagnostic."),
+});
+export const domainBindingConflictSchema = z.object({
+    id: z.string().describe("Stable conflict id, passed back in activation `confirm`."),
+    scope: z
+        .enum(["same_space", "same_principal", "same_tenant", "external"])
+        .describe("Who holds the overlapping claim, relative to the caller."),
+    hostname: z.string().describe("Hostname both claims target."),
+    pathPrefix: z.string().optional().describe("Conflicting path scope, when path-based."),
+    existingBindingId: z.string().optional().describe("The incumbent binding, when visible."),
+    resolution: z
+        .enum([
+        "activate_moves_existing",
+        "choose_different_path",
+        "verify_to_takeover",
+        "cannot_resolve",
+    ])
+        .optional()
+        .describe("How this conflict can be resolved."),
+});
+export const domainBindingStatusSchema = z
+    .enum(["draft", "pending", "blocked", "activating", "active", "failed", "deleted"])
+    .describe("Binding lifecycle status; the binding is the pollable resource for activation.");
+const domainBindingBaseFields = {
+    id: z.string().describe("Domain binding id (`dbn_...`)."),
+    tenantId: z.string().describe("Tenant the binding belongs to (`ten_...`)."),
+    domainId: z.string().describe("Domain inventory record this binding routes (`dom_...`)."),
+    siteDomainAssignmentId: z
+        .string()
+        .nullable()
+        .describe("Provider assignment serving this hostname, once linked (`sda_...`)."),
+    hostname: z.string().describe("Hostname this binding claims (copied from the domain)."),
+    pathPrefix: z
+        .string()
+        .nullable()
+        .describe("Path scope like `/docs`; null claims the whole host. More specific paths win."),
+    wildcard: z
+        .boolean()
+        .describe("Whether this binding captures subdomains (requires domain wildcardEnabled)."),
+    status: domainBindingStatusSchema,
+    diagnostics: z
+        .array(domainBindingDiagnosticSchema)
+        .describe("Structured diagnostics with stable codes and suggested actions."),
+    requiredActions: requiredActionsSchema,
+    conflicts: z
+        .array(domainBindingConflictSchema)
+        .describe("Unresolved overlapping claims; conflicts block instead of dead-ending."),
+    providerState: AnyObjectSchema.describe("Raw provider-side state, for diagnostics only."),
+    createdAt: z.string().datetime().describe("When the binding was created."),
+    updatedAt: z.string().datetime().describe("When the binding last changed."),
+};
+export const domainBindingRedirectTargetSchema = z
+    .union([
+    z.object({
+        url: z.string().url().describe("Absolute URL to redirect to."),
+    }),
+    z.object({
+        spaceId: z.string().min(1).describe("Space to redirect to (`spc_...`)."),
+        path: z.string().max(255).optional().describe("Path on the target space."),
+    }),
+])
+    .describe("Redirect destination: an absolute URL, or a space (optionally with a path).");
+export const domainBindingRedirectStatusSchema = z
+    .union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)])
+    .describe("HTTP redirect status; defaults to 308.");
+export const domainBindingSchema = z.discriminatedUnion("mode", [
+    z.object({
+        ...domainBindingBaseFields,
+        mode: z.literal("serve").describe("Serve a space's content on this hostname/path."),
+        spaceId: z.string().describe("Space served by this binding (`spc_...`)."),
+        channel: z.string().describe('Channel served on this hostname; defaults to "live".'),
+        primary: z
+            .boolean()
+            .describe("One primary hostname per space; the primary binding feeds `liveUrl`."),
+    }),
+    z.object({
+        ...domainBindingBaseFields,
+        mode: z.literal("redirect").describe("Redirect requests to a URL or another space."),
+        to: domainBindingRedirectTargetSchema,
+        redirectStatus: domainBindingRedirectStatusSchema,
+    }),
+    z.object({
+        ...domainBindingBaseFields,
+        mode: z.literal("proxy").describe("Proxy requests to an external upstream."),
+        upstream: z.object({
+            url: z.string().url().describe("Absolute upstream URL requests are proxied to."),
+        }),
+    }),
+]);
+function requireBindingModeFields(value, ctx) {
+    if (value.mode === "redirect" && value.to === undefined) {
+        ctx.addIssue({ code: "custom", path: ["to"], message: "Redirect bindings require `to`." });
+    }
+    if (value.mode === "proxy" && value.upstream === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["upstream"],
+            message: "Proxy bindings require `upstream`.",
+        });
+    }
+    if (value.mode !== "redirect" && (value.to !== undefined || value.redirectStatus !== undefined)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["to"],
+            message: "`to`/`redirectStatus` apply only to redirect bindings.",
+        });
+    }
+    if (value.mode !== "proxy" && value.upstream !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["upstream"],
+            message: "`upstream` applies only to proxy bindings.",
+        });
+    }
+    if (value.mode === "serve" || value.mode === undefined) {
+        return;
+    }
+    if (value.channel !== undefined || value.primary !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["channel"],
+            message: "`channel`/`primary` apply only to serve bindings.",
+        });
+    }
+}
+// One POST end to end (charter D5): pass `hostname` and the Domain inventory
+// record is auto-created for the space's principal — no separate create-domain
+// step. Pass `domainId` to bind an existing inventory record instead.
+export const domainBindingCreateSchema = z
+    .object({
+    domainId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Existing domain inventory record to bind (`dom_...`)."),
+    hostname: z
+        .string()
+        .trim()
+        .min(1)
+        .max(253)
+        .optional()
+        .describe("Hostname to bind. Auto-creates the Domain inventory record for the space's team when none exists."),
+    spaceId: z
+        .string()
+        .min(1)
+        .describe("Space this hostname is anchored to: the serve target, or for redirect/proxy bindings the space whose site serves the hostname."),
+    mode: z
+        .enum(["serve", "redirect", "proxy"])
+        .default("serve")
+        .describe("Routing intent: serve a space, redirect, or proxy an upstream."),
+    pathPrefix: z
+        .string()
+        .trim()
+        .max(255)
+        .nullable()
+        .optional()
+        .describe("Path scope like `/docs`; omit to claim the whole host."),
+    wildcard: z
+        .boolean()
+        .optional()
+        .describe("Capture subdomains too (requires domain wildcardEnabled)."),
+    channel: z
+        .string()
+        .trim()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe('Channel to serve (serve mode); defaults to "live".'),
+    primary: z
+        .boolean()
+        .optional()
+        .describe("Make this the space's primary hostname (serve mode)."),
+    to: domainBindingRedirectTargetSchema.optional(),
+    redirectStatus: domainBindingRedirectStatusSchema.optional(),
+    upstream: z
+        .object({ url: z.string().url().describe("Absolute upstream URL.") })
+        .optional()
+        .describe("Proxy upstream (proxy mode)."),
+})
+    .superRefine((value, ctx) => {
+    if (!value.domainId && !value.hostname) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["hostname"],
+            message: "Pass `hostname` (auto-creates the domain) or `domainId`.",
+        });
+    }
+    if (value.domainId && value.hostname) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["domainId"],
+            message: "Pass either `domainId` or `hostname`, not both.",
+        });
+    }
+    requireBindingModeFields(value, ctx);
+});
+export const domainBindingPatchSchema = z
+    .object({
+    mode: z
+        .enum(["serve", "redirect", "proxy"])
+        .optional()
+        .describe("Switch the routing intent; the new mode's fields are required alongside."),
+    pathPrefix: z.string().trim().max(255).nullable().optional().describe("New path scope."),
+    wildcard: z.boolean().optional().describe("Toggle subdomain capture."),
+    channel: z.string().trim().min(1).max(64).optional().describe("Channel to serve (serve mode)."),
+    primary: z
+        .boolean()
+        .optional()
+        .describe("Promote to the space's primary hostname (serve mode)."),
+    to: domainBindingRedirectTargetSchema.optional(),
+    redirectStatus: domainBindingRedirectStatusSchema.optional(),
+    upstream: z
+        .object({ url: z.string().url().describe("Absolute upstream URL.") })
+        .optional()
+        .describe("Proxy upstream (proxy mode)."),
+})
+    .superRefine((value, ctx) => {
+    if (Object.keys(value).length === 0) {
+        ctx.addIssue({ code: "custom", message: "At least one binding field is required." });
+    }
+    if (value.mode !== undefined) {
+        requireBindingModeFields(value, ctx);
+    }
+});
+// Binding activation is asynchronous; the binding is the pollable status
+// resource. `confirm` carries conflict ids whose `confirm_move` resolution the
+// caller accepts — activation performs the move (no public move API).
+export const domainBindingActivateSchema = z.object({
+    confirm: z
+        .array(z.string())
+        .default([])
+        .describe("Conflict ids whose `activate_moves_existing` resolution the caller confirms."),
+});
+// Activation is asynchronous: the binding is the pollable status resource and
+// `operation` tracks the work item (standard mutation envelope).
+export const domainBindingActivateResponseSchema = mutationEnvelope(domainBindingSchema);
+export const domainBindingListResponseSchema = z.object({
+    data: z.array(domainBindingSchema),
+    pagination: CursorPaginationSchema,
+});
+export const domainBindingListQuerySchema = cursorListQuerySchema;
+// ---------------------------------------------------------------------------
+// SiteDomainAssignment (internal-docs/platform.md L2445-2464): provider
+// assignment of a hostname to a unified site. Mostly provider state managed by
+// bindings; POST/DELETE exist as the canonical explicit mutation surface.
+// ---------------------------------------------------------------------------
+export const siteDomainAssignmentSchema = z.object({
+    id: z.string().describe("Site domain assignment id (`sda_...`)."),
+    tenantId: z.string().describe("Tenant the assignment belongs to (`ten_...`)."),
+    domainId: z.string().describe("Domain inventory record this hostname belongs to (`dom_...`)."),
+    siteId: z.string().nullable().describe("Unified site (`site_...`) the hostname is assigned to."),
+    hostname: z.string().describe("Hostname assigned at the provider."),
+    status: z
+        .enum([
+        "unassigned",
+        "pending_provider",
+        "pending_dns",
+        "pending_ssl",
+        "active",
+        "blocked",
+        "failed",
+    ])
+        .describe("Provider assignment status; the assignment is pollable during activation."),
+    dnsInstructions: z
+        .array(DnsInstructionSchema)
+        .describe("DNS records required for this hostname to route and verify."),
+    providerState: AnyObjectSchema.describe("Raw provider-side state, for diagnostics only."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .describe("Structured assignment diagnostics with stable codes."),
+    createdAt: z.string().datetime().describe("When the assignment was created."),
+    updatedAt: z.string().datetime().describe("When the assignment last changed."),
+});
+export const siteDomainAssignmentCreateSchema = z.object({
+    spaceId: z
+        .string()
+        .min(1)
+        .describe("Space whose site this domain's hostname is assigned to (`spc_...`)."),
+});
+export const siteDomainAssignmentListResponseSchema = z.object({
+    data: z.array(siteDomainAssignmentSchema),
+    pagination: CursorPaginationSchema,
+});
+// ---------------------------------------------------------------------------
+// Registrar facet routes (feature-flagged dev-only per charter D5).
+// ---------------------------------------------------------------------------
+export const domainRegistrationSchema = z.object({
+    id: z.string().nullable().describe("Registration or transfer record id; null when unregistered."),
+    domainId: z.string().describe("Domain inventory record (`dom_...`)."),
+    hostname: z.string().describe("Registered hostname."),
+    provider: z
+        .enum(["dsapi", "manual"])
+        .nullable()
+        .describe("Wrapped registrar bridge the registration lives at."),
+    status: z.string().describe("Registration lifecycle status."),
+    expiresAt: z.string().datetime().nullable().describe("When the registration expires."),
+    redemptionEndsAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("End of the redemption window after expiry."),
+    autoRenew: z.boolean().describe("Whether the registration renews automatically."),
+    transferLock: z.boolean().describe("Whether outbound transfers are locked."),
+    privacySetting: z
+        .enum(["enable_privacy_service", "redact_contact_info", "disclose_contact_info"])
+        .nullable()
+        .describe("WHOIS privacy behavior."),
+    contactId: z.string().nullable().describe("Registrant contact record."),
+    failureReason: z.string().nullable().describe("Provider failure detail, when failed."),
+    createdAt: z.string().datetime().nullable(),
+    updatedAt: z.string().datetime().nullable(),
+});
+const domainRegistrationPeriodSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe("Registration period in years.");
+const domainRegistrationContactIdSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Registrant contact record to use.");
+// `registrar.mode` changes only through these actions, never via PATCH. Keep
+// mode-specific fields in the contract so clients get param-level validation.
+export const domainRegistrationActionSchema = z.discriminatedUnion("action", [
+    z
+        .object({
+        action: z.literal("purchase"),
+        period: domainRegistrationPeriodSchema,
+        contactId: domainRegistrationContactIdSchema,
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("renew"),
+        period: domainRegistrationPeriodSchema,
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("transfer_in"),
+        authCode: z
+            .string()
+            .trim()
+            .min(1)
+            .max(255)
+            .describe("Transfer authorization code from the current registrar."),
+        contactId: domainRegistrationContactIdSchema,
+    })
+        .strict(),
+    z
+        .object({
+        action: z.literal("transfer_out"),
+    })
+        .strict(),
+]);
+// Registration actions are asynchronous: the registration is the pollable
+// status resource and the operation tracks the provider submission.
+export const domainRegistrationActionResponseSchema = mutationEnvelope(domainRegistrationSchema);
+export const domainRegistrationPatchSchema = z
+    .object({
+    autoRenew: z.boolean().optional().describe("Toggle automatic renewal."),
+    transferLock: z.boolean().optional().describe("Toggle the registrar transfer lock."),
+    privacySetting: z
+        .enum(["enable_privacy_service", "redact_contact_info", "disclose_contact_info"])
+        .optional()
+        .describe("WHOIS privacy behavior."),
+    contactId: z
+        .string()
+        .trim()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe("Registrant contact record."),
+})
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one registration field is required.",
+});
+export const domainNameserverResponseSchema = z.object({
+    domainId: z.string().describe("Domain inventory record (`dom_...`)."),
+    mode: z.enum(["stattic", "external"]).describe("Current DNS hosting mode."),
+    nameservers: z.array(z.string()).describe("Delegation set at the registrar."),
+    assignedNameserverSetId: z
+        .string()
+        .optional()
+        .describe("Managed nameserver set identifier when Spacefast assigns the delegation."),
+    nameserverFamilyKey: z
+        .string()
+        .optional()
+        .describe("Provider-neutral family key for the assigned delegation set."),
+    observedNameservers: z
+        .array(z.string())
+        .optional()
+        .describe("Nameservers currently observed in public DNS."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .optional()
+        .describe("Delegation diagnostics such as divergence or registrar-action requirements."),
+});
+export const domainNameserverUpdateSchema = z.object({
+    nameservers: z
+        .array(z.string().trim().min(1).max(253))
+        .min(2)
+        .max(13)
+        .describe("Nameserver hostnames to delegate to (2-13)."),
+});
+// Facet modes change only here, never via PATCH. The response is the
+// post-mutation Domain plus an operation for callers watching the work item.
+export const domainDnsModeRequestSchema = z.object({
+    mode: z
+        .enum(["stattic", "external"])
+        .describe("Target DNS hosting mode. external→stattic snapshots observed records first."),
+});
+// The transition receipt rides inside `data` (envelope law: `{data}` plus
+// `operation` only): the post-mutation Domain plus the transition diagnostics
+// (import visibility limits on external→stattic, exported records to re-create
+// on stattic→external).
+export const domainDnsModeResponseSchema = mutationEnvelope(z.object({
+    domain: DomainSchema.describe("The post-mutation Domain."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .describe("Transition diagnostics: import visibility limits on external→stattic, exported records on stattic→external."),
+    requiredActions: requiredActionsSchema,
+}));
+// ---------------------------------------------------------------------------
+// Managed DNS records (feature-flagged dev-only per charter D5).
+// ---------------------------------------------------------------------------
+export const domainDnsRecordSchema = z.object({
+    id: z.string().describe("DNS record id (`rec_...`)."),
+    domainId: z.string().describe("Zone-cut domain record this zone belongs to (`dom_...`)."),
+    type: z
+        .enum(["A", "AAAA", "ALIAS", "CAA", "CNAME", "MX", "NS", "SRV", "TXT"])
+        .describe("DNS record type."),
+    name: z.string().describe('Record name relative to the zone; "@" for the zone cut itself.'),
+    value: z.string().describe("Record value."),
+    ttl: z.number().int().positive().describe("Time to live in seconds."),
+    priority: z.number().int().nullable().describe("Record priority; required for MX and SRV."),
+    providerRecordId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Provider-assigned DNS record id; read-only and present only for connected providers."),
+    proxied: z
+        .boolean()
+        .nullable()
+        .optional()
+        .describe("Provider proxying flag when supported; null when not applicable or unknown."),
+    comment: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Provider/user record comment when supported; null when unavailable."),
+    providerOptions: AnyObjectSchema.nullable()
+        .optional()
+        .describe("Provider-only record metadata when advertised by capabilities."),
+    managed: z
+        .boolean()
+        .describe("Spacefast-owned (verification/routing/ssl); read-only via the public API."),
+    protected: z
+        .boolean()
+        .default(false)
+        .describe("Read-only through public DNS record writes even when the record is not Spacefast-owned."),
+    purpose: z
+        .enum(["verification", "routing", "ssl"])
+        .nullable()
+        .describe("Why Spacefast manages this record; present on managed records."),
+    ownerResourceId: z
+        .string()
+        .nullable()
+        .describe("Owning resource: the domain (verification) or binding/assignment (routing/ssl)."),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const domainDnsCapabilityFieldSchema = z.object({
+    path: z
+        .string()
+        .describe("Stable record field path, for example `ttl` or `providerOptions.proxied`."),
+    type: z
+        .enum(["string", "number", "boolean", "enum", "object", "array"])
+        .describe("Machine-readable field type."),
+    readable: z.boolean().describe("Whether provider snapshots can return this field."),
+    creatable: z.boolean().describe("Whether create requests may set this field."),
+    patchable: z.boolean().describe("Whether patch requests may change this field."),
+    requiredWhen: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Stable condition expression, if conditional."),
+    limits: AnyObjectSchema.optional().describe("Provider-neutral field limits."),
+    default: z.unknown().optional().describe("Provider default when known."),
+    unsupportedReasonCode: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Why this field is unavailable."),
+});
+export const domainDnsExclusiveFieldGroupSchema = z.object({
+    key: z.string().describe("Stable exclusivity rule key."),
+    fields: z.array(z.string()).min(1).describe("Stable field paths included in this rule."),
+    mode: z.enum(["exactly_one", "at_most_one", "required_with", "forbidden_with"]),
+    appliesWhen: z
+        .object({
+        recordTypes: z.array(domainDnsRecordSchema.shape.type).optional(),
+        managementKinds: z
+            .array(z.enum([
+            "unmanaged_external",
+            "connected_provider",
+            "registrar_dns",
+            "stattic_nameservers",
+        ]))
+            .optional(),
+        providerKeys: z.array(z.string()).optional(),
+        expression: z.string().optional(),
+    })
+        .optional(),
+    errorCode: z.string(),
+    message: z.string(),
+    fixSuggestion: z.string(),
+});
+export const domainDnsServiceTemplateSchema = z.object({
+    key: z.string().describe("Stable service-template key."),
+    subjectFacet: z.enum(["dns_zone", "email", "forwarding", "hosting_binding"]),
+    previewable: z.boolean().describe("Whether the template can be previewed before apply."),
+    applyMode: z
+        .enum(["automatic", "manual", "either"])
+        .describe("Whether Spacefast can apply the template automatically."),
+    variables: z
+        .array(domainDnsCapabilityFieldSchema)
+        .describe("Template variable descriptors rendered by clients."),
+});
+const domainFeatureCrudSchema = z.object({
+    readable: z.boolean(),
+    creatable: z.boolean(),
+    patchable: z.boolean(),
+    deletable: z.boolean().optional(),
+    verification: z.boolean().optional(),
+});
+export const domainDnsFeatureCapabilitiesSchema = z.object({
+    batch: z.object({
+        supported: z.boolean(),
+        atomic: z.boolean(),
+        maxChanges: z.number().int().positive().optional(),
+    }),
+    importBind: z.boolean(),
+    exportBind: z.boolean(),
+    providerImport: z.boolean(),
+    providerExport: z.boolean(),
+    migrationPreview: z.boolean(),
+    scanReview: z.boolean(),
+    serviceTemplates: z.array(domainDnsServiceTemplateSchema),
+    domainFeatures: z
+        .object({
+        forwarding: domainFeatureCrudSchema.optional(),
+        emailForwards: domainFeatureCrudSchema.optional(),
+        dnssec: z
+            .object({
+            readable: z.boolean(),
+            toggleable: z.boolean(),
+            dsData: z.boolean().optional(),
+        })
+            .optional(),
+        glueRecords: domainFeatureCrudSchema.optional(),
+        sslRetry: z.object({ supported: z.boolean() }).optional(),
+        contactVerification: z
+            .object({ supported: z.boolean(), uploadRequired: z.boolean().optional() })
+            .optional(),
+        privacy: z
+            .object({ supported: z.boolean(), discloseRedact: z.boolean().optional() })
+            .optional(),
+        transferLock: z.object({ supported: z.boolean() }).optional(),
+        authCodeCheck: z.object({ supported: z.boolean() }).optional(),
+    })
+        .describe("Capability-backed non-record domain features."),
+    proxied: z.object({
+        supported: z.boolean(),
+        editableTypes: z.array(domainDnsRecordSchema.shape.type),
+        ttlBehavior: z.enum(["automatic_when_enabled"]).optional(),
+    }),
+    comments: z.object({
+        supported: z.boolean(),
+        maxLength: z.number().int().positive().optional(),
+    }),
+    tags: z
+        .object({
+        supported: z.boolean(),
+        maxItems: z.number().int().positive().optional(),
+        maxLength: z.number().int().positive().optional(),
+    })
+        .optional(),
+});
+export const domainDnsProviderWriteStrategySchema = z.enum([
+    "per_record",
+    "batch_add_remove",
+    "batch_transaction",
+    "replace_all_record_sets",
+]);
+// Hybrid DNS mode (both available at launch). `authoritative` = Spacefast hosts
+// the zone and answers queries (registrar_dns / stattic_nameservers backends);
+// `adapter` = Spacefast manages records on the user's existing DNS host through
+// that host's API (connected_provider) or only observes them and emits
+// instructions (unmanaged_external). Additive read-model label derived from
+// `managementKind`; it never changes how records are applied.
+export const domainDnsHybridModeSchema = z
+    .enum(["authoritative", "adapter"])
+    .describe("Whether Spacefast hosts the authoritative zone (`authoritative`) or manages/observes records on the user's existing DNS host (`adapter`).");
+const DNS_MANAGEMENT_KINDS = [
+    "unmanaged_external",
+    "connected_provider",
+    "registrar_dns",
+    "stattic_nameservers",
+];
+// Single source of truth mapping management kind -> hybrid mode. Spacefast-hosted
+// zones (registrar_dns, stattic_nameservers) are authoritative; provider and
+// external backends are adapter-mode.
+export function deriveDnsHybridMode(managementKind) {
+    return managementKind === "registrar_dns" || managementKind === "stattic_nameservers"
+        ? "authoritative"
+        : "adapter";
+}
+export const domainDnsCapabilitiesSchema = z
+    .object({
+    domainId: z.string().describe("Domain inventory record (`dom_...`)."),
+    managementKind: z.enum([
+        "unmanaged_external",
+        "connected_provider",
+        "registrar_dns",
+        "stattic_nameservers",
+    ]),
+    dnsMode: domainDnsHybridModeSchema
+        .optional()
+        .describe("Hybrid DNS mode derived from `managementKind`: authoritative (Spacefast-hosted zone) or adapter (records on the user's existing host)."),
+    writeAuthority: z
+        .enum([
+        "none",
+        "provider_credentials",
+        "registrar_authority",
+        "delegated_nameservers",
+        "internal_service_key",
+    ])
+        .describe("Why DNS writes are or are not available."),
+    provider: z.string().nullable().describe("Effective DNS provider key when known."),
+    recordTypes: z
+        .array(domainDnsRecordSchema.shape.type)
+        .describe("Record types accepted by this backend."),
+    fields: z
+        .array(domainDnsCapabilityFieldSchema)
+        .describe("Editable/readable field descriptors."),
+    exclusiveGroups: z
+        .array(domainDnsExclusiveFieldGroupSchema)
+        .describe("Cross-field rules shared by clients, validation, and provider planning."),
+    features: domainDnsFeatureCapabilitiesSchema.describe("Normalized service-template, import/export, and domain-feature capabilities."),
+    supportsBatch: z.boolean().describe("Whether normalized batch writes are supported."),
+    supportsAtomicBatch: z.boolean().describe("Whether batch writes are all-or-nothing."),
+    writeStrategy: domainDnsProviderWriteStrategySchema.describe("How normalized DNS changes are applied by the effective provider."),
+    supportsImport: z
+        .boolean()
+        .describe("Whether Spacefast can import zone content from this backend."),
+    supportsExport: z
+        .boolean()
+        .describe("Whether Spacefast can export zone content from this backend."),
+    ttlBehavior: z
+        .enum(["explicit", "automatic_when_proxied", "provider_default"])
+        .describe("How TTL is handled for editable records."),
+    snapshot: z
+        .object({
+        freshness: z.enum(["fresh", "stale", "refresh_running", "refresh_failed", "never_fetched"]),
+        lastFetchedAt: z.string().datetime().nullable(),
+        version: z.string().nullable(),
+    })
+        .describe("Provider snapshot freshness for connected-provider records."),
+    diagnostics: z.array(baseDiagnosticSchema).describe("Capability or authority diagnostics."),
+})
+    .transform((capabilities) => ({
+    ...capabilities,
+    dnsMode: capabilities.dnsMode ?? deriveDnsHybridMode(capabilities.managementKind),
+}));
+export const domainProviderConnectionStatusSchema = z.enum([
+    "active",
+    "degraded",
+    "auth_expired",
+    "revoked",
+    "owner_access_lost",
+    "disconnected",
+    "pending_relink",
+    "reconnect_required",
+    "disabled",
+]);
+export const domainDnsProviderSchema = z.enum([
+    "cloudflare",
+    "vercel",
+    "wpcom",
+    "pressable",
+    "route53",
+    "stattic",
+    "manual",
+]);
+export const domainProviderConnectionSchema = z.object({
+    id: z.string().describe("Provider connection id (`dpc_...`)."),
+    tenantId: z.string().describe("Tenant that owns this connection."),
+    teamId: z.string().describe("Team that owns this connection."),
+    provider: domainDnsProviderSchema.describe("DNS provider key."),
+    label: z.string().describe("Human-readable provider account label."),
+    authType: z.enum(["oauth", "api_token", "internal_service"]),
+    credentialConfigured: z.boolean().describe("Whether a write credential exists."),
+    scopes: z
+        .array(z.string())
+        .describe("Provider scopes or permissions observed for this connection."),
+    status: domainProviderConnectionStatusSchema,
+    lastVerifiedAt: z.string().datetime().nullable(),
+    lastErrorCode: z.string().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const domainProviderConnectionListQuerySchema = cursorListQuerySchema.extend({
+    teamId: z.string().min(1).optional(),
+    provider: domainDnsProviderSchema.optional(),
+});
+export const domainProviderConnectionListResponseSchema = z.object({
+    data: z.array(domainProviderConnectionSchema),
+    pagination: CursorPaginationSchema,
+});
+export const domainProviderConnectionCreateSchema = z
+    .object({
+    teamId: z.string().min(1).optional(),
+    provider: domainDnsProviderSchema,
+    label: z.string().trim().min(1).max(255),
+    authType: z.enum(["api_token", "internal_service"]).default("api_token"),
+    apiToken: z.string().trim().min(1).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.authType === "api_token" && !value.apiToken) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["apiToken"],
+            message: "`apiToken` is required for api_token provider connections.",
+        });
+    }
+    if (value.authType === "internal_service" && value.apiToken) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["apiToken"],
+            message: "`apiToken` is not accepted for internal service provider connections.",
+        });
+    }
+});
+export const domainProviderConnectionOAuthCompleteSchema = z.object({
+    teamId: z.string().min(1).optional(),
+    provider: z.literal("cloudflare"),
+    label: z.string().trim().min(1).max(255).optional(),
+});
+export const domainProviderZoneSchema = z.object({
+    id: z.string().describe("Provider-native zone id."),
+    name: z.string().describe("Provider-native zone name."),
+    provider: domainDnsProviderSchema,
+    connectionId: z.string(),
+    status: z.enum(["active", "pending", "moved", "unknown"]).default("unknown"),
+    observedNameservers: z.array(z.string()).default([]),
+});
+export const domainProviderZoneListResponseSchema = z.object({
+    data: z.array(domainProviderZoneSchema),
+    pagination: CursorPaginationSchema,
+});
+export const domainProviderZoneAttachSchema = z.object({
+    connectionId: z.string().min(1),
+    providerZoneId: z.string().min(1).max(255),
+    providerZoneName: z.string().trim().min(1).max(255).optional(),
+});
+export const domainProviderSnapshotRefreshResponseSchema = mutationEnvelope(z.object({
+    operationId: z.string(),
+    snapshot: z.object({
+        freshness: z.enum(["refresh_running", "fresh", "refresh_failed"]),
+        lastFetchedAt: z.string().datetime().nullable(),
+        version: z.string().nullable(),
+    }),
+}));
+export const domainDnsOperationKindSchema = z.enum([
+    "provider_snapshot_refresh",
+    "provider_zone_detach",
+    "dns_record_create",
+    "dns_record_patch",
+    "dns_record_delete",
+    "dns_record_batch",
+    "review_import",
+    "apply_dns_plan",
+    "apply_service_template",
+    "change_nameservers",
+    "observe_cutover",
+    "repair_connection",
+    "registration_action",
+    "feature_action",
+]);
+export const domainDnsOperationSchema = z.object({
+    id: z.string().describe("DNS operation id (`dop_...`)."),
+    domainId: z.string(),
+    zoneId: z.string().nullable(),
+    operationKind: domainDnsOperationKindSchema,
+    status: z.enum(["queued", "running", "observing", "succeeded", "failed", "canceled"]),
+    provider: z.string(),
+    providerConnectionId: z.string().nullable(),
+    providerZoneId: z.string().nullable(),
+    providerRequestId: z.string().nullable(),
+    providerReceipt: AnyObjectSchema.nullable(),
+    diagnostics: z.array(baseDiagnosticSchema),
+    requiredActions: requiredActionsSchema,
+    retryable: z.boolean(),
+    retryAfterAt: z.string().datetime().nullable(),
+    attemptCount: z.number().int().nonnegative(),
+    lastSafeErrorCode: z.string().nullable(),
+    lastSafeErrorMessage: z.string().nullable(),
+    hints: z.array(domainHintSchema).optional(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    completedAt: z.string().datetime().nullable(),
+});
+export const domainDnsOperationListResponseSchema = z.object({
+    data: z.array(domainDnsOperationSchema),
+    pagination: CursorPaginationSchema,
+});
+export const domainActionKindSchema = z.enum([
+    "setup_dns_records",
+    "connect_provider",
+    "review_import",
+    "apply_dns_plan",
+    "apply_service_template",
+    "change_nameservers",
+    "observe_cutover",
+    "repair_connection",
+    "registration_action",
+    "feature_action",
+]);
+export const domainActionSubjectFacetSchema = z.enum([
+    "dns_zone",
+    "registrar",
+    "hosting_binding",
+    "email",
+    "forwarding",
+    "provider_connection",
+]);
+export const domainActionStatusSchema = z.enum([
+    "open",
+    "planned",
+    "waiting_for_user",
+    "ready_to_run",
+    "running",
+    "observing",
+    "complete",
+    "canceled",
+    "dismissed",
+    "expired",
+    "failed",
+    "blocked",
+    "review_required",
+    "reconnect_required",
+    "retry_available",
+    "rollback_available",
+]);
+export const domainActionOwnerSchema = z.enum([
+    "stattic",
+    "user",
+    "team_admin",
+    "provider",
+    "registrar",
+    "support",
+    "waiting",
+]);
+export const domainActionSchema = z.object({
+    id: z.string().describe("Domain action id (`dac_...`)."),
+    tenantId: z.string(),
+    teamId: z.string(),
+    domainId: z.string(),
+    kind: domainActionKindSchema,
+    subjectFacet: domainActionSubjectFacetSchema,
+    subject: AnyObjectSchema,
+    status: domainActionStatusSchema,
+    owner: domainActionOwnerSchema,
+    desiredOutcome: AnyObjectSchema,
+    plan: AnyObjectSchema,
+    instructions: z.array(AnyObjectSchema),
+    operationId: z.string().nullable(),
+    observation: AnyObjectSchema,
+    recovery: AnyObjectSchema,
+    expiresAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const domainActionListResponseSchema = z.object({
+    data: z.array(domainActionSchema),
+    pagination: CursorPaginationSchema,
+});
+export const domainActionListQuerySchema = cursorListQuerySchema.extend({
+    status: domainActionStatusSchema.optional(),
+});
+const domainActionDraftSchema = z.object({
+    kind: domainActionKindSchema,
+    subjectFacet: domainActionSubjectFacetSchema,
+    subject: AnyObjectSchema.default({}),
+    owner: domainActionOwnerSchema,
+    desiredOutcome: AnyObjectSchema,
+    plan: AnyObjectSchema.default({}),
+    instructions: z.array(AnyObjectSchema).default([]),
+    observation: AnyObjectSchema.default({}),
+    recovery: AnyObjectSchema.default({}),
+    expiresAt: z.string().datetime().nullable().optional(),
+});
+export const domainActionPreviewRequestSchema = domainActionDraftSchema;
+export const domainActionCreateRequestSchema = domainActionDraftSchema.extend({
+    dedupeKey: z
+        .string()
+        .trim()
+        .min(1)
+        .max(320)
+        .optional()
+        .describe("Stable caller-supplied dedupe key; server derives one when omitted."),
+});
+export const domainActionMutationResponseSchema = mutationEnvelope(domainActionSchema);
+export const domainDnsRecordSnapshotMetadataSchema = z.object({
+    status: z.enum([
+        "missing",
+        "fresh",
+        "stale",
+        "refreshing",
+        "refresh_failed",
+        "provider_unavailable",
+    ]),
+    fetchedAt: z.string().datetime().nullable(),
+    expiresAt: z.string().datetime().nullable(),
+    providerVersion: z.string().nullable().optional(),
+    providerRequestId: z.string().nullable().optional(),
+    recordCount: z.number().int().nonnegative(),
+});
+export const domainDnsRecordListResponseSchema = z.object({
+    data: z.array(domainDnsRecordSchema),
+    pagination: CursorPaginationSchema,
+    managementKind: z.enum(DNS_MANAGEMENT_KINDS).optional(),
+    provider: z.string().nullable().optional(),
+    writeStrategy: domainDnsProviderWriteStrategySchema.optional(),
+    snapshot: domainDnsRecordSnapshotMetadataSchema.optional(),
+    capabilities: domainDnsCapabilitiesSchema.optional(),
+});
+export const domainDnsRecordListQuerySchema = cursorListQuerySchema;
+function requireMxSrvPriority(value, ctx) {
+    if ((value.type === "MX" || value.type === "SRV") &&
+        (value.priority === undefined || value.priority === null)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["priority"],
+            message: `\`priority\` is required for ${value.type} records.`,
+        });
+    }
+    if (value.type !== undefined &&
+        value.type !== "MX" &&
+        value.type !== "SRV" &&
+        value.priority !== undefined &&
+        value.priority !== null) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["priority"],
+            message: "`priority` is only valid for MX and SRV records.",
+        });
+    }
+}
+export function validateDomainDnsFieldCapabilities(input, capabilities, operation) {
+    const fields = new Map(capabilities.fields.map((field) => [field.path, field]));
+    const issues = [];
+    for (const [path, value] of Object.entries(input)) {
+        if (value === undefined) {
+            continue;
+        }
+        const field = fields.get(path);
+        const writable = operation === "create" ? field?.creatable : field?.patchable;
+        if (!field || !writable) {
+            issues.push({
+                path,
+                code: "dns_field_not_applicable",
+                message: `${path} is not writable for this DNS provider or management mode.`,
+            });
+        }
+    }
+    for (const group of capabilities.exclusiveGroups) {
+        const present = group.fields.filter((field) => input[field] !== undefined && input[field] !== null);
+        const appliesToProvider = !group.appliesWhen?.providerKeys ||
+            group.appliesWhen.providerKeys.includes(capabilities.provider ?? "");
+        const appliesToManagementKind = !group.appliesWhen?.managementKinds ||
+            group.appliesWhen.managementKinds.includes(capabilities.managementKind);
+        if (!appliesToProvider || !appliesToManagementKind) {
+            continue;
+        }
+        let conflictPath = null;
+        switch (group.mode) {
+            case "forbidden_with":
+            case "at_most_one":
+                if (present.length > 1) {
+                    conflictPath = present[0] ?? group.fields[0] ?? "dns";
+                }
+                break;
+            case "exactly_one":
+                if (present.length !== 1) {
+                    conflictPath = group.fields[0] ?? "dns";
+                }
+                break;
+            case "required_with":
+                if (present.length > 0 && present.length < group.fields.length) {
+                    conflictPath =
+                        group.fields.find((field) => !present.includes(field)) ?? group.fields[0] ?? "dns";
+                }
+                break;
+        }
+        if (conflictPath !== null) {
+            issues.push({
+                path: conflictPath,
+                code: "dns_field_conflict",
+                message: group.message,
+                fixSuggestion: group.fixSuggestion,
+            });
+        }
+    }
+    return issues;
+}
+const domainDnsRecordPatchableFields = z.object({
+    type: domainDnsRecordSchema.shape.type,
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .describe('Record name relative to the zone; defaults to "@" on create.'),
+    value: z.string().trim().min(1).max(2048).describe("Record value."),
+    ttl: z
+        .number()
+        .int()
+        .min(60)
+        .max(86400)
+        .describe("Time to live in seconds (60-86400); defaults to 3600 on create."),
+    priority: z
+        .number()
+        .int()
+        .min(0)
+        .max(65535)
+        .nullable()
+        .optional()
+        .describe("Record priority; required for MX and SRV."),
+    proxied: z
+        .boolean()
+        .nullable()
+        .optional()
+        .describe("Provider proxying flag; accepted only when capabilities advertise it."),
+    comment: z.string().trim().max(1024).nullable().optional().describe("Record comment."),
+    providerOptions: AnyObjectSchema.nullable()
+        .optional()
+        .describe("Provider-only record fields; accepted only when capabilities advertise them."),
+});
+const domainDnsRecordFields = domainDnsRecordPatchableFields.extend({
+    name: domainDnsRecordPatchableFields.shape.name.default("@"),
+    ttl: domainDnsRecordPatchableFields.shape.ttl.default(3600),
+});
+export const domainDnsRecordCreateSchema = domainDnsRecordFields.superRefine(requireMxSrvPriority);
+export const domainDnsRecordPatchSchema = domainDnsRecordPatchableFields
+    .partial()
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one DNS record field is required.",
+})
+    .superRefine(requireMxSrvPriority);
+// Executed in exactly this order — deletes, patches, puts, posts — as one
+// atomic transaction; any failure rejects the whole batch with the failing
+// entry in `error.param`.
+export const domainDnsRecordBatchSchema = z
+    .object({
+    deletes: z
+        .array(z.object({ id: z.string().describe("Record id to delete.") }))
+        .default([])
+        .describe("Records to delete, applied first."),
+    patches: z
+        .array(domainDnsRecordPatchableFields
+        .partial()
+        .extend({ id: z.string() })
+        .superRefine(requireMxSrvPriority))
+        .default([])
+        .describe("Partial record updates, applied second."),
+    puts: z
+        .array(domainDnsRecordFields.extend({ id: z.string() }).superRefine(requireMxSrvPriority))
+        .default([])
+        .describe("Full record upserts by id, applied third."),
+    posts: z
+        .array(domainDnsRecordFields.superRefine(requireMxSrvPriority))
+        .default([])
+        .describe("New records, applied last."),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Per-hostname connectivity diagnostics (dashboard/CLI/agent read model).
+// ---------------------------------------------------------------------------
+export const domainHostnameDnsSnapshotSchema = z.object({
+    resolver: z.string().describe("Public resolver the snapshot was taken from."),
+    a: z.array(z.string()).default([]),
+    aaaa: z.array(z.string()).default([]),
+    caa: z.array(z.string()).default([]),
+    txt: z.array(z.string()).default([]),
+});
+export const domainHostnameSslBrokenRecordSchema = z.object({
+    reason: z.string().nullable(),
+    lastError: z.string().nullable(),
+    retryDate: z.string().nullable(),
+    failCount: z.number().int().nullable(),
+});
+export const domainHostnameDiagnosticsSchema = z.object({
+    hostname: z.string().describe("Hostname this diagnostic block describes."),
+    purpose: z
+        .enum(["apex", "www", "configured"])
+        .describe("Why this hostname is checked: the apex, its www twin, or the configured name."),
+    isConfiguredHostname: z.boolean().describe("Whether this is the hostname on the domain record."),
+    providerIps: z
+        .array(z.string())
+        .default([])
+        .describe("Provider IPs the hostname should point at."),
+    verificationCode: z.string().nullable().describe("Expected TXT verification value."),
+    dnsInstructions: z
+        .array(AnyObjectSchema)
+        .default([])
+        .describe("DNS records required for this hostname."),
+    dns: z.object({
+        expectedTxtValue: z.string().nullable(),
+        pointsToProvider: z.boolean().describe("Whether observed A records point at the provider."),
+        txtVerified: z.boolean().nullable().describe("Whether the verification TXT is observed."),
+        hasAaaaRecords: z.boolean(),
+        hasCaaRecords: z.boolean(),
+        records: z.object({
+            a: z.array(z.string()).default([]),
+            aaaa: z.array(z.string()).default([]),
+            caa: z.array(z.string()).default([]),
+            txt: z.array(z.string()).default([]),
+        }),
+        byResolver: z.array(domainHostnameDnsSnapshotSchema).default([]),
+    }),
+    ssl: z.object({
+        status: z.enum(["missing", "pending", "active", "broken"]).describe("Certificate state."),
+        canRetry: z.boolean().describe("Whether SSL provisioning can be retried now."),
+        certificateId: z.string().nullable(),
+        validationExpiration: z.string().nullable(),
+        authzUri: z.string().nullable(),
+        brokenRecord: domainHostnameSslBrokenRecordSchema.nullable(),
+    }),
+});
+export const domainDiagnosticsResponseSchema = z.object({
+    domainId: z.string().describe("Domain inventory record (`dom_...`)."),
+    hostname: z.string().describe("Configured hostname."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .optional()
+        .describe('Domain-level setup nudges computed at read time, e.g. "companion_hostname_unbound" when the apex/www pair is half-bound.'),
+    hostnameDiagnostics: z
+        .array(domainHostnameDiagnosticsSchema)
+        .describe("Per-hostname DNS and SSL connectivity diagnostics."),
+});