@grafloria/element 0.3.19 → 0.3.21

package/src/libs/engine/src/comments/mentions.js

@@ -1,94 +0,0 @@
-"use strict";
-// Wave 9 — Card 6: @mentions.
-//
-// ===========================================================================
-// A SEAM, NOT A NOTIFICATION BACKEND
-// ===========================================================================
-//
-// A diagram engine has no business owning email, push, Slack or a user directory. What
-// it CAN own, and what nobody else can, is the two facts a notifier needs and cannot
-// reconstruct: WHO was mentioned, and WHICH message mentioned them. That is the seam.
-//
-// THE HARD PART IS NOT PARSING. It is that a collaborative document has N peers, every
-// one of which will observe the same @mention op, and every one of which will fire this
-// event. Wire a naive notifier to it and Ada gets one email per peer that happened to
-// have the file open. That is not a hypothetical: it is what happens the first time
-// somebody does the obvious thing.
-//
-// So the event carries an IDEMPOTENCY KEY — `${threadId}:${messageId}` — which is the
-// SAME string on every peer, forever, across reloads and replays, because it is derived
-// from data carried in the op rather than from anything local. A host has two correct
-// ways to use it, and the seam supports both:
-//
-//   • SERVER-SIDE (recommended): run the notifier on the relay/server replica only. It
-//     sees every op exactly once and is the only peer that should hold mail credentials.
-//   • CLIENT-SIDE: fire from every peer and DEDUPE ON `key` at the backend (an upsert on
-//     a unique index, a Redis SETNX, whatever). The key makes that a one-liner.
-//
-// What a host must wire, in full:
-//   1. an implementation of MentionNotifier (email/push/websocket/whatever),
-//   2. a directory that maps the ids in `mentioned` to real users — the engine never
-//      invents one, because a mention id is a HOST identifier and only the host knows
-//      what `@ada` means,
-//   3. deduplication on `key` (or a single privileged replica).
-//
-// Everything else is done here.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseMentions = parseMentions;
-exports.mentionIds = mentionIds;
-exports.mentionKey = mentionKey;
-/**
- * Two syntaxes, because two things are true at once.
- *
- * `@[Ada Lovelace](u_ada)` — what a real mention-PICKER emits: the display name and the
- * stable id, decoupled, so renaming Ada does not orphan the mention and two Adas do not
- * collide. This is the form the product should write.
- *
- * `@ada` — what a human TYPES. It is ambiguous by nature (a handle is not an id), and we
- * do not pretend otherwise: the id is the handle verbatim, and it is the host's directory
- * that decides whether `ada` resolves to anyone at all. Refusing to parse it would just
- * mean every host writes this regex again, worse.
- *
- * Ordered `@[...](...)` first so the explicit form is never mis-lexed as a bare handle.
- */
-const EXPLICIT = /@\[([^\]\n]+)\]\(([^)\s]+)\)/g;
-// A bare handle: letters, digits, dot, dash, underscore. Must not be preceded by a word
-// character — otherwise every email address in a comment becomes a mention of its domain.
-const BARE = /(^|[^\w@[\]()])@([A-Za-z0-9][\w.-]*)/g;
-/**
- * Extract the mentions from a body. Pure, and total: never throws, never re-orders.
- *
- * Deduplicated by id — mentioning Ada three times in one message is one notification, not
- * three, and that is a property of the DATA, not of the notifier's retry policy.
- */
-function parseMentions(body) {
-    if (!body)
-        return [];
-    const found = [];
-    const claimed = [];
-    EXPLICIT.lastIndex = 0;
-    for (let m = EXPLICIT.exec(body); m; m = EXPLICIT.exec(body)) {
-        found.push({ id: m[2], display: m[1], raw: m[0], index: m.index });
-        claimed.push([m.index, m.index + m[0].length]);
-    }
-    BARE.lastIndex = 0;
-    for (let m = BARE.exec(body); m; m = BARE.exec(body)) {
-        const at = m.index + m[1].length; // skip the required preceding character
-        // Do not double-count the `@` of an explicit mention we already took.
-        if (claimed.some(([s, e]) => at >= s && at < e))
-            continue;
-        found.push({ id: m[2], display: m[2], raw: `@${m[2]}`, index: at });
-    }
-    found.sort((a, b) => a.index - b.index);
-    const seen = new Set();
-    return found.filter((r) => (seen.has(r.id) ? false : (seen.add(r.id), true)));
-}
-/** Just the ids — what gets stored on the message register. */
-function mentionIds(body) {
-    return parseMentions(body).map((r) => r.id);
-}
-/** The idempotency key. Derived only from op-borne data — never from local state. */
-function mentionKey(threadId, messageId) {
-    return `${threadId}:${messageId}`;
-}
-//# sourceMappingURL=mentions.js.map

