@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/guarded-version-save.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Comparable form of a version doc's `updatedAt` (AGL-674).
+ *
+ * Deliberately compares for EQUALITY, never ordering. `updatedAt` is written
+ * with a client clock (`Timestamp.now()` in the version converter), so two
+ * machines' timestamps cannot be ordered against each other — but any write
+ * by anyone changes the value, and "did this change since I loaded it" is
+ * the only question conflict detection needs to answer.
+ *
+ * Returns null for a missing/!unrecognised stamp so a doc that has never
+ * been written cannot be mistaken for one that has.
+ */
+export declare function versionStamp(updatedAt: unknown): string | null;
+/**
+ * Whether the stored document has moved since the editor loaded it.
+ *
+ * An absent base means "we never established one" — treated as NOT a
+ * conflict, because refusing every save on a document we failed to stamp
+ * would break editing entirely to protect against a case we cannot
+ * confirm. An absent stored stamp likewise: the doc has no write to
+ * conflict with.
+ */
+export declare function hasConcurrentWrite(baseStamp: string | null, storedStamp: string | null): boolean;
+/**
+ * Whether a map we are about to write already INCORPORATES everything the
+ * stored document gained since we last agreed with it (AGL-2486).
+ *
+ * ## Why the version stamp is the wrong question in a co-edited room
+ *
+ * {@link hasConcurrentWrite} asks "did the stored document move", and that
+ * was the right question while a besigner session was an island. With the
+ * co-edit mirror running it is not: a colleague's changes reach this canvas
+ * node by node, *before* they press Save. So by the time their save moves
+ * the stamp, this session usually already holds what they stored, and its
+ * own write is a SUPERSET of it rather than a clobber. Refusing it protects
+ * nothing and blocks the ordinary rhythm of two people building a page —
+ *
+ * So the question becomes "does my document contain theirs", and this
+ * answers it from evidence rather than from an assumption that the mirror
+ * is healthy:
+ *
+ * * Take every node whose STORED value differs from the baseline. That set
+ *   is exactly what the other writer changed — added, edited or deleted.
+ * * Require our map to carry the stored value for every one of them, an
+ *   absent node included, which is how a deletion is incorporated.
+ *
+ * ## What cannot satisfy it
+ *
+ * A session that has fallen behind. A tab that lost its connection, or
+ * whose mirror entries were reaped, never received those nodes — so it
+ * still holds the BASELINE value for them, which by construction differs
+ * from what is stored, and the very first one refuses the save. Same for a
+ * write that never went through the mirror at all: an admin backfill that
+ * edits `nodes` directly (AGL-1301) is invisible to every canvas in the
+ * room and is caught here exactly as it was by the content check.
+ *
+ * A node we have edited OURSELVES since their value arrived also refuses,
+ * and that is deliberate rather than a gap: it is the same-element
+ * simultaneous edit, the one case co-editing genuinely cannot merge, and
+ * papering over it is how the last writer silently wins. The author is sent
+ * to reload, with their work still on the canvas.
+ *
+ * ## Absent inputs
+ *
+ * A missing baseline or a missing stored map answers FALSE, the opposite of
+ * {@link hasConcurrentWrite}'s "not a conflict". The two defaults face the
+ * same way: that function decides whether to REFUSE, and refusing on no
+ * evidence would break editing; this one decides whether to RELAX a refusal
+ * already justified, and relaxing on no evidence would lose work.
+ */
+export declare function incorporatesStoredNodes(baseNodes: unknown, storedNodes: unknown, ourNodes: unknown): boolean;
+/** Thrown by a guarded save when someone else wrote first. */
+export declare class ConcurrentEditError extends Error {
+    constructor();
+}

