Add runtime capture status primitive

Add a generic runtime capture status DTO and normalizer for existing snapshot, patch, changed-file, and mount-diff evidence, exposed through the public runtime-playground API without product-specific semantics.

Author: chubes4

docs/public-api-contract.md

@@ -44,7 +44,7 @@ Use these package entrypoints from external integrations:
   implementation packages directly.
 - `@automattic/wp-codebox-playground`: advanced runtime backend entrypoint and
   adapter surface for runtime-backend implementors. New consumers should prefer
-  `@automattic/wp-codebox-playground/public`. Product consumers should use the Codebox-owned public surfaces above and the WordPress/browser surfaces below.
+  `@automattic/wp-codebox-playground/public`. Product consumers should use the Codebox-owned public surfaces above and the WordPress/browser surfaces below. The public facade exposes `runtimeCaptureStatus()` for normalizing existing snapshot, workspace patch, changed-file, or mount-diff evidence into `wp-codebox/runtime-capture-status/v1`.
 - `@automattic/wp-codebox-cli`: the executable CLI surface for schema, command,
   recipe, runtime, and artifact operations.
 - `@automattic/wp-codebox-cli/recipe-secret-env`: recipe secret environment

package.json

@@ -203,6 +203,7 @@
     "test:php-provider-credential-boundary": "php scripts/php-provider-credential-boundary-smoke.php",
     "test:production-boundary-enforcement": "tsx tests/production-boundary-enforcement.test.ts",
     "test:public-api-contract": "tsx tests/public-api-contract.test.ts",
+    "test:runtime-capture-status": "tsx tests/runtime-capture-status.test.ts",
     "test:wordpress-runtime-actions": "tsx tests/wordpress-runtime-actions.test.ts",
     "test:wordpress-action-auth-contract": "tsx tests/wordpress-action-auth-contract.test.ts",
     "test:wordpress-hotspots-contracts": "tsx tests/wordpress-hotspots-contracts.test.ts",

packages/runtime-playground/src/index.ts