package/src/libs/engine/src/comments/mentions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mentions.js","sourceRoot":"","sources":["../../../../../../engine/src/comments/mentions.ts"],"names":[],"mappings":"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"}

package/src/libs/engine/src/comments/read-state.d.ts

@@ -1,37 +0,0 @@
-import { type CommentMessage } from './types';
-/** The serializable shape. Give this to the host to persist; hand it back on load. */
-export interface SerializedReadState {
-    viewer: string;
-    /** threadId → the messageKey of the newest message this viewer has seen. */
-    watermarks: Record<string, string>;
-}
-/**
- * What THIS viewer has seen. Local. Never synced.
- */
-export declare class ReadState {
-    readonly viewer: string;
-    private readonly watermarks;
-    constructor(viewer: string);
-    /**
-     * Mark a thread read up to its newest message.
-     *
-     * Takes the messages rather than a key so the caller cannot accidentally set a
-     * watermark ahead of the messages it has actually seen — which would silently swallow
-     * a message that is still in flight.
-     */
-    markRead(threadId: string, messages: readonly CommentMessage[]): void;
-    /** Explicitly mark unread again (a "mark as unread" affordance). */
-    markUnread(threadId: string): void;
-    /**
-     * How many messages in this thread the viewer has not seen.
-     *
-     * A message YOU wrote is never unread — you were there. A tombstoned message is never
-     * unread either: a badge that says "1 unread" and opens onto "message deleted" is a
-     * badge that has wasted someone's attention, which is the only currency a notification
-     * has.
-     */
-    unreadCount(threadId: string, messages: readonly CommentMessage[]): number;
-    isRead(threadId: string, messages: readonly CommentMessage[]): boolean;
-    toJSON(): SerializedReadState;
-    static fromJSON(data: SerializedReadState): ReadState;
-}

package/src/libs/engine/src/comments/read-state.js

