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

package/dist/sections/replica.d.ts

@@ -0,0 +1,412 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type SnapshotLimits } from "../admission/limits.js";
+import { type ReplicaIntent, type TaskView } from "../replica.js";
+import type { Task } from "../task.js";
+import type { Json } from "../validate.js";
+import { type SectionValidation } from "./schema.js";
+import { type SectionTree } from "./tree.js";
+import { type ListStyle } from "./values.js";
+/**
+ * The writer of a SHARED-SECTIONS-PROFILE-01 document (LFCP-02-012): the
+ * section and creation intents of §11, and the SOP Task intents on the
+ * section's Tasks (§2), committed as batches.
+ *
+ * - One batch is one Automerge change (§12), with time 0 and the actor of
+ *   §2 for (Resource, Principal); the batch is validated as a whole, and
+ *   one refused intent refuses it with nothing written
+ *   (SDK-SECTIONS-INTEGRATION-01 §3.1).
+ * - The caller allocates every node and Task ID and the SDK uses them;
+ *   PlacementIds are the SDK's unless the intent names one.
+ * - A node, its placement, the placement's entry in the parent's children
+ *   list and the node's `placement` register are written in one change
+ *   (§4.3); a Task node and its Task are created together (§4.2).
+ * - Writes touch single properties; unknown fields and extensions survive.
+ *
+ * Moves, lifecycle, Text edits and the effective tree come with LFCP-02-013
+ * to 016; batches over the §16.2 budgets are refused until 016 splits them.
+ */
+/** Why a batch was refused before anything was written (SDK-SECTIONS-INTEGRATION-01 §3.6). */
+export type SectionIntentCode = 
+/** The document is not a valid section (§14.2 section-level problems). */
+"SECTION_INVALID"
+/** section.create on a document that already has a root, or another intent before one. */
+ | "SECTION_EXISTS"
+/** The section has no `ready` and this writer is not its creator (§12.1). */
+ | "SECTION_IMPORTING"
+/** A new ID is not a canonical UUIDv7 or is already used in the Resource (§3). */
+ | "ID_IN_USE"
+/** The parent is missing, invalid, deleted, in conflict or cannot hold content (§4.2, §6). */
+ | "INVALID_PARENT"
+/** `after` is not a visible child of the parent, or is the moved node (§6). */
+ | "INVALID_PREDECESSOR"
+/** The node is invalid, collides, or has concurrent placements: resolve it first (§7, §8). */
+ | "NODE_IN_CONFLICT"
+/** The intent names a node the section does not have. */
+ | "UNKNOWN_NODE"
+/** A value outside its domain: an ID, a list style, a timestamp, a string (§3, §4). */
+ | "INVALID_INTENT"
+/** The batch is over an authoring budget of §16.2. */
+ | "OVER_BUDGET"
+/** A Text position names a base revision the SDK cannot rebase onto the current Text (§10). */
+ | "STALE_BASE";
+/** A batch refused before commit, with the intent it concerns (SDK-SECTIONS-INTEGRATION-01 §3.6). */
+export declare class SectionIntentError extends Error {
+    readonly code: SectionIntentCode;
+    /** The index of the refused intent in its batch. */
+    readonly intentIndex: number | undefined;
+    /** The node the refusal concerns, when there is one. */
+    readonly nodeId: string | undefined;
+    constructor(code: SectionIntentCode, message: string, intentIndex?: number, nodeId?: string);
+}
+/** Where a new node goes: under `parent`, right after the visible sibling `after` (null: first). */
+interface Position {
+    /** The section ID, or a task or item node. */
+    readonly parent: string;
+    /** The preceding visible sibling, a node ID; null puts the node first (§6). */
+    readonly after: string | null;
+    /** The new PlacementId; generated when absent. */
+    readonly placementId?: string;
+}
+export type SectionIntent = {
+    readonly intent: "section.create";
+    readonly sectionId: string;
+    readonly title: string;
+    readonly createdBy: PrincipalId;
+    readonly createdAt?: string;
+    /** §12.1: false while an import continues in later changes; the default writes `ready`. */
+    readonly ready?: boolean;
+} | {
+    readonly intent: "section.set_title";
+    readonly title: string;
+}
+/** §12.1: the last change of an import writes `ready`; the creator only, once. */
+ | {
+    readonly intent: "section.mark_ready";
+} | ({
+    readonly intent: "task.create_in_section";
+    /** The Task, from createTask (§53); its ID is the node's ID. */
+    readonly task: Task;
+    readonly listStyle?: ListStyle;
+} & Position) | ({
+    readonly intent: "paragraph.create" | "item.create" | "raw.create";
+    readonly id: string;
+    readonly createdBy: PrincipalId;
+    readonly createdAt?: string;
+    /** Markdown inline source (§4.2); collaborative Text. */
+    readonly text: string;
+    /** item.create only. */
+    readonly listStyle?: ListStyle;
+} & Position)
+/** §5, §6: a fresh placement under `parent`; the node keeps its identity and subtree. */
+ | ({
+    readonly intent: "node.move";
+    readonly id: string;
+} & Position)
+/**
+ * §8: a fresh placement written to a node's register, superseding every
+ * placement observed at this causal point, conflicted or not.
+ */
+ | ({
+    readonly intent: "node.resolve_placement";
+    readonly id: string;
+} & Position)
+/**
+ * §8: relocates several nodes atomically, as for a parent cycle; each
+ * move is checked against the moves before it, so the result is acyclic.
+ */
+ | {
+    readonly intent: "structure.resolve";
+    readonly moves: readonly ({
+        readonly id: string;
+    } & Position)[];
+}
+/**
+ * §9: the lifecycle of a node: a Task node's Task, any other node itself.
+ * Always a fresh causal write, also when the value is already visible;
+ * descendants are not rewritten.
+ */
+ | {
+    readonly intent: "node.delete" | "node.restore";
+    readonly id: string;
+}
+/**
+ * §10: edits of a node's existing Text, in Unicode scalar positions of the
+ * Text at `base` (a modelRevision): sorted, not overlapping, each against
+ * the base text as CodeMirror changes are. They are rebased onto the
+ * current Text; a deleted range that changed since `base` is STALE_BASE.
+ */
+ | {
+    readonly intent: "text.edit";
+    readonly id: string;
+    readonly base: string;
+    readonly edits: readonly TextEdit[];
+}
+/**
+ * §10: the node keeps the prefix before `at` (a scalar position at
+ * `base`); a new node of the same kind, `newId`, gets the suffix right
+ * after it under the same parent. An item's children stay with it.
+ */
+ | ({
+    readonly intent: "paragraph.split" | "item.split";
+    readonly id: string;
+    readonly base: string;
+    readonly at: number;
+    readonly newId: string;
+    readonly createdBy: PrincipalId;
+} & Pick<Position, "placementId">)
+/**
+ * §10: two adjacent paragraphs, or items of one list style, without
+ * children: `id` gets `separator` (default LF) and `second`'s current
+ * text, and `second` is deleted with its Text history kept.
+ */
+ | {
+    readonly intent: "node.join";
+    readonly id: string;
+    readonly second: string;
+    readonly separator?: string;
+}
+/** §4.2: ordered or bullet list membership, on task and item nodes. */
+ | {
+    readonly intent: "node.set_list_style";
+    readonly id: string;
+    readonly listStyle: ListStyle;
+}
+/** A SHARED-OBJECTS-PROFILE-01 Task intent on a Task of this section (§2). */
+ | Exclude<ReplicaIntent, {
+    intent: "task.create";
+}>;
+/** One Text edit in Unicode scalar positions (§10). */
+export interface TextEdit {
+    readonly index: number;
+    readonly deleteCount: number;
+    readonly insert: string;
+}
+/** §16.2: what one change may carry. */
+export declare const AUTHORING_BUDGET: Readonly<{
+    textOperations: 8192;
+    createdNodes: 256;
+}>;
+/** One change of a batch, as its Data Unit carries it. */
+export interface SectionChangePart {
+    readonly change: Uint8Array;
+    /** The §11 Data Unit plaintext [1, change]. */
+    readonly plaintext: Uint8Array;
+    readonly hash: string;
+    readonly seq: number;
+}
+/**
+ * A committed batch. A batch over the §16.2 budgets is several changes
+ * (§12, §12.3): `parts`, in order, one Data Unit each; `change`, `hash`,
+ * `seq` and `plaintext` name the last of them (the only one, usually).
+ */
+export interface SectionLocalChange {
+    /** The intents of the batch, by name. */
+    readonly intents: readonly string[];
+    /** Every change of the batch, in order. */
+    readonly parts: readonly SectionChangePart[];
+    readonly change: Uint8Array;
+    /** The §11 Data Unit plaintext [1, change]. */
+    readonly plaintext: Uint8Array;
+    readonly hash: string;
+    readonly seq: number;
+    /** Nodes the batch creates or writes; the section ID when it writes the section. */
+    readonly affectedNodeIds: readonly string[];
+    /** The document heads after the change, sorted, as one string (SDK-SECTIONS-INTEGRATION-01 §3.2). */
+    readonly modelRevision: string;
+}
+/** A received change with the Principal that signed its Data Unit (§2). */
+export interface SectionUnit {
+    readonly bytes: Uint8Array;
+    readonly signer?: PrincipalId;
+}
+/** A received change that was not merged. */
+export interface SectionRefusal {
+    /** Its position in the received list. */
+    readonly index: number;
+    /**
+     * Its change hash. A change the SOP checks refused is never decoded: its
+     * hash is read from its bytes (SHA-256 of the chunk from the type byte),
+     * and is undefined only when the bytes are not one readable change chunk.
+     */
+    readonly hash: string | undefined;
+    /** The §14.1 diagnostic (SOP §74.1 for the inherited checks), or ACTOR_EQUIVOCATION when held. */
+    readonly diagnostic: string;
+    /** Held (SOP §14.1, POST-001): its actor and sequence belong to another change; retried after a rebuild. */
+    readonly held: boolean;
+    readonly message: string;
+}
+export interface SectionReceiveResult {
+    /** Merged now, in causal order. */
+    readonly admitted: readonly string[];
+    /** Already in the document. */
+    readonly duplicates: readonly string[];
+    /** Missing a dependency: not received yet, or refused, or waiting itself. */
+    readonly waiting: readonly string[];
+    readonly refused: readonly SectionRefusal[];
+}
+/** One node of a snapshot (SectionReplica.snapshot). */
+export interface SectionSnapshotNode {
+    readonly kind: string;
+    /** The section ID or the parent node of the selected placement; undefined when it has none. */
+    readonly parent: string | undefined;
+    /** Paragraph, item and raw nodes: the Text, with LF line breaks. */
+    readonly text?: string;
+    readonly listStyle?: ListStyle;
+    /** Task nodes: the Task's ID (the node's own). */
+    readonly taskId?: string;
+    /** Deleted itself (a Task node: its Task); delete projected lines only for this. */
+    readonly deleted: boolean;
+    /** Deleted itself or under a deleted ancestor: not shown. */
+    readonly hidden: boolean;
+}
+/** One synchronous read of a section on one revision (SectionReplica.snapshot). */
+export interface SectionSnapshot {
+    /** The document heads, sorted, as one string: a receipt's modelRevision, text.edit's base. */
+    readonly revision: string;
+    readonly classification: SectionTree["classification"];
+    readonly title: {
+        readonly value: string | undefined;
+        readonly conflicts: readonly string[];
+    };
+    /** Every node but colliding ones, by ID. */
+    readonly nodes: Readonly<Record<string, SectionSnapshotNode>>;
+    /** The visible nodes in projection order (preorder), with parent and depth. */
+    readonly order: SectionTree["tree"];
+    readonly problems: {
+        readonly recovery: SectionTree["recovery"];
+        readonly invalid: SectionTree["invalid"];
+        readonly collisions: SectionTree["collisions"];
+        readonly retainedConcurrentEdits: SectionTree["retainedConcurrentEdits"];
+        readonly scalarConflicts: SectionTree["scalarConflicts"];
+    };
+}
+/** A batch validated and changed on a copy (SectionReplica.stage): applied only on request. */
+export interface StagedSectionChange {
+    readonly change: SectionLocalChange;
+    /** Adopts the change; throws if the replica moved on since staging. Idempotent. */
+    apply(): void;
+    /**
+     * Undoes apply() while nothing came after it: the replica holds the
+     * document it had before (its storage commit failed, or the operation
+     * had committed already). Idempotent.
+     */
+    revert(): void;
+}
+export interface SectionReplicaOptions {
+    readonly resource: ResourceId;
+    readonly principal: PrincipalId;
+    /**
+     * SOP §9: the actor sequence this device already used (a restored
+     * checkpoint's). Below it the replica writes nothing: its next change
+     * would reuse a sequence number another change of this actor has.
+     */
+    readonly minSeq?: number;
+}
+export declare class SectionReplica {
+    #private;
+    readonly resource: ResourceId;
+    /** The §2 Automerge actor ID. */
+    readonly actorId: Uint8Array;
+    private constructor();
+    /** This actor's latest change sequence in the document (0 when it has none). */
+    get actorSeq(): number;
+    /** SOP §9: whether this replica may write (it is not behind its actor's used sequence). */
+    get writable(): boolean;
+    /**
+     * §12.1: "ready" once the section's `ready` is written, "importing"
+     * before, undefined while the document has no section. Reads one
+     * register; validate() tells whether the section is valid.
+     */
+    sectionState(): "ready" | "importing" | undefined;
+    /** Whether the document holds the change with this hex hash. */
+    hasChange(hash: string): boolean;
+    /**
+     * SOP §14.1 (G-EP7): the replica rebuilt from its changes minus `exclude`
+     * (change hashes); changes that depend on an excluded one are unapplied
+     * too. An excluded change of this actor is not lost state (§9): the
+     * rebuilt replica writes on from its own sequence.
+     */
+    rebuildWithout(exclude: Iterable<string>): {
+        readonly replica: SectionReplica;
+        readonly unapplied: readonly string[];
+    };
+    /**
+     * This replica merged with a received Snapshot's full save (SOP §13,
+     * §14): every change the save holds is admitted as if received one by
+     * one (the SOP checks and A1–A5, §14.1), on an empty replica of this
+     * actor, so a Snapshot that holds a change admission refuses is
+     * rejected; then this replica's own changes follow, so local work the
+     * Snapshot lacks is kept. The §9 sequence carries over. Throws
+     * PROFILE_INVALID (with the refused change's diagnostic, or
+     * INVALID_AUTOMERGE_BYTES) and keeps this replica unchanged.
+     */
+    mergeSave(save: Uint8Array, limits?: SnapshotLimits): SectionReplica;
+    /** An empty replica of the same actor that keeps the §9 sequence (SNAP-EP reset). */
+    emptied(): SectionReplica;
+    /** An empty document, for section.create or for receiving. */
+    static empty(opts: SectionReplicaOptions): SectionReplica;
+    /** Loads a full save; SOP §13.1 limits unless it is this device's own state. */
+    static fromSave(save: Uint8Array, opts: SectionReplicaOptions, limits?: SnapshotLimits | "local-state"): SectionReplica;
+    /** The replica of an admitted change set; changes missing a dependency are returned unapplied. */
+    static fromChanges(changes: Iterable<Uint8Array>, opts: SectionReplicaOptions): {
+        readonly replica: SectionReplica;
+        readonly unapplied: readonly string[];
+    };
+    /**
+     * Receives changes others wrote, as LFCP accepted them (§14.1): each
+     * passes the inherited SOP checks (framing, §11.1 expansion, the signer's
+     * actor when `signer` is given, the sequence check, holding a taken
+     * actor sequence) and the section rules A1–A5 and §12.1, against its
+     * causal history, before the engine applies any. A refused change is
+     * never merged; the changes that depend on it wait.
+     */
+    receiveChanges(items: readonly (Uint8Array | SectionUnit)[]): SectionReceiveResult;
+    /**
+     * Everything an editor projects, in one synchronous read of one revision:
+     * the title (and its concurrent values), each node, the visible order,
+     * and the problems to show. `revision` is the modelRevision of a commit
+     * receipt and the `base` of text.edit.
+     */
+    snapshot(): SectionSnapshot;
+    /**
+     * The Task of a task node (§4.2: stored under `/objects/<id>`, the node's
+     * ID) with its conflict metadata, in the form SharedObjectsReplica.task
+     * gives (SOP §99); undefined if there is no object or it is not a Task.
+     */
+    task(id: string): TaskView | undefined;
+    /** §3, §4, §14.2. */
+    validate(): SectionValidation;
+    /** §7, §9, §14.3: the effective tree, hidden nodes and structural facts. */
+    tree(): SectionTree;
+    /** The document heads, sorted, as one string. */
+    revision(): string;
+    /**
+     * The Shared Objects (by ID) that changes since `revision`, an earlier
+     * revision() of this document, wrote: a Task's fields, conflicts
+     * included, live there and not in its node. From A.diff, without reading
+     * the document; undefined when this document does not hold `revision`
+     * (a rebuild, or another document).
+     */
+    objectsTouchedSince(revision: string): readonly string[] | undefined;
+    save(): Uint8Array;
+    /** Every change of the document, in causal order. */
+    changes(): Uint8Array[];
+    /** The current state as JSON: scalar strings and Text read as strings. */
+    toJSON(): Json;
+    /**
+     * Validates `intents` as one batch and commits them as one change.
+     * Returns null when the batch writes nothing. Throws SectionIntentError,
+     * or ProfileError / ObjectIdCollisionError for a Task the SOP refuses.
+     */
+    commit(intents: readonly SectionIntent[]): SectionLocalChange | null;
+    /**
+     * Validates `intents` as one batch and prepares their change without
+     * changing this replica: `apply()` adopts it, once the caller has stored
+     * it durably (its Data Unit, outbound entry and checkpoint). A batch that
+     * is never applied leaves the replica as it was. Null when the batch
+     * writes nothing.
+     */
+    stage(intents: readonly SectionIntent[]): StagedSectionChange | null;
+}
+export {};
+//# sourceMappingURL=replica.d.ts.map