@ai-matrx/messaging 0.15.82 → 0.16.0

package/dist/index.d.cts

@@ -134,6 +134,13 @@ interface Message {
     readonly attachments: readonly Attachment[];
     readonly references: readonly MatrxReference[];
     readonly metadata: JsonObject;
+    /**
+     * SOFT EXPIRY (`dm_messages.soft_expires_at`). Past this instant the message
+     * is LAPSED: still readable and actionable, never hidden or edited, and it no
+     * longer counts as unread. `null` = never lapses. Ask `isLapsed`, never
+     * compare this yourself — that is the one lapse rule.
+     */
+    readonly softExpiresAt: string | null;
     /** Set only while this message is in the outbox and its last send failed. */
     readonly failureReason?: string | undefined;
 }
@@ -222,6 +229,8 @@ interface DraftMessage {
     readonly attachments?: readonly Attachment[] | undefined;
     readonly references?: readonly MatrxReference[] | undefined;
     readonly metadata?: JsonObject | undefined;
+    /** ISO instant after which the message is lapsed (see `Message.softExpiresAt`). */
+    readonly softExpiresAt?: string | undefined;
 }
 
 /**
@@ -939,9 +948,22 @@ declare const RPCS: {
     /** Conversation list + participants + last message + unread, keyset paged. */
     readonly conversationsWithDetails: "get_dm_conversations_with_details";
     readonly unreadCount: "get_dm_unread_count";
+    /** The soonest future soft expiry per conversation, plus the server's clock. */
+    readonly pendingSoftExpiries: "get_dm_pending_soft_expiries";
     readonly userInfo: "get_dm_user_info";
     readonly isParticipant: "is_dm_participant";
 };
+/** The answer to `pendingSoftExpiries`: per conversation, and the server's own clock. */
+interface PendingSoftExpiries {
+    /** Soonest FUTURE `soft_expires_at` per conversation; absent = nothing pending. */
+    readonly byConversation: ReadonlyMap<ConversationId, string>;
+    /**
+     * The database's `now()` when it answered. The engine measures its clock against this and
+     * judges lapse on the SERVER's clock — a skewed browser clock never suppresses a count.
+     * `null` when nothing was asked (no conversations), so no clock was read.
+     */
+    readonly serverNow: string | null;
+}
 /**
  * The host's session source. A messaging read that lands between sign-in and
  * token arrival must not become a red error — it retries ONCE after the host
@@ -1054,6 +1076,20 @@ interface MessagingRepository {
     deleteMessage(id: MessageId, forEveryone: boolean): Promise<void>;
     /** Persists the cutoff, then returns the server's remaining unread count. */
     markRead(conversationId: ConversationId, at: string): Promise<number>;
