@xemahq/kernel-contracts 0.1.0

package/src/workflow/lib/sampling-profiles.ts

@@ -0,0 +1,153 @@
+// =============================================================================
+// -- Sampling Profiles — Semantic Task-Type Classification --
+//
+// Defines semantic task-type profiles that classify WHAT an agent does.
+// These profiles are used for:
+//   1. Documentation — communicate intent to human readers
+//   2. LLM Registry model strategy — the registry can map profile → model tier
+//
+// IMPORTANT: For OpenCode SDK mode, temperature/sampling is handled by
+// OpenCode itself via its ProviderTransform (model-specific defaults) and
+// agent config (temperature field in .md frontmatter / opencode.jsonc).
+//
+// OpenCode's built-in model-specific defaults (from ProviderTransform):
+//   - Qwen: temperature=0.55, topP=1
+//   - Gemini: temperature=1.0, topP=0.95, topK=64
+//   - Claude: undefined (uses agent config if set, else provider default)
+//   - Kimi K2 (thinking): temperature=1.0, topP=0.95
+//
+// We only set explicit temperature in agent configs for deterministic agents
+// (temperature=0.0) where we want zero randomness regardless of model.
+// For all other agents, we omit temperature and let OpenCode choose based
+// on the model's ProviderTransform.
+// =============================================================================
+
+/**
+ * Semantic sampling profiles — describe WHAT the agent does, not HOW the model
+ * should behave. Used for documentation and LLM Registry model strategy mapping.
+ *
+ * All pipeline agents run through the OpenCode SDK. OpenCode's ProviderTransform
+ * handles model-specific sampling parameters (temperature, topP, topK) automatically.
+ * We only set temperature=0.0 in agent configs for deterministic agents.
+ */
+export enum SamplingProfile {
+  /**
+   * Classification, routing, merge validation, yes/no decisions.
+   * Maximum reproducibility — single correct answer expected.
+   * Agent config: temperature=0.0 (explicit override).
+   */
+  Deterministic = 'deterministic',
+
+  /**
+   * Code generation, structured JSON output, data transformations, backlog creation.
+   * Near-deterministic with a tiny margin to avoid degenerate repetition loops.
+   * Agent config: no temperature set — OpenCode's model-specific default applies.
+   */
+  Precise = 'precise',
+
+  /**
+   * Analysis, reasoning, planning, requirements elicitation, design decisions.
+   * Enough randomness for nuanced reasoning and varied phrasing.
+   * Agent config: no temperature set — OpenCode's model-specific default applies.
+   */
+  Analytical = 'analytical',
+
+  /**
+   * Design System Builder, document drafting, creative writing, prompt enrichment.
+   * High diversity, reduced repetition for longer outputs.
+   * Agent config: no temperature set — OpenCode's model-specific default applies.
+   */
+  Creative = 'creative',
+}
+
+/**
+ * Sampling parameters that can be sent to an LLM provider.
+ * All fields are optional — providers ignore unsupported params.
+ */
+export interface SamplingParams {
+  /** Controls randomness. Range depends on provider (0–1 for Anthropic, 0–2 for others). */
+  temperature: number;
+
+  /** Nucleus sampling — cumulative probability threshold. Universal. */
+  topP?: number;
+
+  /** Limits token candidates. Not supported by OpenAI. */
+  topK?: number;
+
+  /** Penalizes tokens already in the output. OpenAI, Google, Qwen only. */
+  presencePenalty?: number;
+
+  /** Penalizes based on token frequency. OpenAI, Google, Qwen only. */
+  frequencyPenalty?: number;
+
+  /** Multiplicative repetition penalty. Qwen and open-source only (mutually exclusive with presence/frequency penalties). */
+  repetitionPenalty?: number;
+}
+
+/**
+ * Reference parameters per profile.
+ *
+ * In OpenCode SDK mode (all current agents), these are NOT used at runtime —
+ * OpenCode's ProviderTransform handles model-specific tuning automatically.
+ * These serve as documentation and as a reference for the LLM Registry
+ * when configuring model strategy entries.
+ */
+export const SAMPLING_PROFILE_DEFAULTS: Record<SamplingProfile, SamplingParams> = {
+  [SamplingProfile.Deterministic]: {
+    temperature: 0.0,
+    topP: 0.95,
+  },
+  [SamplingProfile.Precise]: {
+    temperature: 0.15,
+    topP: 0.95,
+  },
+  [SamplingProfile.Analytical]: {
+    temperature: 0.6,
+    topP: 0.95,
+  },
+  [SamplingProfile.Creative]: {
+    temperature: 0.85,
+    topP: 0.95,
+  },
+};
+
+/**
+ * Resolve sampling parameters for a given profile.
+ *
+ * Priority: registryOverride > profile defaults
+ *
+ * @param profile - The semantic sampling profile
+ * @param registryOverride - Optional per-model override from the LLM Registry
+ * @returns Merged sampling parameters
+ */
+export function resolveSamplingParams(
+  profile: SamplingProfile,
+  registryOverride?: Partial<SamplingParams>,
+): SamplingParams {
+  const defaults = SAMPLING_PROFILE_DEFAULTS[profile];
+  if (!registryOverride) return { ...defaults };
+
+  const merged: SamplingParams = {
+    temperature: registryOverride.temperature ?? defaults.temperature,
+  };
+  const topP = registryOverride.topP ?? defaults.topP;
+  if (topP !== undefined) merged.topP = topP;
+  if (registryOverride.topK !== undefined) merged.topK = registryOverride.topK;
+  if (registryOverride.presencePenalty !== undefined) merged.presencePenalty = registryOverride.presencePenalty;
+  if (registryOverride.frequencyPenalty !== undefined) merged.frequencyPenalty = registryOverride.frequencyPenalty;
+  if (registryOverride.repetitionPenalty !== undefined) merged.repetitionPenalty = registryOverride.repetitionPenalty;
+  return merged;
+}
+
+/**
+ * Extract temperature from a profile.
+ *
+ * Only returns a value for Deterministic (0.0) since that's the only
+ * profile where we explicitly override the model default. For all other
+ * profiles, returns undefined to let the runtime adapter's
+ * provider-specific defaults apply.
+ */
+export function profileTemperature(profile: SamplingProfile): number | undefined {
+  if (profile === SamplingProfile.Deterministic) return 0.0;
+  return undefined;
+}

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

