@volter/twin 0.1.0

package/src/actions.ts

@@ -0,0 +1,285 @@
+// 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.ts';
+import type { SubjectFields } from './shadow.ts';
+import { appendDurable, appendEvent, twinLog, withFileLock, worldPaths } from './storage.ts';
+import type { WorldServiceEvent } from './types.ts';
+import type { TwinResource } from './serve.ts';
+
+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;
+};
+
+// Multi-resource transaction projection (the twins architecture notes → "Local
+// Transaction Commit Packet"). The flat single-subject `fields` overlay is the
+// common shorthand; `projection` is the richer form for a transaction that
+// atomically touches MORE THAN ONE resource (e.g. create a PR + a review), deletes
+// a resource, or emits a delivery (webhook/notification) the twin should fire.
+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[];
+  // op 'set': the local field changes to overlay on `subject` (single-resource shorthand).
+  fields?: SubjectFields;
+  // op 'set': the richer multi-resource transaction projection (optional; composes with `fields`).
+  projection?: ActionProjection;
+  // op 'revert': the prior action id being undone.
+  revertsActionId?: string;
+  // op 'confirm': the prior action id now reflected as an observed event.
+  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 class TwinActionPreconditionError extends Error {
+  constructor(readonly actionId: string, readonly failed: TwinActionPrecondition) {
+    super(`Twin transaction precondition failed for ${actionId}: ${failed.subject.type}:${failed.subject.id}.${failed.field} ${failed.op}`);
+    this.name = 'TwinActionPreconditionError';
+  }
+}
+
+function actionsPath(service: string, root?: string): string {
+  return join(dirname(worldPaths(service, root).events), 'actions.jsonl');
+}
+const actionsLock = (service: string, root?: string): string => `${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: TwinAction): TwinAction {
+  return action.correlationId ? action : { ...action, correlationId: randomUUID() };
+}
+
+function appendActionRaw(action: TwinAction, root?: string): void {
+  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: TwinAction, root?: string): TwinAction {
+  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: TwinAction, root?: string): { action: TwinAction; appended: boolean } {
+  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: TwinTransactionCommit, root?: string): TwinTransactionCommit {
+  return appendAction(commit, root);
+}
+
+export function listActions(service: string, root?: string): TwinAction[] {
+  const path = actionsPath(service, root);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as TwinAction);
+}
+
+const META = new Set(['id', 'type', 'updatedAt']);
+
+function projectedField(resource: TwinResource | undefined, field: string): unknown {
+  if (!resource) return undefined;
+  if (field === 'id' || field === 'type' || field === 'updatedAt') return resource[field];
+  return resource[field];
+}
+
+function assertPreconditions(action: TwinAction, root?: string): void {
+  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: string, root?: string): TwinResource[] {
+  // base: observed mirror (events.jsonl only)
+  const mirror = buildShadowState(service, () => null, root);
+  const subjects = new Map<string, { type: string; id: string; updatedAt: string; fields: SubjectFields }>();
+  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<string>();
+  const confirmed = new Set<string>();
+  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: string, id: string, fields: SubjectFields, at: string): void => {
+    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: Record<string, unknown> = { 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 as 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 function confirmAction(opts: {
+  service: string;
+  actionId: string;
+  subject: { type: string; id: string };
+  fields: SubjectFields;
+  occurredAt: string;
+  root?: string;
+}): { observedEventId: string } {
+  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 }])) },
+    } as unknown as WorldServiceEvent,
+    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: string, root?: string): TwinAction[] {
+  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: string, root?: string): Array<{ actionId: string; delivery: ProjectedDelivery }> {
+  const out: Array<{ actionId: string; delivery: ProjectedDelivery }> = [];
+  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/src/args.ts

@@ -0,0 +1,14 @@
+// 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: string[], name: string, fallback = ''): string {
+  const index = args.indexOf(name);
+  return index >= 0 && index + 1 < args.length ? args[index + 1]! : fallback;
+}
+
+export function hasFlag(args: string[], name: string): boolean {
+  return args.includes(name);
+}