@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/runtime-components.d.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+export declare const runtimeCapabilityIdSchema: z.core.$ZodBranded<z.ZodString, "RuntimeCapabilityId", "out">;
+export declare const runtimeComponentIdSchema: z.core.$ZodBranded<z.ZodString, "RuntimeComponentId", "out">;
+export type RuntimeCapabilityId = z.infer<typeof runtimeCapabilityIdSchema>;
+export type RuntimeComponentId = z.infer<typeof runtimeComponentIdSchema>;
+export declare const RUNTIME_COMPONENT_V1_REQUIRED_IDS: readonly ["wordpress-core", "runtime-engine", "immutable-loader", "content-kernel", "managed-theme", "secure-custom-fields", "redirection", "block-transformer", "quickjs-abi"];
+export declare const RUNTIME_COMPONENT_KINDS: readonly ["wordpress-core", "runtime-engine", "mu-plugin", "plugin", "theme", "block-transformer", "quickjs-abi"];
+export declare const runtimeComponentKindSchema: z.ZodEnum<{
+    plugin: "plugin";
+    theme: "theme";
+    "wordpress-core": "wordpress-core";
+    "runtime-engine": "runtime-engine";
+    "block-transformer": "block-transformer";
+    "quickjs-abi": "quickjs-abi";
+    "mu-plugin": "mu-plugin";
+}>;
+export type RuntimeComponentKind = z.infer<typeof runtimeComponentKindSchema>;
+export declare const runtimeComponentV1Schema: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "RuntimeComponentId", "out">;
+    kind: z.ZodEnum<{
+        plugin: "plugin";
+        theme: "theme";
+        "wordpress-core": "wordpress-core";
+        "runtime-engine": "runtime-engine";
+        "block-transformer": "block-transformer";
+        "quickjs-abi": "quickjs-abi";
+        "mu-plugin": "mu-plugin";
+    }>;
+    version: z.ZodString;
+    sha256: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"archive">;
+        url: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"embedded">;
+        path: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    provides: z.ZodArray<z.core.$ZodBranded<z.ZodString, "RuntimeCapabilityId", "out">>;
+    activation: z.ZodEnum<{
+        always: "always";
+        "on-demand": "on-demand";
+    }>;
+}, z.core.$strict>;
+export type RuntimeComponentV1 = z.infer<typeof runtimeComponentV1Schema>;
+export declare const runtimeComponentInventoryV1Schema: z.ZodObject<{
+    format: z.ZodLiteral<"spacefast.wordpress-components">;
+    version: z.ZodLiteral<1>;
+    platformRelease: z.ZodString;
+    digest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    components: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "RuntimeComponentId", "out">;
+        kind: z.ZodEnum<{
+            plugin: "plugin";
+            theme: "theme";
+            "wordpress-core": "wordpress-core";
+            "runtime-engine": "runtime-engine";
+            "block-transformer": "block-transformer";
+            "quickjs-abi": "quickjs-abi";
+            "mu-plugin": "mu-plugin";
+        }>;
+        version: z.ZodString;
+        sha256: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+        source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"archive">;
+            url: z.ZodString;
+            bytes: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"embedded">;
+            path: z.ZodString;
+        }, z.core.$strict>], "kind">;
+        provides: z.ZodArray<z.core.$ZodBranded<z.ZodString, "RuntimeCapabilityId", "out">>;
+        activation: z.ZodEnum<{
+            always: "always";
+            "on-demand": "on-demand";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RuntimeComponentInventoryV1 = z.infer<typeof runtimeComponentInventoryV1Schema>;
+export declare const programRequirementsV1Schema: z.ZodObject<{
+    format: z.ZodLiteral<"spacefast.program-requirements">;
+    version: z.ZodLiteral<1>;
+    inputDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    wordpressAbi: z.ZodLiteral<1>;
+    capabilities: z.ZodArray<z.core.$ZodBranded<z.ZodString, "RuntimeCapabilityId", "out">>;
+}, z.core.$strict>;
+export type ProgramRequirementsV1 = z.infer<typeof programRequirementsV1Schema>;
+export declare const runtimeComponentPlacementTargetV1Schema: z.ZodObject<{
+    spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+    runtimeInstanceId: z.ZodString;
+    siteId: z.ZodString;
+}, z.core.$strict>;
+export type RuntimeComponentPlacementTargetV1 = z.infer<typeof runtimeComponentPlacementTargetV1Schema>;
+export declare const runtimeComponentPlacementReceiptV1Schema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"ready">;
+    observedInventoryDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+    substrate: z.ZodObject<{
+        wordpress: z.ZodObject<{
+            boot: z.ZodLiteral<"ready">;
+            database: z.ZodLiteral<"ready">;
+            tables: z.ZodLiteral<"ready">;
+        }, z.core.$strict>;
+        routing: z.ZodObject<{
+            state: z.ZodLiteral<"ready">;
+            snapshotRevision: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+            inventoryDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+        }, z.core.$strict>;
+        mail: z.ZodObject<{
+            state: z.ZodLiteral<"ready">;
+        }, z.core.$strict>;
+        journal: z.ZodObject<{
+            state: z.ZodLiteral<"ready">;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    format: z.ZodLiteral<"spacefast.component-placement">;
+    version: z.ZodLiteral<1>;
+    operationId: z.ZodString;
+    target: z.ZodObject<{
+        spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+        runtimeInstanceId: z.ZodString;
+        siteId: z.ZodString;
+    }, z.core.$strict>;
+    platformRelease: z.ZodString;
+    expectedInventoryDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"blocked">;
+    problems: z.ZodArray<z.ZodObject<{
+        componentId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RuntimeComponentId", "out">>;
+        code: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+    format: z.ZodLiteral<"spacefast.component-placement">;
+    version: z.ZodLiteral<1>;
+    operationId: z.ZodString;
+    target: z.ZodObject<{
+        spaceId: z.ZodTemplateLiteral<`spc_${string}`>;
+        runtimeInstanceId: z.ZodString;
+        siteId: z.ZodString;
+    }, z.core.$strict>;
+    platformRelease: z.ZodString;
+    expectedInventoryDigest: z.core.$ZodBranded<z.ZodString, "ContentProgramSha256", "out">;
+}, z.core.$strict>], "status">;
+export type RuntimeComponentPlacementReceiptV1 = z.infer<typeof runtimeComponentPlacementReceiptV1Schema>;

package/dist/contracts/runtime-components.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { contentProgramSha256Schema } from "./content-program.js";
+import { registeredIdSchema } from "./ids.js";
+export const runtimeCapabilityIdSchema = z
+    .string()
+    .min(1)
+    .max(160)
+    .regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/)
+    .brand();
+export const runtimeComponentIdSchema = z
+    .string()
+    .min(1)
+    .max(160)
+    .regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/)
+    .brand();
+export const RUNTIME_COMPONENT_V1_REQUIRED_IDS = [
+    "wordpress-core",
+    "runtime-engine",
+    "immutable-loader",
+    "content-kernel",
+    "managed-theme",
+    "secure-custom-fields",
+    "redirection",
+    "block-transformer",
+    "quickjs-abi",
+];
+export const RUNTIME_COMPONENT_KINDS = [
+    "wordpress-core",
+    "runtime-engine",
+    "mu-plugin",
+    "plugin",
+    "theme",
+    "block-transformer",
+    "quickjs-abi",
+];
+export const runtimeComponentKindSchema = z.enum(RUNTIME_COMPONENT_KINDS);
+const runtimeComponentV1RequiredKinds = {
+    "wordpress-core": "wordpress-core",
+    "runtime-engine": "runtime-engine",
+    "immutable-loader": "mu-plugin",
+    "content-kernel": "mu-plugin",
+    "managed-theme": "theme",
+    "secure-custom-fields": "plugin",
+    redirection: "plugin",
+    "block-transformer": "block-transformer",
+    "quickjs-abi": "quickjs-abi",
+};
+const runtimeComponentSourceSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("archive"),
+        url: z.string().url(),
+        bytes: z.number().int().positive(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("embedded"),
+        path: z
+            .string()
+            .min(1)
+            .max(512)
+            .refine((path) => !path.startsWith("/") && !path.split("/").includes(".."), {
+            message: "embedded component paths must be relative and cannot traverse",
+        }),
+    })
+        .strict(),
+]);
+export const runtimeComponentV1Schema = z
+    .object({
+    id: runtimeComponentIdSchema,
+    kind: runtimeComponentKindSchema,
+    version: z.string().min(1).max(160),
+    sha256: contentProgramSha256Schema,
+    source: runtimeComponentSourceSchema,
+    provides: z.array(runtimeCapabilityIdSchema).max(100),
+    activation: z.enum(["always", "on-demand"]),
+})
+    .strict()
+    .refine((component) => new Set(component.provides).size === component.provides.length, {
+    path: ["provides"],
+    message: "provided capabilities must be unique",
+});
+export const runtimeComponentInventoryV1Schema = z
+    .object({
+    format: z.literal("spacefast.wordpress-components"),
+    version: z.literal(1),
+    platformRelease: z.string().min(1).max(160),
+    digest: contentProgramSha256Schema,
+    components: z.array(runtimeComponentV1Schema).min(1).max(100),
+})
+    .strict()
+    .superRefine((inventory, context) => {
+    const ids = inventory.components.map((component) => component.id);
+    if (new Set(ids).size !== ids.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["components"],
+            message: "component ids must be unique",
+        });
+    }
+    for (const required of RUNTIME_COMPONENT_V1_REQUIRED_IDS) {
+        const matching = inventory.components.filter((component) => component.id === required);
+        if (matching.length !== 1) {
+            context.addIssue({
+                code: "custom",
+                path: ["components"],
+                message: `component inventory requires exactly one ${required} component`,
+            });
+        }
+        else if (matching[0]?.kind !== runtimeComponentV1RequiredKinds[required]) {
+            context.addIssue({
+                code: "custom",
+                path: ["components"],
+                message: `${required} must use component kind ${runtimeComponentV1RequiredKinds[required]}`,
+            });
+        }
+    }
+});
+export const programRequirementsV1Schema = z
+    .object({
+    format: z.literal("spacefast.program-requirements"),
+    version: z.literal(1),
+    inputDigest: contentProgramSha256Schema,
+    wordpressAbi: z.literal(1),
+    capabilities: z.array(runtimeCapabilityIdSchema).max(100),
+})
+    .strict()
+    .refine((requirements) => new Set(requirements.capabilities).size === requirements.capabilities.length, {
+    path: ["capabilities"],
+    message: "program capabilities must be unique",
+});
+export const runtimeComponentPlacementTargetV1Schema = z
+    .object({
+    spaceId: registeredIdSchema("spc"),
+    runtimeInstanceId: z.string().min(1).max(255),
+    siteId: z.string().min(1).max(255),
+})
+    .strict();
+const runtimeComponentPlacementReceiptFields = {
+    format: z.literal("spacefast.component-placement"),
+    version: z.literal(1),
+    operationId: z.string().min(1).max(160),
+    target: runtimeComponentPlacementTargetV1Schema,
+    platformRelease: z.string().min(1).max(160),
+    expectedInventoryDigest: contentProgramSha256Schema,
+};
+const readyPlacementSubstrateV1Schema = z
+    .object({
+    wordpress: z
+        .object({
+        boot: z.literal("ready"),
+        database: z.literal("ready"),
+        tables: z.literal("ready"),
+    })
+        .strict(),
+    routing: z
+        .object({
+        state: z.literal("ready"),
+        snapshotRevision: contentProgramSha256Schema,
+        inventoryDigest: contentProgramSha256Schema,
+    })
+        .strict(),
+    mail: z.object({ state: z.literal("ready") }).strict(),
+    journal: z.object({ state: z.literal("ready") }).strict(),
+})
+    .strict();
+export const runtimeComponentPlacementReceiptV1Schema = z
+    .discriminatedUnion("status", [
+    z
+        .object({
+        ...runtimeComponentPlacementReceiptFields,
+        status: z.literal("ready"),
+        observedInventoryDigest: contentProgramSha256Schema,
+        substrate: readyPlacementSubstrateV1Schema,
+    })
+        .strict(),
+    z
+        .object({
+        ...runtimeComponentPlacementReceiptFields,
+        status: z.literal("blocked"),
+        problems: z
+            .array(z
+            .object({
+            componentId: runtimeComponentIdSchema.optional(),
+            code: z.string().min(1).max(160),
+            detail: z.string().min(1).max(2_000),
+        })
+            .strict())
+            .min(1)
+            .max(100),
+    })
+        .strict(),
+])
+    .refine((receipt) => receipt.status !== "ready" ||
+    receipt.observedInventoryDigest === receipt.expectedInventoryDigest, {
+    path: ["observedInventoryDigest"],
+    message: "a ready receipt must observe the expected inventory digest",
+});