@@ -0,0 +1,27 @@
+import { SnapshotStoreKind } from './enums';
+
+/**
+ * A pointer to an immutable blob in a snapshot store. The (store, uri, sha256)
+ * triple is content-addressed: given the same workflow+inputs the compiler
+ * always produces the same sha256, and readers never need to trust the
+ * engine's DB for content integrity.
+ *
+ * Used as Temporal workflow input in place of the CompiledRun blob itself —
+ * Temporal payload limits (2MB) make inline transport unsafe for realistic
+ * compiled runs. A custom PayloadCodec on the Temporal Client transparently
+ * spills large payloads to the snapshot store and reads them back as needed.
+ */
+export interface SnapshotRef {
+  /** Backing store. Enum to keep the set closed. */
+  readonly store: SnapshotStoreKind;
+  /** Opaque URI the store understands. No parsing by consumers. */
+  readonly uri: string;
+  /** Lowercase hex sha256 of the blob. Used for integrity + LRU cache keys. */
+  readonly sha256: string;
+  /** Blob size in bytes. Present for observability; NOT a truncation hint. */
+  readonly sizeBytes: number;
+  /** Media type of the blob (e.g. `application/json`). */
+  readonly contentType: string;
+  /** ISO-8601 UTC timestamp the snapshot was written. */
+  readonly createdAt: string;
+}

package/src/workflow/lib/temporal-namespace.ts