+    /**
+     * The server's unread count for one conversation — READ ONLY. It never moves
+     * the watermark. The soft-expiry timer uses it to re-derive unread once a
+     * counted message lapses, instead of guessing with local arithmetic.
+     */
+    unreadCount(conversationId: ConversationId): Promise<number>;
+    /**
+     * The soonest FUTURE `soft_expires_at` among other people's live messages,
+     * per conversation, for the given conversations, and the server's clock.
+     * Conversations with nothing pending are absent. One call per
+     * `PENDING_SOFT_EXPIRY_CHUNK` conversations, each answering every one of them
+     * — this is what lets ONE timer re-derive unread when a counted message lapses.
+     */
+    pendingSoftExpiries(conversationIds: readonly ConversationId[]): Promise<PendingSoftExpiries>;
     setConversationFlags(conversationId: ConversationId, flags: {
         isMuted?: boolean;
         isArchived?: boolean;
@@ -1098,6 +1134,10 @@ declare function createMessagingRepository(options: RepositoryOptions): Messagin
  *    clears unread counts. Only a confirmed participant write may do that, and
  *    overlapping confirmations apply monotonically so one baseline is never
  *    subtracted twice.
+ * 6. **A lapsed message never counts as unread** (`isLapsed`, the one lapse
+ *    rule). It is ingested and drawn like any other message; it just never
+ *    increments a badge. Messages that lapse LATER are re-derived from the
+ *    server by the engine's one soft-expiry timer, never subtracted here.
  */
 
 /**
@@ -1229,7 +1269,11 @@ interface ConversationReadCutoff {
     /** Per-conversation unread-state revision observed when this read began. */
     readonly revision: number;
 }
-declare function createMessagingStore(): MessagingStore;
+interface MessagingStoreOptions {
+    /** The clock the lapse rule reads. Defaults to `Date.now`. */
+    now?: (() => number) | undefined;
+}
+declare function createMessagingStore(options?: MessagingStoreOptions): MessagingStore;
 /**
  * The optimistic row a composer shows the instant Enter is pressed. It carries
  * the outbox's client key, which is the whole reason the confirmed row can find
@@ -1246,6 +1290,7 @@ declare function optimisticMessage(args: {
     action?: Message["action"];
     attachments?: readonly Message["attachments"][number][];
     references?: readonly Message["references"][number][];
+    softExpiresAt?: string | null;
     now?: () => number;
 }): Message;
 
@@ -1294,6 +1339,8 @@ interface MessagingEngineOptions {
      * the list.
      */
     archiveFilter?: MessagingArchiveFilter | undefined;
+    /** The clock the soft-expiry rule reads. Defaults to `Date.now`. */
+    now?: (() => number) | undefined;
 }
 interface MessagingEngine {
     readonly store: MessagingStore;
@@ -1384,6 +1431,28 @@ declare function participantNames(participants: readonly UserSummary[], excludin
  */
 declare function formatLastSeen(lastSeenMs: number | null, now?: number): string;
 
+/**
+ * THE LAPSE RULE — the only place in this package that decides whether a
+ * message has soft-expired.
+ *
+ * A message carrying `softExpiresAt` (a meeting invitation is worth reading
+ * until an hour after the meeting starts) is LAPSED once that instant has
+ * passed. Lapsed is DERIVED from the clock every time it is asked, never
+ * stamped on the row: there is no sweeper and nothing to drift. The database's
+ * `get_dm_unread_count` applies the same comparison (`soft_expires_at > now()`
+ * still counts), so the badge the server computes and the bubble the client
+ * draws agree.
+ *
+ * A lapsed message stays readable and its actions keep working. It simply
+ * stops counting as unread — and the reader's watermark is NEVER moved for it,
+ * because moving `last_read_at` would mark every other message read too.
+ */
+
+/** Parse a soft-expiry instant; `null` when absent or unparseable (never lapses). */
+declare function softExpiryTime(message: Pick<Message, "softExpiresAt">): number | null;
+/** True when the message's soft expiry is at or before `now` (epoch ms or Date). */
+declare function isLapsed(message: Pick<Message, "softExpiresAt">, now?: number | Date): boolean;
+
 /**
  * THE INGRESS BOUNDARY — where a database row becomes a domain object.
  *
@@ -1466,4 +1535,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, type ConversationReadCutoff, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, writeNotApplied };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, type ConversationReadCutoff, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PendingSoftExpiries, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isLapsed, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, softExpiryTime, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, writeNotApplied };

package/dist/index.d.ts

@@ -134,6 +134,13 @@ interface Message {
     readonly attachments: readonly Attachment[];
     readonly references: readonly MatrxReference[];
     readonly metadata: JsonObject;
+    /**
+     * SOFT EXPIRY (`dm_messages.soft_expires_at`). Past this instant the message
+     * is LAPSED: still readable and actionable, never hidden or edited, and it no
+     * longer counts as unread. `null` = never lapses. Ask `isLapsed`, never
+     * compare this yourself — that is the one lapse rule.
+     */
+    readonly softExpiresAt: string | null;
     /** Set only while this message is in the outbox and its last send failed. */
     readonly failureReason?: string | undefined;
 }
@@ -222,6 +229,8 @@ interface DraftMessage {
     readonly attachments?: readonly Attachment[] | undefined;
     readonly references?: readonly MatrxReference[] | undefined;
     readonly metadata?: JsonObject | undefined;
+    /** ISO instant after which the message is lapsed (see `Message.softExpiresAt`). */
+    readonly softExpiresAt?: string | undefined;
 }
 
 /**
@@ -939,9 +948,22 @@ declare const RPCS: {
     /** Conversation list + participants + last message + unread, keyset paged. */
     readonly conversationsWithDetails: "get_dm_conversations_with_details";
     readonly unreadCount: "get_dm_unread_count";
+    /** The soonest future soft expiry per conversation, plus the server's clock. */
+    readonly pendingSoftExpiries: "get_dm_pending_soft_expiries";
     readonly userInfo: "get_dm_user_info";
     readonly isParticipant: "is_dm_participant";
 };