package/dist/contracts/runtime-db.d.ts

@@ -2,22 +2,33 @@ import { z } from "zod";
 /**
  * The database surface, for whichever runtime a space is carrying.
  *
- * There is one database per space — the site's own MySQL — and at most one
- * runtime with a claim on it, so these contracts are runtime-neutral by
- * default. The two exceptions are stated explicitly: a migration plan is a
- * capsule's declaration and no worker has one, and the console hand-off is a
- * property of the wp.cloud site rather than of anything a version declared.
+ * One database per space, the site's own MySQL, and at most one runtime with a
+ * claim on it, so these contracts are runtime-neutral. Two exceptions: a
+ * migration plan is a capsule's declaration and no worker has one, and the
+ * console hand-off is a property of the wp.cloud site.
  *
- * The reads answer in the capsule's declaration shapes (`zeroTableSchema`,
- * `zeroMigrationOperationSchema`) because a capsule's declared schema is the
- * richest answer either runtime can give and a worker's is the same answer with
- * the declaration-shaped fields empty. Those shapes stay Zero-named and stay in
- * `./zero.js`: a declared table is the capsule's own statement about itself.
+ * Reads answer in the capsule's declaration shapes (`zeroTableSchema`,
+ * `zeroMigrationOperationSchema`); a worker's answer is the same shape with the
+ * declaration-shaped fields empty.
  */
