@openlfcp/shared-objects 0.1.2 → 0.1.4

package/dist/data-profile.js

@@ -0,0 +1,349 @@
+import { LfcpError, toHex, } from "@openlfcp/core";
+import { frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./automerge-bytes.js";
+import { SharedObjectsReplica } from "./replica.js";
+import { ProfileInvalidError } from "./validate.js";
+import { deriveActorId, PROFILE_ID } from "./values.js";
+export class SharedObjectsDataProfile {
+    dataProfile = PROFILE_ID;
+    #replica;
+    /** Merged units: unit ID hex → change hash. */
+    #merged = new Map();
+    /** LFCP-accepted units waiting for Automerge dependencies, by unit ID hex. */
+    #pending = new Map();
+    /** LFCP-accepted units whose actor and sequence number a different change has (§14.1), by unit ID hex. */
+    #held = new Map();
+    #listeners = new Set();
+    constructor(replica) {
+        this.#replica = replica;
+    }
+    /**
+     * The local state to persist (structurally the storage ProfileCheckpoint,
+     * LFCP-034/035): the Automerge full save, this actor's sequence (the §9
+     * minSeq on restore) and which unit carried which merged change (for a
+     * G-EP7 rebuild). Units buffered for Automerge dependencies are not in it:
+     * they stay "profile-pending" in storage and are offered again on restore.
+     */
+    checkpoint() {
+        return Object.freeze({
+            resourceId: this.#replica.resource,
+            dataProfile: PROFILE_ID,
+            state: this.#replica.save(),
+            actorSeq: this.#replica.actorSeq,
+            units: Object.freeze([...this.#merged.values()]
+                .map((m) => Object.freeze({ unitId: m.unitId, ref: m.hash }))
+                .sort((a, b) => (toHex(a.unitId) < toHex(b.unitId) ? -1 : 1))),
+        });
+    }
+    /**
+     * The handler of a persisted checkpoint. The replica refuses local writes
+     * if its actor is behind the checkpoint's sequence (§9).
+     */
+    static restore(checkpoint, options) {
+        if (checkpoint.dataProfile !== PROFILE_ID)
+            throw new LfcpError("DATA_PROFILE_MISMATCH", `a ${checkpoint.dataProfile} checkpoint is not ${PROFILE_ID}`);
+        // This device's own persisted state: not held to the Snapshot limits (§13.1).
+        const replica = SharedObjectsReplica.fromSave(checkpoint.state, { ...options, minSeq: checkpoint.actorSeq }, "local-state");
+        const profile = new SharedObjectsDataProfile(replica);
+        for (const u of checkpoint.units) {
+            if (!replica.hasChange(u.ref))
+                throw new LfcpError("PROFILE_INVALID", `the checkpoint names change ${u.ref}, which its state lacks`);
+            profile.#merged.set(toHex(u.unitId), { unitId: u.unitId, hash: u.ref });
+        }
+        return profile;
+    }
+    /** The current replica (a G-EP7 rebuild replaces it). */
+    get replica() {
+        return this.#replica;
+    }
+    /** §98, §100: object change notifications for remote merges and rebuilds. */
+    onObjectChanged(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #emit(changes) {
+        for (const c of changes)
+            for (const l of this.#listeners)
+                l(c);
+    }
+    /**
+     * Records which change one of this client's OWN units carries (the unit
+     * was created from a local change, so it is merged already). A later
+     * G-EP7 exclusion of that unit then rebuilds the replica without it, and
+     * the checkpoint keeps the reference. Use it as createQueuedDataUnit's
+     * onCreated.
+     */
+    recordLocal(unitId, change) {
+        if (!this.#replica.hasChange(change.hash))
+            throw new LfcpError("PROFILE_INVALID", "the change is not in this replica; record only local changes");
+        this.#merged.set(toHex(unitId), { unitId, hash: change.hash });
+    }
+    /**
+     * The §13 Snapshot codec (structurally the wire DataProfileCodec): an
+     * Automerge full save framed as [1, save]; decoding requires a document
+     * chunk. For receiveSnapshot and createSnapshot.
+     */
+    snapshotCodec() {
+        return {
+            dataProfile: PROFILE_ID,
+            encode: (save) => frameSnapshot(save),
+            decode: (plaintext) => unframeSnapshot(plaintext),
+        };
+    }
+    /** The state to publish as a Snapshot: the replica's full save. */
+    snapshotState() {
+        return this.#replica.save();
+    }
+    /**
+     * Loads a received Snapshot's full save (§13, §66 step 3): the replica
+     * becomes the save merged with everything it held, and buffered units
+     * whose dependencies the Snapshot brings are merged. Returns the objects
+     * that changed and the units merged from the buffer.
+     */
+    loadSnapshot(save) {
+        const before = this.#replica;
+        const { replica } = before.mergeSave(save);
+        this.#replica = replica;
+        const merged = [...this.#applyBatch([]).result.merged];
+        const changes = rebuildChanges(before, replica).map((c) => Object.freeze({ ...c, origin: "remote" }));
+        this.#emit(changes);
+        return Object.freeze({ objects: changes.map((c) => c.objectId), merged });
+    }
+    /**
+     * Forgets the whole state (an empty replica that keeps the §9 sequence,
+     * no merged or buffered units), so it can be rebuilt from accepted units
+     * only (SNAP-EP: Snapshot-derived state dropped). Notifies the changes.
+     */
+    reset() {
+        const before = this.#replica;
+        this.#replica = before.emptied();
+        this.#merged.clear();
+        this.#pending.clear();
+        this.#held.clear();
+        this.#emit(rebuildChanges(before, this.#replica));
+    }
+    /** Whether this handler holds the unit's change (merged, recorded, buffered or held). */
+    has(unitId) {
+        const key = toHex(unitId);
+        return this.#merged.has(key) || this.#pending.has(key) || this.#held.has(key);
+    }
+    /** The units held because a different change has their actor and sequence number (§14.1). */
+    heldUnits() {
+        return [...this.#held.values()].map((b) => b.unitId);
+    }
+    /** The units waiting for Automerge dependencies. */
+    pendingUnits() {
+        return [...this.#pending.values()].map((b) => b.unitId);
+    }
+    codecFor(unit) {
+        const actor = toHex(deriveActorId(unit.resourceId, unit.actor));
+        // §8, §11 (SO-SEC1): a unit carries only changes of its signer's §8
+        // actor, so no Principal can write into another Principal's Automerge
+        // history. Anything else is PROFILE_INVALID / CHANGE_ACTOR_MISMATCH.
+        const bound = (change) => {
+            if (change.actor !== actor)
+                throw new ProfileInvalidError("CHANGE_ACTOR_MISMATCH", `the change's Automerge actor ${change.actor} is not the §8 actor ${actor} of the unit's signer (§11, SO-SEC1)`);
+            return change;
+        };
+        return {
+            dataProfile: PROFILE_ID,
+            encode: (change) => frameChange(bound(change).bytes),
+            decode: (plaintext) => bound(unframeChange(plaintext)),
+        };
+    }
+    apply(unit, change) {
+        const key = toHex(unit.unitId);
+        const r = this.#applyBatch([{ unit, value: change }]);
+        const own = r.refused.get(key);
+        if (own !== undefined)
+            throw own;
+        if (this.#held.has(key))
+            return Object.freeze({
+                merged: r.result.merged,
+                objects: r.result.objects,
+                diagnostics: r.result.diagnostics,
+                held: `held: a different change has actor ${change.actor} sequence ${change.seq} (§14.1)`,
+            });
+        const self = r.result.merged.some((id) => toHex(id) === key);
+        if (!self)
+            return Object.freeze({
+                merged: r.result.merged,
+                objects: r.result.objects,
+                diagnostics: r.result.diagnostics,
+                pending: `waiting for Automerge changes ${r.missing.join(", ")}`,
+            });
+        // The unit first, then the buffered ones it released.
+        return Object.freeze({
+            merged: [unit.unitId, ...r.result.merged.filter((id) => toHex(id) !== key)],
+            objects: r.result.objects,
+            diagnostics: r.result.diagnostics,
+        });
+    }
+    /**
+     * Applies many accepted units at once (catch-up, store replay, a
+     * Snapshot's remainder): their changes and every buffered one go to the
+     * replica in one receiveChanges call, which hands Automerge one batch
+     * (§14.1 admission per change; one change per call is quadratic). A
+     * refused change rejects only its unit; units missing a dependency are
+     * buffered. Diagnostics are computed once, for the objects that changed.
+     */
+    applyBatch(units) {
+        return this.#applyBatch(units).result;
+    }
+    #applyBatch(units, retryHeld = false) {
+        const byHash = new Map();
+        const offer = (unitId, change) => byHash.set(change.hash, [...(byHash.get(change.hash) ?? []), unitId]);
+        // §14.1: after a rebuild, held changes are offered again with the rest.
+        if (retryHeld) {
+            for (const [key, b] of this.#held)
+                this.#pending.set(key, b);
+            this.#held.clear();
+        }
+        for (const b of this.#pending.values())
+            offer(b.unitId, b.change);
+        for (const { unit, value } of units) {
+            this.#pending.set(toHex(unit.unitId), { unitId: unit.unitId, change: value });
+            offer(unit.unitId, value);
+        }
+        const r = this.#replica.receiveChanges([...this.#pending.values()].map((b) => b.change));
+        const merged = [];
+        for (const c of [...r.applied, ...r.duplicates])
+            for (const unitId of byHash.get(c.hash) ?? []) {
+                this.#pending.delete(toHex(unitId));
+                this.#merged.set(toHex(unitId), { unitId, hash: c.hash });
+                merged.push(unitId);
+            }
+        const rejected = [];
+        const refused = new Map();
+        for (const { change, error } of r.refused)
+            for (const unitId of byHash.get(change.hash) ?? []) {
+                this.#pending.delete(toHex(unitId));
+                // §14.1 (POST-001): another change has its actor and sequence number: held, not refused.
+                if (error.code === "ACTOR_EQUIVOCATION") {
+                    this.#held.set(toHex(unitId), { unitId, change });
+                    continue;
+                }
+                rejected.push({ unitId, code: error.code, message: error.message });
+                refused.set(toHex(unitId), error);
+            }
+        this.#emit(r.objects);
+        const objects = [...new Set(r.objects.map((c) => c.objectId))].sort();
+        const missing = [
+            ...new Set(r.waiting.flatMap((c) => c.deps.filter((d) => !this.#replica.hasChange(d)))),
+        ];
+        return {
+            result: Object.freeze({
+                merged: Object.freeze(merged),
+                pending: Object.freeze([...this.#pending.values()].map((b) => b.unitId)),
+                held: Object.freeze(this.heldUnits()),
+                rejected: Object.freeze(rejected),
+                objects: Object.freeze(objects),
+                diagnostics: Object.freeze(this.#diagnostics(objects)),
+            }),
+            refused,
+            missing,
+        };
+    }
+    /** §74.1 problems and §21 collisions of the given objects (§77: the rest are unaffected). */
+    #diagnostics(objects) {
+        if (objects.length === 0)
+            return [];
+        const validation = this.#replica.validate();
+        const out = [];
+        for (const id of objects) {
+            for (const p of validation.objects.get(id) ?? [])
+                out.push({
+                    objectId: id,
+                    code: p.code,
+                    diagnostic: p.diagnostic,
+                    pointer: p.pointer,
+                    message: p.message,
+                });
+            if (validation.collisions.includes(id))
+                out.push({
+                    objectId: id,
+                    code: "OBJECT_ID_COLLISION",
+                    message: `${id}: concurrent objects share this Object ID (§21)`,
+                });
+        }
+        return out;
+    }
+    /**
+     * §14.1 (G-EP7): the state without `unitIds`, rebuilt from the
+     * remaining changes. Merged units whose changes build on an excluded one
+     * go back to the buffer and are reported as pending.
+     */
+    exclude(unitIds) {
+        const hashes = [];
+        for (const id of unitIds) {
+            const key = toHex(id);
+            this.#pending.delete(key);
+            this.#held.delete(key);
+            const m = this.#merged.get(key);
+            if (m !== undefined) {
+                hashes.push(m.hash);
+                this.#merged.delete(key);
+            }
+        }
+        if (hashes.length === 0)
+            return Object.freeze({ objects: [], pending: [], released: [] });
+        const before = this.#replica;
+        const { replica, unapplied } = before.rebuildWithout(hashes);
+        this.#replica = replica;
+        const pending = [];
+        for (const change of unapplied) {
+            const entry = [...this.#merged].find(([, m]) => m.hash === change.hash);
+            if (entry === undefined)
+                continue; // a local change: kept out with its dependency
+            this.#merged.delete(entry[0]);
+            this.#pending.set(entry[0], { unitId: entry[1].unitId, change });
+            pending.push(entry[1].unitId);
+        }
+        const changes = rebuildChanges(before, replica);
+        this.#emit(changes);
+        // §14.1: the rebuild may have freed held changes' actor sequences.
+        const held = new Set(this.#held.keys());
+        const retried = held.size > 0 ? this.#applyBatch([], true) : null;
+        const released = (retried?.result.merged ?? []).filter((id) => held.has(toHex(id)));
+        const objects = [
+            ...new Set([...changes.map((c) => c.objectId), ...(retried?.result.objects ?? [])]),
+        ].sort();
+        return Object.freeze({
+            objects,
+            pending: pending.filter((id) => !(retried?.result.merged ?? []).some((m) => toHex(m) === toHex(id))),
+            released: Object.freeze(released),
+        });
+    }
+}
+/** §100 notifications for every object that differs between two replicas of one Resource. */
+function rebuildChanges(before, after) {
+    const ids = [...new Set([...before.objectIds(), ...after.objectIds()])].sort();
+    const beforeConflicts = before.conflicts();
+    const afterConflicts = after.conflicts();
+    const out = [];
+    for (const id of ids) {
+        const was = (before.getObject(id) ?? {});
+        const now = (after.getObject(id) ?? {});
+        const fields = [...new Set([...Object.keys(was), ...Object.keys(now)])]
+            .filter((f) => JSON.stringify(was[f]) !== JSON.stringify(now[f]))
+            .sort();
+        const wasC = Object.keys(beforeConflicts[id] ?? {});
+        const nowC = Object.keys(afterConflicts[id] ?? {});
+        if (fields.length === 0 && JSON.stringify(wasC) === JSON.stringify(nowC))
+            continue;
+        out.push(Object.freeze({
+            resource: after.resource,
+            objectId: id,
+            objectType: typeof now.type === "string"
+                ? now.type
+                : typeof was.type === "string"
+                    ? was.type
+                    : undefined,
+            fields: Object.freeze(fields),
+            conflictsAppeared: Object.freeze(nowC.filter((f) => !wasC.includes(f)).sort()),
+            conflictsDisappeared: Object.freeze(wasC.filter((f) => !nowC.includes(f)).sort()),
+            origin: "rebuild",
+        }));
+    }
+    return out;
+}
+//# sourceMappingURL=data-profile.js.map

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SHARED-OBJECTS-PROFILE-01 (org.openlfcp.shared-objects.v1): the Shared
+ * Task model and profile validation over logical state (LFCP-030), and its
+ * Automerge binding (LFCP-031).
+ */
+export declare const PACKAGE = "@openlfcp/shared-objects";
+export { type CheckedChange, checkChange, checkSaveHeader, frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./automerge-bytes.js";
+export { CHANGE_LIMITS, type ChunkExpansion, checkChangeExpansion, checkSnapshotExpansion, MAX_DOCUMENT_DEPTH, SNAPSHOT_LIMITS_FLOOR, type SnapshotLimits, } from "./chunk-limits.js";
+export { type SharedObjectsApplyResult, type SharedObjectsBatchResult, type SharedObjectsCheckpoint, type SharedObjectsCodec, SharedObjectsDataProfile, type SharedObjectsDiagnostic, type SharedObjectsExcludeResult, type SharedObjectsSnapshotCodec, type SharedObjectsUnit, } from "./data-profile.js";
+export { type BatchReceiveResult, type BuiltReplica, type LocalChange, type ObjectChange, ObjectIdCollisionError, type ObjectStatus, type ReceiveResult, type ReplicaIntent, type ReplicaOptions, type ReplicaValidation, type ResolveFieldConflict, resolveFieldConflict, SCALAR_FIELDS, type ScalarField, type ScalarView, SharedObjectsReplica, type TaskView, } from "./replica.js";
+export { addTag, assign, cancel, clearDue, clearScheduled, complete, createTask, deleteTask, type NewTask, type ParsedTask, ProfileError, parseTask, removeTag, reopen, restoreTask, setDue, setPriority, setScheduled, setStatus, setTitle, type Task, type TaskChange, type TaskIntent, type TaskPriority, type TaskStatus, taskToJson, unassign, } from "./task.js";
+export { DIAGNOSTIC_ORDER, firstPerField, isMap, type Json, objectProblems, type ProfileDiagnostic, ProfileInvalidError, type ProfileProblem, pointerToken, type RootValidation, validateRoot, validateTransition, } from "./validate.js";
+export { deriveActorId, FRAMING_VERSION, frameProfilePayload, isLocalDate, isNamespacedValue, isPrincipalRef, isReverseDomain, isUtcTimestamp, PROFILE_ID, type PrincipalRef, parsePrincipalRef, principalRef, unframeProfilePayload, } from "./values.js";
+export { initializeAutomerge, isAutomergeInitialized } from "./wasm.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * SHARED-OBJECTS-PROFILE-01 (org.openlfcp.shared-objects.v1): the Shared
+ * Task model and profile validation over logical state (LFCP-030), and its
+ * Automerge binding (LFCP-031).
+ */
+export const PACKAGE = "@openlfcp/shared-objects";
+export { checkChange, checkSaveHeader, frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./automerge-bytes.js";
+export { CHANGE_LIMITS, checkChangeExpansion, checkSnapshotExpansion, MAX_DOCUMENT_DEPTH, SNAPSHOT_LIMITS_FLOOR, } from "./chunk-limits.js";
+export { SharedObjectsDataProfile, } from "./data-profile.js";
+export { ObjectIdCollisionError, resolveFieldConflict, SCALAR_FIELDS, SharedObjectsReplica, } from "./replica.js";
+export { addTag, assign, cancel, clearDue, clearScheduled, complete, createTask, deleteTask, ProfileError, parseTask, removeTag, reopen, restoreTask, setDue, setPriority, setScheduled, setStatus, setTitle, taskToJson, unassign, } from "./task.js";
+export { DIAGNOSTIC_ORDER, firstPerField, isMap, objectProblems, ProfileInvalidError, pointerToken, validateRoot, validateTransition, } from "./validate.js";
+export { deriveActorId, FRAMING_VERSION, frameProfilePayload, isLocalDate, isNamespacedValue, isPrincipalRef, isReverseDomain, isUtcTimestamp, PROFILE_ID, parsePrincipalRef, principalRef, unframeProfilePayload, } from "./values.js";
+export { initializeAutomerge, isAutomergeInitialized } from "./wasm.js";
+//# sourceMappingURL=index.js.map

package/dist/profile-invalid.d.ts

@@ -0,0 +1,12 @@
+import { LfcpError } from "@openlfcp/core";
+import type { ProfileDiagnostic } from "./validate.js";
+/**
+ * PROFILE_INVALID thrown for a rejected profile plaintext or value, with
+ * its §74.1 diagnostic: CHANGE_ACTOR_MISMATCH (§8, §11) or
+ * INVALID_AUTOMERGE_BYTES (§11, §13).
+ */
+export declare class ProfileInvalidError extends LfcpError {
+    readonly diagnostic: ProfileDiagnostic;
+    constructor(diagnostic: ProfileDiagnostic, message: string);
+}
+//# sourceMappingURL=profile-invalid.d.ts.map

package/dist/profile-invalid.js

@@ -0,0 +1,15 @@
+import { LfcpError } from "@openlfcp/core";
+/**
+ * PROFILE_INVALID thrown for a rejected profile plaintext or value, with
+ * its §74.1 diagnostic: CHANGE_ACTOR_MISMATCH (§8, §11) or
+ * INVALID_AUTOMERGE_BYTES (§11, §13).
+ */
+export class ProfileInvalidError extends LfcpError {
+    diagnostic;
+    constructor(diagnostic, message) {
+        super("PROFILE_INVALID", message);
+        this.name = "ProfileInvalidError";
+        this.diagnostic = diagnostic;
+    }
+}
+//# sourceMappingURL=profile-invalid.js.map

package/dist/references.d.ts

@@ -0,0 +1,28 @@
+import * as A from "@automerge/automerge";
+import { type ParsedChange } from "./canonical.js";
+/** A §11.4 rule a change breaks. */
+export type ReferenceRule = "R1" | "R2" | "R3" | "R4" | "R5" | "R6" | "R7";
+/**
+ * The changes of a document as §11.4 reads them. A replica keeps it current
+ * as changes are admitted and committed, or builds it again from its
+ * document.
+ */
+export declare class ReferenceHistory {
+    #private;
+    get size(): number;
+    has(hash: string): boolean;
+    /**
+     * Adds a change the document now holds. Its dependencies are added
+     * first; one this index does not hold adds nothing to its history.
+     */
+    add(hash: string, change: ParsedChange): void;
+    /** The §11.4 rule `change` breaks against its causal history, or null. */
+    check(change: ParsedChange): ReferenceRule | null;
+}
+/**
+ * The index of every change a document holds, as the engine hands them
+ * out (in its encoding, so canonical), dependencies first. A change the
+ * walk cannot read is left out: references into it are then refused.
+ */
+export declare function referenceHistoryOf(doc: A.Doc<unknown>): ReferenceHistory;
+//# sourceMappingURL=references.d.ts.map

package/dist/references.js

@@ -0,0 +1,220 @@
+// Operation references (SHARED-OBJECTS-PROFILE-01 §11.4, SPEC-PATCH-10,
+// ADR 0010): a change's operations refer only to its own causal history H
+// (its dependencies and all their ancestors) or to operations earlier in
+// the change. An engine applies a change that refers elsewhere (a
+// predecessor on another key, an element of another list, an object that is
+// not one), but then cannot write it back out, and some such changes abort
+// the apply itself, which in Automerge JS terminates its wasm module. The
+// rules are decided against H only, never anything else the receiver holds,
+// so every replica decides alike.
+//
+// H is held as a vector clock: an admitted change's actor chain is
+// contiguous in its history (R1), so the latest sequence number of each
+// actor in H says exactly which changes H holds. An operation is found by
+// its actor's changes and their counter ranges.
+import * as A from "@automerge/automerge";
+import { checkCanonicalChange } from "./canonical.js";
+const MAKE = new Set([0, 2, 4, 6]);
+const MAP_LIKE = new Set([0, 6]);
+function slotOf(op, id) {
+    if (op.insert)
+        return `e:${id}`;
+    if (op.key.kind === "prop")
+        return `p:${op.key.name}`;
+    if (op.key.kind === "elem")
+        return `e:${op.key.id}`;
+    return "e:_head";
+}
+const targetOf = (op, id) => ({
+    obj: op.obj,
+    slot: slotOf(op, id),
+    insert: op.insert,
+    del: op.action === 3,
+    make: MAKE.has(op.action) ? op.action : null,
+});
+function splitId(id) {
+    const at = id.indexOf("@");
+    return { ctr: Number(id.slice(0, at)), actor: id.slice(at + 1) };
+}
+/**
+ * The changes of a document as §11.4 reads them. A replica keeps it current
+ * as changes are admitted and committed, or builds it again from its
+ * document.
+ */
+export class ReferenceHistory {
+    #byHash = new Map();
+    /** Each actor's changes by sequence number (index seq - 1). */
+    #byActor = new Map();
+    get size() {
+        return this.#byHash.size;
+    }
+    has(hash) {
+        return this.#byHash.has(hash);
+    }
+    /** H of a change with these dependencies: the latest sequence of each actor. */
+    #history(deps) {
+        const clock = new Map();
+        for (const d of deps) {
+            const e = this.#byHash.get(d);
+            if (e === undefined)
+                continue;
+            for (const [a, s] of e.clock)
+                if ((clock.get(a) ?? 0) < s)
+                    clock.set(a, s);
+        }
+        return clock;
+    }
+    /**
+     * Adds a change the document now holds. Its dependencies are added
+     * first; one this index does not hold adds nothing to its history.
+     */
+    add(hash, change) {
+        if (this.#byHash.has(hash))
+            return;
+        const clock = this.#history(change.deps);
+        if ((clock.get(change.actor) ?? 0) < change.seq)
+            clock.set(change.actor, change.seq);
+        const entry = {
+            actor: change.actor,
+            seq: change.seq,
+            startOp: change.startOp,
+            ops: change.ops.map((op, i) => targetOf(op, `${change.startOp + i}@${change.actor}`)),
+            clock,
+        };
+        this.#byHash.set(hash, entry);
+        const list = this.#byActor.get(change.actor) ?? [];
+        list[change.seq - 1] = entry;
+        this.#byActor.set(change.actor, list);
+    }
+    /** The change of `actor` holding operation counter `ctr`, among its first `upToSeq` changes. */
+    #find(actor, ctr, upToSeq) {
+        const list = this.#byActor.get(actor);
+        if (list === undefined)
+            return null;
+        let lo = 0;
+        let hi = Math.min(upToSeq, list.length) - 1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const e = list[mid];
+            if (e === undefined)
+                return null;
+            if (ctr < e.startOp)
+                hi = mid - 1;
+            else if (ctr >= e.startOp + e.ops.length)
+                lo = mid + 1;
+            else
+                return { entry: e, index: ctr - e.startOp };
+        }
+        return null;
+    }
+    /** The §11.4 rule `change` breaks against its causal history, or null. */
+    check(change) {
+        const H = this.#history(change.deps);
+        // R1: the actor's previous change is in H.
+        if (change.seq > 1 && (H.get(change.actor) ?? 0) < change.seq - 1)
+            return "R1";
+        // R2: the start op follows H's largest counter (each actor's latest change in H has its largest).
+        let top = 0;
+        for (const [a, s] of H) {
+            const e = this.#byActor.get(a)?.[s - 1];
+            if (e !== undefined && e.startOp + e.ops.length - 1 > top)
+                top = e.startOp + e.ops.length - 1;
+        }
+        if (change.startOp !== top + 1)
+            return "R2";
+        const own = [];
+        // An operation of H or earlier in this change; deletions are not targets.
+        const target = (id) => {
+            const { ctr, actor } = splitId(id);
+            let t;
+            if (actor === change.actor && ctr >= change.startOp && ctr < change.startOp + own.length)
+                t = own[ctr - change.startOp];
+            else {
+                const found = this.#find(actor, ctr, H.get(actor) ?? 0);
+                t = found === null ? undefined : found.entry.ops[found.index];
+            }
+            return t === undefined || t.del ? undefined : t;
+        };
+        for (const [i, op] of change.ops.entries()) {
+            const id = `${change.startOp + i}@${change.actor}`;
+            // R3: the root, or an object an operation made; its key form.
+            let sequence;
+            if (op.obj === "_root")
+                sequence = false;
+            else {
+                const made = target(op.obj)?.make ?? null;
+                if (made === null)
+                    return "R3";
+                sequence = !MAP_LIKE.has(made);
+            }
+            if (!sequence && (op.insert || op.key.kind !== "prop"))
+                return op.insert ? "R4" : "R3";
+            if (sequence && op.key.kind === "prop")
+                return "R3";
+            const element = (e) => {
+                const t = target(e);
+                return t !== undefined && t.insert && t.obj === op.obj;
+            };
+            // R4: an insertion goes after the head or an element of the same object, without predecessors.
+            if (op.insert && (op.pred.length > 0 || (op.key.kind === "elem" && !element(op.key.id))))
+                return "R4";
+            // R5: any other sequence operation names an element of the same object.
+            if (sequence && !op.insert && (op.key.kind !== "elem" || !element(op.key.id)))
+                return "R5";
+            // R6: predecessors on the same object and key.
+            const slot = slotOf(op, id);
+            for (const p of op.pred) {
+                const t = target(p);
+                if (t === undefined || t.obj !== op.obj || t.slot !== slot)
+                    return "R6";
+            }
+            // R7: a deletion has a predecessor.
+            if (op.action === 3 && op.pred.length === 0)
+                return "R7";
+            own.push(targetOf(op, id));
+        }
+        return null;
+    }
+}
+/**
+ * The index of every change a document holds, as the engine hands them
+ * out (in its encoding, so canonical), dependencies first. A change the
+ * walk cannot read is left out: references into it are then refused.
+ */
+export function referenceHistoryOf(doc) {
+    const parsed = new Map();
+    for (const bytes of A.getAllChanges(doc)) {
+        try {
+            parsed.set(A.decodeChange(bytes).hash, checkCanonicalChange(bytes));
+        }
+        catch {
+            // not readable: left out
+        }
+    }
+    const refs = new ReferenceHistory();
+    const placed = new Set();
+    for (const start of parsed.keys()) {
+        // Iterative depth-first: dependencies first, without recursion.
+        const stack = [{ hash: start, next: 0 }];
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            const change = parsed.get(top.hash);
+            if (change === undefined || placed.has(top.hash)) {
+                stack.pop();
+                continue;
+            }
+            const dep = change.deps[top.next];
+            if (dep !== undefined) {
+                top.next++;
+                if (!placed.has(dep) && parsed.has(dep))
+                    stack.push({ hash: dep, next: 0 });
+                continue;
+            }
+            placed.add(top.hash);
+            refs.add(top.hash, change);
+            stack.pop();
+        }
+    }
+    return refs;
+}
+//# sourceMappingURL=references.js.map