@ai-matrx/messaging 0.10.5 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 0.11.0 — 2026-09-10
+
+### THE ARCHIVED-ITEMS LAW reaches conversations
+
+> "everything should have an archive filter, and the default should always hide archived, but
+> seeing archived items should be one or two clicks away … this is a system wide decision for
+> every single item everywhere in our system, for every single table and every single page."
+> — Arman, 2026-09-09 (`common-docs/policies/archived-items.md`)
+
+This package could ARCHIVE a conversation — `setConversationFlags({ isArchived: true })` — and
+had no read side for one. No filter, no parameter, no affordance anywhere could show it again,
+and `get_dm_conversations_with_details` hardcoded the exclusion with no parameter of its own.
+An archived conversation was not hidden. It was unreachable.
+
+- **`MessagingArchiveFilter`** — the platform tri-state (`active` | `archived` | `all`), the
+  same three words as matrx-frontend's `lib/entity-list`, the `agx_`/`wfx_` list RPCs and
+  `@ai-matrx/design-system`'s `ArchiveFilter`. Shipped with
+  `DEFAULT_MESSAGING_ARCHIVE_FILTER` (`active`) and `toMessagingArchiveFilter()`, which
+  narrows an untrusted value and falls back to the default rather than silently widening a
+  list to archived rows. Three states, never a boolean: a boolean cannot say "archived only".
+- **`repository.listConversations({ archived })`** passes `p_archived` to the RPC, which
+  gained that parameter on 2026-09-09 (register row R1). The axis is a REQUEST to the reader,
+  never a client-side sieve — so `hasMore`, the cursor and any count describe the rows the
+  caller actually asked for.
+- **`repository.countArchivedConversations()`** answers the reveal's label. It is CAPPED and
+  says so: `{ count, exact }`, and `exact: false` must render "12+", never a confident "12".
+- **The engine** carries the axis on every read — first page, "load more", and the reconnect
+  backfill — with `setArchiveFilter()` re-reading page one and refreshing the count. Flipping
+  the filter returns the store to NOT-LOADED, not to "loaded and empty": leaving the old rows
+  up renders active conversations under an "Archived" heading, and an empty "loaded" list
+  tells someone with forty archived chats she has none.
+- **`ConversationList`** renders the reveal — **"Archived (N)"** → the archive → "← Back to
+  active conversations". One click, and it appears only when it would do something: while
+  hiding, when something is there to reveal; while showing, always, so the way back is never
+  missing. A button that changes nothing is a dead end, not an affordance.
+- **`useConversations()`** returns `archiveFilter`, `setArchiveFilter` and `archivedCount`.
+
+### Consumer action
+
+- **Nothing breaks.** Every existing signature is unchanged and every default is the old
+  behaviour: a host that passes nothing still hides archived conversations.
+- **Delete your local archive split.** A host that worked around this gap by fetching
+  everything and partitioning `ConversationSummary.isArchived` in its own component is now
+  reading rows the server would not have sent, and its counts and pagination describe a
+  different set from the one on screen. Drop the local split and the `include_archived`-style
+  boolean beside it; `ConversationList` carries the control, and a host list built on
+  `useConversations()` reads `archiveFilter` / `setArchiveFilter` / `archivedCount`.
+- **`<MessagingProvider archiveFilter={…}>` is the knob** (root law 6, and clause 6 of the
+  law itself): the initial state is an org/user setting, not this package's taste. Wire it to
+  whatever your setting resolves to; omit it and you get the platform default, `active`.
+
 ## 0.10.5 — 2026-09-09
 
 ### Fixed

package/README.md

@@ -333,6 +333,39 @@ import { createMessagingEngine, createMessagingRepository } from "@ai-matrx/mess
 
 ---
 
