@volter/twin 0.1.0 → 0.1.1

package/README.md

@@ -22,6 +22,13 @@ its own vendor's exact API on top of this. CLI: `volter-twin`.
   and append only changed fields.
 - **Connectors** (`runConnectorPoll` / `runConnectorSweep`): cursor/subject poll
   runners owning the sync invariants.
+- **Pull posture** (`pullPosture` / `assertContinuousPullAllowed` / `pullOnSchedule`):
+  how often a vendor's REAL API may be pulled, declared once by the pack that knows its
+  rate limits (`pullPosture: 'continuous' | 'on-demand'`, default `'on-demand'`) and
+  enforced at the cadence seams. Both poll runners require `connector.vendor` and assert
+  the posture *before* the first vendor request, so a scheduled pull of a rate-fragile —
+  or undeclared — vendor is refused having made zero calls. A one-off pull someone asked
+  for is still allowed: pass `trigger: 'explicit'`.
 - **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
@@ -40,15 +47,22 @@ 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 plan <service> --root <project>           # exact pending transaction set + latest review
+volter-twin review <service> --decision rejected --actor-id <id> --reason <text> --root <project>
+volter-twin review <service> --decision approved --actor-id <id> --root <project>
 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`.
+`VOLTER_STATE_DIR`; `plan` and `review` accept `--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.
 
+Every non-empty plan requires review. Decisions are appended to `plan-reviews.jsonl` and bind to a
+hash of the exact ordered pending-action IDs. Adding or removing an action therefore invalidates an
+earlier approval automatically. `applyPlan` refuses to call a provider unless that exact transaction
+set has a durable approval; rejection records intent but never pushes.
+
 ## API
 
 `listEvents`, `appendEvent`, `createEvent`, `loadState`, `rebuildGenericState`,