@memberjunction/core-entities 6.2.0-edge.3 → 6.2.0-edge.4

package/dist/engines/conversations.js

@@ -14,7 +14,32 @@ const CONVERSATIONS_RESOURCE_TYPE_ID = '81D4BC3D-9FEB-EF11-B01A-286B35C04427';
  * {@link ConversationWindowSourceRow} — single-sourced so server callers cannot drift
  * from the assembler's requirements.
  */
-export const ConversationWindowFields = ['ID', 'Sequence', 'Role', 'Message', 'SummaryOfEarlierConversation', '__mj_CreatedAt'];
+export const ConversationWindowFields = ['ID', 'Sequence', 'Role', 'Message', 'SummaryOfEarlierConversation', '__mj_CreatedAt', 'ReplacedAt'];
+/** The fork kinds, keyed by {@link ForkKind} so a value CodeGen adds to the union fails to compile until it is listed. */
+const FORK_KIND_KEYS = { Fork: true, Edit: true, Regenerate: true };
+/** True when `value` is a key of {@link FORK_KIND_KEYS}. */
+function isForkKind(value) {
+    return Object.prototype.hasOwnProperty.call(FORK_KIND_KEYS, value);
+}
+/** Every fork kind. */
+export const FORK_KINDS = Object.keys(FORK_KIND_KEYS).filter(isForkKind);
+/** Longest branch chain the path predicate will build. */
+export const MAX_BRANCH_DEPTH = 32;
+/** The Fields a fresh load of fork rows selects. */
+export const ConversationBranchFields = ['ID', 'ConversationID', 'ParentBranchID', 'ForkFromSequence', 'Name', 'Kind', 'SourceDetailID', 'UserID', 'User', '__mj_CreatedAt'];
+/** The Fields the fork-summary reads select. */
+export const ForkSummaryRowFields = ['ID', 'BranchID', 'Sequence', 'Role', 'Message', 'UserID', 'AgentID', 'User', 'Agent', 'HiddenToUser', '__mj_CreatedAt'];
+/** Most participants a fork summary lists. */
+export const MAX_FORK_PARTICIPANTS = 3;
+const FORK_NAME_MAX_WORDS = 6;
+const FORK_NAME_MAX_CHARS = 40;
+const FORK_PREVIEW_MAX_CHARS = 120;
+function sameId(a, b) {
+    if (a == null || b == null) {
+        return a == null && b == null;
+    }
+    return NormalizeUUID(a) === NormalizeUUID(b);
+}
 /**
  * Helper: parse a raw ConversationDetailComplete row into typed arrays.
  */
