@roubo/shared 0.1.0

package/integration-types.ts

@@ -0,0 +1,124 @@
+/**
+ * Declarative source-picker payloads returned by an integration plugin's
+ * `listSourceCandidates` RPC. Roubo's host renders the UI; plugins ship no
+ * React. See `.specifications/integration-plugins/architecture.md` (FR-019).
+ */
+
+export type SourceCandidateIcon = "repo" | "project" | "board" | "epic" | "filter";
+
+export interface SourceCandidateItem {
+  externalId: string;
+  label: string;
+  sublabel?: string;
+  icon?: SourceCandidateIcon;
+}
+
+export interface SourceCandidateCategory {
+  id: string;
+  label: string;
+  items: SourceCandidateItem[];
+}
+
+export type SourceCandidatesShape =
+  | "multi-list"
+  | "categorized-multi-list"
+  | "searchable-categorized";
+
+// One selectable mode within a synthetic category (e.g. "assigned to me":
+// in-project vs anywhere). Distinct from a SourceCandidateItem in that it has
+// no externalId and is not fetched via search; the host renders it inline.
+export interface SourceCategoryOption {
+  id: string;
+  label: string;
+}
+
+// A category declared by the "searchable-categorized" shape. The plugin ships
+// no items here; it only declares which categories exist, their icon, and
+// whether each is gated behind a parent selection. Items arrive later via the
+// host's source-options search RPC.
+export interface SearchableSourceCategory {
+  id: "project" | "board" | "filter" | "epic" | "mine";
+  label: string;
+  icon?: SourceCandidateIcon;
+  // Gate: the category is disabled until the named parent selection exists.
+  scopedBy?: "project";
+  // Inline modes for synthetic categories like "mine".
+  options?: SourceCategoryOption[];
+}
+
+export interface SourceCandidatesResponse {
+  shape: SourceCandidatesShape;
+  // Present iff shape === "multi-list".
+  items?: SourceCandidateItem[];
+  // Present iff shape === "categorized-multi-list".
+  categories?: SourceCandidateCategory[];
+  // Present iff shape === "searchable-categorized".
+  searchableCategories?: SearchableSourceCategory[];
+  // Reserved for future pagination; v1 plugins return undefined.
+  nextCursor?: string | null;
+}
+
+/**
+ * Params for the scoped, paginated source-option search (`getSourceOptions`).
+ * Generalizes facet-option search with a parent `scope` (the Jira project keys a
+ * board/filter/epic search is confined to) and an opaque `cursor`. `search` is
+ * the optional user-typed term (debounced client-side). Scoped categories with
+ * no `scope.project` return an empty page.
+ */
+export interface GetSourceOptionsParams {
+  category: "project" | "board" | "filter" | "epic";
+  scope?: { project?: string[] };
+  search?: string;
+  cursor?: string | null;
+}
+
+/**
+ * One page of source options returned by `getSourceOptions`. `nextCursor` is an
+ * opaque token the host passes back verbatim to fetch the next page; `null`
+ * means exhausted (NFR-004: every item reachable, no page dropped or duplicated).
+ */
+export interface SourceOptionsResult {
+  items: SourceCandidateItem[];
+  nextCursor: string | null;
+}
+
+/**
+ * One persisted source entry. The primitive `string` form is the externalId;
+ * the object form carries per-source toggles (currently only the GitHub-family
+ * Code Scanning / Secret Scanning / Dependabot booleans, ignored by other
+ * plugins). The two forms are interchangeable on disk: a writer collapses to
+ * the primitive form when no toggles are set, and expands to the object form
+ * the moment any toggle turns on.
+ */
+export type SourceSelectionEntry =
+  | string
+  | {
+      externalId: string;
+      // Human-readable display name and secondary line for the source, captured
+      // when the user picks it so chips and the Settings tile can show the name
+      // instead of the raw id on reload (no re-fetch). Display only: the plugin
+      // and `translateSources` ignore them.
+      label?: string;
+      sublabel?: string;
+      // Jira project key the source is scoped to (project-first model). Set on
+      // board / filter / epic entries and on the synthetic `mine` source when
+      // scoped in-project, so removing a project can prune its scoped sources.
+      project?: string;
+      // Board sources: active sprint only vs the whole board's backing filter.
+      boardMode?: "active-sprint" | "whole-board";
+      // "Assigned to me" synthetic source: scoped to a project or instance-wide.
+      mineScope?: "in-project" | "anywhere";
+      // GitHub-family toggles (ignored by other plugins).
+      includeCodeQLAlerts?: boolean;
+      includeSecretScanningAlerts?: boolean;
+      includeDependabotAlerts?: boolean;
+    };
+
+/**
+ * Persisted selection for a project. Keys are plugin-defined category ids
+ * (or the literal `"items"` for the multi-list shape). Values are arrays of
+ * source entries (string externalIds or objects with per-source toggles).
+ * Stored verbatim in `integration.sources` of the per-user override and
+ * treated as opaque-to-Roubo elsewhere.
+ */
+export type SourceSelection = Record<string, SourceSelectionEntry[]>;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@roubo/shared",
+  "version": "0.1.0",
+  "description": "Shared TypeScript types for Roubo client + server.",
+  "author": "David Poxon",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/davidpoxon/roubo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidpoxon/roubo.git",
+    "directory": "shared"
+  },
+  "bugs": {
+    "url": "https://github.com/davidpoxon/roubo/issues"
+  },
+  "type": "module",
+  "main": "./types.ts",
+  "types": "./types.ts",
+  "exports": {
+    ".": "./types.ts",
+    "./provision-descriptor-schema": "./provision-descriptor-schema.ts",
+    "./testbench-contracts": "./testbench-contracts.ts",
+    "./testbench-canonicalize": "./testbench-canonicalize.ts",
+    "./testbench-domain": "./testbench-domain.ts",
+    "./work-units-contract": "./work-units-contract.ts",
+    "./gate-overrides-contract": "./gate-overrides-contract.ts"
+  },
+  "files": [
+    "*.ts",
+    "!*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  }
+}

