State and Deduplication

Overview

This document describes deployment authority and idempotency behavior in remote mode.

Active deployment authority

The active deployment pointer in worker settings is the source of truth for new run execution when deployment ID is not explicitly provided.

Endpoints aligned to this pointer include:

GET /v1/deployments/active
GET /v1/world/deployment-id
POST /v1/runs when deploymentId is omitted

If no active deployment exists, these paths return:

HTTP 409
{ code: "no_active_deployment" }

Deployment lifecycle behavior

compute deploy creates an inactive deployment record and stores artifact metadata.
compute activate updates active deployment pointer.
compute rollback re-points active deployment to a previous deployment.

In-flight runs continue against their pinned deployment.

Queue publish deduplication

Queue deduplication applies only when opts.idempotencyKey is provided.

If opts.idempotencyKey is absent:

queue publish does not dedupe,
repeated publishes are processed independently.

`/v1/runs` idempotency

POST /v1/runs requires Idempotency-Key.

Behavior:

same key + semantically equivalent payload: replay previous accepted result,
same key + different payload: 409 with idempotency_conflict (surfaced as IdempotencyComputeClientError by the client).

`run_created` deduplication in world lane

/v1/world/events/create deduplicates run_created by run ID to prevent duplicate initialization events.

Audit metadata

Audit logs store structured metadata (metadata_json) for lane, dedupe, and correlation fields. This supports forensic analysis and ownership incident debugging.