@amerged/ohmyhost-mcp 0.1.10

package/src/packages/contracts/framework-family.ts

@@ -0,0 +1,18 @@
+export type FrameworkFamilyClassification =
+  | "ambiguous"
+  | "nextjs"
+  | "tanstack-start"
+  | "unknown"
+  | "vite";
+
+export function classifyFrameworkFamily(
+  dependencies: ReadonlySet<string>,
+): FrameworkFamilyClassification {
+  const next = dependencies.has("next");
+  const tanStack = dependencies.has("@tanstack/react-start");
+  const vite = dependencies.has("vite");
+  if (next && (tanStack || vite)) return "ambiguous";
+  if (next) return "nextjs";
+  if (tanStack) return "tanstack-start";
+  return vite ? "vite" : "unknown";
+}

package/src/packages/contracts/functions.ts

@@ -0,0 +1,76 @@
+/**
+ * Declared cron schedules for the Worker module of a project environment.
+ * Five-field UTC cron, at most eight unique entries, minimum five-minute interval.
+ */
+export function normalizeCrons(value: readonly unknown[]): readonly string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 8) {
+    throw new TypeError("ohmyhost.yaml functions.crons must list one to eight schedules");
+  }
+  const crons = value.map((entry) => {
+    if (typeof entry !== "string") throw new TypeError("ohmyhost.yaml cron is invalid");
+    return normalizeCron(entry);
+  });
+  const sorted = [...crons].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+  for (let index = 1; index < sorted.length; index += 1) {
+    if (sorted[index - 1] === sorted[index]) {
+      throw new TypeError("ohmyhost.yaml functions.crons must be unique");
+    }
+  }
+  return Object.freeze(sorted);
+}
+
+export function normalizeCron(value: string): string {
+  if (value !== value.trim() || value.includes("  ")) {
+    throw new TypeError("ohmyhost.yaml cron is invalid");
+  }
+  const fields = value.split(" ");
+  if (fields.length !== 5) throw new TypeError("ohmyhost.yaml cron is invalid");
+  const [minute, hour, day, month, weekday] = fields;
+  if (
+    minute === undefined ||
+    hour === undefined ||
+    day === undefined ||
+    month === undefined ||
+    weekday === undefined ||
+    !validCronMinute(minute) ||
+    !validCronField(hour, 0, 23) ||
+    !validCronField(day, 1, 31) ||
+    !validCronField(month, 1, 12) ||
+    !validCronField(weekday, 0, 6)
+  ) {
+    throw new TypeError("ohmyhost.yaml cron is invalid");
+  }
+  return value;
+}
+
+function validCronMinute(value: string): boolean {
+  const step = /^\*\/([1-9]|[1-5][0-9])$/u.exec(value);
+  if (step !== null) return Number(step[1]) >= 5;
+  return value !== "*" && validCronField(value, 0, 59);
+}
+
+function validCronField(value: string, minimum: number, maximum: number): boolean {
+  if (value === "*") return true;
+  if (!/^(?:0|[1-9][0-9]?)$/u.test(value)) return false;
+  const parsed = Number(value);
+  return parsed >= minimum && parsed <= maximum;
+}
+
+/** Whether a validated five-field UTC cron fires in the minute that contains `at`. */
+export function isCronDue(cron: string, at: Date): boolean {
+  const fields = normalizeCron(cron).split(" ");
+  const [minute, hour, day, month, weekday] = fields as [string, string, string, string, string];
+  const utcMinute = at.getUTCMinutes();
+  const minuteDue = minute.startsWith("*/")
+    ? utcMinute % Number(minute.slice(2)) === 0
+    : Number(minute) === utcMinute;
+  const matches = (field: string, value: number): boolean =>
+    field === "*" || Number(field) === value;
+  return (
+    minuteDue &&
+    matches(hour, at.getUTCHours()) &&
+    matches(day, at.getUTCDate()) &&
+    matches(month, at.getUTCMonth() + 1) &&
+    matches(weekday, at.getUTCDay())
+  );
+}

package/src/packages/contracts/index.ts

