Snapshots - shipd

Overview

A snapshot is the derived, evaluation-ready document for one environment. Postgres owns definitions; KV holds only this blob. SDKs never see audit logs, secrets, tags, or managedBy.

Shape

{
  "schemaVersion": 1,
  "projectId": "prj_fieldkit_web",
  "environmentId": "env_prod_01",
  "environmentKey": "production",
  "version": 42,
  "generatedAt": "2026-08-18T16:04:00.000Z",
  "flags": {
    "new-checkout": {
      "key": "new-checkout",
      "type": "boolean",
      "enabled": true,
      "default": false,
      "version": 7,
      "rules": [],
      "fallthrough": { "kind": "boolean", "value": false }
    }
  },
  "segments": {}
}

version is environment.snapshot_version — monotonic per environment, independent of per-flag versions.

How it gets there

Control-plane mutation + audit commit
snapshot_outbox row
Materialize → KV snapshots/{environmentId}/current.json
Notify ws-gateway (snapshot.updated)
Mark outbox processed

Failed KV/notify leaves the outbox pending. Retry with shipd snapshots publish or wait for the drain interval.

SDK rules

Fetch current snapshot only (no replay of versions 11–14 if you jumped 10 → 15)
Ignore HTTP bodies with version < local (no rollback)
After notify, retry while version < notified (KV lag), then keep last good
Unsupported schemaVersion → onError, keep last good

ETag: "snapshot-<version>". Send If-None-Match to get 304.

Next

⌘I