@xemahq/kernel-contracts 0.1.0

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

@@ -0,0 +1,376 @@
+import type { CompiledWorkspaceManifest } from './compiled-workspace-manifest';
+
+import type { ActionRef } from './action-ref';
+import type { Briefcase } from './briefcase';
+import type { ConcurrencyGroup } from './concurrency-group';
+import { MatrixStrategyKind, type PermissionResource, type PermissionScope } from './enums';
+import type { MountPlan } from './mount-plan';
+import type { SnapshotRef } from './snapshot-ref';
+import type { TriggerPayload } from './trigger-payload';
+import type { WorkflowVariableRequirement } from './variable-requirement';
+
+/**
+ * Pre-resolved manifest source for `xema/agent`-shaped jobs. The
+ * workflow-dsl compiler emits exactly one variant per agent step:
+ *
+ *   • `ref` — long-form `with.compositionRef: <slug>` (or
+ *     `<slug>@<version>`) that the activity resolves at boot via
+ *     llm-registry-api's Agent Composition `GET /compositions/resolve/
+ *     :ref`, reconstructing the compiled workspace manifest from the
+ *     resolved composition's `workspace.mountLayout` block.
+ *   • `inline` — short-form `with.mounts` whose agent metadata
+ *     (`agentSlug`, `groupKey`, `deliverableSpecRef`, every entry in
+ *     `mounts`) is fully literal at compile time. The compiler runs
+ *     `compileManifest()` once and embeds the result so the worker
+ *     skips both the DB round-trip and the runtime synthesis step.
+ *   • `inline-deferred` — short-form whose agent metadata still
+ *     contains `${{ … }}` expressions; the worker synthesizes the
+ *     inline manifest after expression evaluation.
+ *
+ * `null` for non-agent actions (compileManifestSource short-circuits
+ * when the action manifest's `inputs.properties` lacks both
+ * `compositionRef` and `mounts`).
+ */
+export type CompiledManifestSource =
+  | { readonly kind: 'ref'; readonly ref: string }
+  | { readonly kind: 'inline'; readonly compiled: CompiledWorkspaceManifest }
+  | { readonly kind: 'inline-deferred' };
+
+/**
+ * A CompiledRun is the IMMUTABLE semantic expansion of a workflow definition
+ * for one execution. Produced by `@xemahq/workflow-dsl` at run
+ * start, written to the snapshot store, referenced by {@link SnapshotRef}
+ * as the input to `rootRunWorkflow`.
+ *
+ * Rules that must hold for every CompiledRun:
+ *   1. The same (workflowDefinitionVersionSha256, triggerPayload) always
+ *      produces the same CompiledRun modulo `snapshotCreatedAt`. Determinism
+ *      is a hard invariant — the runtime relies on it for replay semantics.
+ *   2. Unknown fields are forbidden (additionalProperties=false at schema
+ *      level). A CompiledRun with unrecognized fields must fail to load.
+ *   3. Every referenced action/reusable-workflow version is pinned at
+ *      compile time. The worker does not re-resolve.
+ *   4. Dynamic matrix jobs carry enough metadata for runtime expansion but
+ *      do NOT emit child entries — the root workflow spawns those.
+ */
+export interface CompiledRun {
+  /** Schema version of this CompiledRun shape. Bumped on breaking changes. */
+  readonly compiledRunVersion: 1;
+
+  /** Workflow slug@version the compilation started from. */
+  readonly workflowRef: WorkflowRef;
+
+  /** Immutable copy of the trigger that produced this run. */
+  readonly trigger: TriggerPayload;
+
+  /** Validated inputs bound from `on.<trigger>.inputs` schemas + defaults applied. */
+  readonly inputs: Readonly<Record<string, unknown>>;
+
+  /** Top-level `vars` block, fully resolved (no expressions left). */
+  readonly vars: Readonly<Record<string, unknown>>;
+
+  /**
+   * Run-scoped ephemeral context object synthesized from the dispatch
+   * request (uploads, references, vars, optional MCP tool additions).
+   * Propagated to every activity / child-workflow via
+   * `ActionBaseInput.briefcase`. `undefined` only for legacy runs
+   * compiled before this field existed; new dispatches synthesize at
+   * least an `emptyBriefcase()` so consumers can safely assume the
+   * field's presence after this PR.
+   *
+   * Distinct from workspace manifests: a manifest declares the agent's
+   * static workspace shape; the Briefcase carries the per-run contents
+   * that fill those slots.
+   */
+  readonly briefcase?: Briefcase;
+
+  /**
+   * Wallet names the workflow declared via `requires.wallets`. Preserved
+   * for audit / display ("this run used the `aws-production` wallet").
+   * Note: dispatch-time additional wallets are NOT included here — they
+   * live on the trigger payload alongside dispatch inputs.
+   */
+  readonly requiredWallets: readonly string[];
+
+  /**
+   * Flat list of every variable key the workflow references — derived
+   * from the union of the declared wallets' contents at compile time.
+   * The engine fails fast at dispatch if any non-optional entry is
+   * unresolvable; the worker treats this as a defensive contract for
+   * the values it receives in the input payload.
+   */
+  readonly requiredVariables: readonly WorkflowVariableRequirement[];
+
+  /** Declared permissions, resolved to a concrete (resource, scope) map. */
+  readonly permissions: Readonly<Record<PermissionResource, PermissionScope>>;
+
+  /** Resolved concurrency group, or null if the workflow declares none. */
+  readonly concurrency: ConcurrencyGroup | null;
+
+  /** Default retry + timeout (merged with per-job overrides at runtime). */
+  readonly defaults: CompiledDefaults;
+
+  /**
+   * All jobs in DAG order (topological sort). Each job carries its resolved
+   * `needs` edges so the worker can build the dependency graph without
+   * re-parsing. Jobs form a DAG — cycles are rejected at compile time.
+   */
+  readonly jobs: readonly CompiledJob[];
+
+  /** When this CompiledRun was produced. ISO-8601 UTC. */
+  readonly snapshotCreatedAt: string;
+
+  /** sha256 of the canonical-JSON serialization of this CompiledRun, excluding this field. */
+  readonly snapshotSha256: string;
+
+  /** Version hash of the source workflow definition — authoritative at audit time. */
+  readonly workflowDefinitionVersionSha256: string;
+
+  /**
+   * `on.workflow_call.outputs` mapping for reusable workflows: outputName →
+   * already-stripped expression body (no `${{ }}` wrapper). Evaluated by
+   * the runtime against the inner workflow's final `needs.*` once the
+   * child `rootRunWorkflow` returns, projecting inner job outputs into
+   * the externally-visible call outputs that the parent's job-level
+   * `outputs:` block consumes via `job.outputs.*`.
+   *
+   * Empty object for non-reusable workflows. Reusable workflows whose
+   * authors omit `on.workflow_call.outputs` also produce an empty map —
+   * the parent will see `job.outputs = {}` and any `outputs:` projection
+   * referencing missing fields will fail fast at evaluation.
+   */
+  readonly workflowCallOutputs: Readonly<Record<string, string>>;
+
+  /**
+   * Workflow-level `outputs:` block — top-level named outputs declared
+   * on the workflow document. Each entry references a `(fromJob,
+   * fromOutput)` pair and declares the kind of value it surfaces
+   * (deliverable artifact, structured JSON, plain text).
+   *
+   * Consumers:
+   *   - Biome `mcpWorkflowTools[].outputProjection.slug` cross-
+   *     reference (the slug must match a key here at biome boot).
+   *   - `RunResponseDto.deliverables` projection — built by walking
+   *     this map against the producing JobRun outputs.
+   *   - Future `workflow_call` composition surfaces.
+   *
+   * Empty for workflows without an `outputs:` declaration.
+   */
+  readonly workflowOutputs: Readonly<Record<string, WorkflowOutputDescriptor>>;
+}
+
+/** Compiled, validated workflow-level output descriptor. */
+export type WorkflowOutputDescriptor =
+  | {
+      readonly kind: 'deliverable';
+      readonly slug: string;
+      readonly fromJob: string;
+      readonly fromOutput: string;
+      readonly description?: string;
+      readonly deliverableSpecRef: string;
+    }
+  | {
+      readonly kind: 'structured';
+      readonly slug: string;
+      readonly fromJob: string;
+      readonly fromOutput: string;
+      readonly description?: string;
+      readonly schemaRef?: string;
+    }
+  | {
+      readonly kind: 'text';
+      readonly slug: string;
+      readonly fromJob: string;
+      readonly fromOutput: string;
+      readonly description?: string;
+    };
+
+export interface WorkflowRef {
+  /** Workflow slug (unique within an org). */
+  readonly slug: string;
+  /** Semantic version, resolved from the `@ver` reference. */
+  readonly version: string;
+  /** True if this is a system-seeded workflow (read-only), false if UI-authored. */
+  readonly isSystem: boolean;
+}
+
+export interface CompiledDefaults {
+  /** Retry policy inherited by jobs unless overridden. */
+  readonly retry: CompiledRetryPolicy;
+  /** Default job-level timeout in milliseconds. */
+  readonly timeoutMs: number;
+}
+
+export interface CompiledRetryPolicy {
+  readonly maxAttempts: number;
+  readonly initialIntervalMs: number;
+  readonly backoffCoefficient: number;
+  readonly maximumIntervalMs: number;
+  /** Non-retryable error type codes (consumed by the Temporal activity retry policy). */
+  readonly nonRetryableErrorTypes: readonly string[];
+}
+
+export interface CompiledJob {
+  /** Stable logical key (as authored in YAML). Unique per CompiledRun. */
+  readonly jobKey: string;
+  /** Optional human-readable title; falls back to jobKey in UIs. */
+  readonly title: string | null;
+  /** Upstream jobKeys this job depends on (must form a DAG). */
+  readonly needs: readonly string[];
+  /**
+   * Upstream matrix jobKeys whose `outputs` should be flattened into a plain
+   * array for THIS job's expression context. For every key in this list,
+   * `needs.<key>.outputs` is reshaped from `{ kind: 'matrix', outputs: [...] }`
+   * to the raw `[...]` array before `with:`, `if:`, and `outputs:` are
+   * evaluated. Enables the synthesizer / coordinator pattern without forcing
+   * authors to know the matrix envelope shape. Empty array when not declared.
+   */
+  readonly matrixGather: readonly string[];
+  /**
+   * Gating expression EVALUATED at runtime with actual `needs` outputs bound.
+   * Null = always run. Expression is already validated to belong to the
+   * closed subset by the compiler; evaluator trusts it.
+   */
+  readonly ifExpression: string | null;
+  /** Strategy for this job: single, compile-time static matrix, or runtime-dynamic. */
+  readonly strategy: CompiledStrategy;
+  /** Resolved action / reusable workflow reference. Never re-resolved at runtime. */
+  readonly action: ActionRef;
+  /** Pre-compiled mount plan (NEW: expansion already done). */
+  readonly mountPlan: MountPlan;
+  /**
+   * Pre-resolved workspace-manifest source for agent-shaped jobs.
+   * `null` for non-agent actions and reusable-workflow jobs.
+   */
+  readonly manifestSource: CompiledManifestSource | null;
+  /**
+   * Raw `with:` arguments passed to the action/reusable workflow. Values
+   * may still contain expression references (`${{ matrix.x }}` etc.) that
+   * the worker evaluates per-matrix-entry.
+   */
+  readonly with: Readonly<Record<string, unknown>>;
+  /**
+   * Declarative outputs: outputName → already-stripped expression body
+   * (no `${{ }}` wrapper). Evaluated at job completion against an
+   * expression context whose `job.outputs.*` is bound to the raw
+   * dispatch result (activity return value, child-workflow result, or —
+   * for reusable workflows — the projection produced by
+   * `CompiledRun.workflowCallOutputs`). The resulting projected map is
+   * what downstream jobs observe via `needs.<jobKey>.outputs.*`.
+   *
+   * Empty object means "no projection" — downstream jobs see the raw
+   * dispatch result directly.
+   */
+  readonly outputs: Readonly<Record<string, string>>;
+  /** Retry policy — job-level override of defaults.retry. */
+  readonly retry: CompiledRetryPolicy;
+  /** Job-level timeout in milliseconds — overrides defaults.timeoutMs. */
+  readonly timeoutMs: number;
+  /** Permissions this job needs. Must be a subset of the workflow's permissions. */
+  readonly permissions: Readonly<Record<PermissionResource, PermissionScope>>;
+  /**
+   * When `action.isReusableWorkflow === true`, the nested CompiledRun for
+   * the reusable workflow body — pre-compiled by the engine at parent
+   * compile time. The worker dispatches the reusable via
+   * `executeChild('rootRunWorkflow', { args: [{ runId, compiledRun: this }] })`
+   * and merges its `jobOutputs` into the parent's `needs.<jobKey>.outputs`.
+   * Null for non-reusable jobs. Cycles are rejected at compile time.
+   */
+  readonly reusableCompiledRun: CompiledRun | null;
+  /**
+   * Compile-time pins for every `needs.<X>.outputs.<...>.<payload-field>`
+   * reach-in this job authors. Each pin records the upstream job whose
+   * artifact payload will be reached into AND the deliverable-spec
+   * version the compiler resolved at compile time. The runtime
+   * pre-fetcher asserts the fetched artifact's `schemaVersion` matches
+   * `specVersion` — fail-fast on spec drift between the producer's emit
+   * and the consumer's compile (per plan "Risks and mitigations").
+   *
+   * Empty array when the job has no typed reach-ins (the common case
+   * for non-agent jobs or jobs whose upstream specs are
+   * expression-shaped). Indexing/keying produces one pin per (upstream
+   * job, output access form) — multiple `<field>` accesses on the same
+   * upstream collapse to one pin since the spec binding is per-job.
+   */
+  readonly payloadReachIns: readonly PayloadReachInPin[];
+}
+
+/**
+ * One compile-time pin recording the spec a payload reach-in expects to
+ * fetch against. The runtime pre-fetcher reads these to validate that
+ * the artifact the producer actually emitted carries the same
+ * `schemaVersion` the compiler bound against — fail-fast on drift.
+ *
+ * The compiler emits at most one pin per `(consumerJob, upstreamJob)`
+ * pair because the deliverable-spec binding on an upstream activity is
+ * job-level today (`with.deliverableSpecRef`). When per-output spec
+ * bindings land (plan §B), this shape extends with `outputName` and the
+ * cardinality changes to `(consumerJob, upstreamJob, outputName)`.
+ */
+export interface PayloadReachInPin {
+  /** Dotted authoring path the reach-in appeared at (for diagnostics). */
+  readonly fieldPath: string;
+  /** Upstream job whose artifact the runtime will fetch. */
+  readonly upstreamJobKey: string;
+  /**
+   * Output name on the upstream activity this pin governs. When the
+   * upstream activity manifest declared per-output `outputBindings`,
+   * the pin is keyed by `(upstreamJobKey, outputName)`; otherwise the
+   * pin covers every reach-in on that upstream (job-level spec from
+   * `with.deliverableSpecRef`) and `outputName` is `null`.
+   */
+  readonly outputName: string | null;
+  /** Spec reference as authored (e.g. `agent-summary@1.0.0`). */
+  readonly specRef: string;
+  /** Spec version segment parsed off `specRef` (e.g. `1.0.0`). */
+  readonly specVersion: string;
+}
+
+export type CompiledStrategy =
+  | CompiledSingleStrategy
+  | CompiledStaticMatrixStrategy
+  | CompiledDynamicMatrixStrategy;
+
+export interface CompiledSingleStrategy {
+  readonly kind: MatrixStrategyKind.SINGLE;
+}
+
+/**
+ * Matrix known at compile time — already fully expanded into a list of
+ * concrete bindings. Each element is one job run.
+ */
+export interface CompiledStaticMatrixStrategy {
+  readonly kind: MatrixStrategyKind.STATIC;
+  readonly entries: readonly Readonly<Record<string, unknown>>[];
+  readonly maxParallel: number;
+}
+
+/**
+ * Matrix expanded at runtime. `fromExpression` is the expression the root
+ * workflow evaluates once upstream outputs are available; it must resolve
+ * to an array of bindings. `maxParallel` caps concurrent child spawns.
+ * The compile-time cardinality cap (plan §5) is enforced at runtime by
+ * rejecting arrays > maxEntries.
+ */
+export interface CompiledDynamicMatrixStrategy {
+  readonly kind: MatrixStrategyKind.DYNAMIC;
+  readonly fromExpression: string;
+  readonly maxParallel: number;
+  readonly maxEntries: number;
+  /** Name of the variable each entry binds to inside the job (e.g. `matrix.changeUnit`). */
+  readonly bindingName: string;
+  /**
+   * Optional dotted path on each bound entry whose value becomes the
+   * key in `needs.<thisJob>.outputs.byKey`. Lets per-CU downstream
+   * matrices reference the matching upstream iteration via
+   * `needs.X.outputs.byKey[matrix.<binding>.<keyBy>].field`. `null` =
+   * no keyed map exposed (positional + matrixGather still work).
+   */
+  readonly keyBy: string | null;
+}
+
+/**
+ * Re-export of {@link SnapshotRef} for callers that only import compiled-run.
+ * Keeps the dependency direction one-way.
+ */
+export type { SnapshotRef };

