feat(runtime-services): add native ephemeral MariaDB provider

Author: chubes4

docs/native-mariadb-runtime-service.md

@@ -0,0 +1,67 @@
+# Native MariaDB Runtime Service
+
+`provider: "native"` provisions a short-lived MariaDB process for MySQL-compatible workloads on Docker-free hosts. The generic runtime-service layer owns its complete lifecycle. Recipes may select only `provider: "native"` and `engine: "mariadb"`; host, port, credentials, sockets, configuration files, and filesystem paths are not configurable.
+
+## Isolation Contract
+
+- The provider resolves and validates `mariadbd`, `mariadb-install-db`, and `mariadb` identities before allocation.
+- Every run gets a mode-`0700` `mkdtemp` root. The data directory, temporary directory, socket, PID file, and error log are children of that root.
+- Initialization, daemon, and client argument arrays begin with `--no-defaults`. No shell or default socket is used.
+- Administration uses only the private Unix socket. Workloads receive a generated least-privilege `runtime` account over loopback TCP through the existing ephemeral connector-secret channel.
+- Cleanup signals only the retained direct `ChildProcess`; the PID file is never trusted or read. Linux captures the owned process start-time token and revalidates it before every signal to reject PID reuse. Root device/inode identity and a symlink-free tree are revalidated before recursive removal.
+- Failures, aborts, timeouts, startup crashes, and partial initialization all enter the same graceful-shutdown, forced-shutdown, wait, and verified-removal state machine. Cleanup failure is terminal and retained in bounded lifecycle evidence.
+- Evidence contains service ID, engine/provider version, lifecycle state, and memory measurements only. It never contains credentials or private absolute paths.
+
+## Daemon Arguments
+
+The provider starts `mariadbd` directly with these fixed controls plus provider-owned absolute paths and a freshly allocated loopback port:
+
+```text
+--no-defaults
+--datadir=<private-root>/data
+--socket=<private-root>/server.sock
+--pid-file=<private-root>/server.pid
+--log-error=<private-root>/server.log
+--tmpdir=<private-root>/tmp
+--bind-address=127.0.0.1
+--port=<ephemeral>
+--skip-name-resolve
+--skip-log-bin
+--skip-host-cache
+--skip-slave-start
+--skip-symbolic-links
+--local-infile=OFF
+--performance-schema=OFF
+--skip-feedback
+--innodb-buffer-pool-size=32M
+--innodb-log-buffer-size=4M
+--key-buffer-size=8M
+--aria-pagecache-buffer-size=8M
+--max-connections=10
+--thread-cache-size=0
+--table-open-cache=128
+--table-definition-cache=128
+--tmp-table-size=8M
+--max-heap-table-size=8M
+```
+
+The configured service budget is 128 MiB. Linux runs record the owned daemon's post-readiness RSS in evidence; the MariaDB 10.11 integration gate requires the observed value to remain within that budget.
+
+## Integration Contract
+
+Homeboy Extensions issue #2412 may select this provider by emitting the generic runtime-service recipe declaration below. WP Codebox performs all provisioning and cleanup; callers do not supply or manage native process details.
+
+```json
+{
+  "id": "wordpress-database",
+  "kind": "mysql",
+  "configuration": { "provider": "native", "engine": "mariadb" },
+  "outputs": {
+    "host": "DB_HOST",
+    "port": "DB_PORT",
+    "username": "DB_USER",
+    "password": "DB_PASSWORD",
+    "database": "DB_NAME"
+  }
+}
+```

package.json

@@ -248,8 +248,9 @@
     "test:generic-ability-runtime-run": "tsx tests/generic-ability-runtime-run.test.ts",
     "test:provider-runtime-contracts": "tsx tests/provider-runtime-contracts.test.ts",
     "test:runtime-requirements-readiness": "tsx tests/runtime-requirements-readiness.test.ts",
-    "test:runtime-services": "tsx tests/runtime-services.test.ts && tsx tests/external-mysql-runtime-service.test.ts",
+    "test:runtime-services": "tsx tests/runtime-services.test.ts && tsx tests/external-mysql-runtime-service.test.ts && tsx tests/native-mariadb-runtime-service.test.ts",
     "test:runtime-services-lifecycle": "tsx tests/runtime-services-lifecycle.test.ts",
+    "test:native-mariadb-runtime-service-integration": "tsx tests/native-mariadb-runtime-service.integration.test.ts",
     "test:disposable-mysql-mysqli-e2e": "tsx tests/disposable-mysql-mysqli.integration.test.ts",
     "test:runtime-contract-manifest": "tsx tests/runtime-contract-manifest.test.ts",
     "test:runtime-contract-package-exports": "tsx tests/runtime-contract-package-exports.test.ts",