@@ -592,6 +617,29 @@ export class ConversationEngine extends BaseEngine {
     async MoveConversationToProject(conversationId, projectId, contextUser) {
         return this.SaveConversation(conversationId, { ProjectID: projectId }, contextUser);
     }
+    /**
+     * Creates a fork (an `MJ: Conversation Branches` row) started by `contextUser`. A fork before the
+     * first message shares nothing, so its parent is always Main. Never reads or writes the
+     * conversation row. Write access is the branch entity's rule (owner, or an Edit/Owner share).
+     * The server refuses it unless the person holds the `Conversations: Fork` authorization.
+     * @throws when the fork cannot be saved; the message carries the save result
+     */
+    async CreateFork(input, contextUser) {
+        const branch = await this.ProviderToUse.GetEntityObject('MJ: Conversation Branches', contextUser);
+        branch.NewRecord();
+        branch.ConversationID = input.ConversationID;
+        branch.Kind = input.Kind;
+        branch.ForkFromSequence = input.ForkFromSequence;
+        branch.ParentBranchID = input.ForkFromSequence == null ? null : input.ParentBranchID;
+        branch.SourceDetailID = input.SourceDetailID ?? null;
+        branch.UserID = contextUser.ID;
+        const name = input.Name?.trim();
+        branch.Name = name ? name : null;
+        if (!(await branch.Save())) {
+            throw new Error(`Failed to create the fork: ${branch.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        return branch;
+    }
     /**
      * Reparents a folder (project) under another folder, or to the top level when
      * parentId is null. Callers are responsible for preventing cycles (don't pass a
@@ -1184,36 +1232,33 @@ export class ConversationEngine extends BaseEngine {
     // ========================================================================
     // CONVERSATION DETAILS (Messages)
     // ========================================================================
-    /**
-     * Loads conversation details (messages) for a specific conversation.
-     * Results are cached for instant retrieval on subsequent calls.
-     *
-     * @param conversationId - The conversation to load details for
-     * @param contextUser - The current user context
-     * @param forceRefresh - If true, reloads even if cached
-     * @returns Array of conversation detail entities
-     */
     /**
      * Loads conversation details using the efficient GetConversationComplete query
      * which returns messages, agent runs, artifacts, ratings, and user avatars in one round-trip.
-     * Results are cached for instant retrieval on subsequent calls.
+     * The cache holds every row of the conversation, on every branch path; a scope limits
+     * only what this call returns.
      *
      * @param conversationId - The conversation to load details for
      * @param contextUser - The current user context
      * @param forceRefresh - If true, reloads even if cached
-     * @returns The full cache entry with all peripheral data
+     * @param scope - When given, the returned entry holds only the rows in this scope
+     *   (see {@link scopedEntry}); when omitted, every row of the conversation
+     * @returns The cache entry with all peripheral data, limited to the scope when one is given
+     * @throws when the scope belongs to another conversation
      */
-    async LoadConversationDetails(conversationId, contextUser, forceRefresh = false) {
+    async LoadConversationDetails(conversationId, contextUser, forceRefresh = false, scope) {
+        ConversationEngine.assertScopeOf(conversationId, scope);
         const key = NormalizeUUID(conversationId);
         // Return cached if available and not forcing
         if (!forceRefresh) {
             const cached = this._detailCache.get(key);
             if (cached) {
-                return cached;
+                return ConversationEngine.scopedEntry(cached, scope);
             }
         }
         // Use GetConversationComplete for one-round-trip loading of all data
         const rq = new RunQuery();
+        // conversation-scope: whole-conversation cache; every consumer filters to its scope
         const result = await rq.RunQuery({
             QueryName: 'GetConversationComplete',
             CategoryPath: 'MJ/Conversations',
@@ -1232,13 +1277,41 @@ export class ConversationEngine extends BaseEngine {
                 LoadedAt: new Date(),
                 PeripheralDataStale: false
             };
-            return empty;
+            return ConversationEngine.scopedEntry(empty, scope);
         }
         const rawData = result.Results;
         // Build the cache entry from the rich query result
         const cacheEntry = await this.buildDetailCacheFromRawData(rawData, contextUser);
         this._detailCache.set(key, cacheEntry);
-        return cacheEntry;
+        return ConversationEngine.scopedEntry(cacheEntry, scope);
+    }
+    /**
+     * Throws when a scope is given and belongs to another conversation.
+     * @throws when the scope belongs to another conversation
+     */
+    static assertScopeOf(conversationId, scope) {
+        if (scope && !sameId(scope.ConversationID, conversationId)) {
+            throw new Error(`Conversation ${conversationId} is not the scope's conversation ${scope.ConversationID}`);
+        }
+    }
+    /**
+     * A cache entry limited to a scope: a copy whose `Details` hold only the rows in the scope,
+     * and whose `RawData` holds the raw rows of those details, both in their cached order. The
+     * peripheral maps are the cached ones, shared. The entry itself when no scope is given. The
+     * cached entry is never changed. Callers check the scope's conversation first
+     * ({@link assertScopeOf}).
+     */
+    static scopedEntry(entry, scope) {
+        if (!scope) {
+            return entry;
+        }
+        const details = ConversationEngine.FilterToScope(scope, entry.Details);
+        const detailIds = new Set(details.map(d => NormalizeUUID(d.ID)));
+        return {
+            ...entry,
+            Details: details,
+            RawData: entry.RawData.filter(r => !!r.ID && detailIds.has(NormalizeUUID(r.ID))),
+        };
     }
     /**
      * Loads ONE page of a conversation's transcript — the chat area's windowed history read.
@@ -1254,19 +1327,25 @@ export class ConversationEngine extends BaseEngine {
      * a partial entry there would silently starve the agent of everything before the summary
      * boundary, with no error. Use a separate partial cache if incremental caching is needed.
      *
-     * Does not throw for a read that FAILS — a failed load returns an empty window flagged
-     * {@link DetailWindowLoadResult.Failed} so the caller can leave its paging state intact
-     * rather than mistaking the failure for the start of the conversation.
+     * Every detail read is limited to the path of `BranchID` (the trunk when omitted).
+     * Replaced rows (`ReplacedAt` set) are never read.
+     *
+     * Does not throw for a read that FAILS — a failed branch-path read, like a failed page
+     * read, returns an empty window flagged {@link DetailWindowLoadResult.Failed} so the
+     * caller can leave its paging state intact rather than mistaking the failure for the
+     * start of the conversation. A failed branch-path read never falls back to the trunk.
      *
-     * It is not, however, exception-proof: there is no `try/catch` here, so a provider that
-     * REJECTS rather than returning `Success: false` propagates out to the caller. That path
-     * is left deliberately — it degrades better than the handled one, because an exception
-     * skips the cursor write entirely and the caller's paging state survives untouched.
+     * It is not, however, exception-proof: the detail reads have no `try/catch`, so a
+     * provider that REJECTS rather than returning `Success: false` propagates out to the
+     * caller. That path is left deliberately — it degrades better than the handled one,
+     * because an exception skips the cursor write entirely and the caller's paging state
+     * survives untouched.
      *
      * ### Round-trip profile — the counterweight to the payload win
      *
      * This trades ONE fat query for several thin ones. Per page:
      *
+     *   0. {@link BranchPathFilterFresh} — one branch read, only when `BranchID` is set
      *   1. {@link fetchDetailRowsBySequence} — always
      *   2. {@link expandOldestSession} — only when the oldest row is session-stamped
      *   3. {@link hasOlderDetails} — always, in parallel with (4)
@@ -1288,13 +1367,18 @@ export class ConversationEngine extends BaseEngine {
      * over more content — and unlike first paint, a reader who has scrolled up has already
      * committed to reading back. If paging up ever feels slow, that is the number to raise.
      *
-     * @param params - Conversation, optional `Sequence` bound, and page sizing
+     * @param params - Conversation, optional branch, optional `Sequence` bound, and page sizing
      * @param contextUser - The requesting user (entity RLS applies)
      */
     async LoadDetailWindow(params, contextUser) {
         const pageSize = params.PageSize ?? DEFAULT_WINDOW_PAGE_SIZE;
         const overread = params.RawOverread ?? pageSize * DETAIL_WINDOW_OVERREAD_FACTOR;
-        const page = await this.fetchDetailRowsBySequence(params.ConversationID, params.BeforeSequence, overread, contextUser);
+        const pathFilter = await this.resolveWindowPathFilter(params, contextUser);
+        if (pathFilter === null) {
+            return emptyDetailWindowResult(true);
+        }
+        const liveFilter = ConversationEngine.LiveRowsFilter(pathFilter);
+        const page = await this.fetchDetailRowsBySequence(liveFilter, params.BeforeSequence, overread, contextUser);
         // Deliberately two branches, not one. `null` is a FAILED read; an empty array is a
         // range that genuinely holds no rows. Collapsing them is what lets a transport blip
         // read downstream as "you have reached the start of the conversation".
@@ -1304,7 +1388,7 @@ export class ConversationEngine extends BaseEngine {
         if (page.length === 0) {
             return emptyDetailWindowResult(false);
         }
-        const details = await this.expandOldestSession(params.ConversationID, page, contextUser);
+        const details = await this.expandOldestSession(liveFilter, page, contextUser);
         const oldestSequence = details[0].Sequence;
         const newestSequence = details[details.length - 1].Sequence;
         // Concurrent, not sequential: the probe needs only `oldestSequence` and the peripherals
@@ -1312,7 +1396,7 @@ export class ConversationEngine extends BaseEngine {
         // to an empty/false result on a failed read — so `Promise.all` cannot introduce a
         // rejection path this method did not already have.
         const [olderProbe, peripherals] = await Promise.all([
-            this.hasOlderDetails(params.ConversationID, oldestSequence, contextUser),
+            this.hasOlderDetails(liveFilter, oldestSequence, contextUser),
             this.buildWindowPeripherals(details, contextUser)
         ]);
         return {
@@ -1327,6 +1411,22 @@ export class ConversationEngine extends BaseEngine {
             Failed: olderProbe.Failed
         };
     }
+    /**
+     * The `ExtraFilter` predicate for the window's branch path.
+     *
+     * @returns The predicate, or null when the branch rows could not be read or the branch
+     *   path could not be built.
+     */
+    async resolveWindowPathFilter(params, contextUser) {
+        try {
+            return await ConversationEngine.BranchPathFilterFresh(params.ConversationID, params.BranchID, contextUser, this.ProviderToUse);
+        }
+        catch (error) {
+            console.error(`[ConversationEngine] Failed to build the branch path for conversation ${params.ConversationID}, `
+                + `branch ${params.BranchID}:`, error);
+            return null;
+        }
+    }
     /**
      * Reads the newest `maxRows` detail rows below an optional `Sequence` bound and returns
      * them in CHRONOLOGICAL order.
@@ -1334,13 +1434,14 @@ export class ConversationEngine extends BaseEngine {
      * The query is `Sequence DESC` because the interesting end of a transcript is the tail;
      * the reversal happens here so every caller downstream sees oldest-to-newest.
      *
+     * @param pathFilter - The branch path predicate from {@link BuildBranchPathFilter}
      * @returns The page in ascending `Sequence` order, or null when the read failed.
      */
-    async fetchDetailRowsBySequence(conversationId, beforeSequence, maxRows, contextUser) {
+    async fetchDetailRowsBySequence(pathFilter, beforeSequence, maxRows, contextUser) {
         const rv = RunView.FromMetadataProvider(this.ProviderToUse);
         const filter = beforeSequence == null
-            ? `ConversationID='${conversationId}'`
-            : `ConversationID='${conversationId}' AND Sequence < ${beforeSequence}`;
+            ? pathFilter
+            : `${pathFilter} AND Sequence < ${beforeSequence}`;
         const result = await rv.RunView({
             EntityName: 'MJ: Conversation Details',
             ExtraFilter: filter,
@@ -1362,9 +1463,10 @@ export class ConversationEngine extends BaseEngine {
      * boundary — without this read the card renders from a partial row set AND the same
      * session reappears on the next older page.
      *
+     * @param pathFilter - The branch path predicate from {@link BuildBranchPathFilter}
      * @returns The page with any missing session rows prepended, still chronological.
      */
-    async expandOldestSession(conversationId, details, contextUser) {
+    async expandOldestSession(pathFilter, details, contextUser) {
         const sessionId = details[0].AgentSessionID?.trim();
         if (!sessionId) {
             return details;
@@ -1372,7 +1474,7 @@ export class ConversationEngine extends BaseEngine {
         const rv = RunView.FromMetadataProvider(this.ProviderToUse);
         const result = await rv.RunView({
             EntityName: 'MJ: Conversation Details',
-            ExtraFilter: `ConversationID='${conversationId}' AND AgentSessionID='${sessionId}' `
+            ExtraFilter: `${pathFilter} AND AgentSessionID='${sessionId}' `
                 + `AND Sequence < ${details[0].Sequence}`,
             OrderBy: 'Sequence DESC',
             MaxRows: MAX_SESSION_EXPANSION_ROWS,
@@ -1392,12 +1494,14 @@ export class ConversationEngine extends BaseEngine {
      *
      * Returns a TRI-STATE rather than a boolean. "No older rows" and "could not find out"
      * are both `HasOlder: false`, and only the second must leave the caller's cursor alone.
+     *
+     * @param pathFilter - The branch path predicate from {@link BuildBranchPathFilter}
      */
-    async hasOlderDetails(conversationId, oldestSequence, contextUser) {
+    async hasOlderDetails(pathFilter, oldestSequence, contextUser) {
         const rv = RunView.FromMetadataProvider(this.ProviderToUse);
         const probe = await rv.RunView({
             EntityName: 'MJ: Conversation Details',
-            ExtraFilter: `ConversationID='${conversationId}' AND Sequence < ${oldestSequence}`,
+            ExtraFilter: `${pathFilter} AND Sequence < ${oldestSequence}`,
             OrderBy: 'Sequence DESC',
             MaxRows: 1,
             Fields: ['ID'],
@@ -1589,21 +1693,27 @@ export class ConversationEngine extends BaseEngine {
      * - Artifacts/ratings: replaced per-detail (cheap — plain data, not entity objects)
      * - User avatars: merged (new users added)
      *
-     * If no cache exists yet, falls back to a full load.
+     * If no cache exists yet, falls back to a full load. The cache holds every row of the
+     * conversation; a scope limits only what this call returns.
      *
      * @param conversationId - The conversation to refresh
      * @param contextUser - The current user context
-     * @returns The updated cache entry
+     * @param scope - When given, the returned entry holds only the rows in this scope
+     *   (see {@link scopedEntry}); when omitted, every row of the conversation
+     * @returns The updated cache entry, limited to the scope when one is given
+     * @throws when the scope belongs to another conversation
      */
-    async RefreshConversationDetails(conversationId, contextUser) {
+    async RefreshConversationDetails(conversationId, contextUser, scope) {
+        ConversationEngine.assertScopeOf(conversationId, scope);
         const key = NormalizeUUID(conversationId);
         const existing = this._detailCache.get(key);
         // No cache yet — do a full load
         if (!existing) {
-            return this.LoadConversationDetails(conversationId, contextUser);
+            return this.LoadConversationDetails(conversationId, contextUser, false, scope);
         }
         // Run the query
         const rq = new RunQuery();
+        // conversation-scope: whole-conversation cache; every consumer filters to its scope
         const result = await rq.RunQuery({
             QueryName: 'GetConversationComplete',
             CategoryPath: 'MJ/Conversations',
@@ -1611,7 +1721,7 @@ export class ConversationEngine extends BaseEngine {
         }, contextUser);
         if (!result.Success || !result.Results) {
             console.error('[ConversationEngine] Failed to refresh conversation details:', result.ErrorMessage);
-            return existing;
+            return ConversationEngine.scopedEntry(existing, scope);
         }
         const freshRows = result.Results;
         const md = this.ProviderToUse;
@@ -1692,7 +1802,7 @@ export class ConversationEngine extends BaseEngine {
         existing.RawData = freshRows;
         existing.LoadedAt = new Date();
         existing.PeripheralDataStale = false;
-        return existing;
+        return ConversationEngine.scopedEntry(existing, scope);
     }
     /**
      * Returns cached conversation details (messages only) without hitting the database.
@@ -1752,22 +1862,55 @@ export class ConversationEngine extends BaseEngine {
      *   covers everything before it, and cutting into the post-boundary tail would create
      *   a coverage gap.
      * @param options.historyFrom - A history floor: see {@link AssembleContextWindow}.
+     * @param scope - When given, the window is built from the rows in this scope only; when
+     *   omitted, from every cached row of the conversation
      * @returns Messages in chronological order, each stamped with
      *   {@link ConversationContextMetadata}
+     * @throws when the scope belongs to another conversation
      */
-    async GetAgentContextWindow(conversationId, contextUser, options) {
+    async GetAgentContextWindow(conversationId, contextUser, options, scope) {
         await this.Config(false, contextUser);
-        const cache = await this.LoadConversationDetails(conversationId, contextUser);
+        const cache = await this.LoadConversationDetails(conversationId, contextUser, false, scope);
         return ConversationEngine.AssembleContextWindow(cache.Details, options);
     }
     /**
-     * Loads a conversation's window source rows FRESH — one RunView through the given
+     * Loads a conversation's branch rows FRESH through the given provider (entity RLS applies).
+     * Ordered by creation so alternatives at a fork point list in the order they were made.
+     * @throws when the RunView reports failure
+     */
+    static async LoadBranchesFresh(conversationId, contextUser, provider) {
+        const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
+        const rows = await rv.RunView({
+            EntityName: 'MJ: Conversation Branches',
+            ExtraFilter: `ConversationID='${EscapeSQLString(conversationId)}'`,
+            OrderBy: '__mj_CreatedAt ASC',
+            Fields: [...ConversationBranchFields],
+            ResultType: 'simple',
+        }, contextUser);
+        if (!rows.Success) {
+            throw new Error(`Failed to load branches for conversation ${conversationId}: ${rows.ErrorMessage}`);
+        }
+        return rows.Results || [];
+    }
+    /**
+     * {@link ScopeFilter} of the scope from {@link LoadScope}. The trunk (an empty, whitespace-only
+     * or missing branch id) needs no load and costs no query.
+     * @throws When the branch read fails ({@link LoadBranchesFresh}), when `branchId` is not
+     *   among the conversation's branches, or when its chain is longer than {@link MAX_BRANCH_DEPTH}
+     */
+    static async BranchPathFilterFresh(conversationId, branchId, contextUser, provider) {
+        const scope = await ConversationEngine.LoadScope(conversationId, branchId, contextUser, provider);
+        return ConversationEngine.ScopeFilter(scope);
+    }
+    /**
+     * Loads the window source rows on a conversation's branch path FRESH — through the given
      * provider with the contextUser (entity RLS applies), never touching this engine's
-     * process-global detail cache. The single source of the fresh-load query shape
-     * (entity name, filter, order, fields) for every server-side caller: the agent
-     * resolver's history loader and the cross-turn compaction pass both consume this,
+     * process-global detail cache. The trunk costs one RunView; a branch costs two (its branch
+     * rows via {@link BranchPathFilterFresh}, then the path's rows). The single source of the
+     * fresh-load query shape (entity name, filter, order, fields) for every server-side
+     * caller: the agent resolver's history loader and the cross-turn compaction pass both consume this,
      * so the two can never drift apart. THROWS on load failure — servers must fail
-     * loudly rather than proceed against an empty history.
+     * loudly rather than proceed against an empty history. Replaced rows never leave the database.
      *
      * @param conversationId - The conversation whose detail rows to load
      * @param contextUser - The requesting user (entity RLS is applied under this user)
@@ -1775,18 +1918,21 @@ export class ConversationEngine extends BaseEngine {
      * @param historyFrom - Optional history floor: only rows written at or after it are loaded,
      *   so nothing before it leaves the database. Pair it with the same `historyFrom` on
      *   {@link AssembleContextWindow}, which also drops the summary of earlier messages.
-     * @returns The conversation's rows in Sequence order, shaped for {@link AssembleContextWindow}
-     * @throws When the underlying RunView reports failure (never returns a silent empty set),
-     *   or when `historyFrom` is an invalid date
-     */
-    static async LoadWindowRowsFresh(conversationId, contextUser, provider, historyFrom) {
+     * @param branchId - The branch whose path to load; null or omitted reads the trunk.
+     * @returns The rows on the branch's path (the trunk when no branch) in Sequence order,
+     *   shaped for {@link AssembleContextWindow}
+     * @throws When a RunView reports failure (never returns a silent empty set), when
+     *   `historyFrom` is an invalid date, when `branchId` is not among the conversation's
+     *   branches, or when its chain is longer than {@link MAX_BRANCH_DEPTH}
+     */
+    static async LoadWindowRowsFresh(conversationId, contextUser, provider, historyFrom, branchId) {
         const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
-        const conversationFilter = `ConversationID='${conversationId}'`;
+        const pathFilter = await ConversationEngine.BranchPathFilterFresh(conversationId, branchId, contextUser, provider);
         const rows = await rv.RunView({
             EntityName: 'MJ: Conversation Details',
-            ExtraFilter: historyFrom
-                ? `${conversationFilter} AND ${ConversationEngine.HistoryFromFilter(historyFrom)}`
-                : conversationFilter,
+            ExtraFilter: ConversationEngine.LiveRowsFilter(historyFrom
+                ? `${pathFilter} AND ${ConversationEngine.HistoryFromFilter(historyFrom)}`
+                : pathFilter),
             OrderBy: 'Sequence ASC',
             Fields: [...ConversationWindowFields],
             ResultType: 'simple',
@@ -1814,12 +1960,14 @@ export class ConversationEngine extends BaseEngine {
      * floor none is used, and the window is the most recent `maxTailMessages` rows at or
      * after the floor. A row whose `__mj_CreatedAt` is missing or unreadable can't be shown
      * to be after the floor, so it is dropped too.
+     *
+     * Replaced rows (`ReplacedAt` set) are always left out.
      */
     static AssembleContextWindow(details, options) {
         const excluded = new Set((options?.excludeDetailIds || []).map(id => NormalizeUUID(id)));
         const floor = options?.historyFrom ?? null;
         const ordered = details
-            .filter(d => !excluded.has(NormalizeUUID(d.ID)))
+            .filter(d => !excluded.has(NormalizeUUID(d.ID)) && !ConversationEngine.IsReplacedRow(d))
             .filter(d => !floor || ConversationEngine.isAtOrAfter(d.__mj_CreatedAt, floor))
             .sort((a, b) => a.Sequence - b.Sequence);
         const boundary = floor ? undefined : ConversationEngine.findSummaryBoundary(ordered);
@@ -1844,6 +1992,412 @@ export class ConversationEngine extends BaseEngine {
     static HistoryFromFilter(historyFrom, column = '__mj_CreatedAt') {
         return `${column} >= '${historyFrom.toISOString()}'`;
     }
+    /**
+     * `filter` limited to rows no rerun replaced (`ReplacedAt` is NULL). A replaced row is an answer a
+     * rerun of its turn superseded: it is kept, but never shown and never sent to an agent. Every reader
+     * of conversation rows for display or for agent context applies this.
+     */
+    static LiveRowsFilter(filter) {
+        return `${filter} AND [ReplacedAt] IS NULL`;
+    }
+    /** True when a rerun of its turn replaced the row (`ReplacedAt` is set). */
+    static IsReplacedRow(row) {
+        return row.ReplacedAt != null;
+    }
+    /**
+     * The branch and its ancestors, current branch first. Empty for the trunk.
+     * @throws when the branch is not in `branches`, or the chain is longer than
+     *   {@link MAX_BRANCH_DEPTH} (which also catches a cycle).
+     */
+    static BuildBranchChain(branches, branchId) {
+        const chain = [];
+        let current = branchId ?? null;
+        while (current != null) {
+            if (chain.length >= MAX_BRANCH_DEPTH) {
+                throw new Error(`Branch chain for ${branchId} exceeds ${MAX_BRANCH_DEPTH} levels`);
+            }
+            const id = current;
+            const branch = branches.find(b => sameId(b.ID, id));
+            if (!branch) {
+                throw new Error(`Branch ${id} not found`);
+            }
+            chain.push(branch);
+            current = branch.ParentBranchID ?? null;
+        }
+        return chain;
+    }
+    /**
+     * The `ExtraFilter` predicate for a branch path: the branch's own rows, plus each
+     * ancestor's rows up to that ancestor's fork sequence, plus the trunk up to the last
+     * fork sequence. A null branch is the trunk alone.
+     *
+     * Column names are bracketed, so the predicate also works inside a subquery on
+     * `vwConversationDetails` from another entity's filter: the PostgreSQL provider converts
+     * bracketed names itself but quotes bare names only when they are fields of the outer entity.
+     */
+    static BuildBranchPathFilter(conversationId, branchId, branches) {
+        const conversationFilter = `[ConversationID]='${EscapeSQLString(conversationId)}'`;
+        const chain = ConversationEngine.BuildBranchChain(branches, branchId);
+        if (chain.length === 0) {
+            return `${conversationFilter} AND [BranchID] IS NULL`;
+        }
+        const clauses = [];
+        let cap = null;
+        for (const branch of chain) {
+            const id = EscapeSQLString(branch.ID);
+            clauses.push(cap == null ? `[BranchID]='${id}'` : `([BranchID]='${id}' AND [Sequence] <= ${cap})`);
+            cap = branch.ForkFromSequence;
+            if (cap == null) {
+                return `${conversationFilter} AND (${clauses.join(' OR ')})`;
+            }
+        }
+        clauses.push(`([BranchID] IS NULL AND [Sequence] <= ${cap})`);
+        return `${conversationFilter} AND (${clauses.join(' OR ')})`;
+    }
+    /** True when a row is on the path described by a chain from {@link BuildBranchChain}. */
+    static IsRowOnBranchPath(row, chain) {
+        let cap = null;
+        for (const branch of chain) {
+            if (sameId(row.BranchID, branch.ID)) {
+                return cap == null || row.Sequence <= cap;
+            }
+            cap = branch.ForkFromSequence;
+            if (cap == null) {
+                return false;
+            }
+        }
+        return row.BranchID == null && (cap == null || row.Sequence <= cap);
+    }
+    /** In-memory counterpart of {@link BuildBranchPathFilter} for rows already loaded. */
+    static FilterRowsToBranchPath(rows, branchId, branches) {
+        const chain = ConversationEngine.BuildBranchChain(branches, branchId);
+        return rows.filter(r => ConversationEngine.IsRowOnBranchPath(r, chain));
+    }
+    /** A scope for the trunk: no branch rows are needed. */
+    static TrunkScope(conversationId) {
+        return { ConversationID: conversationId, BranchID: null, Branches: [] };
+    }
+    /**
+     * Builds a scope for an explicit branch. An empty, whitespace-only or missing branch id is the
+     * trunk. A branch id loads the conversation's branch rows once and must name one of them
+     * (compared without regard to case); the scope's `BranchID` is that row's `ID`.
+     * @throws when the branch rows cannot be read or the branch is not one of them.
+     */
+    static async LoadScope(conversationId, branchId, contextUser, provider) {
+        const normalized = branchId && branchId.trim().length > 0 ? branchId : null;
+        if (normalized === null) {
+            return ConversationEngine.TrunkScope(conversationId);
+        }
+        const branches = await ConversationEngine.LoadBranchesFresh(conversationId, contextUser, provider);
+        const branch = branches.find(b => sameId(b.ID, normalized));
+        if (!branch) {
+            throw new Error(`Branch ${normalized} is not a branch of conversation ${conversationId}`);
+        }
+        return { ConversationID: conversationId, BranchID: branch.ID, Branches: branches };
+    }
+    /**
+     * Predicate over MJ: Conversation Details for the rows in scope. Same text as
+     * {@link BuildBranchPathFilter}.
+     * @throws when the scope's `BranchID`, or the parent of a branch on its chain, is not in the
+     *   scope's `Branches`, or when the chain is longer than {@link MAX_BRANCH_DEPTH}.
+     */
+    static ScopeFilter(scope) {
+        return ConversationEngine.BuildBranchPathFilter(scope.ConversationID, scope.BranchID, scope.Branches);
+    }
+    /**
+     * `[column] IN (SELECT ID FROM [__mj].[vwConversationDetails] WHERE <ScopeFilter>)` for entities
+     * anchored by a conversation detail id column.
+     */
+    static ScopeSubquery(scope, column = 'ConversationDetailID') {
+        return `[${column}] IN (SELECT ID FROM [__mj].[vwConversationDetails] WHERE ${ConversationEngine.ScopeFilter(scope)})`;
+    }
+    /** In-memory form of {@link ScopeFilter} for one row already loaded. */
+    static IsInScope(scope, row) {
+        const chain = ConversationEngine.BuildBranchChain(scope.Branches, scope.BranchID);
+        return ConversationEngine.IsRowOnBranchPath(row, chain);
+    }
+    /** In-memory form of {@link ScopeFilter} for rows already loaded. Keeps their order. */
+    static FilterToScope(scope, rows) {
+        return ConversationEngine.FilterRowsToBranchPath(rows, scope.BranchID, scope.Branches);
+    }
+    /**
+     * Filter over MJ: Artifact Versions for the versions of one artifact visible in scope: versions
+     * linked (in any direction) from a message on the path, and versions with no conversation link
+     * at all.
+     */
+    static ArtifactVersionScopeFilter(scope, artifactId) {
+        const path = ConversationEngine.ScopeFilter(scope);
+        const id = EscapeSQLString(artifactId);
+        return `[ArtifactID]='${id}' AND (` +
+            `[ID] IN (SELECT ArtifactVersionID FROM [__mj].[vwConversationDetailArtifacts] WHERE ConversationDetailID IN (SELECT ID FROM [__mj].[vwConversationDetails] WHERE ${path}))` +
+            ` OR [ID] NOT IN (SELECT ArtifactVersionID FROM [__mj].[vwConversationDetailArtifacts] WHERE ArtifactVersionID IS NOT NULL)` +
+            `)`;
+    }
+    /** The kind of a fork row; a missing or unknown value is 'Fork'. */
+    static NormalizeForkKind(kind) {
+        return FORK_KINDS.find(k => k === kind) ?? 'Fork';
+    }
+    /**
+     * Plain text of a stored message: each `@{...}` mention becomes `@<name>`, or is dropped when it
+     * has no name, and runs of whitespace become one space. Null when nothing is left.
+     */
+    static ForkPlainText(message) {
+        if (!message) {
+            return null;
+        }
+        const plain = message
+            .replace(/@\{[^{}]*\}/g, token => {
+            try {
+                const parsed = JSON.parse(token.slice(1));
+                return typeof parsed.name === 'string' && parsed.name.trim().length > 0 ? `@${parsed.name.trim()}` : ' ';
+            }
+            catch {
+                return ' ';
+            }
+        })
+            .replace(/\s+/g, ' ')
+            .trim();
+        return plain.length > 0 ? plain : null;
+    }
+    /** The first words of a message, for a fork with no name: at most 6 words and 40 characters, '…' when cut. */
+    static ForkFirstWords(message) {
+        const plain = ConversationEngine.ForkPlainText(message);
+        if (!plain) {
+            return null;
+        }
+        const words = plain.split(' ');
+        let text = words.slice(0, FORK_NAME_MAX_WORDS).join(' ');
+        let cut = words.length > FORK_NAME_MAX_WORDS;
+        if (text.length > FORK_NAME_MAX_CHARS) {
+            text = text.slice(0, FORK_NAME_MAX_CHARS).trimEnd();
+            cut = true;
+        }
+        return cut ? `${text}…` : text;
+    }
+    /** A one-line preview of a message: at most 120 characters, '…' when cut. */
+    static ForkPreviewText(message) {
+        const plain = ConversationEngine.ForkPlainText(message);
+        if (!plain) {
+            return null;
+        }
+        return plain.length > FORK_PREVIEW_MAX_CHARS ? `${plain.slice(0, FORK_PREVIEW_MAX_CHARS).trimEnd()}…` : plain;
+    }
+    /**
+     * The label of a fork: its name, else a default from its kind — Fork: the first words of its first
+     * message, else "Fork"; Edit: "Edited version"; Regenerate: "Other answer".
+     */
+    static ForkDisplayName(branch, firstOwnMessage) {
+        const name = branch.Name?.trim();
+        if (name) {
+            return name;
+        }
+        switch (ConversationEngine.NormalizeForkKind(branch.Kind)) {
+            case 'Edit':
+                return 'Edited version';
+            case 'Regenerate':
+                return 'Other answer';
+            default:
+                return ConversationEngine.ForkFirstWords(firstOwnMessage) ?? 'Fork';
+        }
+    }
+    /** The fork point at a message: the new fork starts after the message itself, on its branch. */
+    static ForkPointFrom(message) {
+        return { ParentBranchID: message.BranchID ?? null, ForkFromSequence: message.Sequence };
+    }
+    /**
+     * Edit of a message, or Fork from here on it (the fork replaces it): the new fork starts at the row
+     * before it on its path (both null when it is the first message). Undefined when that row is not
+     * known: the message is not in `pathRows`, or it is the first loaded row while older rows exist
+     * (`hasMoreAbove`).
+     */
+    static EditForkPoint(message, pathRows, hasMoreAbove = false) {
+        const sorted = [...pathRows].sort((a, b) => a.Sequence - b.Sequence);
+        const index = sorted.findIndex(r => sameId(r.ID, message.ID));
+        if (index < 0) {
+            return undefined;
+        }
+        if (index === 0) {
+            return hasMoreAbove ? undefined : { ParentBranchID: null, ForkFromSequence: null };
+        }
+        return ConversationEngine.ForkPointFrom(sorted[index - 1]);
+    }
+    /** Regenerate of an answer: the new fork starts at the user message the answer replied to. */
+    static RegenerateForkPoint(userMessage) {
+        return ConversationEngine.ForkPointFrom(userMessage);
+    }
+    /**
+     * Predicate over MJ: Conversation Details for the anchor rows of the given forks (one clause per
+     * distinct fork point); null when no fork has a fork point.
+     */
+    static AnchorRowsFilter(conversationId, branches) {
+        const clauses = [];
+        for (const branch of branches) {
+            if (branch.ForkFromSequence == null) {
+                continue;
+            }
+            const onParent = branch.ParentBranchID == null
+                ? '[BranchID] IS NULL'
+                : `[BranchID]='${EscapeSQLString(branch.ParentBranchID)}'`;
+            const clause = `(${onParent} AND [Sequence]=${Math.trunc(branch.ForkFromSequence)})`;
+            if (!clauses.includes(clause)) {
+                clauses.push(clause);
+            }
+        }
+        if (clauses.length === 0) {
+            return null;
+        }
+        return `[ConversationID]='${EscapeSQLString(conversationId)}' AND (${clauses.join(' OR ')})`;
+    }
+    /**
+     * Predicate over MJ: Conversation Details for the source rows of the given forks (each distinct
+     * SourceDetailID once); null when no fork has a source.
+     */
+    static SourceRowsFilter(conversationId, branches) {
+        const ids = [];
+        for (const branch of branches) {
+            const id = branch.SourceDetailID;
+            if (id && !ids.some(known => sameId(known, id))) {
+                ids.push(id);
+            }
+        }
+        if (ids.length === 0) {
+            return null;
+        }
+        const list = ids.map(id => `'${EscapeSQLString(id)}'`).join(', ');
+        return `[ConversationID]='${EscapeSQLString(conversationId)}' AND [ID] IN (${list})`;
+    }
+    /**
+     * One summary per fork, in the order of `branches`. Pure: `ownRows` are the conversation's rows
+     * with a BranchID, `anchorRows` the rows {@link AnchorRowsFilter} selects, `sourceRows` the rows
+     * {@link SourceRowsFilter} selects.
+     */
+    static BuildForkSummaries(branches, ownRows, anchorRows, sourceRows = []) {
+        const ownByFork = new Map();
+        for (const row of ownRows) {
+            if (row.BranchID == null || row.HiddenToUser === true) {
+                continue;
+            }
+            const key = NormalizeUUID(row.BranchID);
+            const list = ownByFork.get(key);
+            if (list) {
+                list.push(row);
+            }
+            else {
+                ownByFork.set(key, [row]);
+            }
+        }
+        return branches.map(branch => {
+            const own = [...(ownByFork.get(NormalizeUUID(branch.ID)) ?? [])].sort((a, b) => a.Sequence - b.Sequence);
+            const anchor = branch.ForkFromSequence == null
+                ? undefined
+                : anchorRows.find(r => r.Sequence === branch.ForkFromSequence && sameId(r.BranchID, branch.ParentBranchID ?? null));
+            const sourceId = branch.SourceDetailID;
+            const source = sourceId ? sourceRows.find(r => sameId(r.ID, sourceId)) : undefined;
+            const placement = sourceId ? source : anchor;
+            const first = own.find(r => ConversationEngine.ForkPlainText(r.Message) != null);
+            const last = own.length > 0 ? own[own.length - 1] : undefined;
+            const authors = [];
+            for (const r of own) {
+                if (r.Role === 'User' && r.UserID && !authors.some(a => sameId(a, r.UserID))) {
+                    authors.push(r.UserID);
+                }
+            }
+            return {
+                Branch: branch,
+                Kind: ConversationEngine.NormalizeForkKind(branch.Kind),
+                DisplayName: ConversationEngine.ForkDisplayName(branch, first?.Message ?? null),
+                MessageCount: own.length,
+                Participants: ConversationEngine.forkParticipants(own),
+                AuthorUserIDs: authors,
+                LastActivityAt: (last ? ConversationEngine.toForkDate(last.__mj_CreatedAt) : null)
+                    ?? ConversationEngine.toForkDate(branch.__mj_CreatedAt)
+                    ?? new Date(0),
+                LastMessagePreview: last ? ConversationEngine.ForkPreviewText(last.Message) : null,
+                LastMessageAuthorName: last ? ConversationEngine.rowAuthorName(last) : null,
+                PlacementDetailID: branch.SourceDetailID ?? anchor?.ID ?? null,
+                PlacementPosition: placement ? { BranchID: placement.BranchID ?? null, Sequence: placement.Sequence } : null,
+                AnchorDetailID: anchor?.ID ?? null,
+                AnchorAuthorName: anchor ? ConversationEngine.rowAuthorName(anchor) : null,
+                AnchorAt: anchor ? ConversationEngine.toForkDate(anchor.__mj_CreatedAt) : null,
+                SourceAuthorName: source ? ConversationEngine.rowAuthorName(source) : null,
+                StartedByUserID: branch.UserID ?? null,
+                StartedByName: branch.User ?? null,
+                ParentBranchID: branch.ParentBranchID ?? null,
+            };
+        });
+    }
+    /**
+     * Loads the fork summaries of a conversation FRESH (entity RLS applies): the fork rows (unless
+     * given), then the forks' own rows, their anchor rows and their source rows in one RunViews batch.
+     * @throws when a read fails
+     */
+    static async LoadForkSummaries(conversationId, contextUser, provider, branches) {
+        const forks = branches ?? await ConversationEngine.LoadBranchesFresh(conversationId, contextUser, provider);
+        if (forks.length === 0) {
+            return [];
+        }
+        const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
+        const params = [{
+                EntityName: 'MJ: Conversation Details',
+                ExtraFilter: `[ConversationID]='${EscapeSQLString(conversationId)}' AND [BranchID] IS NOT NULL`,
+                OrderBy: 'Sequence ASC',
+                Fields: [...ForkSummaryRowFields],
+                ResultType: 'simple',
+            }];
+        const rowsParams = (filter) => ({
+            EntityName: 'MJ: Conversation Details',
+            ExtraFilter: filter,
+            Fields: [...ForkSummaryRowFields],
+            ResultType: 'simple',
+        });
+        const anchorFilter = ConversationEngine.AnchorRowsFilter(conversationId, forks);
+        const anchorIndex = anchorFilter ? params.push(rowsParams(anchorFilter)) - 1 : -1;
+        const sourceFilter = ConversationEngine.SourceRowsFilter(conversationId, forks);
+        const sourceIndex = sourceFilter ? params.push(rowsParams(sourceFilter)) - 1 : -1;
+        const results = await rv.RunViews(params, contextUser);
+        const own = results[0];
+        const anchors = anchorIndex >= 0 ? results[anchorIndex] : undefined;
+        const sources = sourceIndex >= 0 ? results[sourceIndex] : undefined;
+        if (!own?.Success) {
+            throw new Error(`Failed to load the forks of conversation ${conversationId}: ${own?.ErrorMessage}`);
+        }
+        if (anchors && !anchors.Success) {
+            throw new Error(`Failed to load the fork anchors of conversation ${conversationId}: ${anchors.ErrorMessage}`);
+        }
+        if (sources && !sources.Success) {
+            throw new Error(`Failed to load the fork source messages of conversation ${conversationId}: ${sources.ErrorMessage}`);
+        }
+        return ConversationEngine.BuildForkSummaries(forks, own.Results ?? [], anchors?.Results ?? [], sources?.Results ?? []);
+    }
+    /** Distinct agents and people of rows in order, at most {@link MAX_FORK_PARTICIPANTS}. */
+    static forkParticipants(rows) {
+        const out = [];
+        for (const r of rows) {
+            const participant = r.AgentID
+                ? { Kind: 'Agent', ID: r.AgentID, Name: r.Agent ?? null }
+                : r.UserID ? { Kind: 'User', ID: r.UserID, Name: r.User ?? null } : null;
+            if (!participant || out.some(p => p.Kind === participant.Kind && sameId(p.ID, participant.ID))) {
+                continue;
+            }
+            out.push(participant);
+            if (out.length === MAX_FORK_PARTICIPANTS) {
+                break;
+            }
+        }
+        return out;
+    }
+    /** The agent's name for an agent row, else the person's name; null when the row names neither. */
+    static rowAuthorName(row) {
+        return row.AgentID ? (row.Agent ?? null) : (row.User ?? null);
+    }
+    /** A Date from a stored timestamp; null when missing or unreadable. */
+    static toForkDate(value) {
+        if (value == null) {
+            return null;
+        }
+        const date = value instanceof Date ? value : new Date(value);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
     /** True when a row's timestamp is at or after the floor; false when it is missing or unreadable. */
     static isAtOrAfter(createdAt, floor) {
         if (createdAt == null) {