@@ -0,0 +1,78 @@
+/**
+ * Temporal namespace naming + system-vs-org classification.
+ *
+ * Per-organization Temporal namespaces are the tenant-isolation boundary
+ * for workflow execution: each org's workflow state, history, signals,
+ * queries, and visibility live inside `xema-org-<orgId>`. System-level
+ * workflows (cluster-wide tools like retention sweepers) live in the
+ * platform namespace `xema`.
+ *
+ * The mapping is deterministic so every caller (engine dispatch,
+ * worker polling, frontend deep links, schedule reconciler) derives
+ * the same name from the same org id without coordination.
+ */
+
+/**
+ * Platform namespace — system workflows owned by the cluster, not
+ * attributable to any single tenant org. The pre-existing single
+ * namespace this codebase was using; it now hosts only platform code.
+ */
+export const PLATFORM_TEMPORAL_NAMESPACE = 'xema';
+
+const ORG_NAMESPACE_PREFIX = 'xema-org-';
+
+/**
+ * Resolve the Temporal namespace name for a given org id.
+ *
+ * `orgId === null` is the explicit signal for "system / platform run"
+ * (cluster sweepers, etc.). Callers that pass null are declaring the
+ * workflow has no tenant.
+ *
+ * Empty-string orgId is rejected fail-fast — it would silently collapse
+ * to the prefix-only namespace `xema-org-`, which Temporal would accept
+ * but which would give every caller-with-empty-orgId access to one
+ * shared "ghost" namespace.
+ */
+export function temporalNamespaceForOrg(orgId: string | null): string {
+  if (orgId === null) {
+    return PLATFORM_TEMPORAL_NAMESPACE;
+  }
+  if (orgId.length === 0) {
+    throw new Error(
+      'temporalNamespaceForOrg called with empty orgId — pass null for ' +
+      'system runs, a non-empty orgId for tenant runs.',
+    );
+  }
+  return `${ORG_NAMESPACE_PREFIX}${orgId}`;
+}
+
+/**
+ * Inverse of `temporalNamespaceForOrg` — extract the orgId from a
+ * Temporal namespace name. Returns null for the platform namespace.
+ *
+ * Used by reconcile / discovery loops that read the active set of
+ * namespaces from Temporal and need to map back to org context.
+ */
+export function orgIdFromTemporalNamespace(namespace: string): string | null {
+  if (namespace === PLATFORM_TEMPORAL_NAMESPACE) {
+    return null;
+  }
+  if (!namespace.startsWith(ORG_NAMESPACE_PREFIX)) {
+    throw new Error(
+      `Namespace '${namespace}' does not match the platform namespace ` +
+      `'${PLATFORM_TEMPORAL_NAMESPACE}' or the org-namespace prefix ` +
+      `'${ORG_NAMESPACE_PREFIX}<orgId>'. The Temporal cluster contains a ` +
+      `namespace that this code does not own.`,
+    );
+  }
+  return namespace.slice(ORG_NAMESPACE_PREFIX.length);
+}
+
+/**
+ * Whether `namespace` is the platform namespace (system workflows) or
+ * a tenant org namespace. Used by signal/query routing and visibility
+ * checks that must distinguish "cluster-wide tool" from "tenant call".
+ */
+export function isPlatformTemporalNamespace(namespace: string): boolean {
+  return namespace === PLATFORM_TEMPORAL_NAMESPACE;
+}

package/src/workflow/lib/trigger-payload.ts