@@ -1,105 +0,0 @@
-"use strict";
-// Wave 9 — Card 6: unread markers.
-//
-// ===========================================================================
-// READ STATE IS NOT DOCUMENT STATE. THIS IS THE WHOLE FILE.
-// ===========================================================================
-//
-// Everything else in this card rides the op log, because everything else is a fact about
-// the DOCUMENT. "Ada has read this thread" is not a fact about the document. It is a fact
-// about Ada. Putting it in the shared log would be wrong three separate ways, and it is
-// the single most common mistake in this feature:
-//
-//   1. WRONG SEMANTICS. Ada opens a thread; the op replicates; Ben's unread badge clears.
-//      Ben never read it. The badge — the one thing whose entire job is to tell YOU what
-//      YOU have not seen — now lies to everyone but the last person to scroll.
-//   2. WRONG ECONOMICS. Reading is the most common action in a comment system by two
-//      orders of magnitude. Making every read a broadcast op turns a passive act into
-//      write traffic to every peer, and it puts it in the persisted history forever.
-//   3. WRONG LIFETIME. It would be replayed, undone, and merged. Undoing a node move
-//      should not mark a comment unread again.
-//
-// So read state is LOCAL, per viewer, and the seam to persist it is `toJSON()`/`fromJSON()`
-// — the host puts it in localStorage or on its own user-scoped API. That is a seam with no
-// machinery behind it, which is the correct amount for something the engine cannot know.
-//
-// (A product that genuinely wants shared "seen by" receipts wants a DIFFERENT feature —
-// per-user receipts keyed by user id, which is additive shared data rather than a shared
-// mutable flag. Not built, deliberately, and called out so nobody mistakes its absence
-// for an oversight.)
-//
-// THE MARKER IS A WATERMARK, NOT A COUNT. We store the sort key of the newest message the
-// viewer has seen in each thread. A count would be wrong the instant a message arrived
-// out of order or a tombstone changed the length; a watermark is monotone and compares
-// against the SAME total order the messages are displayed in (`messageKey`).
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReadState = void 0;
-const types_1 = require("./types");
-/**
- * What THIS viewer has seen. Local. Never synced.
- */
-class ReadState {
-    constructor(viewer) {
-        this.viewer = viewer;
-        this.watermarks = new Map();
-    }
-    /**
-     * Mark a thread read up to its newest message.
-     *
-     * Takes the messages rather than a key so the caller cannot accidentally set a
-     * watermark ahead of the messages it has actually seen — which would silently swallow
-     * a message that is still in flight.
-     */
-    markRead(threadId, messages) {
-        var _a;
-        let max = (_a = this.watermarks.get(threadId)) !== null && _a !== void 0 ? _a : '';
-        for (const m of messages) {
-            const k = (0, types_1.messageKey)(m);
-            if (k > max)
-                max = k;
-        }
-        if (max)
-            this.watermarks.set(threadId, max);
-    }
-    /** Explicitly mark unread again (a "mark as unread" affordance). */
-    markUnread(threadId) {
-        this.watermarks.delete(threadId);
-    }
-    /**
-     * How many messages in this thread the viewer has not seen.
-     *
-     * A message YOU wrote is never unread — you were there. A tombstoned message is never
-     * unread either: a badge that says "1 unread" and opens onto "message deleted" is a
-     * badge that has wasted someone's attention, which is the only currency a notification
-     * has.
-     */
-    unreadCount(threadId, messages) {
-        var _a;
-        const mark = (_a = this.watermarks.get(threadId)) !== null && _a !== void 0 ? _a : '';
-        let n = 0;
-        for (const m of messages) {
-            if (m.deleted)
-                continue;
-            if (m.author === this.viewer)
-                continue;
-            if ((0, types_1.messageKey)(m) > mark)
-                n++;
-        }
-        return n;
-    }
-    isRead(threadId, messages) {
-        return this.unreadCount(threadId, messages) === 0;
-    }
-    toJSON() {
-        return { viewer: this.viewer, watermarks: Object.fromEntries(this.watermarks) };
-    }
-    static fromJSON(data) {
-        var _a;
-        const rs = new ReadState(data.viewer);
-        for (const [k, v] of Object.entries((_a = data.watermarks) !== null && _a !== void 0 ? _a : {}))
-            rs.watermarks.set(k, v);
-        return rs;
-    }
-}
-exports.ReadState = ReadState;
-//# sourceMappingURL=read-state.js.map

package/src/libs/engine/src/comments/read-state.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"read-state.js","sourceRoot":"","sources":["../../../../../../engine/src/comments/read-state.ts"],"names":[],"mappings":";AAAA,mCAAmC;AACnC,EAAE;AACF,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAC9E,EAAE;AACF,yFAAyF;AACzF,0FAA0F;AAC1F,wFAAwF;AACxF,kDAAkD;AAClD,EAAE;AACF,0FAA0F;AAC1F,yFAAyF;AACzF,+EAA+E;AAC/E,qFAAqF;AACrF,sFAAsF;AACtF,qFAAqF;AACrF,qFAAqF;AACrF,+CAA+C;AAC/C,EAAE;AACF,4FAA4F;AAC5F,2FAA2F;AAC3F,yFAAyF;AACzF,EAAE;AACF,wFAAwF;AACxF,yFAAyF;AACzF,uFAAuF;AACvF,qBAAqB;AACrB,EAAE;AACF,0FAA0F;AAC1F,uFAAuF;AACvF,uFAAuF;AACvF,6EAA6E;;;AAE7E,mCAA0D;AAS1D;;GAEG;AACH,MAAa,SAAS;IAGpB,YAAqB,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;QAFlB,eAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAElB,CAAC;IAEvC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAgB,EAAE,QAAmC;;QAC5D,IAAI,GAAG,GAAG,MAAA,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,mCAAI,EAAE,CAAC;QAC9C,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,IAAA,kBAAU,EAAC,CAAC,CAAC,CAAC;YACxB,IAAI,CAAC,GAAG,GAAG;gBAAE,GAAG,GAAG,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,GAAG;YAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,oEAAoE;IACpE,UAAU,CAAC,QAAgB;QACzB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CAAC,QAAgB,EAAE,QAAmC;;QAC/D,MAAM,IAAI,GAAG,MAAA,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,mCAAI,EAAE,CAAC;QACjD,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,CAAC,OAAO;gBAAE,SAAS;YACxB,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;gBAAE,SAAS;YACvC,IAAI,IAAA,kBAAU,EAAC,CAAC,CAAC,GAAG,IAAI;gBAAE,CAAC,EAAE,CAAC;QAChC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,CAAC,QAAgB,EAAE,QAAmC;QAC1D,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;IAClF,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAyB;;QACvC,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAA,IAAI,CAAC,UAAU,mCAAI,EAAE,CAAC;YAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpF,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AA1DD,8BA0DC"}

