@volter/twin 0.1.0

package/src/reconcile.ts

@@ -0,0 +1,192 @@
+// Reconciliation for twins (the twins architecture notes, the hard part).
+//
+// A fork diverges from a known base. Meanwhile the REAL service may have changed
+// too (someone edited the issue in Linear while the agent worked in the fork).
+// Reconciliation is the THREE-WAY merge that decides, per field, what the
+// converged value should be — exactly like a VCS merge:
+//
+//     base   = the value at fork time (the common ancestor)
+//     fork   = the value now in the twin (what the agent changed)
+//     real   = the value now in the real service (a fresh pull)
+//
+// This module is PURE and deterministic: it takes three resource snapshots and a
+// policy, and returns a plan (per-field decisions + conflicts). It performs NO
+// I/O and touches NO real service — applying the plan (pushing twin-wins fields
+// back to real, or pulling real-wins fields into the twin) is a separate, gated
+// step. Computing the plan safely is the foot-gun surface; we make it inspectable
+// BEFORE anything is enacted.
+import type { TwinResource } from './serve.ts';
+
+export type ReconcilePolicy = 'hub-wins' | 'twin-wins' | 'merge';
+
+// What happened to a single field across the three versions.
+export type FieldDecision = {
+  field: string;
+  base: unknown;
+  fork: unknown;
+  real: unknown;
+  // forkChanged / realChanged relative to base.
+  forkChanged: boolean;
+  realChanged: boolean;
+  // The chosen value + why. 'conflict' means both sides changed to different
+  // values and the policy could not auto-resolve (merge policy only).
+  resolution: 'unchanged' | 'take-fork' | 'take-real' | 'conflict';
+  value: unknown;
+};
+
+export type SubjectReconcile = {
+  id: string;
+  type: string;
+  // present: in which versions the subject exists.
+  inFork: boolean;
+  inReal: boolean;
+  existence: 'both' | 'fork-only' | 'real-only';
+  fields: FieldDecision[];
+  conflicts: FieldDecision[]; // subset of fields with resolution === 'conflict'
+};
+
+export type ReconcilePlan = {
+  policy: ReconcilePolicy;
+  subjects: SubjectReconcile[];
+  // Direction summaries to enact later (still gated, never auto-applied here).
+  toPush: Array<{ id: string; type: string; fields: Record<string, unknown> }>; // twin → real
+  toPull: Array<{ id: string; type: string; fields: Record<string, unknown> }>; // real → twin
+  conflictCount: number;
+};
+
+const META_FIELDS = new Set(['id', 'type', 'updatedAt']);
+
+function eq(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function dataFields(r: TwinResource | undefined): Record<string, unknown> {
+  if (!r) return {};
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(r)) if (!META_FIELDS.has(k)) out[k] = v;
+  return out;
+}
+
+function decideField(field: string, base: unknown, fork: unknown, real: unknown, policy: ReconcilePolicy): FieldDecision {
+  const forkChanged = !eq(base, fork);
+  const realChanged = !eq(base, real);
+  let resolution: FieldDecision['resolution'];
+  let value: unknown;
+
+  if (!forkChanged && !realChanged) {
+    resolution = 'unchanged';
+    value = base;
+  } else if (forkChanged && !realChanged) {
+    // only the twin changed it
+    resolution = policy === 'hub-wins' ? 'take-real' : 'take-fork';
+    value = resolution === 'take-fork' ? fork : real;
+  } else if (!forkChanged && realChanged) {
+    // only the real service changed it
+    resolution = policy === 'twin-wins' ? 'take-fork' : 'take-real';
+    value = resolution === 'take-fork' ? fork : real;
+  } else {
+    // BOTH changed (relative to base) — the genuine conflict case
+    if (eq(fork, real)) {
+      resolution = 'take-fork'; // converged independently to the same value
+      value = fork;
+    } else if (policy === 'hub-wins') {
+      resolution = 'take-real';
+      value = real;
+    } else if (policy === 'twin-wins') {
+      resolution = 'take-fork';
+      value = fork;
+    } else {
+      resolution = 'conflict'; // merge policy surfaces it; no silent pick
+      value = real; // safe default: do NOT overwrite real on an unresolved conflict
+    }
+  }
+  return { field, base, fork, real, forkChanged, realChanged, resolution, value };
+}
+
+/**
+ * Compute a three-way reconciliation plan. Inputs are resource snapshots keyed
+ * by id (base = at fork time, fork = twin now, real = fresh pull). Pure.
+ */
+export function reconcile(opts: {
+  policy: ReconcilePolicy;
+  base: TwinResource[];
+  fork: TwinResource[];
+  real: TwinResource[];
+}): ReconcilePlan {
+  const { policy } = opts;
+  const baseById = new Map(opts.base.map((r) => [r.id, r]));
+  const forkById = new Map(opts.fork.map((r) => [r.id, r]));
+  const realById = new Map(opts.real.map((r) => [r.id, r]));
+  const allIds = [...new Set([...forkById.keys(), ...realById.keys()])].sort();
+
+  const subjects: SubjectReconcile[] = [];
+  const toPush: ReconcilePlan['toPush'] = [];
+  const toPull: ReconcilePlan['toPull'] = [];
+  let conflictCount = 0;
+
+  for (const id of allIds) {
+    const baseR = baseById.get(id);
+    const forkR = forkById.get(id);
+    const realR = realById.get(id);
+    const inFork = !!forkR;
+    const inReal = !!realR;
+    const existence: SubjectReconcile['existence'] = inFork && inReal ? 'both' : inFork ? 'fork-only' : 'real-only';
+    const type = (forkR?.type ?? realR?.type ?? baseR?.type ?? 'unknown') as string;
+
+    const baseF = dataFields(baseR);
+    const forkF = dataFields(forkR);
+    const realF = dataFields(realR);
+    const fieldNames = [...new Set([...Object.keys(baseF), ...Object.keys(forkF), ...Object.keys(realF)])].sort();
+
+    const fields = fieldNames.map((f) => decideField(f, baseF[f], forkF[f], realF[f], policy));
+    const conflicts = fields.filter((d) => d.resolution === 'conflict');
+    conflictCount += conflicts.length;
+    subjects.push({ id, type, inFork, inReal, existence, fields, conflicts });
+
+    // Enactment summaries (gated; not applied here):
+    const pushFields: Record<string, unknown> = {};
+    const pullFields: Record<string, unknown> = {};
+    if (existence === 'both') {
+      // field-level convergence only makes sense when the subject is on both sides:
+      // - fields resolved 'take-fork' that differ from real → push to real.
+      // - fields resolved 'take-real' that differ from fork → pull into twin.
+      for (const d of fields) {
+        if (d.resolution === 'take-fork' && !eq(d.value, d.real)) pushFields[d.field] = d.value;
+        if (d.resolution === 'take-real' && !eq(d.value, d.fork)) pullFields[d.field] = d.value;
+      }
+    } else if (existence === 'fork-only') {
+      // present in the twin, absent in real. Under twin-wins/merge that's a
+      // create-on-real candidate; under hub-wins (real authoritative) the fork's
+      // creation is discarded — neither pushed nor pulled.
+      if (policy !== 'hub-wins') for (const [k, v] of Object.entries(forkF)) pushFields[k] = v;
+    } else {
+      // real-only: a create-in-twin candidate (pull) under every policy.
+      for (const [k, v] of Object.entries(realF)) pullFields[k] = v;
+    }
+
+    if (Object.keys(pushFields).length > 0) toPush.push({ id, type, fields: pushFields });
+    if (Object.keys(pullFields).length > 0) toPull.push({ id, type, fields: pullFields });
+  }
+
+  return { policy, subjects, toPush, toPull, conflictCount };
+}
+
+/** True when the plan can be enacted without a human decision. */
+export function isCleanlyReconcilable(plan: ReconcilePlan): boolean {
+  return plan.conflictCount === 0;
+}
+
+/**
+ * Whether enacting this plan's `toPush` requires explicit approval before
+ * `syncPush` may perform it. Nothing pushed → nothing to gate. Otherwise: any
+ * unresolved conflict anywhere in the plan requires approval (never silently
+ * applied), and so does any pushed field whose resolution is 'take-fork' while
+ * `realChanged` is true — twin-wins discarding a change that also happened on the
+ * real side, the "destructive twin-wins reconcile push" case that must not go out
+ * silently.
+ */
+export function reconcileRequiresApproval(plan: ReconcilePlan): boolean {
+  if (plan.toPush.length === 0) return false;
+  if (plan.conflictCount > 0) return true;
+  return plan.subjects.some((s) => s.fields.some((f) => f.resolution === 'take-fork' && f.realChanged));
+}