package/plugin-consent-schema.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import type { PluginPermissions } from "./plugin-manifest-schema.js";
+
+// Issue #615 / CP-FR-011, CP-FR-012, CP-NFR-001. Per-plugin consent record.
+// See:
+//   .specifications/component-plugins/prd.md (CP-FR-011, CP-FR-012, CP-NFR-001)
+//   .specifications/component-plugins/architecture.md ('Data model', lines 61, 108-109)
+//
+// v1 ships the declare-then-enforce trust model's declaration half: the consumer
+// is shown every declared permission category and must acknowledge them before a
+// component plugin runs. A ConsentRecord captures that acknowledgement so the
+// server can refuse to start a component whose plugin has none. v2 adds runtime
+// enforcement and sandboxing; this record is advisory in v1.
+
+export const PLUGIN_CONSENT_STATE_SCHEMA_VERSION = 1 as const;
+
+// The advisory permission categories a component plugin can declare. Kept in one
+// place so the consent store, the route, and the UI agree on the canonical set.
+export const PERMISSION_CATEGORIES = [
+  "network",
+  "credentials",
+  "filesystem",
+  "processes",
+  "ports",
+  "docker",
+] as const;
+export type PermissionCategory = (typeof PERMISSION_CATEGORIES)[number];
+
+export const ConsentRecordSchema = z
+  .object({
+    pluginId: z.string().min(1),
+    acknowledgedCategories: z.array(z.string().min(1)),
+    consentedAt: z.string().min(1),
+  })
+  .strict();
+export type ConsentRecord = z.infer<typeof ConsentRecordSchema>;
+
+export const PluginConsentStateSchema = z
+  .object({
+    schemaVersion: z.literal(PLUGIN_CONSENT_STATE_SCHEMA_VERSION),
+    plugins: z.record(z.string().min(1), ConsentRecordSchema),
+  })
+  .strict();
+export type PluginConsentState = z.infer<typeof PluginConsentStateSchema>;
+
+/**
+ * Enumerates the permission categories a manifest actually declares, i.e. the
+ * categories the consumer must acknowledge before the plugin may run. A category
+ * is "declared" only when it requests something: an empty `network.hosts`,
+ * `credentials.slots`, or `filesystem.paths`, a `false` `processes` / `ports` /
+ * `docker`, or an absent optional category all count as not-declared and so do
+ * not require acknowledgement.
+ *
+ * Order follows PERMISSION_CATEGORIES so the UI and the route render a stable
+ * sequence.
+ */
+export function declaredCategories(permissions: PluginPermissions): PermissionCategory[] {
+  const declared: PermissionCategory[] = [];
+  if (permissions.network.hosts.length > 0) declared.push("network");
+  if (permissions.credentials.slots.length > 0) declared.push("credentials");
+  if (permissions.filesystem.paths.length > 0) declared.push("filesystem");
+  if (permissions.processes !== false) declared.push("processes");
+  if (permissions.ports !== undefined && permissions.ports !== false) declared.push("ports");
+  if (permissions.docker !== undefined && permissions.docker !== false) declared.push("docker");
+  return declared;
+}
+
+/**
+ * True when every category the manifest declares appears in `acknowledged`.
+ * Extra acknowledged categories are tolerated (forward-compatible); the gate is
+ * only that no declared category is missing. Used by the POST /consent route to
+ * reject a body that omits any declared category (400).
+ */
+export function isFullyAcknowledged(
+  permissions: PluginPermissions,
+  acknowledged: readonly string[],
+): boolean {
+  const ack = new Set(acknowledged);
+  return declaredCategories(permissions).every((cat) => ack.has(cat));
+}

