@xemahq/kernel-contracts 0.1.0

package/src/workflow/lib/errors.ts

@@ -0,0 +1,171 @@
+/**
+ * Typed error codes produced by the workflow plane. Every error raised by
+ * the engine, compiler, evaluator, or worker picks a code from this enum.
+ *
+ * Enum-based so:
+ *   - OpenAPI emits a stable `code` field (docs/API_STANDARDS §3.5).
+ *   - The retry policy can mark specific codes as non-retryable
+ *     deterministically (see CompiledRetryPolicy.nonRetryableErrorTypes).
+ *   - Frontend switches are exhaustive.
+ */
+export enum WorkflowErrorCode {
+  // Validation — the authored YAML failed JSON-Schema or semantic rules.
+  DSL_SCHEMA_INVALID = 'DSL_SCHEMA_INVALID',
+  DSL_SEMANTIC_INVALID = 'DSL_SEMANTIC_INVALID',
+  DSL_EXPRESSION_INVALID = 'DSL_EXPRESSION_INVALID',
+  DSL_CYCLE_DETECTED = 'DSL_CYCLE_DETECTED',
+  DSL_MATRIX_CARDINALITY_EXCEEDED = 'DSL_MATRIX_CARDINALITY_EXCEEDED',
+  DSL_UNKNOWN_ACTION = 'DSL_UNKNOWN_ACTION',
+  DSL_UNKNOWN_REUSABLE_WORKFLOW = 'DSL_UNKNOWN_REUSABLE_WORKFLOW',
+  /**
+   * A literal `with.agentSlug` (or `with.reviewers[].agentSlug`) value
+   * does not appear in the resolvedAgents map the engine passed to the
+   * compiler. Indicates a typo, a stale slug, or a new agent that was
+   * never seeded into llm-registry.
+   */
+  DSL_UNKNOWN_AGENT = 'DSL_UNKNOWN_AGENT',
+  /**
+   * A literal `with.deliverableSpecRef` value does not appear in the
+   * resolvedDeliverableSpecs map. Indicates a typo or a spec that was
+   * renamed/removed from deliverable-specs-api.
+   */
+  DSL_UNKNOWN_DELIVERABLE_SPEC = 'DSL_UNKNOWN_DELIVERABLE_SPEC',
+  /**
+   * An expression of shape `${{ needs.<job>.outputs.deliverable.content.<field> }}`
+   * (or the matrix-keyed equivalent `…outputs.byKey[<k>].deliverable.content.<field>`)
+   * reads a `<field>` that does NOT exist on the producing job's declared
+   * deliverable spec content shape. Indicates the YAML and the spec have
+   * drifted: either the expression has a typo or the spec changed shape
+   * without the workflow being updated.
+   */
+  DSL_UNKNOWN_DELIVERABLE_FIELD = 'DSL_UNKNOWN_DELIVERABLE_FIELD',
+  DSL_VERSION_NOT_RESOLVABLE = 'DSL_VERSION_NOT_RESOLVABLE',
+  DSL_PERMISSION_ESCALATION = 'DSL_PERMISSION_ESCALATION',
+  /**
+   * A consumer expression dereferences `needs.<X>.outputs.byKey[…]` but
+   * `<X>` is either not a matrix job, or is matrix without `keyBy:`
+   * declared. Authors must add `keyBy:` upstream or switch to positional
+   * / `matrixGather:` access.
+   */
+  DSL_MATRIX_KEY_NOT_DECLARED = 'DSL_MATRIX_KEY_NOT_DECLARED',
+  /**
+   * A consumer expression accesses a matrix upstream's outputs in a
+   * shape the runtime cannot serve — e.g. bare `.deliverables` on a
+   * matrix without `matrixGather:`, or `byKey[<non-literal-non-matrix-binding>]`,
+   * or `byKey[matrix.x.<wrongField>]` where `<wrongField>` doesn't match
+   * upstream's `keyBy:`. Compile-time fix-it carries the three valid
+   * shapes (`outputs[<n>]`, `matrixGather:`, `keyBy:` + `byKey[…]`).
+   */
+  DSL_INVALID_MATRIX_OUTPUT_ACCESS = 'DSL_INVALID_MATRIX_OUTPUT_ACCESS',
+  /**
+   * A consumer expression of shape
+   * `${{ needs.<job>.outputs.<name>.<payload-field> }}` reaches INTO the
+   * artifact payload of an upstream's named output, but the producing
+   * job's output declaration has no schema-bearing deliverable spec
+   * (`ZOD_SCHEMA` / `JSON_SCHEMA` / `DOCUMENT_TEMPLATE` with declared
+   * frontmatter). Authors must either bind a typed spec to the output
+   * or use the `fromJSON(...)` escape hatch — silent string fallback
+   * is forbidden.
+   */
+  DSL_FIELD_NOT_TYPED = 'DSL_FIELD_NOT_TYPED',
+  /**
+   * A consumer expression reaches into a typed payload at a path that
+   * does NOT exist on the bound deliverable spec's JSON Schema. The
+   * spec and the YAML have drifted: fix the path or update the spec.
+   */
+  DSL_FIELD_NOT_IN_SCHEMA = 'DSL_FIELD_NOT_IN_SCHEMA',
+
+  // Compile — compile-time failure not covered above.
+  COMPILE_INTERNAL = 'COMPILE_INTERNAL',
+  /**
+   * Compile-preview was called without a resolvable projectId — neither
+   * `trigger.projectId` in the body nor the `X-Project-Id` header was
+   * supplied. Surfaced as 400 so the Workflow Builder can prompt the
+   * author to pick a project before validating drafts.
+   */
+  COMPILE_PROJECT_ID_REQUIRED = 'COMPILE_PROJECT_ID_REQUIRED',
+
+  // Runtime — reported via the workflow runtime's activity failures.
+  RUNTIME_ACTION_FAILED = 'RUNTIME_ACTION_FAILED',
+  RUNTIME_APPROVAL_REJECTED = 'RUNTIME_APPROVAL_REJECTED',
+  RUNTIME_APPROVAL_EXPIRED = 'RUNTIME_APPROVAL_EXPIRED',
+  RUNTIME_UNKNOWN_MATRIX_ENTRY = 'RUNTIME_UNKNOWN_MATRIX_ENTRY',
+  RUNTIME_DYNAMIC_MATRIX_OVERFLOW = 'RUNTIME_DYNAMIC_MATRIX_OVERFLOW',
+  /**
+   * Two upstream matrix entries produced the same `keyBy` value. Fail-
+   * fast at dispatch time before any iteration runs — the keyed output
+   * map cannot be built unambiguously.
+   */
+  RUNTIME_MATRIX_KEY_DUPLICATE = 'RUNTIME_MATRIX_KEY_DUPLICATE',
+  /**
+   * An upstream matrix entry doesn't carry the `keyBy` path (e.g. an
+   * entry produced by a dynamic `from:` source has no `id` field while
+   * `keyBy: id` is declared). Fail-fast at dispatch time.
+   */
+  RUNTIME_MATRIX_KEY_MISSING_AT_BIND_TIME = 'RUNTIME_MATRIX_KEY_MISSING_AT_BIND_TIME',
+  RUNTIME_SNAPSHOT_UNREADABLE = 'RUNTIME_SNAPSHOT_UNREADABLE',
+  RUNTIME_CONCURRENCY_CONFLICT = 'RUNTIME_CONCURRENCY_CONFLICT',
+  /**
+   * `fromJSON(ref)` evaluated against an `ArtifactRef` whose payload
+   * could not be fetched or parsed as JSON at runtime. Surfaces both
+   * artifact-store transport failures and "the bytes are not JSON"
+   * cases; the `cause` carries the upstream error message. This is the
+   * runtime counterpart of `DSL_FIELD_NOT_TYPED` / `DSL_FIELD_NOT_IN_SCHEMA`
+   * for authors who opted out of compile-time validation via the
+   * `fromJSON(...)` escape hatch.
+   */
+  DSL_PAYLOAD_PARSE_ERROR = 'DSL_PAYLOAD_PARSE_ERROR',
+  /**
+   * The agent activity harvested its workspace and ran the deliverable
+   * spec's kind handler validation. Validation failed twice: once on the
+   * initial drive, then again after the structured self-correction
+   * attempt that re-uses the same agent session. The activity surfaces
+   * both failure objects (`{ first, second }`) on the error cause and
+   * fails the activity non-retryably.
+   */
+  DELIVERABLE_CONTRACT_VIOLATED = 'DELIVERABLE_CONTRACT_VIOLATED',
+
+  /**
+   * The workflow's `requires.variables` declares one or more entries the
+   * engine could not resolve from the org/project variable store at
+   * dispatch time. The run is never started. The error payload carries
+   * `{ missing: string[] }` so the dispatch UI can list the unconfigured
+   * keys and deep-link to the variables settings page.
+   */
+  WORKFLOW_VARIABLES_MISSING = 'WORKFLOW_VARIABLES_MISSING',
+
+  /**
+   * One or more wallets declared under `requires.wallets` (or passed at
+   * dispatch / session-create time as additional wallets) does not
+   * exist for the target project/org scope. The error payload carries
+   * `{ missing: string[] }` so the UI can list them and offer a
+   * "create wallet" affordance.
+   */
+  WORKFLOW_WALLET_NOT_FOUND = 'WORKFLOW_WALLET_NOT_FOUND',
+}
+
+/** Error codes that must never be retried by an activity retry policy. */
+export const NON_RETRYABLE_WORKFLOW_ERROR_CODES: readonly WorkflowErrorCode[] = [
+  WorkflowErrorCode.DSL_SCHEMA_INVALID,
+  WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+  WorkflowErrorCode.DSL_EXPRESSION_INVALID,
+  WorkflowErrorCode.DSL_CYCLE_DETECTED,
+  WorkflowErrorCode.DSL_MATRIX_CARDINALITY_EXCEEDED,
+  WorkflowErrorCode.DSL_UNKNOWN_ACTION,
+  WorkflowErrorCode.DSL_UNKNOWN_REUSABLE_WORKFLOW,
+  WorkflowErrorCode.DSL_UNKNOWN_AGENT,
+  WorkflowErrorCode.DSL_UNKNOWN_DELIVERABLE_SPEC,
+  WorkflowErrorCode.DSL_UNKNOWN_DELIVERABLE_FIELD,
+  WorkflowErrorCode.DSL_VERSION_NOT_RESOLVABLE,
+  WorkflowErrorCode.DSL_PERMISSION_ESCALATION,
+  WorkflowErrorCode.DSL_MATRIX_KEY_NOT_DECLARED,
+  WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS,
+  WorkflowErrorCode.DSL_FIELD_NOT_TYPED,
+  WorkflowErrorCode.DSL_FIELD_NOT_IN_SCHEMA,
+  WorkflowErrorCode.RUNTIME_APPROVAL_REJECTED,
+  WorkflowErrorCode.RUNTIME_APPROVAL_EXPIRED,
+  WorkflowErrorCode.RUNTIME_DYNAMIC_MATRIX_OVERFLOW,
+  WorkflowErrorCode.RUNTIME_MATRIX_KEY_DUPLICATE,
+  WorkflowErrorCode.RUNTIME_MATRIX_KEY_MISSING_AT_BIND_TIME,
+  WorkflowErrorCode.DELIVERABLE_CONTRACT_VIOLATED,
+] as const;