@@ -0,0 +1,69 @@
+import { WorkflowTriggerKind } from './enums';
+
+/**
+ * Canonical trigger payload — the immutable envelope carried through the
+ * engine → Temporal → worker → activities. Discriminated by `kind` so
+ * every consumer switches exhaustively; unknown `kind` is a compile error.
+ *
+ * Webhook trigger payloads are the canonical envelopes produced by
+ * `integration-adapters-api` (see `docs/API_STANDARDS.md §17`), so the
+ * workflow plane never touches provider-specific shapes.
+ */
+export type TriggerPayload =
+  | WorkflowDispatchTriggerPayload
+  | ScheduleTriggerPayload
+  | WebhookTriggerPayload
+  | WorkflowCallTriggerPayload;
+
+export interface BaseTriggerPayload {
+  readonly kind: WorkflowTriggerKind;
+  /** Opaque request id for correlation across services. ISO `urn:xema:<uuid>`. */
+  readonly correlationId: string;
+  /** Org that owns this run. Required for every trigger. */
+  readonly orgId: string;
+  /** Project that owns this run. Required for every trigger. */
+  readonly projectId: string;
+  /** Actor subject (user id) that initiated the trigger. Null for scheduled + webhook. */
+  readonly actorSubject: string | null;
+  /** Wall-clock UTC at trigger dispatch. Set by the engine, never by clients. */
+  readonly triggeredAt: string;
+}
+
+export interface WorkflowDispatchTriggerPayload extends BaseTriggerPayload {
+  readonly kind: WorkflowTriggerKind.WORKFLOW_DISPATCH;
+  /** Typed inputs as declared by the workflow's `on.workflow_dispatch.inputs` schema. */
+  readonly inputs: Readonly<Record<string, unknown>>;
+}
+
+export interface ScheduleTriggerPayload extends BaseTriggerPayload {
+  readonly kind: WorkflowTriggerKind.SCHEDULE;
+  /** Temporal Schedule id that fired this run. */
+  readonly scheduleId: string;
+  /** Cron spec that matched (for observability). */
+  readonly cronSpec: string;
+  /** Pre-bound inputs from the schedule definition. */
+  readonly inputs: Readonly<Record<string, unknown>>;
+}
+
+export interface WebhookTriggerPayload extends BaseTriggerPayload {
+  readonly kind: WorkflowTriggerKind.WEBHOOK;
+  /** Canonical envelope's entity kind (e.g. `scm.push`). Closed set at the adapter. */
+  readonly event: string;
+  /** Provider + adapter key from the canonical envelope. */
+  readonly provider: string;
+  readonly adapterKey: string;
+  /** Opaque delivery id used for idempotency: `Idempotency-Key = {provider}:{deliveryId}`. */
+  readonly deliveryId: string;
+  /** Canonical envelope payload, typed upstream by the domain service. */
+  readonly payload: Readonly<Record<string, unknown>>;
+}
+
+export interface WorkflowCallTriggerPayload extends BaseTriggerPayload {
+  readonly kind: WorkflowTriggerKind.WORKFLOW_CALL;
+  /** Parent workflow run id that initiated the call. */
+  readonly parentRunId: string;
+  /** Parent workflow slug@version. */
+  readonly parentWorkflowRef: string;
+  /** Inputs forwarded from the parent's `uses:` with block. */
+  readonly inputs: Readonly<Record<string, unknown>>;
+}

package/src/workflow/lib/variable-requirement.ts