package/src/libs/engine/src/comments/types.d.ts

@@ -1,154 +0,0 @@
-/** A point in WORLD space. Never screen space — see CommentAnchor. */
-export interface WorldPoint {
-    x: number;
-    y: number;
-}
-/**
- * WHAT A COMMENT IS ABOUT.
- *
- * ANCHOR BY IDENTITY, NEVER BY COORDINATES — for anything that has an identity. A
- * comment pinned to (420, 180) is a comment about whatever happens to be at (420, 180)
- * *right now*, which after one auto-layout is a different node and a different meaning.
- * The comment would still be there, still timestamped, still confidently wrong. So a
- * node/link anchor stores the ENTITY ID and derives its position from the live entity
- * every frame; move the node across the canvas and the pin comes with it, and not one
- * op is emitted to make that happen (position is derived, and derived state is never
- * synced — the same rule capture.ts applies to link routes).
- *
- * A FREE-REGION anchor genuinely is coordinates, and they are WORLD coordinates. Screen
- * coordinates would make the pin's meaning depend on the reader's scroll position and
- * zoom — a note about the top-right corner of a subsystem would drift onto empty canvas
- * the moment anyone panned. World coordinates are invariant under pan and zoom by
- * construction, and the renderer draws them inside the viewBox, so the pin sticks to
- * the diagram rather than to the glass.
- *
- * `fallback` and `targetLabel` are the ANCHOR'S OBITUARY: where the target was and what
- * it was called, captured at the moment the thread was created. They exist for exactly
- * one purpose — so that a thread whose target has been DELETED can still be shown, in
- * the right place, saying what it was about. See ResolvedAnchor.
- */
-export type CommentAnchor = {
-    kind: 'node';
-    /** The node this thread is about. The pin follows it. */
-    id: string;
-    /** Where it was when the thread was created. Used only if the node is gone. */
-    fallback: WorldPoint;
-    /** What it was called when the thread was created. Used only if the node is gone. */
-    targetLabel?: string;
-} | {
-    kind: 'link';
-    id: string;
-    fallback: WorldPoint;
-    targetLabel?: string;
-} | {
-    /** A note about a REGION of the canvas, attached to nothing. World coordinates. */
-    kind: 'region';
-    x: number;
-    y: number;
-    width?: number;
-    height?: number;
-};
-/** Write-once thread identity. One register, so a thread appears whole or not at all. */
-export interface CommentThreadHead {
-    id: string;
-    /** The PERSON who started the thread (a user id, not a session/actor id). */
-    author: string;
-    /**
-     * Wall-clock milliseconds, captured at authoring time and carried IN the op.
-     *
-     * The substrate bans wall time from deciding CAUSALITY, and rightly: a clock that
-     * runs backwards would corrupt merge. It does not ban wall time from being DATA.
-     * `Date.now()` read inside a reducer destroys replay determinism; `Date.now()`
-     * captured into an op's payload at the moment a human pressed Enter is just a
-     * number, identical on every peer forever. This is the latter.
-     */
-    createdAt: number;
-}
-/** Resolve/reopen. ONE register, so the flag and its attribution can never split. */
-export interface CommentThreadStatus {
-    resolved: boolean;
-    by: string;
-    at: number;
-}
-/**
- * One message. ONE register — the rule that makes concurrent replies survive.
- *
- * An edit rewrites the whole register (an edit IS a whole-body replacement, so nothing
- * is gained by splitting it). A delete rewrites it as a TOMBSTONE — `deleted: true`,
- * body cleared, author and createdAt kept — rather than removing the key, because
- * removing it would let a concurrent edit resurrect the message with no body, and
- * because the ordering of the surviving messages must not shift under a peer that has
- * not yet seen the delete.
- */
-export interface CommentMessage {
-    id: string;
-    author: string;
-    body: string;
-    createdAt: number;
-    /** User ids extracted from the body at authoring time. Convergent, queryable. */
-    mentions?: string[];
-    editedAt?: number;
-    deleted?: boolean;
-}
-/** The raw register tree as it sits on the model and in the serialized document. */
-export interface StoredThread {
-    head?: CommentThreadHead;
-    anchor?: CommentAnchor;
-    status?: CommentThreadStatus;
-    messages?: Record<string, CommentMessage>;
-}
-export type CommentRegisterTree = Record<string, StoredThread>;
-/**
- * WHERE A THREAD'S PIN GOES, AND WHETHER ITS SUBJECT STILL EXISTS.
- *
- * `attached` is DERIVED — computed from the live diagram on every read, never stored
- * and never synced. That is the single most important decision in this file, and it is
- * argued at length in comment-store.ts (`resolveAnchor`).
- */
-export interface ResolvedAnchor {
-    /** World coordinates for the pin. */
-    point: WorldPoint;
-    /** False ⇒ ORPHANED: the node/link this thread is about is not in the diagram. */
-    attached: boolean;
-    /** The live label if attached; the snapshot taken at anchor time if not. */
-    targetLabel: string;
-    targetKind: 'node' | 'link' | 'region';
-    targetId?: string;
-}
-/** A thread, assembled for reading: sorted messages, derived anchor, viewer's unread count. */
-export interface CommentThreadView {
-    id: string;
-    author: string;
-    createdAt: number;
-    anchor: CommentAnchor;
-    resolved: boolean;
-    resolvedBy?: string;
-    resolvedAt?: number;
-    /** Total order, identical on every peer. Tombstones included (flagged `deleted`). */
-    messages: CommentMessage[];
-    /** Messages this viewer has not seen, authored by someone else. LOCAL, never synced. */
-    unread: number;
-    /** Derived from the live diagram — see ResolvedAnchor. */
-    resolvedAnchor: ResolvedAnchor;
-}
-/**
- * THE TOTAL ORDER ON MESSAGES.
- *
- * Every peer must list a thread's messages in the SAME order or two people reading the
- * same conversation read different conversations. `(createdAt, author, id)` is total
- * (ids are unique) and it is computed from data that travels IN the ops, so it is
- * identical on every peer and stable across replay.
- *
- * It is wall time, and that is a deliberate, bounded concession. Wall time may not
- * decide MERGE — a skewed clock deciding which edit wins is silent data loss, which is
- * why the substrate uses Lamport clocks for that and why this function is not used for
- * anything but display order. Wall time deciding the ORDER OF A CHAT LIST is what every
- * messaging product on earth does, and its worst case is cosmetic: two messages sent
- * within the clock skew of each other may read in the wrong order. Nobody loses a
- * comment. (The alternative — a per-message Lamport stamp — is unavailable without
- * reaching into OpCapture's clock, and buying strict causal order for a chat list at
- * the price of a second way to mint stamps is a bad trade.)
- */
-export declare function messageOrder(a: CommentMessage, b: CommentMessage): number;
-/** The sort key of a message, as an opaque comparable string. Used by read-state. */
-export declare function messageKey(m: CommentMessage): string;