package/src/workflow/lib/job-run.ts

@@ -0,0 +1,65 @@
+import { JobRunStatus, StepRunStatus } from './enums';
+
+/**
+ * Projection row for a single job run in the engine's read model. Not the
+ * Temporal execution truth (that lives in Temporal history); this is the
+ * materialized view the UI queries without touching Temporal on every
+ * request.
+ *
+ * Projections are rebuilt by consuming `WorkflowEvent` records produced by
+ * the worker via activity completions and workflow signals. The read model
+ * can be recomputed from event history at any time — deterministic by
+ * construction.
+ */
+export interface JobRun {
+  readonly id: string;
+  readonly workflowRunId: string;
+  readonly jobKey: string;
+  /**
+   * Index within the parent job's matrix expansion. `0` for single-strategy
+   * jobs; 0..N-1 for matrix/dynamic expansions.
+   */
+  readonly matrixIndex: number;
+  /** Matrix binding values for this instance (empty object for single-strategy). */
+  readonly matrixBinding: Readonly<Record<string, unknown>>;
+  readonly status: JobRunStatus;
+  readonly startedAt: string | null;
+  readonly completedAt: string | null;
+  /** Number of attempts Temporal made for this job (post-retry). */
+  readonly attempt: number;
+  /**
+   * Outputs from the job's action, typed by the action's output schema.
+   * Null until status reaches SUCCEEDED.
+   */
+  readonly outputs: Readonly<Record<string, unknown>> | null;
+  /** Error record, null unless status is FAILED. */
+  readonly error: JobRunError | null;
+  /** Temporal child workflow id or activity id this job is backed by. */
+  readonly temporalHandle: string;
+}
+
+export interface JobRunError {
+  /** Short error type code. Used by retry policy to decide non-retryable. */
+  readonly type: string;
+  readonly message: string;
+  /** Structured details — may include validation issues or downstream trace id. */
+  readonly details: Readonly<Record<string, unknown>> | null;
+}
+
+/**
+ * Projection row for a single step run (one action invocation) inside a
+ * job. Most jobs have exactly one step — steps are granular enough to
+ * distinguish retries and, for composite actions like `xema/review@v3`
+ * that fan out per reviewer, the per-reviewer sub-activities.
+ */
+export interface StepRun {
+  readonly id: string;
+  readonly jobRunId: string;
+  readonly stepKey: string;
+  readonly status: StepRunStatus;
+  readonly startedAt: string | null;
+  readonly completedAt: string | null;
+  readonly attempt: number;
+  readonly outputs: Readonly<Record<string, unknown>> | null;
+  readonly error: JobRunError | null;
+}

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

