instar 1.3.524 → 1.3.526

package/dist/core/RollbackUnmerge.d.ts

@@ -0,0 +1,134 @@
+/**
+ * RollbackUnmerge — deterministic origin-drop un-merge with no dangling references
+ * (WS2 replicated-store foundation, Component 6 / §7.4).
+ *
+ * Spec: docs/specs/multi-machine-replicated-store-foundation.md §7.4 (disabling
+ * stateSync.<store> for a peer atomically DROPS that origin's foreign namespace —
+ * a real un-merge, not a flag; the union recomputes live; the dropped streams +
+ * per-peer meta + snapshot cache are QUARANTINED-ASIDE, reversible + auditable,
+ * NEVER a destructive delete; no dangling references; a conflictId whose
+ * version-pair referenced the dropped origin auto-RESOLVES + its attention item
+ * closes), §11 (machine-local-by-design — a machine un-merges ITS OWN copy of a
+ * peer's namespace, never reaches into the peer).
+ *
+ * THE LIVE-RECOMPUTE INVARIANT (why this is a real un-merge, §7.4 step 1+3).
+ * Because records are keyed by (recordKey, origin) and the union reader computes
+ * the union LIVE from the per-origin namespaces, REMOVING an origin from the set
+ * of participating namespaces instantly removes its contribution — no rewrite of
+ * any surviving record is needed. A key whose winning value came from the dropped
+ * origin reverts to the HLC-latest among the REMAINING origins (or to "no record"
+ * if none remains). The DroppedOriginRegistry is the live exclusion set the
+ * union reader consults; the quarantine-aside is the durability/reversibility leg.
+ *
+ * QUARANTINE-ASIDE (§7.4 step 2 — NEVER a destructive delete). The dropped
+ * origin's replica streams + per-peer meta + snapshot-cache entries are RENAMED
+ * aside (rename is non-destructive: node:fs renameSync, mirroring
+ * JournalSyncApplier.quarantineReplica) into a bounded-retain ring; the ONLY
+ * actual deletion — pruning the oldest retained un-merge past the ring bound —
+ * goes through SafeFsExecutor.safeRmSync (the destructive-fs funnel + audit
+ * trail). A re-merge restores from the ring (reversibility).
+ */
+/** How many un-merge quarantine sets to retain per (store, origin) before the
+ *  oldest is pruned (mirrors JournalSyncApplier.MAX_QUARANTINE_PER_STREAM). */
+export declare const MAX_UNMERGE_RETAIN = 2;
+/** Persistent record of which (store, origin) pairs are currently un-merged. The
+ *  union reader consults this so a dropped origin is excluded LIVE — the
+ *  un-merge survives restarts. */
+export interface DroppedOriginEntry {
+    store: string;
+    origin: string;
+    droppedAt: string;
+}
+/** The durable set of un-merged (store, origin) pairs. Consulted by the union
+ *  reader's participating-namespace filter (§7.4). */
+export declare class DroppedOriginRegistry {
+    private readonly stateDir;
+    private readonly readFileSync;
+    private readonly existsSync;
+    private doc;
+    constructor(seams: {
+        stateDir: string;
+        readFileSync?: (p: string) => string;
+        existsSync?: (p: string) => boolean;
+    });
+    private docPath;
+    private load;
+    private persist;
+    /** Is (store, origin) currently un-merged (excluded from the union)? */
+    isDropped(store: string, origin: string): boolean;
+    /** The set of dropped origins for a store (for the reader's namespace filter). */
+    droppedOrigins(store: string): Set<string>;
+    add(store: string, origin: string, at: string): void;
+    remove(store: string, origin: string): void;
+    list(): DroppedOriginEntry[];
+}
+/** The seams RollbackUnmerge needs from the journal/applier (DI'd for testability). */
+export interface RollbackUnmergeSeams {
+    /** Absolute path to the peers/ replica directory
+     *  (`<stateDir>/state/coherence-journal/peers`). */
+    peersDir: () => string;
+    /** The journal kinds a store rides (so we move every replica stream for it). */
+    kindsForStore: (store: string) => string[];
+    /** Injected wall clock. */
+    now: () => Date;
+    /** Drop every snapshot-cache entry for the origin (§7.4 step 2 — the cache leg).
+     *  Wired to SnapshotCache.dropOrigin. */
+    dropSnapshotCacheForOrigin: (origin: string) => void;
+    /** Auto-resolve conflicts referencing the dropped origin (§7.4) — returns the
+     *  closed conflictIds. Wired to ConflictStore.autoResolveForDroppedOrigin. */
+    autoResolveConflicts: (origin: string) => string[];
+    /** Close an attention item for a conflictId (signal-only; idempotent). */
+    closeAttention?: (conflictId: string) => void;
+    /** Optional fs seams (tests); default node:fs. */
+    existsSync?: (p: string) => boolean;
+    readdirSync?: (p: string) => string[];
+    renameSync?: (from: string, to: string) => void;
+    /** Optional structured logger (default no-op). */
+    log?: (event: string, detail: Record<string, unknown>) => void;
+}
+/** Result of an un-merge (§7.4) — auditable. */
+export interface UnmergeResult {
+    store: string;
+    origin: string;
+    /** Replica stream files quarantined-aside. */
+    movedStreams: number;
+    /** Per-peer meta files quarantined-aside. */
+    movedMeta: number;
+    /** Conflict ids auto-resolved because they referenced the dropped origin. */
+    closedConflicts: string[];
+    at: string;
+}
+/**
+ * RollbackUnmerge — drops a (store, origin) from the union deterministically
+ * (§7.4). The order matters:
+ *  1. Register the drop in DroppedOriginRegistry FIRST — the union recomputes
+ *     live, so from this instant every read excludes the origin (no dangling refs).
+ *  2. Quarantine-aside the replica streams + per-peer meta + snapshot cache
+ *     (rename + bounded-retain; reversible, auditable; the prune leg through
+ *     SafeFsExecutor).
+ *  3. Auto-resolve every conflict that referenced the dropped origin + close its
+ *     attention item.
+ * Reversible: reMerge() restores the registry entry + the most-recent quarantined
+ * streams.
+ */
+export declare class RollbackUnmerge {
+    private readonly registry;
+    private readonly seams;
+    private readonly existsSync;
+    private readonly readdirSync;
+    private readonly renameSync;
+    private readonly log;
+    constructor(registry: DroppedOriginRegistry, seams: RollbackUnmergeSeams);
+    /** Un-merge (store, origin) — §7.4. Idempotent: a re-call after the drop is a
+     *  no-op for the registry but still re-attempts any leftover quarantine. */
+    unmergeOrigin(store: string, origin: string): UnmergeResult;
+    /** Re-merge (reversibility, §7.4): remove the drop + restore the MOST RECENT
+     *  quarantined streams/meta for (store, origin). Returns the count restored. */
+    reMerge(store: string, origin: string): {
+        restored: number;
+    };
+    /** Prune retained un-merge sets past MAX_UNMERGE_RETAIN per base (the ONLY
+     *  destructive leg — through SafeFsExecutor, audited). */
+    private pruneRetained;
+}
+//# sourceMappingURL=RollbackUnmerge.d.ts.map