package/src/libs/engine/src/comments/types.js

@@ -1,107 +0,0 @@
-"use strict";
-// Wave 9 (Collaboration) — Card 6: comments, annotations & @mentions.
-//
-// ===========================================================================
-// WHERE COMMENTS LIVE, AND WHY
-// ===========================================================================
-//
-// Comments RIDE THE OP LOG. They are not a side store. `diagram.comments` is a
-// register namespace on the model, written through the same `set(diagram, …)` ops
-// as everything else, so a comment gets convergence, transport, persistence and
-// causal ordering for free — the same four things every other card had to build.
-//
-//   • CONVERGENCE. Two people commenting on the same node, offline, must both keep
-//     their comment. Riding the log means the LWW register table (Card 0) already
-//     decides this — provided the REGISTERS ARE CUT CORRECTLY, which is the whole
-//     of the design below.
-//   • TRANSPORT. The sync card (Card 5) ships ops. Comments ship with them. No second
-//     channel, no second auth handshake, no second reconnect/backfill path.
-//   • PERSISTENCE. serialize() → save → fromJSON, and replay(log) reconstructs the
-//     comments exactly as it reconstructs the nodes.
-//   • CAUSALITY. A comment saying "delete this box" and the deletion of the box are
-//     ordered against each other by the same Lamport clock. Two clocks would not be.
-//
-// THE ARGUMENT FOR A SEPARATE STORE, honestly: comments are unbounded text, they are
-// a distinct privacy/ACL surface (a reviewer may comment but not edit), and you may
-// want to load them lazily. That is a real argument, and it is answered WITHOUT a
-// second store: the register namespace `comments.*` IS the seam. A host that wants
-// separate storage or separate ACLs filters ops by `op.path.startsWith('comments.')`
-// at the transport — a three-line predicate — and gets both. Splitting the store to
-// buy that would cost a second clock, and a second clock is not free (see below).
-//
-// A SECOND CLOCK IS A BUG, not a design choice. `opId()` is `${clock}@${actor}`. Give
-// comments their own LamportClock under the same actor and the very first comment
-// mints op id `1@alice` — which the OpLog has already seen (alice's first node edit)
-// and therefore SILENTLY DROPS. The comment is gone. No error. That single fact is
-// what makes "reuse the diagram's op stream" the only cheap answer.
-//
-// ===========================================================================
-// HOW THE REGISTERS ARE CUT — the part that decides whether comments survive
-// ===========================================================================
-//
-// A register is a property path, and LWW resolves two writes to the SAME path. So the
-// cut of the paths IS the concurrency semantics. Two rules, both load-bearing:
-//
-//   1. ONE MESSAGE = ONE REGISTER (`comments.<tid>.messages.<mid>`).
-//      This is the rule that makes concurrent replies safe. Two people replying to the
-//      same thread while offline write to DIFFERENT registers (different message ids),
-//      so LWW never has to choose and BOTH replies survive. Store the messages as a
-//      single `messages: [...]` array register instead — the obvious shape — and the
-//      two replies collide on one register, LWW picks one, and somebody's comment is
-//      deleted by a stranger. Silently. (There is a test that builds exactly that
-//      wrong design and watches it lose a message, so the claim is demonstrated and
-//      not merely asserted.)
-//
-//   2. THE WRITTEN PATHS ARE PREFIX-FREE. No path we ever write is a prefix of another
-//      path we ever write. This is not tidiness, it is correctness under out-of-order
-//      delivery: `set(comments.t1)` and `set(comments.t1.status)` are DIFFERENT LWW
-//      registers, so the gate cannot order them — whichever is APPLIED last wins, and
-//      arrival order is a property of the network. A late whole-thread write would
-//      silently wipe a resolve. So a thread is written as leaves:
-//
-//          comments.<tid>.head              { id, author, createdAt }   — write-once
-//          comments.<tid>.anchor            CommentAnchor               — re-anchorable
-//          comments.<tid>.status            { resolved, by, at }        — resolve/reopen
-//          comments.<tid>.messages.<mid>    CommentMessage              — one per message
-//
-//      `comments.<tid>` and `comments.<tid>.messages` are NEVER written. The fuzz test
-//      asserts prefix-freedom over every op the store has ever emitted, so this cannot
-//      rot.
-//
-// A consequence, faced rather than hidden: a thread arrives as SEVERAL ops, and an
-// unreliable transport can deliver a message before the head that owns it. The read
-// model therefore treats an incomplete thread as INVISIBLE, not as a crash and not as
-// a half-thread — it appears, whole, when its head lands. See `readThreads`.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.messageOrder = messageOrder;
-exports.messageKey = messageKey;
-/**
- * THE TOTAL ORDER ON MESSAGES.
- *
- * Every peer must list a thread's messages in the SAME order or two people reading the
- * same conversation read different conversations. `(createdAt, author, id)` is total
- * (ids are unique) and it is computed from data that travels IN the ops, so it is
- * identical on every peer and stable across replay.
- *
- * It is wall time, and that is a deliberate, bounded concession. Wall time may not
- * decide MERGE — a skewed clock deciding which edit wins is silent data loss, which is
- * why the substrate uses Lamport clocks for that and why this function is not used for
- * anything but display order. Wall time deciding the ORDER OF A CHAT LIST is what every
- * messaging product on earth does, and its worst case is cosmetic: two messages sent
- * within the clock skew of each other may read in the wrong order. Nobody loses a
- * comment. (The alternative — a per-message Lamport stamp — is unavailable without
- * reaching into OpCapture's clock, and buying strict causal order for a chat list at
- * the price of a second way to mint stamps is a bad trade.)
- */
-function messageOrder(a, b) {
-    if (a.createdAt !== b.createdAt)
-        return a.createdAt - b.createdAt;
-    if (a.author !== b.author)
-        return a.author < b.author ? -1 : 1;
-    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-}
-/** The sort key of a message, as an opaque comparable string. Used by read-state. */
-function messageKey(m) {
-    return `${String(m.createdAt).padStart(16, '0')}|${m.author}|${m.id}`;
-}
-//# sourceMappingURL=types.js.map

