@openlfcp/shared-objects 0.1.0-rc.1

package/dist/data-profile.js

@@ -0,0 +1,311 @@
+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();
+    #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.#emit(rebuildChanges(before, this.#replica));
+    }
+    /** Whether this handler holds the unit's change (merged, recorded or buffered). */
+    has(unitId) {
+        const key = toHex(unitId);
+        return this.#merged.has(key) || this.#pending.has(key);
+    }
+    /** 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;
+        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) {
+        const byHash = new Map();
+        const offer = (unitId, change) => byHash.set(change.hash, [...(byHash.get(change.hash) ?? []), unitId]);
+        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));
+                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)),
+                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);
+            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: [] });
+        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);
+        return Object.freeze({ objects: changes.map((c) => c.objectId), pending });
+    }
+}
+/** §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/replica.d.ts

@@ -0,0 +1,277 @@
+import * as A from "@automerge/automerge";
+import { LfcpError, type ObjectId, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CheckedChange } from "./automerge-bytes.js";
+import { type SnapshotLimits } from "./chunk-limits.js";
+import { type Task, type TaskIntent } from "./task.js";
+import { type Json, type ProfileProblem, type RootValidation } from "./validate.js";
+/**
+ * The Automerge binding of SHARED-OBJECTS-PROFILE-01 (LFCP-031): one
+ * Resource's replica of the org.openlfcp.shared-objects.v1 document.
+ *
+ * - The actor is always the §8 actor of (Resource, Principal), set
+ *   explicitly; §9 actor state safety is enforced with `minSeq`.
+ * - One semantic intent is exactly one Automerge change (§10, §12), with
+ *   time 0 (informational, and a wall clock would leak edit times) and the
+ *   intent name as message. An intent that changes nothing makes no change.
+ * - Writes touch single properties only, so unknown fields, extension
+ *   namespaces and object types survive (§70-§72). Objects are never
+ *   removed: deletion is the lifecycle tombstone (§54-§56).
+ * - Scalar conflicts stay visible (§44-§47) and are resolved by a new
+ *   causal write (§69); tags and assignees are add-wins maps (§39-§43).
+ *
+ * Receiving is pure profile work: LFCP verification, decryption and
+ * authorization come first (§95, LFCP-033).
+ */
+/** The conflict-preserving scalar registers of a Task (§44). */
+export declare const SCALAR_FIELDS: readonly ["lifecycle", "title", "status", "due", "scheduled", "completion_date", "priority"];
+export type ScalarField = (typeof SCALAR_FIELDS)[number];
+/** §69 task.resolve_field_conflict: write `value` (null clears a date) after the merged conflicts. */
+export interface ResolveFieldConflict {
+    readonly intent: "task.resolve_field_conflict";
+    readonly id: ObjectId;
+    readonly field: ScalarField;
+    readonly value: string | null;
+}
+export type ReplicaIntent = TaskIntent | ResolveFieldConflict;
+/** task.resolve_field_conflict (§69). */
+export declare function resolveFieldConflict(id: ObjectId, field: ScalarField, value: string | null): ResolveFieldConflict;
+/** §21: two concurrent objects under one Object ID: OBJECT_ID_COLLISION, a profile error of its own, not PROFILE_INVALID. */
+export declare class ObjectIdCollisionError extends LfcpError {
+    readonly objectId: string;
+    constructor(objectId: string);
+}
+/** §99: a scalar register's provisional value and every concurrent value. */
+export interface ScalarView {
+    /** Automerge's deterministic visible value; provisional while conflicted. Undefined when absent. */
+    readonly value: Json | undefined;
+    /** Every concurrent value, sorted by JSON: none when absent, one when resolved. */
+    readonly values: readonly Json[];
+    readonly conflicted: boolean;
+}
+export type ObjectStatus = "ready" | "profile_invalid" | "object_id_collision";
+/** §99: a Task with its conflict metadata. */
+export interface TaskView {
+    readonly id: string;
+    readonly status: ObjectStatus;
+    readonly problems: readonly ProfileProblem[];
+    /** The provisional Task, when every visible value is valid. */
+    readonly task: Task | undefined;
+    readonly fields: {
+        readonly [F in ScalarField]: ScalarView;
+    };
+    readonly tags: readonly string[];
+    readonly assignees: readonly string[];
+}
+/** §100: what one change did to one object. */
+export interface ObjectChange {
+    readonly resource: ResourceId;
+    readonly objectId: string;
+    readonly objectType: string | undefined;
+    /** Top-level fields written, sorted. */
+    readonly fields: readonly string[];
+    readonly conflictsAppeared: readonly string[];
+    readonly conflictsDisappeared: readonly string[];
+    /** "rebuild": the state was rebuilt without some changes (§14.1, G-EP7). */
+    readonly origin: "local" | "remote" | "rebuild";
+}
+/** A local intent's Automerge change, ready to become a Data Unit. */
+export interface LocalChange {
+    readonly intent: string;
+    /** The exact Automerge change bytes. */
+    readonly change: Uint8Array;
+    /** §11: the Data Unit plaintext [1, change]. */
+    readonly plaintext: Uint8Array;
+    readonly hash: string;
+    readonly seq: number;
+    readonly objects: readonly ObjectChange[];
+}
+/**
+ * The outcome of receiving one change. A change whose dependencies are not
+ * all here is not applied and not invalid: the caller buffers it and offers
+ * it again later (LFCP-033).
+ */
+export type ReceiveResult = {
+    readonly status: "applied";
+    readonly change: CheckedChange;
+    readonly objects: readonly ObjectChange[];
+} | {
+    readonly status: "duplicate";
+    readonly change: CheckedChange;
+} | {
+    readonly status: "missing_dependencies";
+    readonly change: CheckedChange;
+    readonly missing: readonly string[];
+};
+/**
+ * The outcome of receiving many changes at once (receiveChanges): the
+ * changes merged, those already held, those still missing a dependency
+ * (not handed to Automerge, §14.1), and those refused with their error.
+ */
+export interface BatchReceiveResult {
+    readonly applied: readonly CheckedChange[];
+    readonly duplicates: readonly CheckedChange[];
+    readonly waiting: readonly CheckedChange[];
+    readonly refused: readonly {
+        readonly change: CheckedChange;
+        readonly error: LfcpError;
+    }[];
+    /** §100 notifications for everything the batch changed. */
+    readonly objects: readonly ObjectChange[];
+}
+/** Root validation plus §21 collisions and the G-SC3 scalar-string rule. */
+export interface ReplicaValidation extends RootValidation {
+    /** Object IDs with concurrent objects (OBJECT_ID_COLLISION, §21). */
+    readonly collisions: readonly string[];
+}
+export interface ReplicaOptions {
+    readonly resource: ResourceId;
+    /** The writing Principal; with the Resource it fixes the §8 actor. */
+    readonly principal: PrincipalId;
+    /**
+     * §9: the highest change sequence this actor is known to have used
+     * (persisted by the caller, LFCP-035). If the loaded state is behind it,
+     * local writes are refused: they would start an unrelated history under
+     * sequences already used.
+     */
+    readonly minSeq?: number;
+}
+/** A replica built from a change set; `unapplied` lacks dependencies in that set. */
+export interface BuiltReplica {
+    readonly replica: SharedObjectsReplica;
+    readonly unapplied: readonly CheckedChange[];
+}
+type Doc = A.Doc<Record<string, unknown>>;
+/** §30: an object's maps and lists nest at most this many levels (the field's own map is 1). */
+export declare const MAX_VALUE_DEPTH = 64;
+/**
+ * Applies one change that passed the receive checks. Automerge can throw
+ * after changing the document in place (a change that skips a sequence
+ * number stays in its graph without its operations), so on any engine error
+ * the handle is dropped: the document is rebuilt from the changes it held,
+ * which must give back the heads it had. A wasm trap is rethrown as it
+ * is: the module is dead, and only a restart recovers. Exported for tests.
+ */
+export declare function applyChecked(doc: Doc, bytes: Uint8Array): {
+    readonly next: Doc;
+} | {
+    readonly restored: Doc;
+    readonly error: Error;
+};
+/**
+ * applyChecked for a batch of admitted changes, in one engine call. On any
+ * engine error the handle is dropped and the document as it was before is
+ * rebuilt from the changes it held minus the batch, checked against the
+ * heads it had. Exported for tests.
+ */
+export declare function applyBatchChecked(doc: Doc, batch: readonly CheckedChange[]): {
+    readonly next: Doc;
+} | {
+    readonly restored: Doc;
+    readonly error: Error;
+};
+export declare class SharedObjectsReplica {
+    #private;
+    readonly resource: ResourceId;
+    /** The §8 Automerge actor ID. */
+    readonly actorId: Uint8Array;
+    private constructor();
+    /** §16: a new Resource document. The initial change is the Resource's first Data Unit. */
+    static create(opts: ReplicaOptions): {
+        replica: SharedObjectsReplica;
+        change: LocalChange;
+    };
+    /** A replica with no state yet, that receives the Resource's changes. */
+    static empty(opts: ReplicaOptions): SharedObjectsReplica;
+    /**
+     * Loads an Automerge full save: a received Snapshot image (§13), checked
+     * against `limits` (§13.1, at least the floor) before Automerge loads it,
+     * or this device's own persisted state ("local-state", not limited).
+     * Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES.
+     */
+    static fromSave(save: Uint8Array, opts: ReplicaOptions, limits?: SnapshotLimits | "local-state"): SharedObjectsReplica;
+    /** §13: loads a Snapshot plaintext [1, save]; later Data Units are received after it. */
+    static fromSnapshot(plaintext: Uint8Array, opts: ReplicaOptions): SharedObjectsReplica;
+    /**
+     * The replica of exactly an accepted change set: its state depends only
+     * on the set, not on the order. Changes whose dependencies are not in the
+     * set are returned as unapplied.
+     */
+    static fromChanges(changes: Iterable<Uint8Array>, opts: ReplicaOptions): BuiltReplica;
+    /**
+     * §14.1 (G-EP7): this replica rebuilt from its own changes minus
+     * `exclude` (change hashes). Changes that depend on an excluded change are
+     * unapplied too. An excluded change of this actor is not lost state (§9):
+     * the rebuilt replica writes on from its own sequence, reusing the
+     * sequence numbers of the removed changes. A replica that was already
+     * behind its persisted sequence stays refused.
+     */
+    rebuildWithout(exclude: Iterable<string>): BuiltReplica;
+    /**
+     * This replica merged with an Automerge full save (a loaded Snapshot,
+     * §13): the save's document plus every change of this replica, so local
+     * work the Snapshot does not hold is kept. The §9 sequence carries over.
+     * Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES when the save does not load.
+     */
+    mergeSave(save: Uint8Array): BuiltReplica;
+    /** An empty replica of the same Resource and actor that keeps the §9 sequence (nothing reused). */
+    emptied(): SharedObjectsReplica;
+    /** The highest change sequence of this replica's own actor in its state. */
+    get actorSeq(): number;
+    /** §9: false when the state is behind the persisted sequence, so local writes are refused. */
+    get writable(): boolean;
+    /** Hex hashes of the current heads, sorted. */
+    heads(): string[];
+    hasChange(hash: string): boolean;
+    /** Every change of the state, dependencies first. */
+    changes(): Uint8Array[];
+    /** The Automerge full save of the state. */
+    save(): Uint8Array;
+    /** §13: the Snapshot plaintext [1, save]. */
+    snapshot(): Uint8Array;
+    /**
+     * The logical root: scalar strings (and Text) read as strings, object keys
+     * in canonical order, so JSON.stringify(root()) is comparable across
+     * replicas holding the same state.
+     */
+    root(): Json;
+    /** The logical object stored under `id` (its visible value), if any. */
+    getObject(id: string): Json | undefined;
+    objectIds(): string[];
+    /** §45: every conflicted top-level field of every object, with its concurrent values sorted. */
+    conflicts(): Record<string, Record<string, Json[]>>;
+    /** §21: Object IDs under which concurrent objects were created. */
+    collisions(): string[];
+    /** §73-§77 validation of the visible state, every concurrent scalar value and G-SC3, plus §21 collisions. */
+    validate(): ReplicaValidation;
+    /** §99: the Task under `id` with conflict metadata, or undefined if there is no object or it is not a Task. */
+    task(id: string): TaskView | undefined;
+    /**
+     * Applies one intent as exactly one Automerge change (§10) and returns it,
+     * or null when the intent changes nothing (removing an absent tag,
+     * clearing an absent date). The resulting object must be profile-valid;
+     * an object already invalid or collided is not written (§76, §21) unless
+     * the write repairs it.
+     */
+    apply(intent: ReplicaIntent): LocalChange | null;
+    /** §11: receives a Data Unit plaintext [1, change]. Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES for invalid bytes. */
+    receive(plaintext: Uint8Array): ReceiveResult;
+    /** Receives one bare Automerge change (persisted or reference bytes). */
+    receiveChange(bytes: Uint8Array): ReceiveResult;
+    /**
+     * Receives many changes at once: store replay, catch-up, a Snapshot's
+     * remainder. Same rules as receiveChange (§14.1: no change with a
+     * missing dependency reaches Automerge; a taken sequence is
+     * ACTOR_EQUIVOCATION; a skipped one INVALID_AUTOMERGE_BYTES), but the
+     * admitted changes go to Automerge in ONE call: one change per call is
+     * quadratic (10 000 changes: ~12 s against ~70 ms as one batch).
+     *
+     * The changes may come in any order, duplicated: each is admitted once
+     * its dependencies inside the batch are (Kahn's order). A refused change
+     * does not stop the others; changes that depend on it wait. If Automerge
+     * fails anyway, the document is restored and the admitted changes are
+     * received one at a time, which isolates the failing one.
+     */
+    receiveChanges(changes: Iterable<Uint8Array | CheckedChange>): BatchReceiveResult;
+}
+export {};
+//# sourceMappingURL=replica.d.ts.map