+/** The answer to `pendingSoftExpiries`: per conversation, and the server's own clock. */
+interface PendingSoftExpiries {
+    /** Soonest FUTURE `soft_expires_at` per conversation; absent = nothing pending. */
+    readonly byConversation: ReadonlyMap<ConversationId, string>;
+    /**
+     * The database's `now()` when it answered. The engine measures its clock against this and
+     * judges lapse on the SERVER's clock — a skewed browser clock never suppresses a count.
+     * `null` when nothing was asked (no conversations), so no clock was read.
+     */
+    readonly serverNow: string | null;
+}
 /**
  * The host's session source. A messaging read that lands between sign-in and
  * token arrival must not become a red error — it retries ONCE after the host
@@ -1054,6 +1076,20 @@ interface MessagingRepository {
     deleteMessage(id: MessageId, forEveryone: boolean): Promise<void>;
     /** Persists the cutoff, then returns the server's remaining unread count. */
     markRead(conversationId: ConversationId, at: string): Promise<number>;
+    /**
+     * The server's unread count for one conversation — READ ONLY. It never moves
+     * the watermark. The soft-expiry timer uses it to re-derive unread once a
+     * counted message lapses, instead of guessing with local arithmetic.
+     */
+    unreadCount(conversationId: ConversationId): Promise<number>;
+    /**
+     * The soonest FUTURE `soft_expires_at` among other people's live messages,
+     * per conversation, for the given conversations, and the server's clock.
+     * Conversations with nothing pending are absent. One call per
+     * `PENDING_SOFT_EXPIRY_CHUNK` conversations, each answering every one of them
+     * — this is what lets ONE timer re-derive unread when a counted message lapses.
+     */
+    pendingSoftExpiries(conversationIds: readonly ConversationId[]): Promise<PendingSoftExpiries>;
     setConversationFlags(conversationId: ConversationId, flags: {
         isMuted?: boolean;
         isArchived?: boolean;
@@ -1098,6 +1134,10 @@ declare function createMessagingRepository(options: RepositoryOptions): Messagin
  *    clears unread counts. Only a confirmed participant write may do that, and
  *    overlapping confirmations apply monotonically so one baseline is never
  *    subtracted twice.
+ * 6. **A lapsed message never counts as unread** (`isLapsed`, the one lapse
+ *    rule). It is ingested and drawn like any other message; it just never
+ *    increments a badge. Messages that lapse LATER are re-derived from the
+ *    server by the engine's one soft-expiry timer, never subtracted here.
  */
 
 /**
@@ -1229,7 +1269,11 @@ interface ConversationReadCutoff {
     /** Per-conversation unread-state revision observed when this read began. */
     readonly revision: number;
 }
-declare function createMessagingStore(): MessagingStore;
+interface MessagingStoreOptions {
+    /** The clock the lapse rule reads. Defaults to `Date.now`. */
+    now?: (() => number) | undefined;
+}
+declare function createMessagingStore(options?: MessagingStoreOptions): MessagingStore;
 /**
  * The optimistic row a composer shows the instant Enter is pressed. It carries
  * the outbox's client key, which is the whole reason the confirmed row can find
@@ -1246,6 +1290,7 @@ declare function optimisticMessage(args: {
     action?: Message["action"];
     attachments?: readonly Message["attachments"][number][];
     references?: readonly Message["references"][number][];
+    softExpiresAt?: string | null;
     now?: () => number;
 }): Message;
 
@@ -1294,6 +1339,8 @@ interface MessagingEngineOptions {
      * the list.
      */
     archiveFilter?: MessagingArchiveFilter | undefined;
+    /** The clock the soft-expiry rule reads. Defaults to `Date.now`. */
+    now?: (() => number) | undefined;
 }
 interface MessagingEngine {
     readonly store: MessagingStore;
@@ -1384,6 +1431,28 @@ declare function participantNames(participants: readonly UserSummary[], excludin
  */
 declare function formatLastSeen(lastSeenMs: number | null, now?: number): string;
 
+/**
+ * THE LAPSE RULE — the only place in this package that decides whether a
+ * message has soft-expired.
+ *
+ * A message carrying `softExpiresAt` (a meeting invitation is worth reading
+ * until an hour after the meeting starts) is LAPSED once that instant has
+ * passed. Lapsed is DERIVED from the clock every time it is asked, never
+ * stamped on the row: there is no sweeper and nothing to drift. The database's
+ * `get_dm_unread_count` applies the same comparison (`soft_expires_at > now()`
+ * still counts), so the badge the server computes and the bubble the client
+ * draws agree.
+ *
+ * A lapsed message stays readable and its actions keep working. It simply
+ * stops counting as unread — and the reader's watermark is NEVER moved for it,
+ * because moving `last_read_at` would mark every other message read too.
+ */
+
+/** Parse a soft-expiry instant; `null` when absent or unparseable (never lapses). */
+declare function softExpiryTime(message: Pick<Message, "softExpiresAt">): number | null;
+/** True when the message's soft expiry is at or before `now` (epoch ms or Date). */
+declare function isLapsed(message: Pick<Message, "softExpiresAt">, now?: number | Date): boolean;
+
 /**
  * THE INGRESS BOUNDARY — where a database row becomes a domain object.
  *
@@ -1466,4 +1535,4 @@ declare function summarizeText(content: string, maxLength?: number): string;
 /** Serialize picked references into a fence the platform's other readers accept. */
 declare function composeFence(references: readonly MatrxReference[]): string;
 
-export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, type ConversationReadCutoff, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, writeNotApplied };
+export { type ActionChoice, type ActionContext, type ActionHandler, type ActionOutcome, type ActionReceipt, type ActionRegistry, type ActorPresentation, type AiCallArgs, type AiCapability, type AiResult, type Attachment, type ClientMessageId, type Conversation, type ConversationAiContext, type ConversationCursor, type ConversationId, type ConversationReadCutoff, type ConversationReadFailure, type ConversationSummary, type ConversationThread, type ConversationType, DEFAULT_MESSAGING_ARCHIVE_FILTER, type DeliveryState, type DraftMessage, type EngineDiagnostic, type JsonObject, type JsonValue, MESSAGING_EVENTS, MESSAGING_RPC_SCHEMA, MESSAGING_SCHEMA, type MatrxReference, type Message, type MessageAction, type MessageCursor, type MessageGroup, type MessageId, type MessageKind, type MessagingAgentIdentity, type MessagingAgents, type MessagingAi, type MessagingAiOptions, type MessagingArchiveFilter, type MessagingEngine, type MessagingEngineOptions, MessagingError, type MessagingErrorCode, type MessagingIdentity, type MessagingRepository, type MessagingSnapshot, type MessagingStore, type MessagingSupabaseClient, type MessagingSupabaseInternal, type OrganizationId, type Outbox, type OutboxEntry, type OutboxOptions, type OutboxStorage, type Page, type Participant, type ParticipantRole, type PendingSoftExpiries, type PostgrestFilterLike, type PostgrestLikeResponse, type PostgrestTableLike, RPCS, type ReadCache, type ReadCacheOptions, type RepositoryOptions, SERVER_SESSION_IDENTITY, type SchemaLike, type SessionIdentity, type SessionIdentitySnapshot, type SessionResolver, type SupabaseLike, TABLES, type TextSegment, type UserId, type UserSummary, asClientMessageId, asConversationId, asMessageId, asOrganizationId, asUserId, composeFence, conversationContextVariables, conversationTopic, createActionRegistry, createMemoryOutboxStorage, createMessagingAi, createMessagingEngine, createMessagingRepository, createMessagingStore, createOutbox, createReadCache, createSessionIdentity, createWebOutboxStorage, effectiveActorKey, extractReferences, formatConversationTime, formatDateSeparator, formatLastSeen, formatMessageTime, formatTypists, groupMessages, inboxTopic, invalidResponse, isLapsed, isSameDay, messagingClientId, normalizeMessagingError, optimisticMessage, participantNames, projectConversationSummary, projectMessage, projectMessageAction, projectParticipantRole, projectUserSummary, resolveActor, softExpiryTime, splitText, summarizeText, toMessagingArchiveFilter, unreadCutoff, writeNotApplied };

package/dist/index.js

@@ -901,7 +901,8 @@ function projectBroadcastMessage(value) {
     action: projectMessageAction(record["action"]),
     attachments: projectAttachmentList(record["attachments"]),
     references: projectReferenceList(record["references"]),
-    metadata
+    metadata,
+    softExpiresAt: str(record, "softExpiresAt")
   };
 }
 function projectMessage(row, fallbackOrganizationId) {
@@ -931,7 +932,8 @@ function projectMessage(row, fallbackOrganizationId) {
     action,
     attachments: projectAttachments(metadata),
     references: projectReferences(metadata),
-    metadata
+    metadata,
+    softExpiresAt: str(row, "soft_expires_at")
   };
 }
 function projectParticipantRole(value) {
@@ -984,6 +986,18 @@ function projectConversationSummary(row, viewerId, fallbackOrganizationId) {
   };
 }
 