package/src/lib/app-utils/guarded-version-save.js

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import isEqual from "lodash-es/isEqual.js";
+/**
+ * Comparable form of a version doc's `updatedAt` (AGL-674).
+ *
+ * Deliberately compares for EQUALITY, never ordering. `updatedAt` is written
+ * with a client clock (`Timestamp.now()` in the version converter), so two
+ * machines' timestamps cannot be ordered against each other — but any write
+ * by anyone changes the value, and "did this change since I loaded it" is
+ * the only question conflict detection needs to answer.
+ *
+ * Returns null for a missing/!unrecognised stamp so a doc that has never
+ * been written cannot be mistaken for one that has.
+ */ export function versionStamp(updatedAt) {
+    if (!updatedAt) return null;
+    const value = updatedAt;
+    if (typeof value.toMillis === 'function') {
+        try {
+            return `ms:${value.toMillis()}`;
+        } catch (unused) {
+        // Fall through to the field form below.
+        }
+    }
+    if (typeof value.seconds === 'number') {
+        var _value_nanoseconds;
+        return `ts:${value.seconds}.${(_value_nanoseconds = value.nanoseconds) != null ? _value_nanoseconds : 0}`;
+    }
+    if (typeof updatedAt === 'number') return `ms:${updatedAt}`;
+    if (typeof updatedAt === 'string') return `s:${updatedAt}`;
+    return null;
+}
+/**
+ * Whether the stored document has moved since the editor loaded it.
+ *
+ * An absent base means "we never established one" — treated as NOT a
+ * conflict, because refusing every save on a document we failed to stamp
+ * would break editing entirely to protect against a case we cannot
+ * confirm. An absent stored stamp likewise: the doc has no write to
+ * conflict with.
+ */ export function hasConcurrentWrite(baseStamp, storedStamp) {
+    if (!baseStamp || !storedStamp) return false;
+    return baseStamp !== storedStamp;
+}
+/**
+ * Whether a map we are about to write already INCORPORATES everything the
+ * stored document gained since we last agreed with it (AGL-2486).
+ *
+ * ## Why the version stamp is the wrong question in a co-edited room
+ *
+ * {@link hasConcurrentWrite} asks "did the stored document move", and that
+ * was the right question while a besigner session was an island. With the
+ * co-edit mirror running it is not: a colleague's changes reach this canvas
+ * node by node, *before* they press Save. So by the time their save moves
+ * the stamp, this session usually already holds what they stored, and its
+ * own write is a SUPERSET of it rather than a clobber. Refusing it protects
+ * nothing and blocks the ordinary rhythm of two people building a page —
+ *
+ * So the question becomes "does my document contain theirs", and this
+ * answers it from evidence rather than from an assumption that the mirror
+ * is healthy:
+ *
+ * * Take every node whose STORED value differs from the baseline. That set
+ *   is exactly what the other writer changed — added, edited or deleted.
+ * * Require our map to carry the stored value for every one of them, an
+ *   absent node included, which is how a deletion is incorporated.
+ *
+ * ## What cannot satisfy it
+ *
+ * A session that has fallen behind. A tab that lost its connection, or
+ * whose mirror entries were reaped, never received those nodes — so it
+ * still holds the BASELINE value for them, which by construction differs
+ * from what is stored, and the very first one refuses the save. Same for a
+ * write that never went through the mirror at all: an admin backfill that
+ * edits `nodes` directly (AGL-1301) is invisible to every canvas in the
+ * room and is caught here exactly as it was by the content check.
+ *
+ * A node we have edited OURSELVES since their value arrived also refuses,
+ * and that is deliberate rather than a gap: it is the same-element
+ * simultaneous edit, the one case co-editing genuinely cannot merge, and
+ * papering over it is how the last writer silently wins. The author is sent
+ * to reload, with their work still on the canvas.
+ *
+ * ## Absent inputs
+ *
+ * A missing baseline or a missing stored map answers FALSE, the opposite of
+ * {@link hasConcurrentWrite}'s "not a conflict". The two defaults face the
+ * same way: that function decides whether to REFUSE, and refusing on no
+ * evidence would break editing; this one decides whether to RELAX a refusal
+ * already justified, and relaxing on no evidence would lose work.
+ */ export function incorporatesStoredNodes(baseNodes, storedNodes, ourNodes) {
+    const base = asNodeMap(baseNodes);
+    const stored = asNodeMap(storedNodes);
+    const ours = asNodeMap(ourNodes);
+    if (!base || !stored || !ours) return false;
+    const ids = new Set([
+        ...Object.keys(base),
+        ...Object.keys(stored)
+    ]);
+    for (const id of ids){
+        // Untouched by them: whatever we hold for it is our own business.
+        if (isEqual(base[id], stored[id])) continue;
+        if (!isEqual(ours[id], stored[id])) return false;
+    }
+    return true;
+}
+function asNodeMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    return value;
+}
+/** Thrown by a guarded save when someone else wrote first. */ export class ConcurrentEditError extends Error {
+    constructor(){
+        super('Someone else saved this document while you were editing. Reload to ' + 'see their changes — your work is still here until you do.');
+        this.name = 'ConcurrentEditError';
+    }
+}
+
+//# sourceMappingURL=guarded-version-save.js.map

