State and Deduplication

Overview

This guide covers the deployment source of truth, queue deduplication semantics, and how the system maintains consistency across distributed components.

Deployment Source of Truth

Remote execution uses a single active deployment pointer stored in the worker's SQLite database. This pointer is the authoritative source for:

Which deployment runs new workflows
Which deployment handles queue messages
/v1/world/deployment-id responses
Trigger path resolution when deploymentId is omitted

Active Pointer Resolution

The active deployment is stored in the settings table:

CREATE TABLE IF NOT EXISTS settings (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL
);

-- Active deployment pointer
INSERT INTO settings (key, value) VALUES ('active_deployment', 'dep_abc123');

Retrieved via:

function getActiveDeploymentId(db: SqliteDB): string | undefined {
  const active = db
    .prepare(`SELECT value FROM settings WHERE key = 'active_deployment'`)
    .get() as { value: string } | undefined;
  return active?.value;
}

Missing Active Deployment

If no active deployment is set, endpoints return:

{
  "code": "no_active_deployment",
  "message": "No active deployment. Activate a deployment before triggering runs."
}

with HTTP status 409 Conflict.

This error is returned by:

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

Activate vs Deploy

Deploy: Uploads an artifact and creates a deployment record. Does not change which deployment is active.
Activate: Updates the active deployment pointer. Existing runs continue on their original deployment; new runs use the newly activated deployment.
Rollback: Activates a previous deployment, reverting new runs to that code.

Queue Deduplication

Queue publishing deduplicates only when an explicit idempotency key is provided:

// No deduplication - each call publishes
await compute.publish(queueName, message, {
  deploymentId: 'dep_123',
});

// Deduplication applied
await compute.publish(queueName, message, {
  deploymentId: 'dep_123',
  idempotencyKey: 'unique-key-123',
});

Why Explicit Only?

Implicit deduplication based on run/deployment IDs can suppress legitimate lifecycle events like:

Multiple wakeups for the same run
Resume operations after suspension
Retry attempts with the same deployment

Explicit opts.idempotencyKey puts control in the caller's hands.

Idempotency Implementation

Idempotency is implemented via the idempotency table:

CREATE TABLE IF NOT EXISTS idempotency (
  project_id TEXT NOT NULL,
  idempotency_key TEXT NOT NULL,
  endpoint TEXT NOT NULL,
  status_code INTEGER NOT NULL,
  body TEXT NOT NULL,
  created_at INTEGER NOT NULL,
  state TEXT,
  request_hash TEXT,
  response_run_id TEXT,
  PRIMARY KEY (project_id, idempotency_key, endpoint)
);

Keys expire after 24 hours (idempotencyTtlMs).

Run Creation Deduplication

Run creation (/v1/runs) always requires an Idempotency-Key header and always deduplicates:

const idempotencyKey = req.headers.get('idempotency-key');
if (!idempotencyKey) {
  return json(
    { code: 'idempotency_required', message: 'Idempotency-Key header is required' },
    { status: 400 }
  );
}

/v1/runs compares canonical JSON hashes of request payloads:

Same key + semantically equal payload (including different object key order) is treated as the same request.
Same key + different payload returns 409 { code: 'idempotency_conflict' }.
In-progress retries reuse the same reserved runId to avoid duplicate run creation.

World Events Deduplication

World events (/v1/world/events/create) deduplicate run_created events by run ID:

const isRunCreated = body.data.eventType === 'run_created';
const dedupeKey = isRunCreated && body.runId !== null
  ? `world.events.create:run_created:${body.runId}`
  : undefined;

This prevents duplicate run creation if the same event is sent twice.

Audit Logging

All operations are logged with structured metadata:

logAudit(db, req, auth, 'world.queue.publish', pathname, 'success', {
  lane: 'world_proxy',
  deduped: false,
  idempotencyKey: 'key-123',
});

Metadata includes:

lane - Which auth lane processed the request (world_proxy or public)
deduped - Whether deduplication was applied
correlationId - Request correlation ID from headers
runId - Associated run ID from headers
idempotencyKey - Idempotency key if present

The audit_logs table schema:

CREATE TABLE IF NOT EXISTS audit_logs (
  id TEXT PRIMARY KEY,
  key_id TEXT,
  project_id TEXT,
  action TEXT NOT NULL,
  resource TEXT NOT NULL,
  result TEXT NOT NULL,
  ip TEXT,
  user_agent TEXT,
  metadata_json TEXT,
  created_at TEXT NOT NULL
);

Diagnostics and Ownership

The diagnostics endpoint tracks unexpected app-host traffic:

{
  remoteModeEnabled: true,
  strictMode: true,
  targetWorld: 'workflow-studio/world-remote',
  expectedTargetWorld: 'workflow-studio/world-remote',
  status: 'pass', // or 'warn' or 'fail'
  lifetimeUnexpectedHits: 0,
  unexpectedHitsLast15m: 0,
  lastUnexpectedHitAt: null,
}

Unexpected Hit Detection

When the app host receives a queue callback while remote execution is enabled:

recordUnexpectedHit() stores the event
Diagnostics endpoint reports status: 'fail' in strict mode
validate-ownership --strict exits with code 1

This helps catch misconfigured queue routing or webhook URLs.

On this page