+// src/core/lapse.ts
+function softExpiryTime(message) {
+  if (message.softExpiresAt === null) return null;
+  const parsed = Date.parse(message.softExpiresAt);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function isLapsed(message, now = Date.now()) {
+  const at = softExpiryTime(message);
+  if (at === null) return false;
+  return at <= (typeof now === "number" ? now : now.getTime());
+}
+
 // src/core/types.ts
 var asConversationId = (value) => value;
 var asMessageId = (value) => value;
@@ -1021,7 +1035,8 @@ function insertOrdered(messages, message) {
   next.splice(index, 0, message);
   return next;
 }
-function createMessagingStore() {
+function createMessagingStore(options = {}) {
+  const now = options.now ?? Date.now;
   let conversations = [];
   let conversationSummaries = /* @__PURE__ */ new Map();
   let hasMoreConversations = false;
@@ -1258,7 +1273,7 @@ function createMessagingStore() {
       if (existing === void 0) return;
       if (message.deliveryState === "sending" || message.deletedAt !== null) return;
       if (existing.lastMessageAt !== null && message.createdAt < existing.lastMessageAt) return;
-      const shouldCount = args.incrementUnread === true;
+      const shouldCount = args.incrementUnread === true && !isLapsed(message, now());
       replaceOneSummary(message.conversationId, (item) => ({
         ...item,
         lastMessageContent: message.content,
@@ -1321,14 +1336,25 @@ function optimisticMessage(args) {
     action: args.action ?? null,
     attachments: args.attachments ?? [],
     references: args.references ?? [],
-    metadata: {}
+    metadata: {},
+    softExpiresAt: args.softExpiresAt ?? null
   };
 }
 
 // src/core/engine.ts
+var SOFT_EXPIRY_GRACE_MS = 2e3;
+var MAX_TIMER_DELAY_MS = 2147483647;
 function createMessagingEngine(options) {
   const { repository, manager, identity } = options;
-  const store = createMessagingStore();
+  const browserNow = options.now ?? Date.now;
+  let serverClockOffsetMs = 0;
+  const now = () => browserNow() + serverClockOffsetMs;
+  function learnServerClock(serverNow) {
+    if (serverNow === null) return;
+    const server = Date.parse(serverNow);
+    if (Number.isFinite(server)) serverClockOffsetMs = server - browserNow();
+  }
+  const store = createMessagingStore({ now });
   const conversationPageSize = options.conversationPageSize ?? 30;
   const messagePageSize = options.messagePageSize ?? 50;
   const openChannels = /* @__PURE__ */ new Map();
@@ -1342,6 +1368,8 @@ function createMessagingEngine(options) {
   let inboxChannel = null;
   let conversationCursor = null;
   let disposed = false;
+  const pendingExpiry = /* @__PURE__ */ new Map();
+  let expiryTimer = null;
   function report(event) {
     options.onDiagnostic?.(event);
   }
@@ -1384,6 +1412,72 @@ function createMessagingEngine(options) {
     }).catch(() => void 0);
     return current;
   }
+  function scheduleExpiryTimer() {
+    if (expiryTimer !== null) {
+      clearTimeout(expiryTimer);
+      expiryTimer = null;
+    }
+    if (disposed || pendingExpiry.size === 0) return;
+    const soonest = Math.min(...pendingExpiry.values());
+    const delay = Math.min(
+      MAX_TIMER_DELAY_MS,
+      Math.max(0, soonest + SOFT_EXPIRY_GRACE_MS - now())
+    );
+    expiryTimer = setTimeout(() => {
+      expiryTimer = null;
+      void fireSoftExpiry();
+    }, delay);
+  }
+  function noteSoftExpiry(id, at) {
+    if (at === null) return;
+    if (at <= now() && (store.snapshot().conversationSummaries.get(id)?.unreadCount ?? 0) === 0) {
+      return;
+    }
+    const held = pendingExpiry.get(id);
+    if (held !== void 0 && held <= at) return;
+    pendingExpiry.set(id, at);
+    scheduleExpiryTimer();
+  }
+  async function refreshPendingExpiries(ids) {
+    const summaries = store.snapshot().conversationSummaries;
+    const counted = ids.filter((id) => (summaries.get(id)?.unreadCount ?? 0) > 0);
+    ids.forEach((id) => pendingExpiry.delete(id));
+    if (counted.length > 0) {
+      const pending = await repository.pendingSoftExpiries(counted);
+      if (disposed) return;
+      learnServerClock(pending.serverNow);
+      pending.byConversation.forEach(
+        (at, id) => noteSoftExpiry(id, softExpiryTime({ softExpiresAt: at }))
+      );
+    }
+    scheduleExpiryTimer();
+  }
+  async function fireSoftExpiry() {
+    if (disposed) return;
+    const at = now();
+    const due = [...pendingExpiry.entries()].filter(([, expiry]) => expiry <= at).map(([id]) => id);
+    due.forEach((id) => pendingExpiry.delete(id));
+    await Promise.all(
+      due.map(async (id) => {
+        if ((store.snapshot().conversationSummaries.get(id)?.unreadCount ?? 0) === 0) return;
+        try {
+          const count = await repository.unreadCount(id);
+          if (!disposed) store.setUnreadCount(id, count);
+        } catch (error) {
+          reportError(error, "softExpiryUnread", { conversationId: id });
+        }
+      })
+    );
+    if (disposed) return;
+    await refreshPendingExpiries(due).catch(
+      (error) => reportError(error, "softExpiryRefresh")
+    );
+  }
+  function watchSoftExpiries(ids) {
+    void refreshPendingExpiries(ids).catch(
+      (error) => reportError(error, "softExpiryRefresh")
+    );
+  }
   const outbox = createOutbox({
     ...options.outboxStorage !== void 0 ? { storage: options.outboxStorage } : {},
     send: (draft, clientMessageId) => repository.insertMessage(draft, clientMessageId),
@@ -1410,7 +1504,8 @@ function createMessagingEngine(options) {
             ...entry.draft.replyToId !== void 0 ? { replyToId: entry.draft.replyToId } : {},
             ...entry.draft.action !== void 0 ? { action: entry.draft.action } : {},
             ...entry.draft.attachments !== void 0 ? { attachments: [...entry.draft.attachments] } : {},
-            ...entry.draft.references !== void 0 ? { references: [...entry.draft.references] } : {}
+            ...entry.draft.references !== void 0 ? { references: [...entry.draft.references] } : {},
+            ...entry.draft.softExpiresAt !== void 0 ? { softExpiresAt: entry.draft.softExpiresAt } : {}
           })
         );
       });
@@ -1439,6 +1534,7 @@ function createMessagingEngine(options) {
     if (disposed) return;
     conversationCursor = page.nextCursor;
     store.setConversations(page.items, page.hasMore);
+    watchSoftExpiries([...store.snapshot().conversationSummaries.keys()]);
   }
   async function reloadArchivedCount() {
     if (disposed) return;
@@ -1633,6 +1729,7 @@ function createMessagingEngine(options) {
               store.ingest(message);
               const isMine = message.senderId === identity.userId;
               store.applyLastMessage(message, { incrementUnread: !isMine });
+              if (!isMine) noteSoftExpiry(message.conversationId, softExpiryTime(message));
               if (!isMine && store.snapshot().activeConversationId === message.conversationId) {
                 void persistRead(message.conversationId).catch(() => void 0);
               }
@@ -1694,6 +1791,7 @@ function createMessagingEngine(options) {
         });
         conversationCursor = page.nextCursor;
         store.appendConversations(page.items, page.hasMore);
+        watchSoftExpiries(page.items.map((item) => item.conversation.id));
       } catch (error) {
         reportError(error, "loadMoreConversations");
       }
@@ -1713,7 +1811,10 @@ function createMessagingEngine(options) {
         const directSummary = missingSummary ? await repository.getConversationSummary(id) : null;
         if (!openIsLive(id, generation, ownedChannel)) return;
         store.setConversationReadFailure(id, null);
-        if (directSummary !== null) store.setConversationSummary(directSummary);
+        if (directSummary !== null) {
+          store.setConversationSummary(directSummary);
+          watchSoftExpiries([id]);
+        }
         await persistRead(
           id,
           () => openIsLive(id, generation, ownedChannel)
@@ -1808,6 +1909,9 @@ function createMessagingEngine(options) {
     },
     dispose() {
       disposed = true;
+      if (expiryTimer !== null) clearTimeout(expiryTimer);
+      expiryTimer = null;
+      pendingExpiry.clear();
       openChannels.forEach((_handle, id) => {
         initialReadGeneration.set(id, (initialReadGeneration.get(id) ?? 0) + 1);
       });
@@ -2069,10 +2173,13 @@ var RPCS = {
   /** Conversation list + participants + last message + unread, keyset paged. */
   conversationsWithDetails: "get_dm_conversations_with_details",
   unreadCount: "get_dm_unread_count",
+  /** The soonest future soft expiry per conversation, plus the server's clock. */
+  pendingSoftExpiries: "get_dm_pending_soft_expiries",
   userInfo: "get_dm_user_info",
   isParticipant: "is_dm_participant"
 };
-var MESSAGE_COLUMNS = "id,conversation_id,sender_id,organization_id,content,message_type,status,reply_to_id,client_message_id,action_data,media_url,media_thumbnail_url,media_metadata,created_at,edited_at,deleted_at,deleted_for_everyone,metadata";
+var MESSAGE_COLUMNS = "id,conversation_id,sender_id,organization_id,content,message_type,status,reply_to_id,client_message_id,action_data,media_url,media_thumbnail_url,media_metadata,created_at,edited_at,deleted_at,deleted_for_everyone,metadata,soft_expires_at";
+var PENDING_SOFT_EXPIRY_CHUNK = 200;
 var PARTICIPANT_COLUMNS = "conversation_id,user_id,role,joined_at,last_read_at,is_muted,is_archived";
 var CONVERSATION_COLUMNS = "id,type,group_name,group_image_url,created_by,organization_id,created_at,updated_at,metadata";
 function optionalOrg(organizationId) {
@@ -2493,6 +2600,9 @@ function createMessagingRepository(options) {
         // confirmed row instead of showing the message twice.
         client_message_id: clientMessageId,
         action_data: draft.action ?? null,
+        // SOFT EXPIRY: written only when the sender sets one. Lapsed is
+        // derived from it live (`isLapsed`), never stamped.
+        ...draft.softExpiresAt !== void 0 ? { soft_expires_at: draft.softExpiresAt } : {},
         metadata: {
           ...draft.metadata ?? {},
           ...draft.attachments !== void 0 && draft.attachments.length > 0 ? { attachments: draft.attachments } : {},
@@ -2545,6 +2655,56 @@ function createMessagingRepository(options) {
       }
       return Math.floor(unread);
     },
+    async unreadCount(conversationId) {
+      const operation = "unreadCount";
+      const me = await actingUser(operation);
+      const unread = await withSessionRetry(
+        operation,
+        () => rpc(
+          RPCS.unreadCount,
+          { p_conversation_id: conversationId, p_user_id: me },
+          operation
+        )
+      );
+      if (typeof unread !== "number" || !Number.isFinite(unread) || unread < 0) {
+        throw invalidResponse(operation, `${RPCS.unreadCount} returned ${JSON.stringify(unread)}`);
+      }
+      return Math.floor(unread);
+    },
+    async pendingSoftExpiries(conversationIds) {
+      const operation = "pendingSoftExpiries";
+      const unique = [...new Set(conversationIds)];
+      const byConversation = /* @__PURE__ */ new Map();
+      let serverNow = null;
+      for (let start = 0; start < unique.length; start += PENDING_SOFT_EXPIRY_CHUNK) {
+        const chunk = unique.slice(start, start + PENDING_SOFT_EXPIRY_CHUNK);
+        const answer = await withSessionRetry(
+          operation,
+          () => rpc(
+            RPCS.pendingSoftExpiries,
+            { p_conversation_ids: chunk },
+            operation
+          )
+        );
+        const now = answer?.["server_now"];
+        const pending = answer?.["pending"];
+        if (typeof now !== "string" || !Array.isArray(pending)) {
+          throw invalidResponse(
+            operation,
+            `${RPCS.pendingSoftExpiries} returned ${JSON.stringify(answer)}`
+          );
+        }
+        serverNow = now;
+        for (const row of pending) {
+          const id = row["conversation_id"];
+          const at = row["soft_expires_at"];
+          if (typeof id === "string" && typeof at === "string") {
+            byConversation.set(id, at);
+          }
+        }
+      }
+      return { byConversation, serverNow };
+    },
     async setConversationFlags(conversationId, flags) {
       const operation = "setConversationFlags";
       const me = await actingUser(operation);
@@ -2657,6 +2817,7 @@ export {
   groupMessages,
   inboxTopic,
   invalidResponse,
+  isLapsed,
   isSameDay,
   messagingClientId,
   normalizeMessagingError,
@@ -2668,6 +2829,7 @@ export {
   projectParticipantRole,
   projectUserSummary,
   resolveActor,
+  softExpiryTime,
   splitText,
   summarizeText,
   toMessagingArchiveFilter,