@@ -0,0 +1,245 @@
+import { Ajv2020, type ErrorObject } from "ajv/dist/2020.js";
+import { parse as parseYaml } from "yaml";
+
+import schema from "../schemas/ohmyhost.schema.json" with { type: "json" };
+import { normalizeApplicationRoot, type ApplicationRoot } from "./application-root.js";
+import { normalizeCrons } from "./functions.js";
+
+export * from "./application-root.js";
+export * from "./framework-admission.js";
+export * from "./operation-deployment-result.js";
+export * from "./operation-failure.js";
+export * from "./functions.js";
+
+export type OhmyhostRuntimeMode = "static" | "edge" | "functions" | "auto";
+
+/** Build settings of an application; the functions runtime installs dependencies only. */
+export type OhmyhostApplicationBuild = Readonly<{
+  install: string;
+  command: string;
+  output: string;
+}>;
+export type OhmyhostFunctionsBuild = Readonly<{ install: string }>;
+
+export interface OhmyhostConfig {
+  readonly version: 1;
+  readonly project: string;
+  readonly applicationRoot: ApplicationRoot;
+  readonly build: OhmyhostApplicationBuild | OhmyhostFunctionsBuild;
+  readonly runtime: Readonly<{
+    mode: OhmyhostRuntimeMode;
+    healthcheck: string;
+    egress: Readonly<{ allow: readonly string[] }>;
+  }>;
+  readonly database?: Readonly<{
+    enabled: boolean;
+    migrations?: string;
+  }>;
+  readonly auth?: Readonly<{
+    provider: "none" | "better-auth";
+  }>;
+  readonly mail?: Readonly<{
+    enabled: boolean;
+  }>;
+  readonly storage?: Readonly<{
+    provider: "r2";
+    /** Must equal the project's hosting region (`us` by default, `eu` when the project was created there). */
+    jurisdiction: "us" | "eu";
+    public: false;
+  }>;
+  readonly functions?: Readonly<{ crons: readonly string[] }>;
+  readonly credits?: Readonly<{
+    monthly_budget: number;
+    auto_recharge?: Readonly<{
+      enabled: boolean;
+      threshold?: number;
+      amount_usd_micros?: number;
+      monthly_cap_usd_micros?: number;
+    }>;
+  }>;
+}
+
+const validateOhmyhostConfig = new Ajv2020({
+  allErrors: true,
+  strict: true,
+}).compile<OhmyhostConfig>(schema);
+
+export function parseOhmyhostConfig(value: unknown): OhmyhostConfig {
+  if (!validateOhmyhostConfig(value)) {
+    throw new TypeError(`ohmyhost.yaml is invalid: ${formatErrors(validateOhmyhostConfig.errors)}`);
+  }
+
+  const input = value as OhmyhostConfig;
+  const config: OhmyhostConfig = {
+    version: 1,
+    project: input.project,
+    applicationRoot: normalizeApplicationRoot(input.applicationRoot),
+    build:
+      input.runtime.mode === "functions"
+        ? Object.freeze({ install: input.build.install })
+        : Object.freeze({
+            install: input.build.install,
+            command: (input.build as OhmyhostApplicationBuild).command,
+            output: (input.build as OhmyhostApplicationBuild).output,
+          }),
+    runtime: Object.freeze({
+      mode: input.runtime.mode,
+      healthcheck: normalizeHealthcheck(input.runtime.healthcheck),
+      egress: Object.freeze({
+        allow: normalizeEgressOrigins(input.runtime.egress?.allow),
+      }),
+    }),
+    ...(input.database === undefined
+      ? {}
+      : {
+          database: Object.freeze({
+            enabled: input.database.enabled,
+            ...(input.database.migrations === undefined
+              ? {}
+              : { migrations: input.database.migrations }),
+          }),
+        }),
+    ...(input.auth === undefined ? {} : { auth: Object.freeze({ provider: input.auth.provider }) }),
+    ...(input.mail === undefined ? {} : { mail: Object.freeze({ enabled: input.mail.enabled }) }),
+    ...(input.storage === undefined
+      ? {}
+      : {
+          storage: Object.freeze({
+            provider: input.storage.provider,
+            jurisdiction: input.storage.jurisdiction,
+            public: input.storage.public,
+          }),
+        }),
+    ...(input.functions === undefined
+      ? {}
+      : {
+          functions: Object.freeze({ crons: normalizeCrons(input.functions.crons) }),
+        }),
+    ...(input.credits === undefined
+      ? {}
+      : {
+          credits: Object.freeze({
+            monthly_budget: input.credits.monthly_budget,
+            ...(input.credits.auto_recharge === undefined
+              ? {}
+              : {
+                  auto_recharge: Object.freeze({
+                    enabled: input.credits.auto_recharge.enabled,
+                    ...(input.credits.auto_recharge.threshold === undefined
+                      ? {}
+                      : { threshold: input.credits.auto_recharge.threshold }),
+                    ...(input.credits.auto_recharge.amount_usd_micros === undefined
+                      ? {}
+                      : { amount_usd_micros: input.credits.auto_recharge.amount_usd_micros }),
+                    ...(input.credits.auto_recharge.monthly_cap_usd_micros === undefined
+                      ? {}
+                      : {
+                          monthly_cap_usd_micros:
+                            input.credits.auto_recharge.monthly_cap_usd_micros,
+                        }),
+                  }),
+                }),
+          }),
+        }),
+  };
+
+  return Object.freeze(config);
+}
+
+function normalizeHealthcheck(value: string | undefined): string {
+  const candidate = value ?? "/";
+  if (
+    candidate !== candidate.trim() ||
+    !candidate.startsWith("/") ||
+    candidate.startsWith("//") ||
+    candidate.includes("\\") ||
+    candidate.includes("?") ||
+    candidate.includes("#") ||
+    candidate.split("/").some((segment) => segment === "." || segment === "..")
+  ) {
+    throw new TypeError("ohmyhost.yaml runtime healthcheck is invalid");
+  }
+  return candidate;
+}
+
+function normalizeEgressOrigins(value: readonly string[] | undefined): readonly string[] {
+  const origins = [...(value ?? [])];
+  for (const origin of origins) {
+    let parsed: URL;
+    try {
+      parsed = new URL(origin);
+    } catch {
+      throw new TypeError("ohmyhost.yaml runtime egress origin is invalid");
+    }
+    if (
+      parsed.protocol !== "https:" ||
+      parsed.username !== "" ||
+      parsed.password !== "" ||
+      parsed.origin !== origin ||
+      parsed.pathname !== "/" ||
+      parsed.search !== "" ||
+      parsed.hash !== "" ||
+      forbiddenEgressHostname(parsed.hostname)
+    ) {
+      throw new TypeError("ohmyhost.yaml runtime egress origin is invalid");
+    }
+  }
+  origins.sort();
+  return Object.freeze(origins);
+}
+
+function forbiddenEgressHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase();
+  if (
+    normalized === "localhost" ||
+    normalized.endsWith(".localhost") ||
+    normalized.endsWith(".local") ||
+    normalized.endsWith(".internal") ||
+    normalized === "0.0.0.0" ||
+    normalized === "::1"
+  ) {
+    return true;
+  }
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(normalized);
+  if (ipv4 === null) return normalized.startsWith("[") || normalized.endsWith("]");
+  const octets = ipv4.slice(1).map(Number);
+  if (octets.some((octet) => octet > 255)) return true;
+  return (
+    octets[0] === 10 ||
+    octets[0] === 127 ||
+    (octets[0] === 169 && octets[1] === 254) ||
+    (octets[0] === 172 && (octets[1] ?? 0) >= 16 && (octets[1] ?? 0) <= 31) ||
+    (octets[0] === 192 && octets[1] === 168)
+  );
+}
+
+/** The application build of a static or edge configuration. */
+export function requireApplicationBuild(config: OhmyhostConfig): OhmyhostApplicationBuild {
+  if (config.runtime.mode === "functions" || !("command" in config.build)) {
+    throw new TypeError(
+      "ohmyhost.yaml build.command and build.output require an application runtime",
+    );
+  }
+  return config.build;
+}
+
+export function parseOhmyhostConfigYaml(source: string): OhmyhostConfig {
+  if (typeof source !== "string") {
+    throw new TypeError("ohmyhost.yaml must be a string");
+  }
+
+  let value: unknown;
+  try {
+    value = parseYaml(source) as unknown;
+  } catch {
+    throw new TypeError("ohmyhost.yaml is not valid YAML");
+  }
+
+  return parseOhmyhostConfig(value);
+}
+
+function formatErrors(errors: ErrorObject[] | null | undefined): string {
+  return (errors ?? [])
+    .map(({ instancePath, message }) => `${instancePath || "/"} ${message ?? "is invalid"}`)
+    .join("; ");
+}