package/plugin-enable-state-schema.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+// WU-046 / issue #137: persistent per-plugin enable state. See:
+//   .specifications/integration-plugins/prd.md (FR-059, FR-060, NFR-019, US-016)
+//   .specifications/integration-plugins/architecture.md (lines 1064-1097)
+
+export const PLUGIN_ENABLE_STATE_SCHEMA_VERSION = 1 as const;
+
+/**
+ * Manifest ids of the bundled plugins shipped in `<repo>/plugins/`. The
+ * greenfield migration path seeds `plugins-state.json` with one `"disabled"`
+ * entry per id so a fresh install opts in to each integration explicitly.
+ */
+export const BUNDLED_PLUGIN_IDS = ["github-com", "ghe", "jira-self-hosted"] as const;
+export type BundledPluginId = (typeof BUNDLED_PLUGIN_IDS)[number];
+
+export const PluginEnableStateValueSchema = z.enum(["enabled", "disabled"]);
+export type PluginEnableStateValue = z.infer<typeof PluginEnableStateValueSchema>;
+
+export const PluginEnableStateSchema = z
+  .object({
+    schemaVersion: z.literal(PLUGIN_ENABLE_STATE_SCHEMA_VERSION),
+    plugins: z.record(z.string().min(1), PluginEnableStateValueSchema),
+    // Sentinel that this install has been through the greenfield seeding pass.
+    // Prevents re-seeding a fresh-cloned alpha install that happens to look
+    // greenfield. Set to true at the same atomic write that seeds `plugins`.
+    installInitialized: z.boolean(),
+  })
+  .strict();
+export type PluginEnableState = z.infer<typeof PluginEnableStateSchema>;

package/plugin-manifest-schema.ts

