@caelo-cms/shared 0.10.47 → 0.10.49

package/src/cloud-shell-install.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The "Open in Google Cloud Shell" install link (epic #696, Phase 3).
+ *
+ * The link opens github.com/caelo-cms/install on the `release-v<version>`
+ * branch that repository's track-release workflow creates for every stable
+ * release (and never moves), with the provider's walkthrough tutorial. Its
+ * `run.sh` pins and verifies exactly that release of the provisioner. One
+ * builder for every place that shows the link — README, docs, and the
+ * admin's "run this release in Cloud Shell" hint — so they can't drift.
+ */
+
+/** The repository the Cloud Shell button clones. */
+export const CLOUD_SHELL_INSTALL_REPO = "https://github.com/caelo-cms/install";
+
+/** The button image Google publishes for "Open in Cloud Shell" links. */
+export const CLOUD_SHELL_BUTTON_IMAGE = "https://gstatic.com/cloudssh/images/open-btn.svg";
+
+/** Providers the Cloud Shell install covers (one tutorial each). */
+export type CloudShellProvider = "gcp" | "gcp-firebase";
+
+const STABLE = /^v?(\d+\.\d+\.\d+)$/;
+
+/**
+ * The Cloud Shell install link for a stable release.
+ *
+ * @throws for a pre-release or non-SemVer version — only stable releases
+ *   get a `release-v<version>` branch in the install repository
+ *
+ * @example cloudShellInstallUrl("0.10.47", "gcp")
+ *   // → "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=release-v0.10.47&cloudshell_tutorial=gcp.md"
+ */
+export function cloudShellInstallUrl(version: string, provider: CloudShellProvider): string {
+  const m = STABLE.exec(version);
+  if (!m) {
+    throw new Error(
+      `no Cloud Shell install link for "${version}": only stable releases are pinned in ${CLOUD_SHELL_INSTALL_REPO}`,
+    );
+  }
+  return [
+    "https://shell.cloud.google.com/cloudshell/editor",
+    `?cloudshell_git_repo=${CLOUD_SHELL_INSTALL_REPO}`,
+    `&cloudshell_git_branch=release-v${m[1]}`,
+    `&cloudshell_tutorial=${provider}.md`,
+  ].join("");
+}

package/src/database-url.test.ts

@@ -1,7 +1,12 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { databasePasswordVar, databaseUrlFromEnv, withDatabasePassword } from "./database-url.js";
+import {
+  cloudSqlIamDatabaseUrls,
+  databasePasswordVar,
+  databaseUrlFromEnv,
+  withDatabasePassword,
+} from "./database-url.js";
 
 describe("databasePasswordVar", () => {
   it("pairs each URL var with its _PASSWORD var", () => {
@@ -114,3 +119,13 @@ describe("databaseUrlFromEnv", () => {
     );
   });
 });
+
+describe("cloudSqlIamDatabaseUrls", () => {
+  it("logs in as the service account's IAM database user with the token as password", () => {
+    expect(cloudSqlIamDatabaseUrls("10.0.0.3", "job@p.iam.gserviceaccount.com", "ya29/x")).toEqual({
+      user: "job@p.iam",
+      admin: "postgresql://job%40p.iam:ya29%2Fx@10.0.0.3:5432/cms_admin?sslmode=require",
+      public: "postgresql://job%40p.iam:ya29%2Fx@10.0.0.3:5432/cms_public?sslmode=require",
+    });
+  });
+});

package/src/database-url.ts

@@ -81,3 +81,24 @@ export function databaseUrlFromEnv(
   }
   return undefined;
 }
+
+/**
+ * Password-less database URLs for Cloud SQL IAM database authentication —
+ * how the in-cloud jobs (the operator-access sync job, the upgrader job)
+ * connect: the user is the service account email without
+ * `.gserviceaccount.com`, the password a short-lived OAuth access token.
+ *
+ * @example
+ *   cloudSqlIamDatabaseUrls("10.0.0.3", "job@p.iam.gserviceaccount.com", "ya29.x").user
+ *   // → "job@p.iam"
+ */
+export function cloudSqlIamDatabaseUrls(
+  host: string,
+  serviceAccountEmail: string,
+  accessToken: string,
+): { admin: string; public: string; user: string } {
+  const user = serviceAccountEmail.replace(/\.gserviceaccount\.com$/, "");
+  const url = (db: string) =>
+    `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(accessToken)}@${host}:5432/${db}?sslmode=require`;
+  return { admin: url("cms_admin"), public: url("cms_public"), user };
+}

package/src/index.ts

@@ -4,9 +4,11 @@ export const PROJECT_NAME = "caelo-cms";
 
 export * from "./ai-tools.js";
 export * from "./auth-forms.js";
+export * from "./auto-update.js";
 export * from "./base-css.js";
 export * from "./build-page.js";
 export * from "./cap-failures.js";
+export * from "./cloud-shell-install.js";
 export * from "./content.js";
 export * from "./context.js";
 export * from "./css-gradient-scan.js";
@@ -35,12 +37,14 @@ export {
 export * from "./media.js";
 export * from "./nested-module-render.js";
 export * from "./page-log.js";
+export * from "./platform-updates.js";
 export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
 export * from "./provisioning-command.js";
 export * from "./redirect-target.js";
+export * from "./release-manifest.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
 export * from "./safe-keys.js";

package/src/platform-updates.test.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  autoInstallRefusal,
+  inMaintenanceWindow,
+  isFinishedUpdateStatus,
+  PLATFORM_UPDATE_STALE_REASON,
+  type StoredUpdatePolicy,
+  updateKind,
+  updatePolicySchema,
+} from "./platform-updates.js";
+
+describe("updateKind", () => {
+  it.each([
+    ["0.10.45", "0.10.46", "patch"],
+    ["0.10.45", "0.11.0", "minor"],
+    ["0.10.45", "1.0.0", "major"],
+    ["0.11.0-rc.1", "0.11.0", "patch"],
+    ["0.11.0-rc.1", "0.11.0-rc.2", "patch"],
+    ["0.11.0-rc.9", "0.11.0-rc.10", "patch"],
+    ["0.11.0-rc.2", "0.11.0-rc.1", null],
+    ["0.11.0", "0.11.0-rc.2", null],
+    ["0.10.45", "0.10.45", null],
+    ["0.10.45", "0.10.44", null],
+    ["0.11.0", "0.10.99", null],
+    ["nope", "0.10.46", null],
+  ] as const)("%s → %s is %s", (from, to, kind) => {
+    expect(updateKind(from, to)).toBe(kind);
+  });
+});
+
+describe("inMaintenanceWindow", () => {
+  const at = (iso: string) => new Date(iso);
+  it("no window = any time", () => {
+    expect(
+      inMaintenanceWindow(
+        { windowStart: null, windowEnd: null, windowTimezone: "UTC" },
+        at("2026-10-13T12:00:00Z"),
+      ),
+    ).toBe(true);
+  });
+  it("respects the time zone", () => {
+    const w = { windowStart: "02:00", windowEnd: "05:00", windowTimezone: "Europe/Berlin" };
+    // 01:30 UTC = 03:30 Berlin (CEST).
+    expect(inMaintenanceWindow(w, at("2026-10-13T01:30:00Z"))).toBe(true);
+    expect(inMaintenanceWindow(w, at("2026-10-13T03:30:00Z"))).toBe(false);
+  });
+  it("a window across midnight", () => {
+    const w = { windowStart: "22:00", windowEnd: "04:00", windowTimezone: "UTC" };
+    expect(inMaintenanceWindow(w, at("2026-10-13T23:00:00Z"))).toBe(true);
+    expect(inMaintenanceWindow(w, at("2026-10-13T03:59:00Z"))).toBe(true);
+    expect(inMaintenanceWindow(w, at("2026-10-13T04:00:00Z"))).toBe(false);
+    expect(inMaintenanceWindow(w, at("2026-10-13T12:00:00Z"))).toBe(false);
+  });
+});
+
+describe("autoInstallRefusal", () => {
+  const policy: StoredUpdatePolicy = {
+    mode: "auto",
+    autoSecurity: true,
+    autoPatch: false,
+    autoMinor: false,
+    channel: "stable",
+    windowStart: null,
+    windowEnd: null,
+    windowTimezone: "UTC",
+    soakHours: 24,
+    securitySoakHours: 2,
+    paused: false,
+    pausedReason: null,
+    pausedAt: null,
+    pausedUntil: null,
+    pausedByOwner: false,
+    updatedAt: "2026-10-13T00:00:00Z",
+  };
+  const now = new Date("2026-10-13T12:00:00Z");
+  const patch = {
+    kind: "patch",
+    security: false,
+    contractMigrations: false,
+    channel: "stable",
+  } as const;
+
+  it.each([
+    ["mode off", { ...policy, mode: "notify" as const }, patch, "switched off"],
+    ["paused", { ...policy, paused: true }, { ...patch, security: true }, "paused"],
+    ["rc channel", policy, { ...patch, security: true, channel: "rc" }, "only stable"],
+    [
+      "contract migrations",
+      policy,
+      { ...patch, security: true, contractMigrations: true },
+      "destructive",
+    ],
+    [
+      "major",
+      { ...policy, autoMinor: true, autoPatch: true },
+      { ...patch, kind: "major" as const },
+      "major",
+    ],
+    ["patch not enabled", policy, patch, "does not install"],
+    [
+      "outside window",
+      { ...policy, autoPatch: true, windowStart: "02:00", windowEnd: "03:00" },
+      patch,
+      "outside the maintenance window",
+    ],
+  ])("%s → refused", (_name, p, c, why) => {
+    expect(autoInstallRefusal(p, c, now)).toContain(why);
+  });
+
+  it("allows an enabled kind inside the window", () => {
+    expect(autoInstallRefusal(policy, { ...patch, security: true }, now)).toBeNull();
+    expect(
+      autoInstallRefusal({ ...policy, autoMinor: true }, { ...patch, kind: "minor" }, now),
+    ).toBeNull();
+  });
+});
+
+describe("updatePolicySchema", () => {
+  const base = {
+    mode: "auto",
+    autoSecurity: true,
+    autoPatch: false,
+    autoMinor: false,
+    channel: "stable",
+    windowStart: "02:00",
+    windowEnd: "04:00",
+    windowTimezone: "Europe/Berlin",
+    soakHours: 24,
+    securitySoakHours: 2,
+  };
+  it("accepts a sane policy and rejects broken ones", () => {
+    expect(updatePolicySchema.safeParse(base).success).toBe(true);
+    for (const bad of [
+      { ...base, channel: "rc" },
+      { ...base, windowEnd: null },
+      { ...base, windowStart: "25:00" },
+      { ...base, windowTimezone: "Nowhere/Land" },
+      { ...base, soakHours: 1000 },
+      { ...base, securitySoakHours: 48 },
+      { ...base, extra: true },
+    ]) {
+      expect(updatePolicySchema.safeParse(bad).success).toBe(false);
+    }
+  });
+});
+
+it("isFinishedUpdateStatus", () => {
+  expect(isFinishedUpdateStatus("pending")).toBe(false);
+  expect(isFinishedUpdateStatus("running")).toBe(false);
+  expect(isFinishedUpdateStatus("needs_cloud_shell")).toBe(true);
+});
+
+describe("PLATFORM_UPDATE_STALE_REASON (#721)", () => {
+  it("names no provider's tool: it ends dead Google Cloud and self-hosted runs alike", () => {
+    expect(PLATFORM_UPDATE_STALE_REASON).not.toContain("Cloud Shell");
+    expect(PLATFORM_UPDATE_STALE_REASON).toContain("Settings → Updates");
+  });
+});

package/src/platform-updates.ts

@@ -0,0 +1,336 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * In-product Caelo updates (epic #696): the vocabulary the admin (Settings →
+ * Updates, the `platform_updates.*` ops), the upgrader job and the Phase 5
+ * scheduler share. One module so the timeline the page renders, the states
+ * the job writes and the database CHECK constraints (migration 0267) agree.
+ */
+
+import { z } from "zod";
+
+/** Every state of an update request (`platform_update_requests.status`). */
+export const PLATFORM_UPDATE_STATUSES = [
+  "pending",
+  "running",
+  "succeeded",
+  "rolled_back",
+  "failed",
+  "refused",
+  "needs_cloud_shell",
+  "cancelled",
+] as const;
+export type PlatformUpdateStatusValue = (typeof PLATFORM_UPDATE_STATUSES)[number];
+
+/** States in which a request is still in flight (at most one at a time). */
+export const ACTIVE_UPDATE_STATUSES: readonly PlatformUpdateStatusValue[] = ["pending", "running"];
+
+/** Whether `status` is an end state. */
+export function isFinishedUpdateStatus(status: PlatformUpdateStatusValue): boolean {
+  return !ACTIVE_UPDATE_STATUSES.includes(status);
+}
+
+/**
+ * The phases of an upgrader run, in order (`platform_update_events.phase`).
+ * `rollback` only appears when a roll had to be undone.
+ */
+export const PLATFORM_UPDATE_PHASES = [
+  "queued",
+  "start",
+  "verify",
+  "assess",
+  "backup",
+  "health-baseline",
+  "migrations",
+  "roll",
+  "health",
+  "rollback",
+  "record",
+  "self-update",
+  "finish",
+] as const;
+export type PlatformUpdatePhase = (typeof PLATFORM_UPDATE_PHASES)[number];
+
+/** Severity of one timeline line. */
+export const PLATFORM_UPDATE_EVENT_LEVELS = ["info", "success", "warn", "error"] as const;
+export type PlatformUpdateEventLevel = (typeof PLATFORM_UPDATE_EVENT_LEVELS)[number];
+
+/** Who started a request: the Owner's click, or the Phase 5 scheduler. */
+export const PLATFORM_UPDATE_TRIGGERS = ["manual", "auto"] as const;
+export type PlatformUpdateTrigger = (typeof PLATFORM_UPDATE_TRIGGERS)[number];
+
+/**
+ * A run still `running` this long after it started died (the upgrader job's
+ * task timeout is 60 minutes). The next job run, and the next install
+ * request, end it as failed — so a crashed run never blocks updates.
+ */
+export const PLATFORM_UPDATE_STALE_MINUTES = 90;
+
+/**
+ * Why a stale run was ended (shown on its timeline). Provider-neutral: the
+ * same text ends a dead Google Cloud job run and a dead self-hosted agent
+ * run, and Settings → Updates shows each install its own way to upgrade by
+ * hand (Cloud Shell there, the upgrade command on the server here).
+ */
+export const PLATFORM_UPDATE_STALE_REASON =
+  "The upgrader stopped before it finished (its run timed out or crashed). The previous release may still serve, or the new one may be partly rolled out: open the site, and if it misbehaves run the upgrade by hand once — Settings → Updates shows how for this install.";
+
+/** Longest an event message may be (DB CHECK). */
+export const PLATFORM_UPDATE_EVENT_MAX = 4000;
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+/** A SemVer release version without a leading `v` (`0.11.0`, `0.11.0-rc.1`). */
+export const releaseVersionSchema = z
+  .string()
+  .regex(SEMVER, "expected a release version like 0.11.0 (no leading v)");
+
+/** How big a step from `from` to `to` is, by SemVer position. */
+export type UpdateKind = "major" | "minor" | "patch";
+
+/**
+ * Classify the step from the installed release to a newer one.
+ *
+ * @returns null when `to` is not newer than `from` or either is not SemVer.
+ * @example updateKind("0.10.45", "0.10.46") // → "patch"
+ */
+export function updateKind(from: string, to: string): UpdateKind | null {
+  const a = SEMVER.exec(from);
+  const b = SEMVER.exec(to);
+  if (!a || !b) return null;
+  const [fa, fb, fc] = [Number(a[1]), Number(a[2]), Number(a[3])];
+  const [ta, tb, tc] = [Number(b[1]), Number(b[2]), Number(b[3])];
+  if (ta !== fa) return ta > fa ? "major" : null;
+  if (tb !== fb) return tb > fb ? "minor" : null;
+  if (tc !== fc) return tc > fc ? "patch" : null;
+  // Same X.Y.Z: a stable release over its own pre-release, or a later
+  // pre-release (rc.1 → rc.2), is a step.
+  if (a[4] === undefined) return null;
+  if (b[4] === undefined) return "patch";
+  return comparePrerelease(b[4], a[4]) > 0 ? "patch" : null;
+}
+
+/** SemVer §11 precedence of two pre-release identifier lists. */
+function comparePrerelease(x: string, y: string): number {
+  const xs = x.split(".");
+  const ys = y.split(".");
+  for (let i = 0; i < Math.max(xs.length, ys.length); i++) {
+    const p = xs[i];
+    const q = ys[i];
+    if (p === undefined) return -1;
+    if (q === undefined) return 1;
+    const pn = /^\d+$/.test(p);
+    const qn = /^\d+$/.test(q);
+    if (pn && qn && Number(p) !== Number(q)) return Number(p) - Number(q);
+    if (pn !== qn) return pn ? -1 : 1;
+    if (p !== q) return p < q ? -1 : 1;
+  }
+  return 0;
+}
+
+/** The automatic-update modes. */
+export const UPDATE_POLICY_MODES = ["off", "notify", "auto"] as const;
+export type UpdatePolicyMode = (typeof UPDATE_POLICY_MODES)[number];
+
+/** Release channels a policy may follow (only `stable` installs automatically). */
+export const UPDATE_POLICY_CHANNELS = ["stable", "rc", "beta", "alpha"] as const;
+
+const WALL_CLOCK = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+/** Whether `tz` is an IANA time zone this runtime knows. */
+export function isKnownTimeZone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The Owner's automatic-update policy (`platform_update_policy`), as the
+ * ops read and write it. Major releases have no toggle: they are never
+ * installed automatically before 1.0.
+ */
+export const updatePolicySchema = z
+  .object({
+    mode: z.enum(UPDATE_POLICY_MODES),
+    autoSecurity: z.boolean(),
+    autoPatch: z.boolean(),
+    autoMinor: z.boolean(),
+    channel: z.enum(UPDATE_POLICY_CHANNELS),
+    /** `HH:MM` local time in `windowTimezone`, or null with windowEnd null = any time. */
+    windowStart: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
+    windowEnd: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
+    windowTimezone: z.string().min(1).max(64).refine(isKnownTimeZone, "unknown time zone"),
+    /** Hours after publication before a non-security release installs automatically. */
+    soakHours: z.number().int().min(0).max(720),
+    /**
+     * The same for a release whose signed manifest names a published GitHub
+     * Security Advisory (auto-update.ts `isSecurityRelease`). Shorter by
+     * default (2 h vs 24 h): the fix is public, so every hour unpatched is
+     * exposure, while two hours still let a broken release be pulled first.
+     */
+    securitySoakHours: z.number().int().min(0).max(720),
+  })
+  .strict()
+  .refine((p) => (p.windowStart === null) === (p.windowEnd === null), {
+    message: "set both ends of the maintenance window, or neither",
+  })
+  .refine((p) => p.mode !== "auto" || p.channel === "stable", {
+    message: "automatic installs follow the stable channel only",
+  })
+  .refine((p) => p.securitySoakHours <= p.soakHours, {
+    message: "security fixes cannot wait longer than other releases",
+  });
+export type UpdatePolicy = z.infer<typeof updatePolicySchema>;
+
+/** The policy plus its pause state, as stored. */
+export interface StoredUpdatePolicy extends UpdatePolicy {
+  readonly paused: boolean;
+  readonly pausedReason: string | null;
+  readonly pausedAt: string | null;
+  /** End of the Owner's pause; null = until resumed (or not paused). */
+  readonly pausedUntil: string | null;
+  /** True when the Owner paused; false when the upgrader paused after a failure. */
+  readonly pausedByOwner: boolean;
+  readonly updatedAt: string;
+}
+
+/** Minutes since local midnight of `at` in `timeZone`. */
+function localMinutes(at: Date, timeZone: string): number {
+  const parts = new Intl.DateTimeFormat("en-GB", {
+    timeZone,
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  }).formatToParts(at);
+  const n = (t: string) => Number(parts.find((p) => p.type === t)?.value ?? "0");
+  return n("hour") * 60 + n("minute");
+}
+
+const toMinutes = (hhmm: string) => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(3, 5));
+
+/**
+ * Whether `at` falls inside the policy's maintenance window. A window whose
+ * end is before its start spans midnight (`22:00`–`04:00`).
+ */
+export function inMaintenanceWindow(
+  policy: Pick<UpdatePolicy, "windowStart" | "windowEnd" | "windowTimezone">,
+  at: Date,
+): boolean {
+  if (policy.windowStart === null || policy.windowEnd === null) return true;
+  const now = localMinutes(at, policy.windowTimezone);
+  const start = toMinutes(policy.windowStart);
+  const end = toMinutes(policy.windowEnd);
+  if (start === end) return true;
+  return start < end ? now >= start && now < end : now >= start || now < end;
+}
+
+/** What the policy needs to know about a release to decide on an automatic install. */
+export interface AutoInstallCandidate {
+  readonly kind: UpdateKind;
+  /** From the signed manifest AND auto-installable (assessAutoInstall's `kind`). */
+  readonly security: boolean;
+  /** Manifest `migrations.contract` (or a skipped contract release). */
+  readonly contractMigrations: boolean;
+  /** The release's channel. */
+  readonly channel: string;
+}
+
+/**
+ * Whether the policy lets the upgrader install `candidate` unattended at
+ * `at` — the job's check for `trigger = 'auto'` requests (the scheduler
+ * applies the soak period before it ever queues one).
+ *
+ * @returns null when allowed, else the reason in plain words
+ */
+export function autoInstallRefusal(
+  policy: Pick<
+    StoredUpdatePolicy,
+    | "mode"
+    | "autoSecurity"
+    | "autoPatch"
+    | "autoMinor"
+    | "paused"
+    | "pausedUntil"
+    | "windowStart"
+    | "windowEnd"
+    | "windowTimezone"
+  >,
+  candidate: AutoInstallCandidate,
+  at: Date,
+): string | null {
+  if (policy.mode !== "auto") return "automatic installs are switched off in the update policy";
+  // An Owner pause with an end that has passed no longer holds (the
+  // scheduler lifts it on its next tick; this keeps the job consistent).
+  if (
+    policy.paused &&
+    (policy.pausedUntil === null || Date.parse(policy.pausedUntil) > at.getTime())
+  ) {
+    return "automatic installs are paused";
+  }
+  if (candidate.channel !== "stable") return "only stable releases install automatically";
+  if (candidate.contractMigrations) {
+    return "the release carries destructive database changes; the Owner installs it by hand";
+  }
+  if (candidate.kind === "major") return "major releases never install automatically";
+  const allowed =
+    (candidate.security && policy.autoSecurity) ||
+    (candidate.kind === "patch" && policy.autoPatch) ||
+    (candidate.kind === "minor" && policy.autoMinor);
+  if (!allowed) {
+    return `the policy does not install ${candidate.security ? "security fixes or " : ""}${candidate.kind} releases automatically`;
+  }
+  if (!inMaintenanceWindow(policy, at)) return "outside the maintenance window";
+  return null;
+}
+
+/**
+ * How long a verified Google sign-in authorizes one guarded action. Long
+ * enough to read the confirmation dialog, short enough that an unattended
+ * browser is useless soon after.
+ */
+export const STEP_UP_MAX_AGE_SECONDS = 600;
+
+/** What a step-up is for (`step_up_challenges.purpose`). */
+export const STEP_UP_PURPOSES = ["platform_update", "update_policy", "step_up_client"] as const;
+export type StepUpPurpose = (typeof STEP_UP_PURPOSES)[number];
+
+/**
+ * Self-hosted installs (#696 Phase 4c): the host agent (`caelo-agent`, a
+ * systemd timer on the install's host) polls for update requests this
+ * often and writes a heartbeat each time it looks.
+ */
+export const PLATFORM_UPDATE_AGENT_POLL_SECONDS = 60;
+
+/**
+ * The admin offers "Install update" on a self-hosted install only while the
+ * agent's last heartbeat is younger than this (five missed polls): a request
+ * nobody picks up would just sit there.
+ */
+export const PLATFORM_UPDATE_AGENT_FRESH_SECONDS = 300;
+
+/** The host agent's last check-in (`platform_update_agent`), as the admin reads it. */
+export interface PlatformUpdateAgentStatus {
+  /** The Caelo release of the agent's own code. */
+  readonly agentVersion: string;
+  /** The host it runs on (its hostname). */
+  readonly host: string;
+  readonly lastSeenAt: string;
+  /**
+   * What would make an install fail on that host (cosign missing, Docker
+   * not reachable), in plain words; null when its preflight passed.
+   */
+  readonly problem: string | null;
+  /** Whether {@link lastSeenAt} is within {@link PLATFORM_UPDATE_AGENT_FRESH_SECONDS}. */
+  readonly checkedInRecently: boolean;
+}
+
+/** Whether an agent last seen at `lastSeenAt` counts as running at `now`. */
+export function agentCheckedInRecently(lastSeenAt: Date | string, now: Date): boolean {
+  const seen = new Date(lastSeenAt).getTime();
+  return (
+    Number.isFinite(seen) && now.getTime() - seen <= PLATFORM_UPDATE_AGENT_FRESH_SECONDS * 1000
+  );
+}