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

package/dist/admission/sequence.d.ts

@@ -0,0 +1,81 @@
+import { LfcpError } from "@openlfcp/core";
+import { ProfileInvalidError } from "../profile-invalid.js";
+import { type CheckedChange } from "./framing.js";
+import type { ReferenceHistory } from "./references.js";
+/**
+ * SHARED-OBJECTS-PROFILE-01 §14.1, the sequence admission, for any profile
+ * that inherits it (SHARED-SECTIONS-PROFILE-01 §2): which received changes
+ * the engine may apply, in which order, and why the others wait or are
+ * refused. It reads the document through `DocumentSequences` and knows no
+ * profile semantics; a profile adds its own checks through `accept`.
+ */
+/** What admission needs to know of the document. */
+export interface DocumentSequences {
+    /** Whether the document holds the change with this hex hash. */
+    hasChange(hash: string): boolean;
+    /** The actor's latest sequence number in the document; 0 when it has none. */
+    latestSeq(actor: string): number;
+    /**
+     * The document's changes as §11.4 reads them. When given, a change whose
+     * operations refer outside its causal history is refused; admitBatch adds
+     * the changes it admits (the caller rebuilds it if the engine then fails).
+     */
+    readonly references?: ReferenceHistory;
+}
+/** A change admission refused: held (§14.1, POST-001) or invalid. */
+export interface RefusedChange {
+    readonly change: CheckedChange;
+    readonly error: LfcpError;
+    /**
+     * The actor and sequence number belong to a different change of the
+     * document (ACTOR_EQUIVOCATION): a profile holds it and retries it after a
+     * rebuild that removes changes; it is not profile-invalid.
+     */
+    readonly held: boolean;
+}
+export interface BatchAdmission {
+    /** Changes to apply, in an order where each comes after its dependencies. */
+    readonly admitted: readonly CheckedChange[];
+    /** Changes the document holds already. */
+    readonly duplicates: readonly CheckedChange[];
+    /** Changes whose dependencies are neither in the document nor admitted. */
+    readonly waiting: readonly CheckedChange[];
+    /** Held and invalid changes, in the order they were decided. */
+    readonly refused: readonly RefusedChange[];
+}
+/**
+ * Admits many changes at once: each once its dependencies inside the batch
+ * are admitted (Kahn's order), against the document and the batch so far.
+ * A taken sequence is held, a change naming an actor the document does not
+ * know or skipping a sequence is INVALID_AUTOMERGE_BYTES (§11.1, §14.1),
+ * and `accept` (the profile's own checks, e.g. §11.2 depth) may refuse by
+ * throwing; a refused change does not stop the others, and the changes
+ * that depend on it wait. `changes` must hold each hash once.
+ */
+export declare function admitBatch(changes: readonly CheckedChange[], doc: DocumentSequences, accept?: (change: CheckedChange) => void): BatchAdmission;
+/** One change against the document (receiveChange): what §14.1 says of it. */
+export type ChangeAdmission = {
+    readonly kind: "duplicate";
+} | {
+    readonly kind: "missing";
+    readonly missing: readonly string[];
+}
+/** Its actor and sequence belong to another change: held (§14.1, POST-001). */
+ | {
+    readonly kind: "held";
+    readonly error: LfcpError;
+} | {
+    readonly kind: "invalid";
+    readonly error: ProfileInvalidError;
+}
+/** The actor's next change, every dependency present: the engine may apply it. */
+ | {
+    readonly kind: "next";
+};
+/**
+ * One change: a duplicate, missing dependencies, a held sequence, an actor
+ * the document does not know (§11.1) or a skipped sequence (§14.1), checked
+ * in that order before the engine sees it; or the actor's next change.
+ */
+export declare function admitChange(change: CheckedChange, doc: DocumentSequences): ChangeAdmission;
+//# sourceMappingURL=sequence.d.ts.map

package/dist/admission/sequence.js