package/dist/core/RollbackUnmerge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RollbackUnmerge.d.ts","sourceRoot":"","sources":["../../src/core/RollbackUnmerge.ts"],"names":[],"mappings":"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"}

package/dist/core/RollbackUnmerge.js

@@ -0,0 +1,286 @@
+/**
+ * RollbackUnmerge — deterministic origin-drop un-merge with no dangling references
+ * (WS2 replicated-store foundation, Component 6 / §7.4).
+ *
+ * Spec: docs/specs/multi-machine-replicated-store-foundation.md §7.4 (disabling
+ * stateSync.<store> for a peer atomically DROPS that origin's foreign namespace —
+ * a real un-merge, not a flag; the union recomputes live; the dropped streams +
+ * per-peer meta + snapshot cache are QUARANTINED-ASIDE, reversible + auditable,
+ * NEVER a destructive delete; no dangling references; a conflictId whose
+ * version-pair referenced the dropped origin auto-RESOLVES + its attention item
+ * closes), §11 (machine-local-by-design — a machine un-merges ITS OWN copy of a
+ * peer's namespace, never reaches into the peer).
+ *
+ * THE LIVE-RECOMPUTE INVARIANT (why this is a real un-merge, §7.4 step 1+3).
+ * Because records are keyed by (recordKey, origin) and the union reader computes
+ * the union LIVE from the per-origin namespaces, REMOVING an origin from the set
+ * of participating namespaces instantly removes its contribution — no rewrite of
+ * any surviving record is needed. A key whose winning value came from the dropped
+ * origin reverts to the HLC-latest among the REMAINING origins (or to "no record"
+ * if none remains). The DroppedOriginRegistry is the live exclusion set the
+ * union reader consults; the quarantine-aside is the durability/reversibility leg.
+ *
+ * QUARANTINE-ASIDE (§7.4 step 2 — NEVER a destructive delete). The dropped
+ * origin's replica streams + per-peer meta + snapshot-cache entries are RENAMED
+ * aside (rename is non-destructive: node:fs renameSync, mirroring
+ * JournalSyncApplier.quarantineReplica) into a bounded-retain ring; the ONLY
+ * actual deletion — pruning the oldest retained un-merge past the ring bound —
+ * goes through SafeFsExecutor.safeRmSync (the destructive-fs funnel + audit
+ * trail). A re-merge restores from the ring (reversibility).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+import { sanitizeMachineId } from './CoherenceJournal.js';
+/** How many un-merge quarantine sets to retain per (store, origin) before the
+ *  oldest is pruned (mirrors JournalSyncApplier.MAX_QUARANTINE_PER_STREAM). */
+export const MAX_UNMERGE_RETAIN = 2;
+/** The durable set of un-merged (store, origin) pairs. Consulted by the union
+ *  reader's participating-namespace filter (§7.4). */
+export class DroppedOriginRegistry {
+    stateDir;
+    readFileSync;
+    existsSync;
+    doc;
+    constructor(seams) {
+        this.stateDir = seams.stateDir;
+        this.readFileSync = seams.readFileSync ?? ((p) => fs.readFileSync(p, 'utf-8'));
+        this.existsSync = seams.existsSync ?? ((p) => fs.existsSync(p));
+        this.doc = this.load();
+    }
+    docPath() {
+        return path.join(this.stateDir, 'state', 'state-sync', 'dropped-origins.json');
+    }
+    load() {
+        const p = this.docPath();
+        if (!this.existsSync(p))
+            return { version: 1, dropped: [] };
+        try {
+            const raw = JSON.parse(this.readFileSync(p));
+            const dropped = Array.isArray(raw.dropped)
+                ? raw.dropped.filter((d) => !!d && typeof d.store === 'string' && typeof d.origin === 'string')
+                : [];
+            return { version: 1, dropped };
+        }
+        catch {
+            // @silent-fallback-ok: a corrupt dropped-origins file degrades to "nothing
+            // dropped" — the CONSERVATIVE direction is to FAIL CLOSED (treat a corrupt
+            // un-merge ledger as no un-merge ⇒ the origin participates again). That is
+            // safe: a stale-but-readable peer namespace re-joining the union is a normal
+            // re-merge, never data loss; the operator re-issues the un-merge if needed.
+            return { version: 1, dropped: [] };
+        }
+    }
+    persist() {
+        SafeFsExecutor.atomicWriteJsonSync(this.docPath(), this.doc, { operation: 'dropped-origin-registry:persist' });
+    }
+    /** Is (store, origin) currently un-merged (excluded from the union)? */
+    isDropped(store, origin) {
+        return this.doc.dropped.some((d) => d.store === store && d.origin === origin);
+    }
+    /** The set of dropped origins for a store (for the reader's namespace filter). */
+    droppedOrigins(store) {
+        return new Set(this.doc.dropped.filter((d) => d.store === store).map((d) => d.origin));
+    }
+    add(store, origin, at) {
+        if (this.isDropped(store, origin))
+            return;
+        this.doc.dropped.push({ store, origin, droppedAt: at });
+        this.persist();
+    }
+    remove(store, origin) {
+        const before = this.doc.dropped.length;
+        this.doc.dropped = this.doc.dropped.filter((d) => !(d.store === store && d.origin === origin));
+        if (this.doc.dropped.length !== before)
+            this.persist();
+    }
+    list() {
+        return [...this.doc.dropped];
+    }
+}
+/**
+ * RollbackUnmerge — drops a (store, origin) from the union deterministically
+ * (§7.4). The order matters:
+ *  1. Register the drop in DroppedOriginRegistry FIRST — the union recomputes
+ *     live, so from this instant every read excludes the origin (no dangling refs).
+ *  2. Quarantine-aside the replica streams + per-peer meta + snapshot cache
+ *     (rename + bounded-retain; reversible, auditable; the prune leg through
+ *     SafeFsExecutor).
+ *  3. Auto-resolve every conflict that referenced the dropped origin + close its
+ *     attention item.
+ * Reversible: reMerge() restores the registry entry + the most-recent quarantined
+ * streams.
+ */
+export class RollbackUnmerge {
+    registry;
+    seams;
+    existsSync;
+    readdirSync;
+    renameSync;
+    log;
+    constructor(registry, seams) {
+        this.registry = registry;
+        this.seams = seams;
+        this.existsSync = seams.existsSync ?? ((p) => fs.existsSync(p));
+        this.readdirSync = seams.readdirSync ?? ((p) => fs.readdirSync(p));
+        this.renameSync = seams.renameSync ?? ((from, to) => fs.renameSync(from, to));
+        this.log = seams.log ?? (() => { });
+    }
+    /** Un-merge (store, origin) — §7.4. Idempotent: a re-call after the drop is a
+     *  no-op for the registry but still re-attempts any leftover quarantine. */
+    unmergeOrigin(store, origin) {
+        const at = this.seams.now().toISOString();
+        // (1) Register the drop FIRST — the live union excludes the origin instantly.
+        this.registry.add(store, origin, at);
+        const stamp = this.seams.now().getTime();
+        const peers = this.seams.peersDir();
+        const safe = sanitizeMachineId(origin);
+        let movedStreams = 0;
+        let movedMeta = 0;
+        if (this.existsSync(peers)) {
+            let names = [];
+            try {
+                names = this.readdirSync(peers);
+            }
+            catch {
+                names = [];
+            }
+            const kinds = new Set(this.seams.kindsForStore(store));
+            for (const name of names) {
+                // Replica stream for this origin + one of the store's kinds:
+                //   <safe>.<kind>.jsonl   (NOT a .quarantine. or numbered-archive file)
+                const streamMatch = /^(.+)\.([^.]+)\.jsonl$/.exec(name);
+                if (streamMatch && streamMatch[1] === safe && kinds.has(streamMatch[2]) && !name.includes('.quarantine.')) {
+                    const from = path.join(peers, name);
+                    const to = path.join(peers, `${name}.unmerge.${stamp}`);
+                    try {
+                        this.renameSync(from, to);
+                        movedStreams++;
+                    }
+                    catch (e) {
+                        this.log('unmerge-rename-failed', { name, error: e?.message });
+                    }
+                    continue;
+                }
+                // Per-peer meta for this origin: <safe>.meta.json
+                if (name === `${safe}.meta.json`) {
+                    const from = path.join(peers, name);
+                    const to = path.join(peers, `${name}.unmerge.${stamp}`);
+                    try {
+                        this.renameSync(from, to);
+                        movedMeta++;
+                    }
+                    catch (e) {
+                        this.log('unmerge-meta-rename-failed', { name, error: e?.message });
+                    }
+                }
+            }
+            this.pruneRetained(peers, safe);
+        }
+        // (2 cont.) drop the snapshot-cache entries for the origin.
+        try {
+            this.seams.dropSnapshotCacheForOrigin(origin);
+        }
+        catch (e) {
+            this.log('unmerge-cache-drop-failed', { origin, error: e?.message });
+        }
+        // (3) Auto-resolve conflicts referencing the dropped origin + close attention.
+        let closedConflicts = [];
+        try {
+            closedConflicts = this.seams.autoResolveConflicts(origin);
+            for (const id of closedConflicts)
+                this.seams.closeAttention?.(id);
+        }
+        catch (e) {
+            this.log('unmerge-conflict-resolve-failed', { origin, error: e?.message });
+        }
+        this.log('unmerge', { store, origin, movedStreams, movedMeta, closedConflicts: closedConflicts.length });
+        return { store, origin, movedStreams, movedMeta, closedConflicts, at };
+    }
+    /** Re-merge (reversibility, §7.4): remove the drop + restore the MOST RECENT
+     *  quarantined streams/meta for (store, origin). Returns the count restored. */
+    reMerge(store, origin) {
+        this.registry.remove(store, origin);
+        const peers = this.seams.peersDir();
+        if (!this.existsSync(peers))
+            return { restored: 0 };
+        const safe = sanitizeMachineId(origin);
+        let names = [];
+        try {
+            names = this.readdirSync(peers);
+        }
+        catch {
+            return { restored: 0 };
+        }
+        // Group quarantined files by their base name; restore the newest stamp.
+        const re = new RegExp(`^(${escapeRegExp(safe)}\\..+)\\.unmerge\\.(\\d+)$`);
+        const byBase = new Map();
+        for (const name of names) {
+            const m = re.exec(name);
+            if (!m)
+                continue;
+            const base = m[1];
+            const stamp = Number(m[2]);
+            const prev = byBase.get(base);
+            if (!prev || stamp > prev.stamp)
+                byBase.set(base, { stamp, file: name });
+        }
+        let restored = 0;
+        for (const [base, { file }] of byBase) {
+            // Only restore if the live file isn't already present (a re-merge after a
+            // fresh tail must not clobber newer data — leave the quarantine as audit).
+            const liveTarget = path.join(peers, base);
+            if (this.existsSync(liveTarget))
+                continue;
+            try {
+                this.renameSync(path.join(peers, file), liveTarget);
+                restored++;
+            }
+            catch (e) {
+                this.log('remerge-restore-failed', { file, error: e?.message });
+            }
+        }
+        this.log('remerge', { store, origin, restored });
+        return { restored };
+    }
+    /** Prune retained un-merge sets past MAX_UNMERGE_RETAIN per base (the ONLY
+     *  destructive leg — through SafeFsExecutor, audited). */
+    pruneRetained(peers, safe) {
+        let names = [];
+        try {
+            names = this.readdirSync(peers);
+        }
+        catch {
+            return;
+        }
+        const re = new RegExp(`^(${escapeRegExp(safe)}\\..+)\\.unmerge\\.(\\d+)$`);
+        const byBase = new Map();
+        for (const name of names) {
+            const m = re.exec(name);
+            if (!m)
+                continue;
+            const base = m[1];
+            const arr = byBase.get(base) ?? [];
+            arr.push({ stamp: Number(m[2]), name });
+            byBase.set(base, arr);
+        }
+        for (const arr of byBase.values()) {
+            if (arr.length <= MAX_UNMERGE_RETAIN)
+                continue;
+            arr.sort((a, b) => a.stamp - b.stamp); // oldest first
+            const drop = arr.slice(0, arr.length - MAX_UNMERGE_RETAIN);
+            for (const d of drop) {
+                try {
+                    SafeFsExecutor.safeRmSync(path.join(peers, d.name), { force: true, operation: 'rollback-unmerge:prune-retained' });
+                }
+                catch (e) {
+                    this.log('unmerge-prune-failed', { name: d.name, error: e?.message });
+                }
+            }
+        }
+    }
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=RollbackUnmerge.js.map

package/dist/core/RollbackUnmerge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RollbackUnmerge.js","sourceRoot":"","sources":["../../src/core/RollbackUnmerge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;+EAC+E;AAC/E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAgBpC;sDACsD;AACtD,MAAM,OAAO,qBAAqB;IACf,QAAQ,CAAS;IACjB,YAAY,CAAwB;IACpC,UAAU,CAAyB;IAC5C,GAAG,CAAa;IAExB,YAAY,KAIX;QACC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/E,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAEO,OAAO;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,sBAAsB,CAAC,CAAC;IACjF,CAAC;IAEO,IAAI;QACV,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAwB,CAAC;YACpE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;gBACxC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAA2B,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,OAAQ,CAAwB,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAQ,CAAwB,CAAC,MAAM,KAAK,QAAQ,CAAC;gBACxK,CAAC,CAAC,EAAE,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;YAC3E,2EAA2E;YAC3E,2EAA2E;YAC3E,6EAA6E;YAC7E,4EAA4E;YAC5E,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IAEO,OAAO;QACb,cAAc,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,iCAAiC,EAAE,CAAC,CAAC;IACjH,CAAC;IAED,wEAAwE;IACxE,SAAS,CAAC,KAAa,EAAE,MAAc;QACrC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAChF,CAAC;IAED,kFAAkF;IAClF,cAAc,CAAC,KAAa;QAC1B,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACzF,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,MAAc,EAAE,EAAU;QAC3C,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,OAAO;QAC1C,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,MAAc;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;QACvC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC;QAC/F,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM;YAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACzD,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;CACF;AAwCD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAe;IACT,QAAQ,CAAwB;IAChC,KAAK,CAAuB;IAC5B,UAAU,CAAyB;IACnC,WAAW,CAA0B;IACrC,UAAU,CAAqC;IAC/C,GAAG,CAA2D;IAE/E,YAAY,QAA+B,EAAE,KAA2B;QACtE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAa,CAAC,CAAC;QAC/E,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;QAC9E,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACrC,CAAC;IAED;gFAC4E;IAC5E,aAAa,CAAC,KAAa,EAAE,MAAc;QACzC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,8EAA8E;QAC9E,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAErC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,IAAI,KAAK,GAAa,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;YAAC,MAAM,CAAC;gBACP,KAAK,GAAG,EAAE,CAAC;YACb,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;YACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,6DAA6D;gBAC7D,wEAAwE;gBACxE,MAAM,WAAW,GAAG,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACxD,IAAI,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;oBAC1G,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;oBACpC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,YAAY,KAAK,EAAE,CAAC,CAAC;oBACxD,IAAI,CAAC;wBACH,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;wBAC1B,YAAY,EAAE,CAAC;oBACjB,CAAC;oBAAC,OAAO,CAAC,EAAE,CAAC;wBACX,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAG,CAAW,EAAE,OAAO,EAAE,CAAC,CAAC;oBAC5E,CAAC;oBACD,SAAS;gBACX,CAAC;gBACD,kDAAkD;gBAClD,IAAI,IAAI,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;oBACjC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;oBACpC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,YAAY,KAAK,EAAE,CAAC,CAAC;oBACxD,IAAI,CAAC;wBACH,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;wBAC1B,SAAS,EAAE,CAAC;oBACd,CAAC;oBAAC,OAAO,CAAC,EAAE,CAAC;wBACX,IAAI,CAAC,GAAG,CAAC,4BAA4B,EAAE,EAAE,IAAI,EAAE,KAAK,EAAG,CAAW,EAAE,OAAO,EAAE,CAAC,CAAC;oBACjF,CAAC;gBACH,CAAC;YACH,CAAC;YACD,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;QAED,4DAA4D;QAC5D,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,CAAC,2BAA2B,EAAE,EAAE,MAAM,EAAE,KAAK,EAAG,CAAW,EAAE,OAAO,EAAE,CAAC,CAAC;QAClF,CAAC;QAED,+EAA+E;QAC/E,IAAI,eAAe,GAAa,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;YAC1D,KAAK,MAAM,EAAE,IAAI,eAAe;gBAAE,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,CAAC,iCAAiC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAG,CAAW,EAAE,OAAO,EAAE,CAAC,CAAC;QACxF,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;QACzG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IACzE,CAAC;IAED;oFACgF;IAChF,OAAO,CAAC,KAAa,EAAE,MAAc;QACnC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,KAAK,GAAa,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACzB,CAAC;QACD,wEAAwE;QACxE,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2C,CAAC;QAClE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK;gBAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;YACtC,0EAA0E;YAC1E,2EAA2E;YAC3E,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC1C,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;gBAAE,SAAS;YAC1C,IAAI,CAAC;gBACH,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;gBACpD,QAAQ,EAAE,CAAC;YACb,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,IAAI,CAAC,GAAG,CAAC,wBAAwB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAG,CAAW,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjD,OAAO,EAAE,QAAQ,EAAE,CAAC;IACtB,CAAC;IAED;8DAC0D;IAClD,aAAa,CAAC,KAAa,EAAE,IAAY;QAC/C,IAAI,KAAK,GAAa,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6C,CAAC;QACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAClB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACnC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YACxC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACxB,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAClC,IAAI,GAAG,CAAC,MAAM,IAAI,kBAAkB;gBAAE,SAAS;YAC/C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe;YACtD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC;YAC3D,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;gBACrB,IAAI,CAAC;oBACH,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,iCAAiC,EAAE,CAAC,CAAC;gBACrH,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAG,CAAW,EAAE,OAAO,EAAE,CAAC,CAAC;gBACnF,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}

