@xemahq/kernel-contracts 0.1.0

package/src/workflow/lib/deliverable-result.ts

@@ -0,0 +1,238 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Deliverable result envelope ──
+//
+// Canonical shape an agent activity returns when it produces a deliverable.
+// One envelope, one access path (`needs.<job>.outputs.deliverable.content.…`),
+// one source of truth for the FE, the workflow VM, and downstream jobs.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Workspace slot the deliverable lands in. Mirrors
+ * `@xemahq/platform-common`'s `DeliverableTargetSlot` shape but
+ * defined locally so workflow-contracts (kernel) keeps zero runtime deps.
+ * Both definitions describe the same wire shape — the platform-common
+ * version is the authoritative Zod schema that validates spec rows; this
+ * one is a structural mirror for typed consumers in the runtime worker
+ * and engine that already pull from workflow-contracts.
+ */
+export type DeliverableTargetSlot =
+  | { readonly kind: 'deliverables' }
+  | { readonly kind: 'repos'; readonly repoSlug: string };
+
+/**
+ * Canonical envelope returned by `xema/agent`-shaped activities.
+ *
+ * Wrapped under `agentResult.deliverable` in `AgentActivityOutput.agentResult`
+ * so downstream YAML expressions read
+ * `${{ needs.<job>.outputs.deliverable.content.<...> }}` (or, for matrix
+ * jobs, `…outputs.byKey[<key>].deliverable.content.<...>`).
+ */
+export interface AgentDeliverableResult {
+  /** Resolved deliverable spec ref this envelope honors. Always literal post-expression. */
+  readonly specRef: string;
+  /** Spec kind value (closed set lives in deliverable-specs-api enum). */
+  readonly kind: string;
+  /** Where on disk the deliverable landed (deliverables slot vs a repo workspace). */
+  readonly targetSlot: DeliverableTargetSlot;
+  /** Kind-discriminated content body. */
+  readonly content: DeliverableContent;
+  /**
+   * True iff the activity dispatched the structured self-correction
+   * follow-up message into the same agent session before returning. The
+   * frontend uses this to badge the activity span as "self-corrected".
+   */
+  readonly selfCorrectionAttempted: boolean;
+}
+
+/**
+ * Discriminated union of deliverable content payloads, keyed by a
+ * presentation-level discriminator. Adding a new shape is one new
+ * arm here + one new branch in the harvester + the FE switch — no
+ * other consumer has to change.
+ */
+export type DeliverableContent =
+  | DocumentDeliverableContent
+  | JsonDeliverableContent
+  | EndpointDeliverableContent
+  | ResponseDeliverableContent
+  | CustomDeliverableContent;
+
+export const DeliverableContentDiscriminator = {
+  Document: 'document',
+  Json: 'json',
+  Endpoint: 'endpoint',
+  Response: 'response',
+  Custom: 'custom',
+} as const;
+
+export type DeliverableContentDiscriminatorValue =
+  (typeof DeliverableContentDiscriminator)[keyof typeof DeliverableContentDiscriminator];
+
+/** Document-template kind: multi-page markdown manifest + page artifacts. */
+export interface DocumentDeliverableContent {
+  readonly kind: typeof DeliverableContentDiscriminator.Document;
+  readonly manifestPath: string;
+  readonly pages: readonly DeliverablePage[];
+}
+
+export interface DeliverablePage {
+  readonly slug: string;
+  readonly title: string;
+  readonly artifactId: string;
+  readonly versionId: string;
+  readonly version: number;
+}
+
+/** ZodSchema / JsonSchema / StructuredJson kinds: a single validated JSON value. */
+export interface JsonDeliverableContent {
+  readonly kind: typeof DeliverableContentDiscriminator.Json;
+  readonly artifactId: string;
+  readonly versionId: string;
+  readonly version: number;
+  readonly value: unknown;
+}
+
+/** EndpointFetch kind: a payload the activity fetched from a configured endpoint. */
+export interface EndpointDeliverableContent {
+  readonly kind: typeof DeliverableContentDiscriminator.Endpoint;
+  readonly artifactId: string;
+  readonly versionId: string;
+  readonly version: number;
+  readonly payload: unknown;
+}
+
+/** ResponseOnly kind: agent's final assistant text — no file emitted. */
+export interface ResponseDeliverableContent {
+  readonly kind: typeof DeliverableContentDiscriminator.Response;
+  readonly text: string;
+}
+
+/** Custom kind: a list of arbitrary files written into the target slot. */
+export interface CustomDeliverableContent {
+  readonly kind: typeof DeliverableContentDiscriminator.Custom;
+  readonly files: readonly DeliverableCustomFile[];
+}
+
+export interface DeliverableCustomFile {
+  readonly path: string;
+  readonly artifactId: string;
+  readonly versionId: string;
+  readonly version: number;
+  readonly contentKind: 'json' | 'markdown' | 'text';
+  readonly sizeBytes: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Validation failures ──
+//
+// Emitted by the agent activity when the harvested workspace fails the
+// deliverable spec's `outputContract`. Carried in CloudEvent payloads
+// (`workflow.activity.deliverable.validation-failed`,
+// `…self-correction-failed`) and surfaced on the run-detail UI so users
+// see exactly what the agent did vs. what the contract required.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export enum DeliverableValidationReason {
+  /** A required `files[]` entry was not present in the target slot. */
+  MissingFile = 'MISSING_FILE',
+  /** A `multiPage.pages[]` entry has no corresponding rendered page artifact. */
+  MissingPage = 'MISSING_PAGE',
+  /** The harvested JSON parsed but failed Ajv / Zod schema validation. */
+  SchemaViolation = 'SCHEMA_VIOLATION',
+  /** A required JSON file did not parse. */
+  MalformedJson = 'MALFORMED_JSON',
+  /** Mode is response-only but the agent produced no assistant text. */
+  EmptyResponse = 'EMPTY_RESPONSE',
+  /** Files were emitted, but in the wrong workspace slot (deliverables vs repos/<slug>). */
+  WrongTargetSlot = 'WRONG_TARGET_SLOT',
+  /** The harvester itself failed mechanically (e.g. proxy 5xx). */
+  HarvestError = 'HARVEST_ERROR',
+}
+
+/**
+ * One specific reason the validation failed. Multiple reasons may coexist
+ * for a single failure (e.g. one missing page + one schema violation).
+ */
+export interface DeliverableValidationFailureReason {
+  readonly code: DeliverableValidationReason;
+  /** File path (for file-related reasons) or JSON pointer (for schema reasons). */
+  readonly path: string | null;
+  /** Short summary of what was expected at this path. */
+  readonly expected: string | null;
+  /** Short summary of what was found at this path. */
+  readonly actual: string | null;
+  /** Human-readable message — safe to display verbatim on the UI. */
+  readonly message: string;
+}
+
+/**
+ * Structured snapshot of what the deliverable spec required. Derived from
+ * the spec's `outputContract` at validation time so the FE doesn't need
+ * a second round-trip to deliverable-specs-api to render the failure card.
+ */
+export interface DeliverableExpectedSummary {
+  readonly mode: string;
+  readonly targetSlot: DeliverableTargetSlot | null;
+  readonly requiredFiles: readonly DeliverableExpectedFile[];
+  readonly multiPagePages: readonly { slug: string; title: string }[];
+  readonly notes: string | null;
+}
+
+export interface DeliverableExpectedFile {
+  readonly path: string;
+  readonly contentKind: string;
+  readonly schemaRef: string | null;
+  readonly required: boolean;
+  readonly purpose: string;
+}
+
+/**
+ * Structured snapshot of what the harvester actually found. Lets the FE
+ * render "expected vs actual" side-by-side without re-walking the workspace.
+ * Sample bytes are bounded — full file contents stay in artifact-store.
+ */
+export interface DeliverableActualSummary {
+  readonly filesFound: readonly DeliverableActualFile[];
+  /** Up to ~2 KB of the agent's final assistant text (response-only mode). */
+  readonly responseExcerpt: string | null;
+  /**
+   * For json/json-schema/structured-json kinds, the parsed JSON the
+   * harvester read (if it parsed at all). `null` for non-JSON modes or
+   * when parse failed (`MALFORMED_JSON` reason will be present instead).
+   */
+  readonly parsedJsonSample: unknown;
+}
+
+export interface DeliverableActualFile {
+  readonly path: string;
+  readonly sizeBytes: number;
+  readonly contentKind: 'json' | 'markdown' | 'text' | null;
+}
+
+/**
+ * Top-level failure object. Emitted as the payload of the four
+ * `workflow.activity.deliverable.*` CloudEvents and carried on the
+ * `DELIVERABLE_CONTRACT_VIOLATED` error's `cause` ({ first, second }).
+ */
+export interface DeliverableValidationFailure {
+  readonly specRef: string;
+  readonly kind: string;
+  readonly expected: DeliverableExpectedSummary;
+  readonly actual: DeliverableActualSummary;
+  readonly reasons: readonly DeliverableValidationFailureReason[];
+  /** The agent's closing assistant message (if any) — useful to compare claim vs reality. */
+  readonly agentFinalMessage: string | null;
+  /** ISO-8601 UTC. */
+  readonly attemptedAt: string;
+}
+
+/** CloudEvent kinds the agent activity emits for the self-correction flow. */
+export const DeliverableLifecycleEventKind = {
+  ValidationFailed: 'workflow.activity.deliverable.validation-failed',
+  SelfCorrectionStarted: 'workflow.activity.deliverable.self-correction-started',
+  SelfCorrectionSucceeded: 'workflow.activity.deliverable.self-correction-succeeded',
+  SelfCorrectionFailed: 'workflow.activity.deliverable.self-correction-failed',
+} as const;
+
+export type DeliverableLifecycleEventKindValue =
+  (typeof DeliverableLifecycleEventKind)[keyof typeof DeliverableLifecycleEventKind];

