@volter/twin

The kernel + control plane that the vendor twins build on. It is the shared layer of the twins project: the uniform way every twin is driven (the controlPlane namespace), plus the optional data-plane libraries a twin may reuse. It does not make twins implement their vendor alike — each @volter/twin-<vendor> pack presents its own vendor's exact API on top of this. CLI: volter-twin.

The model

• Events (events.jsonl): append-only, idempotency-keyed observations — facts pulled or confirmed from the real vendor. Replays append nothing; conflicting payloads under one key throw.
• Actions / transaction commits (actions.jsonl): append-only local writes. They project into visible state but do not pollute the observed-event log; undo is a later revert/cancel commit.
• Projected state: a twin's read model is fold(events) + apply(active actions), suppressing a local projection once a push is confirmed by an observed vendor event.
• Push / egress ledger: selected local actions are replicated to the real vendor idempotently; the ledger records action → attempt/result → confirmation.
• Shadow state + deltas: pollers fold the event log into per-subject field state and append only changed fields.
• Connectors (runConnectorPoll / runConnectorSweep): cursor/subject poll runners owning the sync invariants.
• Control plane (the controlPlane namespace): status, plan, push (+ phases), lease, refs/checkpoints, the queue lifecycle, and fork operations (rebase/merge/cherry-pick/revert/reset) — the one uniform surface for driving any twin.
• Validation (volter-twin validate / validateWorld): twin integrity — egress reconciliation + schema conformance.

One twin, three operations (not "modes"): pull reality, write local actions (unless started read-only), fork the local commits — like pull/commit/branch on a repo. The on-disk state is a "world" (a synchronized set of twins).

CLI (volter-twin)

volter-twin events append <service> --file evt.json   # append an observed event
volter-twin events list <service> --json
volter-twin state rebuild <service>                   # rebuild projected state from events
volter-twin status <service>                          # queued/unpushed/drift/conflicts
volter-twin plan <service>                            # reviewable apply plan
volter-twin refs <service>                            # remote checkpoints
volter-twin validate [--services <a,b>]               # twin integrity (egress reconciliation)

State lives under <cwd>/.volter/world/ by default (directory name overridable via VOLTER_STATE_DIR, or pass --root); per-service config in .volter/world/config.json. Pin a --root / VOLTER_STATE_DIR in CI so a twin doesn't write into your repo.

API

listEvents, appendEvent, createEvent, loadState, rebuildGenericState, buildShadowState, recordObservedDelta, performExternalWrite, recordWriteIntent, listEgressLedger, validateWorld, runConnectorPoll, createTwinServer, applyTwinWrite, loadWorldConfig, plus the controlPlane namespace and the optional queryHelpers / recordedDiff / derive / pack-registry libraries. See src/index.ts.

(Annotations + source books are a tracker concern, not a twin one: @volter/tracker/world-annotations, @volter/tracker/world-source-books.)

The vendor twins

Each vendor's twin is its own modular package that peerDepends on @volter/twin: @volter/twin-stripe, @volter/twin-linear, @volter/twin-jira, @volter/twin-github, @volter/twin-slack (at packages/twin/<vendor>), each with its own world-<vendor> CLI (serve / mirror / conformance) and React UI mirror.