@panphora/clayjs 1.15.2 → 1.17.0

package/src/page/boot.js

@@ -0,0 +1,237 @@
+export const PHASES = Object.freeze({
+  loading: "loading",
+  joining: "joining",
+  adopting: "adopting",
+  ready: "ready",
+  blocked: "blocked",
+  error: "error",
+});
+
+const TERMINAL = new Set([PHASES.ready, PHASES.blocked, PHASES.error]);
+
+let installs = 0;
+
+const monotonic = () => globalThis.performance?.now?.() ?? Date.now();
+
+export function createInstall({ gen = 0, isCurrent = () => true, onPhase = null } = {}) {
+  installs += 1;
+  return {
+    installId: installs,
+    gen,
+    isCurrent,
+    onPhase: typeof onPhase === "function" ? onPhase : null,
+    phase: PHASES.loading,
+    result: null,
+    at: monotonic(),
+    controller: new AbortController(),
+    disposers: [],
+    disposed: false,
+    steps: null,
+    deferred: null,
+  };
+}
+
+export function isCurrent(inst) {
+  return !inst.disposed && !inst.controller.signal.aborted && inst.isCurrent() !== false;
+}
+
+// One owner: the view this installation mounted, and nothing a later or a cancelled
+// installation staged. The final input gate asks this before it accepts a key.
+export function ownsView(inst, mounted) {
+  return isCurrent(inst) && !!mounted?.view && inst.mounted === mounted.view;
+}
+
+export function setPhase(inst, phase, reason = null) {
+  if (TERMINAL.has(inst.phase) && inst.result) return inst.result;
+  inst.phase = phase;
+  inst.at = monotonic();
+  inst.result = Object.freeze({ phase, reason: reason ?? null, installId: inst.installId, at: inst.at });
+  try {
+    inst.onPhase?.(inst.result);
+  } catch (error) {
+    console.error("clayjs: page boot phase callback failed", error);
+  }
+  return inst.result;
+}
+
+export function finishBlocked(inst, reason) {
+  const result = setPhase(inst, PHASES.blocked, reason);
+  inst.editorReadyResolve?.();
+  return result;
+}
+
+export function finishError(inst, reason) {
+  return setPhase(inst, PHASES.error, reason);
+}
+
+export function addDisposer(inst, dispose) {
+  if (typeof dispose === "function") inst.disposers.push(dispose);
+  return dispose;
+}
+
+export function disposeInstall(inst) {
+  if (inst.disposed) return;
+  inst.disposed = true;
+  inst.mounted = null;
+  try {
+    inst.controller.abort();
+  } catch (error) {
+    console.error("clayjs: page boot abort failed", error);
+  }
+  const disposers = inst.disposers.splice(0).reverse();
+  for (const dispose of disposers) {
+    try {
+      dispose();
+    } catch (error) {
+      console.error("clayjs: a page boot disposer failed", error);
+    }
+  }
+}
+
+export function mark(name, inst) {
+  const perf = globalThis.performance;
+  if (typeof perf?.mark !== "function") return;
+  try {
+    perf.mark(name, { detail: { installId: inst.installId } });
+  } catch (error) {
+    try { perf.mark(name); } catch (ignored) { return; }
+  }
+}
+
+// A boot that ends without an editor gives up what its steps acquired on the way
+// there, through the install's own teardown, before it reports where it stopped.
+function release(inst, steps) {
+  try {
+    steps.release?.(inst);
+  } catch (error) {
+    console.error("clayjs: page boot release failed", error);
+  }
+}
+
+function stop(inst, result, steps) {
+  if (result.cancelled) return null;
+  release(inst, steps);
+  return finishBlocked(inst, result.reason ?? "boot-incomplete");
+}
+
+// A branch of the parallel boot reports its own failure here, so a rejection in one
+// cannot leave an unhandled rejection or a late continuation mounting the other. The
+// mark it owns is emitted when it settles, which is what proves the two overlapped.
+function branch(promise, inst, reason, name = null) {
+  return Promise.resolve(promise)
+    .then((result) => result ?? { ok: false, reason }, (error) => {
+      console.error(`clayjs: page boot ${reason}`, error);
+      return { ok: false, reason };
+    })
+    .then((result) => {
+      if (result.ok && name && isCurrent(inst)) mark(name, inst);
+      return result;
+    });
+}
+
+// The wait on the parallel branches: the first one to fail, or the install's abort,
+// answers it at once. A boot blocked by the download that failed must not sit in
+// `joining` on the join that never answered, and a disposed install must not wait for
+// either of them.
+function settleBranches(inst, branches) {
+  return new Promise((resolve) => {
+    const signal = inst.controller.signal;
+    let done = false;
+    const finish = (outcome) => {
+      if (done) return;
+      done = true;
+      resolve(outcome);
+    };
+    if (signal.aborted) return finish({ cancelled: true });
+    signal.addEventListener("abort", () => finish({ cancelled: true }), { once: true });
+    const results = new Array(branches.length);
+    let left = branches.length;
+    branches.forEach((branch, index) => {
+      branch.then((result) => {
+        if (done) return;
+        if (!result.ok) return finish({ result, branch });
+        results[index] = result;
+        left -= 1;
+        if (left === 0) finish({ results });
+      });
+    });
+  });
+}
+
+// One coordinator for the edit boot: read the source, take the assets while
+// authority is prepared, mount, adopt, then enable input. Every step reports an
+// outcome and every await is followed by an ownership check, so a late or
+// cancelled installation can neither mutate the page nor mark it ready.
+export async function runBoot(inst, steps, { activate = true } = {}) {
+  mark("document:boot", inst);
+  setPhase(inst, PHASES.loading);
+
+  const read = steps.readSource(inst);
+  if (!isCurrent(inst)) return null;
+  if (!read.ok) return finishBlocked(inst, read.reason);
+  const source = read.source;
+
+  // The editor's code arrives while authority is prepared, so the wait is the longer
+  // of the two plus adoption rather than their sum. Neither branch subscribes a
+  // resource or touches the page: only the coordinator does, after both are in.
+  setPhase(inst, PHASES.joining);
+  const settled = await settleBranches(inst, [
+    branch(steps.loadEditorAssets(inst, source), inst, "editor-assets-failed", "document:assets-ready"),
+    branch(steps.prepareAuthority(inst, source), inst, "authority-failed", "document:authority-ready"),
+  ]);
+  if (settled.cancelled || !isCurrent(inst)) return null;
+  if (!settled.results) {
+    // The branch still on the wire is not worth waiting for, and it must not go on to
+    // subscribe anything: the abort ends it where its next ownership check is.
+    try {
+      inst.controller.abort();
+    } catch (error) {
+      console.error("clayjs: page boot abort failed", error);
+    }
+    return stop(inst, settled.result, steps);
+  }
+  const [loaded, admitted] = settled.results;
+
+  const mounted = steps.mountAndAttach(inst, source, loaded, admitted);
+  if (!isCurrent(inst)) return null;
+  if (!mounted.ok) return stop(inst, mounted, steps);
+  inst.mounted = mounted.view ?? null;
+
+  setPhase(inst, PHASES.adopting);
+  const adoption = await steps.adoptSource(inst, source, mounted);
+  if (!isCurrent(inst)) return null;
+  if (!adoption.ok) return stop(inst, adoption, steps);
+
+  // A session that has not committed yet stages the editor and leaves input and every
+  // write closed: the checks input waits for run now, so the commit that opens it has
+  // nothing left to wait on or fail.
+  if (!activate) {
+    if (steps.prepareInput) {
+      const prepared = await steps.prepareInput(inst, mounted);
+      if (!isCurrent(inst)) return null;
+      if (!prepared.ok) return stop(inst, prepared, steps);
+    }
+    inst.deferred = mounted;
+    return { phase: inst.phase, view: mounted.view, deferred: true };
+  }
+
+  const enabled = await steps.enableInput(inst, mounted);
+  if (!isCurrent(inst)) return null;
+  if (!enabled.ok) return stop(inst, enabled, steps);
+
+  mark("document:input-ready", inst);
+  return setPhase(inst, PHASES.ready);
+}
+
+// The commit that enters edit opens the input the preparation held back. Every check
+// it needs passed for this very mount, so it is synchronous: it changes activation
+// only, never durable data.
+export function activateInput(inst) {
+  const mounted = inst.deferred;
+  inst.deferred = null;
+  if (!mounted || !isCurrent(inst)) return inst.result ?? null;
+  const opened = inst.steps?.openInput?.(inst, mounted);
+  if (!opened?.ok) return finishBlocked(inst, opened?.reason ?? "input-refused");
+  mark("document:input-ready", inst);
+  return setPhase(inst, PHASES.ready);
+}

