@openlup/platform 0.29.0 → 0.30.0

package/dist/lifecycle/appUpgrade.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export class AppUpgradeConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`Application upgrade refused: ${conflicts.map(({ path, reason }) => `${path || "schema"}: ${reason}`).join("; ")}`);
+        this.conflicts = conflicts;
+        this.name = "AppUpgradeConflictError";
+    }
+}
+/** Read-only comparison of explicit predecessor and candidate snapshots. */
+export async function planAppUpgrade(input) {
+    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) {
+    const { root, plan, target } = await inspectUpgrade(input);
+    if (plan.conflicts.length)
+        throw new AppUpgradeConflictError(plan.conflicts);
+    const applied = [];
+    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) {
+    const before = snapshotFiles(input.from), target = snapshotFiles(input.to);
+    const paths = [...new Set([...before.keys(), ...target.keys()])].sort();
+    const aliases = new Set();
+    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();
+    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 = {
+        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) => observed === null ? bytes === null : bytes !== null && observed.equals(bytes);
+        let action;
+        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) {
+    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();
+    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, path) {
+    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.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/dist/lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+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/dist/lifecycle/index.js

@@ -0,0 +1,2 @@
+export { planAppUpgrade, applyAppUpgrade, AppUpgradeConflictError, } from "./appUpgrade.js";
+export { inspectLegacyPostgresInstallRoles, } from "./postgresInstallQualification.js";

package/dist/lifecycle/postgresInstallQualification.d.ts

@@ -0,0 +1,51 @@
+/** 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;
+}
+/**
+ * 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 declare function inspectLegacyPostgresInstallRoles(db: PostgresInstallQuery, request: LegacyPostgresInstallRequest): Promise<LegacyPostgresInstallRoleReport>;

package/dist/lifecycle/postgresInstallQualification.js

@@ -0,0 +1,74 @@
+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) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validRows(value, texts, flags) {
+    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, request) {
+    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;
+    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(row.roles, ["name"], ["login", "superuser", "inherit", "createRole", "createDatabase", "replication", "bypassRls"])
+        || !validRows(row.memberships, ["role", "member", "grantor"], ["admin", "inherit", "set"])) {
+        throw new Error("postgres_install_observation_invalid");
+    }
+    const roles = row.roles;
+    const 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, currentUser: row.currentUser, sessionUser: row.sessionUser,
+        roles, memberships: row.memberships, blockers, rolePrerequisitesMet: blockers.length === 0,
+    };
+}

package/dist/migrations/postgresRunner.d.ts

@@ -34,6 +34,15 @@ 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 {
     /** Name of the PostgreSQL advisory lock that serializes migration sessions. */

package/dist/migrations/postgresRunner.js

@@ -6,6 +6,9 @@
 const LEDGER = "public.platform_schema_migrations";
 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, options) {
     const root = options.root ?? process.cwd();
     let pool = null;
@@ -20,8 +23,10 @@ export function createPostgresMigrationRunner(env, options) {
         async status() {
             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 {
@@ -33,8 +38,10 @@ export function createPostgresMigrationRunner(env, options) {
         async apply(opts) {
             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)
@@ -55,7 +62,7 @@ export function createPostgresMigrationRunner(env, options) {
                         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);
@@ -64,14 +71,14 @@ export function createPostgresMigrationRunner(env, options) {
         },
     };
 }
-async function withMigrationSession(pool, lockName, operation) {
+async function withMigrationSession(pool, lockName, catalogBoundSession, operation) {
     const client = await pool.connect();
     let locked = false;
     let failed = false;
     let operationFailure;
     let result;
     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);
     }
@@ -82,7 +89,7 @@ async function withMigrationSession(pool, lockName, operation) {
     let unlockFailure;
     if (locked) {
         try {
-            const unlocked = await client.query(RELEASE_MIGRATION_LOCK, [lockName]);
+            const unlocked = await client.query(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");
         }
@@ -128,8 +135,8 @@ function loadPlan(root, source) {
     }));
     return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
 }
-async function readAppliedPrefix(client, units) {
-    const exists = await client.query("SELECT to_regclass($1) IS NOT NULL AS ledger_exists", [LEDGER]);
+async function readAppliedPrefix(client, units, catalogBoundSession) {
+    const exists = await client.query(catalogBoundSession ? CATALOG_BOUND_LEDGER_EXISTENCE : "SELECT to_regclass($1) IS NOT NULL AS ledger_exists", [LEDGER]);
     if (exists.rows[0]?.ledger_exists !== true)
         return [];
     const result = await client.query(`SELECT catalog_path, sha256, position FROM ${LEDGER} ORDER BY position`);

package/dist/operations/adminAlertsSchemas.d.ts

@@ -0,0 +1,153 @@
+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 declare const adminAlertSeveritySchema: z.ZodEnum<{
+    p0: "p0";
+    p1: "p1";
+    p2: "p2";
+    p3: "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 declare const adminAlertLaneSchema: z.ZodEnum<{
+    commerce: "commerce";
+    platform: "platform";
+}>;
+export declare const adminAlertHealthSchema: z.ZodEnum<{
+    unknown: "unknown";
+    ok: "ok";
+    degraded: "degraded";
+    down: "down";
+}>;
+export declare const adminAlertSchema: z.ZodObject<{
+    id: z.ZodString;
+    dedupeKey: z.ZodString;
+    lane: z.ZodEnum<{
+        commerce: "commerce";
+        platform: "platform";
+    }>;
+    owner: z.ZodString;
+    severity: z.ZodEnum<{
+        p0: "p0";
+        p1: "p1";
+        p2: "p2";
+        p3: "p3";
+    }>;
+    status: z.ZodEnum<{
+        open: "open";
+        acknowledged: "acknowledged";
+    }>;
+    pageable: z.ZodBoolean;
+    title: z.ZodString;
+    message: z.ZodString;
+    supportCode: z.ZodNullable<z.ZodString>;
+    runbookUrl: z.ZodNullable<z.ZodString>;
+    firstSeenAt: z.ZodString;
+    lastSeenAt: z.ZodString;
+    snoozedUntil: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const adminAlertsHeartbeatSchema: z.ZodObject<{
+    lastSuccessAt: z.ZodNullable<z.ZodString>;
+    staleAfterSeconds: z.ZodNumber;
+    stale: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const adminAlertsSummarySchema: z.ZodObject<{
+    commercePageableCount: z.ZodNumber;
+    commerceTotalCount: z.ZodNumber;
+    platformPageableCount: z.ZodNumber;
+    snoozedCount: z.ZodNumber;
+    maxOpenSeverity: z.ZodNullable<z.ZodEnum<{
+        p0: "p0";
+        p1: "p1";
+        p2: "p2";
+        p3: "p3";
+    }>>;
+}, z.core.$strict>;
+export declare const adminAlertsOverviewResponseSchema: z.ZodObject<{
+    health: z.ZodEnum<{
+        unknown: "unknown";
+        ok: "ok";
+        degraded: "degraded";
+        down: "down";
+    }>;
+    summary: z.ZodObject<{
+        commercePageableCount: z.ZodNumber;
+        commerceTotalCount: z.ZodNumber;
+        platformPageableCount: z.ZodNumber;
+        snoozedCount: z.ZodNumber;
+        maxOpenSeverity: z.ZodNullable<z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>>;
+    }, z.core.$strict>;
+    heartbeat: z.ZodObject<{
+        lastSuccessAt: z.ZodNullable<z.ZodString>;
+        staleAfterSeconds: z.ZodNumber;
+        stale: z.ZodBoolean;
+    }, z.core.$strict>;
+    alerts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        dedupeKey: z.ZodString;
+        lane: z.ZodEnum<{
+            commerce: "commerce";
+            platform: "platform";
+        }>;
+        owner: z.ZodString;
+        severity: z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>;
+        status: z.ZodEnum<{
+            open: "open";
+            acknowledged: "acknowledged";
+        }>;
+        pageable: z.ZodBoolean;
+        title: z.ZodString;
+        message: z.ZodString;
+        supportCode: z.ZodNullable<z.ZodString>;
+        runbookUrl: z.ZodNullable<z.ZodString>;
+        firstSeenAt: z.ZodString;
+        lastSeenAt: z.ZodString;
+        snoozedUntil: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    snoozedAlerts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        dedupeKey: z.ZodString;
+        lane: z.ZodEnum<{
+            commerce: "commerce";
+            platform: "platform";
+        }>;
+        owner: z.ZodString;
+        severity: z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>;
+        status: z.ZodEnum<{
+            open: "open";
+            acknowledged: "acknowledged";
+        }>;
+        pageable: z.ZodBoolean;
+        title: z.ZodString;
+        message: z.ZodString;
+        supportCode: z.ZodNullable<z.ZodString>;
+        runbookUrl: z.ZodNullable<z.ZodString>;
+        firstSeenAt: z.ZodString;
+        lastSeenAt: z.ZodString;
+        snoozedUntil: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    generatedAt: z.ZodString;
+}, z.core.$strict>;

package/dist/operations/adminAlertsSchemas.js

@@ -0,0 +1,69 @@
+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();