@memberjunction/core-entities 6.2.0-edge.0 → 6.2.0-edge.2

package/dist/engines/conversations.js

@@ -1,5 +1,5 @@
-import { BaseEngine, RunQuery, RunView, TransformSimpleObjectToEntityObject } from "@memberjunction/core";
-import { NormalizeUUID, ToEpochMs, UUIDsEqual } from "@memberjunction/global";
+import { BaseEngine, EntityEventRowIsFree, ResolveEntityEventKey, ResolveEntityEventRow, RunQuery, RunView, TransformSimpleObjectToEntityObject } from "@memberjunction/core";
+import { EscapeSQLString, NormalizeUUID, ToEpochMs, UUIDsEqual } from "@memberjunction/global";
 import { BehaviorSubject } from "rxjs";
 import { ArtifactMetadataEngine } from "./artifacts.js";
 import { ResourcePermissionEngine } from "../custom/ResourcePermissions/ResourcePermissionEngine.js";
@@ -14,11 +14,11 @@ 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'];
+export const ConversationWindowFields = ['ID', 'Sequence', 'Role', 'Message', 'SummaryOfEarlierConversation', '__mj_CreatedAt'];
 /**
  * Helper: parse a raw ConversationDetailComplete row into typed arrays.
  */
-export function parseConversationDetailComplete(queryResult) {
+export function ParseConversationDetailComplete(queryResult) {
     return {
         ...queryResult,
         agentRuns: queryResult.AgentRunsJSON
@@ -32,6 +32,10 @@ export function parseConversationDetailComplete(queryResult) {
             : []
     };
 }
+/** @deprecated Use {@link ParseConversationDetailComplete}. */
+export function parseConversationDetailComplete(queryResult) {
+    return ParseConversationDetailComplete(queryResult);
+}
 /**
  * Timeline items the UI asks for per page. Mirrors `DEFAULT_TRANSCRIPT_PAGE_SIZE` in
  * `@memberjunction/ng-conversations` — duplicated rather than imported because the
@@ -160,6 +164,61 @@ function mergeArtifactJSON(junction, version, artifact) {
         Visibility: artifact.Visibility
     };
 }
+/**
+ * The row filter that decides which folders a user may see: SHARED ones (no owner)
+ * plus their OWN.
+ *
+ * Exported and used by every list read of 'MJ: Projects', because the rule being in
+ * one place is the point. It first shipped inline in LoadProjects, and review caught
+ * ProjectSelectorComponent running its own RunView with no ownership clause at all —
+ * so personal folder names were still listed in the chat area's Assign Project modal,
+ * which is precisely the exposure OwnerUserID exists to close. Gating one reader never
+ * gates the others; a second copy of a predicate is a second place to forget it.
+ *
+ * NOT for the Explorer entity-admin surfaces (the Projects record view and its
+ * hierarchy panel). Those are the raw entity browser, where an admin sees every row of
+ * every entity, and narrowing them here would be inconsistent with how MJ treats
+ * entity administration generally.
+ *
+ * A missing user gets SHARED ONLY, never every personal folder in the environment:
+ * without an identity there is nobody to be the owner of, and widening on absent input
+ * is how a personal folder reaches a stranger's list.
+ */
+export function BuildProjectVisibilityFilter(userId) {
+    const id = String(userId ?? '').trim();
+    return id.length > 0
+        ? `(OwnerUserID IS NULL OR OwnerUserID='${EscapeSQLString(id)}')`
+        : `OwnerUserID IS NULL`;
+}
+/**
+ * Turns a failed folder delete into something the person reading it can act on.
+ *
+ * `Project.ParentID` and `Conversation.ProjectID` are RESTRICT foreign keys, so the delete
+ * fails while anything still points at the row. `DeleteProject` clears everything it can
+ * reach first, which leaves exactly one interesting residue: a referencing row the caller
+ * is not permitted to read, and therefore could not reparent. The raw message for that is a
+ * constraint name, about a record whose existence is deliberately hidden from them.
+ *
+ * The constraint name is the signal, and it is kept in the text — a support engineer needs
+ * it — but it is no longer the whole message.
+ */
+export function ExplainProjectDeleteFailure(dbMessage) {
+    const raw = (dbMessage ?? '').trim();
+    if (!raw) {
+        return 'Failed to delete folder.';
+    }
+    const blockedByTree = /FK_Project_Parent/i.test(raw);
+    // Constraint names only. A bare /ProjectID/ also matched things like "Invalid column
+    // name 'ProjectID'", and answering an unrelated error with "conversations you do not
+    // have access to" is worse than passing the raw message through.
+    const blockedByConversation = /FK_Conversation_Project/i.test(raw);
+    if (blockedByTree || blockedByConversation) {
+        const what = blockedByTree ? 'subfolders' : 'conversations';
+        return `This folder still contains ${what} that you do not have access to, so it cannot be deleted. `
+            + `Ask someone who can see them to move or remove them first. (${raw})`;
+    }
+    return raw;
+}
 /**
  * ConversationEngine provides centralized, reactive caching for conversations,
  * conversation details (messages), and peripheral data (agent runs, artifacts).
@@ -206,6 +265,14 @@ export class ConversationEngine extends BaseEngine {
         this._lastEnvironmentId = null;
         /** Track the environment ID used for the last projects (folders) load */
         this._lastProjectsEnvironmentId = null;
+        /**
+         * The user the cached projects were loaded FOR. Part of the cache key because
+         * the project read is now user-dependent (personal folders): keyed on the
+         * environment alone, a second user in the same process — a server-side caller,
+         * an impersonated context — would be served the first user's personal folders
+         * from cache and never issue a read of their own.
+         */
+        this._lastProjectsUserId = null;
         /**
          * Monotonic ticket for conversation loads, to keep the newest ANSWER rather than the
          * newest REQUEST.
@@ -274,6 +341,29 @@ export class ConversationEngine extends BaseEngine {
     GetSharedByInfo(conversationId) {
         return this._sharedByByConversationId.get(NormalizeUUID(conversationId)) ?? null;
     }
+    /**
+     * True when the user may grant others access to the conversation: they own it,
+     * or hold an Owner-level grant on it. Mirrors the server's share gate in
+     * `MJResourcePermissionEntityExtended`, so the UI never offers a share the save
+     * would refuse.
+     */
+    CanShareConversation(conversation, userId) {
+        if (conversation.UserID && UUIDsEqual(conversation.UserID, userId)) {
+            return true;
+        }
+        return this.GetSharedByInfo(conversation.ID)?.Level === 'Owner';
+    }
+    /**
+     * True when the user may change the conversation's folder and pin: they own
+     * it, or hold an Edit or Owner grant on it. A View grant is read-only.
+     */
+    CanEditConversation(conversation, userId) {
+        if (conversation.UserID && UUIDsEqual(conversation.UserID, userId)) {
+            return true;
+        }
+        const level = this.GetSharedByInfo(conversation.ID)?.Level;
+        return level === 'Edit' || level === 'Owner';
+    }
     // ========================================================================
     // ENGINE CONFIG (BaseEngine pattern)
     // ========================================================================
@@ -317,28 +407,9 @@ export class ConversationEngine extends BaseEngine {
         // Claim a ticket for this load. Anything published below is gated on still holding
         // the newest one — see _conversationsLoadGeneration.
         const generation = ++this._conversationsLoadGeneration;
-        // Include conversations the user has been granted access to via
-        // `MJ: Resource Permissions`. ResourcePermissionEngine caches the full
-        // permission table; GetUserAvailableResources filters it to approved
-        // grants (direct + role-inherited) for this user + resource type.
-        await ResourcePermissionEngine.Instance.Config(false, contextUser);
-        const sharedPermissions = ResourcePermissionEngine.Instance
-            .GetUserAvailableResources(contextUser, CONVERSATIONS_RESOURCE_TYPE_ID);
-        const sharedConversationIds = sharedPermissions.map((p) => p.ResourceRecordID);
+        const sharedPermissions = await this.getSharedConversationPermissions(contextUser);
+        const filter = this.buildVisibleConversationsFilter(environmentId, contextUser.ID, sharedPermissions.map((p) => p.ResourceRecordID), options);
         const rv = new RunView();
-        const ownershipClause = `UserID='${contextUser.ID}'`;
-        const sharedClause = sharedConversationIds.length > 0
-            ? ` OR ID IN (${sharedConversationIds.map((id) => `'${id}'`).join(',')})`
-            : '';
-        // Default main-chat view shows Global + Both. App-scoped
-        // conversations live inside their owning Application's embedded
-        // surface and are filtered out here. Callers that want to surface
-        // them (e.g. an "Include app conversations" toggle) pass
-        // includeApplicationScoped=true to drop the scope predicate.
-        const scopeClause = options?.includeApplicationScoped
-            ? ''
-            : ` AND ApplicationScope IN ('Global', 'Both')`;
-        const filter = `EnvironmentID='${environmentId}' AND (${ownershipClause}${sharedClause}) AND (IsArchived IS NULL OR IsArchived=0)${scopeClause}`;
         const result = await rv.RunView({
             EntityName: 'MJ: Conversations',
             ExtraFilter: filter,
@@ -384,6 +455,42 @@ export class ConversationEngine extends BaseEngine {
         // own per-environment guard to avoid redundant reloads.
         await this.LoadProjects(environmentId, contextUser, forceRefresh);
     }
+    /**
+     * Returns an `ExtraFilter` for `MJ: Conversations` that matches exactly the conversations
+     * {@link LoadConversations} shows the user: owned by the user or shared with them, not
+     * archived, and (unless `includeApplicationScoped`) Global or Both scope.
+     *
+     * Use it anywhere that reads conversations for display (search, pickers) so those reads
+     * cannot show more than the conversation list does. It is not capped, unlike the list load.
+     *
+     * @param environmentId - The environment to filter conversations by
+     * @param contextUser - The user whose conversations to match
+     * @param options - `includeApplicationScoped` also matches app-scoped conversations
+     */
+    async GetVisibleConversationsFilter(environmentId, contextUser, options) {
+        const sharedPermissions = await this.getSharedConversationPermissions(contextUser);
+        return this.buildVisibleConversationsFilter(environmentId, contextUser.ID, sharedPermissions.map((p) => p.ResourceRecordID), options);
+    }
+    /**
+     * Approved conversation grants (direct and role-inherited) for the user, from
+     * `MJ: Resource Permissions`. ResourcePermissionEngine caches the full permission table.
+     */
+    async getSharedConversationPermissions(contextUser) {
+        await ResourcePermissionEngine.Instance.Config(false, contextUser);
+        return ResourcePermissionEngine.Instance.GetUserAvailableResources(contextUser, CONVERSATIONS_RESOURCE_TYPE_ID);
+    }
+    buildVisibleConversationsFilter(environmentId, userId, sharedConversationIds, options) {
+        const ownershipClause = `UserID='${userId}'`;
+        const sharedClause = sharedConversationIds.length > 0
+            ? ` OR ID IN (${sharedConversationIds.map((id) => `'${id}'`).join(',')})`
+            : '';
+        // The main chat view shows Global and Both. App-scoped conversations live inside
+        // their owning Application's embedded surface.
+        const scopeClause = options?.includeApplicationScoped
+            ? ''
+            : ` AND ApplicationScope IN ('Global', 'Both')`;
+        return `EnvironmentID='${environmentId}' AND (${ownershipClause}${sharedClause}) AND (IsArchived IS NULL OR IsArchived=0)${scopeClause}`;
+    }
     /**
      * Populates {@link _sharedByByConversationId}. Resolves grantor emails via
      * one `MJ: Users` query keyed on the unique set of `SharedByUserID`s.
@@ -424,22 +531,34 @@ export class ConversationEngine extends BaseEngine {
         }
     }
     /**
-     * Loads the projects (conversation folders) for an environment and emits via Projects$.
-     * Projects are environment-scoped (not user-scoped) and small, so the full active set
-     * is cached. Skips reloading when already loaded for the same environment unless forced.
+     * Loads the projects (conversation folders) visible to a user in an environment and
+     * emits via Projects$.
+     *
+     * Visible means SHARED (OwnerUserID IS NULL — every folder that existed before
+     * ownership was expressible) plus the user's OWN personal folders. A personal folder
+     * never reaches anyone else's sidebar. The set is small, so it is cached whole;
+     * reloading is skipped only when both the environment AND the user match, because the
+     * read now depends on both.
      *
      * @param environmentId - The environment to filter projects by
-     * @param contextUser - The current user context
-     * @param forceRefresh - If true, reloads even if already cached for this environment
+     * @param contextUser - The current user context; also decides which personal folders load
+     * @param forceRefresh - If true, reloads even if already cached for this environment/user
      */
     async LoadProjects(environmentId, contextUser, forceRefresh = false) {
-        if (!forceRefresh && this._lastProjectsEnvironmentId === environmentId) {
+        const userId = contextUser?.ID ?? null;
+        if (!forceRefresh
+            && this._lastProjectsEnvironmentId === environmentId
+            && this._lastProjectsUserId === userId) {
             return;
         }
+        // Shared folders, plus this user's own. One definition, shared with every other
+        // list read of this entity — see BuildProjectVisibilityFilter.
+        const ownership = BuildProjectVisibilityFilter(userId);
         const rv = new RunView();
         const result = await rv.RunView({
             EntityName: 'MJ: Projects',
-            ExtraFilter: `EnvironmentID='${environmentId}' AND (IsArchived IS NULL OR IsArchived=0)`,
+            ExtraFilter: `EnvironmentID='${environmentId}' AND (IsArchived IS NULL OR IsArchived=0)`
+                + ` AND ${ownership}`,
             OrderBy: 'Name ASC',
             MaxRows: 1000,
             ResultType: 'entity_object',
@@ -452,6 +571,7 @@ export class ConversationEngine extends BaseEngine {
         }, contextUser);
         if (result.Success) {
             this._lastProjectsEnvironmentId = environmentId;
+            this._lastProjectsUserId = userId;
             this._projects$.next(result.Results || []);
         }
         else {
@@ -525,15 +645,41 @@ export class ConversationEngine extends BaseEngine {
      */
     async DeleteProject(id, contextUser) {
         const md = this.ProviderToUse;
+        // 0. Resolve the folder itself FIRST. Its ParentID is where the children go, and the
+        // cached copy may not be there at all — the cache is narrowed by ownership, and a
+        // principal allowed to delete a folder is not necessarily one whose sidebar lists it.
+        let project = this._projects$.value.find(p => UUIDsEqual(p.ID, id));
+        if (!project) {
+            project = await md.GetEntityObject('MJ: Projects', contextUser);
+            const loaded = await project.Load(id);
+            if (!loaded) {
+                throw new Error('Folder not found');
+            }
+        }
+        const newParentId = project.ParentID ?? null;
         // 1. Unassign conversations directly in this folder
         const directConversations = this._conversations$.value.filter(c => c.ProjectID && UUIDsEqual(c.ProjectID, id));
         for (const conv of directConversations) {
             await this.SaveConversation(conv.ID, { ProjectID: null }, contextUser);
         }
-        // 2. Reparent direct child folders to this folder's parent
-        const target = this._projects$.value.find(p => UUIDsEqual(p.ID, id));
-        const newParentId = target?.ParentID ?? null;
-        const childFolders = this._projects$.value.filter(p => p.ParentID && UUIDsEqual(p.ParentID, id));
+        // 2. Reparent direct child folders one level up.
+        //
+        // The child set comes from a READ keyed on ParentID, never from `_projects$`. That
+        // cache is narrowed to shared-plus-mine by BuildProjectVisibilityFilter, and a
+        // structural operation on the tree cannot be driven by a view of the tree that is
+        // missing rows. Someone else's personal folder under a shared parent does not appear
+        // in the cache, so it would never be reparented — and `Project.ParentID` is a
+        // RESTRICT foreign key with no ON DELETE clause, so the delete below would then fail
+        // with a raw constraint message, about a row the user is not allowed to know exists.
+        //
+        // The read carries NO ownership clause, deliberately. Deleting a folder needs
+        // CanDelete on the entity, which the UI role does not hold; the roles that do also
+        // hold unfiltered read, which makes them exempt from the row-level filter — so this
+        // read returns the complete child set for every principal that can actually reach
+        // here. Should a deployment grant delete to a filtered role anyway, the server still
+        // narrows the read, and step 3's guard turns the resulting FK failure into something
+        // legible rather than "Failed to save project".
+        const childFolders = await this.readChildFolders(id, contextUser);
         if (childFolders.length > 0) {
             this._selfMutating = true;
             try {
@@ -548,18 +694,13 @@ export class ConversationEngine extends BaseEngine {
             finally {
                 this._selfMutating = false;
             }
-            // Children were mutated in place — re-emit so subscribers re-read the tree
+            // Children were mutated in place — re-emit so subscribers re-read the tree.
+            // Reparented children the caller cannot see are not in `_projects$` and stay out
+            // of it; the emit is for the ones that are.
             this._projects$.next([...this._projects$.value]);
         }
-        // 3. Delete the now-unreferenced folder
-        let project = target;
-        if (!project) {
-            project = await md.GetEntityObject('MJ: Projects', contextUser);
-            const loaded = await project.Load(id);
-            if (!loaded) {
-                throw new Error('Folder not found');
-            }
-        }
+        // 3. Delete the now-unreferenced folder.
+        //
         // Remove from the cached list BEFORE calling Delete(). BaseEntity.Delete() calls
         // NewRecord() which wipes the entity's fields — including ID — so filtering the list
         // by ID *after* the delete wouldn't match the (now-blank) cached entity and the folder
@@ -578,10 +719,43 @@ export class ConversationEngine extends BaseEngine {
         if (!deleted) {
             // Restore the list on failure (the entity wasn't deleted, so its fields are intact)
             this._projects$.next(projectsBeforeDelete);
-            throw new Error(project.LatestResult?.CompleteMessage || 'Failed to delete folder');
+            throw new Error(ExplainProjectDeleteFailure(project.LatestResult?.CompleteMessage));
         }
         return true;
     }
+    /**
+     * Every direct child of a folder, read by ParentID with no ownership clause.
+     *
+     * Separate from `LoadProjects` on purpose: that one answers "what may this user SEE",
+     * and this one answers "what actually REFERENCES this row". Only the second is a safe
+     * basis for a delete, because an unseen child still holds the foreign key.
+     */
+    async readChildFolders(parentId, contextUser) {
+        // Validated rather than escaped-and-hoped: EscapeSQLString turns an empty value into
+        // `ParentID = ''`, which matches nothing — and "no children" is precisely the wrong
+        // answer here, because it reads as permission to delete.
+        const id = (parentId ?? '').trim();
+        if (!id) {
+            throw new Error('Cannot read subfolders without a folder id.');
+        }
+        // The engine's own provider, as DeleteProject uses for the folder itself. `new RunView()`
+        // would be the process-global default, which in a multi-provider client can be a
+        // different server from the one this delete runs against.
+        const rv = RunView.FromMetadataProvider(this.ProviderToUse);
+        const result = await rv.RunView({
+            EntityName: 'MJ: Projects',
+            ExtraFilter: `ParentID='${EscapeSQLString(id)}'`,
+            // This read has to be COMPLETE, not merely representative: one child left out
+            // is one FK left pointing at the row. Omitting MaxRows is not enough — the
+            // entity's own UserViewMaxRows would then apply and truncate silently.
+            IgnoreMaxRows: true,
+            ResultType: 'entity_object'
+        }, contextUser);
+        if (!result.Success) {
+            throw new Error(`Could not read the folder's subfolders, so it cannot be safely deleted: ${result.ErrorMessage}`);
+        }
+        return result.Results || [];
+    }
     /**
      * Creates a new conversation, saves it to the database, and adds it to the cached list.
      *
@@ -907,6 +1081,106 @@ export class ConversationEngine extends BaseEngine {
         this.removeMultipleFromList(successful);
         return { Successful: successful, Failed: failed };
     }
+    /**
+     * Moves multiple conversations into a folder (project), or out of every folder
+     * when projectId is null. Emits the updated list once for the whole batch.
+     *
+     * @param ids - Conversation IDs to move
+     * @param projectId - Target folder ID, or null for no folder
+     * @param contextUser - The current user context
+     * @returns Per-item successful and failed outcomes
+     */
+    async MoveMultipleConversationsToProject(ids, projectId, contextUser) {
+        return this.saveMultipleConversations(ids, { ProjectID: projectId }, contextUser);
+    }
+    /**
+     * Pins or unpins multiple conversations. Emits the re-sorted list once for the
+     * whole batch, so pinned conversations move to the top in a single UI update.
+     *
+     * @param ids - Conversation IDs to pin or unpin
+     * @param isPinned - True to pin, false to unpin
+     * @param contextUser - The current user context
+     * @returns Per-item successful and failed outcomes
+     */
+    async PinMultipleConversations(ids, isPinned, contextUser) {
+        return this.saveMultipleConversations(ids, { IsPinned: isPinned }, contextUser);
+    }
+    /**
+     * Applies the same field updates to several conversations, one save at a time so
+     * a single rejection cannot fail the batch, then re-emits the list once.
+     * A conversation whose save fails keeps its previous field values in memory.
+     * Conversations the user holds only View access to are refused without a save.
+     */
+    async saveMultipleConversations(ids, updates, contextUser) {
+        const successful = [];
+        const failed = [];
+        if (ids.length === 0) {
+            return { Successful: successful, Failed: failed };
+        }
+        const md = this.ProviderToUse;
+        this._selfMutating = true;
+        try {
+            for (const id of ids) {
+                let conversation = this.GetConversation(id);
+                try {
+                    if (!conversation) {
+                        const entity = await md.GetEntityObject('MJ: Conversations', contextUser);
+                        const loaded = await entity.Load(id);
+                        if (!loaded) {
+                            failed.push({ ID: id, Name: 'Unknown', Error: 'Conversation not found' });
+                            continue;
+                        }
+                        conversation = entity;
+                    }
+                    if (!this.CanEditConversation(conversation, contextUser.ID)) {
+                        failed.push({
+                            ID: id,
+                            Name: conversation.Name || 'Unknown',
+                            Error: 'You have View access only'
+                        });
+                        continue;
+                    }
+                    const previous = {
+                        ProjectID: conversation.ProjectID,
+                        IsPinned: conversation.IsPinned
+                    };
+                    this.applyBulkUpdate(conversation, updates);
+                    const saved = await conversation.Save();
+                    if (saved) {
+                        successful.push(conversation.ID);
+                    }
+                    else {
+                        this.applyBulkUpdate(conversation, previous);
+                        failed.push({
+                            ID: id,
+                            Name: conversation.Name || 'Unknown',
+                            Error: conversation.LatestResult?.Message || 'Failed to update conversation'
+                        });
+                    }
+                }
+                catch (error) {
+                    failed.push({
+                        ID: id,
+                        Name: conversation?.Name || 'Unknown',
+                        Error: error instanceof Error ? error.message : 'Unknown error'
+                    });
+                }
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        if (successful.length > 0) {
+            this._conversations$.next(this.sortConversations(this._conversations$.value));
+        }
+        return { Successful: successful, Failed: failed };
+    }
+    applyBulkUpdate(conversation, updates) {
+        if (updates.ProjectID !== undefined)
+            conversation.ProjectID = updates.ProjectID;
+        if (updates.IsPinned !== undefined)
+            conversation.IsPinned = updates.IsPinned;
+    }
     // ========================================================================
     // CONVERSATION DETAILS (Messages)
     // ========================================================================
@@ -1152,7 +1426,7 @@ export class ConversationEngine extends BaseEngine {
         for (const row of rawData) {
             if (!row.ID)
                 continue;
-            const parsed = parseConversationDetailComplete(row);
+            const parsed = ParseConversationDetailComplete(row);
             // Agent runs
             if (parsed.agentRuns.length > 0) {
                 const agentRunData = parsed.agentRuns[0];
@@ -1363,7 +1637,7 @@ export class ConversationEngine extends BaseEngine {
                 newDetail.LoadFromData(row);
                 existing.Details.push(newDetail);
             }
-            const parsed = parseConversationDetailComplete(row);
+            const parsed = ParseConversationDetailComplete(row);
             // Merge agent runs: update in-place or add.
             //
             // Important: `existingRun` may be a plain JSON object rather than a BaseEntity.
@@ -1477,6 +1751,7 @@ export class ConversationEngine extends BaseEngine {
      *   the most recent N messages. Ignored when a boundary exists — the summary already
      *   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}.
      * @returns Messages in chronological order, each stamped with
      *   {@link ConversationContextMetadata}
      */
@@ -1497,14 +1772,21 @@ export class ConversationEngine extends BaseEngine {
      * @param conversationId - The conversation whose detail rows to load
      * @param contextUser - The requesting user (entity RLS is applied under this user)
      * @param provider - Optional per-request metadata provider; falls back to the global default
+     * @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)
+     * @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) {
+    static async LoadWindowRowsFresh(conversationId, contextUser, provider, historyFrom) {
         const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
+        const conversationFilter = `ConversationID='${conversationId}'`;
         const rows = await rv.RunView({
             EntityName: 'MJ: Conversation Details',
-            ExtraFilter: `ConversationID='${conversationId}'`,
+            ExtraFilter: historyFrom
+                ? `${conversationFilter} AND ${ConversationEngine.HistoryFromFilter(historyFrom)}`
+                : conversationFilter,
             OrderBy: 'Sequence ASC',
             Fields: [...ConversationWindowFields],
             ResultType: 'simple',
@@ -1525,13 +1807,22 @@ export class ConversationEngine extends BaseEngine {
      *
      * Accepts the minimal {@link ConversationWindowSourceRow} shape, satisfied by full
      * entities AND `ResultType: 'simple'` rows selecting {@link ConversationWindowFields}.
+     *
+     * **History floor.** With `options.historyFrom` set, the window starts there: rows written
+     * before it are dropped, and so is any persisted summary. A summary folds in the
+     * conversation from its first message — exactly what the floor excludes — so under a
+     * 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.
      */
     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 => !floor || ConversationEngine.isAtOrAfter(d.__mj_CreatedAt, floor))
             .sort((a, b) => a.Sequence - b.Sequence);
-        const boundary = ConversationEngine.findSummaryBoundary(ordered);
+        const boundary = floor ? undefined : ConversationEngine.findSummaryBoundary(ordered);
         if (boundary) {
             const tail = ordered.filter(d => d.Sequence >= boundary.Sequence);
             return [ConversationEngine.buildSummaryMessage(boundary), ...tail.map(d => ConversationEngine.detailToContextMessage(d))];
@@ -1540,6 +1831,27 @@ export class ConversationEngine extends BaseEngine {
         const cap = options?.maxTailMessages;
         return cap && all.length > cap ? all.slice(-cap) : all;
     }
+    /**
+     * The `ExtraFilter` predicate for a history floor: rows written at or after `historyFrom`.
+     * Shared by every reader that honours a floor, so they agree on what it means.
+     *
+     * @param historyFrom The first moment that may be read.
+     * @param column The timestamp column to compare, when the predicate runs against a view
+     *   or subquery that names it differently.
+     * @throws RangeError when `historyFrom` is an invalid date — a floor that can't be written
+     *   down must fail rather than silently read everything.
+     */
+    static HistoryFromFilter(historyFrom, column = '__mj_CreatedAt') {
+        return `${column} >= '${historyFrom.toISOString()}'`;
+    }
+    /** 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) {
+            return false;
+        }
+        const time = createdAt instanceof Date ? createdAt.getTime() : Date.parse(createdAt);
+        return !Number.isNaN(time) && time >= floor.getTime();
+    }
     /**
      * Finds the summary boundary: the detail with the HIGHEST `Sequence` whose
      * `SummaryOfEarlierConversation` is non-blank. Older summaries below it simply stop
@@ -1692,6 +2004,7 @@ export class ConversationEngine extends BaseEngine {
         this._detailCache.clear();
         this._lastEnvironmentId = null;
         this._lastProjectsEnvironmentId = null;
+        this._lastProjectsUserId = null;
     }
     // ========================================================================
     // CONVERSATION DETAIL CRUD
@@ -1815,46 +2128,130 @@ export class ConversationEngine extends BaseEngine {
         const effectiveType = event.type === 'remote-invalidate'
             ? event.payload?.action || 'save'
             : event.type;
-        if (normalizedName === 'mj: conversations') {
-            return this.handleConversationEntityEvent(event, effectiveType);
-        }
-        if (normalizedName === 'mj: conversation details') {
-            return this.handleConversationDetailEntityEvent(event, effectiveType);
-        }
-        if (normalizedName === 'mj: projects') {
-            return this.handleProjectEntityEvent(event, effectiveType);
-        }
-        if (normalizedName === 'mj: ai agent runs') {
-            return this.handleAgentRunEntityEvent(event, effectiveType);
-        }
-        if (normalizedName === 'mj: conversation detail artifacts' || normalizedName === 'mj: conversation detail ratings') {
-            return this.handlePeripheralJunctionEntityEvent(event);
+        const handled = normalizedName === 'mj: conversations' ||
+            normalizedName === 'mj: conversation details' ||
+            normalizedName === 'mj: projects' ||
+            normalizedName === 'mj: ai agent runs' ||
+            normalizedName === 'mj: conversation detail artifacts' ||
+            normalizedName === 'mj: conversation detail ratings';
+        if (handled) {
+            // Hydrate ONCE, here, because this is the only async frame on the path. A remote event
+            // carries the row only for entities on the server's broadcast allowlist (see
+            // `cacheSettings.recordDataBroadcastEntities`); otherwise this re-reads the single
+            // record through the provider, as this user, so access control decides what comes
+            // back. Handlers below stay synchronous and simply receive the row — passing it down
+            // rather than letting each fetch its own keeps this to one read per event and avoids
+            // turning five handlers async for a value the dispatcher can obtain once.
+            // ...and only when something below will actually use it — see eventNeedsRow. On a
+            // remote event without `recordData`, hydrating means a read through the provider, and
+            // this dispatcher runs in EVERY connected browser for every save of these entities
+            // anywhere in the system, whether or not this session has any claim to the record.
+            const row = this.eventNeedsRow(event, normalizedName, effectiveType)
+                ? await ResolveEntityEventRow(event, this.ProviderToUse, this.ContextUser)
+                : null;
+            if (normalizedName === 'mj: conversations') {
+                return this.handleConversationEntityEvent(event, effectiveType, row);
+            }
+            if (normalizedName === 'mj: conversation details') {
+                return this.handleConversationDetailEntityEvent(event, effectiveType, row);
+            }
+            if (normalizedName === 'mj: projects') {
+                return this.handleProjectEntityEvent(event, effectiveType, row);
+            }
+            if (normalizedName === 'mj: ai agent runs') {
+                return this.handleAgentRunEntityEvent(event, effectiveType, row);
+            }
+            return this.handlePeripheralJunctionEntityEvent(event, row);
         }
         // Not a conversation entity — let BaseEngine handle it
         return await super.HandleIndividualBaseEntityEvent(event);
     }
     /**
-     * Extracts record data from a BaseEntityEvent.
-     * For local events: uses baseEntity directly.
-     * For remote-invalidate events: parses recordData JSON from the payload.
-     * Returns null if no data is available.
+     * Will anything below actually use the row, or does the primary key suffice?
+     *
+     * Asked BEFORE hydrating, because for a remote event whose entity is not on the server's
+     * broadcast allowlist, hydrating costs a read through the provider. This dispatcher runs in
+     * every connected browser, for every save of these entities anywhere in the system — and
+     * conversation details are the hottest write path in the product, so an unconditional read
+     * here is one round trip per connected client per message, nearly all of them refused for a
+     * session with no claim to the record.
+     *
+     * Every `false` below is a case where the handler already returns early without touching the
+     * row, so skipping the read changes nothing a caller can observe.
      */
-    extractRecordData(event) {
-        // Local event — entity is available directly
-        if (event.baseEntity) {
-            return event.baseEntity.GetAll();
+    eventNeedsRow(event, normalizedName, effectiveType) {
+        // A row that costs nothing is never worth skipping. Free for a local event (the row IS the
+        // live entity) and for a remote event whose payload already carries `recordData`, because
+        // the entity is on the server's broadcast allowlist.
+        //
+        // This has to come first, and the per-entity reasoning below has to be read as being about
+        // THE READ. Applying it to a free row is what dropped a remote project save: the save
+        // branch uses EnvironmentID and IsArchived off the row, and with the row nulled it read
+        // them as undefined/false, concluded the project was outside the loaded environment, and
+        // filtered it out of the list — for exactly the sessions displaying it.
+        if (EntityEventRowIsFree(event)) {
+            return true;
         }
-        // Remote event — parse from payload
-        const payload = event.payload;
-        if (payload?.recordData) {
-            try {
-                return JSON.parse(payload.recordData);
+        // Projects: a DELETE needs only the id. A SAVE genuinely uses the row — `EnvironmentID` and
+        // `IsArchived` are what decide whether the project stays in the list — so it has to be
+        // hydrated whenever we hold the project.
+        //
+        // The earlier reasoning here ("a save that got this far has nothing to merge regardless")
+        // was true of the MERGE and false of the branch beside it: without the row, `EnvironmentID`
+        // reads as absent, `inLoadedEnvironment` comes out false for any session that has loaded an
+        // environment, and the save REMOVES the project instead. That is precisely the cross-client
+        // case this change exists to serve, so it is gated like conversations are: when we do not
+        // hold the project the remote path does nothing anyway (the append branch below requires
+        // `event.baseEntity`), and the row would be fetched only to be discarded.
+        if (normalizedName === 'mj: projects') {
+            if (effectiveType !== 'save') {
+                return false;
             }
-            catch {
-                return null;
+            const id = this.eventRecordID(event, null);
+            return !!id && this._projects$.value.some(p => UUIDsEqual(p.ID, id));
+        }
+        if (normalizedName === 'mj: conversations') {
+            // A delete needs only the id. A save merges fields onto a conversation we already
+            // hold — and when we do not hold it, the remote branch of the handler does nothing,
+            // so the row would be fetched only to be discarded.
+            if (effectiveType !== 'save') {
+                return false;
             }
+            const id = this.eventRecordID(event, null);
+            return !!id && !!this.GetConversation(id);
+        }
+        // Details, agent runs and the junction entities all resolve through the detail cache and
+        // return early when the conversation they name is not in it.
+        //
+        // A remote DELETE can never be served: the record is gone, so the re-read comes back null
+        // and every one of those handlers early-returns on the missing foreign key. The round trip
+        // could not change an outcome, so it is not made. (That these handlers cannot act on a
+        // remote delete at all is a pre-existing gap — deletes never carried `recordData` at either
+        // publish site — and is not what this method is for.) Local deletes are unaffected: the
+        // free-row check above already returned true for them.
+        if (effectiveType === 'delete') {
+            return false;
+        }
+        // With the cache empty — any session that has not opened a conversation — none of them can
+        // do anything, whatever the row says. (A non-empty cache still needs the read:
+        // ConversationID is a foreign key, so the primary key cannot tell us whether this detail
+        // belongs to a conversation we hold.)
+        return this._detailCache.size > 0;
+    }
+    /**
+     * This record's id, from the primary key the event always carries.
+     *
+     * Prefers the key over the row: the key is broadcast unconditionally, whereas the row is only
+     * present for allowlisted entities or after a re-read. Falls back to the row's `ID` so a
+     * single-column entity still resolves if the key is ever absent.
+     */
+    eventRecordID(event, data) {
+        const key = ResolveEntityEventKey(event);
+        const fromKey = key?.KeyValuePairs?.find(kv => kv.FieldName?.toLowerCase() === 'id')?.Value;
+        if (fromKey != null && String(fromKey).length > 0) {
+            return String(fromKey);
         }
-        return null;
+        return data?.['ID'];
     }
     /**
      * Safely merges data onto a target object that may or may not be a BaseEntity.
@@ -1873,12 +2270,21 @@ export class ConversationEngine extends BaseEngine {
     /**
      * Handles save/delete events on Conversation entities from local or remote code.
      */
-    handleConversationEntityEvent(event, action) {
-        const data = this.extractRecordData(event);
-        const id = data?.['ID'];
+    handleConversationEntityEvent(event, action, data) {
+        // Identity comes from the primary key, which is broadcast unconditionally — a delete needs
+        // nothing else, so it no longer depends on the row being available.
+        const id = this.eventRecordID(event, data);
         if (!id)
             return true;
         if (action === 'save') {
+            // Same reasoning as handleProjectEntityEvent: the row can be null even when
+            // `eventNeedsRow` said yes, because the re-read can be refused, find the record gone,
+            // or simply fail — all of which `ResolveEntityEventRow` reports as null rather than
+            // throwing. `mergeDataOntoRecord` would hand that null to `BaseEntity.SetMany`, which
+            // throws, and nothing above this frame catches it. A conversation we cannot re-read
+            // stays as it was; the next `LoadConversations` corrects it.
+            if (!data)
+                return true;
             const existing = this.GetConversation(id);
             if (existing) {
                 this.mergeDataOntoRecord(existing, data);
@@ -1912,10 +2318,11 @@ export class ConversationEngine extends BaseEngine {
     /**
      * Handles save/delete events on ConversationDetail entities from local or remote code.
      */
-    handleConversationDetailEntityEvent(event, action) {
+    handleConversationDetailEntityEvent(event, action, data) {
         const entity = event.baseEntity;
-        const data = this.extractRecordData(event);
-        const id = data?.['ID'];
+        const id = this.eventRecordID(event, data);
+        // ConversationID is a foreign key, so the primary key cannot supply it — this is the field
+        // the dispatcher's re-read exists to obtain.
         const conversationId = data?.['ConversationID'];
         if (!id || !conversationId)
             return true;
@@ -1957,9 +2364,8 @@ export class ConversationEngine extends BaseEngine {
      * deleted via the project form modal. Only tracks projects in the currently-loaded
      * environment; archived projects are dropped from the active list.
      */
-    handleProjectEntityEvent(event, action) {
-        const data = this.extractRecordData(event);
-        const id = data?.['ID'];
+    handleProjectEntityEvent(event, action, data) {
+        const id = this.eventRecordID(event, data);
         if (!id)
             return true;
         const current = this._projects$.value;
@@ -1970,13 +2376,51 @@ export class ConversationEngine extends BaseEngine {
             }
             return true;
         }
-        // save — only track projects in the loaded environment; drop archived ones
-        const environmentId = data?.['EnvironmentID'];
-        const isArchived = data?.['IsArchived'] === true;
+        // WITHOUT THE ROW WE KNOW NOTHING, and must not guess. Every field below would read as
+        // absent: `IsArchived` becomes false, which is harmless, but `EnvironmentID` becomes
+        // undefined — and "no environment" is indistinguishable from "moved to another one", so the
+        // branch that DROPS the project is the one that runs. Leaving it untouched is the only
+        // honest response to a row we do not have.
+        //
+        // `eventNeedsRow` is supposed to guarantee this never happens for a project we hold, but
+        // that contract is enforced by a comment and `strictNullChecks` is off in this package, so
+        // the guarantee is restated here where the damage would be done. Hydration can also simply
+        // fail: `ResolveEntityEventRow` returns null rather than throwing.
+        //
+        // KEEPING IT IS DELIBERATE EVEN WHEN THE ROW WAS WITHHELD ON PURPOSE. A null can mean the
+        // re-read was refused — the viewer may no longer read this project — or that it failed.
+        // The two are indistinguishable here, and they want opposite responses, so this takes the
+        // one whose wrong case is recoverable: a stale row in a sidebar is corrected by the next
+        // `LoadProjects`, whereas a project deleted from the UI on a transient read failure is
+        // gone until the user reloads and cannot be told why.
+        if (!data) {
+            return true;
+        }
+        // save — the cached list holds folders that are in the loaded environment, not
+        // archived, AND visible to this user. All three are conditions the save can change,
+        // so all three are re-evaluated here rather than only the first two.
+        // No `?.` past the guard above: `data` is non-null here, and optional chaining would say
+        // otherwise. It is also what let `mergeDataOntoRecord(…, data)` accept a nullable argument
+        // without complaint, since `strictNullChecks` is off in this package.
+        const environmentId = data['EnvironmentID'];
+        const isArchived = data['IsArchived'] === true;
         const inLoadedEnvironment = !this._lastProjectsEnvironmentId ||
             (environmentId != null && UUIDsEqual(environmentId, this._lastProjectsEnvironmentId));
+        // Ownership, the third condition, and the one the folder dialog's confirm promises.
+        // When someone makes a shared folder personal, every OTHER session holding it must
+        // drop it — merging and keeping would leave the folder in their sidebar until reload,
+        // which is the opposite of what that confirm just told the user would happen.
+        // Mirrors BuildProjectVisibilityFilter: no owner is shared, my id is mine, anything
+        // else is someone else's. An unknown viewer sees shared only, never every personal
+        // folder in the environment — widening on absent input is the failure mode worth
+        // avoiding, and it is the same rule the read path applies.
+        const ownerUserId = data['OwnerUserID'];
+        const isVisibleToViewer = ownerUserId == null || ownerUserId === ''
+            ? true
+            : !!this._lastProjectsUserId && UUIDsEqual(ownerUserId, this._lastProjectsUserId);
+        const belongsInList = !isArchived && inLoadedEnvironment && isVisibleToViewer;
         if (existingIdx >= 0) {
-            if (isArchived || !inLoadedEnvironment) {
+            if (!belongsInList) {
                 this._projects$.next(current.filter(p => !UUIDsEqual(p.ID, id)));
             }
             else {
@@ -1984,7 +2428,7 @@ export class ConversationEngine extends BaseEngine {
                 this._projects$.next([...current]);
             }
         }
-        else if (event.baseEntity && !isArchived && inLoadedEnvironment) {
+        else if (event.baseEntity && belongsInList) {
             // New folder from a local event — append the entity object
             this._projects$.next([...current, event.baseEntity]);
         }
@@ -1994,9 +2438,9 @@ export class ConversationEngine extends BaseEngine {
      * Handles save/delete events on AI Agent Run entities from local or remote code.
      * Updates the AgentRunsByDetailId map so timers and status reflect reality.
      */
-    handleAgentRunEntityEvent(event, action) {
-        const data = this.extractRecordData(event);
-        const id = data?.['ID'];
+    handleAgentRunEntityEvent(event, action, data) {
+        const id = this.eventRecordID(event, data);
+        // Foreign key, not part of this row's primary key — supplied by the dispatcher's re-read.
         const detailId = data?.['ConversationDetailID'];
         if (!id || !detailId)
             return true;
@@ -2033,8 +2477,9 @@ export class ConversationEngine extends BaseEngine {
      * reconstructed from the entity event alone, so we flag the cache as stale.
      * The UI component checks PeripheralDataStale and force-refreshes when needed.
      */
-    handlePeripheralJunctionEntityEvent(event) {
-        const data = this.extractRecordData(event);
+    handlePeripheralJunctionEntityEvent(event, data) {
+        // The junction's own primary key is not useful here; what matters is which detail it hangs
+        // off, which is a foreign key and therefore only available from the row.
         const detailId = data?.['ConversationDetailID'];
         if (!detailId)
             return true;