@@ -0,0 +1,133 @@
+import { LfcpError } from "@openlfcp/core";
+import { ProfileInvalidError } from "../profile-invalid.js";
+import { parsedOf } from "./framing.js";
+/** §11.4: a refusal for a change whose operations refer outside its history, or null. */
+function referenceRefusal(c, doc) {
+    const rule = doc.references?.check(parsedOf(c)) ?? null;
+    return rule === null
+        ? null
+        : new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `the change's operations refer outside its causal history (§11.4 ${rule})`);
+}
+const held = (c) => new LfcpError("ACTOR_EQUIVOCATION", `actor ${c.actor} sequence ${c.seq} already has a different change (§26.2)`);
+/**
+ * Admits many changes at once: each once its dependencies inside the batch
+ * are admitted (Kahn's order), against the document and the batch so far.
+ * A taken sequence is held, a change naming an actor the document does not
+ * know or skipping a sequence is INVALID_AUTOMERGE_BYTES (§11.1, §14.1),
+ * and `accept` (the profile's own checks, e.g. §11.2 depth) may refuse by
+ * throwing; a refused change does not stop the others, and the changes
+ * that depend on it wait. `changes` must hold each hash once.
+ */
+export function admitBatch(changes, doc, accept = () => undefined) {
+    const all = [...changes];
+    const index = new Map(all.map((c, i) => [c.hash, i]));
+    const blocking = all.map(() => 0);
+    const unreachable = all.map(() => false);
+    const children = new Map();
+    all.forEach((c, i) => {
+        for (const d of c.deps) {
+            if (doc.hasChange(d))
+                continue;
+            if (index.has(d)) {
+                blocking[i] = blocking[i] + 1;
+                children.set(d, [...(children.get(d) ?? []), i]);
+            }
+            else
+                unreachable[i] = true;
+        }
+    });
+    const seqs = new Map();
+    const latest = (actor) => seqs.get(actor) ?? doc.latestSeq(actor);
+    const admitted = [];
+    const duplicates = [];
+    const refused = [];
+    const done = all.map(() => false);
+    const ready = all.flatMap((_, i) => (blocking[i] === 0 && !unreachable[i] ? [i] : []));
+    for (let k = 0; k < ready.length; k++) {
+        const i = ready[k];
+        const c = all[i];
+        done[i] = true;
+        if (doc.hasChange(c.hash))
+            duplicates.push(c);
+        else if (c.seq <= latest(c.actor)) {
+            refused.push({ change: c, error: held(c), held: true });
+            continue;
+        }
+        else if (c.otherActors.some((a) => latest(a) === 0)) {
+            refused.push({
+                change: c,
+                error: new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `the change names an actor unknown to this document (§11.1)`),
+                held: false,
+            });
+            continue;
+        }
+        else if (c.seq !== latest(c.actor) + 1) {
+            refused.push({
+                change: c,
+                error: new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `actor ${c.actor} sequence ${c.seq} skips sequence ${latest(c.actor) + 1} (§14.1)`),
+                held: false,
+            });
+            continue;
+        }
+        else {
+            const references = referenceRefusal(c, doc);
+            if (references !== null) {
+                refused.push({ change: c, error: references, held: false });
+                continue;
+            }
+            try {
+                accept(c);
+            }
+            catch (e) {
+                refused.push({ change: c, error: e, held: false });
+                continue;
+            }
+            seqs.set(c.actor, c.seq);
+            doc.references?.add(c.hash, parsedOf(c));
+            admitted.push(c);
+        }
+        for (const child of children.get(c.hash) ?? []) {
+            blocking[child] = blocking[child] - 1;
+            if (blocking[child] === 0 && !unreachable[child])
+                ready.push(child);
+        }
+    }
+    return Object.freeze({
+        admitted: Object.freeze(admitted),
+        duplicates: Object.freeze(duplicates),
+        waiting: Object.freeze(all.filter((_, i) => !done[i])),
+        refused: Object.freeze(refused),
+    });
+}
+/**
+ * One change: a duplicate, missing dependencies, a held sequence, an actor
+ * the document does not know (§11.1) or a skipped sequence (§14.1), checked
+ * in that order before the engine sees it; or the actor's next change.
+ */
+export function admitChange(change, doc) {
+    if (doc.hasChange(change.hash))
+        return { kind: "duplicate" };
+    const missing = change.deps.filter((d) => !doc.hasChange(d));
+    if (missing.length > 0)
+        return { kind: "missing", missing: Object.freeze(missing) };
+    const latest = doc.latestSeq(change.actor);
+    if (change.seq <= latest)
+        return { kind: "held", error: held(change) };
+    const unknown = change.otherActors.find((a) => doc.latestSeq(a) === 0);
+    if (unknown !== undefined)
+        return {
+            kind: "invalid",
+            error: new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `the change names actor ${unknown}, unknown to this document (§11.1)`),
+        };
+    if (change.seq !== latest + 1)
+        return {
+            kind: "invalid",
+            error: new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `actor ${change.actor} sequence ${change.seq} skips sequence ${latest + 1} (§14.1)`),
+        };
+    // §11.4: checked only; the caller adds the change once the engine applied it.
+    const references = referenceRefusal(change, doc);
+    if (references !== null)
+        return { kind: "invalid", error: references };
+    return { kind: "next" };
+}
+//# sourceMappingURL=sequence.js.map

package/dist/data-profile.d.ts

@@ -1,5 +1,5 @@
 import { type DataUnitId, type PrincipalId, type ResourceId } from "@openlfcp/core";
