@openlfcp/shared-objects 0.1.1 → 0.1.3

package/README.md

@@ -20,9 +20,9 @@ reaches the replica (§95). The replica has no Markdown or editor concepts.
 
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
-at `mvp-0.1-baseline.8`, not every deferred WIRE-01 feature. It does not
+at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.1`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.3`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Automerge and WebAssembly
 

package/dist/data-profile.d.ts

@@ -14,7 +14,10 @@ import { type ObjectChange, type ReplicaOptions, SharedObjectsReplica } from "./
  *   every buffered change it unblocks merges with it;
  * - one object becoming profile-invalid is a diagnostic, never a refusal:
  *   the other objects stay usable (§77);
- * - exclude (§14.1, G-EP7): rebuilds the replica without given units.
+ * - exclude (§14.1, G-EP7): rebuilds the replica without given units;
+ * - a change whose actor and sequence number another change of the
+ *   document already has is held (§14.1, POST-001): never merged, not
+ *   refused, and retried after every exclude.
  */
 /** An accepted unit as the applier passes it (structurally the client's ProfileUnit). */
 export interface SharedObjectsUnit {
@@ -32,6 +35,8 @@ export interface SharedObjectsApplyResult {
     readonly objects: readonly string[];
     readonly diagnostics: readonly SharedObjectsDiagnostic[];
     readonly pending?: string;
+    /** Why the unit is held (§14.1): its actor and sequence number belong to a different change. */
+    readonly held?: string;
 }
 /** The outcome of applyBatch: per unit merged, pending or rejected, and the objects once. */
 export interface SharedObjectsBatchResult {
@@ -39,7 +44,9 @@ export interface SharedObjectsBatchResult {
     readonly merged: readonly DataUnitId[];
     /** Units buffered for Automerge dependencies (the batch's and earlier ones still waiting). */
     readonly pending: readonly DataUnitId[];
-    /** Units whose change was refused (ACTOR_EQUIVOCATION, INVALID_AUTOMERGE_BYTES, …). */
+    /** Units held because a different change has their actor and sequence number (§14.1), all of them. */
+    readonly held: readonly DataUnitId[];
+    /** Units whose change was refused (INVALID_AUTOMERGE_BYTES, …). */
     readonly rejected: readonly {
         readonly unitId: DataUnitId;
         readonly code: string;
@@ -51,6 +58,8 @@ export interface SharedObjectsBatchResult {
 export interface SharedObjectsExcludeResult {
     readonly objects: readonly string[];
     readonly pending: readonly DataUnitId[];
+    /** Held units that merged after the rebuild (§14.1): their actor and sequence number were free again. */
+    readonly released: readonly DataUnitId[];
 }
 /** A persisted handler state (structurally the storage ProfileCheckpoint). */
 export interface SharedObjectsCheckpoint {
@@ -128,8 +137,10 @@ export declare class SharedObjectsDataProfile {
      * only (SNAP-EP: Snapshot-derived state dropped). Notifies the changes.
      */
     reset(): void;
-    /** Whether this handler holds the unit's change (merged, recorded or buffered). */
+    /** Whether this handler holds the unit's change (merged, recorded, buffered or held). */
     has(unitId: DataUnitId): boolean;
+    /** The units held because a different change has their actor and sequence number (§14.1). */
+    heldUnits(): DataUnitId[];
     /** The units waiting for Automerge dependencies. */
     pendingUnits(): DataUnitId[];
     codecFor(unit: {

package/dist/data-profile.js

@@ -10,6 +10,8 @@ export class SharedObjectsDataProfile {
     #merged = new Map();
     /** LFCP-accepted units waiting for Automerge dependencies, by unit ID hex. */
     #pending = new Map();
+    /** LFCP-accepted units whose actor and sequence number a different change has (§14.1), by unit ID hex. */
+    #held = new Map();
     #listeners = new Set();
     constructor(replica) {
         this.#replica = replica;
@@ -116,12 +118,17 @@ export class SharedObjectsDataProfile {
         this.#replica = before.emptied();
         this.#merged.clear();
         this.#pending.clear();
+        this.#held.clear();
         this.#emit(rebuildChanges(before, this.#replica));
     }
-    /** Whether this handler holds the unit's change (merged, recorded or buffered). */
+    /** Whether this handler holds the unit's change (merged, recorded, buffered or held). */
     has(unitId) {
         const key = toHex(unitId);
-        return this.#merged.has(key) || this.#pending.has(key);
+        return this.#merged.has(key) || this.#pending.has(key) || this.#held.has(key);
+    }
+    /** The units held because a different change has their actor and sequence number (§14.1). */
+    heldUnits() {
+        return [...this.#held.values()].map((b) => b.unitId);
     }
     /** The units waiting for Automerge dependencies. */
     pendingUnits() {
@@ -149,6 +156,13 @@ export class SharedObjectsDataProfile {
         const own = r.refused.get(key);
         if (own !== undefined)
             throw own;
+        if (this.#held.has(key))
+            return Object.freeze({
+                merged: r.result.merged,
+                objects: r.result.objects,
+                diagnostics: r.result.diagnostics,
+                held: `held: a different change has actor ${change.actor} sequence ${change.seq} (§14.1)`,
+            });
         const self = r.result.merged.some((id) => toHex(id) === key);
         if (!self)
             return Object.freeze({
@@ -175,9 +189,15 @@ export class SharedObjectsDataProfile {
     applyBatch(units) {
         return this.#applyBatch(units).result;
     }
-    #applyBatch(units) {
+    #applyBatch(units, retryHeld = false) {
         const byHash = new Map();
         const offer = (unitId, change) => byHash.set(change.hash, [...(byHash.get(change.hash) ?? []), unitId]);
+        // §14.1: after a rebuild, held changes are offered again with the rest.
+        if (retryHeld) {
+            for (const [key, b] of this.#held)
+                this.#pending.set(key, b);
+            this.#held.clear();
+        }
         for (const b of this.#pending.values())
             offer(b.unitId, b.change);
         for (const { unit, value } of units) {
@@ -197,6 +217,11 @@ export class SharedObjectsDataProfile {
         for (const { change, error } of r.refused)
             for (const unitId of byHash.get(change.hash) ?? []) {
                 this.#pending.delete(toHex(unitId));
+                // §14.1 (POST-001): another change has its actor and sequence number: held, not refused.
+                if (error.code === "ACTOR_EQUIVOCATION") {
+                    this.#held.set(toHex(unitId), { unitId, change });
+                    continue;
+                }
                 rejected.push({ unitId, code: error.code, message: error.message });
                 refused.set(toHex(unitId), error);
             }
@@ -209,6 +234,7 @@ export class SharedObjectsDataProfile {
             result: Object.freeze({
                 merged: Object.freeze(merged),
                 pending: Object.freeze([...this.#pending.values()].map((b) => b.unitId)),
+                held: Object.freeze(this.heldUnits()),
                 rejected: Object.freeze(rejected),
                 objects: Object.freeze(objects),
                 diagnostics: Object.freeze(this.#diagnostics(objects)),
@@ -251,6 +277,7 @@ export class SharedObjectsDataProfile {
         for (const id of unitIds) {
             const key = toHex(id);
             this.#pending.delete(key);
+            this.#held.delete(key);
             const m = this.#merged.get(key);
             if (m !== undefined) {
                 hashes.push(m.hash);
@@ -258,7 +285,7 @@ export class SharedObjectsDataProfile {
             }
         }
         if (hashes.length === 0)
-            return Object.freeze({ objects: [], pending: [] });
+            return Object.freeze({ objects: [], pending: [], released: [] });
         const before = this.#replica;
         const { replica, unapplied } = before.rebuildWithout(hashes);
         this.#replica = replica;
@@ -273,7 +300,18 @@ export class SharedObjectsDataProfile {
         }
         const changes = rebuildChanges(before, replica);
         this.#emit(changes);
-        return Object.freeze({ objects: changes.map((c) => c.objectId), pending });
+        // §14.1: the rebuild may have freed held changes' actor sequences.
+        const held = new Set(this.#held.keys());
+        const retried = held.size > 0 ? this.#applyBatch([], true) : null;
+        const released = (retried?.result.merged ?? []).filter((id) => held.has(toHex(id)));
+        const objects = [
+            ...new Set([...changes.map((c) => c.objectId), ...(retried?.result.objects ?? [])]),
+        ].sort();
+        return Object.freeze({
+            objects,
+            pending: pending.filter((id) => !(retried?.result.merged ?? []).some((m) => toHex(m) === toHex(id))),
+            released: Object.freeze(released),
+        });
     }
 }
 /** §100 notifications for every object that differs between two replicas of one Resource. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/shared-objects",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "SHARED-OBJECTS-PROFILE-01 (org.openlfcp.shared-objects.v1) implementation.",
   "keywords": [
     "openlfcp",
@@ -45,8 +45,8 @@
   "dependencies": {
     "@automerge/automerge": "3.5.0",
     "fflate": "0.8.3",
-    "@openlfcp/core": "^0.1.1",
-    "@openlfcp/crypto": "^0.1.1"
+    "@openlfcp/core": "^0.1.3",
+    "@openlfcp/crypto": "^0.1.3"
   },
   "devDependencies": {
     "fast-check": "4.10.2"