@@ -0,0 +1,179 @@
+import { z } from "zod";
+
+// ── Sub-schemas ──
+
+export const CredentialSlotSchema = z
+  .object({
+    slot: z.string().min(1, "Required"),
+    scope: z.enum(["read", "read-write"]),
+    description: z.string().min(1, "Required"),
+  })
+  .strict();
+export type CredentialSlot = z.infer<typeof CredentialSlotSchema>;
+
+export const NetworkPermissionsSchema = z
+  .object({
+    hosts: z.array(z.string()),
+  })
+  .strict();
+export type NetworkPermissions = z.infer<typeof NetworkPermissionsSchema>;
+
+export const CredentialsPermissionsSchema = z
+  .object({
+    slots: z.array(CredentialSlotSchema),
+  })
+  .strict();
+export type CredentialsPermissions = z.infer<typeof CredentialsPermissionsSchema>;
+
+export const FilesystemPermissionsSchema = z
+  .object({
+    paths: z.array(z.string()),
+  })
+  .strict();
+export type FilesystemPermissions = z.infer<typeof FilesystemPermissionsSchema>;
+
+export const ProcessesPermissionSchema = z.union([
+  z.literal(false),
+  z.object({ executables: z.array(z.string()) }).strict(),
+]);
+export type ProcessesPermission = z.infer<typeof ProcessesPermissionSchema>;
+
+// `ports` lets a component plugin declare the bench ports it needs allocated.
+// Either false (no port allocation) or an object naming the port keys the host
+// resolves into BenchContext.ports (architecture.md, FR-001/FR-011).
+export const PortsPermissionSchema = z.union([
+  z.literal(false),
+  z.object({ names: z.array(z.string()) }).strict(),
+]);
+export type PortsPermission = z.infer<typeof PortsPermissionSchema>;
+
+// `docker` gates a component plugin's access to the host docker broker
+// (composeUp / waitForHealthy / assignContainer, etc.). Either false (no docker
+// access) or an object (reserved for future scoping fields).
+export const DockerPermissionSchema = z.union([z.literal(false), z.object({}).strict()]);
+export type DockerPermission = z.infer<typeof DockerPermissionSchema>;
+
+// `permissions` is intentionally `.passthrough()` (not `.strict()`) so future
+// permission categories can be added in a 1.x minor without breaking older
+// hosts. See decisions-log.md AF-002. `ports` and `docker` are the component
+// categories (optional, so existing integration manifests validate unchanged).
+export const PluginPermissionsSchema = z
+  .object({
+    network: NetworkPermissionsSchema,
+    credentials: CredentialsPermissionsSchema,
+    filesystem: FilesystemPermissionsSchema,
+    processes: ProcessesPermissionSchema,
+    ports: PortsPermissionSchema.optional(),
+    docker: DockerPermissionSchema.optional(),
+  })
+  .passthrough();
+export type PluginPermissions = z.infer<typeof PluginPermissionsSchema>;
+
+// Per-capability flags a tracker plugin declares for the privileged tracker-action
+// ops the TrackerActionGateway gates (verify-gate FR-011, NFR-005; spike #704).
+// A flag is true only when the plugin implements the op for the connected
+// instance. The gateway reads these up front and degrades with a legible error
+// (never a silent no-op) when a flag is absent or false. close-gate is not a new
+// flag: it reuses the existing applyTransition capability (architecture.md:133-134).
+export const PluginCapabilitiesSchema = z
+  .object({
+    /** The plugin implements `createIssue` for the connected instance (FR-011). */
+    supportsCreateIssue: z.boolean().optional(),
+    /**
+     * The plugin implements `addBlockedBy` AND the connected instance exposes the
+     * blocking-link write (the GitHub GA / GHE version / Jira link-type condition
+     * from spike #704). May be resolved at runtime, not just statically.
+     */
+    supportsBlockingLinks: z.boolean().optional(),
+  })
+  .strict();
+export type PluginCapabilities = z.infer<typeof PluginCapabilitiesSchema>;
+
+// Plugin-global defaults seeded into the three-layer effective-config merge
+// (FR-064). Per-project and per-source layers override these. The host reads
+// this section at manifest parse time; plugins do not see it via host-RPC.
+export const PluginDefaultIntegrationConfigSchema = z
+  .object({
+    excludedStatuses: z.array(z.string().min(1)).optional(),
+    // Plugin-global default for the category-first status exclusion (FR-010).
+    // Seeded by the plugin manifest (e.g. jira-self-hosted ships ["Done"]).
+    excludedStatusCategories: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+export type PluginDefaultIntegrationConfig = z.infer<typeof PluginDefaultIntegrationConfigSchema>;
+
+// Per FR-057 / mockups §22, plugins may ship an icon rendered in the
+// Plugins-page tile header (32×32) and the Configure modal header (24×24).
+// Accepted forms:
+//   - `data:image/svg+xml;...` or `data:image/png;base64,...` data URI
+//   - relative POSIX path inside the plugin directory (e.g. `assets/icon.svg`)
+// Loose validation here: the client renders this as an <img src>; manifest
+// authors are trusted to ship something sensible. 16 KB ceiling guards
+// against accidentally shipping a megabyte of base64.
+export const PluginIconSchema = z
+  .string()
+  .min(1, "Required")
+  .max(16 * 1024, "Icon must be at most 16 KB");
+export type PluginIcon = z.infer<typeof PluginIconSchema>;
+
+// The set of plugin kinds the host understands. `component` lands with the
+// component-plugin work (FR-001); `integration` is the original kind. The
+// discriminator widens here without breaking existing integration manifests.
+export const PluginKindSchema = z.enum(["integration", "component"]);
+export type PluginKind = z.infer<typeof PluginKindSchema>;
+
+// A node-semver-compatible range, used to validate the manifest `roubo` field
+// at schema time so a malformed range is rejected with a clear error (FR-001),
+// rather than only at host-compatibility time. Kept dependency-free (the
+// `shared` workspace depends only on `yaml` + `zod`): this validates each
+// space- or `||`-separated comparator against the comparator grammar
+// node-semver accepts (operators, hyphen ranges, x-ranges, caret/tilde,
+// wildcards). It is intentionally permissive on the comparator side and strict
+// only about rejecting obvious garbage (the host re-checks with node-semver).
+const SEMVER_COMPARATOR =
+  /^(?:[<>]=?|=|\^|~)?\s*v?(?:\d+|[xX*])(?:\.(?:\d+|[xX*]))?(?:\.(?:\d+|[xX*]))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function isValidRouboRange(range: string): boolean {
+  const trimmed = range.trim();
+  if (trimmed.length === 0) return false;
+  // `*` / `x` on their own is the match-anything range.
+  if (/^[*xX]$/.test(trimmed)) return true;
+  const orClauses = trimmed.split("||");
+  return orClauses.every((clause) => {
+    const comparators = clause.trim().split(/\s+/).filter(Boolean);
+    if (comparators.length === 0) return false;
+    // A hyphen range ("1.2.3 - 2.3.4") parses as [lo, "-", hi].
+    if (comparators.length === 3 && comparators[1] === "-") {
+      return SEMVER_COMPARATOR.test(comparators[0]) && SEMVER_COMPARATOR.test(comparators[2]);
+    }
+    return comparators.every((c) => SEMVER_COMPARATOR.test(c));
+  });
+}
+
+// ── Root manifest ──
+
+export const PluginManifestSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(/^[a-z][a-z0-9-]*$/, "Must be kebab-case (lowercase letters, digits, hyphens)"),
+    name: z.string().min(1, "Required"),
+    version: z.string().min(1, "Required"),
+    description: z.string().min(1, "Required"),
+    kind: PluginKindSchema,
+    roubo: z.string().min(1, "Required").refine(isValidRouboRange, "Must be a valid semver range"),
+    entry: z.string().min(1, "Required"),
+    icon: PluginIconSchema.optional(),
+    configSchema: z.record(z.string(), z.unknown()).optional(),
+    capabilities: PluginCapabilitiesSchema.optional(),
+    defaultIntegrationConfig: PluginDefaultIntegrationConfigSchema.optional(),
+    permissions: PluginPermissionsSchema,
+    // Component plugins declare the SDK component-contract version they target
+    // (FR-001/FR-002); the host validates the registered-method set against it.
+    contractVersion: z.number().int().positive().optional(),
+    // Optional ProvisionDescriptor schema version a declarative component plugin
+    // emits, so the host can reject a descriptor-schema mismatch (FR-017).
+    descriptorSchemaVersion: z.number().int().positive().optional(),
+  })
+  .strict();
+export type PluginManifest = z.infer<typeof PluginManifestSchema>;