@@ -0,0 +1,66 @@
+/**
+ * Variable + secret contract a workflow declares it needs.
+ *
+ * Authored in YAML under `requires.variables`. Each entry is the name of an
+ * org/project Variable (per `biomes/project-registry/api/project-registry-api`) that the workflow
+ * expects to be present at dispatch time. Names follow the same
+ * `[A-Z][A-Z0-9_]*` convention as `CreateVariableDto.key`.
+ *
+ * The engine resolves these at dispatch and refuses to start the run if
+ * any required entry is missing — surfaced as
+ * `WorkflowErrorCode.WORKFLOW_VARIABLES_MISSING` with the list of missing
+ * keys so the UI can deep-link to the variables settings page.
+ */
+export interface WorkflowVariableRequirement {
+  /** Variable name. Matches `[A-Z][A-Z0-9_]*`. */
+  readonly name: string;
+  /**
+   * When true, the variable's stored value is the encrypted-at-rest secret
+   * and is exposed at runtime through the `secrets.*` expression
+   * namespace. When false (default), the value is plaintext and merges
+   * into the `vars.*` namespace alongside the YAML-static `vars:` block.
+   */
+  readonly secret: boolean;
+  /**
+   * When true, the requirement is documented but missing values do NOT
+   * block dispatch — the namespace exposes `undefined` for the key and
+   * expressions referencing it must handle that. Defaults to required.
+   */
+  readonly optional: boolean;
+}
+
+/**
+ * Project variables resolved by the engine at dispatch time and passed
+ * into the root workflow's input. Plain JSON; both halves are string-keyed
+ * maps to keep the Temporal payload deterministic.
+ *
+ * The worker overlays `vars` on top of `CompiledRun.vars` (the YAML-static
+ * block) — project values win for the same key. `secrets` is exposed
+ * through the dedicated `secrets.*` namespace so logs/audit can redact
+ * those values without having to interrogate the schema.
+ */
+export interface ResolvedWorkflowVariables {
+  readonly vars: Readonly<Record<string, string>>;
+  readonly secrets: Readonly<Record<string, string>>;
+}
+
+/**
+ * Static shape of a wallet's contents at compile / resolve time. Carries
+ * only the keys and their secret-ness — values are looked up separately
+ * at dispatch (compile is pure, no decryption / no network).
+ *
+ * Engines pre-fetch this for every wallet listed in `requires.wallets`
+ * (plus any additional wallets passed at dispatch time) and hand the
+ * map to the workflow compiler so it can derive
+ * `CompiledRun.requiredVariables` and validate `${{ vars.X }}` /
+ * `${{ secrets.X }}` references.
+ */
+export interface WalletContents {
+  readonly walletName: string;
+  readonly entries: readonly WalletEntry[];
+}
+
+export interface WalletEntry {
+  readonly key: string;
+  readonly isSecret: boolean;
+}

package/src/workflow/lib/work-item-payloads.ts

