Temporal Orchestration

Run States (runs.status) #

Stage States (stages.status) #

Per-Activity Rules #

Side-Effect Isolation Rule #

All activities that touch external systems (GitHub API, LLM provider, Valkey, Postgres) must be at-most-once observable. Implementation requirements:

• All Postgres writes use INSERT ... ON CONFLICT DO NOTHING or compare-and-swap via unique constraints.
• All Valkey writes for rate-limiting use the semantics documented in infra/valkey/NAMESPACES.md.
• GitHub writes use the Git Trees API (append-only; existing tree SHAs are reused).
• Pure reads are unrestricted and require no idempotency handling.

Activity Retry Policy #

Valkey pr_lock Protocol #

Before performing any GitHub API write, CreatePullRequest acquires the per-repo lock:

SET amtp:rl:repo:{repo}:pr_lock {run_id} NX EX 120

• NX — only sets if the key does not exist (atomic acquisition).
• EX 120 — 120-second TTL as a safety net against a crashed activity that never releases the lock.
• If SET NX returns nil (key held by another run), the activity raises RepoPrLockContended (retryable) and defers to Temporal’s standard activity backoff.

The lock is always released in a finally path using a Lua compare-and-delete script to ensure only the holder can release it:

-- Lua CAS release: only delete if the value matches our run_id
if redis.call("GET", KEYS[1]) == ARGV[1] then
  return redis.call("DEL", KEYS[1])
else
  return 0
end

CreatePullRequest Failure Classes #

Design rationale. No tree-rebase logic. Serialization is enforced by the Valkey lock, not by dynamic task-queue routing. Different repositories operate in full parallelism; only concurrent runs on the same repository are serialized.

State Transitions on StaleBaseBranch #

1. Temporal activity fails with StaleBaseBranch (non-retryable).
2. Parent workflow catches the failure and writes:
   • runs.status = 'failed', runs.finished_at = now()
   • stages.status = 'failed' for the active CreatePullRequest stage
   • A new artifact row: artifacts.kind = 'failure_report' with:

     {
       "error": "StaleBaseBranch",
       "base_branch": "<branch>",
       "observed_head": "<sha-at-crawl-time>",
       "expected_parent": "<sha-used-in-git-tree>"
     }

3. The Temporal workflow execution terminates in a FAILED state.

Recovery Protocol #

Recovery requires provisioning an entirely new pipeline execution via an external trigger:

1. An external webhook fires — typically a subsequent push event on base_branch, or an explicit user-initiated POST /runs API call.
2. The receiver provisions a new run_id via gen_random_uuid() (per migrations/sql/V2__runs.sql).
3. The Repo Crawler re-crawls the repository against the new base_branch HEAD, producing a fresh repo_crawler_output artifact tied to the new run_id.
4. The full pipeline proceeds as a fully independent workflow instance.

Rationale. A re-crawl against the advanced HEAD is the only way to guarantee the Test Case Generator and Test Engineer reason about the same source-of-truth that the PR targets. Any in-place rebase would require a second LLM round-trip, invalidating the stateless-agent context-reset guarantee and the idempotency of the crawler output artifact.

The StaleBaseBranch failure is observable in Postgres (runs.status = 'failed' with a failure_report artifact) and should be surfaced by the operational alerting layer.

Token Scope (Documented Assumption) #

The GitHub App installation token used by CreatePullRequest is provisioned with the following permissions:

Branch-Protection Rules AMTP Honors #

BranchProtectionViolation Handling #

A GitHub 403 response classified as a branch-protection error is non-retryable. The workflow:

1. Writes an approvals row with decision = 'pending', approver = 'branch-protection', and comment = <github error body>.
2. Transitions the active stage to awaiting_approval.
3. Pauses the Temporal workflow pending an external signal.
4. Resumes only when an external signal updates the approvals row to approved (and the operator has resolved the underlying protection issue).

awaiting_approval is a valid stages.status CHECK constraint value. See migrations/sql/V3__stages.sql.