package/plugin-manifest.ts

@@ -0,0 +1,55 @@
+import { parse as parseYaml, YAMLParseError } from "yaml";
+import { PluginManifestSchema, type PluginManifest } from "./plugin-manifest-schema.js";
+
+export type ParseManifestResult =
+  | { ok: true; manifest: PluginManifest }
+  | {
+      ok: false;
+      error: {
+        code: "invalid-yaml" | "schema";
+        message: string;
+        path?: string;
+      };
+    };
+
+export function parseManifest(yamlText: string, sourcePath: string): ParseManifestResult {
+  let raw: unknown;
+  try {
+    raw = parseYaml(yamlText);
+  } catch (err) {
+    const message = err instanceof YAMLParseError ? err.message : (err as Error).message;
+    return {
+      ok: false,
+      error: {
+        code: "invalid-yaml",
+        message: `Failed to parse ${sourcePath}: ${message}`,
+      },
+    };
+  }
+
+  if (raw === null || raw === undefined) {
+    return {
+      ok: false,
+      error: {
+        code: "invalid-yaml",
+        message: `${sourcePath} is empty`,
+      },
+    };
+  }
+
+  const parsed = PluginManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+    return {
+      ok: false,
+      error: {
+        code: "schema",
+        message: path ? `${path}: ${issue.message}` : issue.message,
+        path,
+      },
+    };
+  }
+
+  return { ok: true, manifest: parsed.data };
+}