@@ -15,4 +15,5 @@ export { browserPreviewAuthCookieUrls, browserPreviewNetworkPolicySummary, brows
 export { normalizePreviewReviewerAccess, previewReviewerAccess } from "./preview-reviewer-access.js"
 export { applyVfsMountSnapshots, materializePlaygroundMountsFromVfs, materializePlaygroundStagedInputs, type HostMountSnapshot, type MountMaterializationResult, type StagedInputMaterializationResult, type VfsMountSnapshot } from "./mount-materialization.js"
 export { buildReplayExportBlueprint, buildReplayableWordPressSiteBlueprint, buildReplayableWordPressSiteLimitations, writeReplayExportPackage, writeReplayableWordPressSiteBundle, type ReplayExportPackage, type ReplayExportPackageOptions, type ReplayableWordPressSiteBundle, type ReplayableWordPressSiteBundleManifest, type ReplayableWordPressSiteBundleOptions } from "./replayable-wordpress-site-bundle.js"
+export { RUNTIME_CAPTURE_STATUS_SCHEMA, runtimeCaptureStatus, type RuntimeCaptureDiagnostic, type RuntimeCaptureState, type RuntimeCaptureStatus, type RuntimeCaptureStatusInput } from "./runtime-capture-status.js"
 export type { RuntimeSnapshotArtifact } from "./runtime-snapshot.js"

packages/runtime-playground/src/public.ts

@@ -177,6 +177,7 @@ export {
 } from "@automattic/wp-codebox-core"
 import { browserArtifactMetrics, type BrowserArtifactMetricsResult } from "./browser-metrics.js"
 import { createPlaygroundRuntimeBackend, type PlaygroundRuntimeBackendOptions } from "./playground-runtime.js"
+export { RUNTIME_CAPTURE_STATUS_SCHEMA, runtimeCaptureStatus, type RuntimeCaptureDiagnostic, type RuntimeCaptureState, type RuntimeCaptureStatus, type RuntimeCaptureStatusInput } from "./runtime-capture-status.js"
 
 export type WordPressRuntimeSpec = Omit<RuntimeCreateSpec, "backend"> & {
   backend?: "wordpress-playground"

packages/runtime-playground/src/runtime-capture-status.ts

@@ -0,0 +1,153 @@
+import { sha256StableJson } from "@automattic/wp-codebox-core/internals"
+import type { ArtifactDiagnostic } from "@automattic/wp-codebox-core"
+import type { CanonicalChangedFiles, MountDiff, WorkspacePatchArtifact } from "./artifacts.js"
+import type { RuntimeSnapshotArtifact } from "./runtime-snapshot.js"
+
+export const RUNTIME_CAPTURE_STATUS_SCHEMA = "wp-codebox/runtime-capture-status/v1" as const
+
+export type RuntimeCaptureState = "clean" | "changed" | "unknown" | "unsupported"
+
+export interface RuntimeCaptureDiagnostic {
+  severity: "info" | "warning" | "error"
+  code: string
+  message: string
+  details?: Record<string, unknown>
+}
+
+export interface RuntimeCaptureStatus {
+  schema: typeof RUNTIME_CAPTURE_STATUS_SCHEMA
+  version: 1
+  state: RuntimeCaptureState
+  snapshotDigest?: { algorithm: "sha256"; value: string }
+  captureDigest?: { algorithm: "sha256"; value: string }
+  resources?: {
+    databaseTables?: number
+    wpContentFiles?: number
+  }
+  changes?: {
+    files: number
+    added: number
+    modified: number
+    deleted: number
+    workspaces?: number
+  }
+  diagnostics: RuntimeCaptureDiagnostic[]
+  limitations: string[]
+}
+
+export interface RuntimeCaptureStatusInput {
+  supported?: boolean
+  snapshot?: RuntimeSnapshotArtifact
+  workspacePatch?: Pick<WorkspacePatchArtifact, "summary" | "contentDigest" | "workspaces">
+  changedFiles?: CanonicalChangedFiles
+  mountDiffs?: MountDiff[]
+  captureDigest?: string | { algorithm: "sha256"; value: string }
+  diagnostics?: Array<RuntimeCaptureDiagnostic | ArtifactDiagnostic>
+  limitations?: string[]
+}
+
+export function runtimeCaptureStatus(input: RuntimeCaptureStatusInput = {}): RuntimeCaptureStatus {
+  const diagnostics = normalizeRuntimeCaptureDiagnostics(input.diagnostics ?? [])
+  const limitations = [...(input.limitations ?? [])]
+  const snapshotDigest = input.snapshot ? digest(input.snapshot) : undefined
+  const captureDigest = normalizeDigest(input.captureDigest)
+    ?? input.workspacePatch?.contentDigest
+    ?? (input.changedFiles ? digest(input.changedFiles) : undefined)
+    ?? snapshotDigest
+  const changes = summarizeChanges(input)
+  const resources = input.snapshot ? {
+    databaseTables: input.snapshot.database.tables.length,
+    wpContentFiles: input.snapshot.files.length,
+  } : undefined
+
+  if (input.supported === false) {
+    return {
+      schema: RUNTIME_CAPTURE_STATUS_SCHEMA,
+      version: 1,
+      state: "unsupported",
+      ...(snapshotDigest ? { snapshotDigest } : {}),
+      ...(captureDigest ? { captureDigest } : {}),
+      ...(resources ? { resources } : {}),
+      ...(changes ? { changes } : {}),
+      diagnostics,
+      limitations,
+    }
+  }
+
+  const hasChangeEvidence = Boolean(input.workspacePatch || input.changedFiles || input.mountDiffs)
+  const state: RuntimeCaptureState = hasChangeEvidence ? (changes && changes.files > 0 ? "changed" : "clean") : "unknown"
+
+  return {
+    schema: RUNTIME_CAPTURE_STATUS_SCHEMA,
+    version: 1,
+    state,
+    ...(snapshotDigest ? { snapshotDigest } : {}),
+    ...(captureDigest ? { captureDigest } : {}),
+    ...(resources ? { resources } : {}),
+    ...(changes ? { changes } : {}),
+    diagnostics,
+    limitations,
+  }
+}
+
+function summarizeChanges(input: RuntimeCaptureStatusInput): RuntimeCaptureStatus["changes"] | undefined {
+  if (input.workspacePatch) {
+    return {
+      files: input.workspacePatch.summary.files,
+      added: input.workspacePatch.summary.added,
+      modified: input.workspacePatch.summary.modified,
+      deleted: input.workspacePatch.summary.deleted,
+      workspaces: input.workspacePatch.workspaces.length,
+    }
+  }
+
+  if (input.changedFiles) {
+    return changedFileStats(input.changedFiles.files)
+  }
+
+  if (input.mountDiffs) {
+    return {
+      files: input.mountDiffs.filter((diff) => diff.changed).length,
+      added: 0,
+      modified: input.mountDiffs.filter((diff) => diff.changed).length,
+      deleted: 0,
+      workspaces: input.mountDiffs.length,
+    }
+  }
+
+  return undefined
+}
+
+function changedFileStats(files: CanonicalChangedFiles["files"]): NonNullable<RuntimeCaptureStatus["changes"]> {
+  return {
+    files: files.length,
+    added: files.filter((file) => file.status === "added").length,
+    modified: files.filter((file) => file.status === "modified").length,
+    deleted: files.filter((file) => file.status === "deleted").length,
+  }
+}
+
+function normalizeDigest(value: RuntimeCaptureStatusInput["captureDigest"]): RuntimeCaptureStatus["captureDigest"] | undefined {
+  if (!value) {
+    return undefined
+  }
+
+  return typeof value === "string" ? { algorithm: "sha256", value } : value
+}
+
+function digest(value: unknown): { algorithm: "sha256"; value: string } {
+  return { algorithm: "sha256", value: sha256StableJson(value) }
+}
+
+function normalizeRuntimeCaptureDiagnostics(diagnostics: Array<RuntimeCaptureDiagnostic | ArtifactDiagnostic>): RuntimeCaptureDiagnostic[] {
+  return diagnostics.map((diagnostic) => ({
+    severity: normalizeSeverity(diagnostic.severity),
+    code: ("code" in diagnostic ? diagnostic.code : diagnostic.type) || "runtime-capture-diagnostic",
+    message: diagnostic.message,
+    ...(diagnostic.details ? { details: diagnostic.details as Record<string, unknown> } : {}),
+  }))
+}
+
+function normalizeSeverity(severity: string): RuntimeCaptureDiagnostic["severity"] {
+  return severity === "error" || severity === "warning" ? severity : "info"
+}

tests/public-api-contract.test.ts

@@ -568,6 +568,9 @@ assert.equal(typeof playgroundPublicApi.runWordPressBrowserAction, "function")
 assert.equal(typeof playgroundPublicApi.probeWordPressBrowser, "function")
 assert.equal(typeof playgroundPublicApi.openWordPressEditor, "function")
 assert.equal(typeof playgroundPublicApi.collectWordPressArtifacts, "function")
+assert.equal(typeof playgroundPublicApi.runtimeCaptureStatus, "function")
+assert.equal(playgroundPublicApi.RUNTIME_CAPTURE_STATUS_SCHEMA, "wp-codebox/runtime-capture-status/v1")
+assert.equal("buildRuntimeCaptureStatusForWordPressBuild" in playgroundPublicApi, false)
 assert.equal(RUNNER_WORKSPACE_BACKEND_FILTER, "wp_codebox_runner_workspace_backend")
 assert.ok(RUNNER_WORKSPACE_BACKEND_ABILITY_KEYS.includes("publish_runner_workspace"))
 assert.match(runnerWorkspaceAdapter, new RegExp(escapeRegExp(RUNNER_WORKSPACE_BACKEND_FILTER)))

tests/runtime-capture-status.test.ts

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import { RUNTIME_CAPTURE_STATUS_SCHEMA, runtimeCaptureStatus } from "../packages/runtime-playground/src/public.js"
+import * as playgroundPublicApi from "../packages/runtime-playground/src/public.js"
+import type { CanonicalChangedFiles, WorkspacePatchArtifact } from "../packages/runtime-playground/src/artifacts.js"
+import type { RuntimeSnapshotArtifact } from "../packages/runtime-playground/src/runtime-snapshot.js"
+
+const snapshot: RuntimeSnapshotArtifact = {
+  schema: "wp-codebox/wordpress-runtime-snapshot/v1",
+  version: 1,
+  id: "snapshot-1",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  compatibility: { backend: "wordpress-playground", wordpressVersion: "6.9", phpVersion: "8.3" },
+  metadata: {
+    runtime: {
+      id: "runtime-1",
+      backend: "wordpress-playground",
+      status: "running",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      environment: { kind: "wordpress", version: "6.9", phpVersion: "8.3" },
+    },
+    mounts: [],
+    mountedInputs: [],
+    activeTheme: "twentytwentyfive",
+    activePlugins: ["example/example.php"],
+    wpContentPath: "/wordpress/wp-content",
+  },
+  database: { tables: [{ name: "wp_options", createSql: "CREATE TABLE wp_options (option_id int)", rows: [], rowCount: 0 }] },
+  files: [{ scope: "wp-content", path: "themes/twentytwentyfive/style.css", bytes: 12, sha256: "a".repeat(64), base64: "ZXhhbXBsZQ==" }],
+  hashes: { database: { algorithm: "sha256", value: "b".repeat(64) }, files: { algorithm: "sha256", value: "c".repeat(64) } },
+}
+
+const cleanChangedFiles: CanonicalChangedFiles = { schema: "wp-codebox/changed-files/v1", files: [] }
+const changedFiles: CanonicalChangedFiles = {
+  schema: "wp-codebox/changed-files/v1",
+  files: [
+    { path: "/tmp/site/wp-content/plugins/example/plugin.php", status: "added", mountIndex: 0, mountTarget: "/wordpress/wp-content/plugins/example", relativePath: "plugin.php", patchPath: "files/diffs/mount-0.patch" },
+    { path: "/tmp/site/wp-content/themes/theme/style.css", status: "modified", mountIndex: 1, mountTarget: "/wordpress/wp-content/themes/theme", relativePath: "style.css", patchPath: "files/diffs/mount-1.patch" },
+    { path: "/tmp/site/wp-content/themes/theme/old.css", status: "deleted", mountIndex: 1, mountTarget: "/wordpress/wp-content/themes/theme", relativePath: "old.css", patchPath: "files/diffs/mount-1.patch" },
+  ],
+}
+
+const clean = runtimeCaptureStatus({ snapshot, changedFiles: cleanChangedFiles })
+assert.equal(clean.schema, RUNTIME_CAPTURE_STATUS_SCHEMA)
+assert.equal(clean.version, 1)
+assert.equal(clean.state, "clean")
+assert.equal(clean.resources?.databaseTables, 1)
+assert.equal(clean.resources?.wpContentFiles, 1)
+assert.deepEqual(clean.changes, { files: 0, added: 0, modified: 0, deleted: 0 })
+assert.equal(clean.snapshotDigest?.algorithm, "sha256")
+assert.equal(clean.captureDigest?.algorithm, "sha256")
+
+const changed = runtimeCaptureStatus({ snapshot, changedFiles })
+assert.equal(changed.state, "changed")
+assert.deepEqual(changed.changes, { files: 3, added: 1, modified: 1, deleted: 1 })
+
+const unknown = runtimeCaptureStatus({ snapshot, limitations: ["No comparable baseline was provided."] })
+assert.equal(unknown.state, "unknown")
+assert.deepEqual(unknown.limitations, ["No comparable baseline was provided."])
+assert.equal(unknown.resources?.databaseTables, 1)
+assert.equal(unknown.snapshotDigest?.value, unknown.captureDigest?.value)
+
+const workspacePatch: Pick<WorkspacePatchArtifact, "summary" | "contentDigest" | "workspaces"> = {
+  summary: { changed: true, files: 2, added: 1, modified: 1, deleted: 0 },
+  contentDigest: { algorithm: "sha256", inputs: ["files/changed-files.json", "files/patch.diff"], value: "d".repeat(64) },
+  workspaces: [
+    { mountIndex: 0, target: "/wordpress/wp-content/plugins/example", source: "/tmp/example", status: "changed", changed: true, patch: "files/diffs/mount-0.patch" },
+  ],
+}
+const workspaceChanged = runtimeCaptureStatus({ workspacePatch })
+assert.equal(workspaceChanged.state, "changed")
+assert.equal(workspaceChanged.captureDigest?.value, "d".repeat(64))
+assert.deepEqual(workspaceChanged.changes, { files: 2, added: 1, modified: 1, deleted: 0, workspaces: 1 })
+
+const unsupported = runtimeCaptureStatus({ supported: false, diagnostics: [{ severity: "warning", code: "runtime-capture-unavailable", message: "Runtime capture is not available for this backend." }] })
+assert.equal(unsupported.state, "unsupported")
+assert.deepEqual(unsupported.diagnostics, [{ severity: "warning", code: "runtime-capture-unavailable", message: "Runtime capture is not available for this backend." }])
+
+assert.equal(typeof playgroundPublicApi.runtimeCaptureStatus, "function")
+assert.equal(playgroundPublicApi.RUNTIME_CAPTURE_STATUS_SCHEMA, "wp-codebox/runtime-capture-status/v1")
+assert.equal("buildRuntimeCaptureStatusForWordPressBuild" in playgroundPublicApi, false)
+
+for (const path of [
+  "packages/runtime-playground/src/runtime-capture-status.ts",
+  "packages/runtime-playground/src/public.ts",
+  "packages/runtime-playground/src/index.ts",
+]) {
+  const source = await readFile(new URL(`../${path}`, import.meta.url), "utf8")
+  assert.doesNotMatch(source, /WP Build|WordPress Build|paid|free|export gating/i, `${path} must stay product-agnostic`)
+}
+
+console.log("runtime capture status ok")