packages/cli/src/commands/recipe-run-artifact-pointers.ts

@@ -4,6 +4,7 @@ import type { ArtifactBundle, RecipeRunSummary, RuntimeInfo } from "@automattic/
 import { stripUndefined } from "@automattic/wp-codebox-core/internals"
 import type { RunOutput } from "../runtime-command-wrappers.js"
 import type { RecipeArtifactPointerCommandStatus, RecipeArtifactPointerState, RecipeBrowserEvidence, RecipeDiagnosticArtifactRef, RecipePhaseEvidence } from "./recipe-run-types.js"
+import type { RuntimeServiceEvidence } from "../runtime-services.js"
 
 export class RecipeArtifactPointerTracker {
   private command: string | undefined
@@ -15,6 +16,7 @@ export class RecipeArtifactPointerTracker {
   private browserEvidence: RecipeBrowserEvidence[] = []
   private diagnosticArtifacts: RecipeDiagnosticArtifactRef[] = []
   private result: RecipeRunSummary | undefined
+  private managedRuntimeServices: RuntimeServiceEvidence[] = []
 
   constructor(private readonly directory: string | undefined, private readonly runId: string, private readonly recipePath: string, private readonly startedAt: string) {}
 
@@ -32,6 +34,7 @@ export class RecipeArtifactPointerTracker {
     this.browserEvidence = state.browserEvidence ?? this.browserEvidence
     this.diagnosticArtifacts = state.diagnosticArtifacts ?? this.diagnosticArtifacts
     this.result = state.result ?? this.result
+    this.managedRuntimeServices = state.managedRuntimeServices ?? this.managedRuntimeServices
 
     const pointer = stripUndefined({
       schema: "wp-codebox/recipe-run-artifact-pointer/v1",
@@ -47,6 +50,7 @@ export class RecipeArtifactPointerTracker {
       failure: this.failure,
       failurePhase: recipeArtifactPointerFailurePhase(this.failure, this.phases),
       result: this.result,
+      managedRuntimeServices: this.managedRuntimeServices.length > 0 ? this.managedRuntimeServices : undefined,
       browserEvidence: this.browserEvidence.length > 0 ? this.browserEvidence : undefined,
       diagnosticArtifacts: this.diagnosticArtifacts.length > 0 ? this.diagnosticArtifacts : undefined,
       ...await recipeArtifactPointerArtifactState(this.directory, this.runtime, this.artifacts),

packages/cli/src/commands/recipe-run-finalizer.ts

@@ -67,6 +67,7 @@ interface RecipeRunCommonOutputFields {
   replayStatus?: RecipeRunOutput["replayStatus"]
   fuzzRun?: RecipeRunOutput["fuzzRun"]
   provenance?: RecipeRunOutput["provenance"]
+  managedRuntimeServices?: RecipeRunOutput["managedRuntimeServices"]
   artifacts?: ArtifactBundle
   interruption?: RecipeRunOutput["interruption"]
 }
@@ -194,7 +195,7 @@ export async function finalizeCompletedRecipeRun(args: FinalizeCompletedRecipeRu
   }) as RecipeRunOutput)
   runRecord = await args.runRegistry.update(args.runRecord.runId, { result: runtimeRunResultFromRecipeSummary(output.result!) })
   output.run = runRecord
-  await args.artifactPointer.update({ commandStatus: args.success ? "completed" : "failed", runtime: args.runtime, artifacts: args.artifacts, failure: args.failure, phases: args.phaseEvidence, stepFailures: args.output.stepFailures, browserEvidence: args.browserEvidence, result: output.result })
+  await args.artifactPointer.update({ commandStatus: args.success ? "completed" : "failed", runtime: args.runtime, artifacts: args.artifacts, failure: args.failure, phases: args.phaseEvidence, stepFailures: args.output.stepFailures, browserEvidence: args.browserEvidence, managedRuntimeServices: args.output.managedRuntimeServices, result: output.result })
   return output
 }
 
@@ -220,19 +221,19 @@ export async function finalizeRecoveredRecipeFailure(args: FinalizeRecoveredReci
   }) as RecipeRunOutput)
   runRecord = await args.runRegistry.update(args.runRecord.runId, { result: runtimeRunResultFromRecipeSummary(output.result!) })
   output.run = runRecord
-  await args.artifactPointer.update({ commandStatus: "failed", ...(args.runtime ? { runtime: args.runtime } : {}), ...(args.artifacts ? { artifacts: args.artifacts } : {}), failure: args.serializedError, phases: args.phaseEvidence, stepFailures: args.output.stepFailures, browserEvidence: args.browserEvidence, diagnosticArtifacts: args.diagnosticArtifacts, result: output.result })
+  await args.artifactPointer.update({ commandStatus: "failed", ...(args.runtime ? { runtime: args.runtime } : {}), ...(args.artifacts ? { artifacts: args.artifacts } : {}), failure: args.serializedError, phases: args.phaseEvidence, stepFailures: args.output.stepFailures, browserEvidence: args.browserEvidence, diagnosticArtifacts: args.diagnosticArtifacts, managedRuntimeServices: args.output.managedRuntimeServices, result: output.result })
   return output
 }
 