+## Archived conversations
+
+THE ARCHIVED-ITEMS LAW (Arman, 2026-09-09 — `common-docs/policies/archived-items.md`): every
+list over an entity that can be archived carries an archive filter, the default hides archived
+rows, and revealing them is one or two clicks. Three states, and no more:
+
+| value | what the list shows |
+|---|---|
+| `active` | only un-archived conversations (the default) |
+| `archived` | only archived conversations |
+| `all` | every conversation |
+
+**The filter is a REQUEST to the reader, never a client-side sieve.** It travels as
+`p_archived` on `get_dm_conversations_with_details`, so `hasMore`, the pagination cursor and
+every count describe the rows the caller actually asked for. A host that fetches everything and
+partitions `ConversationSummary.isArchived` in its own component is reading rows the server
+would not have sent, and its counts describe a different set from the one on screen.
+
+`ConversationList` already carries the control — **"Archived (N)"**, one click, and a way back.
+The count comes from `countArchivedConversations()` and is CAPPED: `exact: false` renders "N+",
+never a confident total. A host building its own list reads `archiveFilter`, `setArchiveFilter`
+and `archivedCount` from `useConversations()`.
+
+The initial state is a KNOB, not this package's taste (root law 6, and clause 6 of the law):
+
+```tsx
+<MessagingProvider archiveFilter={settings.lists.archivedDefault} … >
+```
+
+Omit it and you get the platform default, `active`.
+
+---
+
 ## The database contract
 
 One canonical schema, in Matrx Main, under the platform's DB conventions:

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  DEFAULT_MESSAGING_ARCHIVE_FILTER: () => DEFAULT_MESSAGING_ARCHIVE_FILTER,
   MESSAGING_EVENTS: () => MESSAGING_EVENTS,
   MESSAGING_RPC_SCHEMA: () => MESSAGING_RPC_SCHEMA,
   MESSAGING_SCHEMA: () => MESSAGING_SCHEMA,
@@ -65,6 +66,7 @@ __export(src_exports, {
   resolveActor: () => resolveActor,
   splitText: () => splitText,
   summarizeText: () => summarizeText,
+  toMessagingArchiveFilter: () => toMessagingArchiveFilter,
   unreadCutoff: () => unreadCutoff
 });
 module.exports = __toCommonJS(src_exports);
@@ -986,6 +988,17 @@ function projectConversationSummary(row, viewerId, fallbackOrganizationId) {
   };
 }
 
