@volter/twin 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,68 @@
+# @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`)
+
+```bash
+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.

package/dist/src/actions.d.ts

@@ -0,0 +1,138 @@
+import type { SubjectFields } from './shadow.js';
+import type { TwinResource } from './serve.js';
+export type TwinActionOp = 'set' | 'revert' | 'confirm';
+export type TwinActionPreconditionOp = 'exists' | 'not_exists' | 'eq' | 'neq' | 'version_eq';
+export type TwinActionPrecondition = {
+    subject: {
+        type: string;
+        id: string;
+    };
+    field: string;
+    op: TwinActionPreconditionOp;
+    value?: unknown;
+};
+export type TwinActionRevertSpec = {
+    strategy: 'inverse' | 'suppress' | 'compensating-action';
+    operation?: string;
+    fields?: SubjectFields;
+};
+export type ProjectedResource = {
+    type: string;
+    id: string;
+    fields: SubjectFields;
+};
+export type ProjectedResourcePatch = {
+    type: string;
+    id: string;
+    fields: SubjectFields;
+};
+export type ProjectedResourceRef = {
+    type: string;
+    id: string;
+};
+export type ProjectedDelivery = {
+    kind: 'webhook' | 'event' | 'notification';
+    target: string;
+    payload: Record<string, unknown>;
+};
+export type ActionProjection = {
+    creates?: ProjectedResource[];
+    updates?: ProjectedResourcePatch[];
+    deletes?: ProjectedResourceRef[];
+    emits?: ProjectedDelivery[];
+};
+export type TwinAction = {
+    id: string;
+    service: string;
+    op: TwinActionOp;
+    subject: {
+        type: string;
+        id: string;
+    };
+    occurredAt: string;
+    actor?: {
+        kind: 'agent' | 'human' | 'bot' | 'system';
+        id?: string;
+    };
+    /** Optional vendor operation name, e.g. `issue.update` or `message.send`. */
+    operation?: string;
+    /** Raw operation input (provenance); not projected — `fields`/`projection` carry the state change. */
+    input?: Record<string, unknown>;
+    /** Preconditions are evaluated against the current projected twin state before append. */
+    preconditions?: TwinActionPrecondition[];
+    fields?: SubjectFields;
+    projection?: ActionProjection;
+    revertsActionId?: string;
+    confirmsActionId?: string;
+    observedEventId?: string;
+    /** Optional machine-readable hint for how a UI/pack should construct a revert. */
+    revert?: TwinActionRevertSpec;
+    /**
+     * Request-scoped correlation id (D3 — the purpose-3 audit trail: "who reviewed the
+     * change that caused this real write"). Always present on an appended action —
+     * appendAction/appendActionIfAbsent generate one when the caller doesn't supply it —
+     * and threaded through to the push-ledger row(s) a push against this action produces
+     * (see pushLedger.ts), so an action row and its push-ledger row(s) join on this id
+     * alone, with no dependence on actionId/pushId naming conventions.
+     */
+    correlationId?: string;
+};
+export type TwinTransactionCommit = TwinAction;
+export type TwinTransactionCommitOp = TwinActionOp;
+export type TwinTransactionPrecondition = TwinActionPrecondition;
+export type TwinTransactionRevertSpec = TwinActionRevertSpec;
+export declare class TwinActionPreconditionError extends Error {
+    readonly actionId: string;
+    readonly failed: TwinActionPrecondition;
+    constructor(actionId: string, failed: TwinActionPrecondition);
+}
+export declare function appendAction(action: TwinAction, root?: string): TwinAction;
+/** Append `action` only if no action with the same id already exists — the whole
+ *  check-then-append runs under the actions lock, so it's atomic across processes (two
+ *  concurrent identical writes converge to ONE action; distinct writes both land). */
+export declare function appendActionIfAbsent(action: TwinAction, root?: string): {
+    action: TwinAction;
+    appended: boolean;
+};
+export declare function appendTransactionCommit(commit: TwinTransactionCommit, root?: string): TwinTransactionCommit;
+export declare function listActions(service: string, root?: string): TwinAction[];
+/**
+ * Project the action log over the observed mirror → current twin resources.
+ * `set` actions overlay fields (creating subjects that don't exist in the mirror);
+ * reverted and confirmed actions are skipped (confirmed facts come from the
+ * observed log instead, so they are not projected twice).
+ */
+export declare function projectResources(service: string, root?: string): TwinResource[];
+/**
+ * Confirm a local action after it was pushed to the real vendor (R18): record the
+ * confirmed fields as an OBSERVED event (origin 'external' — it's now real) and
+ * append a `confirm` action mapping the local action → that observed event id.
+ * Projection then drops the local action (the fact lives in the observed log), so
+ * the change is counted exactly once. Returns the observed event id.
+ */
+export declare function confirmAction(opts: {
+    service: string;
+    actionId: string;
+    subject: {
+        type: string;
+        id: string;
+    };
+    fields: SubjectFields;
+    occurredAt: string;
+    root?: string;
+}): {
+    observedEventId: string;
+};
+/** Local pending actions (set, not reverted, not yet confirmed) — the divergence from the mirror. */
+export declare function pendingActions(service: string, root?: string): TwinAction[];
+/**
+ * Deliveries (webhooks/events/notifications) the active transactions want fired —
+ * the `projection.emits` of pending `set` actions, in order. A twin's event layer
+ * reads these to know what to deliver; projecting state ignores emits (side effects).
+ */
+export declare function pendingEmits(service: string, root?: string): Array<{
+    actionId: string;
+    delivery: ProjectedDelivery;
+}>;
+export declare const listTransactionCommits: typeof listActions;
+export declare const pendingTransactionCommits: typeof pendingActions;

package/dist/src/actions.js

@@ -0,0 +1,201 @@
+// Transaction/action log (scorecard R18) — the semantic correction that separates
+// OBSERVED facts from LOCAL transaction commits.
+//
+// The observed-event log (`events.jsonl`) holds only what was observed upstream
+// (connector pulls) or confirmed after a push. Local simulator/fork writes do NOT
+// go there — they are transaction commits in `actions.jsonl`, projected OVER the
+// observed mirror to produce the twin's current state. Undo is a `revert` commit;
+// a push that succeeds appends a `confirm` commit mapping the local transaction
+// to the observed event it produced, which SUPPRESSES the local projection (the
+// fact is now carried by the observed log, so it must not be double-counted).
+//
+// Projection = observed mirror, then apply each `set` transaction in order,
+// skipping any transaction that was reverted or confirmed.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { buildShadowState } from "./shadow.js";
+import { appendDurable, appendEvent, twinLog, withFileLock, worldPaths } from "./storage.js";
+export class TwinActionPreconditionError extends Error {
+    actionId;
+    failed;
+    constructor(actionId, failed) {
+        super(`Twin transaction precondition failed for ${actionId}: ${failed.subject.type}:${failed.subject.id}.${failed.field} ${failed.op}`);
+        this.actionId = actionId;
+        this.failed = failed;
+        this.name = 'TwinActionPreconditionError';
+    }
+}
+function actionsPath(service, root) {
+    return join(dirname(worldPaths(service, root).events), 'actions.jsonl');
+}
+const actionsLock = (service, root) => `${actionsPath(service, root)}.lock`;
+/** Every appended action carries a correlationId — generate one when the caller
+ *  hasn't supplied it, so downstream joins (push ledger, logs) always have an id
+ *  to key on (D3). Preserves a caller-supplied id (e.g. propagated from an HTTP
+ *  request id) so a whole call chain can share one. */
+function withCorrelationId(action) {
+    return action.correlationId ? action : { ...action, correlationId: randomUUID() };
+}
+function appendActionRaw(action, root) {
+    const path = actionsPath(action.service, root);
+    mkdirSync(dirname(path), { recursive: true });
+    appendDurable(path, `${JSON.stringify(action)}\n`);
+    twinLog('action.append', { service: action.service, id: action.id, op: action.op, correlationId: action.correlationId });
+}
+export function appendAction(action, root) {
+    const stamped = withCorrelationId(action);
+    assertPreconditions(stamped, root);
+    // Cross-process line-atomic append (same lock the dedup path uses, so writes from a
+    // backend + a browser proxy sharing one twin can't interleave or race a check-then-append).
+    withFileLock(actionsLock(stamped.service, root), () => appendActionRaw(stamped, root));
+    return stamped;
+}
+/** Append `action` only if no action with the same id already exists — the whole
+ *  check-then-append runs under the actions lock, so it's atomic across processes (two
+ *  concurrent identical writes converge to ONE action; distinct writes both land). */
+export function appendActionIfAbsent(action, root) {
+    const stamped = withCorrelationId(action);
+    assertPreconditions(stamped, root);
+    return withFileLock(actionsLock(stamped.service, root), () => {
+        const exists = listActions(stamped.service, root).some((a) => a.id === stamped.id);
+        if (!exists)
+            appendActionRaw(stamped, root);
+        return { action: stamped, appended: !exists };
+    });
+}
+export function appendTransactionCommit(commit, root) {
+    return appendAction(commit, root);
+}
+export function listActions(service, root) {
+    const path = actionsPath(service, root);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf8')
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+const META = new Set(['id', 'type', 'updatedAt']);
+function projectedField(resource, field) {
+    if (!resource)
+        return undefined;
+    if (field === 'id' || field === 'type' || field === 'updatedAt')
+        return resource[field];
+    return resource[field];
+}
+function assertPreconditions(action, root) {
+    if (!action.preconditions?.length)
+        return;
+    const resources = projectResources(action.service, root);
+    for (const precondition of action.preconditions) {
+        const resource = resources.find((r) => r.type === precondition.subject.type && r.id === precondition.subject.id);
+        const actual = projectedField(resource, precondition.field);
+        const passes = precondition.op === 'exists' ? actual !== undefined
+            : precondition.op === 'not_exists' ? actual === undefined
+                : precondition.op === 'eq' || precondition.op === 'version_eq' ? Object.is(actual, precondition.value)
+                    : precondition.op === 'neq' ? !Object.is(actual, precondition.value)
+                        : false;
+        if (!passes)
+            throw new TwinActionPreconditionError(action.id, precondition);
+    }
+}
+/**
+ * Project the action log over the observed mirror → current twin resources.
+ * `set` actions overlay fields (creating subjects that don't exist in the mirror);
+ * reverted and confirmed actions are skipped (confirmed facts come from the
+ * observed log instead, so they are not projected twice).
+ */
+export function projectResources(service, root) {
+    // base: observed mirror (events.jsonl only)
+    const mirror = buildShadowState(service, () => null, root);
+    const subjects = new Map();
+    for (const s of Object.values(mirror.subjects)) {
+        subjects.set(`${s.subject.type}:${s.subject.id}`, { type: s.subject.type, id: s.subject.id, updatedAt: s.updatedAt, fields: { ...s.fields } });
+    }
+    const actions = listActions(service, root);
+    const reverted = new Set();
+    const confirmed = new Set();
+    for (const a of actions) {
+        if (a.op === 'revert' && a.revertsActionId)
+            reverted.add(a.revertsActionId);
+        if (a.op === 'confirm' && a.confirmsActionId)
+            confirmed.add(a.confirmsActionId);
+    }
+    const overlay = (type, id, fields, at) => {
+        const key = `${type}:${id}`;
+        const existing = subjects.get(key) ?? { type, id, updatedAt: at, fields: {} };
+        subjects.set(key, { ...existing, updatedAt: at, fields: { ...existing.fields, ...fields } });
+    };
+    for (const a of actions) {
+        if (a.op !== 'set')
+            continue;
+        if (reverted.has(a.id) || confirmed.has(a.id))
+            continue; // suppressed
+        // single-resource shorthand: overlay `fields` on the action's own subject.
+        if (a.fields)
+            overlay(a.subject.type, a.subject.id, a.fields, a.occurredAt);
+        // richer multi-resource transaction projection (applied in order; deletes remove).
+        if (a.projection) {
+            for (const c of a.projection.creates ?? [])
+                overlay(c.type, c.id, c.fields, a.occurredAt);
+            for (const u of a.projection.updates ?? [])
+                overlay(u.type, u.id, u.fields, a.occurredAt);
+            for (const d of a.projection.deletes ?? [])
+                subjects.delete(`${d.type}:${d.id}`);
+        }
+    }
+    return [...subjects.values()].map((s) => {
+        const out = { id: s.id, type: s.type, updatedAt: s.updatedAt };
+        for (const [k, v] of Object.entries(s.fields))
+            if (!META.has(k))
+                out[k] = v;
+        return out;
+    });
+}
+/**
+ * Confirm a local action after it was pushed to the real vendor (R18): record the
+ * confirmed fields as an OBSERVED event (origin 'external' — it's now real) and
+ * append a `confirm` action mapping the local action → that observed event id.
+ * Projection then drops the local action (the fact lives in the observed log), so
+ * the change is counted exactly once. Returns the observed event id.
+ */
+export function confirmAction(opts) {
+    const observedEventId = `confirmed:${opts.service}:${opts.subject.type}:${opts.subject.id}:${opts.actionId}`;
+    appendEvent({
+        id: observedEventId,
+        service: opts.service,
+        type: `${opts.service}.${opts.subject.type}.delta`,
+        schemaVersion: 1,
+        idempotencyKey: observedEventId,
+        occurredAt: opts.occurredAt,
+        observedAt: opts.occurredAt,
+        origin: 'external', // confirmed by the real vendor → an observed fact
+        subject: opts.subject,
+        data: { changed: Object.fromEntries(Object.entries(opts.fields).map(([k, v]) => [k, { after: v }])) },
+    }, opts.root);
+    appendAction({ id: `confirm:${opts.actionId}`, service: opts.service, op: 'confirm', subject: opts.subject, occurredAt: opts.occurredAt, confirmsActionId: opts.actionId, observedEventId }, opts.root);
+    return { observedEventId };
+}
+/** Local pending actions (set, not reverted, not yet confirmed) — the divergence from the mirror. */
+export function pendingActions(service, root) {
+    const actions = listActions(service, root);
+    const reverted = new Set(actions.filter((a) => a.op === 'revert').map((a) => a.revertsActionId));
+    const confirmed = new Set(actions.filter((a) => a.op === 'confirm').map((a) => a.confirmsActionId));
+    return actions.filter((a) => a.op === 'set' && !reverted.has(a.id) && !confirmed.has(a.id));
+}
+/**
+ * Deliveries (webhooks/events/notifications) the active transactions want fired —
+ * the `projection.emits` of pending `set` actions, in order. A twin's event layer
+ * reads these to know what to deliver; projecting state ignores emits (side effects).
+ */
+export function pendingEmits(service, root) {
+    const out = [];
+    for (const a of pendingActions(service, root)) {
+        for (const d of a.projection?.emits ?? [])
+            out.push({ actionId: a.id, delivery: d });
+    }
+    return out;
+}
+export const listTransactionCommits = listActions;
+export const pendingTransactionCommits = pendingActions;

package/dist/src/args.d.ts

@@ -0,0 +1,3 @@
+/** Value of `--name <value>`; fallback when the flag is absent or has no value. */
+export declare function optionValue(args: string[], name: string, fallback?: string): string;
+export declare function hasFlag(args: string[], name: string): boolean;

package/dist/src/args.js

@@ -0,0 +1,12 @@
+// Shared CLI argument helpers for world scripts and tools. Scripts kept
+// growing private copies of these (5 in the sync subsystem alone before this
+// file); a parsing fix that lands in one copy and not the others corrupts
+// flag handling silently.
+/** Value of `--name <value>`; fallback when the flag is absent or has no value. */
+export function optionValue(args, name, fallback = '') {
+    const index = args.indexOf(name);
+    return index >= 0 && index + 1 < args.length ? args[index + 1] : fallback;
+}
+export function hasFlag(args, name) {
+    return args.includes(name);
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};