package/src/libs/engine/src/comments/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../engine/src/comments/types.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,kFAAkF;AAClF,gFAAgF;AAChF,iFAAiF;AACjF,EAAE;AACF,mFAAmF;AACnF,kFAAkF;AAClF,kFAAkF;AAClF,2BAA2B;AAC3B,sFAAsF;AACtF,4EAA4E;AAC5E,mFAAmF;AACnF,qDAAqD;AACrD,oFAAoF;AACpF,qFAAqF;AACrF,EAAE;AACF,qFAAqF;AACrF,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,qFAAqF;AACrF,oFAAoF;AACpF,kFAAkF;AAClF,EAAE;AACF,sFAAsF;AACtF,kFAAkF;AAClF,qFAAqF;AACrF,mFAAmF;AACnF,oEAAoE;AACpE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,EAAE;AACF,sFAAsF;AACtF,+EAA+E;AAC/E,EAAE;AACF,qEAAqE;AACrE,uFAAuF;AACvF,uFAAuF;AACvF,oFAAoF;AACpF,qFAAqF;AACrF,qFAAqF;AACrF,kFAAkF;AAClF,oFAAoF;AACpF,6BAA6B;AAC7B,EAAE;AACF,uFAAuF;AACvF,sFAAsF;AACtF,oFAAoF;AACpF,sFAAsF;AACtF,mFAAmF;AACnF,kEAAkE;AAClE,EAAE;AACF,qFAAqF;AACrF,wFAAwF;AACxF,yFAAyF;AACzF,0FAA0F;AAC1F,EAAE;AACF,uFAAuF;AACvF,uFAAuF;AACvF,YAAY;AACZ,EAAE;AACF,mFAAmF;AACnF,oFAAoF;AACpF,sFAAsF;AACtF,6EAA6E;;AAoK7E,oCAIC;AAGD,gCAEC;AA3BD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,YAAY,CAAC,CAAiB,EAAE,CAAiB;IAC/D,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS;QAAE,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;IAClE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,qFAAqF;AACrF,SAAgB,UAAU,CAAC,CAAiB;IAC1C,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;AACxE,CAAC"}