+// src/core/types.ts
+var asConversationId = (value) => value;
+var asMessageId = (value) => value;
+var asUserId = (value) => value;
+var asOrganizationId = (value) => value;
+var asClientMessageId = (value) => value;
+var DEFAULT_MESSAGING_ARCHIVE_FILTER = "active";
+function toMessagingArchiveFilter(value, fallback = DEFAULT_MESSAGING_ARCHIVE_FILTER) {
+  return value === "active" || value === "archived" || value === "all" ? value : fallback;
+}
+
 // src/core/store.ts
 function timeOf(message) {
   const stamp = message.editedAt ?? message.createdAt;
@@ -1016,6 +1029,8 @@ function createMessagingStore() {
   let conversations = [];
   let hasMoreConversations = false;
   let hasLoadedConversations = false;
+  let archiveFilter = DEFAULT_MESSAGING_ARCHIVE_FILTER;
+  let archivedCount = null;
   let threads = /* @__PURE__ */ new Map();
   let activeConversationId = null;
   const listeners = /* @__PURE__ */ new Set();
@@ -1028,7 +1043,9 @@ function createMessagingStore() {
       hasLoadedConversations,
       threads,
       activeConversationId,
-      totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length
+      totalUnreadConversations: conversations.filter((item) => item.unreadCount > 0).length,
+      archiveFilter,
+      archivedCount
     };
     return cached;
   }
@@ -1075,6 +1092,18 @@ function createMessagingStore() {
       hasLoadedConversations = true;
       emit();
     },
+    setArchiveFilter(next) {
+      if (next === archiveFilter) return;
+      archiveFilter = next;
+      conversations = [];
+      hasMoreConversations = false;
+      hasLoadedConversations = false;
+      emit();
+    },
+    setArchivedCount(value) {
+      archivedCount = value;
+      emit();
+    },
     appendConversations(items, hasMore) {
       const byId = new Map(conversations.map((item) => [item.conversation.id, item]));
       items.forEach((item) => byId.set(item.conversation.id, item));
@@ -1281,11 +1310,20 @@ function createMessagingEngine(options) {
   }
   async function reloadInbox() {
     if (disposed) return;
-    const page = await repository.listConversations({ limit: conversationPageSize });
+    const page = await repository.listConversations({
+      limit: conversationPageSize,
+      archived: store.snapshot().archiveFilter
+    });
     if (disposed) return;
     conversationCursor = page.nextCursor;
     store.setConversations(page.items, page.hasMore);
   }
+  async function reloadArchivedCount() {
+    if (disposed) return;
+    const value = await repository.countArchivedConversations();
+    if (disposed) return;
+    store.setArchivedCount(value);
+  }
   async function backfillConversation(id) {
     const thread = store.snapshot().threads.get(id);
     const since = thread?.latestAt ?? null;
@@ -1312,7 +1350,13 @@ function createMessagingEngine(options) {
     outbox,
     identity,
     async start() {
+      if (options.archiveFilter !== void 0) {
+        store.setArchiveFilter(options.archiveFilter);
+      }
       await reloadInbox();
+      void reloadArchivedCount().catch(
+        (error) => reportError(error, "refreshArchivedCount")
+      );
       if (disposed || inboxChannel !== null) return;
       inboxChannel = manager.open({
         topic: inboxTopic(identity.userId),
@@ -1354,12 +1398,33 @@ function createMessagingEngine(options) {
         }
       });
     },
+    async setArchiveFilter(next) {
+      if (next === store.snapshot().archiveFilter) return;
+      store.setArchiveFilter(next);
+      conversationCursor = null;
+      try {
+        await reloadInbox();
+      } catch (error) {
+        reportError(error, "setArchiveFilter");
+      }
+      await reloadArchivedCount().catch(
+        (error) => reportError(error, "refreshArchivedCount")
+      );
+    },
+    async refreshArchivedCount() {
+      try {
+        await reloadArchivedCount();
+      } catch (error) {
+        reportError(error, "refreshArchivedCount");
+      }
+    },
     async loadMoreConversations() {
       if (conversationCursor === null) return;
       try {
         const page = await repository.listConversations({
           limit: conversationPageSize,
-          cursor: conversationCursor
+          cursor: conversationCursor,
+          archived: store.snapshot().archiveFilter
         });
         conversationCursor = page.nextCursor;
         store.appendConversations(page.items, page.hasMore);
@@ -1668,6 +1733,7 @@ function createMessagingRepository(options) {
     identity,
     async listConversations(args = {}) {
       const limit = args.limit ?? 30;
+      const archived = args.archived ?? DEFAULT_MESSAGING_ARCHIVE_FILTER;
       const operation = "listConversations";
       const rows = await withSessionRetry(
         operation,
@@ -1677,7 +1743,12 @@ function createMessagingRepository(options) {
             p_user_id: identity.userId,
             p_limit: limit + 1,
             p_before_sort_at: args.cursor?.beforeSortAt ?? null,
-            p_before_conversation_id: args.cursor?.beforeConversationId ?? null
+            p_before_conversation_id: args.cursor?.beforeConversationId ?? null,
+            // THE ARCHIVED-ITEMS LAW, SERVER-side. `get_dm_conversations_with_details`
+            // used to hardcode `is_archived IS FALSE` with no parameter at all,
+            // so an archived conversation was not hidden — it was unreachable.
+            // The RPC gained `p_archived` on 2026-09-09 (register row R1).
+            p_archived: archived
           },
           operation
         )
@@ -1697,6 +1768,29 @@ function createMessagingRepository(options) {
         nextCursor: hasMore && last !== void 0 ? { beforeSortAt: last.sortAt, beforeConversationId: last.conversation.id } : null
       };
     },
+    async countArchivedConversations(args = {}) {
+      const limit = args.limit ?? 100;
+      const operation = "countArchivedConversations";
+      const rows = await withSessionRetry(
+        operation,
+        () => rpc(
+          RPCS.conversationsWithDetails,
+          {
+            p_user_id: identity.userId,
+            p_limit: limit + 1,
+            p_before_sort_at: null,
+            p_before_conversation_id: null,
+            p_archived: "archived"
+          },
+          operation
+        )
+      );
+      if (rows !== null && !Array.isArray(rows)) {
+        throw invalidResponse(operation, `${RPCS.conversationsWithDetails} did not return rows`);
+      }
+      const found = (rows ?? []).length;
+      return found > limit ? { count: limit, exact: false } : { count: found, exact: true };
+    },
     async getConversation(id) {
       const operation = "getConversation";
       const { data, error } = await withSessionRetry(
@@ -1930,11 +2024,4 @@ function createMessagingRepository(options) {
   };
   return repository;
 }
-
-// src/core/types.ts
-var asConversationId = (value) => value;
-var asMessageId = (value) => value;
-var asUserId = (value) => value;
-var asOrganizationId = (value) => value;
-var asClientMessageId = (value) => value;
 //# sourceMappingURL=index.cjs.map