package/src/workflow/lib/domain-tag.ts

@@ -0,0 +1,48 @@
+// ── Domain Tags (clarification decomposition) ────────────────────────
+//
+// Canonical tag set for domain classification of change units.
+// Covers the major technology domains that a change unit can affect.
+
+export type DomainTag =
+  // Web
+  | 'frontend'
+  | 'backend'
+  | 'api'
+  // Data
+  | 'database'
+  | 'data_pipeline'
+  // Infrastructure / DevOps
+  | 'infrastructure'
+  | 'ci_cd'
+  | 'deployment'
+  | 'cloud'
+  // Security / Identity
+  | 'auth'
+  | 'security'
+  // Integration / Communication
+  | 'integration'
+  | 'messaging'
+  | 'event_streaming'
+  // Observability
+  | 'observability'
+  | 'logging'
+  | 'monitoring'
+  // Embedded / IoT / Hardware
+  | 'firmware'
+  | 'embedded'
+  | 'iot'
+  | 'hardware_interface'
+  // Mobile
+  | 'mobile_ios'
+  | 'mobile_android'
+  | 'mobile_cross_platform'
+  // AI / ML
+  | 'ml_model'
+  | 'ai_agent'
+  // Documentation / Content
+  | 'documentation'
+  | 'content'
+  // Cross-cutting
+  | 'cross_cutting'
+  // Escape hatch
+  | `custom/${string}`;

