@openlup/platform 0.29.0 → 0.30.0

package/src/lifecycle/appUpgrade.ts

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** Exact UTF-8 scaffold files; every unlisted path remains application-owned. */
+export interface AppVersionSnapshot {
+  version: string;
+  schema: { min: number; max: number };
+  files: Readonly<Record<string, string>>;
+}
+
+export interface AppUpgradeInput {
+  /** Absolute canonical path (as returned by realpath) of an existing app directory. */
+  root: string;
+  from: AppVersionSnapshot;
+  to: AppVersionSnapshot;
+  /** Observed by the caller; planning and applying execute no database work. */
+  schemaVersion: number;
+}
+
+export type AppUpgradeAction = "create" | "replace" | "remove" | "unchanged" | "preserved" | "already-applied";
+export interface AppUpgradeConflict { path: string; reason: string }
+export interface AppUpgradePlan {
+  fromVersion: string;
+  toVersion: string;
+  schemaVersion: number;
+  files: { path: string; action: AppUpgradeAction }[];
+  conflicts: AppUpgradeConflict[];
+}
+
+export class AppUpgradeConflictError extends Error {
+  constructor(public readonly conflicts: readonly AppUpgradeConflict[]) {
+    super(`Application upgrade refused: ${conflicts.map(({ path, reason }) => `${path || "schema"}: ${reason}`).join("; ")}`);
+    this.name = "AppUpgradeConflictError";
+  }
+}
+
+/** Read-only comparison of explicit predecessor and candidate snapshots. */
+export async function planAppUpgrade(input: AppUpgradeInput): Promise<AppUpgradePlan> {
+  return (await inspectUpgrade(input)).plan;
+}
+
+/**
+ * The caller must hold an exclusive maintenance window over the application tree.
+ * This is not a lock against concurrent editors or hostile filesystem mutation.
+ * All conflicts are checked before any writes. A later I/O failure can leave a
+ * partial upgrade: rerun the same snapshots to recognize exact completed bytes.
+ * Each replacement is atomic on a local filesystem; the complete upgrade is not.
+ * An abrupt process termination can leave a uniquely named temporary file; it is
+ * never treated as a managed app file or resumed operation.
+ * No SQL, dependency install, version marker, deployment or user hook is executed.
+ */
+export async function applyAppUpgrade(input: AppUpgradeInput): Promise<{ plan: AppUpgradePlan; applied: string[] }> {
+  const { root, plan, target } = await inspectUpgrade(input);
+  if (plan.conflicts.length) throw new AppUpgradeConflictError(plan.conflicts);
+  const applied: string[] = [];
+  for (const file of plan.files) {
+    const destination = join(root, file.path);
+    if (file.action === "remove") {
+      await fs.unlink(destination);
+    } else if (file.action === "create" || file.action === "replace") {
+      await fs.mkdir(dirname(destination), { recursive: true });
+      const temporary = join(dirname(destination), `.openlup-${randomUUID()}.tmp`);
+      // Rename replaces this directory entry rather than modifying a possible hardlink.
+      const mode = file.action === "replace" ? (await fs.stat(destination)).mode & 0o777 : 0o600;
+      let handle;
+      try {
+        handle = await fs.open(temporary, "wx", mode);
+        if (file.action === "replace") await handle.chmod(mode);
+        await handle.writeFile(target.get(file.path)!, "utf8");
+        await handle.close();
+        await fs.rename(temporary, destination);
+      } finally {
+        if (handle) {
+          await handle.close();
+          await fs.rm(temporary, { force: true });
+        }
+      }
+    } else continue;
+    applied.push(file.path);
+  }
+  return { plan, applied };
+}
+
+async function inspectUpgrade(input: AppUpgradeInput): Promise<{
+  root: string; plan: AppUpgradePlan; target: Map<string, string>;
+}> {
+  const before = snapshotFiles(input.from), target = snapshotFiles(input.to);
+  const paths = [...new Set([...before.keys(), ...target.keys()])].sort();
+  const aliases = new Set<string>();
+  for (const path of paths) {
+    const alias = path.normalize("NFC").toLowerCase().toUpperCase();
+    if (aliases.has(alias)) throw new Error(`Application upgrade path alias: ${path}`);
+    aliases.add(alias);
+  }
+  const directorySpellings = new Map<string, string>();
+  for (const path of paths) {
+    const components = path.split("/");
+    while (components.length > 1) {
+      components.pop();
+      const directory = components.join("/"), alias = directory.normalize("NFC").toLowerCase().toUpperCase();
+      if (aliases.has(alias)) throw new Error(`Application upgrade file-parent collision: ${path}`);
+      // Parents may not exist yet; both snapshots must still agree on their spelling.
+      const spelling = directorySpellings.get(alias);
+      if (spelling !== undefined && spelling !== directory) throw new Error(`Application upgrade path alias: ${path}`);
+      directorySpellings.set(alias, directory);
+    }
+  }
+  if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 0) throw new Error("Application schema version must be a nonnegative safe integer");
+  const plan: AppUpgradePlan = {
+    fromVersion: input.from.version, toVersion: input.to.version,
+    schemaVersion: input.schemaVersion, files: [], conflicts: [],
+  };
+  for (const snapshot of [input.from, input.to]) {
+    if (input.schemaVersion < snapshot.schema.min || input.schemaVersion > snapshot.schema.max) {
+      plan.conflicts.push({ path: "", reason: `schema ${input.schemaVersion} is outside ${snapshot.version} range ${snapshot.schema.min}..${snapshot.schema.max}` });
+    }
+  }
+  const requestedRoot = resolve(input.root), rootStat = await fs.lstat(requestedRoot);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) throw new Error("Application upgrade root must be an ordinary directory");
+  const root = await fs.realpath(requestedRoot);
+  if (input.root !== root) throw new Error("Application upgrade root must be an absolute canonical path");
+  for (const path of paths) {
+    const observed = await readFile(root, path);
+    if (typeof observed === "string") {
+      plan.conflicts.push({ path, reason: observed });
+      continue;
+    }
+    const oldBytes = before.has(path) ? Buffer.from(before.get(path)!, "utf8") : null;
+    const newBytes = target.has(path) ? Buffer.from(target.get(path)!, "utf8") : null;
+    const equal = (bytes: Buffer | null) => observed === null ? bytes === null : bytes !== null && observed.equals(bytes);
+    let action: AppUpgradeAction;
+    if (oldBytes !== null && newBytes !== null && oldBytes.equals(newBytes)) {
+      // An upstream-unchanged file carries no write authority over local customization.
+      action = equal(oldBytes) ? "unchanged" : "preserved";
+    } else if (equal(newBytes)) action = "already-applied";
+    else if (equal(oldBytes)) action = newBytes === null ? "remove" : oldBytes === null ? "create" : "replace";
+    else {
+      plan.conflicts.push({ path, reason: "current bytes match neither predecessor nor candidate" });
+      continue;
+    }
+    plan.files.push({ path, action });
+  }
+  return { root, plan, target };
+}
+
+function snapshotFiles(snapshot: AppVersionSnapshot): Map<string, string> {
+  if (!snapshot || typeof snapshot.version !== "string" || !snapshot.version.trim()) throw new Error("Application snapshot needs an explicit version");
+  const range = snapshot.schema;
+  if (!range || !Number.isSafeInteger(range.min) || !Number.isSafeInteger(range.max) || range.min < 0 || range.max < range.min) throw new Error("Application snapshot needs an ordered nonnegative schema range");
+  if (!snapshot.files || typeof snapshot.files !== "object" || Array.isArray(snapshot.files)) throw new Error("Application snapshot files must be a record");
+  const result = new Map<string, string>();
+  for (const [path, content] of Object.entries(snapshot.files)) {
+    const segments = path.split("/");
+    if (!path || Buffer.from(path, "utf8").toString("utf8") !== path || /[\\:]/u.test(path) || [...path].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) || segments.some(segment => !segment || segment === "." || segment === ".." || /[. ]$/u.test(segment)) || segments.some(segment => [".git", "node_modules"].includes(segment.toLowerCase()))) {
+      throw new Error(`Unsafe application upgrade path: ${path}`);
+    }
+    if (typeof content !== "string" || Buffer.from(content, "utf8").toString("utf8") !== content) throw new Error(`Application upgrade content must be valid UTF-8: ${path}`);
+    result.set(path, content);
+  }
+  return result;
+}
+
+/** A string is a structural refusal; null means an absent path. Never follow links. */
+async function readFile(root: string, path: string): Promise<Buffer | null | string> {
+  const segments = path.split("/");
+  let current = root;
+  for (const [index, segment] of segments.entries()) {
+    const parent = current;
+    current = join(current, segment);
+    let stat;
+    try { stat = await fs.lstat(current); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+    // A filesystem alias is not ownership of the differently spelled entry.
+    // Check only after lstat: ENOENT on a case-sensitive store stays absence.
+    if (!(await fs.readdir(parent)).includes(segment)) return "managed path spelling differs from directory entry";
+    if (stat.isSymbolicLink()) return "symlink in managed path";
+    const last = index === segments.length - 1;
+    if (last) return stat.isFile() ? fs.readFile(current) : "managed path is not a regular file";
+    if (!stat.isDirectory()) return "managed parent is not a directory";
+  }
+  return null;
+}

package/src/lifecycle/index.ts

@@ -0,0 +1,19 @@
+export {
+  planAppUpgrade,
+  applyAppUpgrade,
+  AppUpgradeConflictError,
+  type AppVersionSnapshot,
+  type AppUpgradeInput,
+  type AppUpgradeAction,
+  type AppUpgradeConflict,
+  type AppUpgradePlan,
+} from "./appUpgrade.js";
+export {
+  inspectLegacyPostgresInstallRoles,
+  type PostgresInstallQuery,
+  type LegacyPostgresInstallRequest,
+  type PostgresInstallRoleObservation,
+  type PostgresInstallMembershipObservation,
+  type LegacyPostgresInstallBlocker,
+  type LegacyPostgresInstallRoleReport,
+} from "./postgresInstallQualification.js";

package/src/lifecycle/postgresInstallQualification.ts

@@ -0,0 +1,125 @@
+/** Read-only prerequisites of the immutable legacy fresh-install bootstrap, not install readiness. */
+export interface PostgresInstallQuery {
+  query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export interface LegacyPostgresInstallRequest {
+  /** Expected actual login: both current_user and session_user must match. */
+  migrationLogin: string;
+  /** Legacy bootstrap requires this to be the same login as the migrator. */
+  runtimeLogin: string;
+  roleMode: "installer-managed" | "operator-provisioned";
+}
+
+export interface PostgresInstallRoleObservation {
+  name: string;
+  login: boolean;
+  superuser: boolean;
+  inherit: boolean;
+  createRole: boolean;
+  createDatabase: boolean;
+  replication: boolean;
+  bypassRls: boolean;
+}
+
+export interface PostgresInstallMembershipObservation {
+  role: string;
+  member: string;
+  grantor: string;
+  admin: boolean;
+  inherit: boolean;
+  set: boolean;
+}
+
+export type LegacyPostgresInstallBlocker =
+  | "migration_login_mismatch"
+  | "legacy_bootstrap_requires_superuser"
+  | "legacy_bootstrap_requires_shared_runtime_login"
+  | "runtime_login_missing_or_not_login"
+  | "legacy_bootstrap_requires_installer_managed_roles"
+  | "legacy_bootstrap_role_already_exists";
+
+export interface LegacyPostgresInstallRoleReport {
+  scope: "legacy-fresh-bootstrap-role-prerequisites";
+  database: string;
+  currentUser: string;
+  sessionUser: string;
+  roles: PostgresInstallRoleObservation[];
+  memberships: PostgresInstallMembershipObservation[];
+  blockers: { code: LegacyPostgresInstallBlocker; role?: string }[];
+  rolePrerequisitesMet: boolean;
+}
+
+const BOOTSTRAP_ROLES = ["anon", "authenticated", "platform_acquisition_owner", "platform_acquisition_runtime"];
+// One statement observes identities and the relevant role graph in the same statement snapshot.
+// No SQL, identifiers, credentials or catalog expectations come from the caller.
+// Bind functions, cast types and operators independently of the caller's search_path.
+const OBSERVE = `SELECT pg_catalog.current_database() AS database, current_user::pg_catalog.text AS "currentUser",
+  session_user::pg_catalog.text AS "sessionUser",
+  (SELECT COALESCE(pg_catalog.jsonb_agg(pg_catalog.jsonb_build_object('name', rolname, 'login', rolcanlogin,
+    'superuser', rolsuper, 'inherit', rolinherit, 'createRole', rolcreaterole,
+    'createDatabase', rolcreatedb, 'replication', rolreplication, 'bypassRls', rolbypassrls)
+    ORDER BY rolname), '[]'::pg_catalog.jsonb) FROM pg_catalog.pg_roles
+    WHERE rolname OPERATOR(pg_catalog.=) ANY($1::pg_catalog.text[]) OR rolname OPERATOR(pg_catalog.=) current_user) AS roles,
+  (SELECT COALESCE(pg_catalog.jsonb_agg(pg_catalog.jsonb_build_object('role', granted.rolname, 'member', member.rolname,
+    'grantor', grantor.rolname, 'admin', m.admin_option, 'inherit', m.inherit_option, 'set', m.set_option)
+    ORDER BY granted.rolname, member.rolname, grantor.rolname), '[]'::pg_catalog.jsonb)
+    FROM pg_catalog.pg_auth_members m
+    JOIN pg_catalog.pg_roles granted ON granted.oid OPERATOR(pg_catalog.=) m.roleid
+    JOIN pg_catalog.pg_roles member ON member.oid OPERATOR(pg_catalog.=) m.member
+    JOIN pg_catalog.pg_roles grantor ON grantor.oid OPERATOR(pg_catalog.=) m.grantor
+    WHERE granted.rolname OPERATOR(pg_catalog.=) ANY($1::pg_catalog.text[])
+      OR member.rolname OPERATOR(pg_catalog.=) ANY($1::pg_catalog.text[])) AS memberships`;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validRows<T>(value: unknown, texts: string[], flags: string[]): value is T[] {
+  return Array.isArray(value) && value.every(row => isRecord(row)
+    && texts.every(key => typeof row[key] === "string" && row[key].length > 0)
+    && flags.every(key => typeof row[key] === "boolean"));
+}
+
+/**
+ * Observes PostgreSQL 16+ legacy role prerequisites without changing the database.
+ * A true result says nothing about schema inventory, object ACLs, pooling, import safety or hosting.
+ * Query/driver errors are redacted because they can contain connection credentials.
+ */
+export async function inspectLegacyPostgresInstallRoles(
+  db: PostgresInstallQuery,
+  request: LegacyPostgresInstallRequest,
+): Promise<LegacyPostgresInstallRoleReport> {
+  if (![request.migrationLogin, request.runtimeLogin].every(name => typeof name === "string" && name.trim().length > 0)
+    || !["installer-managed", "operator-provisioned"].includes(request.roleMode)) {
+    throw new Error("postgres_install_request_invalid");
+  }
+  let rows: Record<string, unknown>[];
+  try {
+    ({ rows } = await db.query(OBSERVE, [[...new Set([...BOOTSTRAP_ROLES, request.migrationLogin, request.runtimeLogin])]]));
+  } catch {
+    throw new Error("postgres_install_observation_failed");
+  }
+  const row = rows[0];
+  if (rows.length !== 1 || !row
+    || ![row.database, row.currentUser, row.sessionUser].every(value => typeof value === "string" && value.length > 0)
+    || !validRows<PostgresInstallRoleObservation>(row.roles, ["name"], ["login", "superuser", "inherit", "createRole", "createDatabase", "replication", "bypassRls"])
+    || !validRows<PostgresInstallMembershipObservation>(row.memberships, ["role", "member", "grantor"], ["admin", "inherit", "set"])) {
+    throw new Error("postgres_install_observation_invalid");
+  }
+  const roles = row.roles;
+  const blockers: LegacyPostgresInstallRoleReport["blockers"] = [];
+  if (row.currentUser !== request.migrationLogin || row.sessionUser !== request.migrationLogin) blockers.push({ code: "migration_login_mismatch" });
+  if (!roles.some(role => role.name === row.currentUser && role.superuser)) blockers.push({ code: "legacy_bootstrap_requires_superuser" });
+  if (row.currentUser !== request.runtimeLogin) blockers.push({ code: "legacy_bootstrap_requires_shared_runtime_login" });
+  if (!roles.some(role => role.name === request.runtimeLogin && role.login)) blockers.push({ code: "runtime_login_missing_or_not_login" });
+  if (request.roleMode !== "installer-managed") blockers.push({ code: "legacy_bootstrap_requires_installer_managed_roles" });
+  for (const name of BOOTSTRAP_ROLES) {
+    if (roles.some(role => role.name === name)) blockers.push({ code: "legacy_bootstrap_role_already_exists", role: name });
+  }
+  return {
+    scope: "legacy-fresh-bootstrap-role-prerequisites",
+    database: row.database as string, currentUser: row.currentUser as string, sessionUser: row.sessionUser as string,
+    roles, memberships: row.memberships, blockers, rolePrerequisitesMet: blockers.length === 0,
+  };
+}

package/src/migrations/postgresRunner.ts

@@ -34,6 +34,13 @@ export interface PlatformMigrationSource {
     migrations: readonly PlatformMigrationFile[];
     objectInventoryPayload?: string;
   }): string[];
+  /**
+   * Optional trusted-source observation/refusal after exact-prefix validation, under the
+   * migration session lock. Runs once per operation before any pending SQL or dry-run result.
+   * The canonical source uses read-only observations; the callback shares the caller's existing
+   * database capability and is not a sandbox or a provisioning/per-unit execution hook.
+   */
+  assertSession?(client: PoolClient, applied: readonly (PlatformMigrationManifestEntry & { position: number })[]): Promise<void>;
 }
 
 export interface PostgresMigrationRunnerOptions {
@@ -60,6 +67,9 @@ type LedgerExistenceRow = { ledger_exists: unknown };
 type AdvisoryUnlockRow = { unlocked: unknown };
 const ACQUIRE_MIGRATION_LOCK = "SELECT pg_advisory_lock(hashtextextended($1, 0))";
 const RELEASE_MIGRATION_LOCK = "SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS unlocked";
+const ACQUIRE_CATALOG_BOUND_MIGRATION_LOCK = "SELECT pg_catalog.pg_advisory_lock(pg_catalog.hashtextextended($1::pg_catalog.text, 0::pg_catalog.int8))";
+const RELEASE_CATALOG_BOUND_MIGRATION_LOCK = "SELECT pg_catalog.pg_advisory_unlock(pg_catalog.hashtextextended($1::pg_catalog.text, 0::pg_catalog.int8)) AS unlocked";
+const CATALOG_BOUND_LEDGER_EXISTENCE = "SELECT pg_catalog.to_regclass($1::pg_catalog.text) IS NOT NULL AS ledger_exists";
 
 export function createPostgresMigrationRunner(
   env: PostgresMigrationRunnerEnv,
@@ -79,8 +89,10 @@ export function createPostgresMigrationRunner(
     async status(): Promise<{ pending: string[]; applied: string[] }> {
       assertConnectionString(env);
       const plan = loadPlan(root, options.source);
-      return withMigrationSession(await getPool(), options.lockName, async (client) => {
-        const applied = await readAppliedPrefix(client, plan.units);
+      const catalogBoundSession = options.source.assertSession !== undefined;
+      return withMigrationSession(await getPool(), options.lockName, catalogBoundSession, async (client) => {
+        const applied = await readAppliedPrefix(client, plan.units, catalogBoundSession);
+        await options.source.assertSession?.(client, applied.map((unit) => ({ file: unit.catalogPath, sha256: unit.sha256, position: unit.position })));
         if (applied.length === plan.units.length) await assertObjectInventory(client, plan, options);
         return {
           pending: plan.units.slice(applied.length).map((unit) => unit.catalogPath),
@@ -92,8 +104,10 @@ export function createPostgresMigrationRunner(
     async apply(opts?: { dryRun?: boolean }): Promise<{ applied: string[] }> {
       assertConnectionString(env);
       const plan = loadPlan(root, options.source);
-      return withMigrationSession(await getPool(), options.lockName, async (client) => {
-        const already = await readAppliedPrefix(client, plan.units);
+      const catalogBoundSession = options.source.assertSession !== undefined;
+      return withMigrationSession(await getPool(), options.lockName, catalogBoundSession, async (client) => {
+        const already = await readAppliedPrefix(client, plan.units, catalogBoundSession);
+        await options.source.assertSession?.(client, already.map((unit) => ({ file: unit.catalogPath, sha256: unit.sha256, position: unit.position })));
         const pending = plan.units.slice(already.length);
         if (opts?.dryRun) {
           if (pending.length === 0) await assertObjectInventory(client, plan, options);
@@ -115,7 +129,7 @@ export function createPostgresMigrationRunner(
             throw new Error(`platform migration ${unit.catalogPath} failed: ${errorMessage(error)}`);
           }
         }
-        const complete = await readAppliedPrefix(client, plan.units);
+        const complete = await readAppliedPrefix(client, plan.units, catalogBoundSession);
         if (complete.length !== plan.units.length) throw new Error("platform migration ledger is incomplete after apply");
         await assertObjectInventory(client, plan, options);
         return { applied: appliedNow };
@@ -127,6 +141,7 @@ export function createPostgresMigrationRunner(
 async function withMigrationSession<T>(
   pool: Pool,
   lockName: string,
+  catalogBoundSession: boolean,
   operation: (client: PoolClient) => Promise<T>,
 ): Promise<T> {
   const client = await pool.connect();
@@ -135,7 +150,7 @@ async function withMigrationSession<T>(
   let operationFailure: unknown;
   let result!: T;
   try {
-    await client.query(ACQUIRE_MIGRATION_LOCK, [lockName]);
+    await client.query(catalogBoundSession ? ACQUIRE_CATALOG_BOUND_MIGRATION_LOCK : ACQUIRE_MIGRATION_LOCK, [lockName]);
     locked = true;
     result = await operation(client);
   } catch (error) {
@@ -146,7 +161,7 @@ async function withMigrationSession<T>(
   let unlockFailure: unknown;
   if (locked) {
     try {
-      const unlocked = await client.query<AdvisoryUnlockRow>(RELEASE_MIGRATION_LOCK, [lockName]);
+      const unlocked = await client.query<AdvisoryUnlockRow>(catalogBoundSession ? RELEASE_CATALOG_BOUND_MIGRATION_LOCK : RELEASE_MIGRATION_LOCK, [lockName]);
       if (unlocked.rows[0]?.unlocked !== true) throw new Error("PostgreSQL did not release the advisory lock");
     } catch (error) {
       unlockFailure = error;
@@ -194,9 +209,9 @@ function loadPlan(root: string, source: PlatformMigrationSource): LoadedPlan {
   return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
 }
 
-async function readAppliedPrefix(client: PoolClient, units: readonly PlannedMigration[]): Promise<readonly PlannedMigration[]> {
+async function readAppliedPrefix(client: PoolClient, units: readonly PlannedMigration[], catalogBoundSession: boolean): Promise<readonly PlannedMigration[]> {
   const exists = await client.query<LedgerExistenceRow>(
-    "SELECT to_regclass($1) IS NOT NULL AS ledger_exists",
+    catalogBoundSession ? CATALOG_BOUND_LEDGER_EXISTENCE : "SELECT to_regclass($1) IS NOT NULL AS ledger_exists",
     [LEDGER],
   );
   if (exists.rows[0]?.ledger_exists !== true) return [];

package/src/operations/adminAlertsSchemas.ts

@@ -0,0 +1,78 @@
+import { z } from "./validation.js";
+
+/**
+ * Admin-facing projection of the platform alert ledger.
+ *
+ * Only what an operator needs to read; the ledger itself stays service-role only
+ * (platform_alerts REVOKEs ALL from `authenticated`), so this shape is served by
+ * /api/bff/admin/platform/alerts rather than by PostgREST.
+ */
+
+export const adminAlertSeveritySchema = z.enum(["p0", "p1", "p2", "p3"]);
+
+/**
+ * Audience split, derived from `platform_alerts.owner`:
+ *   commerce -> a business operator can act on it
+ *   platform -> engineering owns it; shown for context so the health pill is explainable
+ */
+export const adminAlertLaneSchema = z.enum(["commerce", "platform"]);
+
+export const adminAlertHealthSchema = z.enum(["ok", "degraded", "down", "unknown"]);
+
+const isoDateTimeSchema = z.string().datetime({ offset: true });
+
+export const adminAlertSchema = z
+  .object({
+    id: z.string().min(1).max(128),
+    dedupeKey: z.string().min(1).max(256),
+    lane: adminAlertLaneSchema,
+    // Free text on purpose: platform_alerts.owner has no CHECK constraint, so an
+    // enum here would throw the whole admin shell on the first new owner string.
+    // The open-endedness is absorbed by `lane`.
+    owner: z.string().trim().min(1).max(128),
+    severity: adminAlertSeveritySchema,
+    status: z.enum(["open", "acknowledged"]),
+    // Server-decided so every consumer agrees; the client never re-derives it.
+    pageable: z.boolean(),
+    title: z.string().trim().min(1).max(512),
+    message: z.string().trim().max(4096),
+    supportCode: z.string().trim().max(128).nullable(),
+    runbookUrl: z.string().trim().max(1024).nullable(),
+    firstSeenAt: isoDateTimeSchema,
+    lastSeenAt: isoDateTimeSchema,
+    snoozedUntil: isoDateTimeSchema.nullable(),
+  })
+  .strict();
+
+export const adminAlertsHeartbeatSchema = z
+  .object({
+    lastSuccessAt: isoDateTimeSchema.nullable(),
+    staleAfterSeconds: z.number().int().positive(),
+    stale: z.boolean(),
+  })
+  .strict();
+
+export const adminAlertsSummarySchema = z
+  .object({
+    /** Drives the bell badge. */
+    commercePageableCount: z.number().int().min(0),
+    commerceTotalCount: z.number().int().min(0),
+    platformPageableCount: z.number().int().min(0),
+    /** Visible controlled exceptions; excluded from paging and health degradation. */
+    snoozedCount: z.number().int().min(0),
+    maxOpenSeverity: adminAlertSeveritySchema.nullable(),
+  })
+  .strict();
+
+export const adminAlertsOverviewResponseSchema = z
+  .object({
+    health: adminAlertHealthSchema,
+    summary: adminAlertsSummarySchema,
+    heartbeat: adminAlertsHeartbeatSchema,
+    alerts: z.array(adminAlertSchema).max(50),
+    // Snoozed rows are returned separately from the active-list cap so a
+    // controlled exception never disappears behind routine diagnostics.
+    snoozedAlerts: z.array(adminAlertSchema).max(200),
+    generatedAt: isoDateTimeSchema,
+  })
+  .strict();