-export async function runRecipeCleanup(runRegistry: RuntimeRunRegistry, runRecord: RuntimeRunRecord, cleanup: () => Promise<void>): Promise<RunResourceCleanupEvidence> {
+export async function runRecipeCleanup(runRegistry: RuntimeRunRegistry, runRecord: RuntimeRunRecord, cleanup: () => Promise<void>, finalMetadata?: () => Record<string, unknown>): Promise<RunResourceCleanupEvidence> {
   const startedAtMs = Date.now()
   await runRegistry.update(runRecord.runId, { cleanup: { status: "running" } })
   try {
     await cleanup()
-    const updatedRunRecord = await runRegistry.update(runRecord.runId, { cleanup: { status: "succeeded" } })
+    const updatedRunRecord = await runRegistry.update(runRecord.runId, { cleanup: { status: "succeeded" }, ...(finalMetadata ? { metadata: finalMetadata() } : {}) })
     return cleanupEvidenceFromRunRecord(updatedRunRecord, Date.now() - startedAtMs)
   } catch (error) {
-    const updatedRunRecord = await runRegistry.update(runRecord.runId, { cleanup: { status: "failed", error: serializeError(error) } })
+    const updatedRunRecord = await runRegistry.update(runRecord.runId, { cleanup: { status: "failed", error: serializeError(error) }, ...(finalMetadata ? { metadata: finalMetadata() } : {}) })
     const cleanupError = serializeRecipeRunError(error)
     throw new RunResourceCleanupError(
       cleanupEvidenceFromRunRecord(updatedRunRecord, Date.now() - startedAtMs, cleanupError),

packages/cli/src/commands/recipe-run-types.ts

@@ -5,6 +5,7 @@ import type { RecipeExternalServiceBoundaryHostCorrelation } from "../recipe-ext
 import type { RecipeValidationIssue, RecipeWorkflowPhase } from "../recipe-validation.js"
 import type { RunOutput } from "../runtime-command-wrappers.js"
 import type { RecipeAdversarialCampaignOutput } from "../adversarial-recipe.js"
+import type { RuntimeServiceEvidence } from "../runtime-services.js"
 
 export interface RecipeRunOptions {
   recipePath: string
@@ -83,6 +84,7 @@ export interface RecipeRunOutput {
   fuzzRun?: RecipeFuzzRunResult
   adversarialCampaigns?: RecipeAdversarialCampaignOutput[]
   provenance?: RecipeRunProvenance
+  managedRuntimeServices?: RuntimeServiceEvidence[]
   result?: RecipeRunSummary
   artifacts?: ArtifactBundle
   run?: RuntimeRunRecord
@@ -263,6 +265,7 @@ export interface RecipeArtifactPointerState {
   browserEvidence?: RecipeBrowserEvidence[]
   diagnosticArtifacts?: RecipeDiagnosticArtifactRef[]
   result?: RecipeRunSummary
+  managedRuntimeServices?: RuntimeServiceEvidence[]
 }
 
 export interface RecipeEffectiveRecipeArtifact {

packages/cli/src/commands/recipe-run.ts

@@ -445,7 +445,7 @@ export async function runRecipe(options: RecipeRunOptions, interruption?: Recipe
         browserEvidence,
         replayStatus: evidence.replayStatus ? recipeReplayStatusOutput(evidence.replayStatus) : undefined,
         failure: recipeFailure,
-        output: { ...completedRecipeOutputFields({ executions, componentContracts: componentContractResults(recipe, extraPlugins, phaseTracker.list(), executions), stagedFiles: stagedFiles.map(recipeRunStagedFile), fixtureDatabases, siteSeeds, distributionSetupArtifacts, distributionStartupProbes, probes, declaredArtifacts, stepFailures, phaseEvidence: phaseTracker.list(), advisoryFailures, browserEvidence, benchResultsList, fuzzRun: fuzzRunResult, evidence }), ...(adversarialCampaigns.length > 0 ? { adversarialCampaigns } : {}), provenance: recipeRunProvenance(recipe, recipePath) },
+        output: { ...completedRecipeOutputFields({ executions, componentContracts: componentContractResults(recipe, extraPlugins, phaseTracker.list(), executions), stagedFiles: stagedFiles.map(recipeRunStagedFile), fixtureDatabases, siteSeeds, distributionSetupArtifacts, distributionStartupProbes, probes, declaredArtifacts, stepFailures, phaseEvidence: phaseTracker.list(), advisoryFailures, browserEvidence, benchResultsList, fuzzRun: fuzzRunResult, evidence }), ...(adversarialCampaigns.length > 0 ? { adversarialCampaigns } : {}), provenance: recipeRunProvenance(recipe, recipePath), managedRuntimeServices: serviceEvidence },
       })
     }
 
@@ -464,7 +464,7 @@ export async function runRecipe(options: RecipeRunOptions, interruption?: Recipe
       phaseEvidence: phaseTracker.list(),
       browserEvidence,
       replayStatus: evidence.replayStatus ? recipeReplayStatusOutput(evidence.replayStatus) : undefined,
-      output: { ...completedRecipeOutputFields({ executions, componentContracts: componentContractResults(recipe, extraPlugins, phaseTracker.list(), executions), stagedFiles: stagedFiles.map(recipeRunStagedFile), fixtureDatabases, siteSeeds, distributionSetupArtifacts, distributionStartupProbes, probes, declaredArtifacts, stepFailures, phaseEvidence: phaseTracker.list(), advisoryFailures, browserEvidence, benchResultsList, fuzzRun: fuzzRunResult, evidence }), ...(adversarialCampaigns.length > 0 ? { adversarialCampaigns } : {}), provenance: recipeRunProvenance(recipe, recipePath) },
+      output: { ...completedRecipeOutputFields({ executions, componentContracts: componentContractResults(recipe, extraPlugins, phaseTracker.list(), executions), stagedFiles: stagedFiles.map(recipeRunStagedFile), fixtureDatabases, siteSeeds, distributionSetupArtifacts, distributionStartupProbes, probes, declaredArtifacts, stepFailures, phaseEvidence: phaseTracker.list(), advisoryFailures, browserEvidence, benchResultsList, fuzzRun: fuzzRunResult, evidence }), ...(adversarialCampaigns.length > 0 ? { adversarialCampaigns } : {}), provenance: recipeRunProvenance(recipe, recipePath), managedRuntimeServices: serviceEvidence },
     })
   } catch (error) {
     const failedServiceEvidence = runtimeServiceEvidenceFromError(error)
@@ -592,6 +592,7 @@ export async function runRecipe(options: RecipeRunOptions, interruption?: Recipe
         ...(adversarialCampaigns.length > 0 ? { adversarialCampaigns } : {}),
         diagnostics: recipeRuntimeDiagnostics(recipe, executions, error),
         provenance: recipeRunProvenance(recipe, recipePath, diagnosticArtifacts),
+        managedRuntimeServices: serviceEvidence,
       },
     })
   } finally {
@@ -611,16 +612,12 @@ export async function runManagedServiceCleanup(
   cleanup: () => Promise<void>,
 ): Promise<RunResourceCleanupEvidence> {
   try {
-    return await runRecipeCleanup(runRegistry, runRecord, cleanup)
+    return await runRecipeCleanup(runRegistry, runRecord, cleanup, () => ({ managedRuntimeServices: serviceEvidence }))
   } catch (error) {
     if (preservePrimaryFailure && error instanceof RunResourceCleanupError) {
       return error.evidence
     }
     throw error
-  } finally {
-    await runRegistry.update(runRecord.runId, {
-      metadata: { managedRuntimeServices: serviceEvidence },
-    })
   }
 }
 

packages/cli/src/recipe-validation.ts

@@ -805,6 +805,13 @@ function validateRecipeRuntimeServices(recipe: WorkspaceRecipe, addIssue: (code:
         if (service.configuration[field] !== undefined) addIssue("unsupported-external-runtime-service-option", `${path}.configuration.${field}`, `External MySQL services do not support ${field}.`)
       }
     }
+    if (service.configuration?.provider === "native") {
+      if (service.kind !== "mysql") addIssue("unsupported-runtime-service-provider", `${path}.configuration.provider`, "The native provider supports only MySQL-compatible services.")
+      if (service.configuration.engine !== "mariadb") addIssue("unsupported-native-runtime-service-engine", `${path}.configuration.engine`, "The native provider requires engine=mariadb.")
+      for (const field of ["externalService", "hostEnv", "portEnv", "usernameEnv", "passwordEnv", "image", "rootAuthentication", "foreignKeyTargetPolicy", "responseStatus", "responseBody"] as const) {
+        if (service.configuration[field] !== undefined) addIssue("unsupported-native-runtime-service-option", `${path}.configuration.${field}`, `Native MariaDB services do not accept ${field}.`)
+      }
+    }
     const supportedOutputs: Record<string, RegExp> = {
       mysql: /^(host|port|username|password|database)$/,
       redis: /^(host|port|url)$/,