package/src/packages/contracts/operation-deployment-result.ts

@@ -0,0 +1,165 @@
+export const OPERATION_DEPLOYMENT_RESULT_SCHEMA_VERSION =
+  "ohmyhost.operation-deployment-result/v2" as const;
+
+export interface OperationDeploymentResult {
+  readonly schemaVersion: typeof OPERATION_DEPLOYMENT_RESULT_SCHEMA_VERSION;
+  readonly operationId: string;
+  readonly deploymentId: string;
+  readonly planId: string;
+  readonly artifactSha256: string;
+  readonly url: string;
+}
+
+export function createOperationDeploymentResult(
+  input: Omit<OperationDeploymentResult, "schemaVersion">,
+): OperationDeploymentResult {
+  return parseOperationDeploymentResult({
+    schemaVersion: OPERATION_DEPLOYMENT_RESULT_SCHEMA_VERSION,
+    ...input,
+  });
+}
+
+export function parseOperationDeploymentResult(value: unknown): OperationDeploymentResult {
+  const result = exactRecord(value, [
+    "schemaVersion",
+    "operationId",
+    "deploymentId",
+    "planId",
+    "artifactSha256",
+    "url",
+  ]);
+  if (result["schemaVersion"] !== OPERATION_DEPLOYMENT_RESULT_SCHEMA_VERSION) invalid();
+  return Object.freeze({
+    schemaVersion: OPERATION_DEPLOYMENT_RESULT_SCHEMA_VERSION,
+    operationId: ulid(result["operationId"]),
+    deploymentId: ulid(result["deploymentId"]),
+    planId: ulid(result["planId"]),
+    artifactSha256: digest(result["artifactSha256"]),
+    url: httpsUrl(result["url"]),
+  });
+}
+
+function exactRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) invalid();
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    invalid();
+  }
+  return value as Record<string, unknown>;
+}
+
+function ulid(value: unknown): string {
+  if (typeof value !== "string" || !/^[0-9A-HJKMNP-TV-Z]{26}$/u.test(value)) invalid();
+  return value;
+}
+
+function digest(value: unknown): string {
+  if (typeof value !== "string" || !/^[0-9a-f]{64}$/u.test(value)) invalid();
+  return value;
+}
+
+function httpsUrl(value: unknown): string {
+  if (typeof value !== "string" || value.length > 2048) invalid();
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    invalid();
+  }
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.username !== "" ||
+    parsed.password !== "" ||
+    parsed.search !== "" ||
+    parsed.hash !== "" ||
+    parsed.hostname === ""
+  ) {
+    invalid();
+  }
+  return value;
+}
+
+function invalid(): never {
+  throw new TypeError("Operation deployment result is invalid");
+}
+
+const deploymentProgressActions = {
+  queued: "The deployment is queued. Poll this same operation; do not submit another deployment.",
+  building:
+    "The build has not yet completed. Poll this same operation and read deployment logs if it fails.",
+  publishing:
+    "The build has completed. Runtime preparation or publication is still running; poll this same operation.",
+  waiting_for_mail:
+    "Read 'ohmyhost mail domain status --project PROJECT --json' now and follow its verification issue and DNS records. Keep this operation; do not rebuild or repeat correct DNS changes.",
+  mail_status_unavailable:
+    "Mail readiness could not be observed. Read 'ohmyhost mail domain status --project PROJECT --json' and report a persistent error; keep this operation.",
+} as const;
+export type DeploymentProgressPhase = keyof typeof deploymentProgressActions;
+export interface OperationDeploymentProgress {
+  readonly build_completed_at?: string;
+  readonly phase: DeploymentProgressPhase;
+  readonly project_id: string;
+  readonly deployment_id: string;
+  readonly observed_at: string;
+  readonly next_poll_after_seconds: 60;
+  readonly suggested_action: string;
+}
+export function createOperationDeploymentProgress(input: {
+  build_completed_at?: string;
+  phase: DeploymentProgressPhase;
+  project_id: string;
+  deployment_id: string;
+  observed_at: string;
+}): OperationDeploymentProgress {
+  const project = ulid(input.project_id);
+  ulid(input.deployment_id);
+  if (
+    !Object.hasOwn(deploymentProgressActions, input.phase) ||
+    !Number.isFinite(Date.parse(input.observed_at)) ||
+    new Date(input.observed_at).toISOString() !== input.observed_at
+  )
+    invalid();
+  if (
+    input.build_completed_at !== undefined &&
+    (!Number.isFinite(Date.parse(input.build_completed_at)) ||
+      new Date(input.build_completed_at).toISOString() !== input.build_completed_at)
+  )
+    invalid();
+  return Object.freeze({
+    ...(input.build_completed_at === undefined
+      ? {}
+      : { build_completed_at: input.build_completed_at }),
+    phase: input.phase,
+    project_id: project,
+    deployment_id: input.deployment_id,
+    observed_at: input.observed_at,
+    next_poll_after_seconds: 60 as const,
+    suggested_action: deploymentProgressActions[input.phase].replace("PROJECT", project),
+  });
+}
+export function parseOperationDeploymentProgress(value: unknown): OperationDeploymentProgress {
+  const keys = [
+    "phase",
+    "project_id",
+    "deployment_id",
+    "observed_at",
+    "next_poll_after_seconds",
+    "suggested_action",
+  ];
+  if (typeof value === "object" && value !== null && Object.hasOwn(value, "build_completed_at"))
+    keys.push("build_completed_at");
+  const row = exactRecord(value, keys);
+  const parsed = createOperationDeploymentProgress({
+    ...(row["build_completed_at"] === undefined
+      ? {}
+      : { build_completed_at: row["build_completed_at"] as string }),
+    phase: row["phase"] as DeploymentProgressPhase,
+    project_id: row["project_id"] as string,
+    deployment_id: row["deployment_id"] as string,
+    observed_at: row["observed_at"] as string,
+  });
+  if (row["next_poll_after_seconds"] !== 60 || row["suggested_action"] !== parsed.suggested_action)
+    invalid();
+  return parsed;
+}