package/src/workflow/lib/enums.ts

@@ -0,0 +1,288 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workflow Execution Enums ──
+//
+// Closed domains for every workflow/job/step state + policy value.
+// Every workflow-plane decision point uses one of these enums. Free-form
+// strings are forbidden for closed sets (see docs/API_STANDARDS.md §5.3).
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** How a workflow run was initiated. */
+export enum WorkflowTriggerKind {
+  WORKFLOW_DISPATCH = 'workflow_dispatch',
+  SCHEDULE = 'schedule',
+  WEBHOOK = 'webhook',
+  WORKFLOW_CALL = 'workflow_call',
+}
+
+/** How concurrent runs that share a concurrency group behave. */
+export enum ConcurrencyMode {
+  ALLOW = 'allow',
+  QUEUE = 'queue',
+  CANCEL_IN_PROGRESS = 'cancel_in_progress',
+  SKIP = 'skip',
+}
+
+/** Permission scopes a workflow may request. Enforced at the activity boundary. */
+export enum PermissionScope {
+  NONE = 'none',
+  READ = 'read',
+  LIMITED = 'limited',
+  WRITE = 'write',
+}
+
+/** Permission resources a workflow may request scoped access to. */
+export enum PermissionResource {
+  REPOS = 'repos',
+  KB = 'kb',
+  BACKLOG = 'backlog',
+  INTEGRATIONS = 'integrations',
+  ARTIFACTS = 'artifacts',
+  MEMORY = 'memory',
+}
+
+/** How an action is executed under Temporal. */
+export enum ActionExecutionKind {
+  ACTIVITY = 'activity',
+  CHILD_WORKFLOW = 'child_workflow',
+}
+
+/**
+ * Semantic category of an action — drives consumer presentation (FE
+ * canvas shape, badge iconography, narration colouring) WITHOUT
+ * dictating execution semantics.
+ *
+ * Declared per-manifest under `spec.actionKind`. Optional: omitted
+ * manifests fall back to `GENERIC`. Biomes introducing new actions
+ * pick the closest match; the closed set keeps consumers' visuals
+ * stable regardless of how many actions are published. Consumers MUST
+ * treat unknown strings as `GENERIC` so a future kind doesn't crash
+ * an older client.
+ */
+export enum ActionKind {
+  /** Long-running LLM agent invocation against a workspace mount. */
+  AGENT = 'agent',
+  /** Aggregates reviewer verdicts, emits an `approve`/`reject` decision. */
+  REVIEW = 'review',
+  /** Suspends the run pending an external signal (human input, webhook). */
+  WAIT = 'wait',
+  /** Suspends the run for a fixed duration. Distinct from `wait`: timer
+   *  fires deterministically; `wait` blocks on a signal. */
+  TIMER = 'timer',
+  /** Joins fan-out results into a single downstream output. */
+  AGGREGATE = 'aggregate',
+  /** Dispatches a sub-workflow (reusable workflow or external workflow call). */
+  DISPATCH = 'dispatch',
+  /** Conditional split — routes downstream based on a predicate. */
+  BRANCH = 'branch',
+  /** Iterative construct — repeats a body until a termination condition. */
+  LOOP = 'loop',
+  /** Publishes artefacts / state to an external store (KB, repo, ticket tracker). */
+  PUBLISH = 'publish',
+  /** Outbound notification (email, slack, push) — fire-and-forget; no reply expected. */
+  NOTIFY = 'notify',
+  /** Open question to a human or agent — information-gathering, not a
+   *  binding decision. For binding approve/reject, use `review`. */
+  INQUIRY = 'inquiry',
+  /** Reads from an external source (SCM checkout, HTTP fetch, webhook ingest). */
+  FETCH = 'fetch',
+  /** Pure deterministic data transformation — no side effects, no external IO. */
+  TRANSFORM = 'transform',
+  /** Validates a deliverable / payload against a schema or contract. */
+  VALIDATE = 'validate',
+  /** Explicit terminal node — marks the end of a branch with a summary
+   *  outcome. Distinct from the trigger node, which marks the start. */
+  TERMINATE = 'terminate',
+  /** None of the above — neutral catch-all. */
+  GENERIC = 'generic',
+}
+
+/**
+ * Semantic category of a workflow run event — drives consumer
+ * iconography + colouring in the recent-tail / activity console
+ * surfaces without dictating delivery semantics.
+ *
+ * Stamped by the producer (the run-timeline projector) by mapping
+ * structured CloudEvent `type` strings (`workflow.activity.failed`,
+ * `workflow.run.started`, …) into this closed set. Consumers MUST
+ * treat unknown strings as `GENERIC`.
+ */
+export enum RunEventKind {
+  RUN_STARTED = 'run_started',
+  RUN_COMPLETED = 'run_completed',
+  RUN_FAILED = 'run_failed',
+  RUN_CANCELLED = 'run_cancelled',
+  JOB_STARTED = 'job_started',
+  JOB_COMPLETED = 'job_completed',
+  JOB_FAILED = 'job_failed',
+  JOB_WAITING = 'job_waiting',
+  DELIVERABLE_EMITTED = 'deliverable_emitted',
+  DELIVERABLE_REJECTED = 'deliverable_rejected',
+  REVIEW_VERDICT = 'review_verdict',
+  QUESTION_ASKED = 'question_asked',
+  QUESTION_ANSWERED = 'question_answered',
+  PHASE_ENTERED = 'phase_entered',
+  PAUSED = 'paused',
+  RESUMED = 'resumed',
+  GENERIC = 'generic',
+}
+
+/** Named Temporal task queues the worker polls. Enum so every caller picks a valid queue. */
+export enum TaskQueueName {
+  DEFAULT = 'xema_default',
+  AGENT = 'xema_agent',
+  HUMAN = 'xema_human',
+}
+
+/** Job strategy kind — determines how many job runs a declaration produces. */
+export enum MatrixStrategyKind {
+  /** No matrix — exactly one job run. */
+  SINGLE = 'single',
+  /** Matrix expanded at compile time from static input lists. Cardinality fixed. */
+  STATIC = 'static',
+  /** Matrix expanded at runtime from an upstream output. Cardinality determined after dispatch. */
+  DYNAMIC = 'dynamic',
+}
+
+/** Lifecycle states of a workflow run. */
+export enum WorkflowRunStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  WAITING_ON_APPROVAL = 'waiting_on_approval',
+  WAITING_ON_HUMAN = 'waiting_on_human',
+  PAUSED = 'paused',
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  ABORTED_FOR_MIGRATION = 'aborted_for_migration',
+}
+
+/** Terminal states — a run in one of these states accepts no further transitions. */
+export const TERMINAL_WORKFLOW_RUN_STATUSES: readonly WorkflowRunStatus[] = [
+  WorkflowRunStatus.SUCCEEDED,
+  WorkflowRunStatus.FAILED,
+  WorkflowRunStatus.CANCELLED,
+  WorkflowRunStatus.ABORTED_FOR_MIGRATION,
+] as const;
+
+/** Lifecycle states of a single job run inside a workflow run. */
+export enum JobRunStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  WAITING = 'waiting',
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  SKIPPED = 'skipped',
+}
+
+/** Terminal states — a job in one of these states accepts no further transitions. */
+export const TERMINAL_JOB_RUN_STATUSES: readonly JobRunStatus[] = [
+  JobRunStatus.SUCCEEDED,
+  JobRunStatus.FAILED,
+  JobRunStatus.CANCELLED,
+  JobRunStatus.SKIPPED,
+] as const;
+
+/** Lifecycle states of a step run (single action invocation) inside a job. */
+export enum StepRunStatus {
+  PENDING = 'pending',
+  RUNNING = 'running',
+  SUCCEEDED = 'succeeded',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+  RETRYING = 'retrying',
+}
+
+/**
+ * Canonical action ids shipped in the v1 built-in catalog. Closed set; new builtins extend this.
+ *
+ * Namespace policy:
+ *   - `xema/<id>`         — generic, platform-owned actions every sub-app needs.
+ *   - `software-dev/<id>` — actions belonging to the first-party software-dev biome.
+ *
+ * No alias map. The deploy migration rewrites in-flight `CompiledRun`
+ * records that still carry the old `xema/scm-*` / `xema/backlog-sync`
+ * ids to their new `software-dev/*` form. Anything not migrated → engine
+ * dispatch throws `ActionNotRegistered` (fail-fast, deterministic).
+ */
+export enum BuiltInActionId {
+  AGENT = 'xema/agent',
+  REVIEW = 'xema/review',
+  /**
+   * Decision gate action — the canonical workflow-author-declared
+   * pause-and-aggregate primitive. Accepts 1+ recipients (humans /
+   * agents / endpoints) and a reply policy.
+   */
+  DECISION_GATE = 'xema/decision-gate',
+  /**
+   * Comment review action — the workflow-author-declared comment-only
+   * review primitive. Pins one or more artifact versions and asks human
+   * recipients to leave free-form commentary; auto-resolves once every
+   * mandatory recipient has replied OR the deadline passes. Returns the
+   * union of all reviewers' comments. Distinct from `xema/decision-gate`
+   * (no approve/reject) and `xema/review` (the iteration-loop orchestrator).
+   */
+  COMMENT_REVIEW = 'xema/comment-review',
+  VALIDATE_DELIVERABLES = 'xema/validate-deliverables',
+  PUBLISH_KB = 'xema/publish-kb',
+  BACKLOG_SYNC = 'software-dev/backlog-sync',
+  SCM_CHECKOUT = 'software-dev/scm-checkout',
+  SCM_MERGE = 'software-dev/scm-merge',
+  WEBHOOK = 'xema/webhook',
+  HTTP = 'xema/http',
+  WAIT = 'xema/wait',
+  EMIT_ARTIFACT = 'xema/emit-artifact',
+  ENDPOINT_FETCH = 'xema/endpoint-fetch',
+  SCM_POST_REVIEW = 'software-dev/scm-post-review',
+  DISPATCH_WORKFLOW = 'xema/dispatch-workflow',
+  /**
+   * Send an email via AWS Simple Email Service. Shipped by
+   * `biomes/platform/aws-integration`. Credentials come from the
+   * caller's wallet via `${{ secrets.AWS_SECRET_ACCESS_KEY }}` etc.
+   */
+  AWS_SES_SEND = 'aws-integration/ses-send',
+  /**
+   * Invoke a capability through `xema-capability-router`'s
+   * `POST /capabilities/invoke` funnel. The single constitutional path
+   * for a workflow step to talk to any platform / biome service —
+   * biomes MUST NOT see internal service URLs or mint their own
+   * authorization decisions, so any cross-service side-effect routes
+   * through this action and the router's grant resolver decides.
+   *
+   * Inputs declare the `ref` (`<domain>:<resource>.<verb>@<major>`),
+   * the opaque `input` payload the bound implementation consumes, and
+   * an optional `subjectOverride` for callers that need to act as a
+   * different subject than the workflow's executing identity. The
+   * activity derives `subject` from the worker's service identity
+   * when no override is supplied and stamps `correlationId` with the
+   * workflow run id so audit-log entries stitch back to the run.
+   */
+  CAPABILITY_INVOKE = 'xema/capability',
+  /**
+   * Trigger an org-database migration via org-database-pool-api and
+   * block until the run reaches a terminal state. Generic primitive
+   * (Phase G of the org-managed-databases plan) — any sub-app that
+   * needs to materialize a schema against a pool-managed database
+   * dispatches this action; the caller is responsible for resolving
+   * the `databaseId` and providing a `workspaceDir` containing the
+   * migration package.
+   */
+  RUN_MIGRATIONS = 'xema/run-migrations',
+}
+
+/** Revision semantics exposed to the UI. Maps 1:1 to the 4 revision UIs in the pipeline redesign. */
+export enum RevisionKind {
+  /** Deterministic automatic retry under a declared retry policy. */
+  AUTO_RETRY = 'auto-retry',
+  /** Operator override (extendRetries / forceApprove / rejectRun). */
+  MANUAL_OVERRIDE = 'manual-override',
+  /** Checkpoint revise & resume (reviseAndResume Update). */
+  CHECKPOINT_REVISE = 'checkpoint-revise',
+  /** Redo from a prior step (resetWorkflowExecution). */
+  REDO_FROM_STEP = 'redo-from-step',
+}
+
+/** Snapshot storage kinds. Extended when a new store is added. */
+export enum SnapshotStoreKind {
+  ARTIFACT_STORE = 'artifact-store',
+}