package/plugin-runtime-types.ts

@@ -0,0 +1,50 @@
+import type { PluginManifest } from "./plugin-manifest-schema.js";
+
+export type PluginStatus = "enabled" | "disabled" | "errored" | "incompatible" | "invalid";
+
+export type PluginSource = "bundled" | "user";
+
+export interface RestartEvent {
+  at: string;
+  reason: "unexpected-exit" | "spawn-failed" | "sandbox-fallback";
+  exitCode: number | null;
+}
+
+export interface PluginError {
+  code: string;
+  message: string;
+  methodName?: string;
+}
+
+export interface LogLine {
+  ts: string;
+  source: "stdout" | "stderr" | "host";
+  level?: "info" | "warn" | "error";
+  text: string;
+}
+
+/**
+ * A structured, user-visible notice that the docker isolation tier could not
+ * engage for the plugin's directory. Surfaced on PluginRecord so callers of
+ * listInstalled() can present an actionable remediation rather than relying
+ * only on the log line (#743).
+ */
+export interface IsolationNotice {
+  kind: "docker-mount-unshared";
+  pluginDir: string;
+  message: string;
+  at: string;
+}
+
+export interface PluginRecord {
+  id: string;
+  manifest: PluginManifest | null;
+  manifestPath: string;
+  pluginDir: string;
+  source: PluginSource;
+  status: PluginStatus;
+  lastError: PluginError | null;
+  restartHistory: RestartEvent[];
+  pid: number | null;
+  isolationNotices?: IsolationNotice[];
+}