package/src/refs.ts

@@ -0,0 +1,91 @@
+// Remote refs (the twins architecture notes → "Remote Refs"): the provider-side
+// baselines a fork or push is based on. `remote/<provider>/<name>` records the last
+// CONFIRMED provider checkpoint (cursor/version/event id/observed time); a local
+// ref records which remote ref a fork was based on, so a stale-base push can be
+// rejected before any provider call. Pure file I/O over the world dir; deterministic
+// (caller supplies observedAt).
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJsonFile, worldPaths } from './storage.ts';
+
+export type WorldRemoteRef = {
+  service: string;
+  provider: string;
+  /** "main" by default; a named checkpoint otherwise. */
+  name: string;
+  eventId?: string;
+  cursor?: string;
+  providerVersion?: string;
+  observedAt: string;
+};
+
+export type WorldLocalRef = {
+  service: string;
+  /** the fork this ref belongs to. */
+  forkId: string;
+  /** the remote ref the fork is based on (provider + name + checkpoint). */
+  baseRemoteRef: WorldRemoteRef;
+  recordedAt: string;
+};
+
+function refsDir(service: string, root?: string): string {
+  return join(worldPaths(service, root).dir, 'refs');
+}
+function remoteRefPath(service: string, provider: string, name: string, root?: string): string {
+  return join(refsDir(service, root), 'remote', provider, `${name}.json`);
+}
+function localRefPath(service: string, forkId: string, root?: string): string {
+  return join(refsDir(service, root), 'local', `${forkId}.json`);
+}
+function safe(part: string): string {
+  if (!/^[A-Za-z0-9_.-]+$/.test(part)) throw new Error(`invalid ref segment: ${part}`);
+  return part;
+}
+
+/** Record/advance a provider checkpoint (e.g. after a confirmed pull). */
+export function writeRemoteRef(ref: WorldRemoteRef, root?: string): WorldRemoteRef {
+  const path = remoteRefPath(ref.service, safe(ref.provider), safe(ref.name), root);
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
+  return ref;
+}
+
+export function readRemoteRef(service: string, provider: string, name = 'main', root?: string): WorldRemoteRef | null {
+  const path = remoteRefPath(service, safe(provider), safe(name), root);
+  return existsSync(path) ? readJsonFile<WorldRemoteRef>(path) : null;
+}
+
+export function listRemoteRefs(service: string, root?: string): WorldRemoteRef[] {
+  const base = join(refsDir(service, root), 'remote');
+  if (!existsSync(base)) return [];
+  const out: WorldRemoteRef[] = [];
+  for (const provider of readdirSync(base)) {
+    const providerDir = join(base, provider);
+    for (const file of readdirSync(providerDir)) {
+      if (file.endsWith('.json')) out.push(readJsonFile<WorldRemoteRef>(join(providerDir, file)));
+    }
+  }
+  return out.sort((a, b) => (a.provider === b.provider ? a.name.localeCompare(b.name) : a.provider.localeCompare(b.provider)));
+}
+
+export function writeLocalRef(ref: WorldLocalRef, root?: string): WorldLocalRef {
+  const path = localRefPath(ref.service, safe(ref.forkId), root);
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
+  return ref;
+}
+
+export function readLocalRef(service: string, forkId: string, root?: string): WorldLocalRef | null {
+  const path = localRefPath(service, safe(forkId), root);
+  return existsSync(path) ? readJsonFile<WorldLocalRef>(path) : null;
+}
+
+/**
+ * Is a fork's base ref still current against the live remote ref? A push against a
+ * stale base must be blocked or explicitly reconciled (rebase) first.
+ */
+export function isBaseStale(local: WorldLocalRef, root?: string): boolean {
+  const current = readRemoteRef(local.service, local.baseRemoteRef.provider, local.baseRemoteRef.name, root);
+  if (!current) return false; // no live checkpoint recorded yet → cannot be stale
+  return (current.eventId ?? current.cursor ?? '') !== (local.baseRemoteRef.eventId ?? local.baseRemoteRef.cursor ?? '');
+}