package/src/workflow/lib/compiled-working-file.ts

@@ -0,0 +1,35 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Compiled working-file declaration ──
+//
+// The post-interpolation form of a `WorkingFileBinding` (declared in
+// `@xemahq/agent-workspace-contracts`). The manifest DSL compile step
+// resolves any `${input.x}` tokens in `path` / `sourceRef` values
+// against the caller's bind inputs before producing this shape, so
+// downstream consumers (session-bundle composer, workspace-proxy
+// working-file engine) receive concrete strings.
+//
+// Restated here (rather than re-exported from agent-workspace-contracts)
+// to keep workflow-contracts dependency-free from the AWP package — the
+// shape is identical by design.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type CompiledWorkingFileFormat =
+  | 'markdown'
+  | 'html'
+  | 'json'
+  | 'yaml'
+  | 'text';
+
+export type CompiledWorkingFileSyncDirection =
+  | 'down-only'
+  | 'up-only'
+  | 'bidirectional';
+
+export interface CompiledWorkingFile {
+  readonly slug: string;
+  readonly path: string;
+  readonly format: CompiledWorkingFileFormat;
+  readonly syncDirection: CompiledWorkingFileSyncDirection;
+  readonly sourceKind: string;
+  readonly sourceRef: Readonly<Record<string, string>>;
+}