package/src/packages/contracts/operation-failure.ts

@@ -0,0 +1,150 @@
+const failures = {
+  operation_abandoned: [
+    "The operation stopped renewing its execution lease and was ended.",
+    "Inspect project status and deployment diagnostics before creating a fresh plan. Keep this operation ID; the expired execution cannot resume.",
+  ],
+  database_write_rejected: [
+    "The database rejected this write; it was not committed.",
+    "Inspect the schema and parameter types with database query, then correct the statement and use a new key. Do not reset the database.",
+  ],
+  database_write_unavailable: [
+    "The database write could not start.",
+    "Read project status and database compute. This operation did not write data; after fixing availability, submit a new confirmed request.",
+  ],
+  database_write_outcome_unknown: [
+    "The database write outcome could not be confirmed.",
+    "Do not repeat the write with a new key. Inspect the target data with a read query and retain this operation ID. The same key only reads this receipt.",
+  ],
+  database_compute_failed: [
+    "The database size change failed at the provider.",
+    "Read the current database compute and report this operation ID through feedback. Preserve data; do not reset or redeploy the database to repair its size.",
+  ],
+  database_compute_plan_changed: [
+    "Paid access ended before the database size change started.",
+    "Read the organization's plan and current database compute, then confirm a new standard-size request. This operation did not resize the database.",
+  ],
+  database_compute_rejected: [
+    "The database size change could not be started.",
+    "Read current compute and report this operation ID through feedback. Preserve existing data. After the provider problem is resolved, submit a new confirmed size change.",
+  ],
+
+  recovery_dispatch_failed: [
+    "The export executor could not confirm completion after bounded delivery attempts.",
+    "Report the export operation ID through feedback. Check the original status before requesting another export after next_request_at.",
+  ],
+  recovery_job_failed: [
+    "The SQL export could not be completed.",
+    "Inspect the export status and report its operation ID through feedback. A new export is available after next_request_at.",
+  ],
+  recovery_input_expired: [
+    "The export did not start before its temporary password input expired.",
+    "The password input was discarded. Request a new export after next_request_at and report the delayed operation ID.",
+  ],
+  recovery_database_unavailable: [
+    "A read-only database snapshot could not be obtained.",
+    "Check database readiness through project status. Preserve existing data and report the export operation ID.",
+  ],
+  recovery_checksum_mismatch: [
+    "The stored export did not match its verified ciphertext receipt.",
+    "Do not use this archive. Report the export operation ID; request a new export after next_request_at.",
+  ],
+  recovery_scope_unavailable: [
+    "The project was frozen, transferred or deleted before the export completed.",
+    "Check the current project and organization access before requesting another export.",
+  ],
+  recovery_archive_too_large: [
+    "The SQL export exceeds the current 256 MiB plaintext limit.",
+    "Report the required export size through feedback. No incomplete archive is offered for download.",
+  ],
+  operation_failed: [
+    "The operation failed.",
+    "Inspect the operation events and deployment diagnostics. Include the operation ID when reporting the issue.",
+  ],
+  build_not_started: [
+    "The deployment ended without starting a build.",
+    "Create a fresh deployment plan and submit it once with a new idempotency key. Replaying this terminal operation cannot start a build. Report the operation ID if this happens again.",
+  ],
+  build_failed: [
+    "The build did not produce a verified deployable artifact.",
+    "Inspect the deployment build diagnostics and verify the install and build commands for the admitted commit. Correct the reported failure before planning a new deployment.",
+  ],
+  insufficient_organization_credits: [
+    "The organization does not have sufficient available credits for this operation.",
+    "Ask the organization owner to top up credits, then create a new deployment plan. Preserve existing data; do not buy a second subscription or repeatedly reconcile this terminal operation.",
+  ],
+  paid_plan_required: [
+    "Transactional mail requires an active Paid plan for this organization.",
+    "Activate or renew Paid for the organization, then create a new deployment plan. Replaying this terminal operation cannot enable mail. Do not change application code or reset its database.",
+  ],
+  database_migration_failed: [
+    "The database migrations could not be applied.",
+    "Inspect the migration diagnostics and verify the canonical SQL migrations on PostgreSQL. Preserve production data; do not reset the database to retry a deployment.",
+  ],
+  runtime_candidate_failed: [
+    "The deployed candidate failed its runtime checks.",
+    "Inspect deployment runtime diagnostics, required secrets and the health-check route before creating a new deployment plan.",
+  ],
+  runtime_candidate_rejected: [
+    "The runtime rejected the built Worker script.",
+    "Check that src/ohmyhost/worker.ts exports its handlers as the default export and imports no framework-only modules, then plan the new commit. Replaying this terminal operation cannot stage the same script.",
+  ],
+  storage_jurisdiction_conflict: [
+    "storage.jurisdiction must equal the project's hosting region.",
+    "Set storage.jurisdiction in ohmyhost.yaml to the project's hosting region shown by project status and plan again. A project cannot move its files between regions; do not delete or recreate the project to change it.",
+  ],
+  provider_state_absent: [
+    "Reconciliation confirmed that the required deployment resources are absent.",
+    "Create a fresh deployment plan. The original operation is terminal; do not repeatedly reconcile it.",
+  ],
+} as const;
+
+export interface PublicOperationFailure {
+  readonly code: keyof typeof failures;
+  readonly message: string;
+  readonly retryable: false;
+  readonly suggested_action: string;
+}
+
+export interface OperationReconciliationObservation {
+  readonly state: "required" | "pending";
+  readonly attempt_id: string | null;
+  readonly observed_at: string;
+}
+
+export interface PublicOperationReconciliation extends OperationReconciliationObservation {
+  readonly suggested_action: string;
+}
+
+/** Reconciliation is an observation, not a terminal operation event or provider error. */
+export function publicOperationReconciliation(
+  observation: OperationReconciliationObservation,
+): PublicOperationReconciliation {
+  if (
+    !["required", "pending"].includes(observation.state) ||
+    !Number.isFinite(Date.parse(observation.observed_at)) ||
+    (observation.state === "required"
+      ? observation.attempt_id !== null
+      : typeof observation.attempt_id !== "string" ||
+        !/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/u.test(observation.attempt_id))
+  )
+    throw new TypeError("Operation reconciliation observation is invalid");
+  return Object.freeze({
+    state: observation.state,
+    attempt_id: observation.attempt_id,
+    observed_at: observation.observed_at,
+    suggested_action:
+      observation.state === "required"
+        ? "Confirm reconciliation of this same operation; preserve its existing build and resources. Do not submit another deployment."
+        : "Reconciliation is running. Poll this same operation after 60 seconds; do not start another reconciliation or deployment.",
+  });
+}
+
+/** Render only reviewed text; never return the internal/provider error message. */
+export function publicOperationFailure(internalCode: string): PublicOperationFailure {
+  const normalized = internalCode.toLowerCase();
+  const code = Object.hasOwn(failures, normalized)
+    ? (normalized as keyof typeof failures)
+    : "operation_failed";
+  const [message, suggested_action] = failures[code];
+  return Object.freeze({ code, message, retryable: false, suggested_action });
+}

package/src/packages/contracts/platform-origins.ts

@@ -0,0 +1,5 @@
+export type SaasCnameTarget = "customers.omh.st" | "customers.ohmyho.st";
+
+export function isSaasCnameTarget(value: unknown): value is SaasCnameTarget {
+  return value === "customers.omh.st" || value === "customers.ohmyho.st";
+}