@xemahq/kernel-contracts 0.40.0 → 0.42.0

package/src/worker-runtime/lib/runtime-layout-profile.ts

@@ -20,7 +20,7 @@
 // is where the platform renders the system overlay per WS7.
 // ═══════════════════════════════════════════════════════════════════════════
 
-import { WorkerRuntimeKind } from './enums';
+import { RuntimeCommandFormat, WorkerRuntimeKind } from './enums';
 
 /**
  * The workspace slots whose on-disk location differs per orchestrator. The
@@ -48,6 +48,43 @@ export interface RuntimeLayoutProfile {
    * fail-fast contract as `agentBundlesDir`.
    */
   readonly commandsDir: string | null;
+  /**
+   * How this runtime consumes a per-skill `/`-launch command — the capability
+   * the composer/proxy switch on to decide WHETHER (and in which format) to
+   * materialise a launcher file. `Markdown` runtimes get a launcher written at
+   * `commandsDir`; `Toml`/`None` runtimes get NOTHING (skills still mount as
+   * bundles and launch via the runtime's own `/skills` surface / skill tool),
+   * so no stray file lands where the runtime would silently ignore it.
+   *
+   * INVARIANT: `commandFormat === Markdown` ⟺ `commandsDir !== null`. A runtime
+   * with no command surface (`commandsDir: null`) MUST declare `None`.
+   */
+  readonly commandFormat: RuntimeCommandFormat;
+  /**
+   * Absolute path to the runtime's PRIMARY config file — the file the
+   * orchestrator's bundle composer renders and the supervisor materialises on
+   * the PVC. It carries the LLM-gateway credential (OpenCode reads
+   * `.opencode/opencode.jsonc`; Qwen `.qwen/settings.json` → `env.OPENAI_API_KEY`;
+   * Claude `.claude/settings.json` → `env.ANTHROPIC_AUTH_TOKEN`; Hermes
+   * `.hermes/config.json` → `provider.api_key`) and/or merged MCP bearer headers.
+   *
+   * This is the single source of truth for the config-file location: both the
+   * proxy's on-disk layout and the workspace-sandbox protected-path contract
+   * (`deriveWorkspaceSandboxProtection`) source it here rather than each
+   * re-deriving a per-runtime basename literal.
+   */
+  readonly runtimeConfigFile: string;
+  /**
+   * Absolute path to a DEDICATED MCP-server file the runtime reads separately
+   * from its primary config (Claude Code: `.mcp.json` at the workspace root),
+   * or `null` when the runtime merges MCP into {@link runtimeConfigFile}
+   * (OpenCode/Qwen/Hermes: `InConfig`). When non-null the file carries per-server
+   * bearer headers and is therefore part of the secret read-deny set.
+   *
+   * INVARIANT: `mcpConfigFile !== null` ⟺ the runtime places MCP in a separate
+   * file. A runtime that folds MCP into its primary config MUST declare `null`.
+   */
+  readonly mcpConfigFile: string | null;
 }
 
 /**
@@ -63,6 +100,11 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     contextFile: '/workspace/AGENTS.md',
     agentBundlesDir: '/workspace/.opencode/agents',
     commandsDir: '/workspace/.opencode/command',
+    // OpenCode reads markdown commands from `{command,commands}/**.md`.
+    commandFormat: RuntimeCommandFormat.Markdown,
+    runtimeConfigFile: '/workspace/.opencode/opencode.jsonc',
+    // OpenCode pre-merges MCP into opencode.jsonc (`InConfig`) — no separate file.
+    mcpConfigFile: null,
   },
   [WorkerRuntimeKind.Qwen]: {
     kind: WorkerRuntimeKind.Qwen,
@@ -70,6 +112,13 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     contextFile: '/workspace/AGENTS.md',
     agentBundlesDir: '/workspace/.qwen/agents',
     commandsDir: '/workspace/.qwen/commands',
+    // Qwen custom commands are TOML, not markdown; skills launch via Qwen's
+    // own `/skills <name>` surface. A synthesised markdown `.md` under
+    // `.qwen/commands` would be silently ignored — so Xema emits NOTHING.
+    commandFormat: RuntimeCommandFormat.Toml,
+    runtimeConfigFile: '/workspace/.qwen/settings.json',
+    // Qwen reads its `mcpServers` map INSIDE `.qwen/settings.json` (`InConfig`).
+    mcpConfigFile: null,
   },
   [WorkerRuntimeKind.ClaudeCode]: {
     kind: WorkerRuntimeKind.ClaudeCode,
@@ -77,6 +126,12 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     contextFile: '/workspace/CLAUDE.md',
     agentBundlesDir: '/workspace/.claude/agents',
     commandsDir: '/workspace/.claude/commands',
+    // Claude Code custom slash-commands ARE markdown, under `.claude/commands`.
+    commandFormat: RuntimeCommandFormat.Markdown,
+    runtimeConfigFile: '/workspace/.claude/settings.json',
+    // Claude Code reads project-scoped MCP from a DEDICATED `.mcp.json` at the
+    // workspace root (SeparateFile) — NOT from `.claude/settings.json`.
+    mcpConfigFile: '/workspace/.mcp.json',
   },
   [WorkerRuntimeKind.Hermes]: {
     kind: WorkerRuntimeKind.Hermes,
@@ -89,6 +144,11 @@ export const RUNTIME_LAYOUT_PROFILES: Readonly<
     // is a portable `.md` surface, so the composer must not mount them as files.
     agentBundlesDir: null,
     commandsDir: null,
+    // No file-based slash-command surface at all — emit nothing.
+    commandFormat: RuntimeCommandFormat.None,
+    runtimeConfigFile: '/workspace/.hermes/config.json',
+    // Hermes reads its `mcpServers` map INSIDE `.hermes/config.json` (`InConfig`).
+    mcpConfigFile: null,
   },
 };
 

package/src/worker-runtime/lib/workspace-sandbox.ts

@@ -0,0 +1,129 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace-sandbox protection contract ──
+//
+// A FIRST-CLASS, per-runtime security invariant for the agent-workspace sandbox.
+// The agent runs a code CLI (OpenCode/Qwen/Claude/Hermes) inside the workspace
+// pod with its OWN file tools (read/edit/write). Those tools MUST NOT be able to:
+//
+//   (a) READ the mounted platform secrets — the runtime config file carries the
+//       LLM-gateway credential (a signed JWT) and/or merged MCP bearer headers,
+//       and a dedicated `.mcp.json` (Claude) carries per-server bearer headers.
+//   (b) MUTATE the agent's OWN system-instructions / agent-definition bundles —
+//       the auto-loaded context file (`AGENTS.md`/`CLAUDE.md`), the file-based
+//       sub-agent definitions, the Xema-private system overlay + injected
+//       instruction sections, and the `context.json` capability-authority spec
+//       (rewriting it would let the agent self-grant tools).
+//
+// This module DECLARES that protected-path set ONCE, derived from the kernel
+// `RuntimeLayoutProfile` (the SSOT for every per-runtime path). Each runtime's
+// config builder translates the neutral glob set into its NATIVE permission
+// vocabulary (OpenCode `permission.read`/`permission.edit` globs; Claude Code
+// `permissions.deny: ["Read(...)","Edit(...)"]`). Runtimes with no per-file
+// permission surface (Qwen/Hermes) cannot consume the deny set and fall back to
+// the pod's uid + per-org mount confinement — see the residual note in each
+// builder. The contract is declared here regardless so the invariant is
+// single-sourced, not scattered across builders.
+//
+// Globs are runtime-syntax-NEUTRAL absolute paths anchored at `/workspace`
+// (`*` matches any character; `<dir>/**` covers a whole slot). Callers adapt
+// them to their runtime's matcher.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  WorkspaceMount,
+} from '../../agent-workspace/lib/workspace-layout';
+
+import type { RuntimeLayoutProfile } from './runtime-layout-profile';
+
+/**
+ * The resolved protected-path set for one runtime's workspace sandbox.
+ *
+ * - `secretReadDenyGlobs` — the agent's READ tool must DENY these (secrets). The
+ *   agent may still read its own instructions/code; only credential-bearing
+ *   files are denied.
+ * - `protectedEditDenyGlobs` — the agent's EDIT/WRITE tool must DENY these
+ *   (own system-instructions, agent-definitions, authority spec, and — defense
+ *   in depth — its own credential config). The agent may still edit workspace
+ *   code, deliverables, repos, inputs, uploads, and tmp.
+ *
+ * Every entry is an absolute `/workspace/...` glob. Both sets are de-duplicated
+ * and stable-ordered.
+ */
+export interface WorkspaceSandboxProtection {
+  readonly secretReadDenyGlobs: readonly string[];
+  readonly protectedEditDenyGlobs: readonly string[];
+}
+
+/**
+ * Constant, runtime-AGNOSTIC Xema-private system-instruction + authority slots.
+ * These are excluded from the per-runtime `RuntimeLayoutProfile` on purpose (the
+ * profile only carries the slots whose ON-DISK path differs per runtime), so
+ * they are sourced from the `WorkspaceMount` SSOT here — never re-literalled.
+ *
+ * All are EDIT-denied (never mutate the injected system overlay / instructions /
+ * capability-authority). They are NOT read-denied: the runtime legitimately
+ * loads the overlay + instructions as context, and the plugin reads
+ * `context.json`.
+ */
+const XEMA_PRIVATE_INSTRUCTION_EDIT_GLOBS: readonly string[] = [
+  // /workspace/.xema/system-overlay.md — the injected system prompt overlay.
+  WorkspaceMount.SystemOverlay,
+  // /workspace/.xema/instructions/** — injected rule/policy instruction sections.
+  `${WorkspaceMount.Instructions}/**`,
+  // /workspace/context.json — carries authority.allowedXemaTools; rewriting it
+  // would let the agent escalate its own tool grants.
+  WorkspaceMount.ContextJson,
+];
+
+function dedupeStable(globs: readonly string[]): string[] {
+  return [...new Set(globs)];
+}
+
+/**
+ * Derive the workspace-sandbox protected-path set for a runtime, from its
+ * kernel `RuntimeLayoutProfile`. Pure — no I/O, no defaults that mask input.
+ *
+ * The set is CLOSED and fail-closed: a config file always exists (every runtime
+ * declares `runtimeConfigFile`), and every credential-bearing / instruction path
+ * the profile exposes is protected. A runtime with no file-based sub-agent
+ * surface (`agentBundlesDir === null`, e.g. Hermes) contributes no agent-def
+ * glob — there is no such directory to protect.
+ */
+export function deriveWorkspaceSandboxProtection(
+  profile: RuntimeLayoutProfile,
+): WorkspaceSandboxProtection {
+  const configFile = profile.runtimeConfigFile;
+  const mcpFile = profile.mcpConfigFile;
+
+  // ── (a) Secret READ deny ─────────────────────────────────────────────────
+  // The credential-bearing config file + (if separate) the bearer-header MCP
+  // file. Nothing else is read-denied — the agent must still read its own
+  // instructions + workspace code.
+  const secretReadDenyGlobs: string[] = [configFile];
+  if (mcpFile !== null) {
+    secretReadDenyGlobs.push(mcpFile);
+  }
+
+  // ── (b) Own-instruction / agent-def EDIT deny ────────────────────────────
+  const protectedEditDenyGlobs: string[] = [
+    // The auto-loaded context file (AGENTS.md / CLAUDE.md) IS the agent's own
+    // system instructions.
+    profile.contextFile,
+    // Defense in depth: never let the agent rewrite its own credential config
+    // (e.g. to strip its own deny rules or exfiltrate the token).
+    configFile,
+    ...XEMA_PRIVATE_INSTRUCTION_EDIT_GLOBS,
+  ];
+  if (mcpFile !== null) {
+    protectedEditDenyGlobs.push(mcpFile);
+  }
+  if (profile.agentBundlesDir !== null) {
+    // The whole file-based sub-agent-definition slot.
+    protectedEditDenyGlobs.push(`${profile.agentBundlesDir}/**`);
+  }
+
+  return {
+    secretReadDenyGlobs: dedupeStable(secretReadDenyGlobs),
+    protectedEditDenyGlobs: dedupeStable(protectedEditDenyGlobs),
+  };
+}

