Temporal orchestration
How a durable workflow carries a change through its stages with idempotency, checkpoints, pause and resume, and reference-only payloads.
The orchestration layer belongs to the proprietary runtime. The stage and state vocabulary is public in the protocol types.
The lifecycle is a durable state machine with fresh authority per stage, not one long agent session. Temporal schedules the work. It never grants authority.
Shape of the orchestration
One ChangeLifecycle workflow exists per change. It owns the state machine and delegates each stage to an activity or a child workflow: context resolution, one WorkUnitExecution per work unit, verification and release. Intake is idempotent: a second request to open the same change attaches to the existing workflow instead of starting another.
Change lifecycle
What does a durable change do from objective to evidence, and where does it pause?
- Understand / Classify
- ◇ Plan gate
- Implement
- Verify
- ┄ Repair (bounded)
- Rehearse
- ◇ Release gate
- Merge
- Release
- Observe
- ┄ Recover
- Evidence seal
Step 1 of 10 · Understand / Classify
Context is resolved from authorised sources and the Change is classified.
- Lifecycle state
- Opened, Understood, Classified
- Who acts
- engine (read-only grant)
- Temporal holds (references only)
- change_id, state, context bundle artifact_ref + sha256
- Customer artifact storage holds
- Repository index, resolved context bundle, risk classification
- Evidence record emitted
- Context resolved: sources used and digests
Happy path, step 1 of 10: Understand / Classify. Context is resolved from authorised sources and the Change is classified.
Text description
A Change is a durable state machine, not one long agent session. The agent implements one work unit at a time; planning, gates, verification, release and recovery are performed by Numinance with fresh authority per stage. Orchestration payloads carry references and digests only; source, diffs, prompts, logs and findings bodies live in customer artifact storage.
Stages in order: Understand / Classify, Plan gate, Implement, Verify, Repair (bounded), Rehearse, Release gate, Merge, Release, Observe, Recover, Evidence seal. Verification failure re-enters implementation with the findings reference as the only new input, at most max_repair_attempts times (default 2 in the generated Playbook), then the Change is escalated. Plan and release gates can allow, deny or require approval; approvals come from a human other than the author.
Happy path. Every gate allows and verification passes first time.
- Understand / Classify: Context is resolved from authorised sources and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy allows the plan under the initial grant. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
- Implement: One work unit runs in a sandbox under a work-unit grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Deterministic checks pass; the reviewer adds findings, never a verdict. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Rehearse: A disposable environment rehearses migrations and deployment; it is destroyed at its TTL. Acts: engine with environment provider; reviewer identity. Evidence: Rehearsal evidence: timings and plan digests.
- Release gate: Policy consumes the verdict and the evidence list and allows the release. Acts: policy decides; release-pipeline identity only after allow. Evidence: Gate decision referencing the verdict, never raw findings.
- Merge: The release pipeline merges. At PR level the Change closes here; higher levels continue. Acts: release-pipeline. Evidence: Merge recorded with operation id; PR-level autonomy ends here as Closed.
- Release: Only the release pipeline deploys, and only if the autonomy level allows. Acts: release-pipeline (the only deployer). Evidence: Deployment recorded under the release identity.
- Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
- Evidence seal: The runner seals the evidence sequence and the Change closes. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Verification fails, then repair. A failing check feeds one bounded repair attempt, then verification passes.
- Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy allows the plan. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
- Implement: The author-agent produces a first candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: A deterministic check fails. The findings are stored and referenced by digest. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Repair (bounded): Attempt 1 of 2 (the default cap). The findings reference is the only new input. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
- Implement: The author-agent runs again under a fresh grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: All verification layers pass this time. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Rehearse: A disposable environment rehearses migrations and deployment; it is destroyed at its TTL. Acts: engine with environment provider; reviewer identity. Evidence: Rehearsal evidence: timings and plan digests.
- Release gate: Policy consumes the verdict and the evidence list and allows the release. Acts: policy decides; release-pipeline identity only after allow. Evidence: Gate decision referencing the verdict, never raw findings.
- Merge: The release pipeline merges. At PR level the Change closes here; higher levels continue. Acts: release-pipeline. Evidence: Merge recorded with operation id; PR-level autonomy ends here as Closed.
- Release: Only the release pipeline deploys, and only if the autonomy level allows. Acts: release-pipeline (the only deployer). Evidence: Deployment recorded under the release identity.
- Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
- Evidence seal: The runner seals the evidence sequence and the Change closes. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Repair exhausted, escalated. Two bounded repairs fail. The Change escalates to a human instead of trying forever.
- Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy allows the plan. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
- Implement: First candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification fails. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Repair (bounded): Attempt 1 of 2. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
- Implement: Second candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification fails again. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Repair (bounded): Attempt 2 of 2. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
- Implement: Third candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification fails a third time. The cap is reached. Acts: engine; waits for a human signal. Evidence: Escalation recorded with the findings digest; no grant is widened.
Approval required. Policy answers require approval. The workflow waits for a human other than the author.
- Understand / Classify: Context is resolved and the Change is classified as higher risk. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy answers require approval. The workflow now waits on a signal with a timer (default 7 days). Acts: policy; human approver pending. Evidence: Policy decision: require approval, approver group, author excluded.
- Plan gate: A human approver grants. The signal is rejected if the approver equals the author. Acts: human approver. Evidence: Approval record with approver principal and decision id.
- Implement: Work proceeds under the approved grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification passes. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Rehearse: A disposable environment rehearses migrations and deployment; it is destroyed at its TTL. Acts: engine with environment provider; reviewer identity. Evidence: Rehearsal evidence: timings and plan digests.
- Release gate: Policy consumes the verdict and the evidence list and allows the release. Acts: policy decides; release-pipeline identity only after allow. Evidence: Gate decision referencing the verdict, never raw findings.
- Merge: The release pipeline merges. At PR level the Change closes here; higher levels continue. Acts: release-pipeline. Evidence: Merge recorded with operation id; PR-level autonomy ends here as Closed.
- Release: Only the release pipeline deploys, and only if the autonomy level allows. Acts: release-pipeline (the only deployer). Evidence: Deployment recorded under the release identity.
- Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
- Evidence seal: The runner seals the evidence sequence and the Change closes. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Denied by policy. The plan gate denies. The denial is recorded and the Change is abandoned with no write grant ever issued.
- Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy denies the plan. Denials are evidence too. Acts: policy decision point. Evidence: Denial with rule ids as reasons and the policy decision id.
- Evidence seal: The runner seals the sequence. No code was written. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Stage states
A change moves through opened, understood, classified, planned and a plan gate, then implementing, integrated, verifying and rehearsing, then a release gate, merging and, where the autonomy level allows, releasing and observing. Terminal states are closed, abandoned and rolled back. Paused and escalated are holding states, not endings.
| Gate | Authority row | Who decides |
|---|---|---|
| Plan gate | Planning under an initial grant | Policy decision; a human where the decision requires approval |
| Release gate | Release identity only | Policy decision; a human where required |
Reliability mechanics
| Mechanism | What it does |
|---|---|
| Signals | Deliver approvals, rejections, incident notices, breaker trips and resets, and cancellation |
| Timeouts | Every activity is bounded; approval waits have a timer, after which the change escalates |
| Idempotency keys | Each side-effecting step derives a key from the change, step and target, so a retry cannot repeat a merge or deploy |
| Reconciliation | Before retrying, the step queries the provider for the outcome; success whose response was lost is recorded, not repeated |
| Checkpoints | The sandbox snapshots the worktree on checkpoint events; after a crash, a run restarts from the last snapshot |
| Pause and resume | A breaker trip pauses at the next heartbeat, revokes handles and resumes only on a human reset |
| Continue-as-new | Long histories roll over carrying only the change identifier and current state |
| Worker versioning | Running workflows stay pinned to the build that started them; replay tests run recent histories against new builds |
No token-level resume
A harness process cannot resume mid-turn after a crash. Numinance restarts from the last snapshot with the event stream so far as input, and budgets count across restarts.
Payloads carry only references
Every workflow and activity argument and result is limited to identifiers, artifact references, digests, statuses, enum codes and timestamps. Source, diffs, tickets, prompts, logs, findings and secrets live in the artifact store and travel as references. A payload codec rejects shapes outside that allow-list, and failure details are held to the same rule: activities return an error class, a stable code and a diagnostic reference, not vendor or model error text.
Repair, budgets and escalation
A failed verification re-enters implementation with the findings reference as the only new input, at most max_repair_attempts times (the generated Playbook defaults to 2, bounded 0 to 10), then the change is escalated. Budgets bound every loop independently of attempt counts. An exhausted budget pauses and escalates. It never widens the grant.
Authority stays outside the workflow
- Approvals arrive as signals validated against the authenticated human principal. An approver equal to the author is rejected.
- The workflow requests a policy decision and a grant per stage; it cannot mint either.
- A replayed or duplicated signal cannot create authority because decisions are recorded as evidence with their own identifiers.
Boundary table
| Holder | Holds | Does not hold |
|---|---|---|
| Workflow engine | Durable state, timers, references | Content, credentials, the right to approve |
| Activities | One use case each, under a stage grant | Grants beyond the stage |
| Approvers | Signals attributable to an authenticated human | Approval of their own work |
Failure cases
- Worker crash mid-run: restart from the last checkpoint, no repeated external effect.
- Approval timeout: the change escalates; it does not proceed by default.
- Payload outside the allow-list: rejected at the codec, which fails the step rather than leaking content.
- Evidence sealing fails at close: retried until success and the failure trips the breaker.