@openlfcp/shared-objects 0.1.5 → 0.2.0-beta.2

package/dist/sections/admission.js

@@ -0,0 +1,328 @@
+import * as A from "@automerge/automerge";
+import { LfcpError, toHex } from "@openlfcp/core";
+import { decodedOf } from "../admission/framing.js";
+import { MAX_DOCUMENT_DEPTH } from "../admission/limits.js";
+import { parsePrincipalRef } from "../values.js";
+import { deriveSectionActorId } from "./values.js";
+/**
+ * The structural admission of SHARED-SECTIONS-PROFILE-01 §14.1 (LFCP-02-017):
+ * rules A1–A5 and the readiness rule of §12.1, decided from the change's own
+ * operations and the objects they write into, in time linear in the change.
+ * It runs after the inherited SOP checks (framing, limits, actor, sequence)
+ * and before the engine applies anything; a refused change is never merged.
+ *
+ * Objects of the document are identified by their path from the root
+ * (Automerge objInfo); objects created by changes admitted earlier in the
+ * same batch, or earlier in the change, by the operation that creates them.
+ */
+/** §14.1: the admission diagnostics, in their order of precedence. */
+export const ADMISSION_ORDER = Object.freeze([
+    "INVALID_AUTOMERGE_BYTES",
+    "CHANGE_ACTOR_MISMATCH",
+    "CONTAINER_REPLACED",
+    "CHILDREN_LIST_MUTATED",
+    "PLACEMENT_NOT_ATOMIC",
+    "IMMUTABLE_FIELD_MUTATED",
+    "INVALID_FIELD_TYPE",
+]);
+/** A change refused at admission: PROFILE_INVALID with its §14.1 diagnostic. */
+export class SectionAdmissionError extends LfcpError {
+    diagnostic;
+    constructor(diagnostic, message) {
+        super("PROFILE_INVALID", message);
+        this.name = "SectionAdmissionError";
+        this.diagnostic = diagnostic;
+    }
+}
+const ROOT_CONTAINERS = new Set([
+    "profile",
+    "section",
+    "objects",
+    "nodes",
+    "placements",
+    "extensions",
+]);
+const NODE_IMMUTABLE = new Set(["id", "kind", "created_by", "task_id"]);
+const TASK_IMMUTABLE = new Set(["id", "type", "created_by"]);
+const NODE_CONTAINERS = new Set(["children", "text", "extensions"]);
+const MAKE = new Set(["makeMap", "makeList", "makeText", "makeTable"]);
+export class SectionAdmission {
+    /** The document with every change admitted so far: each change is read at its own deps. */
+    #work;
+    #backend;
+    #resource;
+    constructor(doc, resource) {
+        this.#work = doc;
+        this.#backend = A.getBackend(doc);
+        this.#resource = resource;
+    }
+    /** Admitted changes not yet applied to the working document. */
+    #pending = [];
+    /**
+     * Applies the admitted changes still pending, in one engine call. Done
+     * only when a check reads the state they may change, so a long linear run
+     * of Text edits is applied once, not change by change.
+     */
+    #flush() {
+        if (this.#pending.length === 0)
+            return;
+        const batch = this.#pending;
+        this.#pending = [];
+        [this.#work] = A.applyChanges(this.#work, batch);
+        this.#backend = A.getBackend(this.#work);
+        for (const [obj, k] of this.#paths)
+            if (k === undefined)
+                this.#paths.delete(obj);
+    }
+    /** The document with the admitted changes applied. */
+    get document() {
+        this.#flush();
+        return this.#work;
+    }
+    /** Paths of the document's objects, read once each: objects never move. */
+    #paths = new Map();
+    /** Path and depth of an object of the document; undefined when it is unknown. */
+    #known(obj) {
+        if (obj === "_root")
+            return { path: [], depth: 0 };
+        if (this.#paths.get(obj) !== undefined)
+            return this.#paths.get(obj);
+        this.#flush();
+        let known;
+        try {
+            const path = this.#backend.objInfo(obj).path;
+            known = { path, depth: path === undefined ? Number.NaN : path.length };
+        }
+        catch {
+            known = undefined;
+        }
+        this.#paths.set(obj, known);
+        return known;
+    }
+    /** Whether `key` of `obj` has a value in the change's causal history (`heads`). */
+    #has(obj, key, heads) {
+        this.#flush();
+        try {
+            return this.#backend.getAll(obj, key, heads).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The section's scalar `key` in the document (its ID and creator never change). */
+    /** Section fields already read: they never change once written. */
+    #sectionFields = new Map();
+    #section(key) {
+        const cached = this.#sectionFields.get(key);
+        if (cached !== undefined)
+            return cached;
+        this.#flush();
+        const section = this.#work.section;
+        const v = section?.[key];
+        if (v === undefined)
+            return undefined;
+        this.#sectionFields.set(key, String(v));
+        return String(v);
+    }
+    /**
+     * Admits `change` against its causal history, or throws
+     * SectionAdmissionError. An admitted change is applied to the working
+     * document at once, so the changes after it in the batch see it.
+     */
+    accept(change) {
+        const decoded = decodedOf(change);
+        const ops = decoded.ops;
+        const found = new Set();
+        const local = new Map();
+        const knownOf = (obj) => local.get(obj) ?? this.#known(obj);
+        // Objects this change did not create existed in its causal history.
+        const existed = (obj) => !local.has(obj) && obj !== "_root";
+        const heads = decoded.deps;
+        const has = (obj, key) => this.#has(obj, key, heads);
+        // Created placements of this change: their fields, list entries and register writes.
+        const placements = new Map();
+        const registers = new Map(); // node → PlacementIds written to its register
+        const insertedInto = [];
+        let readyWrite;
+        let creatorInChange;
+        ops.forEach((op, i) => {
+            const parent = knownOf(op.obj);
+            const path = parent?.path;
+            const key = op.key;
+            const own = (p, k) => p !== undefined && p.length === k ? p : undefined;
+            if (MAKE.has(op.action)) {
+                const id = `${decoded.startOp + i}@${decoded.actor}`;
+                if (parent === undefined)
+                    throw new SectionAdmissionError("INVALID_AUTOMERGE_BYTES", `the change writes into object ${op.obj}, which the document does not have (SOP §11.2)`);
+                const depth = parent.depth + 1;
+                if (depth > MAX_DOCUMENT_DEPTH)
+                    throw new SectionAdmissionError("INVALID_AUTOMERGE_BYTES", `the change creates an object deeper than ${MAX_DOCUMENT_DEPTH} levels (SOP §11.2)`);
+                const childPath = path === undefined ? undefined : key !== undefined ? [...path, key] : [...path, -1];
+                local.set(id, { path: childPath, depth });
+            }
+            // The root: its containers are created once (A4).
+            if (op.obj === "_root") {
+                if (key !== undefined && ROOT_CONTAINERS.has(key) && has("_root", key))
+                    found.add("CONTAINER_REPLACED");
+                return;
+            }
+            if (path === undefined)
+                return; // an object without a known place: nothing structural
+            const [top, second] = path;
+            if (top === "section" && path.length === 1) {
+                if (!existed(op.obj)) {
+                    if (key === "created_by" && typeof op.value === "string")
+                        creatorInChange = op.value;
+                }
+                else if (key === "id" || key === "created_by")
+                    found.add("IMMUTABLE_FIELD_MUTATED");
+                if ((key === "children" || key === "extensions") && existed(op.obj) && has(op.obj, key))
+                    found.add("CONTAINER_REPLACED");
+                if (key === "ready")
+                    readyWrite = {
+                        value: op.value,
+                        del: op.action === "del",
+                        again: (readyWrite?.again ?? false) || (existed(op.obj) && has(op.obj, "ready")),
+                    };
+                else if (op.action === "makeText")
+                    found.add("INVALID_FIELD_TYPE");
+                return;
+            }
+            // Children lists: insert-only, entries are scalar PlacementIds (A1, A2, A5).
+            const owner = own(path, 2)?.[0] === "section" && path[1] === "children"
+                ? "section"
+                : own(path, 3)?.[0] === "nodes" && path[2] === "children"
+                    ? String(second)
+                    : undefined;
+            if (owner !== undefined) {
+                const isNew = !existed(op.obj);
+                if (op.insert) {
+                    if (op.action !== "set" || typeof op.value !== "string")
+                        found.add("INVALID_FIELD_TYPE");
+                    else
+                        insertedInto.push({ owner, value: op.value });
+                }
+                else if (!isNew || op.action === "del" || op.action === "set") {
+                    found.add("CHILDREN_LIST_MUTATED");
+                }
+                return;
+            }
+            if (top === "nodes" && path.length === 1) {
+                // A node map is created once; replacing or deleting it is A4.
+                if (key !== undefined && has(op.obj, key) && existed(op.obj))
+                    found.add("CONTAINER_REPLACED");
+                return;
+            }
+            if (top === "nodes" && path.length === 2) {
+                const node = String(second);
+                const isNew = !existed(op.obj);
+                if (key === undefined)
+                    return;
+                if (!isNew) {
+                    if (NODE_CONTAINERS.has(key) && has(op.obj, key))
+                        found.add("CONTAINER_REPLACED");
+                    if (NODE_IMMUTABLE.has(key))
+                        found.add("IMMUTABLE_FIELD_MUTATED");
+                }
+                if (key === "text") {
+                    if (op.action !== "makeText" && op.action !== "del")
+                        found.add("INVALID_FIELD_TYPE");
+                }
+                else if (op.action === "makeText")
+                    found.add("INVALID_FIELD_TYPE");
+                if (key === "placement" && op.action === "set" && typeof op.value === "string") {
+                    const set = registers.get(node) ?? new Set();
+                    set.add(op.value);
+                    registers.set(node, set);
+                }
+                return;
+            }
+            if (top === "placements" && path.length === 1) {
+                if (key !== undefined && op.action === "makeMap" && !has(op.obj, key))
+                    placements.set(key, { inserted: [] });
+                else if (key !== undefined)
+                    found.add("IMMUTABLE_FIELD_MUTATED");
+                return;
+            }
+            if (top === "placements" && path.length === 2) {
+                if (existed(op.obj)) {
+                    found.add("IMMUTABLE_FIELD_MUTATED");
+                    return;
+                }
+                const p = placements.get(String(second));
+                if (p !== undefined && op.action === "set" && typeof op.value === "string") {
+                    if (key === "node_id")
+                        p.node = op.value;
+                    if (key === "parent_id")
+                        p.parent = op.value;
+                }
+                if (op.action === "makeText")
+                    found.add("INVALID_FIELD_TYPE");
+                return;
+            }
+            if (top === "objects" && path.length >= 2) {
+                // SOP §30: every string of a Task is a scalar; §75: its identity is immutable.
+                if (op.action === "makeText")
+                    found.add("INVALID_FIELD_TYPE");
+                if (path.length === 2 && existed(op.obj) && key !== undefined && TASK_IMMUTABLE.has(key))
+                    found.add("IMMUTABLE_FIELD_MUTATED");
+                return;
+            }
+        });
+        // §12.1: ready is the scalar true, written once, by the creator's actor.
+        if (readyWrite !== undefined) {
+            const creator = creatorInChange ?? this.#section("created_by");
+            let creatorActor;
+            try {
+                creatorActor =
+                    creator === undefined
+                        ? undefined
+                        : toHex(deriveSectionActorId(this.#resource, parsePrincipalRef(creator)));
+            }
+            catch {
+                creatorActor = undefined;
+            }
+            if (readyWrite.del ||
+                readyWrite.again ||
+                readyWrite.value !== true ||
+                creatorActor !== decoded.actor)
+                found.add("IMMUTABLE_FIELD_MUTATED");
+        }
+        // A2: every inserted entry is a placement this change creates under that list's
+        // owner; every created placement is inserted exactly once and assigned to its node.
+        const sectionId = insertedInto.length > 0 ? this.#sectionId(ops, decoded.startOp, decoded.actor) : undefined;
+        for (const { owner, value } of insertedInto) {
+            const p = placements.get(value);
+            if (p === undefined)
+                found.add("PLACEMENT_NOT_ATOMIC");
+            else
+                p.inserted.push(owner === "section" ? (sectionId ?? "section") : owner);
+        }
+        for (const [pid, p] of placements) {
+            if (p.inserted.length !== 1 || p.inserted[0] !== p.parent)
+                found.add("PLACEMENT_NOT_ATOMIC");
+            if (p.node === undefined || !(registers.get(p.node)?.has(pid) ?? false))
+                found.add("PLACEMENT_NOT_ATOMIC");
+        }
+        const first = ADMISSION_ORDER.find((d) => found.has(d));
+        if (first !== undefined)
+            throw new SectionAdmissionError(first, `the change breaks SHARED-SECTIONS-PROFILE-01 §14.1: ${first}`);
+        // Admitted: the changes after it in the batch see it.
+        // Admitted: applied before the next check that reads the document.
+        this.#pending.push(change.bytes);
+    }
+    /** The SectionId: from the document, or from the change that creates the section. */
+    #sectionId(ops, startOp, actor) {
+        const known = this.#section("id");
+        if (known !== undefined)
+            return known;
+        let sectionObj;
+        ops.forEach((op, i) => {
+            if (op.obj === "_root" && op.key === "section" && op.action === "makeMap")
+                sectionObj = `${startOp + i}@${actor}`;
+        });
+        const set = ops.find((op) => op.obj === sectionObj && op.key === "id" && op.action === "set");
+        return typeof set?.value === "string" ? set.value : undefined;
+    }
+}
+//# sourceMappingURL=admission.js.map

package/dist/sections/data-profile.d.ts

@@ -0,0 +1,195 @@
+import { type DataUnitId, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CheckedChange } from "../admission/framing.js";
+import { SectionReplica } from "./replica.js";
+/**
+ * The Shared Sections Data Profile handler (LFCP-02-025): what the
+ * profile-agnostic Data Unit applier of @openlfcp/client calls once LFCP
+ * has accepted a unit of a org.openlfcp.shared-sections.v1 Resource. It
+ * matches the client's DataProfileHandler structurally; this package
+ * depends on neither client nor wire.
+ *
+ * - decode: the plaintext is [1, change], a change of the section actor of
+ *   the unit's signer (SHARED-SECTIONS-PROFILE-01 §2), else
+ *   CHANGE_ACTOR_MISMATCH: the refusal is the unit's, never the change's;
+ * - apply: the change goes through the section admission (§14.1,
+ *   SectionReplica.receiveChanges); it merges, waits for the changes it
+ *   depends on, is held (a taken actor sequence, SOP §14.1) or is refused;
+ * - exclude (G-EP7): the replica is rebuilt without given units;
+ * - checkpoint/restore: the persisted state, with the units of every merged
+ *   change and this actor's sequence (§9).
+ */
+/** An accepted unit as the applier passes it (structurally the client's ProfileUnit). */
+export interface SectionsUnit {
+    readonly unitId: DataUnitId;
+}
+/** The §11 codec of one unit (structurally the wire DataProfileCodec). */
+export interface SectionsCodec {
+    readonly dataProfile: string;
+    encode(change: CheckedChange): Uint8Array;
+    decode(plaintext: Uint8Array): CheckedChange;
+}
+/** The Snapshot codec: a full save framed as SOP §13 frames it (structurally DataProfileCodec). */
+export interface SectionsSnapshotCodec {
+    readonly dataProfile: string;
+    encode(save: Uint8Array): Uint8Array;
+    decode(plaintext: Uint8Array): Uint8Array;
+}
+/** The Snapshot binding of a sync client (structurally the client's SnapshotBinding). */
+export interface SectionsSnapshotBinding {
+    readonly codec: SectionsSnapshotCodec;
+    load(save: Uint8Array): void;
+    current(): Uint8Array;
+}
+/** The persisted state (structurally the storage ProfileCheckpoint). */
+export interface SectionsCheckpoint {
+    readonly resourceId: ResourceId;
+    readonly dataProfile: string;
+    readonly state: Uint8Array;
+    readonly actorSeq: number;
+    readonly units: readonly {
+        readonly unitId: DataUnitId;
+        readonly ref: string;
+    }[];
+}
+export interface SectionsApplyResult {
+    readonly merged: readonly DataUnitId[];
+    /** Nodes (and the section) whose projected state changed. */
+    readonly objects: readonly string[];
+    readonly diagnostics: readonly never[];
+    readonly pending?: string;
+    readonly held?: string;
+}
+export interface SectionsBatchResult {
+    readonly merged: readonly DataUnitId[];
+    readonly pending: readonly DataUnitId[];
+    readonly held: readonly DataUnitId[];
+    readonly rejected: readonly {
+        readonly unitId: DataUnitId;
+        readonly code: string;
+        readonly diagnostic: string;
+        readonly message: string;
+    }[];
+    readonly objects: readonly string[];
+    readonly diagnostics: readonly never[];
+}
+export interface SectionsExcludeResult {
+    readonly objects: readonly string[];
+    readonly pending: readonly DataUnitId[];
+    readonly released: readonly DataUnitId[];
+}
+/** A batch staged for commit (structurally the client's StagedOperation). */
+export interface SectionsStagedOperation {
+    readonly values: readonly CheckedChange[];
+    readonly affectedNodeIds: readonly string[];
+    readonly modelRevision: string;
+    apply(): void;
+    revert(): void;
+    writes(units: readonly {
+        readonly unitId: DataUnitId;
+    }[]): readonly {
+        readonly op: "put-profile-checkpoint";
+        readonly checkpoint: SectionsCheckpoint;
+    }[];
+    committed(unitIds: readonly DataUnitId[]): void;
+}
+/** How a sync client commits section batches (structurally the client's CommitBinding). */
+export interface SectionsCommitBinding {
+    readonly codec: SectionsCodec;
+    stage(intents: readonly unknown[]): SectionsStagedOperation | null;
+    /** SDK-SECTIONS-INTEGRATION-01 §4.3: ready or importing; undefined before section.create. */
+    section(): "ready" | "importing" | undefined;
+}
+/** SDK-SECTIONS-INTEGRATION-01 §5 nodes-changed: what changed, and why. */
+export interface SectionsNodesChanged {
+    readonly nodeIds: readonly string[];
+    readonly origin: "local" | "remote" | "rebuild";
+    readonly modelRevision: string;
+}
+export declare class SharedSectionsDataProfile {
+    #private;
+    readonly dataProfile = "org.openlfcp.shared-sections.v1";
+    constructor(replica: SectionReplica);
+    /** The current replica (a rebuild replaces it). */
+    get replica(): SectionReplica;
+    /** §5 nodes-changed for remote merges, rebuilds and recorded local changes. */
+    onNodesChanged(listener: (event: SectionsNodesChanged) => void): () => void;
+    /** The codec of one unit, bound to its signer's section actor (§2). */
+    codecFor(unit: {
+        readonly resourceId: ResourceId;
+        readonly actor: PrincipalId;
+    }): SectionsCodec;
+    /**
+     * SDK-SECTIONS-INTEGRATION-01 §3.1: the binding through which a sync
+     * client commits this Principal's batches (structurally the client's
+     * CommitBinding): `stage` validates the intents and changes a copy of the
+     * replica, splitting what one change cannot carry (§12); the staged
+     * operation adopts it, writes the checkpoint with the new units and
+     * records them once committed.
+     */
+    commitBinding(principal: PrincipalId): SectionsCommitBinding;
+    /**
+     * Records which change one of this client's own units carries: the change
+     * is in the replica already (SectionReplica.stage, then apply). A later
+     * exclusion of the unit rebuilds without it, and the checkpoint keeps it.
+     */
+    recordLocal(unitId: DataUnitId, change: {
+        readonly hash: string;
+        readonly affectedNodeIds?: readonly string[];
+    }): void;
+    /** Merges one accepted unit's change; throws when the section admission refuses it. */
+    apply(unit: SectionsUnit, change: CheckedChange): SectionsApplyResult;
+    /**
+     * Merges many accepted units at once, with every unit still waiting: one
+     * admission and one engine call for a catch-up. A refused change rejects
+     * only its unit; the units that depend on it wait.
+     */
+    applyBatch(units: readonly {
+        readonly unit: SectionsUnit;
+        readonly value: CheckedChange;
+    }[]): SectionsBatchResult;
+    /**
+     * G-EP7: the state without `unitIds`, rebuilt from the remaining changes.
+     * Merged units whose changes build on an excluded one wait again; held
+     * units are retried, since the rebuild may free their actor sequence.
+     */
+    exclude(unitIds: readonly DataUnitId[]): SectionsExcludeResult;
+    /** Whether this handler holds the unit's change (merged, recorded, waiting or held). */
+    has(unitId: DataUnitId): boolean;
+    heldUnits(): DataUnitId[];
+    pendingUnits(): DataUnitId[];
+    /** The Snapshot codec (SOP §13): the full save, framed. */
+    snapshotCodec(): SectionsSnapshotCodec;
+    /** The state to publish as a Snapshot: the replica's full save. */
+    snapshotState(): Uint8Array;
+    /**
+     * Loads a received Snapshot's full save (SOP §13, §14; LFCP-02-028):
+     * every change it holds passes the section admission (§14.1), so a
+     * Snapshot holding a refused change is rejected and nothing changes;
+     * this replica's changes, local work the Snapshot lacks included, are
+     * kept on top. Buffered units whose dependencies it brings are merged.
+     * Returns the nodes that changed and the units merged from the buffer.
+     */
+    loadSnapshot(save: Uint8Array): {
+        readonly nodeIds: readonly string[];
+        readonly merged: readonly DataUnitId[];
+    };
+    /** The binding through which a sync client loads and publishes Snapshots. */
+    snapshotBinding(): SectionsSnapshotBinding;
+    /** Forgets the whole state, keeping the §9 sequence (SNAP-EP). */
+    reset(): void;
+    /**
+     * The state to persist: the full save, this actor's sequence and each
+     * merged unit's change, with `local`, this client's units committed in
+     * the same transaction as the checkpoint.
+     */
+    checkpoint(local?: readonly {
+        readonly unitId: DataUnitId;
+        readonly ref: string;
+    }[]): SectionsCheckpoint;
+    /** The handler of a persisted checkpoint; its replica writes nothing below the checkpoint's sequence (§9). */
+    static restore(checkpoint: SectionsCheckpoint, options: {
+        readonly resource: ResourceId;
+        readonly principal: PrincipalId;
+    }): SharedSectionsDataProfile;
+}
+//# sourceMappingURL=data-profile.d.ts.map