package/src/schemas.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+export const WorldActorSchema = z.object({
+  id: z.string().min(1).optional(),
+  name: z.string().min(1).optional(),
+  kind: z.enum(['human', 'agent', 'bot', 'system']),
+});
+
+export const WorldSubjectSchema = z.object({
+  type: z.string().min(1),
+  id: z.string().min(1),
+});
+
+export const WorldExternalRefSchema = z.object({
+  provider: z.string().min(1),
+  id: z.string().min(1).optional(),
+  url: z.string().min(1).optional(),
+  cursor: z.string().min(1).optional(),
+  rawRef: z.string().min(1).optional(),
+});
+
+export const WorldServiceEventSchema = z.object({
+  id: z.string().min(1),
+  service: z.string().min(1),
+  type: z.string().min(1),
+  schemaVersion: z.number().int().positive(),
+  idempotencyKey: z.string().min(1),
+  occurredAt: z.string().min(1),
+  observedAt: z.string().min(1),
+  origin: z.enum(['virtual', 'external', 'agent', 'connector', 'replay', 'migration']),
+  actor: WorldActorSchema.optional(),
+  subject: WorldSubjectSchema,
+  causationId: z.string().min(1).optional(),
+  correlationId: z.string().min(1).optional(),
+  external: WorldExternalRefSchema.optional(),
+  data: z.record(z.string(), z.unknown()),
+  raw: z.record(z.string(), z.unknown()).optional(),
+});
+
+// NOTE: WorldAnnotationSchema moved to @volter/tracker/world-annotations — annotating
+// world events as sources/noise is a tracker (verification) concern, not the twin's.
+
+export const GenericWorldStateSchema = z.object({
+  version: z.literal(1),
+  service: z.string().min(1),
+  rebuiltAt: z.string().min(1),
+  eventCount: z.number().int().nonnegative(),
+  latestEventId: z.string().min(1).optional(),
+  subjects: z.record(z.string(), z.object({
+    type: z.string().min(1),
+    id: z.string().min(1),
+    latestEventId: z.string().min(1),
+    latestType: z.string().min(1),
+    updatedAt: z.string().min(1),
+  })),
+});

