Versioning, Releases & Migration#

Sequence definitions are immutable versions. New executions resolve to the newest non-deprecated version unless a caller pins one; existing executions remain bound to the version where they started. A release is the evidence and routing layer between two stored versions.

Version lifecycle#

• ✓Versions are unique by tenant, namespace, sequence name, and version.
• ✓Deprecating a version prevents new unpinned executions from selecting it.
• ✓Promotion routes new executions; the default pin policy never silently migrates work already in flight.
• ✓Dynamic block injection is instance-local and does not mutate the stored sequence version.

Guarded workflow release#

Release state transitions are compare-and-swap and append immutable decisions. Historical validation is effect-free; missing evidence is divergence or inconclusive, never a pass.

draft → validating → ready → canary → promoted
  └──────────→ failed          ├──────→ paused → canary
                              └──────→ rolled_back

export ORCH8_URL=http://127.0.0.1:8080/api/v1
export ORCH8_API_KEY='replace-me'
export ORCH8_TENANT_ID=demo

RELEASE_ID=$(orch8 --output json release create   --tenant-id demo   --baseline "$BASELINE_ID"   --candidate "$CANDIDATE_ID"   --max-error-regression 0.05   --min-sample 20 | jq -r '.id')

orch8 release diff "$RELEASE_ID"
orch8 release validate "$RELEASE_ID" --sample 20
orch8 release canary "$RELEASE_ID" --percent 10
orch8 release evaluate "$RELEASE_ID"
orch8 release promote "$RELEASE_ID"

Pause with orch8 release pause, resume the canary at a chosen percentage, or permanently roll it back withorch8 release rollback. A failing gate rolls a canary back automatically; inconclusive evidence cannot promote.

Release API#

API=http://127.0.0.1:8080/api/v1

curl -sS -X POST "$API/releases"   -H "x-api-key: $ORCH8_API_KEY"   -H "x-tenant-id: demo"   -H "content-type: application/json"   -d "{
    "tenant_id": "demo",
    "baseline_sequence_id": "$BASELINE_ID",
    "candidate_sequence_id": "$CANDIDATE_ID",
    "gates": [{
      "metric": "error_rate",
      "max_regression": 0.05,
      "min_sample": 20
    }],
    "in_flight_policy": "pin"
  }"

Transition endpoints are /validate,/canary, /evaluate,/promote, /pause, and/rollback. Read semantic evidence fromGET /releases/{id}/diff and the immutable audit trail from GET /releases/{id}/decisions.

Ownership-safe live migration#

Portable Continuity can migrate an execution only at a durable waiting or paused boundary. The server computes the semantic and checkpoint diff, replays retained evidence with real handlers disabled, evaluates invariants, and returns one of automatic,approval_required, pin, or incompatible.

orch8 execution migration-plan plan.json
orch8 execution migration-get <plan-id> --tenant-id tenant-a
orch8 execution migration-apply <plan-id> approval.json
orch8 execution migration-rollback <plan-id> rollback.json

Version-1 transforms support bounded copy,move, and drop operations over checkpoint paths. Apply rechecks state, sequence, and ownership epoch, exports a signed encrypted pre-migration capsule, and leaves the target paused for explicit inspection.

Placement-bound handoff#

In 0.7.0, handoff creation must bind to a fresh placement preview. Send the unchanged policy and requirements with both identifiers returned by preview:

{
  "placement_decision_id": "<from-preview>",
  "preview_sha256": "<from-preview>",
  "destination_runtime_id": "<selected-runtime>",
  "data_classification": "restricted",
  "requirements": { "handlers": ["camera.capture"] },
  "locality_policy": {
    "version": 1,
    "rules": [{
      "classification": "restricted",
      "allowed_runtime_ids": ["<selected-runtime>"],
      "minimum_trust": "registered"
    }]
  }
}

The engine re-evaluates runtime liveness and policy at handoff creation and immediately before capsule export. Stale or changed facts return a conflict instead of silently selecting another destination.

curl -fsSL https://orch8.io/start.sh | sh