package/src/lib/app-utils/guarded-version-save.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/guarded-version-save.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport isEqual from 'lodash-es/isEqual.js'\n\n/**\n * Comparable form of a version doc's `updatedAt` (AGL-674).\n *\n * Deliberately compares for EQUALITY, never ordering. `updatedAt` is written\n * with a client clock (`Timestamp.now()` in the version converter), so two\n * machines' timestamps cannot be ordered against each other — but any write\n * by anyone changes the value, and \"did this change since I loaded it\" is\n * the only question conflict detection needs to answer.\n *\n * Returns null for a missing/!unrecognised stamp so a doc that has never\n * been written cannot be mistaken for one that has.\n */\nexport function versionStamp(updatedAt: unknown): string | null {\n  if (!updatedAt) return null\n  const value = updatedAt as {\n    seconds?: number\n    nanoseconds?: number\n    toMillis?: () => number\n  }\n  if (typeof value.toMillis === 'function') {\n    try {\n      return `ms:${value.toMillis()}`\n    } catch {\n      // Fall through to the field form below.\n    }\n  }\n  if (typeof value.seconds === 'number') {\n    return `ts:${value.seconds}.${value.nanoseconds ?? 0}`\n  }\n  if (typeof updatedAt === 'number') return `ms:${updatedAt}`\n  if (typeof updatedAt === 'string') return `s:${updatedAt}`\n  return null\n}\n\n/**\n * Whether the stored document has moved since the editor loaded it.\n *\n * An absent base means \"we never established one\" — treated as NOT a\n * conflict, because refusing every save on a document we failed to stamp\n * would break editing entirely to protect against a case we cannot\n * confirm. An absent stored stamp likewise: the doc has no write to\n * conflict with.\n */\nexport function hasConcurrentWrite(\n  baseStamp: string | null,\n  storedStamp: string | null,\n): boolean {\n  if (!baseStamp || !storedStamp) return false\n  return baseStamp !== storedStamp\n}\n\n/**\n * Whether a map we are about to write already INCORPORATES everything the\n * stored document gained since we last agreed with it (AGL-2486).\n *\n * ## Why the version stamp is the wrong question in a co-edited room\n *\n * {@link hasConcurrentWrite} asks \"did the stored document move\", and that\n * was the right question while a besigner session was an island. With the\n * co-edit mirror running it is not: a colleague's changes reach this canvas\n * node by node, *before* they press Save. So by the time their save moves\n * the stamp, this session usually already holds what they stored, and its\n * own write is a SUPERSET of it rather than a clobber. Refusing it protects\n * nothing and blocks the ordinary rhythm of two people building a page —\n *\n * So the question becomes \"does my document contain theirs\", and this\n * answers it from evidence rather than from an assumption that the mirror\n * is healthy:\n *\n * * Take every node whose STORED value differs from the baseline. That set\n *   is exactly what the other writer changed — added, edited or deleted.\n * * Require our map to carry the stored value for every one of them, an\n *   absent node included, which is how a deletion is incorporated.\n *\n * ## What cannot satisfy it\n *\n * A session that has fallen behind. A tab that lost its connection, or\n * whose mirror entries were reaped, never received those nodes — so it\n * still holds the BASELINE value for them, which by construction differs\n * from what is stored, and the very first one refuses the save. Same for a\n * write that never went through the mirror at all: an admin backfill that\n * edits `nodes` directly (AGL-1301) is invisible to every canvas in the\n * room and is caught here exactly as it was by the content check.\n *\n * A node we have edited OURSELVES since their value arrived also refuses,\n * and that is deliberate rather than a gap: it is the same-element\n * simultaneous edit, the one case co-editing genuinely cannot merge, and\n * papering over it is how the last writer silently wins. The author is sent\n * to reload, with their work still on the canvas.\n *\n * ## Absent inputs\n *\n * A missing baseline or a missing stored map answers FALSE, the opposite of\n * {@link hasConcurrentWrite}'s \"not a conflict\". The two defaults face the\n * same way: that function decides whether to REFUSE, and refusing on no\n * evidence would break editing; this one decides whether to RELAX a refusal\n * already justified, and relaxing on no evidence would lose work.\n */\nexport function incorporatesStoredNodes(\n  baseNodes: unknown,\n  storedNodes: unknown,\n  ourNodes: unknown,\n): boolean {\n  const base = asNodeMap(baseNodes)\n  const stored = asNodeMap(storedNodes)\n  const ours = asNodeMap(ourNodes)\n  if (!base || !stored || !ours) return false\n  const ids = new Set([...Object.keys(base), ...Object.keys(stored)])\n  for (const id of ids) {\n    // Untouched by them: whatever we hold for it is our own business.\n    if (isEqual(base[id], stored[id])) continue\n    if (!isEqual(ours[id], stored[id])) return false\n  }\n  return true\n}\n\nfunction asNodeMap(value: unknown): Record<string, unknown> | null {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return null\n  return value as Record<string, unknown>\n}\n\n/** Thrown by a guarded save when someone else wrote first. */\nexport class ConcurrentEditError extends Error {\n  constructor() {\n    super(\n      'Someone else saved this document while you were editing. Reload to ' +\n        'see their changes — your work is still here until you do.',\n    )\n    this.name = 'ConcurrentEditError'\n  }\n}\n"],"names":["isEqual","versionStamp","updatedAt","value","toMillis","seconds","nanoseconds","hasConcurrentWrite","baseStamp","storedStamp","incorporatesStoredNodes","baseNodes","storedNodes","ourNodes","base","asNodeMap","stored","ours","ids","Set","Object","keys","id","Array","isArray","ConcurrentEditError","Error","name"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,OAAOA,aAAa,uBAAsB;AAE1C;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,aAAaC,SAAkB;IAC7C,IAAI,CAACA,WAAW,OAAO;IACvB,MAAMC,QAAQD;IAKd,IAAI,OAAOC,MAAMC,QAAQ,KAAK,YAAY;QACxC,IAAI;YACF,OAAO,CAAC,GAAG,EAAED,MAAMC,QAAQ,IAAI;QACjC,EAAE,eAAM;QACN,wCAAwC;QAC1C;IACF;IACA,IAAI,OAAOD,MAAME,OAAO,KAAK,UAAU;YACPF;QAA9B,OAAO,CAAC,GAAG,EAAEA,MAAME,OAAO,CAAC,CAAC,GAAEF,qBAAAA,MAAMG,WAAW,YAAjBH,qBAAqB,GAAG;IACxD;IACA,IAAI,OAAOD,cAAc,UAAU,OAAO,CAAC,GAAG,EAAEA,WAAW;IAC3D,IAAI,OAAOA,cAAc,UAAU,OAAO,CAAC,EAAE,EAAEA,WAAW;IAC1D,OAAO;AACT;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASK,mBACdC,SAAwB,EACxBC,WAA0B;IAE1B,IAAI,CAACD,aAAa,CAACC,aAAa,OAAO;IACvC,OAAOD,cAAcC;AACvB;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GACD,OAAO,SAASC,wBACdC,SAAkB,EAClBC,WAAoB,EACpBC,QAAiB;IAEjB,MAAMC,OAAOC,UAAUJ;IACvB,MAAMK,SAASD,UAAUH;IACzB,MAAMK,OAAOF,UAAUF;IACvB,IAAI,CAACC,QAAQ,CAACE,UAAU,CAACC,MAAM,OAAO;IACtC,MAAMC,MAAM,IAAIC,IAAI;WAAIC,OAAOC,IAAI,CAACP;WAAUM,OAAOC,IAAI,CAACL;KAAQ;IAClE,KAAK,MAAMM,MAAMJ,IAAK;QACpB,kEAAkE;QAClE,IAAIlB,QAAQc,IAAI,CAACQ,GAAG,EAAEN,MAAM,CAACM,GAAG,GAAG;QACnC,IAAI,CAACtB,QAAQiB,IAAI,CAACK,GAAG,EAAEN,MAAM,CAACM,GAAG,GAAG,OAAO;IAC7C;IACA,OAAO;AACT;AAEA,SAASP,UAAUZ,KAAc;IAC/B,IAAI,CAACA,SAAS,OAAOA,UAAU,YAAYoB,MAAMC,OAAO,CAACrB,QAAQ,OAAO;IACxE,OAAOA;AACT;AAEA,4DAA4D,GAC5D,OAAO,MAAMsB,4BAA4BC;IACvC,aAAc;QACZ,KAAK,CACH,wEACE;QAEJ,IAAI,CAACC,IAAI,GAAG;IACd;AACF"}