package/provision-descriptor-schema.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+
+// Issue #603 / T1.2: the typed ProvisionDescriptor discriminated union that a
+// component plugin emits and the host LifecycleEngine executes. See:
+//   .specifications/component-plugins/prd.md (FR-002, FR-022, US-005, US-012)
+//   .specifications/component-plugins/architecture.md ('Data model', line 54)
+//
+// The shape is frozen in architecture.md. It lives in shared/ so both the host
+// LifecycleEngine and the plugin SDK import one contract without a circular
+// dependency. Every variant carries a top-level schemaVersion so the host can
+// validate a descriptor and reject a mismatched version (the z.literal gate
+// below fails validation when the version does not match).
+
+export const SUPPORTED_PROVISION_SCHEMA_VERSION = 1 as const;
+
+// ── docker ──
+// A compose-backed component: the host brings up `service` in `composeFile`,
+// optionally running `initService` first, optionally running a `migration`
+// command once the service is healthy, and optionally exposing a connection
+// string via `connection.template`.
+
+const DockerMigrationSchema = z
+  .object({
+    command: z.string().min(1),
+    args: z.array(z.string()).optional(),
+  })
+  .strict();
+
+const DockerConnectionSchema = z
+  .object({
+    template: z.string().min(1),
+  })
+  .strict();
+
+export const DockerProvisionDescriptorSchema = z
+  .object({
+    schemaVersion: z.literal(SUPPORTED_PROVISION_SCHEMA_VERSION),
+    kind: z.literal("docker"),
+    composeFile: z.string().min(1),
+    service: z.string().min(1),
+    initService: z.string().min(1).optional(),
+    portEnvVar: z.string().min(1).optional(),
+    migration: DockerMigrationSchema.optional(),
+    connection: DockerConnectionSchema.optional(),
+    assignedContainerId: z.string().min(1).optional(),
+    // Component-level env injected into the compose interpolation environment
+    // (and the migration process env), merged alongside the allocated port. This
+    // mirrors the built-in database path, which folds `componentConfig.env` into
+    // the compose `portOverrides` (see bench-manager `startDockerComponent`), so a
+    // plugin-backed database reaches env parity (CP-FR-004, CP-FR-007).
+    env: z.record(z.string(), z.string()).optional(),
+    healthcheck: z.boolean().optional(),
+  })
+  .strict();
+export type DockerProvisionDescriptor = z.infer<typeof DockerProvisionDescriptorSchema>;
+
+// ── process ──
+// A long-running process the host owns: `command` is started in `cwd` with the
+// merged `env` / `envFile`, optionally after running a one-time `setup`, once
+// the named `dependsOn` components are up.
+
+export const ProcessProvisionDescriptorSchema = z
+  .object({
+    schemaVersion: z.literal(SUPPORTED_PROVISION_SCHEMA_VERSION),
+    kind: z.literal("process"),
+    command: z.string().min(1),
+    env: z.record(z.string(), z.string()).optional(),
+    envFile: z.string().min(1).optional(),
+    cwd: z.string().min(1).optional(),
+    setup: z.string().min(1).optional(),
+    dependsOn: z.array(z.string()).optional(),
+  })
+  .strict();
+export type ProcessProvisionDescriptor = z.infer<typeof ProcessProvisionDescriptorSchema>;
+
+// ── oneshot ──
+// A run-to-completion command (the FR-022 deploy stress-test shape): like a
+// process but expected to exit, with an optional `timeoutMs` ceiling.
+
+export const OneshotProvisionDescriptorSchema = z
+  .object({
+    schemaVersion: z.literal(SUPPORTED_PROVISION_SCHEMA_VERSION),
+    kind: z.literal("oneshot"),
+    command: z.string().min(1),
+    env: z.record(z.string(), z.string()).optional(),
+    envFile: z.string().min(1).optional(),
+    cwd: z.string().min(1).optional(),
+    dependsOn: z.array(z.string()).optional(),
+    timeoutMs: z.number().int().positive().optional(),
+  })
+  .strict();
+export type OneshotProvisionDescriptor = z.infer<typeof OneshotProvisionDescriptorSchema>;
+
+// ── union ──
+// Discriminated on `kind`; schemaVersion is a literal field on each member, so
+// a mismatched version fails validation without any z.intersection wrapping.
+
+export const ProvisionDescriptorSchema = z.discriminatedUnion("kind", [
+  DockerProvisionDescriptorSchema,
+  ProcessProvisionDescriptorSchema,
+  OneshotProvisionDescriptorSchema,
+]);
+export type ProvisionDescriptor = z.infer<typeof ProvisionDescriptorSchema>;