package/src/workflow/index.ts

@@ -8,6 +8,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 export * from './lib/enums';
+export * from './lib/workflow-control';
 export * from './lib/temporal-namespace';
 export * from './lib/platform-task-queue';
 export * from './lib/errors';

package/src/workflow/lib/enums.ts

@@ -263,6 +263,14 @@ export enum BuiltInActionId {
   HTTP = 'xema/http',
   WAIT = 'xema/wait',
   EMIT_ARTIFACT = 'xema/emit-artifact',
+  /**
+   * Pull a declared external ingestion source into its local catalog — the
+   * generic runtime counterpart of a `ContributionKind.IngestionSource`
+   * declaration. Any sub-app that materializes an external dataset on a cadence
+   * dispatches this action; the caller resolves which source to pull. The
+   * implementation ships later in workflow-runtime-worker.
+   */
+  INGEST_SOURCE = 'xema/ingest-source',
   ENDPOINT_FETCH = 'xema/endpoint-fetch',
   SCM_POST_REVIEW = 'software-dev/scm-post-review',
   DISPATCH_WORKFLOW = 'xema/dispatch-workflow',

package/src/workflow/lib/model-ref.ts

@@ -64,6 +64,51 @@ export const ModelClassSchema = z.enum(
   MODEL_CLASS_VALUES as readonly [ModelClass, ...ModelClass[]],
 );
 
+/**
+ * A model's INTRINSIC capability / modality — what a concrete model can do
+ * regardless of which routing tier ({@link ModelClass}) selected it. The
+ * SINGLE source of truth for the closed set
+ * `vision | long_context | reasoning | function_calling | audio | embedding`.
+ *
+ * Consumed as a first-class dimension by the Model Resolution Matrix
+ * (`ResolutionDimension.ModelCapability` in `@xemahq/kernel-contracts/agent-composition`),
+ * so an org can route "any invocation that needs vision" to a capable model
+ * without pinning a provider. Domain-agnostic: describes the model, never a
+ * business use-case.
+ */
+export enum ModelCapability {
+  /** Accepts image input (multimodal vision). */
+  VISION = 'vision',
+  /** Supports an extended context window beyond the baseline tier. */
+  LONG_CONTEXT = 'long_context',
+  /** Exposes explicit step-by-step / extended-thinking reasoning. */
+  REASONING = 'reasoning',
+  /** Supports structured tool / function calling. */
+  FUNCTION_CALLING = 'function_calling',
+  /** Accepts or produces audio. */
+  AUDIO = 'audio',
+  /** Produces embedding vectors (retrieval / similarity). */
+  EMBEDDING = 'embedding',
+}
+
+export const MODEL_CAPABILITY_VALUES: readonly ModelCapability[] = [
+  ModelCapability.VISION,
+  ModelCapability.LONG_CONTEXT,
+  ModelCapability.REASONING,
+  ModelCapability.FUNCTION_CALLING,
+  ModelCapability.AUDIO,
+  ModelCapability.EMBEDDING,
+];
+
+/**
+ * Zod schema for {@link ModelCapability}. Built from the enum so the literal
+ * list lives in exactly one place. Use this in any YAML/wire schema that
+ * needs to validate a model-capability field.
+ */
+export const ModelCapabilitySchema = z.enum(
+  MODEL_CAPABILITY_VALUES as readonly [ModelCapability, ...ModelCapability[]],
+);
+
 export enum ModelRefKind {
   CONCRETE = 'concrete',
   STRATEGY = 'strategy',

package/src/workflow/lib/workflow-control.ts

@@ -0,0 +1,198 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Governed Workflow-Control Contracts ──
+//
+// Wire contracts for the least-privilege "workflow-control" surface: an
+// in-session agent invoking its OWN governing workflow run's control signals
+// (decide a decision gate, answer a pending inquiry, change run status) as a
+// governed tool.
+//
+// The agent NEVER supplies the target run or org — those are server-derived
+// from the verified session/token and injected by the mcp-gateway bridge into
+// `runId` / `orgId`. This file carries the closed action set, the settable
+// run-status subset, the typed rejection codes, the engine-internal request
+// shape, and the first-class structured accepted/rejected RESULT.
+//
+// The RESULT is deliberately a structured discriminated union (never an opaque
+// 4xx) so the calling model reads a typed outcome rather than mis-parsing an
+// HTTP error. The engine-internal control endpoint returns HTTP 200 carrying
+// this shape for every BUSINESS outcome (accepted or rejected); only genuine
+// server faults surface as non-2xx.
+//
+// Shared between workflow-engine-api (the control surface) and mcp-gateway-api
+// (the governed tool). Runtime-framework-agnostic — no NestJS, no Prisma.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import { DecisionVerdict } from '../../decision-gate/lib/decision-gate';
+
+/**
+ * The closed set of control actions an agent may take against its own
+ * governing run. Reuses the platform's existing signal/gate/inquiry
+ * mechanisms — no second control path.
+ *
+ * - `DECIDE_GATE`    — submit a decision-gate verdict (approve/reject/abstain)
+ *                      on a `DECISION_GATE` inquiry belonging to the run.
+ * - `ANSWER_INQUIRY` — submit a reply to a pending non-gate inquiry
+ *                      (`AGENT_TOOL_INQUIRY` / `REVIEW`) belonging to the run.
+ * - `SET_RUN_STATUS` — request a run-status transition (pause / resume /
+ *                      cancel) via the existing run signal.
+ *
+ * Phase refine/restart is intentionally absent: the engine ships no
+ * server-side phase-refinement mechanism to reuse today (the run "redo"
+ * affordance is UI-metadata only). Adding it is a coordinated engine+worker
+ * change plus a member here — not a silent no-op action.
+ */
+export enum WorkflowControlAction {
+  DECIDE_GATE = 'decide_gate',
+  ANSWER_INQUIRY = 'answer_inquiry',
+  SET_RUN_STATUS = 'set_run_status',
+}
+
+/**
+ * The settable run-status transitions an agent may request. A closed subset of
+ * `WorkflowRunStatus` — only the values that map 1:1 onto an existing run
+ * signal. The engine translates each to the corresponding signal:
+ *
+ *   PAUSED    → `pauseRun`
+ *   RUNNING   → `resumeRun`
+ *   CANCELLED → `cancelRun`
+ *
+ * Terminal statuses (succeeded/failed/…) are NOT settable — a run reaches
+ * those only through its own execution, never an agent control signal.
+ */
+export enum WorkflowRunStatusTarget {
+  PAUSED = 'paused',
+  RUNNING = 'running',
+  CANCELLED = 'cancelled',
+}
+
+/**
+ * Typed rejection codes for the structured control RESULT. Closed set — the
+ * calling model branches on these, so free-form strings are forbidden. Each
+ * corresponds to a pre-validation against live run/gate/inquiry state.
+ */
+export enum WorkflowControlRejectionCode {
+  /** The calling session is not bound to any governing workflow run. */
+  NO_GOVERNING_RUN = 'NO_GOVERNING_RUN',
+  /** The request failed contract validation before any state was touched. */
+  INVALID_REQUEST = 'INVALID_REQUEST',
+  /** The bound run does not exist for the session's org (uniform anti-probe). */
+  RUN_NOT_FOUND = 'RUN_NOT_FOUND',
+  /** The run is in a terminal state and accepts no control signal. */
+  RUN_ALREADY_TERMINAL = 'RUN_ALREADY_TERMINAL',
+  /** The run's execution rejected the requested signal. */
+  RUN_SIGNAL_REJECTED = 'RUN_SIGNAL_REJECTED',
+  /** The referenced inquiry does not exist for the session's org. */
+  INQUIRY_NOT_FOUND = 'INQUIRY_NOT_FOUND',
+  /** The referenced inquiry does not belong to the session's governing run. */
+  INQUIRY_NOT_ON_RUN = 'INQUIRY_NOT_ON_RUN',
+  /** The inquiry kind does not match the action (gate vs non-gate). */
+  INQUIRY_WRONG_KIND = 'INQUIRY_WRONG_KIND',
+  /** The gate is no longer pending and accepts no further verdicts. */
+  GATE_NOT_PENDING = 'GATE_NOT_PENDING',
+  /** The inquiry is no longer pending and accepts no further replies. */
+  INQUIRY_NOT_PENDING = 'INQUIRY_NOT_PENDING',
+  /** No recipient with the given id exists on the inquiry. */
+  RECIPIENT_NOT_FOUND = 'RECIPIENT_NOT_FOUND',
+  /** The targeted recipient is not an AGENT recipient — an agent tool may
+   *  only reply as an agent recipient, never forge a human/endpoint verdict. */
+  RECIPIENT_NOT_AGENT = 'RECIPIENT_NOT_AGENT',
+  /** The targeted recipient has already replied (idempotent-safe rejection). */
+  RECIPIENT_ALREADY_REPLIED = 'RECIPIENT_ALREADY_REPLIED',
+}
+
+// ─── Request (engine-internal wire shape) ────────────────────────────────────
+//
+// `runId` + `orgId` are the SERVER-derived tenancy/subject binding injected by
+// the gateway from the verified session token — they are part of the wire
+// shape the engine validates, but the AGENT never supplies them.
+
+const RunBindingShape = {
+  /** The governing run, injected server-side from the session — not agent input. */
+  runId: z.string().min(1),
+  /** The session's org, injected server-side from the token — not agent input. */
+  orgId: z.string().min(1),
+} as const;
+
+const DecideGateRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.DECIDE_GATE),
+  /** The DECISION_GATE inquiry to decide (must belong to the governing run). */
+  inquiryId: z.string().min(1),
+  /** The agent recipient row on the inquiry the caller replies AS. */
+  recipientId: z.string().min(1),
+  verdict: z.nativeEnum(DecisionVerdict),
+  /** Required (non-empty) when verdict is REJECT — enforced downstream by the
+   *  reused `DecisionGateReplySchema`. */
+  reason: z.string().optional(),
+});
+
+const AnswerInquiryRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.ANSWER_INQUIRY),
+  /** The non-gate inquiry to answer (must belong to the governing run). */
+  inquiryId: z.string().min(1),
+  /** The agent recipient row on the inquiry the caller replies AS. */
+  recipientId: z.string().min(1),
+  /** Kind-specific reply payload — validated by the inquiry kind's own schema. */
+  payload: z.record(z.string(), z.unknown()),
+});
+
+const SetRunStatusRequestSchema = z.object({
+  ...RunBindingShape,
+  action: z.literal(WorkflowControlAction.SET_RUN_STATUS),
+  status: z.nativeEnum(WorkflowRunStatusTarget),
+  reason: z.string().optional(),
+});
+
+/**
+ * The engine-internal control request. Discriminated on `action`; every member
+ * carries the server-derived `runId` + `orgId` binding.
+ */
+export const WorkflowControlRequestSchema = z.discriminatedUnion('action', [
+  DecideGateRequestSchema,
+  AnswerInquiryRequestSchema,
+  SetRunStatusRequestSchema,
+]);
+export type WorkflowControlRequest = z.infer<typeof WorkflowControlRequestSchema>;
+
+export type DecideGateRequest = z.infer<typeof DecideGateRequestSchema>;
+export type AnswerInquiryRequest = z.infer<typeof AnswerInquiryRequestSchema>;
+export type SetRunStatusRequest = z.infer<typeof SetRunStatusRequestSchema>;
+
+// ─── Result (first-class structured accepted/rejected outcome) ───────────────
+
+export const WorkflowControlResultSchema = z.discriminatedUnion('ok', [
+  z.object({
+    ok: z.literal(true),
+    /** Optional human-readable note (e.g. which signal was sent). */
+    detail: z.string().optional(),
+  }),
+  z.object({
+    ok: z.literal(false),
+    code: z.nativeEnum(WorkflowControlRejectionCode),
+    message: z.string().min(1),
+  }),
+]);
+export type WorkflowControlResult = z.infer<typeof WorkflowControlResultSchema>;
+
+/** Construct an accepted result. */
+export function workflowControlAccepted(detail?: string): WorkflowControlResult {
+  return detail === undefined ? { ok: true } : { ok: true, detail };
+}
+
+/** Construct a typed rejection result. */
+export function workflowControlRejected(
+  code: WorkflowControlRejectionCode,
+  message: string,
+): WorkflowControlResult {
+  return { ok: false, code, message };
+}
+
+/**
+ * The canonical capability ref governing this surface. `workflow` is an
+ * existing first-party capability domain; the router dispatches this ref to the
+ * engine's internal control endpoint and authorization-api gates it by grant.
+ */
+export const WORKFLOW_CONTROL_CAPABILITY_REF = 'workflow:control@1';