+/**
+ * Whether the live version's declared migration plan has actually run against
+ * the space database. `applied` compares the recorded application against the
+ * plan's target `schemaHash`; it is `null` when no application record exists —
+ * a version finalized before this record existed, or a finalize whose ready
+ * receipt was a replay — because the control plane then cannot prove the plan
+ * ran. Honest unknown, never a guess.
+ */
+export declare const runtimeDbPlanStateSchema: z.ZodObject<{
+    applied: z.ZodNullable<z.ZodBoolean>;
+    appliedSchemaHash: z.ZodNullable<z.ZodString>;
+    pendingOperationCount: z.ZodNumber;
+}, z.core.$strict>;
+export type RuntimeDbPlanState = z.infer<typeof runtimeDbPlanStateSchema>;
 export declare const runtimeDbInspectResponseSchema: z.ZodObject<{
     versionId: z.ZodNullable<z.ZodString>;
     artifactId: z.ZodNullable<z.ZodString>;
-    backend: z.ZodNullable<z.ZodLiteral<"wpcloud-mysql">>;
+    backend: z.ZodNullable<z.ZodLiteral<"mysql">>;
     migrationMode: z.ZodNullable<z.ZodEnum<{
         safe: "safe";
         drop: "drop";
@@ -91,13 +102,18 @@ export declare const runtimeDbInspectResponseSchema: z.ZodObject<{
         to: z.ZodString;
         explicit: z.ZodLiteral<"rename">;
     }, z.core.$strict>], "op">>>;
+    plan: z.ZodNullable<z.ZodObject<{
+        applied: z.ZodNullable<z.ZodBoolean>;
+        appliedSchemaHash: z.ZodNullable<z.ZodString>;
+        pendingOperationCount: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type RuntimeDbInspectResponse = z.infer<typeof runtimeDbInspectResponseSchema>;
 export declare const runtimeDbInspectPublicResponseSchema: z.ZodObject<{
     data: z.ZodObject<{
         versionId: z.ZodNullable<z.ZodString>;
         artifactId: z.ZodNullable<z.ZodString>;
-        backend: z.ZodNullable<z.ZodLiteral<"wpcloud-mysql">>;
+        backend: z.ZodNullable<z.ZodLiteral<"mysql">>;
         migrationMode: z.ZodNullable<z.ZodEnum<{
             safe: "safe";
             drop: "drop";
@@ -171,15 +187,24 @@ export declare const runtimeDbInspectPublicResponseSchema: z.ZodObject<{
             to: z.ZodString;
             explicit: z.ZodLiteral<"rename">;
         }, z.core.$strict>], "op">>>;
+        plan: z.ZodNullable<z.ZodObject<{
+            applied: z.ZodNullable<z.ZodBoolean>;
+            appliedSchemaHash: z.ZodNullable<z.ZodString>;
+            pendingOperationCount: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strip>;
 export declare const runtimeDbDumpQuerySchema: z.ZodObject<{
     table: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
+export type RuntimeDbCellValue = string | number | boolean | null | RuntimeDbCellValue[] | {
+    [key: string]: RuntimeDbCellValue;
+};
+export declare const runtimeDbCellValueSchema: z.ZodType<RuntimeDbCellValue>;
 export declare const runtimeDbDumpTableSchema: z.ZodObject<{
     name: z.ZodString;
-    rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodType<RuntimeDbCellValue, unknown, z.core.$ZodTypeInternals<RuntimeDbCellValue, unknown>>>>>;
 }, z.core.$strict>;
 export declare const runtimeDbDumpResponseSchema: z.ZodObject<{
     versionId: z.ZodNullable<z.ZodString>;
@@ -187,7 +212,7 @@ export declare const runtimeDbDumpResponseSchema: z.ZodObject<{
     schemaHash: z.ZodNullable<z.ZodString>;
     tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodType<RuntimeDbCellValue, unknown, z.core.$ZodTypeInternals<RuntimeDbCellValue, unknown>>>>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type RuntimeDbDumpResponse = z.infer<typeof runtimeDbDumpResponseSchema>;
@@ -198,7 +223,7 @@ export declare const runtimeDbDumpPublicResponseSchema: z.ZodObject<{
         schemaHash: z.ZodNullable<z.ZodString>;
         tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
-            rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            rows: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>;
 }, z.core.$strip>;
@@ -237,15 +262,16 @@ export declare const runtimeDbExportPageQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
 export declare const runtimeDbExportPageSchema: z.ZodObject<{
-    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodType<RuntimeDbCellValue, unknown, z.core.$ZodTypeInternals<RuntimeDbCellValue, unknown>>>>;
     cursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type RuntimeDbExportPage = z.infer<typeof runtimeDbExportPageSchema>;
 export declare const runtimeDbExportPagePublicResponseSchema: z.ZodObject<{
-    data: z.ZodObject<{
-        rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        cursor: z.ZodNullable<z.ZodString>;
-    }, z.core.$strict>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const runtimeDbMigrateResultSchema: z.ZodObject<{
     versionId: z.ZodString;
@@ -399,7 +425,7 @@ export declare const runtimeDbMigrateResponseSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;
@@ -412,13 +438,13 @@ export declare const runtimeDbMigrateResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const runtimeDbConsoleSchema: z.ZodObject<{
-    provider: z.ZodLiteral<"wpcloud-phpmyadmin">;
+    provider: z.ZodLiteral<"phpmyadmin">;
     url: z.ZodString;
 }, z.core.$strict>;
 export type RuntimeDbConsole = z.infer<typeof runtimeDbConsoleSchema>;
 export declare const runtimeDbConsoleResponseSchema: z.ZodObject<{
     data: z.ZodObject<{
-        provider: z.ZodLiteral<"wpcloud-phpmyadmin">;
+        provider: z.ZodLiteral<"phpmyadmin">;
         url: z.ZodString;
     }, z.core.$strict>;
 }, z.core.$strip>;

package/dist/contracts/runtime-db.js

@@ -1,44 +1,77 @@
 import { z } from "zod";
-import { dataEnvelope, mutationEnvelope } from "./common.js";
+import { CursorPaginationSchema, dataEnvelope, mutationEnvelope } from "./common.js";
 import { executionIdentifierSchema, executionSha256Schema } from "./execution.js";
 import { ZERO_RUNTIME_KIND, zeroMigrationOperationSchema, zeroTableSchema } from "./zero.js";
 /**
  * The database surface, for whichever runtime a space is carrying.
  *
- * There is one database per space — the site's own MySQL — and at most one
- * runtime with a claim on it, so these contracts are runtime-neutral by
- * default. The two exceptions are stated explicitly: a migration plan is a
- * capsule's declaration and no worker has one, and the console hand-off is a
- * property of the wp.cloud site rather than of anything a version declared.
+ * One database per space, the site's own MySQL, and at most one runtime with a
+ * claim on it, so these contracts are runtime-neutral. Two exceptions: a
+ * migration plan is a capsule's declaration and no worker has one, and the
+ * console hand-off is a property of the wp.cloud site.
  *
- * The reads answer in the capsule's declaration shapes (`zeroTableSchema`,
- * `zeroMigrationOperationSchema`) because a capsule's declared schema is the
- * richest answer either runtime can give and a worker's is the same answer with
- * the declaration-shaped fields empty. Those shapes stay Zero-named and stay in
- * `./zero.js`: a declared table is the capsule's own statement about itself.
+ * Reads answer in the capsule's declaration shapes (`zeroTableSchema`,
+ * `zeroMigrationOperationSchema`); a worker's answer is the same shape with the
+ * declaration-shaped fields empty.
  */
+/**
+ * Whether the live version's declared migration plan has actually run against
+ * the space database. `applied` compares the recorded application against the
+ * plan's target `schemaHash`; it is `null` when no application record exists —
+ * a version finalized before this record existed, or a finalize whose ready
+ * receipt was a replay — because the control plane then cannot prove the plan
+ * ran. Honest unknown, never a guess.
+ */
+export const runtimeDbPlanStateSchema = z
+    .object({
+    applied: z
+        .boolean()
+        .nullable()
+        .describe("Whether this plan has been run against the space database. `null` when the control plane has no application record and cannot truthfully say."),
+    appliedSchemaHash: executionSha256Schema
+        .nullable()
+        .describe("Schema hash recorded when a plan was last applied for this version, if any."),
+    pendingOperationCount: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Queued or running `db migrate` operations for this space. Non-zero means an apply is still waiting."),
+})
+    .strict();
 export const runtimeDbInspectResponseSchema = z
     .object({
     versionId: z.string().min(1).nullable(),
     artifactId: z.string().min(1).nullable(),
-    backend: z.literal("wpcloud-mysql").nullable(),
+    backend: z.literal("mysql").nullable(),
     migrationMode: z.enum(["safe", "drop", "rename"]).nullable(),
     schemaHash: executionSha256Schema.nullable(),
     tables: z.array(zeroTableSchema).default([]),
     migrations: z.array(zeroMigrationOperationSchema).default([]),
+    plan: runtimeDbPlanStateSchema
+        .nullable()
+        .describe("Applied-state of the live version's migration plan. `null` when the live version declares no migration plan."),
 })
     .strict();
 export const runtimeDbInspectPublicResponseSchema = dataEnvelope(runtimeDbInspectResponseSchema);
 export const runtimeDbDumpQuerySchema = z
     .object({
-    table: executionIdentifierSchema.optional(),
-    limit: z.coerce.number().int().min(1).max(100).default(25),
+    table: executionIdentifierSchema
+        .optional()
+        .describe("Dump only this declared table. Omit it to dump every declared table."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(25)
+        .describe("Maximum rows to read per table."),
 })
     .strict();
+export const runtimeDbCellValueSchema = z.json();
 export const runtimeDbDumpTableSchema = z
     .object({
     name: executionIdentifierSchema,
-    rows: z.array(z.record(z.string(), z.unknown())).default([]),
+    rows: z.array(z.record(z.string(), runtimeDbCellValueSchema)).default([]),
 })
     .strict();
 export const runtimeDbDumpResponseSchema = z
@@ -49,7 +82,22 @@ export const runtimeDbDumpResponseSchema = z
     tables: z.array(runtimeDbDumpTableSchema).default([]),
 })
     .strict();
-export const runtimeDbDumpPublicResponseSchema = dataEnvelope(runtimeDbDumpResponseSchema);
+// OpenAPI embeds a local recursive `$ref` below the route and cannot resolve
+// it, so the same wire contract is spelled out non-recursively here.
+const runtimeDbWireCellValueSchema = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(z.unknown()),
+    z.record(z.string(), z.unknown()),
+]);
+const runtimeDbDumpPublicTableSchema = runtimeDbDumpTableSchema.extend({
+    rows: z.array(z.record(z.string(), runtimeDbWireCellValueSchema)).default([]),
+});
+export const runtimeDbDumpPublicResponseSchema = dataEnvelope(runtimeDbDumpResponseSchema.extend({
+    tables: z.array(runtimeDbDumpPublicTableSchema).default([]),
+}));
 export const runtimeDbExportOrderingSchema = z
     .object({
     tables: z.literal("name_asc"),
@@ -69,18 +117,35 @@ export const runtimeDbExportMetadataSchema = z
 export const runtimeDbExportMetadataPublicResponseSchema = dataEnvelope(runtimeDbExportMetadataSchema);
 export const runtimeDbExportPageQuerySchema = z
     .object({
-    schemaHash: executionSha256Schema,
-    cursor: z.string().min(1).max(4_096).optional(),
-    limit: z.coerce.number().int().min(1).max(1_000).default(500),
+    schemaHash: executionSha256Schema.describe("Schema fence from `GET /v1/spaces/{spaceId}/db/export`. A page whose table has changed shape since is rejected rather than mixed into the export."),
+    cursor: z
+        .string()
+        .min(1)
+        .max(4_096)
+        .optional()
+        .describe("Opaque cursor from the previous page's `pagination.nextCursor`."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(1_000)
+        .default(500)
+        .describe("Maximum rows to return in this page."),
 })
     .strict();
+// The runtime's own wire shape for an export page: rows plus a bare keyset
+// `cursor` that is null at the end. The control plane re-envelopes it into the
+// one platform list envelope below.
 export const runtimeDbExportPageSchema = z
     .object({
-    rows: z.array(z.record(z.string(), z.unknown())),
+    rows: z.array(z.record(z.string(), runtimeDbCellValueSchema)),
     cursor: z.string().nullable(),
 })
     .strict();
-export const runtimeDbExportPagePublicResponseSchema = dataEnvelope(runtimeDbExportPageSchema);
+export const runtimeDbExportPagePublicResponseSchema = z.object({
+    data: z.array(z.record(z.string(), runtimeDbWireCellValueSchema)),
+    pagination: CursorPaginationSchema,
+});
 export const runtimeDbMigrateResultSchema = z
     .object({
     versionId: z.string().min(1).describe("Live version whose migration plan this is."),
@@ -98,7 +163,7 @@ export const runtimeDbMigrateResultSchema = z
 export const runtimeDbMigrateResponseSchema = mutationEnvelope(runtimeDbMigrateResultSchema);
 export const runtimeDbConsoleSchema = z
     .object({
-    provider: z.literal("wpcloud-phpmyadmin"),
+    provider: z.literal("phpmyadmin"),
     url: z
         .string()
         .url()

package/dist/contracts/runtime-purge.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const runtimePurgeStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    queued: "queued";
+    pending: "pending";
+    ok: "ok";
+}>;
+export type RuntimePurgeStatus = z.infer<typeof runtimePurgeStatusSchema>;