@@ -0,0 +1,139 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Work-item payload Zod schemas ──
+//
+// Canonical shapes for the JSON blobs persisted on `WorkItem.payloadJson`.
+// Consumers use these with `toPrismaJson(schema, value)` from
+// `@xemahq/platform-common` to replace `as unknown as
+// Prisma.InputJsonValue` coercions — any drift between writer and reader
+// surfaces as a typed `WorkItemPayloadInvalidError`, not silent data loss.
+//
+// New payload variants are added here (not inlined at the call site) so
+// every work-item writer and reader in the monorepo speaks the same shape.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+// ── Rejection feedback (shared across worker + coordinator re-queue) ─────
+
+/**
+ * Per-reviewer rejection feedback entry — what one reviewer said on one
+ * rejection. Mirrors `VoteFeedbackEntry` in `platform-common/vote-feedback`
+ * but kept at the contract-source boundary so re-queue payloads have a
+ * canonical Zod-checked shape.
+ */
+export const VoteFeedbackEntrySchema = z.object({
+  reviewerGuild: z.string(),
+  vote: z.string(),
+  reasoning: z.string().optional(),
+  findings: z.array(z.unknown()).default([]),
+});
+export type VoteFeedbackEntry = z.infer<typeof VoteFeedbackEntrySchema>;
+
+/**
+ * One entry in the per-work-item `rejectionHistory` array. Each retry
+ * pass appends one entry so the downstream reviewer sees the full audit
+ * trail.
+ */
+export const RejectionHistoryEntrySchema = z.object({
+  attemptNumber: z.number().int().min(1),
+  feedback: z.array(VoteFeedbackEntrySchema),
+  timestamp: z.string(),
+});
+export type RejectionHistoryEntry = z.infer<typeof RejectionHistoryEntrySchema>;
+
+// ── Worker retry payload ──────────────────────────────────────────────────
+
+/**
+ * Payload shape written by `reQueueForRetryWithFeedback` when a worker
+ * work-item is re-queued after a gate rejection. Callers provide the
+ * full payload (including any task-specific fields) — this schema
+ * enforces the retry-specific fields only and lets additional keys
+ * pass through via `.passthrough()` during the incremental rollout.
+ */
+export const WorkerRetryPayloadSchema = z
+  .object({
+    rejectionFeedback: z.array(VoteFeedbackEntrySchema),
+    conciseRejectionFeedback: z.string(),
+    rejectionHistory: z.array(RejectionHistoryEntrySchema).default([]),
+    priorResults: z.array(z.record(z.string(), z.unknown())).default([]),
+  })
+  .passthrough();
+export type WorkerRetryPayload = z.infer<typeof WorkerRetryPayloadSchema>;
+
+// ── Coordinator retry payload ─────────────────────────────────────────────
+
+/**
+ * Payload shape for `reQueueCoordinatorWithFeedback`. Mirrors the worker
+ * shape so coordinator retries accumulate `priorResults` identically —
+ * the prior gap where only `publishedPageRefs` was preserved is the
+ * plan's finding #45 and is fixed by making the coordinator path adopt
+ * this schema.
+ */
+export const CoordinatorRetryPayloadSchema = z
+  .object({
+    coordinatorRejectionFeedback: z.unknown(),
+    priorResults: z.array(z.record(z.string(), z.unknown())).default([]),
+    publishedPageRefs: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+export type CoordinatorRetryPayload = z.infer<typeof CoordinatorRetryPayloadSchema>;
+
+// ── Review-attempt trace entry (F3a) ──────────────────────────────────────
+
+/**
+ * One step recorded by the gate-review correction loop. Persisted on
+ * `GateVote.reasonsJson.attempts` so the operator / auditor sees what
+ * the reviewer tried on each attempt, without scraping container logs.
+ */
+export const GateReviewAttemptEntrySchema = z.object({
+  attempt: z.number().int().min(0),
+  step: z.string(),
+  outcome: z.string(),
+  // detail is not always populated — success entries typically omit it.
+  // Keeping it optional matches the handler's actual emission shape
+  // (`GateReviewAttemptEntry.detail?: string` in opencode-client types).
+  detail: z.string().optional(),
+  at: z.string(),
+});
+export type GateReviewAttemptEntry = z.infer<typeof GateReviewAttemptEntrySchema>;
+
+/**
+ * Structured trace attached to every completed (or failed) gate review.
+ * The raw reviewer-emitted content is stored alongside this trace so the
+ * `MANUAL_REVIEW_MALFORMED_OUTPUT` escalation can surface what the LLM
+ * actually said when parsing exhausted.
+ */
+export const GateReviewAttemptTraceSchema = z.object({
+  sessionId: z.string().nullable(),
+  reviewPath: z.string(),
+  durationMs: z.number().int().min(0),
+  entries: z.array(GateReviewAttemptEntrySchema),
+  exhausted: z.boolean(),
+});
+export type GateReviewAttemptTrace = z.infer<typeof GateReviewAttemptTraceSchema>;
+
+/**
+ * Per-reviewer escalation entry persisted on `GateRequest.malformedReviews`
+ * when the correction loop can't produce a parseable review. The operator's
+ * `ManualReviewMalformedPanel` reads this array to render raw content +
+ * attempts trace and collect a structured vote.
+ */
+export const MalformedEscalationKindSchema = z.enum([
+  'malformed',
+  'infrastructure',
+  'structurally_incomplete',
+]);
+export type MalformedEscalationKind = z.infer<typeof MalformedEscalationKindSchema>;
+
+export const MalformedEscalationEntrySchema = z.object({
+  reviewerGuild: z.string().min(1),
+  reviewerAgent: z.string().min(1),
+  kind: MalformedEscalationKindSchema,
+  message: z.string(),
+  rawContent: z.string().nullable(),
+  attempts: z.array(GateReviewAttemptEntrySchema),
+  occurredAt: z.string().min(1),
+});
+export type MalformedEscalationEntry = z.infer<typeof MalformedEscalationEntrySchema>;
+
+export const MalformedEscalationLedgerSchema = z.array(MalformedEscalationEntrySchema);

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

@@ -0,0 +1,89 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workflow Stage — Generic Ordered-Stage Contract ──
+//
+// The kernel knows ONLY that a workflow run can be partitioned into an
+// ordered sequence of named stages. It carries ZERO domain knowledge: the
+// concrete stage list (software-delivery's `clarification → requirements →
+// … → deployment`, a content pipeline's stages, etc.) is owned by the
+// sub-app biome that defines the workflow, never by this kernel package.
+//
+// A stage is identified by a free-form `stageKey` string. The artifact
+// natural key already `_`-encodes this value (`{kind}:{workflowRunId}:
+// {groupKey|_}:{scope|_}:{slug}`), and the workflow engine sequences jobs
+// via explicit `needs:` dependency edges — neither needs a closed enum.
+//
+// Biomes that DO define an ordered stage list (e.g. for a phase rail or a
+// per-stage gate-reviewer map) ship it as biome content and load it at
+// runtime; see `biomes/platform/software-dev/workflow-config/phase-config.json`.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * How the execution engine treats a stage:
+ * - `lifecycle`: a meta-stage that shapes the run but does not produce a
+ *   gated deliverable (e.g. a clarification/intake stage).
+ * - `delivery`: produces artifacts and flows through gate progression.
+ *
+ * This is the one generic, closed property every ordered-stage model
+ * shares. The stage *keys* themselves stay free-form and biome-owned.
+ */
+export enum WorkflowStageCategory {
+  Lifecycle = 'lifecycle',
+  Delivery = 'delivery',
+}
+
+/**
+ * A single ordered workflow stage. `stageKey` is the value that flows onto
+ * a job's `groupKey` and into the artifact natural key — a free-form
+ * string the kernel never validates against a closed set.
+ */
+export interface WorkflowStage {
+  /** Free-form stage identifier (e.g. `requirements`, `engineering`). */
+  readonly stageKey: string;
+  /** Whether the engine treats this stage as lifecycle or delivery. */
+  readonly category: WorkflowStageCategory;
+}
+
+/**
+ * An ordered list of workflow stages, as defined by a workflow/sub-app.
+ * The kernel offers this shape so a biome-supplied stage list has a
+ * typed home; the kernel never instantiates one.
+ */
+export type WorkflowStageSequence = readonly WorkflowStage[];
+
+/**
+ * Compute the next stage after `currentStageKey` within an ordered
+ * sequence, optionally restricted to an in-scope subset of delivery
+ * stages. Lifecycle stages are always in scope; delivery stages must
+ * appear in `deliveryScope` when one is supplied.
+ *
+ * Returns `undefined` when `currentStageKey` is terminal within the
+ * (optionally scoped) sequence.
+ *
+ * @throws Error if `currentStageKey` is not present in `sequence`.
+ */
+export function nextStageInSequence(
+  sequence: WorkflowStageSequence,
+  currentStageKey: string,
+  deliveryScope?: readonly string[],
+): string | undefined {
+  const currentIdx = sequence.findIndex((s) => s.stageKey === currentStageKey);
+  if (currentIdx < 0) {
+    throw new Error(
+      `Stage "${currentStageKey}" is not present in the supplied workflow stage sequence`,
+    );
+  }
+  for (let i = currentIdx + 1; i < sequence.length; i++) {
+    const candidate = sequence[i];
+    if (candidate === undefined) {
+      continue;
+    }
+    if (
+      !deliveryScope ||
+      candidate.category === WorkflowStageCategory.Lifecycle ||
+      deliveryScope.includes(candidate.stageKey)
+    ) {
+      return candidate.stageKey;
+    }
+  }
+  return undefined;
+}