-import { type CheckedChange } from "./automerge-bytes.js";
+import { type CheckedChange } from "./admission/framing.js";
 import { type ObjectChange, type ReplicaOptions, SharedObjectsReplica } from "./replica.js";
 /**
  * The Shared Objects Data Profile handler (LFCP-033): what a profile-

package/dist/data-profile.js

@@ -1,7 +1,7 @@
 import { LfcpError, toHex, } from "@openlfcp/core";
-import { frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./automerge-bytes.js";
+import { checkChangeActor } from "./admission/actor.js";
+import { frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./admission/framing.js";
 import { SharedObjectsReplica } from "./replica.js";
-import { ProfileInvalidError } from "./validate.js";
 import { deriveActorId, PROFILE_ID } from "./values.js";
 export class SharedObjectsDataProfile {
     dataProfile = PROFILE_ID;
@@ -139,11 +139,7 @@ export class SharedObjectsDataProfile {
         // §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;
-        };
+        const bound = (change) => checkChangeActor(change, actor);
         return {
             dataProfile: PROFILE_ID,
             encode: (change) => frameChange(bound(change).bytes),

package/dist/index.d.ts

@@ -4,8 +4,8 @@
  * 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 CheckedChange, checkChange, checkSaveHeader, frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./admission/framing.js";
+export { CHANGE_LIMITS, type ChunkExpansion, checkChangeExpansion, checkSnapshotExpansion, MAX_DOCUMENT_DEPTH, SNAPSHOT_LIMITS_FLOOR, type SnapshotLimits, } from "./admission/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 { applyBatchChecked, applyChecked, type BatchReceiveResult, type BuiltReplica, isWasmTrap, 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";

package/dist/index.js

@@ -4,8 +4,8 @@
  * 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 { checkChange, checkSaveHeader, frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./admission/framing.js";
+export { CHANGE_LIMITS, checkChangeExpansion, checkSnapshotExpansion, MAX_DOCUMENT_DEPTH, SNAPSHOT_LIMITS_FLOOR, } from "./admission/limits.js";
 export { SharedObjectsDataProfile, } from "./data-profile.js";
 export { applyBatchChecked, applyChecked, isWasmTrap, 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";

package/dist/replica.d.ts

@@ -1,7 +1,7 @@
 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 CheckedChange } from "./admission/framing.js";
+import { type SnapshotLimits } from "./admission/limits.js";
 import { type Task, type TaskIntent } from "./task.js";
 import { type Json, type ProfileProblem, type RootValidation } from "./validate.js";
 /**
@@ -141,13 +141,43 @@ export interface BuiltReplica {
     readonly unapplied: readonly CheckedChange[];
 }
 type Doc = A.Doc<Record<string, unknown>>;
+type AMap = 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;
+/**
+ * §99: the Task under `id` of `objects` (the document's `objects` map) with
+ * conflict metadata, or undefined if there is no object or it is not a Task.
+ * Shared by the Shared Objects and the Shared Sections replicas.
+ */
+export declare function taskView(doc: A.Doc<unknown>, objects: AMap | undefined, id: string): TaskView | undefined;
+/**
+ * §74.1 problems of one object as stored at `/objects/<id>` of `doc`: its
+ * logical values, every collaborative Text in it (§30) and every concurrent
+ * value of its scalar registers (§45), one diagnostic per field. Shared by
+ * every profile whose Tasks are SOP Tasks (SHARED-SECTIONS-PROFILE-01 §2).
+ */
+export declare function storedObjectProblems(doc: A.Doc<unknown>, stored: AMap, id: string): ProfileProblem[];
+/** A Task intent checked against the stored objects, ready to write inside a change. */
+export interface PreparedTaskIntent {
+    /** The Task it writes. */
+    readonly id: string;
+    /** Writes the intent into the `objects` map of a change's document. */
+    readonly perform: (objects: Record<string, unknown>) => void;
+}
+/**
+ * Checks one Task intent against `objects`, the stored objects map of
+ * `doc`, before anything is written: §21 no reuse of an Object ID on
+ * create, §74 the Task after the intent is valid, and no Text left in a
+ * field it writes. Throws ProfileError or ObjectIdCollisionError. Shared by
+ * every profile whose Tasks are SOP Tasks (SHARED-SECTIONS-PROFILE-01 §2).
+ */
+export declare function prepareTaskIntent(doc: A.Doc<unknown>, objects: Record<string, unknown>, intent: ReplicaIntent): PreparedTaskIntent;
 /**
  * Whether a thrown value is a wasm trap (the engine's module is dead, not
  * the change refused): it is rethrown as it is, never turned into
  * INVALID_AUTOMERGE_BYTES, so a crash-loop breaker sees it.
  */
+/** A wasm trap (RuntimeError, or a terminated module): fatal, not a refusable change. */
 export declare function isWasmTrap(e: unknown): boolean;
 /**
  * Applies one change that passed the receive checks. Automerge can throw