@openlfcp/shared-objects 0.1.1 → 0.1.2

package/dist/replica.d.ts

@@ -1,277 +0,0 @@
-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