package/src/serve.ts

@@ -0,0 +1,120 @@
+// Twin serve layer (the twins architecture notes, increment 1): answer vendor-shaped
+// READS from the local event-sourced state — the "local twin" read path. An app
+// or agent points at this instead of the real vendor; it responds from local
+// state with the real service unreachable.
+//
+// There is ONE twin, not a set of "modes". Pulling reality, writing locally, and
+// forking are operations on the same substrate (events + local actions + the
+// projection over them), not exclusive modes — see the architecture doc, "a twin
+// is a repo". The only serve-time policy here is `readOnly`: a twin accepts local
+// writes (as actions) unless you start it read-only (a pure mirror of pulled
+// reality). Forking is a separate data operation (fork.ts), never a serve mode.
+import type { SubjectFields } from './shadow.ts';
+import { hashFieldValue } from './shadow.ts';
+import { appendActionIfAbsent, projectResources } from './actions.ts';
+import type { TwinActionPrecondition } from './actions.ts';
+
+// A subject rendered as a vendor resource: its folded current fields + identity.
+export type TwinResource = { id: string; type: string; updatedAt: string } & Record<string, unknown>;
+
+// The twin's current view = the OBSERVED mirror (events.jsonl) with the local
+// ACTION log (actions.jsonl) projected over it (R18). Observed facts and local
+// actions are kept separate; this is the single projected read model.
+export function twinResources(service: string, root?: string): TwinResource[] {
+  return projectResources(service, root);
+}
+
+// Result of a local twin write — it is an ACTION, not an egress/real write.
+export type TwinWriteResult = { status: 'performed' | 'replayed'; actionId: string };
+
+// Resolve a read request against the twin's resources. Returns the matched
+// resource(s) + an HTTP-ish status, deterministically from state.
+//   GET /                       -> { service, mode, resourceTypes, count }
+//   GET /<type>                 -> list of resources of that type
+//   GET /<type>/<id>            -> one resource (id may be url-encoded)
+export function resolveTwinRead(
+  service: string,
+  pathname: string,
+  opts: { root?: string } = {},
+): { status: number; body: unknown } {
+  const resources = twinResources(service, opts.root);
+  const parts = pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+
+  if (parts.length === 0) {
+    const types = [...new Set(resources.map((r) => r.type))].sort();
+    return { status: 200, body: { service, resourceTypes: types, count: resources.length } };
+  }
+  const type = parts[0]!;
+  const ofType = resources.filter((r) => r.type === type);
+  if (parts.length === 1) {
+    return { status: 200, body: { type, count: ofType.length, items: ofType } };
+  }
+  const id = decodeURIComponent(parts.slice(1).join('/'));
+  const found = ofType.find((r) => r.id === id);
+  if (!found) return { status: 404, body: { error: 'not_found', type, id } };
+  return { status: 200, body: found };
+}
+
+// Simulator/fork-mode write: the twin ACCEPTS a write as a LOCAL ACTION appended
+// to the action log (R18) — NOT an observed event and NOT an egress/real write.
+// State is the mirror with this action projected over it, so a subsequent read
+// returns the change. The observed event log is untouched; the real service is
+// provably untouched (no network I/O, no egress). Pushing the action to the real
+// vendor is a separate, explicit step that records egress + confirms the action.
+export async function applyTwinWrite(
+  service: string,
+  write: { operation: string; provider?: string; subjectType: string; subjectId: string; fields: SubjectFields; occurredAt?: string; actor?: { kind: 'agent' | 'human' | 'bot' | 'system'; id?: string }; preconditions?: TwinActionPrecondition[]; correlationId?: string },
+  root?: string,
+): Promise<{ result: TwinWriteResult; resource: TwinResource }> {
+  const occurredAt = write.occurredAt ?? new Date().toISOString();
+  // Idempotency: dedup a RE-ISSUED IDENTICAL write only. The key includes a hash of the write
+  // CONTENT (operation + subject + fields), not just the timestamp — so two DIFFERENT writes to
+  // the same subject in the same millisecond are BOTH kept (previously the second silently
+  // no-opped: e.g. a sprint "start" then "close" in the same ms lost the close). Check + append
+  // run atomically under the actions lock, so concurrent processes can't double-apply either.
+  const contentHash = hashFieldValue({ operation: write.operation, subjectId: write.subjectId, fields: write.fields });
+  const actionId = `twin:${service}:${write.operation}:${write.subjectId}:${occurredAt}:${contentHash}`;
+  // correlationId (D3): pass a caller-supplied request-scoped id through (e.g. propagated
+  // from an inbound HTTP request id) so it lands on the action row; appendActionIfAbsent
+  // generates one when omitted, so it's never missing.
+  const { appended } = appendActionIfAbsent(
+    { id: actionId, service, op: 'set', operation: write.operation, subject: { type: write.subjectType, id: write.subjectId }, occurredAt, ...(write.actor ? { actor: write.actor } : {}), ...(write.preconditions?.length ? { preconditions: write.preconditions } : {}), ...(write.correlationId ? { correlationId: write.correlationId } : {}), fields: write.fields },
+    root,
+  );
+  // Resolve by (type, id) — an id alone is ambiguous when two resource TYPES share it.
+  const resource = projectResources(service, root).find((r) => r.type === write.subjectType && r.id === write.subjectId)
+    ?? ({ id: write.subjectId, type: write.subjectType, updatedAt: occurredAt, ...write.fields } as TwinResource);
+  return { result: { status: appended ? 'performed' : 'replayed', actionId }, resource };
+}
+
+export function createTwinServer(options: { service: string; root?: string; port?: number; readOnly?: boolean }): { port: number; stop: () => void } {
+  const readOnly = options.readOnly ?? false;
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      const json = (status: number, body: unknown) => new Response(JSON.stringify(body, null, 2), { status, headers: { 'content-type': 'application/json' } });
+      if (request.method === 'GET') {
+        // Re-read per request so a concurrently-syncing twin serves fresh state.
+        const { status, body } = resolveTwinRead(options.service, url.pathname, { root: options.root });
+        return json(status, body);
+      }
+      // Writes are accepted as local actions unless this twin was started read-only.
+      if (readOnly) return json(405, { error: 'read_only', hint: 'this twin was started read-only; omit readOnly to accept writes' });
+      const parts = url.pathname.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+      if (parts.length < 2) return json(400, { error: 'write_needs_type_and_id', hint: 'POST /<type>/<id> with a JSON body of fields' });
+      let fields: SubjectFields;
+      try { fields = (await request.json()) as SubjectFields; } catch { return json(400, { error: 'invalid_json_body' }); }
+      const { result, resource } = await applyTwinWrite(options.service, {
+        operation: `${request.method.toLowerCase()}.${parts[0]}`,
+        subjectType: parts[0]!,
+        subjectId: decodeURIComponent(parts.slice(1).join('/')),
+        fields,
+        actor: { kind: 'agent' },
+      }, options.root);
+      return json(result.status === 'replayed' ? 200 : 201, { status: result.status, resource });
+    },
+  });
+  return { port: server.port ?? 0, stop: () => server.stop(true) };
+}

