@phosphorco/bb-identity 0.3.0 → 0.4.0

package/dist/state-controller-runtime.js

@@ -270,6 +270,9 @@ function sameVersion(a, b) {
   return a.status === b.status && version(a).epoch === version(b).epoch && version(a).sequence === version(b).sequence;
 }
 function createIdentityState(options) {
+  return createStateController(options);
+}
+function createStateController(options, editing = false) {
   const address = frozen({ ...options.address });
   const expected = frozen({ ...options.expected });
   const definition = options.definition;
@@ -303,6 +306,12 @@ function createIdentityState(options) {
   let closing = false;
   let checkpoint = null;
   let recoverySource = null;
+  let checkpointError = null;
+  let checkpointWriting = 0;
+  let lastRejection = null;
+  let rejectedGeneration = -1;
+  let ownerFenced = false;
+  let loadFailed = false;
   let automaticSuspensions = 0;
   let automaticEpoch = 0;
   let persistQueue = Promise.resolve();
@@ -318,7 +327,7 @@ function createIdentityState(options) {
     timer?.();
     timer = null;
   };
-  const draft = () => base === null || desired === null ? null : frozen({ formatVersion: 1, key: { address, actor: expected.actor, ownerSession: options.ownerSession }, schemaVersion: definition.schemaVersion, acknowledged: base, desired: desired.value, localGeneration, inFlight: pending?.mutation ?? null });
+  const draft = () => base === null || desired === null ? null : frozen({ formatVersion: 1, key: { address, actor: expected.actor, ownerSession: options.ownerSession }, schemaVersion: definition.schemaVersion, acknowledged: base, desired: desired.value, localGeneration, inFlight: pending?.mutation ?? null, ...editing ? { rejection: lastRejection, rejectedGeneration } : {} });
   function emit() {
     if (lifecycle === "detached" || lifecycle === "disposed")
       snapshot = { status: "detached", address, draft: draft() };
@@ -342,6 +351,8 @@ function createIdentityState(options) {
   function sessionCheck() {
     if (!active())
       return err("disposed", "This state controller is no longer active.");
+    if (editing && ownerFenced)
+      return err("stale-context", "This editing owner was retired.");
     const result = options.currentSession();
     if (!result.ok) {
       block("identity-unavailable", result.error.message);
@@ -353,6 +364,8 @@ function createIdentityState(options) {
       return { ok: false, error: session.error };
     }
     if (session.instanceId !== address.instanceId || session.actor.identity.key !== expected.actor || session.stamp !== expected.session) {
+      if (editing)
+        ownerFenced = true;
       block("owner-changed", "The identity session changed.");
       return err("stale-context", "The identity session changed.", "after-refresh");
     }
@@ -373,11 +386,23 @@ function createIdentityState(options) {
     const capturedEpoch = epoch;
     const serial = ++persistSerial;
     const work = persistQueue.then(async () => {
+      checkpointWriting++;
+      if (editing)
+        emit();
       const result = await safe(() => drafts.write(captured, checkpoint?.revision ?? null));
-      if (result.ok)
+      checkpointWriting--;
+      if (result.ok) {
         checkpoint = result.value;
-      else if (active(capturedEpoch) && serial === persistSerial)
-        block("storage-error", result.error.message);
+        if (editing)
+          checkpointError = null;
+      } else if (active(capturedEpoch) && serial === persistSerial) {
+        if (editing)
+          checkpointError = result.error;
+        else
+          block("storage-error", result.error.message);
+      }
+      if (editing)
+        emit();
       return result;
     });
     persistQueue = work.then(() => {
@@ -387,7 +412,7 @@ function createIdentityState(options) {
   }
   function schedule() {
     clearTimer();
-    if (!active() || automaticSuspensions || closing || blocked || pending || !needsSave())
+    if (editing || !active() || automaticSuspensions || closing || blocked || pending || !needsSave())
       return;
     timer = scheduler.schedule(debounce, () => {
       timer = null;
@@ -456,7 +481,7 @@ function createIdentityState(options) {
       return ok(undefined);
     if (base && dirty()) {
       if (sameVersion(base, read)) {
-        if (!blocked?.conflict)
+        if (!blocked?.conflict && (!editing || blocked?.reason !== "rejected"))
           blocked = null;
         emit();
         schedule();
@@ -466,7 +491,8 @@ function createIdentityState(options) {
     }
     base = read;
     desired = { value: valueClone(codec, currentValue(read)) };
-    blocked = null;
+    if (!editing || blocked?.reason !== "rejected")
+      blocked = null;
     emit();
     schedule();
     return ok(undefined);
@@ -492,14 +518,17 @@ function createIdentityState(options) {
       if (!live.ok)
         return live;
       if (!loaded.ok) {
+        loadFailed = true;
         block("storage-error", loaded.error.message);
         return loaded;
       }
       const parsed = readClone(loaded.value);
       if (!parsed.ok) {
+        loadFailed = true;
         block("storage-error", parsed.error.message);
         return parsed;
       }
+      loadFailed = false;
       return applyRemote(parsed.value, cause);
     })();
     activeLoad = work;
@@ -513,6 +542,10 @@ function createIdentityState(options) {
     return work;
   }
   function outcomeCheck(outcome, operationId) {
+    if (editing && outcome.status === "rejected")
+      return outcome.operationId === operationId ? ok(frozen(outcome)) : err("incompatible", "Rejected receipt has another operation.");
+    if (outcome.status === "rejected")
+      return err("incompatible", "Rejection is not a legacy state outcome.");
     const parsed = codecs.save.decode(structuredClone(codecs.save.encode(outcome)));
     if (!parsed.ok)
       return parsed;
@@ -532,6 +565,17 @@ function createIdentityState(options) {
     pending = null;
     loadId++;
     blocked = null;
+    if (outcome.status === "rejected") {
+      lastRejection = outcome.evidence;
+      rejectedGeneration = captured.generation;
+      block("rejected", "The submitted edit was definitively rejected.");
+      const saved2 = await persist();
+      return saved2.ok ? err("invalid-input", "The submitted edit was definitively rejected.") : saved2;
+    }
+    if (editing && (outcome.status === "saved" || outcome.status === "unchanged")) {
+      lastRejection = null;
+      rejectedGeneration = -1;
+    }
     if (outcome.status === "saved" || outcome.status === "unchanged") {
       base = { status: "present", envelope: outcome.envelope };
       acknowledgedGeneration = Math.max(acknowledgedGeneration, captured.generation);
@@ -563,6 +607,8 @@ function createIdentityState(options) {
         return reload("reconnect");
       schedule();
     }
+    if (editing && snapshot.status === "blocked" && snapshot.reason === "conflict")
+      return err("conflict", snapshot.message);
     return ok(undefined);
   }
   function transmit(captured, automatic = false) {
@@ -631,7 +677,9 @@ function createIdentityState(options) {
     const valid = sessionCheck();
     if (!valid.ok)
       return Promise.resolve(valid);
-    if (blocked)
+    if (editing && lastRejection && localGeneration <= rejectedGeneration)
+      return Promise.resolve(err("invalid-input", "Correct the rejected draft before submitting a new operation."));
+    if (blocked && !(editing && blocked.reason === "rejected" && localGeneration > rejectedGeneration))
       return Promise.resolve(err("conflict", blocked.message));
     if (activeSave)
       return activeSave;
@@ -640,6 +688,8 @@ function createIdentityState(options) {
     if (!base || !desired || !needsSave())
       return Promise.resolve(ok(undefined));
     const mutation = frozen({ kind: base.status === "empty" ? "initialize" : "replace", address, expectedVersion: { ...version(base) }, expected, ownerSession: options.ownerSession, localGeneration, operationId: newOperationId(), schemaVersion: definition.schemaVersion, value: valueClone(codec, desired.value) });
+    if (editing && blocked?.reason === "rejected")
+      blocked = null;
     pending = { mutation, base, generation: localGeneration };
     return transmit(pending, automatic);
   }
@@ -664,7 +714,7 @@ function createIdentityState(options) {
     const valid = sessionCheck();
     if (!valid.ok)
       return valid;
-    const result = await safe(() => options.transport.reconcile({ address, expected, operationId: captured.mutation.operationId }, { signal: abort.signal }));
+    const result = await safe(() => options.transport.reconcile({ address, expected, operationId: captured.mutation.operationId, mutation: captured.mutation }, { signal: abort.signal }));
     if (!active(capturedEpoch) || pending !== captured)
       return err("cancelled", "State reconciliation was superseded.");
     const live = sessionCheck();
@@ -676,7 +726,7 @@ function createIdentityState(options) {
     }
     if (result.value.status === "final")
       return applyOutcome(captured, result.value.outcome);
-    if (result.value.status === "absent-final" && allowReplay) {
+    if (result.value.status === "absent-final" && allowReplay && !editing) {
       if (captured.mutation.expected.actor !== expected.actor || captured.mutation.expected.session !== expected.session) {
         block("draft-recovery", "The original operation cannot be re-authored under a new session.");
         return err("stale-context", "The original operation requires its original session.");
@@ -692,6 +742,13 @@ function createIdentityState(options) {
     const valid = sessionCheck();
     if (!valid.ok)
       return valid;
+    if (editing) {
+      if (activeSave)
+        return activeSave;
+      if (pending)
+        return reconcile(false);
+      return sendNew();
+    }
     const goal = localGeneration;
     let retries = 0;
     if (activeSave) {
@@ -745,6 +802,27 @@ function createIdentityState(options) {
   }
   return {
     getSnapshot: () => snapshot,
+    inspect() {
+      const retained = draft();
+      const checkpointMatches = checkpoint !== null && retained !== null && checkpoint.draft.localGeneration === retained.localGeneration && JSON.stringify(checkpoint.draft.inFlight ? codecs.mutation.encode(checkpoint.draft.inFlight) : null) === JSON.stringify(retained.inFlight ? codecs.mutation.encode(retained.inFlight) : null) && JSON.stringify(checkpoint.draft.rejection ?? null) === JSON.stringify(retained.rejection ?? null) && JSON.stringify(codecs.read.encode(checkpoint.draft.acknowledged)) === JSON.stringify(codecs.read.encode(retained.acknowledged));
+      return {
+        draft: retained,
+        base,
+        desired: desired?.value,
+        generation: localGeneration,
+        pending: pending?.mutation ?? null,
+        saving: networkActive,
+        dirty: dirty(),
+        saveEligible: needsSave() && (!lastRejection || localGeneration > rejectedGeneration),
+        editable: active() && !closing && !ownerFenced && !loadFailed && base !== null && desired !== null && (!blocked || ["conflict", "indeterminate", "rejected", "draft-recovery"].includes(blocked.reason)),
+        checkpoint: {
+          status: !drafts ? "disabled" : checkpointWriting ? "writing" : checkpointError ? "failed" : checkpointMatches ? "backed-up" : "local-only",
+          generation: checkpoint?.draft.localGeneration ?? null,
+          revision: checkpoint?.revision ?? null,
+          error: checkpointError
+        }
+      };
+    },
     subscribe(listener) {
       if (lifecycle === "disposed")
         return () => {};
@@ -780,7 +858,7 @@ function createIdentityState(options) {
       const valid = sessionCheck();
       if (!valid.ok)
         return valid;
-      if (closing || blocked || snapshot.status !== "ready")
+      if (closing || (editing ? ownerFenced || loadFailed || !base || !desired || !!blocked && !["conflict", "indeterminate", "rejected", "draft-recovery"].includes(blocked.reason) : blocked || snapshot.status !== "ready"))
         return err("unavailable", "State is not editable.");
       try {
         desired = { value: valueClone(codec, value) };
@@ -788,6 +866,8 @@ function createIdentityState(options) {
         return err("invalid-input", error instanceof Error ? error.message : "Invalid state.");
       }
       localGeneration++;
+      if (editing && blocked?.conflict)
+        blocked = { ...blocked, conflict: frozen({ ...blocked.conflict, token: newConflictToken(), local: desired.value }) };
       emit();
       schedule();
       return ok(undefined);
@@ -856,6 +936,10 @@ function createIdentityState(options) {
           return err("invalid-input", "Draft operation does not match its owner or generation.");
         mutation = frozen(result.value);
       }
+      if (editing) {
+        lastRejection = source.rejection ?? null;
+        rejectedGeneration = source.rejectedGeneration ?? -1;
+      }
       clearTimer();
       base = parsed.value;
       desired = { value: valueClone(codec, source.desired) };
@@ -946,5 +1030,6 @@ function createIdentityState(options) {
   };
 }
 export {
+  createStateController,
   createIdentityState
 };

package/dist/state-runtime.js

@@ -406,6 +406,9 @@ function sameVersion(a, b) {
   return a.status === b.status && version(a).epoch === version(b).epoch && version(a).sequence === version(b).sequence;
 }
 function createIdentityState(options) {
+  return createStateController(options);
+}
+function createStateController(options, editing = false) {
   const address = frozen({ ...options.address });
   const expected = frozen({ ...options.expected });
   const definition = options.definition;
@@ -439,6 +442,12 @@ function createIdentityState(options) {
   let closing = false;
   let checkpoint = null;
   let recoverySource = null;
+  let checkpointError = null;
+  let checkpointWriting = 0;
+  let lastRejection = null;
+  let rejectedGeneration = -1;
+  let ownerFenced = false;
+  let loadFailed = false;
   let automaticSuspensions = 0;
   let automaticEpoch = 0;
   let persistQueue = Promise.resolve();
@@ -454,7 +463,7 @@ function createIdentityState(options) {
     timer?.();
     timer = null;
   };
-  const draft = () => base === null || desired === null ? null : frozen({ formatVersion: 1, key: { address, actor: expected.actor, ownerSession: options.ownerSession }, schemaVersion: definition.schemaVersion, acknowledged: base, desired: desired.value, localGeneration, inFlight: pending?.mutation ?? null });
+  const draft = () => base === null || desired === null ? null : frozen({ formatVersion: 1, key: { address, actor: expected.actor, ownerSession: options.ownerSession }, schemaVersion: definition.schemaVersion, acknowledged: base, desired: desired.value, localGeneration, inFlight: pending?.mutation ?? null, ...editing ? { rejection: lastRejection, rejectedGeneration } : {} });
   function emit() {
     if (lifecycle === "detached" || lifecycle === "disposed")
       snapshot = { status: "detached", address, draft: draft() };
@@ -478,6 +487,8 @@ function createIdentityState(options) {
   function sessionCheck() {
     if (!active())
       return err("disposed", "This state controller is no longer active.");
+    if (editing && ownerFenced)
+      return err("stale-context", "This editing owner was retired.");
     const result = options.currentSession();
     if (!result.ok) {
       block("identity-unavailable", result.error.message);
@@ -489,6 +500,8 @@ function createIdentityState(options) {
       return { ok: false, error: session.error };
     }
     if (session.instanceId !== address.instanceId || session.actor.identity.key !== expected.actor || session.stamp !== expected.session) {
+      if (editing)
+        ownerFenced = true;
       block("owner-changed", "The identity session changed.");
       return err("stale-context", "The identity session changed.", "after-refresh");
     }
@@ -509,11 +522,23 @@ function createIdentityState(options) {
     const capturedEpoch = epoch;
     const serial = ++persistSerial;
     const work = persistQueue.then(async () => {
+      checkpointWriting++;
+      if (editing)
+        emit();
       const result = await safe(() => drafts.write(captured, checkpoint?.revision ?? null));
-      if (result.ok)
+      checkpointWriting--;
+      if (result.ok) {
         checkpoint = result.value;
-      else if (active(capturedEpoch) && serial === persistSerial)
-        block("storage-error", result.error.message);
+        if (editing)
+          checkpointError = null;
+      } else if (active(capturedEpoch) && serial === persistSerial) {
+        if (editing)
+          checkpointError = result.error;
+        else
+          block("storage-error", result.error.message);
+      }
+      if (editing)
+        emit();
       return result;
     });
     persistQueue = work.then(() => {
@@ -523,7 +548,7 @@ function createIdentityState(options) {
   }
   function schedule() {
     clearTimer();
-    if (!active() || automaticSuspensions || closing || blocked || pending || !needsSave())
+    if (editing || !active() || automaticSuspensions || closing || blocked || pending || !needsSave())
       return;
     timer = scheduler.schedule(debounce, () => {
       timer = null;
@@ -592,7 +617,7 @@ function createIdentityState(options) {
       return ok(undefined);
     if (base && dirty()) {
       if (sameVersion(base, read)) {
-        if (!blocked?.conflict)
+        if (!blocked?.conflict && (!editing || blocked?.reason !== "rejected"))
           blocked = null;
         emit();
         schedule();
@@ -602,7 +627,8 @@ function createIdentityState(options) {
     }
     base = read;
     desired = { value: valueClone(codec, currentValue(read)) };
-    blocked = null;
+    if (!editing || blocked?.reason !== "rejected")
+      blocked = null;
     emit();
     schedule();
     return ok(undefined);
@@ -628,14 +654,17 @@ function createIdentityState(options) {
       if (!live.ok)
         return live;
       if (!loaded.ok) {
+        loadFailed = true;
         block("storage-error", loaded.error.message);
         return loaded;
       }
       const parsed = readClone(loaded.value);
       if (!parsed.ok) {
+        loadFailed = true;
         block("storage-error", parsed.error.message);
         return parsed;
       }
+      loadFailed = false;
       return applyRemote(parsed.value, cause);
     })();
     activeLoad = work;
@@ -649,6 +678,10 @@ function createIdentityState(options) {
     return work;
   }
   function outcomeCheck(outcome, operationId) {
+    if (editing && outcome.status === "rejected")
+      return outcome.operationId === operationId ? ok(frozen(outcome)) : err("incompatible", "Rejected receipt has another operation.");
+    if (outcome.status === "rejected")
+      return err("incompatible", "Rejection is not a legacy state outcome.");
     const parsed = codecs.save.decode(structuredClone(codecs.save.encode(outcome)));
     if (!parsed.ok)
       return parsed;
@@ -668,6 +701,17 @@ function createIdentityState(options) {
     pending = null;
     loadId++;
     blocked = null;
+    if (outcome.status === "rejected") {
+      lastRejection = outcome.evidence;
+      rejectedGeneration = captured.generation;
+      block("rejected", "The submitted edit was definitively rejected.");
+      const saved2 = await persist();
+      return saved2.ok ? err("invalid-input", "The submitted edit was definitively rejected.") : saved2;
+    }
+    if (editing && (outcome.status === "saved" || outcome.status === "unchanged")) {
+      lastRejection = null;
+      rejectedGeneration = -1;
+    }
     if (outcome.status === "saved" || outcome.status === "unchanged") {
       base = { status: "present", envelope: outcome.envelope };
       acknowledgedGeneration = Math.max(acknowledgedGeneration, captured.generation);
@@ -699,6 +743,8 @@ function createIdentityState(options) {
         return reload("reconnect");
       schedule();
     }
+    if (editing && snapshot.status === "blocked" && snapshot.reason === "conflict")
+      return err("conflict", snapshot.message);
     return ok(undefined);
   }
   function transmit(captured, automatic = false) {
@@ -767,7 +813,9 @@ function createIdentityState(options) {
     const valid = sessionCheck();
     if (!valid.ok)
       return Promise.resolve(valid);
-    if (blocked)
+    if (editing && lastRejection && localGeneration <= rejectedGeneration)
+      return Promise.resolve(err("invalid-input", "Correct the rejected draft before submitting a new operation."));
+    if (blocked && !(editing && blocked.reason === "rejected" && localGeneration > rejectedGeneration))
       return Promise.resolve(err("conflict", blocked.message));
     if (activeSave)
       return activeSave;
@@ -776,6 +824,8 @@ function createIdentityState(options) {
     if (!base || !desired || !needsSave())
       return Promise.resolve(ok(undefined));
     const mutation = frozen({ kind: base.status === "empty" ? "initialize" : "replace", address, expectedVersion: { ...version(base) }, expected, ownerSession: options.ownerSession, localGeneration, operationId: newOperationId(), schemaVersion: definition.schemaVersion, value: valueClone(codec, desired.value) });
+    if (editing && blocked?.reason === "rejected")
+      blocked = null;
     pending = { mutation, base, generation: localGeneration };
     return transmit(pending, automatic);
   }
@@ -800,7 +850,7 @@ function createIdentityState(options) {
     const valid = sessionCheck();
     if (!valid.ok)
       return valid;
-    const result = await safe(() => options.transport.reconcile({ address, expected, operationId: captured.mutation.operationId }, { signal: abort.signal }));
+    const result = await safe(() => options.transport.reconcile({ address, expected, operationId: captured.mutation.operationId, mutation: captured.mutation }, { signal: abort.signal }));
     if (!active(capturedEpoch) || pending !== captured)
       return err("cancelled", "State reconciliation was superseded.");
     const live = sessionCheck();
@@ -812,7 +862,7 @@ function createIdentityState(options) {
     }
     if (result.value.status === "final")
       return applyOutcome(captured, result.value.outcome);
-    if (result.value.status === "absent-final" && allowReplay) {
+    if (result.value.status === "absent-final" && allowReplay && !editing) {
       if (captured.mutation.expected.actor !== expected.actor || captured.mutation.expected.session !== expected.session) {
         block("draft-recovery", "The original operation cannot be re-authored under a new session.");
         return err("stale-context", "The original operation requires its original session.");
@@ -828,6 +878,13 @@ function createIdentityState(options) {
     const valid = sessionCheck();
     if (!valid.ok)
       return valid;
+    if (editing) {
+      if (activeSave)
+        return activeSave;
+      if (pending)
+        return reconcile(false);
+      return sendNew();
+    }
     const goal = localGeneration;
     let retries = 0;
     if (activeSave) {
@@ -881,6 +938,27 @@ function createIdentityState(options) {
   }
   return {
     getSnapshot: () => snapshot,
+    inspect() {
+      const retained = draft();
+      const checkpointMatches = checkpoint !== null && retained !== null && checkpoint.draft.localGeneration === retained.localGeneration && JSON.stringify(checkpoint.draft.inFlight ? codecs.mutation.encode(checkpoint.draft.inFlight) : null) === JSON.stringify(retained.inFlight ? codecs.mutation.encode(retained.inFlight) : null) && JSON.stringify(checkpoint.draft.rejection ?? null) === JSON.stringify(retained.rejection ?? null) && JSON.stringify(codecs.read.encode(checkpoint.draft.acknowledged)) === JSON.stringify(codecs.read.encode(retained.acknowledged));
+      return {
+        draft: retained,
+        base,
+        desired: desired?.value,
+        generation: localGeneration,
+        pending: pending?.mutation ?? null,
+        saving: networkActive,
+        dirty: dirty(),
+        saveEligible: needsSave() && (!lastRejection || localGeneration > rejectedGeneration),
+        editable: active() && !closing && !ownerFenced && !loadFailed && base !== null && desired !== null && (!blocked || ["conflict", "indeterminate", "rejected", "draft-recovery"].includes(blocked.reason)),
+        checkpoint: {
+          status: !drafts ? "disabled" : checkpointWriting ? "writing" : checkpointError ? "failed" : checkpointMatches ? "backed-up" : "local-only",
+          generation: checkpoint?.draft.localGeneration ?? null,
+          revision: checkpoint?.revision ?? null,
+          error: checkpointError
+        }
+      };
+    },
     subscribe(listener) {
       if (lifecycle === "disposed")
         return () => {};
@@ -916,7 +994,7 @@ function createIdentityState(options) {
       const valid = sessionCheck();
       if (!valid.ok)
         return valid;
-      if (closing || blocked || snapshot.status !== "ready")
+      if (closing || (editing ? ownerFenced || loadFailed || !base || !desired || !!blocked && !["conflict", "indeterminate", "rejected", "draft-recovery"].includes(blocked.reason) : blocked || snapshot.status !== "ready"))
         return err("unavailable", "State is not editable.");
       try {
         desired = { value: valueClone(codec, value) };
@@ -924,6 +1002,8 @@ function createIdentityState(options) {
         return err("invalid-input", error instanceof Error ? error.message : "Invalid state.");
       }
       localGeneration++;
+      if (editing && blocked?.conflict)
+        blocked = { ...blocked, conflict: frozen({ ...blocked.conflict, token: newConflictToken(), local: desired.value }) };
       emit();
       schedule();
       return ok(undefined);
@@ -992,6 +1072,10 @@ function createIdentityState(options) {
           return err("invalid-input", "Draft operation does not match its owner or generation.");
         mutation = frozen(result.value);
       }
+      if (editing) {
+        lastRejection = source.rejection ?? null;
+        rejectedGeneration = source.rejectedGeneration ?? -1;
+      }
       clearTimer();
       base = parsed.value;
       desired = { value: valueClone(codec, source.desired) };