@@ -0,0 +1,118 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Model Reference + Sub-Agent Binding ──
+//
+// Shared contract for "which model should this invocation use?" and
+// "which delegates should the primary agent have access to?".
+//
+// Used by every override slot in the platform:
+//   - Session.modelSelection            (agent-session-api)
+//   - Session.subAgentBindings          (agent-session-api)
+//   - AgentSessionProfile.defaultModel / defaultSubAgents (llm-registry-api)
+//   - ManifestAgentBlock.defaultModel / subAgents               (workspace-manifest-dsl)
+//   - workflow DSL  with.model / with.subAgents                 (workflow-dsl)
+//   - DrivePromptParams.modelOverride   (agent-runtime-bridge)
+//
+// Resolution chain (highest precedence first):
+//   1. Session/run override
+//   2. Profile default          (agent-session only)
+//   3. Manifest default
+//   4. AgentModelOverride       (project/user/org cascade)
+//   5. Agent's modelClass strategy (built-in default)
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+/**
+ * LLM-routing tier. The SINGLE source of truth for the closed set
+ * `utility | planning | creative | coding | review` — every other
+ * consumer (DTOs, Zod schemas, frontend lookups) MUST import from here
+ * (or re-export this enum) instead of restating the literal list.
+ *
+ * Mirrors `biomes/agent-runtime/api/llm-registry-api`'s Prisma `ModelClass` column.
+ *
+ * IMPORTANT — the one allowed copy is in `@xemahq/biome-builder`'s
+ * `contribution-schemas.ts`, because that package publishes to the
+ * public npm registry and cannot depend on this GitHub-Packages-scoped
+ * package. That copy carries a comment marker; keep both lists
+ * value-identical. The vitest at
+ * `packages/ui/biome-builder/tests/model-class-parity.spec.ts` fails
+ * fast if they drift.
+ */
+export enum ModelClass {
+  CODING = 'coding',
+  REVIEW = 'review',
+  CREATIVE = 'creative',
+  PLANNING = 'planning',
+  UTILITY = 'utility',
+}
+
+export const MODEL_CLASS_VALUES: readonly ModelClass[] = [
+  ModelClass.CODING,
+  ModelClass.REVIEW,
+  ModelClass.CREATIVE,
+  ModelClass.PLANNING,
+  ModelClass.UTILITY,
+];
+
+/**
+ * Zod schema for {@link ModelClass}. 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-class field.
+ */
+export const ModelClassSchema = z.enum(
+  MODEL_CLASS_VALUES as readonly [ModelClass, ...ModelClass[]],
+);
+
+export enum ModelRefKind {
+  CONCRETE = 'concrete',
+  STRATEGY = 'strategy',
+}
+
+/**
+ * Pin to a specific (modelId, providerSlug). The provider slug is
+ * optional only when the modelId is globally unique across credentialed
+ * providers for the org — when ambiguous, the resolver returns 400.
+ */
+export interface ConcreteModelRef {
+  readonly kind: ModelRefKind.CONCRETE;
+  readonly modelId: string;
+  readonly providerSlug?: string;
+  readonly temperature?: number;
+}
+
+/**
+ * Route through the existing `ModelStrategy` cascade for a given
+ * `ModelClass`. The bound model can change without invalidating the
+ * reference (lazy resolution).
+ */
+export interface StrategyModelRef {
+  readonly kind: ModelRefKind.STRATEGY;
+  readonly modelClass: ModelClass;
+  readonly temperature?: number;
+}
+
+export type ModelRef = ConcreteModelRef | StrategyModelRef;
+
+export function isConcreteModelRef(ref: ModelRef): ref is ConcreteModelRef {
+  return ref.kind === ModelRefKind.CONCRETE;
+}
+
+export function isStrategyModelRef(ref: ModelRef): ref is StrategyModelRef {
+  return ref.kind === ModelRefKind.STRATEGY;
+}
+
+/**
+ * A runtime attachment: "while this session/step runs, mount agent
+ * `slug` as a delegate available to the primary, optionally with a
+ * model override."
+ *
+ * Intrinsic delegates (those declared in the primary's own source
+ * manifest under `permission.task.<slug>: allow`) are the floor — they
+ * are always mounted and cannot be removed by any binding layer. A
+ * binding on an intrinsic slug refines its model only.
+ */
+export interface SubAgentBinding {
+  readonly slug: string;
+  readonly alias?: string;
+  readonly modelOverride?: ModelRef;
+}