package/dist/core/UnionReader.d.ts

@@ -0,0 +1,161 @@
+/**
+ * UnionReader — the no-clobber union merge rule + the SOUND last-writer-witness
+ * concurrency detector (WS2 replicated-store foundation, Component 6 / build-order
+ * step 4, §7.2).
+ *
+ * Spec: docs/specs/multi-machine-replicated-store-foundation.md §7.2 (the union
+ * merge rule + the concurrency detector that closes BLOCKER-4), §9 (N-machine
+ * convergence — a version SET, never N-choose-2 pairwise conflicts), §12 #5 (the
+ * adversarial-clock err-direction invariant), §14 (the provable err-toward-flag
+ * decision).
+ *
+ * PURE LOGIC. Imports ONLY the HLC primitive + node:crypto (for the stable
+ * conflictId hash). No fs, no Date, no network. Every function is a pure function
+ * of its inputs — so the load-bearing BLOCKER-4 detector is unit-testable against
+ * an adversarial clock layout (§12 #5).
+ *
+ * THE BLOCKER-4 PRIMITIVE (the load-bearing reason this module exists). Plain
+ * `HybridLogicalClock.compare` is a TOTAL order: it NEVER returns "concurrent",
+ * so it is UNSOUND as a concurrency test in BOTH directions — it over-flags
+ * sequential edits AND silently HLC-resolves (clobbers) a genuinely concurrent
+ * pair. We never use `compare(w2.hlc, w1.hlc)` to decide concurrency. Instead we
+ * use the **last-writer-witness**: a record carries `observed` = the HLC the
+ * author had ALREADY merged for THIS recordKey before writing. W2 is
+ * sequential-after W1 IFF `compare(w2.observed, w1.hlc) >= 0` (W2's author
+ * provably saw ≥ W1). A missing/below witness CANNOT prove W2 saw W1 ⇒ FLAG.
+ * The only path to "sequential" is a POSITIVE witness — the error direction is
+ * always toward flag, never toward silent clobber.
+ */
+import { type HlcTimestamp } from './HybridLogicalClock.js';
+import type { ReplicatedEnvelope } from './ReplicatedRecordEnvelope.js';
+/**
+ * A store's impact tier governs the CONCURRENT-edit behavior (§7.2):
+ *  - `high` (preferences, relationships): APPEND-BOTH-AND-FLAG — both versions
+ *    preserved, ONE deduped conflict, never a silent overwrite.
+ *  - `low` (scores, manifests): field-level HLC-wins WITH a divergence flag —
+ *    the latest HLC wins but the overwrite is FLAGGED, never silent.
+ * A store declares its tier at registration; the union reader looks it up per
+ * read. There is no third "silent" tier by construction — every concurrent
+ * resolution is surfaced.
+ */
+export type ImpactTier = 'high' | 'low';
+/**
+ * One origin's current record for a recordKey, as the union reader sees it. The
+ * `envelope` carries the load-bearing `hlc` (the total order), `op` (put/delete
+ * tombstone), `origin` (author machine id — preserved end-to-end so rollback is
+ * a real un-merge, §7.1), and the `observed` witness (§7.2). `data` is the
+ * store-specific portion (envelope fields stripped).
+ */
+export interface OriginRecord {
+    origin: string;
+    envelope: ReplicatedEnvelope;
+    data: Record<string, unknown>;
+}
+/** The verdict for a PAIR of records on the same recordKey from different origins. */
+export type WitnessVerdict = 'sequential-after' | 'concurrent';
+/**
+ * Classify a PAIR (w1, w2) on the SAME recordKey from DIFFERENT origins (§7.2).
+ *
+ * Returns `'sequential-after'` ONLY when w2 provably saw w1 — i.e. w2 carries an
+ * `observed` witness AND `compare(w2.observed, w1.hlc) >= 0` (w2's author had
+ * already merged w1's version-or-later before writing). EVERY other case is
+ * `'concurrent'` ⇒ FLAG:
+ *   - w2.observed absent → cannot prove w2 saw w1 → concurrent.
+ *   - w2.observed below w1.hlc → w2's author had NOT yet seen w1 → concurrent.
+ *
+ * PROVABLE err-toward-flag (§7.2 / §12 #5): a clock arranged to make w1/w2
+ * `compare` cleanly (one appears strictly later by wall clock) CANNOT make
+ * `observed >= the-other.hlc` true unless the author genuinely merged it first.
+ * The WITNESS, not the wall clock, decides — and the error is always toward flag.
+ *
+ * This function deliberately NEVER consults `compare(w1.hlc, w2.hlc)` to decide
+ * concurrency — that scalar comparison is the unsound test §7.2 replaces.
+ */
+export declare function classifyPair(w1: ReplicatedEnvelope, w2: ReplicatedEnvelope): WitnessVerdict;
+/**
+ * Is the SET of distinct-origin records for one recordKey mutually sequential
+ * (i.e. a clean linear edit history with a single defensible winner), or are at
+ * least two of them concurrent (⇒ FLAG)? Returns `{ concurrent: false, winner }`
+ * for a clean chain (the HLC-max record whose author witness-chains over the
+ * others), or `{ concurrent: true, versions }` for the version SET to preserve.
+ *
+ * N-machine correctness (§9): N concurrent edits to one key produce ONE conflict
+ * with all N in the version set — NOT N-choose-2 pairwise conflicts. We compute
+ * the HLC-max candidate, then verify it is sequential-after EVERY other origin's
+ * record (its author provably saw them all). If any other origin is concurrent
+ * with the candidate, the whole set is concurrent.
+ *
+ * Err-toward-flag is structural: the candidate is "the winner" ONLY when it
+ * witness-dominates every peer; one missing/below witness collapses the verdict
+ * to concurrent.
+ */
+export declare function classifyOriginSet(records: OriginRecord[]): {
+    concurrent: false;
+    winner: OriginRecord;
+} | {
+    concurrent: true;
+    versions: OriginRecord[];
+};
+/**
+ * A stable, deterministic conflict id = `hash(recordKey, sorted version-set)`
+ * (§7.2). Idempotent on `(recordKey, version-set)`: re-discovering the SAME
+ * unresolved conflict yields the SAME id, so append-both never appends a third
+ * copy and the attention surface dedupes on it. The version set is sorted by HLC
+ * key first so the id is independent of origin iteration order (N-machine safe).
+ */
+export declare function conflictId(recordKey: string, versions: HlcTimestamp[]): string;
+/**
+ * The per-recordKey union result (§7.2):
+ *  - `value` — the resolved winning record, or null when the key resolves to "no
+ *    record" (every origin's latest is a delete tombstone, or there are no
+ *    origins). For a HIGH-impact unresolved conflict `value` is null (neither
+ *    version clobbers the other — both are preserved in `conflict.versions` for
+ *    the operator to resolve). For a LOW-impact divergence the HLC-winner is the
+ *    `value` and `divergenceFlag` is set.
+ *  - `conflict` — a ConflictRecord when a HIGH-impact concurrent divergence was
+ *    detected (append-both-and-flag), else null.
+ *  - `divergenceFlag` — true when a LOW-impact concurrent overwrite occurred (the
+ *    HLC-winner won but the overwrite is FLAGGED, never silent).
+ */
+export interface UnionResult {
+    recordKey: string;
+    value: OriginRecord | null;
+    conflict: ConflictDescriptor | null;
+    divergenceFlag: boolean;
+}
+/**
+ * The conflict descriptor the union reader EMITS (the pure, content-addressed
+ * shape). The durable lifecycle (recurrence count, forced-resolution flag,
+ * first-seen timestamp, resolution) lives in ConflictStore — this is the
+ * detection-time fact: the stable id + the preserved version SET. `versions`
+ * carries every concurrent origin's record (a SET, §9 — never just a pair).
+ */
+export interface ConflictDescriptor {
+    conflictId: string;
+    recordKey: string;
+    versions: OriginRecord[];
+}
+/**
+ * The no-clobber union merge for one recordKey (§7.2). `perOrigin` is the set of
+ * distinct-origin current records for the key (own + every non-dropped peer
+ * namespace; the caller has already excluded a rolled-back origin, §7.4). `tier`
+ * is the store's impact tier.
+ *
+ * Rules (§7.2):
+ *  - 0 origins ⇒ no record.
+ *  - 1 origin ⇒ return it (a delete tombstone resolves to "no record" for the
+ *    value, but is still the authoritative latest).
+ *  - multiple origins, provably SEQUENTIAL (witness-dominated clean chain) ⇒ the
+ *    HLC-winner wins, no conflict, no divergence flag (a normal edit history).
+ *  - multiple origins, CONCURRENT ⇒ tier-dependent:
+ *    - high ⇒ APPEND-BOTH-AND-FLAG: value=null (neither clobbers), conflict set.
+ *    - low ⇒ HLC-wins WITH divergenceFlag=true (winner returned, overwrite flagged).
+ *
+ * A delete tombstone participates in the merge as a normal HLC-positioned record
+ * (so a concurrent delete↔put is a real conflict / divergence, never a silent
+ * resurrection or silent loss). When the resolved winner is a delete, `value`
+ * resolves to null (the key is deleted) but the winning RECORD is still returned
+ * via the conflict/divergence path so the caller can see WHY.
+ */
+export declare function readUnion(recordKey: string, perOrigin: OriginRecord[], tier: ImpactTier): UnionResult;
+//# sourceMappingURL=UnionReader.d.ts.map

package/dist/core/UnionReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnionReader.d.ts","sourceRoot":"","sources":["../../src/core/UnionReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAMxE;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAMxC;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAMD,sFAAsF;AACtF,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,YAAY,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,kBAAkB,GAAG,cAAc,CAM3F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EAAE,GACtB;IAAE,UAAU,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAyB9F;AAWD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAS9E;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAuDrG"}

package/dist/core/UnionReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnionReader.js","sourceRoot":"","sources":["../../src/core/UnionReader.ts"],"names":[],"mappings":"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"}