package/src/page/chart-tables.js

@@ -0,0 +1,11 @@
+import { schema } from "./schema.js";
+import { orderedIds } from "./model.js";
+
+// The tables a chart can be drawn from: a top-level table with at least one
+// column. The insert menu reads this without the chart module itself, which only
+// a document that takes a chart loads.
+export function chartTables(doc) {
+  const tables = [];
+  doc.forEach((node) => { if (node.type === schema.nodes.table && orderedIds(node.attrs.cols).length) tables.push(node); });
+  return tables;
+}

package/src/page/chart.js

@@ -1,6 +1,6 @@
-import { state } from "../vendor/prosemirror.vendor.js";
 import { schema } from "./schema.js";
 import { blockJson, keyBetween, newId, orderedIds } from "./model.js";
+import { chartTables } from "./chart-tables.js";
 import { chartModel, renderChartSvg } from "./rich/chart.js";
 import { openPageMenu } from "./chrome.js";
 import { project } from "./projection.js";
@@ -50,11 +50,7 @@ export function insertChartAfterTable(view, tablePos) {
   return true;
 }
 
-export function chartTables(doc) {
-  const tables = [];
-  doc.forEach((node) => { if (node.type === schema.nodes.table && orderedIds(node.attrs.cols).length) tables.push(node); });
-  return tables;
-}
+export { chartTables };
 
 // /chart: an empty line becomes the chart, otherwise it goes below the line.
 // One table is charted at once; several open a picker named by their columns.