package/src/workflow/lib/compiled-workspace-manifest.ts

@@ -0,0 +1,185 @@
+/**
+ * Compiled output types for WorkspaceManifest — produced by
+ * `@xemahq/workspace-manifest-dsl`'s `compileManifest()` and embedded
+ * in {@link CompiledRun} for inline-agent steps.
+ *
+ * Defined here (rather than in workspace-manifest-dsl) to avoid a
+ * circular dependency: workspace-manifest-dsl → agent-workspace-contracts
+ * → workflow-contracts → workspace-manifest-dsl.
+ */
+
+import type { ToolSelectionEntry } from '../../mcp-tool';
+
+import type { AgentRunRole } from './agent-role';
+import type { CompiledWorkingFile } from './compiled-working-file';
+
+// Re-export so callers walking `CompiledWorkspaceManifest.workingFiles`
+// pull the entry type from the same module they got the manifest from.
+export type {
+  CompiledWorkingFile,
+  CompiledWorkingFileFormat,
+  CompiledWorkingFileSyncDirection,
+} from './compiled-working-file';
+import type { ModelRef, SubAgentBinding } from './model-ref';
+import type {
+  CredentialKind,
+  ManifestSurface,
+  OutputSurfaceKind,
+  ToolsetKey,
+} from './workspace-manifest-enums';
+
+export interface CompiledWorkspaceManifest {
+  readonly slug: string;
+  readonly version: string;
+  readonly surfaceCompat: readonly ManifestSurface[];
+  readonly display: CompiledManifestDisplay;
+  readonly agent: CompiledManifestAgent;
+  readonly mounts: Record<string, CompiledMountDeclaration>;
+  readonly skills: readonly CompiledManifestSkillRef[];
+  /**
+   * Default MCP tool selection (resolved at boot via mcp-gateway-api
+   * `POST /mcp-resolve`). Sessions may override per-instance.
+   */
+  readonly toolSelection: readonly ToolSelectionEntry[];
+  readonly credentials: readonly CompiledManifestCredential[];
+  readonly permissions: CompiledManifestPermissions;
+  readonly persistence: CompiledManifestPersistence;
+  readonly outputSurface: CompiledManifestOutputSurface;
+  readonly seedFiles: readonly CompiledSeedFile[];
+  readonly env: readonly { readonly name: string; readonly value: string }[];
+  /**
+   * Working files the platform materialises before the agent's first
+   * turn (see `WorkingFileBinding` in `@xemahq/agent-workspace-contracts`).
+   * Compiled with `${input.x}` tokens already interpolated against the
+   * caller's bind inputs. Empty when the source manifest declared no
+   * working files.
+   */
+  readonly workingFiles: readonly CompiledWorkingFile[];
+  /**
+   * Distinct template names the manifest references via `seedFiles[].template`.
+   * Callers resolve these against the templates table (with the appropriate
+   * scope ladder) before mounting.
+   */
+  readonly requiredTemplateNames: readonly string[];
+}
+
+export interface CompiledManifestAgent {
+  readonly slug: string;
+  readonly groupKey: string;
+  /**
+   * Canonical {@link AgentRunRole}. Validated by the DSL's
+   * `ManifestAgentBlockSchema` at compile time, so the runtime can
+   * trust the value without re-checking.
+   */
+  readonly role: AgentRunRole;
+  readonly deliverableSpecRef?: string;
+  readonly defaultModel?: ModelRef;
+  readonly subAgents: readonly SubAgentBinding[];
+}
+
+export interface CompiledManifestDisplay {
+  readonly title?: string;
+  readonly blurb?: string;
+  readonly icon?: string;
+  readonly category?: string;
+  readonly badges: readonly string[];
+  readonly sortOrder?: number;
+  readonly hidden: boolean;
+  readonly ctaText?: string;
+  readonly curated: boolean;
+}
+
+export interface CompiledManifestSkillRef {
+  readonly slug: string;
+  readonly version?: string;
+}
+
+export interface CompiledManifestCredential {
+  readonly name: string;
+  readonly kind: CredentialKind;
+  readonly sourceRef: string;
+  readonly required: boolean;
+}
+
+export interface CompiledManifestPermissions {
+  readonly tools: {
+    readonly allow: readonly ToolsetKey[];
+    readonly deny: readonly ToolsetKey[];
+  };
+}
+
+/**
+ * Compiled per-slot persistence policy override. Mirrors the manifest
+ * source shape — every field is already validated against closed-set
+ * enums at compile time, so consumers (agent-session-api session
+ * lifecycle, in particular) can read these without re-validating.
+ */
+export interface CompiledSlotPersistenceOverride {
+  readonly kind: 'git-push';
+  readonly branchPrefix: string;
+  readonly branchSuffix?: import('./workspace-manifest-enums').ManifestGitPushBranchSuffix;
+  readonly concurrencyMode?: import('./workspace-manifest-enums').ManifestGitPushConcurrencyMode;
+}
+
+export interface CompiledManifestPersistence {
+  readonly paths: readonly string[];
+  /**
+   * Per-slot persistence policy overrides. Keyed by AWP slot key. Empty
+   * when the manifest doesn't override any slot. Consumed by the session
+   * lifecycle to override the kernel default policy at runtime.
+   */
+  readonly overrides: Readonly<Record<string, CompiledSlotPersistenceOverride>>;
+}
+
+export type CompiledManifestOutputSurfaceMode = 'single' | 'multi';
+
+export interface CompiledManifestOutputSurface {
+  readonly kind: OutputSurfaceKind;
+  readonly port?: number;
+  readonly healthPath?: string;
+  readonly autoOpen: boolean;
+  /**
+   * `'single'` (default) — one preview process pinned to `port`.
+   * `'multi'` — workspace-proxy preview supervisor discovers app
+   * targets and emits one gateway route per detected app; the
+   * top-level `port` is unused.
+   */
+  readonly mode: CompiledManifestOutputSurfaceMode;
+  /**
+   * Workspace-relative directory served as a static site. Present
+   * and meaningful only when `kind === 'static'`. The DSL schema
+   * enforces the cross-field rule (required when `kind === 'static'`).
+   */
+  readonly root?: string;
+  /**
+   * Default document served for directory requests in a `static`
+   * surface. Defaults to `index.html` at compile time; absent for
+   * other kinds.
+   */
+  readonly defaultDocument?: string;
+}
+
+export interface CompiledMountDeclaration {
+  readonly enabled: boolean;
+  readonly mode?: 'read-only' | 'read-write';
+  readonly config: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A compiled seed file. The `source` discriminator separates inline
+ * literal content (already base64-encoded by the compiler) from named
+ * templates (resolved + rendered downstream).
+ */
+export interface CompiledSeedFile {
+  readonly slot: string;
+  readonly relPath: string;
+  readonly source: CompiledSeedFileSource;
+}
+
+export type CompiledSeedFileSource =
+  | { readonly kind: 'inline'; readonly bytesBase64: string }
+  | {
+      readonly kind: 'template';
+      readonly name: string;
+      readonly vars: Readonly<Record<string, unknown>>;
+    };

package/src/workflow/lib/concurrency-group.ts

@@ -0,0 +1,17 @@
+import { ConcurrencyMode } from './enums';
+
+/**
+ * Concurrency declaration resolved at compile time. The engine acquires a
+ * Postgres-backed lease on `leaseKey` before starting the run; the
+ * `mode` drives collision behavior (queue vs cancel vs skip vs allow).
+ *
+ * `leaseKey` is the deterministic expansion of the authored `group`
+ * expression with trigger/inputs bound in. The engine NEVER re-evaluates
+ * the expression at runtime — collisions must be detectable via string
+ * equality on leaseKey alone. This is load-bearing for horizontal scaling:
+ * two engine replicas can both inspect the same lease row.
+ */
+export interface ConcurrencyGroup {
+  readonly leaseKey: string;
+  readonly mode: ConcurrencyMode;
+}