package/src/workflow/lib/mount-plan.ts

@@ -0,0 +1,230 @@
+/**
+ * Compile-time mount plan — declarative list of mount keys grouped by
+ * access mode. The compiler does NOT have access to the engine's resource
+ * registries (org-scoped Postgres state), so it emits only the authored
+ * declaration shape.
+ *
+ * At dispatch time the engine resolves each declared key against the org's
+ * resource registry + the calling user's permission scope, producing a
+ * {@link ResolvedMountPlan} that the activity uses to materialize files
+ * inside `/workspace`.
+ *
+ * Read-only vs read-write is fixed at compile time: the set of authored
+ * read-write mount keys is closed (today: `deliverables`) and enforced by
+ * the compiler's mount-plan stage.
+ */
+export interface MountPlan {
+  readonly readOnly: readonly MountDeclaration[];
+  readonly readWrite: readonly MountDeclaration[];
+}
+
+export interface MountDeclaration {
+  /** Logical mount key as authored, e.g. `references`, `uploads`, `repos`, `deliverables`. */
+  readonly key: string;
+}
+
+/** Engine-dispatch-time resolved mount plan — produced from {@link MountPlan}. */
+export interface ResolvedMountPlan {
+  readonly readOnly: readonly ResolvedMount[];
+  readonly readWrite: readonly ResolvedMount[];
+}
+
+export interface ResolvedMount {
+  readonly key: string;
+  readonly source: MountSource;
+}
+
+// `AgentRunRole` is the canonical role enum defined alongside `agent-role.ts`.
+// Imported for use within this module's `MountSource` discriminator and
+// re-exported below for back-compat with consumers that historically
+// imported it from this module. The `export type {}` form is required
+// (over `export … from`) because the symbol is also referenced inline in
+// the discriminator union below.
+import type { AgentRunRole } from './agent-role';
+
+// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+export type { AgentRunRole };
+
+/**
+ * Concrete source for a single mount entry. The `kind` is an enum-like
+ * discriminator; the runtime dispatches on it. Unknown kinds must fail
+ * fast (never a silent skip).
+ *
+ * The `*-definition` and `rendered-*` kinds are platform-rendered: the
+ * resolver hits llm-registry-api (or its scope-aware composition) to
+ * produce the file content. They land in the same mount-apply pipeline
+ * as user-data sources so every byte under `/workspace/` is a typed
+ * mount entry.
+ */
+export type MountSource =
+  | { readonly kind: 'artifact-store-collection'; readonly collectionId: string }
+  | {
+      /**
+       * Mount a single artifact-store version as a file at the entry's
+       * `relPath`. Used by activities that emit large primary outputs
+       * (e.g. `xema/http@v1` with `outputMode: artifact`) so the next
+       * agent can read the bytes from `/workspace/<slot>/<fileName>`
+       * via tools instead of having the engine inline them into the
+       * agent-run-context prompt.
+       *
+       * `payloadField` selects a string field inside the artifact's JSON
+       * payload to materialise as the file content. Omit to write the
+       * entire JSON payload (pretty-printed). When set and the value is
+       * not a string, the resolver fails fast — silent stringification
+       * would let an HTML body land as `"[object Object]"`.
+       */
+      readonly kind: 'artifact-version';
+      readonly artifactId: string;
+      /**
+       * Monotonic per-artifact version sequence (the integer surfaced by
+       * `xema/emit-artifact@v1.outputs.version`). Used directly against
+       * `GET /artifacts/:id/versions/:version/content`. We deliberately
+       * key off the integer rather than the row PK so the wire shape
+       * lines up with the only artifact-store read endpoint that
+       * returns the canonical content.
+       */
+      readonly version: number;
+      readonly fileName: string;
+      readonly payloadField?: string;
+      readonly contentType?: string;
+    }
+  | { readonly kind: 'kb-space'; readonly spaceId: string }
+  | {
+      /**
+       * Mount a curated subset of KB pages from a single space. Each
+       * page is materialised as its own `<pageSlug>.md` file under the
+       * entry's slot+relPath. Used by the runtime KB-mount feature
+       * (user picks individual pages/folders to attach to a live
+       * Interactive Session or Design System Builder session) — the matching
+       * `kb-space` kind is for whole-space bundles instead.
+       *
+       * `pageSlugs` MUST be non-empty; resolver fails fast otherwise
+       * so an empty selection cannot silently materialise a zero-byte
+       * mount. Duplicate slugs are de-duplicated by the resolver.
+       */
+      readonly kind: 'kb-pages';
+      readonly spaceId: string;
+      readonly pageSlugs: readonly string[];
+    }
+  | { readonly kind: 'scm-repo'; readonly repoRef: string; readonly ref: string }
+  | { readonly kind: 'session-attachment'; readonly sessionId: string }
+  | { readonly kind: 'deliverable-specs'; readonly contractKey: string }
+  | { readonly kind: 'deliverables'; readonly contractKey: string }
+  | { readonly kind: 'static-literal'; readonly pathWithinWorkspace: string; readonly bytes: string }
+  // Platform-rendered (PR 1 of unified-workspace-image refactor):
+  | {
+      readonly kind: 'agent-definition';
+      readonly orgId: string;
+      readonly agentSlug: string;
+      readonly groupKey: string;
+      /**
+       * Frontmatter `mode` for the rendered .opencode/agents/<slug>.md
+       * file. Per OpenCode docs, primary agents and sub-agents share the
+       * same directory and are differentiated by frontmatter.
+       */
+      readonly agentMode: 'primary' | 'subagent';
+    }
+  | {
+      /**
+       * Mount a complete skill BUNDLE — SKILL.md plus every bundled
+       * resource (reference docs, scripts, assets, templates) — as a
+       * directory under the `skill-bundles` slot. The resolver fetches
+       * the multi-file bundle from skill-registry-api; the mount entry's
+       * `relPath` is the skill directory (`<skillKey>`) and the resolver
+       * yields one file per bundle member.
+       */
+      readonly kind: 'skill-bundle';
+      readonly skillKey: string;
+    }
+  | {
+      readonly kind: 'instruction-section';
+      readonly orgId: string;
+      readonly sectionKey: string;
+      readonly agentSlug?: string;
+      readonly groupKey?: string;
+    }
+  | ({ readonly kind: 'rendered-agents-md' } & RenderedAgentRunContextParams)
+  | ({ readonly kind: 'rendered-system-overlay' } & RenderedAgentRunContextParams)
+  | ({ readonly kind: 'rendered-context-json' } & RenderedAgentRunContextParams);
+
+/**
+ * Shared parameter shape for the three `rendered-*` mount sources. All
+ * three resolve to bytes by calling
+ * `llm-registry-api/agent-run-context/render` once per mount-apply —
+ * the upstream returns `{agentsMd, contextJson, systemOverlay}` in a
+ * single response and each resolver yields a different field.
+ *
+ * The shape MUST be identical across the three discriminator variants
+ * so the workspace-proxy resolver-cache can coalesce the three calls
+ * by hashing the params consistently. Diverging shapes break the cache
+ * key and cause one mount-apply to issue three upstream renders
+ * instead of one (and risk the three slots seeing inconsistent
+ * contextJson/systemOverlay output if the upstream is non-deterministic
+ * on the omitted fields).
+ *
+ * Every field that affects the upstream render output must live here.
+ * Cosmetic fields not consumed by the renderer must NOT live here —
+ * they would invalidate the cache key without changing the bytes.
+ */
+export interface RenderedAgentRunContextParams {
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly agentSlug: string;
+  readonly groupKey: string;
+  readonly role: AgentRunRole;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly jobRunId?: string;
+  readonly deliverableSpecRef?: string;
+  /**
+   * Workflow `with:` / `agentContext` payload, surfaced verbatim under
+   * `context.json.workflowInputs.*` so the agent can read what the
+   * caller asked for (e.g. the user's original request) without
+   * relying on a separate `inputs/prompt.md` seed file.
+   */
+  readonly workflowInputs?: Readonly<Record<string, unknown>>;
+  /**
+   * Mounted slots and their access mode, surfaced through the renderer
+   * so `context.json.authority.mayWriteWorkspace[]` lists the slots
+   * the agent is allowed to write to. Without this the xema authority-
+   * guard hook denies every `write`/`edit`/`patch` call.
+   */
+  readonly mounts?: ReadonlyArray<{
+    readonly mount: string;
+    readonly mode: 'read-only' | 'read-write';
+  }>;
+  /**
+   * Workflow-driven input artifacts surfaced through the renderer so
+   * the agent's AGENTS.md and `context.json` enumerate exactly which
+   * files were materialised from upstream steps. Each entry maps a
+   * single artifact-store version onto an absolute workspace path —
+   * the same path the `artifact-version` mount resolver writes.
+   *
+   * The agent doesn't have to discover these by ls'ing slot
+   * directories; they appear under `# Inputs` in AGENTS.md and as
+   * `context.json.workflow.inputArtifacts[]` so a quick `read` tool
+   * call gets the bytes.
+   */
+  readonly inputArtifacts?: ReadonlyArray<{
+    readonly path: string;
+    readonly contentType?: string;
+    readonly sourceArtifactId: string;
+    readonly sourceVersion: number;
+  }>;
+  /**
+   * Working files materialized for the session before the first turn.
+   * The renderer mirrors this into `context.json.workingFiles[]` and
+   * extends `authority.mayWriteWorkspace[]` for every writable binding
+   * (`syncDirection !== 'up-only'`) so agents can discover + edit the
+   * real document file path deterministically.
+   */
+  readonly workingFiles?: ReadonlyArray<{
+    readonly slug: string;
+    readonly path: string;
+    readonly format: 'markdown' | 'html' | 'json' | 'yaml' | 'text';
+    readonly syncDirection: 'down-only' | 'up-only' | 'bidirectional';
+    readonly sourceKind: string;
+    readonly sourceRef: Readonly<Record<string, string>>;
+  }>;
+  readonly hasRetryContext?: boolean;
+}