package/src/shadow.ts

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+import { isEgressEventType } from './egress.ts';
+import { appendEvent, createEvent, listEvents } from './storage.ts';
+import type { AppendEventResult, WorldServiceEvent } from './types.ts';
+
+export const DELTA_TYPE_SUFFIX = '.delta';
+
+export type SubjectFields = Record<string, unknown>;
+
+export type SubjectShadow = {
+  subject: { type: string; id: string };
+  fields: SubjectFields;
+  fieldHashes: Record<string, string>;
+  latestEventId: string;
+  updatedAt: string;
+};
+
+export type ShadowState = {
+  version: 1;
+  service: string;
+  rebuiltAt: string;
+  subjects: Record<string, SubjectShadow>;
+};
+
+/**
+ * Maps a world event to the subject fields it observes, or null when the
+ * event says nothing about remote subject state (comments, egress records, …).
+ * Extractors are provider-specific; the shadow engine is not.
+ */
+export type SubjectFieldExtractor = (event: WorldServiceEvent) => SubjectFields | null;
+
+export type FieldChange = { before: unknown; after: unknown };
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+export function hashFieldValue(value: unknown): string {
+  return createHash('sha256').update(canonicalJson(value)).digest('hex').slice(0, 16);
+}
+
+function subjectKey(subject: { type: string; id: string }): string {
+  return `${subject.type}:${subject.id}`;
+}
+
+function isDeltaEvent(event: WorldServiceEvent): boolean {
+  return event.type.endsWith(DELTA_TYPE_SUFFIX) && typeof event.data.changed === 'object';
+}
+
+function deltaAfterFields(event: WorldServiceEvent): SubjectFields {
+  const changed = event.data.changed as Record<string, FieldChange>;
+  const fields: SubjectFields = {};
+  for (const [field, change] of Object.entries(changed)) fields[field] = change.after;
+  return fields;
+}
+
+function applyFields(state: ShadowState, event: WorldServiceEvent, fields: SubjectFields): void {
+  const key = subjectKey(event.subject);
+  const existing = state.subjects[key];
+  // A late-arriving observation of OLDER provider state must not regress the
+  // shadow. Comparable occurredAt timestamps win over log append order.
+  if (existing) {
+    const incoming = Date.parse(event.occurredAt);
+    const current = Date.parse(existing.updatedAt);
+    if (Number.isFinite(incoming) && Number.isFinite(current) && incoming < current) return;
+  }
+  const target = existing ?? {
+    subject: { ...event.subject },
+    fields: {},
+    fieldHashes: {},
+    latestEventId: event.id,
+    updatedAt: event.occurredAt,
+  };
+  for (const [field, value] of Object.entries(fields)) {
+    if (value === undefined) continue;
+    target.fields[field] = value;
+    target.fieldHashes[field] = hashFieldValue(value);
+  }
+  target.latestEventId = event.id;
+  target.updatedAt = event.occurredAt || target.updatedAt;
+  state.subjects[key] = target;
+}
+
+/**
+ * Fold the service event log into per-subject materialized remote state.
+ * Delta events apply their `after` values directly; every other event goes
+ * through the extractor. The log is the source of truth — the shadow is
+ * always reproducible from a replay.
+ */
+export function buildShadowState(
+  service: string,
+  extractor: SubjectFieldExtractor,
+  root?: string,
+): ShadowState {
+  const state: ShadowState = { version: 1, service, rebuiltAt: new Date().toISOString(), subjects: {} };
+  for (const event of listEvents(service, root)) {
+    if (isEgressEventType(event.type)) continue;
+    if (isDeltaEvent(event)) {
+      applyFields(state, event, deltaAfterFields(event));
+      continue;
+    }
+    const fields = extractor(event);
+    if (fields) applyFields(state, event, fields);
+  }
+  return state;
+}
+
+/** Field-level diff of freshly observed subject fields against the shadow. */
+export function diffSubjectFields(
+  shadow: SubjectShadow | undefined,
+  observed: SubjectFields,
+): Record<string, FieldChange> {
+  const changed: Record<string, FieldChange> = {};
+  for (const [field, after] of Object.entries(observed)) {
+    if (after === undefined) continue;
+    const beforeHash = shadow?.fieldHashes[field];
+    if (beforeHash !== undefined && beforeHash === hashFieldValue(after)) continue;
+    changed[field] = { before: shadow?.fields[field], after };
+  }
+  return changed;
+}
+
+export type DeltaObservation = {
+  service: string;
+  subject: { type: string; id: string };
+  /** Freshly fetched provider-side fields for the subject. */
+  observed: SubjectFields;
+  /** Provider timestamp of the observed state when available. */
+  occurredAt?: string;
+  external?: { provider: string; id?: string; url?: string; cursor?: string };
+  actor?: { kind: 'human' | 'agent' | 'bot' | 'system'; id?: string; name?: string };
+};
+
+export type DeltaResult =
+  | { changed: false }
+  | { changed: true; event: WorldServiceEvent; changes: Record<string, FieldChange>; append: AppendEventResult };
+
+/**
+ * Compare an observed provider snapshot against the shadow and append a
+ * single delta event carrying only the changed fields. An unchanged
+ * re-observation appends nothing — this is the fix for re-snapshot noise.
+ * The delta idempotencyKey is derived from the after-state hashes, so the
+ * same observed change never appends twice.
+ */
+export function recordObservedDelta(
+  state: ShadowState,
+  observation: DeltaObservation,
+  root?: string,
+): DeltaResult {
+  const shadow = state.subjects[subjectKey(observation.subject)];
+  const changes = diffSubjectFields(shadow, observation.observed);
+  if (Object.keys(changes).length === 0) return { changed: false };
+
+  // The hash covers the provider timestamp as well as the after-state:
+  // A→B→A→B transitions revisit an after-state, and an id derived from
+  // content alone would collide with the earlier delta and make appendEvent
+  // throw (same id, different occurredAt). Re-observing the SAME provider
+  // state still dedupes — occurredAt comes from the provider, not the poll.
+  const afterHash = createHash('sha256')
+    .update(observation.occurredAt ?? '')
+    .update('\u001f')
+    .update(canonicalJson(Object.fromEntries(Object.entries(changes).map(([field, change]) => [field, change.after]))))
+    .digest('hex')
+    .slice(0, 16);
+  const type = `${observation.service}.${observation.subject.type}${DELTA_TYPE_SUFFIX}`;
+  const event = createEvent({
+    id: `${type}:${observation.subject.id}:${afterHash}`,
+    service: observation.service,
+    type,
+    idempotencyKey: `${observation.service}:delta:${observation.subject.type}:${observation.subject.id}:${afterHash}`,
+    occurredAt: observation.occurredAt ?? new Date().toISOString(),
+    origin: 'connector',
+    ...(observation.actor ? { actor: observation.actor } : {}),
+    subject: observation.subject,
+    ...(observation.external ? { external: observation.external } : {}),
+    data: {
+      changedFields: Object.keys(changes),
+      changed: changes,
+    },
+  });
+  const append = appendEvent(event, root);
+  if (append.appended) applyFields(state, append.event, deltaAfterFields(append.event));
+  return { changed: true, event: append.event, changes, append };
+}