@@ -213,8 +209,8 @@ export class ChartView {
   }
 }
 
-export function chartPlugin() {
-  return new state.Plugin({
-    view: () => ({ update(view) { for (const chart of views.get(view) ?? []) chart.refresh(); } }),
-  });
+// The hook the chart view part registers for its editor view: every change can
+// have moved a chart's source table.
+export function refreshCharts(view) {
+  for (const chart of views.get(view) ?? []) chart.refresh();
 }

package/src/page/checklist.js

@@ -1,7 +1,7 @@
 import { state, view as pmView } from "../vendor/prosemirror.vendor.js";
 import { schema } from "./schema.js";
 import { asStep } from "./blocksel.js";
-import { el, cardFace } from "./board-view.js";
+import { el, cardFace } from "./board-face.js";
 
 const { Plugin } = state;
 const { Decoration, DecorationSet } = pmView;

package/src/page/checkpoint-proof.js

@@ -0,0 +1,289 @@
+/**
+ * checkpoint-proof.js — the proof one accepted save produces, and the conditional read
+ * that answers for bytes this tab did not write.
+ *
+ * Step 2 built the proof itself: the recorded revisions, the accepted page state, the
+ * final article and the receipt, checked by `validatePageCheckpoint` before a store
+ * retires anything. What it left here is the producer's half. A proof is made at the
+ * accepted-save event, from the page state pinned to THAT capture, never from the live
+ * store: an edit made after the capture is in the store and is not in the bytes the host
+ * took, and reading the store when the response lands would cover it and clear it.
+ *
+ * Checklist item 2 lives here too. A state that no longer projects to the article that
+ * went to disk proves nothing about those bytes, so an authored transform that changed
+ * meaning, a page rebuilt from another article or a stale tag all produce no proof, and
+ * the records stay.
+ *
+ * The second half is the conditional page-state client: the host's own copy of the page
+ * state, asked for by the accepted ETag, for the cases a local capture cannot answer —
+ * the server's checkpoint, another writer's, and a lost reply that only a verified
+ * refetch can reconcile. Nothing here reads a cookie, a room sequence or a version
+ * string: a 412, a 428 or a 404 keeps every record, and so does any state whose
+ * identity, generation, digest or projection disagrees with what was accepted.
+ *
+ * It loads only when a recovery channel is registered: nothing else imports it.
+ */
+
+import { saveToken } from "../core/host-attrs.js";
+import { setCapturePageState } from "../core/snapshot.js";
+import { canonicalPageBytes, digestHex, pageProof, validatePageCheckpoint } from "./ybind/recovery-proof.js";
+import { articleOfPageState, pageStateOfClone } from "./save-projection.js";
+
+// The capture half. A save capture carries its page state only once something can prove
+// it, so the reader is installed here rather than from the page bundle: a page that
+// journals nothing never pays for it, and a page that does gets the state of the exact
+// clone whose bytes it sends, after every transform.
+setCapturePageState(pageStateOfClone);
+
+/** The only page-state resource version this client reads. */
+export const PAGE_STATE_VERSION = 1;
+
+export class PageCheckpointError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "PageCheckpointError";
+    this.code = code;
+  }
+}
+
+const fail = (code, message) => { throw new PageCheckpointError(code, message); };
+const refused = (code, message) => ({ ok: false, code, message });
+const HEX64 = /^[0-9a-f]{64}$/;
+const GENERATION = /^[0-9a-f]{32}$/;
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+// The state as this tab holds it, copied: a pinned capture's value shares its `y` map
+// with the store's at the moment of the copy and must not share it after.
+function copyState(state) {
+  return { v: state.v, g: state.g, y: { ...(state.y ?? {}) } };
+}
+
+// The state the bytes are decoded from, strictly, and its canonical form.
+function stateOfTag(tag) {
+  let state;
+  try { state = JSON.parse(tag); }
+  catch (_) { fail("invalid-state", "The page state is not JSON"); }
+  if (!isObject(state) || state.v !== 1) fail("invalid-state", "Expected a version 1 Yjs page value");
+  return { state: copyState(state), bytes: canonicalPageBytes(state) };
+}
+
+const idKey = (value) => (value === null || value === undefined ? "" : String(value));
+
+/**
+ * Ask the host for the page state of one accepted version, conditionally.
+ *
+ * The ETag is the one the accepted save carried, so the answer is about those exact
+ * bytes or about nothing. 412 (another version is stored), 428 (no condition was sent,
+ * which no answer of ours can be), 404 (this host keeps no page state) and every other
+ * failure are refusals with a code: the caller keeps its records and asks again later.
+ *
+ * @param {Object} options
+ * @param {string} options.href - the resource discovery named in `document.pageState.href`
+ * @param {string} options.etag - the ETag the accepted bytes were stored under
+ * @param {Function} [options.fetch]
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<{ok: true, version: number, documentId: *, generation: string, etag: string, stateHash: string, tag: string}|{ok: false, code: string, message: string}>}
+ */
+export async function readPageState({ href, etag, fetch: doFetch = globalThis.fetch, signal = null } = {}) {
+  if (typeof etag !== "string" || !etag) return refused("missing-etag", "A conditional read needs the accepted ETag");
+  if (typeof href !== "string" || !href) return refused("no-page-state", "This host names no page-state resource");
+  if (typeof doFetch !== "function") return refused("unavailable", "This tab cannot read the page state");
+  const base = globalThis.location?.href ?? "http://localhost/";
+  let url;
+  try { url = new URL(href, base).href; }
+  catch (_) { return refused("no-page-state", "The page-state resource is not a URL"); }
+  const token = saveToken();
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "GET",
+      credentials: token ? "omit" : "same-origin",
+      headers: { "If-Match": etag, "Document-URL": globalThis.location?.href ?? base },
+      cache: "no-store",
+      redirect: "manual",
+      signal,
+    });
+  } catch (_) {
+    return refused("unavailable", "The page-state request did not complete");
+  }
+  if (!res || typeof res.status !== "number") return refused("unavailable", "The page-state request did not answer");
+  if (res.status === 412) return refused("etag-mismatch", "Another version of this document is stored");
+  if (res.status === 428) return refused("etag-required", "The host needs a condition this read cannot send");
+  if (res.status === 404) return refused("no-page-state", "This host keeps no page state");
+  if (!res.ok) return refused("unavailable", `The host answered ${res.status}`);
+
+  let body;
+  try { body = JSON.parse(await res.text()); }
+  catch (_) { return refused("invalid-state", "The page-state answer is not JSON"); }
+  if (!isObject(body) || body.version !== PAGE_STATE_VERSION) return refused("unsupported-version", "Unknown page-state version");
+  if (typeof body.tag !== "string" || !body.tag) return refused("invalid-state", "The page-state answer carries no page tag");
+  if (typeof body.stateHash !== "string" || !HEX64.test(body.stateHash)) return refused("invalid-state", "The page-state answer carries no state digest");
+  if (typeof body.generation !== "string" || !GENERATION.test(body.generation)) return refused("invalid-state", "The page-state answer carries no generation");
+  if (typeof body.etag !== "string" || !body.etag) return refused("invalid-state", "The page-state answer carries no ETag");
+  if (!Object.hasOwn(body, "documentId")) return refused("invalid-state", "The page-state answer carries no document identity");
+  return {
+    ok: true,
+    version: body.version,
+    documentId: body.documentId,
+    generation: body.generation,
+    etag: body.etag,
+    stateHash: body.stateHash,
+    tag: body.tag,
+  };
+}
+
+/**
+ * Whether a conditional read answers for the version this tab accepted.
+ *
+ * Identity, generation, ETag, digest and projection, in that order: a state for another
+ * document, another generation, another version of the same document or another article
+ * is refused rather than used, and the receipt names the pair the host persisted.
+ *
+ * @param {Object} read - an answer from readPageState()
+ * @param {Object} options
+ * @param {{authority: Object, lineage: Object}} options.accepted
+ * @param {string} options.article - the final outgoing canonical article
+ * @param {string} options.etag - the ETag the accepted save carried
+ * @returns {Promise<{ok: true, state: Object, receipt: {file: string, pageState: string}}|{ok: false, code: string, message: string}>}
+ */
+export async function verifyPageState(read, { accepted, article, etag } = {}) {
+  if (!read || read.ok !== true) return refused(read?.code ?? "unavailable", read?.message ?? "The page state was not read");
+  if (idKey(read.documentId) !== idKey(accepted?.authority?.documentId)) return refused("foreign-document", "The page state belongs to another document");
+  if (typeof accepted?.lineage?.generation !== "string" || read.generation !== accepted.lineage.generation) return refused("foreign-generation", "The page state belongs to another generation");
+  if (read.etag !== etag) return refused("etag-mismatch", "The page state belongs to another version of this document");
+  let stateBytes, state;
+  try { ({ state, bytes: stateBytes } = stateOfTag(read.tag)); }
+  catch (error) { return refused(error?.code ?? "invalid-state", error?.message ?? "The page state does not decode"); }
+  if (await digestHex(stateBytes) !== read.stateHash) return refused("state-digest-mismatch", "The page state is not the one the host hashed");
+  if (typeof article !== "string") return refused("missing-article", "A proof names the final outgoing article");
+  let projected;
+  try { projected = articleOfPageState(state); }
+  catch (error) { return refused("invalid-state", error?.message ?? "The page state does not project"); }
+  if (projected !== article) return refused("article-mismatch", "The page state does not project to the accepted article");
+  return { ok: true, state, receipt: { file: read.etag, pageState: read.stateHash } };
+}
+
+// A proof is only worth the records the validator confirms, over the revisions the
+// caller observed: a proof that covers nothing keeps everything.
+async function covered(proof, records) {
+  const observed = (records || []).map(({ id, revision }) => ({ id, revision }));
+  try {
+    return { ok: true, proof, covered: await validatePageCheckpoint(proof, observed) };
+  } catch (error) {
+    return refused(error?.code ?? "invalid-proof", error?.message ?? "The proof does not validate");
+  }
+}
+
+/**
+ * The proof of one accepted save, from the page state pinned to its capture.
+ *
+ * The receipt is the accepted ETag and the digest of the state the proof is made over,
+ * which is this tab's own account that this capture was written and hashed. Nothing
+ * about a later edit, a store value or an acknowledgement reaches this function.
+ *
+ * @param {Object} options
+ * @param {string} options.capture - the capture the save belongs to
+ * @param {Array<Object>} options.records - {id, revision, update, context} the caller observed
+ * @param {{authority: Object, lineage: Object}} options.accepted
+ * @param {string} options.article - the final outgoing canonical article
+ * @param {Object} options.state - the page state pinned to that capture
+ * @param {string} options.etag - the ETag the accepted save carried
+ * @returns {Promise<{ok: true, proof: Object, covered: Array}|{ok: false, code: string, message: string}>}
+ */
+export async function captureProof({ capture, records = [], accepted, article, state = null, etag = null } = {}) {
+  if (!state) return refused("no-capture-state", "No page state was pinned to this capture");
+  if (typeof etag !== "string" || !etag) return refused("missing-etag", "An accepted save with no ETag proves no stored pair");
+  if (typeof article !== "string") return refused("missing-article", "The accepted bytes hold no article");
+  let projected, stateBytes;
+  try {
+    projected = articleOfPageState(state);
+    stateBytes = canonicalPageBytes(state);
+  } catch (error) {
+    return refused(error?.code ?? "invalid-state", error?.message ?? "The pinned page state does not decode");
+  }
+  if (projected !== article) return refused("article-mismatch", "The pinned page state does not project to the accepted article");
+  let proof;
+  try {
+    proof = await pageProof({
+      capture,
+      records,
+      accepted,
+      article,
+      state,
+      receipt: { file: etag, pageState: await digestHex(stateBytes) },
+    });
+  } catch (error) {
+    return refused(error?.code ?? "invalid-proof", error?.message ?? "The proof could not be built");
+  }
+  return covered(proof, records);
+}
+
+/**
+ * The proof of an accepted save, rebuilt from the page state the host persisted.
+ *
+ * The answer for the server's checkpoint, another writer's, and a save whose reply was
+ * lost: identity, generation and digest are checked against that exact ETag first, and
+ * only then is coverage asked. A host that cannot answer leaves the journal alone.
+ *
+ * @param {Object} options
+ * @param {Object} options.read - an answer from readPageState()
+ * @returns {Promise<{ok: true, proof: Object, covered: Array}|{ok: false, code: string, message: string}>}
+ */
+export async function refetchedProof({ read, capture, records = [], accepted, article, etag = null } = {}) {
+  const verified = await verifyPageState(read, { accepted, article, etag });
+  if (!verified.ok) return verified;
+  let proof;
+  try {
+    proof = await pageProof({ capture, records, accepted, article, state: verified.state, receipt: verified.receipt });
+  } catch (error) {
+    return refused(error?.code ?? "invalid-proof", error?.message ?? "The proof could not be built");
+  }
+  return covered(proof, records);
+}
+
+/**
+ * Retire exactly the records one accepted save covers.
+ *
+ * The pinned capture is tried first, because it needs no request and no host. Only a
+ * capture that cannot prove these bytes asks the host, conditionally on the accepted
+ * ETag. Whichever answers, the channel is handed the caller's observed list and the
+ * proof together: it narrows the list to what the proof covers and never widens it, and
+ * a refusal here retires nothing.
+ *
+ * @param {Object} options
+ * @param {Object} options.channel - the `page.yjs` channel api
+ * @param {Array<Object>} options.records - {id, revision, update, context} the caller observed
+ * @param {string} options.capture
+ * @param {{authority: Object, lineage: Object}} options.accepted
+ * @param {string} options.article
+ * @param {Object} [options.state] - the page state pinned to the capture
+ * @param {string} options.etag
+ * @param {?string} [options.href] - the page-state resource, or null
+ * @param {Function} [options.read]
+ * @param {Function} [options.fetch]
+ * @returns {Promise<{ok: boolean, retired: Array, proof: ?Object, code?: string}>}
+ */
+export async function checkpointAccepted({
+  channel,
+  records = [],
+  capture,
+  accepted,
+  article,
+  state = null,
+  etag = null,
+  href = null,
+  read = readPageState,
+  fetch: doFetch,
+} = {}) {
+  if (!channel || typeof channel.checkpoint !== "function") return { ok: false, code: "no-channel", retired: [], proof: null };
+  let proven = await captureProof({ capture, records, accepted, article, state, etag });
+  if (!proven.ok) {
+    const answer = await read({ href, etag, fetch: doFetch });
+    proven = await refetchedProof({ read: answer, capture, records, accepted, article, etag });
+  }
+  if (!proven.ok) return { ok: false, code: proven.code, retired: [], proof: null };
+  const answer = await channel.checkpoint({ records: proven.covered, proof: proven.proof });
+  if (!answer || answer.ok !== true) return { ok: false, code: answer?.code ?? "checkpoint-failed", retired: [], proof: proven.proof };
+  return { ok: true, retired: answer.retired ?? [], proof: proven.proof };
+}