package/src/workflow/lib/phase-report.ts

@@ -0,0 +1,67 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Complexity Tier Types ──
+//
+// Closed enum of complexity tiers used to size workflow runs and tune
+// their downstream behavior (sampling, gating, deliverable depth).
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ── Complexity Tiers ───────────────────────────────────────────────────
+
+export const COMPLEXITY_TIERS = [
+  'simple',
+  'standard',
+  'complex',
+  'enterprise',
+] as const;
+
+/** Complexity tier for a pipeline run */
+export type ComplexityTier = (typeof COMPLEXITY_TIERS)[number];
+
+/** Set of valid complexity tiers for runtime validation */
+export const COMPLEXITY_TIER_SET: ReadonlySet<string> = new Set(
+  COMPLEXITY_TIERS,
+);
+
+/**
+ * Validate whether a string is a valid ComplexityTier.
+ * Returns the typed value or undefined if invalid.
+ */
+export function parseComplexityTier(
+  value: string | null | undefined,
+): ComplexityTier | undefined {
+  if (value && COMPLEXITY_TIER_SET.has(value)) {
+    return value as ComplexityTier;
+  }
+  return undefined;
+}
+
+/**
+ * Complexity tier with an additional 'auto' sentinel —
+ * used in DTOs / UI selectors where the user can let the system decide.
+ */
+export const COMPLEXITY_TIERS_WITH_AUTO = [
+  'auto',
+  ...COMPLEXITY_TIERS,
+] as const;
+
+/** Complexity tier including the 'auto' sentinel value */
+export type ComplexityTierOrAuto = (typeof COMPLEXITY_TIERS_WITH_AUTO)[number];
+
+/** Set of valid complexity tiers including 'auto' for runtime validation */
+export const COMPLEXITY_TIER_OR_AUTO_SET: ReadonlySet<string> = new Set(
+  COMPLEXITY_TIERS_WITH_AUTO,
+);
+
+/**
+ * Validate whether a string is a valid ComplexityTierOrAuto.
+ * Returns the typed value or undefined if invalid.
+ */
+export function parseComplexityTierOrAuto(
+  value: string | null | undefined,
+): ComplexityTierOrAuto | undefined {
+  if (value && COMPLEXITY_TIER_OR_AUTO_SET.has(value)) {
+    return value as ComplexityTierOrAuto;
+  }
+  return undefined;
+}
+