@openlfcp/shared-objects 0.2.1 → 0.2.2

package/dist/data-profile.d.ts

@@ -84,6 +84,11 @@ export interface SharedObjectsCodec {
     encode(change: CheckedChange): Uint8Array;
     decode(plaintext: Uint8Array): CheckedChange;
 }
+/** An object-changed listener that threw: the error, and the change it was given. */
+export interface SharedObjectsListenerFailure {
+    readonly error: unknown;
+    readonly change: ObjectChange;
+}
 export declare class SharedObjectsDataProfile {
     #private;
     readonly dataProfile = "org.openlfcp.shared-objects.v1";
@@ -103,8 +108,20 @@ export declare class SharedObjectsDataProfile {
     static restore(checkpoint: SharedObjectsCheckpoint, options: Pick<ReplicaOptions, "resource" | "principal">): SharedObjectsDataProfile;
     /** The current replica (a G-EP7 rebuild replaces it). */
     get replica(): SharedObjectsReplica;
-    /** §98, §100: object change notifications for remote merges and rebuilds. */
+    /**
+     * §98, §100: object change notifications for remote merges and rebuilds.
+     * A listener that changes the model again (re-entrantly) makes the
+     * nested event reach the listeners after it before the outer one does,
+     * as in 0.2.1.
+     */
     onObjectChanged(listener: (change: ObjectChange) => void): () => void;
+    /**
+     * Called when an object-changed listener throws (REVIEW-20261015-03),
+     * with the error and the change. Without a handler the error goes to the
+     * runtime's reportError where there is one (a browser, Electron), else it
+     * is dropped. A handler that throws is not reported again.
+     */
+    onListenerError(handler: (failure: SharedObjectsListenerFailure) => void): () => void;
     /**
      * Records which change one of this client's OWN units carries (the unit
      * was created from a local change, so it is merged already). A later

package/dist/data-profile.js

@@ -1,6 +1,7 @@
 import { LfcpError, toHex, } from "@openlfcp/core";
 import { checkChangeActor } from "./admission/actor.js";
 import { frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "./admission/framing.js";
+import { GuardedListeners } from "./listeners.js";
 import { SharedObjectsReplica } from "./replica.js";
 import { deriveActorId, PROFILE_ID } from "./values.js";
 export class SharedObjectsDataProfile {
@@ -12,7 +13,7 @@ export class SharedObjectsDataProfile {
     #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();
+    #listeners = new GuardedListeners((error, change) => Object.freeze({ error, change }));
     constructor(replica) {
         this.#replica = replica;
     }
@@ -55,15 +56,34 @@ export class SharedObjectsDataProfile {
     get replica() {
         return this.#replica;
     }
-    /** §98, §100: object change notifications for remote merges and rebuilds. */
+    /**
+     * §98, §100: object change notifications for remote merges and rebuilds.
+     * A listener that changes the model again (re-entrantly) makes the
+     * nested event reach the listeners after it before the outer one does,
+     * as in 0.2.1.
+     */
     onObjectChanged(listener) {
-        this.#listeners.add(listener);
-        return () => this.#listeners.delete(listener);
+        return this.#listeners.add(listener);
     }
+    /**
+     * Called when an object-changed listener throws (REVIEW-20261015-03),
+     * with the error and the change. Without a handler the error goes to the
+     * runtime's reportError where there is one (a browser, Electron), else it
+     * is dropped. A handler that throws is not reported again.
+     */
+    onListenerError(handler) {
+        return this.#listeners.onError(handler);
+    }
+    /**
+     * Every listener gets every change, and a listener that throws never
+     * turns the operation that changed the model (a merge, a rebuild, a
+     * loaded Snapshot, a reset) into a failure: the change stands and the
+     * error is reported (onListenerError), never recursively. An engine trap
+     * is thrown on once every listener has had every change, as SyncClient
+     * does: the engine is dead.
+     */
     #emit(changes) {
-        for (const c of changes)
-            for (const l of this.#listeners)
-                l(c);
+        this.#listeners.emit(changes);
     }
     /**
      * Records which change one of this client's OWN units carries (the unit

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 export declare const PACKAGE = "@openlfcp/shared-objects";
 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 { type SharedObjectsApplyResult, type SharedObjectsBatchResult, type SharedObjectsCheckpoint, type SharedObjectsCodec, SharedObjectsDataProfile, type SharedObjectsDiagnostic, type SharedObjectsExcludeResult, type SharedObjectsListenerFailure, 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";
 export { DIAGNOSTIC_ORDER, firstPerField, isMap, type Json, objectProblems, type ProfileDiagnostic, ProfileInvalidError, type ProfileProblem, pointerToken, type RootValidation, validateRoot, validateTransition, } from "./validate.js";

package/dist/listeners.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Guarded change notifications for the Data Profile handlers
+ * (REVIEW-20261015-03): every listener gets each event, and a listener that
+ * throws never turns the operation that changed the model into a failure.
+ * Its error goes to the handlers registered with onError, or, without one,
+ * to the runtime's reportError where there is one (a browser, Electron);
+ * else it is dropped. A handler that throws, or a failure while one is
+ * being reported, is not reported again (no recursion). An engine trap is
+ * the exception: it is thrown on once every listener has had the event, as
+ * the client's SyncClient does, since the engine is dead.
+ */
+/**
+ * A thrown value that looks like an engine trap (WebAssembly RuntimeError, a
+ * terminated module): the rule of the client's isEngineTrap, which this
+ * package cannot import.
+ */
+export declare function isEngineTrap(e: unknown): boolean;
+/** Listeners of events `E`, and the handlers of their failures `F`. */
+export declare class GuardedListeners<E, F> {
+    #private;
+    /** `failure` builds what a handler receives from the error and the event. */
+    constructor(failure: (error: unknown, event: E) => F);
+    add(listener: (event: E) => void): () => void;
+    onError(handler: (failure: F) => void): () => void;
+    /** Delivers each event to every listener; see the module comment. */
+    emit(events: readonly E[]): void;
+}
+//# sourceMappingURL=listeners.d.ts.map

package/dist/listeners.js

@@ -0,0 +1,93 @@
+/**
+ * Guarded change notifications for the Data Profile handlers
+ * (REVIEW-20261015-03): every listener gets each event, and a listener that
+ * throws never turns the operation that changed the model into a failure.
+ * Its error goes to the handlers registered with onError, or, without one,
+ * to the runtime's reportError where there is one (a browser, Electron);
+ * else it is dropped. A handler that throws, or a failure while one is
+ * being reported, is not reported again (no recursion). An engine trap is
+ * the exception: it is thrown on once every listener has had the event, as
+ * the client's SyncClient does, since the engine is dead.
+ */
+/**
+ * A thrown value that looks like an engine trap (WebAssembly RuntimeError, a
+ * terminated module): the rule of the client's isEngineTrap, which this
+ * package cannot import.
+ */
+export function isEngineTrap(e) {
+    const wasm = globalThis
+        .WebAssembly?.RuntimeError;
+    if (wasm !== undefined && e instanceof wasm)
+        return true;
+    if (!(e instanceof Error))
+        return false;
+    return (e.name === "RuntimeError" ||
+        /\b(module|instance)\b.*\bterminated\b|\bunreachable\b executed|\bwasm trap\b/i.test(e.message));
+}
+/** Listeners of events `E`, and the handlers of their failures `F`. */
+export class GuardedListeners {
+    #listeners = new Set();
+    #errorHandlers = new Set();
+    #failure;
+    #reporting = false;
+    /** `failure` builds what a handler receives from the error and the event. */
+    constructor(failure) {
+        this.#failure = failure;
+    }
+    add(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    onError(handler) {
+        this.#errorHandlers.add(handler);
+        return () => this.#errorHandlers.delete(handler);
+    }
+    /** Delivers each event to every listener; see the module comment. */
+    emit(events) {
+        let trap;
+        const failed = [];
+        for (const event of events)
+            for (const l of [...this.#listeners])
+                try {
+                    l(event);
+                }
+                catch (error) {
+                    if (isEngineTrap(error))
+                        trap ??= { error };
+                    else
+                        failed.push({ error, event });
+                }
+        for (const { error, event } of failed)
+            this.#report(error, event);
+        if (trap !== undefined)
+            throw trap.error;
+    }
+    #report(error, event) {
+        if (this.#reporting)
+            return;
+        this.#reporting = true;
+        try {
+            if (this.#errorHandlers.size === 0) {
+                const report = globalThis.reportError;
+                if (typeof report === "function")
+                    report(error);
+                return;
+            }
+            const failure = this.#failure(error, event);
+            for (const h of [...this.#errorHandlers])
+                try {
+                    h(failure);
+                }
+                catch {
+                    // A failing error handler is not reported again (no recursion).
+                }
+        }
+        catch {
+            // reportError itself failed: nothing left to report to.
+        }
+        finally {
+            this.#reporting = false;
+        }
+    }
+}
+//# sourceMappingURL=listeners.js.map

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

@@ -105,14 +105,31 @@ export interface SectionsNodesChanged {
     readonly origin: "local" | "remote" | "rebuild";
     readonly modelRevision: string;
 }
+/** A nodes-changed listener that threw: the error, and the event it was given. */
+export interface SectionsListenerFailure {
+    readonly error: unknown;
+    readonly event: SectionsNodesChanged;
+}
 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. */
+    /**
+     * §5 nodes-changed for remote merges, rebuilds and recorded local changes.
+     * A listener that changes the model again (re-entrantly) makes the
+     * nested event reach the listeners after it before the outer one does,
+     * as in 0.2.1.
+     */
     onNodesChanged(listener: (event: SectionsNodesChanged) => void): () => void;
+    /**
+     * Called when a nodes-changed listener throws (REVIEW-20261015-03), with
+     * the error and the event. Without a handler the error goes to the
+     * runtime's reportError where there is one (a browser, Electron), else it
+     * is dropped. A handler that throws is not reported again.
+     */
+    onListenerError(handler: (failure: SectionsListenerFailure) => void): () => void;
     /** The codec of one unit, bound to its signer's section actor (§2). */
     codecFor(unit: {
         readonly resourceId: ResourceId;

package/dist/sections/data-profile.js

@@ -1,6 +1,7 @@
 import { LfcpError, toHex, } from "@openlfcp/core";
 import { checkChangeActor } from "../admission/actor.js";
 import { checkChange, frameChange, frameSnapshot, unframeChange, unframeSnapshot, } from "../admission/framing.js";
+import { GuardedListeners } from "../listeners.js";
 import { SectionReplica } from "./replica.js";
 import { deriveSectionActorId, SECTIONS_PROFILE_ID } from "./values.js";
 /** Each node's (and the title's) projected state, to tell which ones a merge changed. */
@@ -62,7 +63,7 @@ export class SharedSectionsDataProfile {
     #pending = new Map();
     /** LFCP-accepted units whose actor sequence a different change has (SOP §14.1), by unit ID hex. */
     #held = new Map();
-    #listeners = new Set();
+    #listeners = new GuardedListeners((error, event) => Object.freeze({ error, event }));
     constructor(replica) {
         this.#replica = replica;
     }
@@ -70,17 +71,37 @@ export class SharedSectionsDataProfile {
     get replica() {
         return this.#replica;
     }
-    /** §5 nodes-changed for remote merges, rebuilds and recorded local changes. */
+    /**
+     * §5 nodes-changed for remote merges, rebuilds and recorded local changes.
+     * A listener that changes the model again (re-entrantly) makes the
+     * nested event reach the listeners after it before the outer one does,
+     * as in 0.2.1.
+     */
     onNodesChanged(listener) {
-        this.#listeners.add(listener);
-        return () => this.#listeners.delete(listener);
+        return this.#listeners.add(listener);
     }
+    /**
+     * Called when a nodes-changed listener throws (REVIEW-20261015-03), with
+     * the error and the event. Without a handler the error goes to the
+     * runtime's reportError where there is one (a browser, Electron), else it
+     * is dropped. A handler that throws is not reported again.
+     */
+    onListenerError(handler) {
+        return this.#listeners.onError(handler);
+    }
+    /**
+     * Every listener gets the event, and a listener that throws never turns
+     * the operation that changed the model (a merge, a recorded local change,
+     * a rebuild, a loaded Snapshot) into a failure: the change stands and the
+     * error is reported (onListenerError), never recursively. An engine trap
+     * is the exception and is thrown on once every listener has had the
+     * event, as before and as SyncClient does: the engine is dead.
+     */
     #emit(nodeIds, origin) {
         if (nodeIds.length === 0)
             return;
         const event = Object.freeze({ nodeIds, origin, modelRevision: this.#replica.revision() });
-        for (const l of this.#listeners)
-            l(event);
+        this.#listeners.emit([event]);
     }
     /** The codec of one unit, bound to its signer's section actor (§2). */
     codecFor(unit) {

package/dist/sections/index.d.ts

@@ -8,7 +8,7 @@
  * shared `@openlfcp/shared-objects/admission` with SECTIONS_ACTOR_DOMAIN.
  */
 export { ADMISSION_ORDER, type AdmissionDiagnostic, SectionAdmissionError, } from "./admission.js";
-export { type SectionsApplyResult, type SectionsBatchResult, type SectionsCheckpoint, type SectionsCodec, type SectionsCommitBinding, type SectionsExcludeResult, type SectionsNodesChanged, type SectionsSnapshotBinding, type SectionsSnapshotCodec, type SectionsStagedOperation, type SectionsUnit, SharedSectionsDataProfile, } from "./data-profile.js";
+export { type SectionsApplyResult, type SectionsBatchResult, type SectionsCheckpoint, type SectionsCodec, type SectionsCommitBinding, type SectionsExcludeResult, type SectionsListenerFailure, type SectionsNodesChanged, type SectionsSnapshotBinding, type SectionsSnapshotCodec, type SectionsStagedOperation, type SectionsUnit, SharedSectionsDataProfile, } from "./data-profile.js";
 export { type ProfileModel, profileModel, SUPPORTED_DATA_PROFILES, taskRefModel, } from "./dispatch.js";
 export { SectionDocument, type ValueType } from "./document.js";
 export { AUTHORING_BUDGET, type SectionIntent, type SectionIntentCode, SectionIntentError, type SectionLocalChange, type SectionReceiveResult, type SectionRefusal, SectionReplica, type SectionReplicaOptions, type SectionSnapshot, type SectionSnapshotNode, type SectionUnit, type StagedSectionChange, type TextEdit, } from "./replica.js";

package/package.json

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