Merge pull request 'feat(#370 PR-1): ядро версий страниц — kind + ручной Save/idle/boundary триггеры' (#374) from feat/370-page-versioning into develop

Reviewed-on: #374

apps/server/src/collaboration/constants.ts

@@ -1,10 +1,36 @@
-export const HISTORY_INTERVAL = 5 * 60 * 1000;
-export const HISTORY_FAST_INTERVAL = 60 * 1000;
-export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
-
 // #348 — debounce window for the per-page RAG re-embed job. Repeated saves
 // within this window collapse to a single delayed job (coalesced by a stable
 // jobId), so active editing does not pile up expensive re-embeds (external API
 // + page_embeddings rewrite, concurrency 1). The worker reads the CURRENT page
 // state at run time, so the last content within the window wins.
 export const EMBED_DEBOUNCE_MS = 30 * 1000;
+
+/**
+ * #370 — page-history intentionality tiers. Domain of `page_history.kind`.
+ *   - 'manual' / 'agent'  → Tier 1 versions (intentional points)
+ *   - 'idle' / 'boundary' → Tier 0 autosnapshots (safety net)
+ * A legacy `null` kind is treated as an autosave.
+ */
+export type PageHistoryKind = 'manual' | 'agent' | 'idle' | 'boundary';
+
+/**
+ * #370 — trailing idle-flush windows. A page's pending idle snapshot is
+ * re-armed on every store and fires this long after edits go quiet, so a burst
+ * of edits collapses into a single autosnapshot instead of one-per-store. Human
+ * sessions are noisier and less risky, so they flush less often than the agent.
+ */
+export const IDLE_INTERVAL_USER = 60 * 60 * 1000; // 60m
+export const IDLE_INTERVAL_AGENT = 15 * 60 * 1000; // 15m
+
+/**
+ * #370 — max-wait ceiling for the idle flush. Pure trailing debounce starves the
+ * safety net: hocuspocus stores at least every ~45s, so a CONTINUOUS editing
+ * session would re-arm the trailing timer forever and never take an idle
+ * snapshot until edits finally go quiet (up to IDLE_INTERVAL_USER = 60m). This
+ * ceiling bounds the actual wait from the FIRST edit of a burst, so an idle
+ * snapshot fires at least this often during a long unbroken session — restoring
+ * a recovery point cadence closer to the old heuristic without one-per-store
+ * noise. Mirrors hocuspocus's own maxDebounce idea.
+ */
+export const IDLE_MAX_WAIT_USER = 10 * 60 * 1000; // 10m
+export const IDLE_MAX_WAIT_AGENT = 5 * 60 * 1000; // 5m

apps/server/src/collaboration/extensions/compute-history-job.spec.ts

@@ -1,84 +1,93 @@
+import { computeHistoryJob, resolveSource } from './persistence.extension';
 import {
-  computeHistoryJob,
-  resolveSource,
-} from './persistence.extension';
-import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
 } from '../constants';
 
-// A fixed clock + fixed createdAt make pageAge deterministic.
-const NOW = 1_700_000_000_000;
 const PAGE_ID = '550e8400-e29b-41d4-a716-446655440000';
 
-// Build a minimal page whose age (NOW - createdAt) is exactly `ageMs`.
-const pageAged = (ageMs: number) => ({
-  id: PAGE_ID,
-  createdAt: new Date(NOW - ageMs),
-});
+const page = { id: PAGE_ID };
 
-describe('computeHistoryJob', () => {
-  it('agent edit → delay MUST be 0 and job id is source-keyed', () => {
-    // INVARIANT (§15 H2 / persistence.extension): the agent delay MUST stay 0.
-    // The worker re-reads the page row at run time, so any non-zero delay risks
-    // snapshotting content a later human edit has already overwritten. This is
-    // the load-bearing assertion of this spec — do not relax it.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'agent', NOW);
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('agent edit on an OLD page is still delay 0 (age never applies to agents)', () => {
-    // Even when the page is far older than the fast threshold, the agent path
-    // must short-circuit to 0 — age-based debounce is a human-only concern.
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 60_000),
-      'agent',
-      NOW,
-    );
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('human edit on a YOUNG page (age < threshold) → fast interval, bare job id', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD - 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+describe('computeHistoryJob (#370 — shared trailing idle pipeline)', () => {
+  it('human edit → user idle window, bare page.id job', () => {
+    // Humans and the agent now share ONE idle job per page (jobId = page.id).
+    // The agent's old delay=0 fast path is GONE — intentional agent points now
+    // arrive via the explicit save-version signal, not a zero-delay snapshot.
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
     expect(jobId).toBe(PAGE_ID);
   });
 
-  it('human edit on an OLD page (age > threshold) → standard interval', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent edit → agent idle window (shorter), still the bare page.id job', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'agent');
+    expect(delay).toBe(IDLE_INTERVAL_AGENT);
+    // No `-agent` suffix anymore: the agent joins the common idle pipeline.
     expect(jobId).toBe(PAGE_ID);
   });
 
-  it('boundary: pageAge EXACTLY === threshold takes the slow branch (the `<` is strict)', () => {
-    // Off-by-one guard: the condition is `pageAge < HISTORY_FAST_THRESHOLD`, so
-    // an age of exactly the threshold is NOT "fast" — it must use HISTORY_INTERVAL.
-    const { delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent flushes sooner than a human', () => {
+    expect(IDLE_INTERVAL_AGENT).toBeLessThan(IDLE_INTERVAL_USER);
   });
 
-  it('treats any non-"agent" source string as human', () => {
-    // resolveSource only ever yields 'agent' | 'user', but guard the contract:
-    // the agent branch keys strictly on === 'agent'.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'user', NOW);
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+  it('treats any non-"agent" source string as human (keys strictly on === agent)', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
     expect(jobId).toBe(PAGE_ID);
   });
+
+  // #370 review round-1 WARNING: the max-wait ceiling prevents autosnapshot
+  // starvation during a continuous editing session (the trailing timer would
+  // otherwise re-arm forever and never fire).
+  describe('max-wait ceiling', () => {
+    const T0 = 1_000_000; // arbitrary fixed epoch for deterministic tests
+
+    it('once a burst is armed, delay clamps to the remaining max-wait budget', () => {
+      // 1 minute into the burst the USER interval (60m) far exceeds the remaining
+      // max-wait budget (10m - 1m = 9m), so the delay is clamped DOWN to that
+      // remaining budget — the full interval is NOT used once a ceiling applies.
+      const { delay } = computeHistoryJob(page, 'user', T0, T0 + 60_000);
+      expect(delay).toBe(IDLE_MAX_WAIT_USER - 60_000);
+    });
+
+    it('never waits longer than the max-wait budget from the burst start', () => {
+      // A store arriving right at the ceiling → delay 0 (fire promptly).
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('past the ceiling never returns a negative delay', () => {
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER + 5 * 60_000,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('the agent ceiling is shorter than the user ceiling', () => {
+      expect(IDLE_MAX_WAIT_AGENT).toBeLessThan(IDLE_MAX_WAIT_USER);
+      const { delay } = computeHistoryJob(
+        page,
+        'agent',
+        T0,
+        T0 + IDLE_MAX_WAIT_AGENT,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('without a burstStart there is no ceiling (backward-compatible)', () => {
+      expect(computeHistoryJob(page, 'user').delay).toBe(IDLE_INTERVAL_USER);
+      expect(computeHistoryJob(page, 'agent').delay).toBe(IDLE_INTERVAL_AGENT);
+    });
+  });
 });
 
 describe('resolveSource (truth table)', () => {

apps/server/src/collaboration/extensions/persistence-store.spec.ts

@@ -40,11 +40,12 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
   let pageHistoryRepo: {
     saveHistory: jest.Mock;
     findPageLastHistory: jest.Mock;
+    updateHistoryKind: jest.Mock;
   };
   let aiQueue: { add: jest.Mock };
-  let historyQueue: { add: jest.Mock };
+  let historyQueue: { add: jest.Mock; remove: jest.Mock };
   let notificationQueue: { add: jest.Mock };
-  let collabHistory: { addContributors: jest.Mock };
+  let collabHistory: { addContributors: jest.Mock; popContributors: jest.Mock };
   let transclusionService: {
     syncPageTransclusions: jest.Mock;
     syncPageReferences: jest.Mock;
@@ -93,13 +94,22 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     pageHistoryRepo = {
       saveHistory: jest.fn().mockImplementation(async () => {
         callOrder.push('saveHistory');
+        return { id: 'history-1' };
       }),
       findPageLastHistory: jest.fn().mockResolvedValue(null),
+      updateHistoryKind: jest.fn().mockResolvedValue(undefined),
     };
     aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = {
+      add: jest.fn().mockResolvedValue(undefined),
+      // #370 — enqueuePageHistory now removes any pending idle job before re-adding.
+      remove: jest.fn().mockResolvedValue(undefined),
+    };
     notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = {
+      addContributors: jest.fn().mockResolvedValue(undefined),
+      popContributors: jest.fn().mockResolvedValue([]),
+    };
     transclusionService = {
       syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
       syncPageReferences: jest.fn().mockResolvedValue(undefined),
@@ -165,6 +175,50 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
   });
 
+  // #370 review round-1 SUGGESTION: the boundary was GENERALIZED from a
+  // user→agent special-case to ANY lastUpdatedSource transition. These pin the
+  // generalized behaviour it was rebuilt for.
+  describe('generalized boundary — any source transition', () => {
+    // Same persisted page but with an explicit prior source.
+    const pageWithPriorSource = (prior: string | null) => ({
+      ...persistedHumanPage('NEW CONTENT'),
+      lastUpdatedSource: prior,
+    });
+
+    it('agent→user transition fires the boundary (pins the prior agent revision)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('agent'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+      expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
+    });
+
+    it('git→user transition fires the boundary (git-sync overwrite is a source change)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('git'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+    });
+
+    it('a null prior source (first-ever edit) does NOT fire the boundary', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource(null));
+
+      await ext.onStoreDocument(buildData(document, 'agent') as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+    });
+  });
+
   it('idempotency: unchanged content → no updatePage, no history, no queues', async () => {
     // The Y.Doc content equals the persisted content deeply → early skip.
     // A Y.Doc round-trip normalizes attrs (e.g. paragraph indent), so derive
@@ -479,4 +533,231 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     // Contributors keyed by the UUID so they match the PAGE_HISTORY job (page.id).
     expect(collabHistory.addContributors.mock.calls[0][0]).toBe(PAGE_ID);
   });
+
+  // #370 — explicit save-version (Cmd+S / agent save tool) over the stateless
+  // seam. The tier is derived from the SIGNED connection actor, the store path
+  // is reused, and promote-not-dup avoids duplicating heavy content rows.
+  describe('save-version (#370)', () => {
+    const emitSave = (document: any, actor: 'user' | 'agent') =>
+      ext.onStateless({
+        connection: {
+          readOnly: false,
+          context: { user: { id: USER_ID, name: 'Alice' }, actor },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+    // findById returns a page whose content already equals the live doc, so the
+    // store path is a no-op and we isolate the versioning decision.
+    const pageMatchingDoc = (document: any) => ({
+      ...persistedHumanPage('IGNORED'),
+      content: TiptapTransformer.fromYdoc(document, 'default'),
+    });
+
+    it('human save with no prior snapshot → writes a manual version + broadcasts', async () => {
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(pageHistoryRepo.saveHistory.mock.calls[0][1]).toEqual(
+        expect.objectContaining({ kind: 'manual' }),
+      );
+      // The pending idle autosnapshot is cancelled by the explicit version.
+      expect(historyQueue.remove).toHaveBeenCalledWith(PAGE_ID);
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({
+        type: 'version.saved',
+        kind: 'manual',
+        alreadySaved: false,
+      });
+    });
+
+    it('agent save derives kind=agent from the signed actor', async () => {
+      const document = ydocFor(doc('AGENT VERSION'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'agent');
+
+      expect(pageHistoryRepo.saveHistory.mock.calls[pageHistoryRepo.saveHistory.mock.calls.length - 1][1]).toEqual(
+        expect.objectContaining({ kind: 'agent' }),
+      );
+    });
+
+    it('promote-not-dup: latest snapshot is an autosave with identical content → upgrades in place', async () => {
+      const document = ydocFor(doc('SAME'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'auto-1',
+        content: page.content,
+        kind: 'idle',
+      });
+
+      await emitSave(document, 'user');
+
+      // No heavy new content row — the existing autosave is promoted to manual.
+      expect(pageHistoryRepo.updateHistoryKind).toHaveBeenCalledWith(
+        'auto-1',
+        'manual',
+        expect.anything(),
+      );
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ historyId: 'auto-1', alreadySaved: false });
+    });
+
+    it('no-op when the latest snapshot is already a manual version of this content', async () => {
+      const document = ydocFor(doc('ALREADY SAVED'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'ver-1',
+        content: page.content,
+        kind: 'manual',
+      });
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ alreadySaved: true, kind: 'manual' });
+    });
+
+    it('a read-only connection cannot save a version', async () => {
+      const document = ydocFor(doc('READER'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+
+      await ext.onStateless({
+        connection: {
+          readOnly: true,
+          context: { user: { id: USER_ID }, actor: 'user' },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+    });
+
+    // #370 F8-twin — a COMMIT abort (serialization/deadlock/conn-drop) rejects
+    // OUTSIDE the tx callback, AFTER the destructive popContributors (SPOP) and
+    // saveHistory ran but the INSERT rolled back. onStateless has no retry, so
+    // the outer catch MUST re-add (SADD) the popped set or attribution is lost
+    // irrecoverably. MUTATION: drop the outer catch → addContributors is never
+    // called → this reddens.
+    it('restores popped contributors when the commit aborts after the callback', async () => {
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      // No matching snapshot → fresh version branch → pops contributors.
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+      collabHistory.popContributors.mockResolvedValue(['u1', 'u2']);
+
+      // A db whose commit REJECTS after the callback body resolved: the SPOP and
+      // saveHistory already ran, then the tx aborts. onStoreDocument's flush uses
+      // the same db but its content matches (no-op branch) and its own retry loop
+      // swallows the throw, so only the versioning tx exercises the restore.
+      const commitFailingDb = {
+        transaction: () => ({
+          execute: async (fn: (trx: any) => Promise<any>) => {
+            await fn(trxStub);
+            throw new Error('commit aborted (serialization_failure)');
+          },
+        }),
+      };
+      const ext2 = new PersistenceExtension(
+        pageRepo as any,
+        pageHistoryRepo as any,
+        commitFailingDb as any,
+        aiQueue as any,
+        historyQueue as any,
+        notificationQueue as any,
+        collabHistory as any,
+        transclusionService as any,
+      );
+      jest.spyOn(ext2['logger'], 'debug').mockImplementation(() => undefined);
+      jest.spyOn(ext2['logger'], 'warn').mockImplementation(() => undefined);
+      jest.spyOn(ext2['logger'], 'error').mockImplementation(() => undefined);
+
+      await expect(
+        ext2.onStateless({
+          connection: {
+            readOnly: false,
+            context: { user: { id: USER_ID, name: 'Alice' }, actor: 'user' },
+          } as any,
+          documentName: `page.${PAGE_ID}`,
+          document: document as any,
+          payload: JSON.stringify({ type: 'save-version' }),
+        } as any),
+      ).rejects.toThrow();
+
+      // Attribution preserved: the popped set is SADD-restored, keyed by the page
+      // UUID it was popped under.
+      expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+        'u1',
+        'u2',
+      ]);
+    });
+
+    // #370 #260 — for a `page.<slugId>` document the idle job is armed under the
+    // page UUID (computeHistoryJob's jobId = page.id), so the supersede-remove
+    // must target page.id, not the raw slugId doc-name id, or it silently misses.
+    it('cancels the superseded idle job by the page UUID for a slugId doc', async () => {
+      const SLUG = 'slug-1'; // persistedHumanPage.slugId
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStateless({
+        connection: {
+          readOnly: false,
+          context: { user: { id: USER_ID, name: 'Alice' }, actor: 'user' },
+        } as any,
+        documentName: `page.${SLUG}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+      // remove() keyed by the UUID (the real jobId), never the slugId.
+      expect(historyQueue.remove).toHaveBeenCalledWith(PAGE_ID);
+      expect(historyQueue.remove).not.toHaveBeenCalledWith(SLUG);
+    });
+  });
+
+  // #370 — the in-memory idle-burst marker must be dropped on doc unload (like
+  // its sibling per-document maps) or it grows unbounded for every page that was
+  // edited but never manually saved. MUTATION: drop the afterUnloadDocument
+  // delete → the entry survives → this reddens.
+  describe('idleBurstStart housekeeping', () => {
+    it('afterUnloadDocument clears the idle-burst marker armed by a store', async () => {
+      const document = ydocFor(doc('EDIT'));
+      pageRepo.findById.mockResolvedValue(persistedHumanPage('EDIT'));
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      const map = ext['idleBurstStart'] as Map<string, number>;
+      // Keyed by documentName (buildData uses `page.${PAGE_ID}`).
+      expect(map.has(`page.${PAGE_ID}`)).toBe(true);
+
+      await ext.afterUnloadDocument({
+        documentName: `page.${PAGE_ID}`,
+      } as any);
+
+      expect(map.has(`page.${PAGE_ID}`)).toBe(false);
+    });
+  });
 });

apps/server/src/collaboration/extensions/persistence.extension.ts

@@ -37,9 +37,11 @@ import { Page } from '@docmost/db/types/entity.types';
 import { CollabHistoryService } from '../services/collab-history.service';
 import {
   EMBED_DEBOUNCE_MS,
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
+  PageHistoryKind,
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
 import {
@@ -56,6 +58,16 @@ import { hasTransclusionFamilyNodes } from '../../core/page/transclusion/utils/t
  */
 export const INTENTIONAL_CLEAR_MESSAGE_TYPE = 'intentional-clear';
 
+/**
+ * #370 — wire format of the client→server "save a version" signal. Sent by the
+ * human (Cmd+S / Save button) and by the agent's explicit save tool over the
+ * SAME stateless channel. The intentionality tier ('manual' vs 'agent') is
+ * derived SERVER-SIDE from the signed connection actor, never from this
+ * payload, so a version's type is unforgeable. The document is taken from the
+ * connection (not the payload), so the signal cannot be aimed at another page.
+ */
+export const SAVE_VERSION_MESSAGE_TYPE = 'save-version';
+
 /**
  * #251 — how long an intentional-clear signal stays "pending" before it is
  * ignored. The signal is set on the clearing keystroke but consumed by the
@@ -92,35 +104,39 @@ export function resolveSource(
 }
 
 /**
- * Compute the BullMQ job id + delay for a page-history snapshot job. Pure so
- * the data-loss-sensitive timing arithmetic is unit-testable; `now` is injected
- * (caller passes `Date.now()`) for determinism.
+ * #370 — compute the BullMQ job id + delay for a page's trailing idle-flush
+ * autosnapshot. Pure so the timing is unit-testable.
  *
- * - Agent edits: delay 0 and a source-keyed job id `${page.id}-agent`. The
- *   delay MUST stay 0 — the worker re-reads the page row at run time, so any
- *   delay risks reading content a later human edit has already overwritten
- *   (mis-tagged snapshot). 0 minimizes that window. The `-agent` suffix keeps
- *   the job from coalescing with the bare-page.id human job.
- * - Human edits: age-based debounce so rapid human edits coalesce into one
- *   snapshot; job id is the bare `page.id`.
- *
- * BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is used;
- * page.id is a UUID, so `${page.id}-agent` cannot collide with a human job.
+ * Both humans and the agent now share ONE idle pipeline (the agent's old
+ * `delay=0` fast path is gone — intentional agent points arrive via the
+ * explicit save-version signal instead). The job id is the bare `page.id`, so a
+ * page has at most one pending idle job; the caller removes-and-re-adds it on
+ * every store to keep it debounced to the trailing edge of an edit burst. The
+ * window differs by source only: the agent flushes sooner than a human.
  */
 export function computeHistoryJob(
-  page: Pick<Page, 'id' | 'createdAt'>,
+  page: Pick<Page, 'id'>,
   source: string,
-  now: number,
+  // Epoch ms of the FIRST edit in the current burst (when the pending idle job
+  // was first armed). Used to enforce the max-wait ceiling so a continuous
+  // editing session cannot re-arm the trailing timer forever. `now` is injectable
+  // for tests; both default to a live clock / no ceiling when omitted.
+  burstStart?: number,
+  now: number = Date.now(),
 ): { jobId: string; delay: number } {
   const isAgent = source === 'agent';
-  const pageAge = now - new Date(page.createdAt).getTime();
-  const delay = isAgent
-    ? 0
-    : pageAge < HISTORY_FAST_THRESHOLD
-      ? HISTORY_FAST_INTERVAL
-      : HISTORY_INTERVAL;
-  const jobId = isAgent ? `${page.id}-agent` : page.id;
-  return { jobId, delay };
+  const interval = isAgent ? IDLE_INTERVAL_AGENT : IDLE_INTERVAL_USER;
+  const maxWait = isAgent ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+
+  let delay = interval;
+  if (burstStart !== undefined) {
+    // Time already elapsed since the burst's first edit; the snapshot must fire
+    // no later than `maxWait` after that, so shrink the trailing delay to the
+    // remaining budget (never negative, so BullMQ fires it promptly).
+    const remaining = burstStart + maxWait - now;
+    delay = Math.max(0, Math.min(interval, remaining));
+  }
+  return { jobId: page.id, delay };
 }
 
 @Injectable()
@@ -132,6 +148,28 @@ export class PersistenceExtension implements Extension {
   // coalescing window" per document and OR it across all edits in the window,
   // so the snapshot is marked 'agent' regardless of who wrote last.
   private agentTouched: Map<string, boolean> = new Map();
+  // #370 — epoch ms of the FIRST edit in the current idle-flush burst. Keyed by
+  // documentName (like its sibling per-document maps above), NOT by page.id, so
+  // it can be cleaned in afterUnloadDocument alongside `contributors` /
+  // `agentTouched` / `intentionalClear` when the doc unloads — otherwise any page
+  // that was edited but never manually saved (the common case) would keep its
+  // entry forever and the Map would grow unbounded in this long-lived process.
+  // Set when the pending idle job is first armed (empty entry), read to enforce
+  // the max-wait ceiling in computeHistoryJob, and cleared on doc unload or when
+  // a manual save cancels the idle job so the next burst starts a fresh window.
+  //
+  // Single-process assumption (like `contributors` / `agentTouched` above): this
+  // lives only in THIS collab process's memory. A restart, or a page's ownership
+  // moving to another node, loses the burst-start marker. Consequence: a burst
+  // that spans the restart looks like a fresh burst to the surviving process, so
+  // its max-wait ceiling is re-anchored to the first post-restart edit — a single
+  // continuous session straddling a restart can therefore wait up to ~2× the cap
+  // for its idle snapshot (once for the lost pre-restart window, once for the new
+  // one). Bounded and benign (it only DELAYS a safety-net autosnapshot; manual
+  // saves are unaffected and the next quiet period always flushes), but the
+  // assumption and its consequence are recorded here so no one mistakes the
+  // in-memory marker for a durable, cross-process guarantee.
+  private idleBurstStart: Map<string, number> = new Map();
   // #251 — per-document "intentional clear pending" flags. Keyed by
   // documentName, value = expiry timestamp (ms). Set by onStateless when the
   // client reports a deliberate clear; consumed once by the next
@@ -363,20 +401,19 @@ export class PersistenceExtension implements Extension {
             //this.logger.debug('Contributors error:' + err?.['message']);
           }
 
-          // Approach A — boundary snapshot before the agent's first edit.
-          // When this store is the agent's and the page's currently persisted
-          // state was authored by a human, pin that human state as its own
-          // history version BEFORE the agent overwrites it. `page` still holds
-          // the OLD content/provenance here, so saveHistory(page) captures the
-          // pre-agent state tagged 'user'. The agent's new content is
-          // snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
-          // if the prior state is already agent-authored (boundary already
-          // pinned on the user->agent transition), if the page is effectively
-          // empty, or if the latest existing snapshot already equals this human
-          // state (avoid duplicates).
+          // #370 — boundary snapshot on ANY source transition. When the store
+          // flips the page's provenance (user↔agent↔git), pin the OUTGOING
+          // state as its own history version BEFORE the incoming source
+          // overwrites it. `page` still holds the OLD content/provenance here,
+          // so saveHistory(page) captures the pre-transition state tagged with
+          // its own source, kind='boundary'. The incoming content is snapshotted
+          // later by the debounced idle job. Skip if the page is effectively
+          // empty or if the latest existing snapshot already equals this state
+          // (the shared isDeepStrictEqual gate — avoids duplicates). Generalizing
+          // beyond the old user→agent special-case also covers git-sync for free.
           if (
-            lastUpdatedSource === 'agent' &&
-            page.lastUpdatedSource !== 'agent'
+            page.lastUpdatedSource &&
+            page.lastUpdatedSource !== lastUpdatedSource
           ) {
             // pageHistory.pageId is uuid-typed; use page.id (never the doc-name
             // slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
@@ -384,15 +421,13 @@ export class PersistenceExtension implements Extension {
               page.id,
               { includeContent: true, trx },
             );
-            const humanBaselineMissing =
+            const baselineMissing =
               !lastHistory ||
               !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+            if (!isEmptyParagraphDoc(page.content as any) && baselineMissing) {
               await this.pageHistoryRepo.saveHistory(page, {
                 contributorIds: page.contributorIds ?? undefined,
+                kind: 'boundary',
                 trx,
               });
             }
@@ -522,7 +557,7 @@ export class PersistenceExtension implements Extension {
         { jobId: `embed-${page.id}`, delay: EMBED_DEBOUNCE_MS },
       );
 
-      await this.enqueuePageHistory(page, lastUpdatedSource);
+      await this.enqueuePageHistory(page, documentName, lastUpdatedSource);
     }
 
     // #402 — report the serialized size for the store histogram's size_bucket.
@@ -554,6 +589,14 @@ export class PersistenceExtension implements Extension {
       return; // unrelated / malformed stateless message
     }
 
+    // #370 — explicit "save a version" (human Cmd+S / agent save tool). Edit
+    // rights are already enforced by the readOnly reject above (a reader can't
+    // create a version), exactly as intentional-clear requires.
+    if (message?.type === SAVE_VERSION_MESSAGE_TYPE) {
+      await this.handleSaveVersion(data);
+      return;
+    }
+
     if (message?.type !== INTENTIONAL_CLEAR_MESSAGE_TYPE) return;
 
     this.intentionalClear.set(
@@ -562,6 +605,160 @@ export class PersistenceExtension implements Extension {
     );
   }
 
+  /**
+   * #370 — persist an intentional version from the live in-memory ydoc.
+   *
+   * One stateless path serves BOTH the human and the agent; the tier is derived
+   * SERVER-SIDE from the signed connection actor ('agent' → 'agent', anything
+   * else → 'manual'), so the version type cannot be spoofed by the client. We
+   * take the fresh ydoc from the collab process memory and run it through the
+   * EXISTING store path first (so pages.content/ydoc reflect the exact content
+   * being versioned — a REST endpoint would race the up-to-10s-stale page row),
+   * then snapshot it into page_history with the intentional kind.
+   *
+   * Promote-not-dup: if the latest history row already holds this exact content
+   * and it is an autosave (idle/boundary/legacy-null), upgrade its kind in place
+   * instead of duplicating a heavy content row; if it is already 'manual', it is
+   * a no-op (the client shows an "already saved" toast). Otherwise a fresh
+   * version row is written, popping the aggregated contributors from Redis.
+   */
+  private async handleSaveVersion(data: onStatelessPayload): Promise<void> {
+    const { connection, document, documentName } = data;
+    const context = connection?.context;
+    const pageId = getPageId(documentName);
+    // Unforgeable: 'agent' only for a signed agent connection, else 'manual'.
+    const kind: PageHistoryKind =
+      context?.actor === 'agent' ? 'agent' : 'manual';
+
+    // Flush the live ydoc through the normal store path so the page row + ydoc
+    // hold exactly what we are about to version (also fires the idle enqueue we
+    // supersede below, plus any source-transition boundary). onStoreDocument
+    // only needs document/documentName/context.
+    await this.onStoreDocument({
+      document,
+      documentName,
+      context,
+    } as onStoreDocumentPayload);
+
+    let result:
+      | { historyId: string; kind: PageHistoryKind; alreadySaved: boolean }
+      | undefined;
+
+    // #370 F8-twin — the contributor set popped from Redis (destructive SPOP)
+    // must be restored if the version row does not durably land. The inner
+    // try/catch below only covers a throw INSIDE the callback; but executeTx
+    // COMMITS after the callback, so a commit-abort (serialization/deadlock/
+    // connection drop — the transient class the epic retries in the processor)
+    // rejects OUTSIDE the callback, after saveHistory already ran and the SPOP
+    // already happened, while the INSERT rolls back. onStateless does NOT retry,
+    // so an unrestored pop is a one-shot irrecoverable attribution loss (the
+    // processor got exactly this fix: poppedForRestore + an outer catch). We
+    // track the popped set here (keyed by the page UUID it was popped by — never
+    // the doc-name id, which may be a slugId, #260) and restore it in the outer
+    // catch. addContributors is an idempotent Redis SADD, so a double-restore is
+    // harmless. versionedPageId is also reused below to remove the superseded
+    // idle job by its real jobId (page.id).
+    let poppedForRestore: string[] = [];
+    let versionedPageId: string | undefined;
+
+    try {
+      await executeTx(this.db, async (trx) => {
+        const page = await this.pageRepo.findById(pageId, {
+          withLock: true,
+          includeContent: true,
+          trx,
+        });
+        if (!page) return;
+        versionedPageId = page.id;
+        // Never version an effectively-empty page (mirrors the processor's
+        // first-history guard); there is nothing intentional to pin.
+        if (isEmptyParagraphDoc(page.content as any)) return;
+
+        const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+          page.id,
+          { includeContent: true, trx },
+        );
+
+        if (
+          lastHistory &&
+          isDeepStrictEqual(lastHistory.content, page.content)
+        ) {
+          // Content is already snapshotted. Promote-not-dup.
+          if (lastHistory.kind === 'manual') {
+            result = {
+              historyId: lastHistory.id,
+              kind: 'manual',
+              alreadySaved: true,
+            };
+            return;
+          }
+          await this.pageHistoryRepo.updateHistoryKind(
+            lastHistory.id,
+            kind,
+            trx,
+          );
+          result = { historyId: lastHistory.id, kind, alreadySaved: false };
+          return;
+        }
+
+        // Fresh version row. Pop the contributors aggregated since the last
+        // snapshot (SPOP); restore them if the write fails so they aren't lost.
+        const contributorIds = await this.collabHistory.popContributors(
+          page.id,
+        );
+        poppedForRestore = contributorIds;
+        try {
+          const saved = await this.pageHistoryRepo.saveHistory(page, {
+            contributorIds,
+            kind,
+            trx,
+          });
+          result = { historyId: saved.id, kind, alreadySaved: false };
+        } catch (err) {
+          await this.collabHistory.addContributors(page.id, contributorIds);
+          poppedForRestore = [];
+          throw err;
+        }
+      });
+    } catch (err) {
+      // A throw here means the tx did NOT commit (callback threw, or the commit
+      // itself failed and rolled back). If we popped contributors and the inner
+      // catch did not already restore them, restore now so attribution is not
+      // lost — onStateless has no retry to recover it. Restore by the page UUID
+      // the pop was keyed under (versionedPageId is always set before the pop).
+      if (poppedForRestore.length && versionedPageId) {
+        await this.collabHistory.addContributors(
+          versionedPageId,
+          poppedForRestore,
+        );
+      }
+      throw err;
+    }
+
+    // Housekeeping: this explicit version supersedes the page's pending idle
+    // autosnapshot, so cancel it and end the current idle burst so the next edit
+    // starts a fresh max-wait window. Remove the idle job by its REAL jobId
+    // (page.id UUID — computeHistoryJob arms it under page.id), not the raw
+    // doc-name id which may be a slugId for a `page.<slugId>` doc (#260), or the
+    // remove silently misses. The burst marker is keyed by documentName (like its
+    // sibling per-document maps), and is also cleaned in afterUnloadDocument.
+    if (versionedPageId) {
+      await this.historyQueue.remove(versionedPageId).catch(() => undefined);
+    }
+    this.idleBurstStart.delete(documentName);
+
+    if (result) {
+      document.broadcastStateless(
+        JSON.stringify({
+          type: 'version.saved',
+          historyId: result.historyId,
+          kind: result.kind,
+          alreadySaved: result.alreadySaved,
+        }),
+      );
+    }
+  }
+
   async onChange(data: onChangePayload) {
     const documentName = data.documentName;
     const userId = data.context?.user?.id;
@@ -586,6 +783,10 @@ export class PersistenceExtension implements Extension {
     this.contributors.delete(documentName);
     this.agentTouched.delete(documentName);
     this.intentionalClear.delete(documentName);
+    // #370 — drop the idle-burst marker with the other per-document maps so it
+    // cannot accumulate across the process lifetime for never-manually-saved
+    // pages. The pending idle job (if any) is a self-expiring BullMQ delayed job.
+    this.idleBurstStart.delete(documentName);
   }
 
   private consumeContributors(documentName: string): string[] {
@@ -617,19 +818,80 @@ export class PersistenceExtension implements Extension {
 
   private async enqueuePageHistory(
     page: Page,
+    documentName: string,
     lastUpdatedSource: string,
   ): Promise<void> {
-    // Job id + delay arithmetic lives in the pure `computeHistoryJob` (see its
-    // doc comment for the agent-delay-0 / age-based-debounce invariants).
+    // #370 — trailing idle debounce with a max-wait ceiling. One pending idle
+    // job per page (jobId = page.id); on every store we remove the pending
+    // delayed job and re-add it, so the snapshot lands `delay` after edits go
+    // quiet rather than once per store (precedent: workspace.service.ts).
+    // remove() on a delayed job simply deletes it (0 if absent, no throw); if the
+    // job is already ACTIVE and the remove is a no-op, the add still de-dups and
+    // the processor's isDeepStrictEqual gate collapses the duplicate content.
+    //
+    // The FIRST arm of a burst records `burstStart`; computeHistoryJob shrinks
+    // the delay to the remaining max-wait budget from that point, so a continuous
+    // session cannot re-arm the trailing timer forever and starve the snapshot.
+    // A burst marker older than THIS TIER's max-wait means the previous idle job
+    // has already fired — start a fresh window instead of firing immediately on
+    // the next edit. Must use the SAME source-specific max-wait computeHistoryJob
+    // uses (agent 5m / user 10m): a hardcoded USER ceiling would leave an agent
+    // burst's marker stale for 5..10m, forcing delay=0 on every store in that
+    // window and writing one idle row per store — exactly the per-store bloat the
+    // debounce exists to prevent, on the continuous-agent path.
+    const maxWait =
+      lastUpdatedSource === 'agent' ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+    const now = Date.now();
+    // Keyed by documentName (see the map declaration) so afterUnloadDocument can
+    // clean it; the queue jobId stays page.id (computeHistoryJob) as required.
+    let burstStart = this.idleBurstStart.get(documentName);
+    if (burstStart === undefined || now - burstStart >= maxWait) {
+      burstStart = now;
+      this.idleBurstStart.set(documentName, burstStart);
+    }
+
     const { jobId, delay } = computeHistoryJob(
       page,
       lastUpdatedSource,
-      Date.now(),
+      burstStart,
+      now,
     );
 
+    // remove-then-add trailing-debounce idiom, and its ONE race. We delete the
+    // pending delayed job and re-add it under the same jobId so the timer resets
+    // to the trailing edge of the burst. The race is the small window between
+    // these two awaits: if the delayed job's `delay` elapses in that gap it goes
+    // ACTIVE, and then:
+    //   - remove() on an active/locked job is a no-op (BullMQ won't yank a job a
+    //     worker holds), and our `.catch(() => undefined)` swallows that too; and
+    //   - add() with a jobId that already exists (the now-active job's id) is
+    //     DROPPED by BullMQ — a duplicate add is a no-op.
+    // So this store fails to re-arm the trailing job: the just-fired snapshot
+    // captured content up to the moment it went active, and THIS edit is left
+    // without a pending trailing job. It is bounded and self-healing — the NEXT
+    // store re-arms a fresh delayed job (the id is free again once the active job
+    // completes / removeOnComplete frees it), and the processor's
+    // isDeepStrictEqual gate collapses any content-identical duplicate. The only
+    // uncovered case is when the racing store was the LAST in the session: the
+    // tail edits made after the job went active get NO trailing snapshot until
+    // the next edit re-arms one. That is an acceptable safety-net gap (a manual
+    // Save, a source-transition boundary, or simply the next edit all still cover
+    // it), which is why the reviewer accepts documenting it here rather than
+    // adding a post-add "did the add actually arm a job?" re-check.
+    //
+    // NOTE — do NOT "unify" this with the neighbouring embed-debounce idiom
+    // (aiQueue.add of PAGE_CONTENT_UPDATED above): that one uses a STABLE jobId
+    // and NO remove(), relying purely on BullMQ coalescing a repeated add under
+    // the same id, because a re-embed only needs to eventually run once on the
+    // latest content and re-anchoring its delay on every keystroke is undesirable.
+    // THIS idiom deliberately removes-then-adds precisely to PUSH the delay back
+    // to the trailing edge on every store (a true debounce), which coalescing
+    // alone cannot do. Collapsing them would silently change the history cadence.
+    await this.historyQueue.remove(jobId).catch(() => undefined);
+
     await this.historyQueue.add(
       QueueJob.PAGE_HISTORY,
-      { pageId: page.id } as IPageHistoryJob,
+      { pageId: page.id, kind: 'idle' } as IPageHistoryJob,
       { jobId, delay },
     );
   }

apps/server/src/collaboration/processors/history.processor.spec.ts

@@ -66,6 +66,15 @@ describe('HistoryProcessor.process', () => {
     notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
     generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
 
+    // #370 F3 — the processor now serializes its find+save under a page-row lock
+    // via executeTx. A db whose transaction().execute(fn) runs fn with a trx stub
+    // drives the real executeTx() helper without a database.
+    const db = {
+      transaction: () => ({
+        execute: (fn: (trx: any) => Promise<any>) => fn({ __trx: true }),
+      }),
+    };
+
     // WorkerHost's constructor reads `this.worker`; passing repos positionally
     // matches the constructor and avoids the Nest DI container.
     proc = new HistoryProcessor(
@@ -73,6 +82,7 @@ describe('HistoryProcessor.process', () => {
       pageRepo as any,
       collabHistory as any,
       watcherService as any,
+      db as any,
       notificationQueue as any,
       generalQueue as any,
     );
@@ -126,15 +136,26 @@ describe('HistoryProcessor.process', () => {
     await proc.process(buildJob());
 
     expect(collabHistory.popContributors).toHaveBeenCalledWith(PAGE_ID);
+    // #370 F3/F9 — the snapshot decision runs under a page-row lock. Pin the lock
+    // structurally so a refactor that drops withLock/trx (silently reintroducing
+    // the TOCTOU double-insert) turns this red. The tx stub is { __trx: true }.
+    expect(pageRepo.findById).toHaveBeenCalledWith(
+      PAGE_ID,
+      expect.objectContaining({ withLock: true, trx: { __trx: true } }),
+    );
+    // #370 F7 — addPageWatchers MUST receive the trx, or its FK-check runs on a
+    // separate connection and self-deadlocks against our FOR UPDATE. Asserting
+    // the trx arg here is exactly what would have caught that regression.
     expect(watcherService.addPageWatchers).toHaveBeenCalledWith(
       ['u1', 'u2'],
       PAGE_ID,
       SPACE_ID,
       WORKSPACE_ID,
+      { __trx: true },
     );
     expect(pageHistoryRepo.saveHistory).toHaveBeenCalledWith(
       expect.objectContaining({ id: PAGE_ID }),
-      { contributorIds: ['u1', 'u2'] },
+      { contributorIds: ['u1', 'u2'], kind: 'idle', trx: { __trx: true } },
     );
     expect(generalQueue.add).toHaveBeenCalledWith(
       QueueJob.PAGE_BACKLINKS,
@@ -186,6 +207,48 @@ describe('HistoryProcessor.process', () => {
     ]);
   });
 
+  it('COMMIT failure (throw outside the tx callback) → contributors RESTORED', async () => {
+    // #370 F8 — a commit-time failure throws OUTSIDE the callback, so the inner
+    // try/catch does not run; the outer catch must restore the popped set (else a
+    // BullMQ retry writes an unattributed version). Use a db whose execute() runs
+    // the callback THEN throws, simulating a commit abort.
+    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+      content: { type: 'doc', content: [] },
+    });
+    const commitFail = {
+      transaction: () => ({
+        execute: async (fn: (trx: any) => Promise<any>) => {
+          await fn({ __trx: true }); // callback succeeds (saveHistory ok)
+          throw new Error('commit aborted'); // ...but the COMMIT fails
+        },
+      }),
+    };
+    const procCommitFail = new HistoryProcessor(
+      pageHistoryRepo as any,
+      pageRepo as any,
+      collabHistory as any,
+      watcherService as any,
+      commitFail as any,
+      notificationQueue as any,
+      generalQueue as any,
+    );
+    jest
+      .spyOn(procCommitFail['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    await expect(procCommitFail.process(buildJob())).rejects.toThrow(
+      'commit aborted',
+    );
+    // The inner catch did NOT run (save succeeded), so only the outer catch can
+    // restore — assert it did.
+    expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+      'u1',
+      'u2',
+    ]);
+    // And the post-snapshot queue work must NOT have run (we rethrew).
+    expect(generalQueue.add).not.toHaveBeenCalled();
+  });
+
   it('backlinks + notification queue failures are swallowed (history still committed)', async () => {
     pageHistoryRepo.findPageLastHistory.mockResolvedValue({
       content: { type: 'doc', content: [] },

apps/server/src/collaboration/processors/history.processor.ts

@@ -19,6 +19,9 @@ import { isDeepStrictEqual } from 'node:util';
 import { CollabHistoryService } from '../services/collab-history.service';
 import { WatcherService } from '../../core/watcher/watcher.service';
 import { isEmptyParagraphDoc } from '../collaboration.util';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';
 
 @Processor(QueueName.HISTORY_QUEUE)
 export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
@@ -29,6 +32,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
     private readonly pageRepo: PageRepo,
     private readonly collabHistory: CollabHistoryService,
     private readonly watcherService: WatcherService,
+    @InjectKysely() private readonly db: KyselyDB,
     @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
     @InjectQueue(QueueName.GENERAL_QUEUE) private generalQueue: Queue,
   ) {
@@ -41,6 +45,9 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
     try {
       const { pageId } = job.data;
 
+      // Read the page WITHOUT a lock first, only to bail early on the two cheap
+      // no-write cases (page gone / empty first snapshot) without opening a
+      // transaction. The authoritative check-then-write happens locked below.
       const page = await this.pageRepo.findById(pageId, {
         includeContent: true,
       });
@@ -51,40 +58,109 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
         return;
       }
 
-      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
-        pageId,
-        { includeContent: true },
-      );
+      // #370 F3 — the snapshot decision (findPageLastHistory → saveHistory) must
+      // be serialized against manual-save/boundary writers, which run under a
+      // page-row lock in onStoreDocument. Without it, this processor and a
+      // concurrent manual-save each read the same lastHistory (MVCC), both see
+      // content != lastHistory, and both insert — producing two page_history rows
+      // with IDENTICAL content (one 'idle', one 'manual'), defeating
+      // promote-not-dup and the version-vs-autosave split. Taking the same
+      // page-row lock makes the second writer observe the first's committed row so
+      // the isDeepStrictEqual gate collapses the duplicate. Only the read+write
+      // is transacted; the post-snapshot queue work stays outside.
+      let contributorIds: string[] = [];
+      let snapshotWritten = false;
+      let lastHistoryContent: unknown;
+      // #370 F8 — the contributor set popped from Redis (destructive SPOP) must be
+      // restored if the snapshot does not durably land. The inner try/catch only
+      // covers a throw INSIDE the callback; a COMMIT failure (connection drop,
+      // serialization/deadlock abort on commit — the transient class the epic
+      // already retries) throws OUTSIDE it, rolling the snapshot back while the
+      // pop is already gone. We track the popped set here and restore it in the
+      // outer catch so a BullMQ retry re-attributes the version. addContributors
+      // is an idempotent Redis SADD, so a double-restore is harmless.
+      let poppedForRestore: string[] = [];
 
-      if (!lastHistory && isEmptyParagraphDoc(page.content as any)) {
-        this.logger.debug(
-          `Skipping first history for page ${pageId}: empty content`,
-        );
-        await this.collabHistory.clearContributors(pageId);
+      try {
+        await executeTx(this.db, async (trx) => {
+          const lockedPage = await this.pageRepo.findById(pageId, {
+            includeContent: true,
+            withLock: true,
+            trx,
+          });
+          if (!lockedPage) return;
+
+          const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+            pageId,
+            { includeContent: true, trx },
+          );
+          lastHistoryContent = lastHistory?.content;
+
+          if (!lastHistory && isEmptyParagraphDoc(lockedPage.content as any)) {
+            this.logger.debug(
+              `Skipping first history for page ${pageId}: empty content`,
+            );
+            return;
+          }
+
+          if (
+            lastHistory &&
+            isDeepStrictEqual(lastHistory.content, lockedPage.content)
+          ) {
+            return; // already snapshotted at this content — nothing to write
+          }
+
+          contributorIds = await this.collabHistory.popContributors(pageId);
+          poppedForRestore = contributorIds;
+          try {
+            // Pass `trx` so the watcher insert's FK check (FOR KEY SHARE on
+            // pages[pageId]) runs on the SAME connection that already holds the
+            // FOR UPDATE lock from findById — otherwise it takes the FK lock on a
+            // separate pool connection and self-deadlocks against our own tx.
+            await this.watcherService.addPageWatchers(
+              contributorIds,
+              pageId,
+              lockedPage.spaceId,
+              lockedPage.workspaceId,
+              trx,
+            );
+
+            // #370 — every job on this queue is a trailing idle-flush autosnapshot.
+            await this.pageHistoryRepo.saveHistory(lockedPage, {
+              contributorIds,
+              kind: job.data.kind ?? 'idle',
+              trx,
+            });
+            snapshotWritten = true;
+            this.logger.debug(`History created for page: ${pageId}`);
+          } catch (err) {
+            await this.collabHistory.addContributors(pageId, contributorIds);
+            poppedForRestore = [];
+            throw err;
+          }
+        });
+      } catch (err) {
+        // A throw here means the tx did NOT commit (callback threw, or the commit
+        // itself failed and rolled back). If we popped contributors and the inner
+        // catch did not already restore them, restore now so the retry keeps
+        // attribution. snapshotWritten is irrelevant: it is set before commit, so
+        // it can be true even when the commit rolled the snapshot back.
+        if (poppedForRestore.length) {
+          await this.collabHistory.addContributors(pageId, poppedForRestore);
+        }
+        throw err;
+      }
+
+      // No snapshot written (page vanished / empty-first / unchanged content) →
+      // clear the contributor set for the skip cases and stop.
+      if (!snapshotWritten) {
+        if (!lastHistoryContent && isEmptyParagraphDoc(page.content as any)) {
+          await this.collabHistory.clearContributors(pageId);
+        }
         return;
       }
 
-      if (
-        !lastHistory ||
-        !isDeepStrictEqual(lastHistory.content, page.content)
-      ) {
-        const contributorIds = await this.collabHistory.popContributors(pageId);
-
-        try {
-          await this.watcherService.addPageWatchers(
-            contributorIds,
-            pageId,
-            page.spaceId,
-            page.workspaceId,
-          );
-
-          await this.pageHistoryRepo.saveHistory(page, { contributorIds });
-          this.logger.debug(`History created for page: ${pageId}`);
-        } catch (err) {
-          await this.collabHistory.addContributors(pageId, contributorIds);
-          throw err;
-        }
-
+      {
         const mentions = extractMentions(page.content);
         const pageMentions = extractPageMentions(mentions);
         const internalLinkSlugIds = extractInternalLinkSlugIds(page.content);
@@ -102,7 +178,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
             );
           });
 
-        if (contributorIds.length > 0 && lastHistory?.content) {
+        if (contributorIds.length > 0 && lastHistoryContent) {
           await this.notificationQueue
             .add(QueueJob.PAGE_UPDATED, {
               pageId,

apps/server/src/database/migrations/20260707T120000-page-history-kind.ts

@@ -0,0 +1,27 @@
+import { type Kysely } from 'kysely';
+
+/**
+ * #370 — page-versioning intentionality tier on a history snapshot.
+ *
+ * Adds `page_history.kind`, the three-tier "how intentional was this snapshot"
+ * marker that lets versions (intentional points) be told apart from autosaves:
+ *   - 'manual'   — a human explicitly saved a version (Cmd+S / Save button)
+ *   - 'agent'    — the AI agent explicitly saved a version
+ *   - 'idle'     — trailing idle-flush autosnapshot (safety net)
+ *   - 'boundary' — autosnapshot pinned on a source transition (user↔agent↔git)
+ *
+ * Nullable with NO default (mirrors last_updated_source in the agent-provenance
+ * migration): legacy rows predate the marker and read back as `null`, which the
+ * client renders as a plain autosave. Stored as a short varchar to stay
+ * forward-compatible without an enum migration.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('page_history')
+    .addColumn('kind', 'varchar(20)', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.alterTable('page_history').dropColumn('kind').execute();
+}

apps/server/src/database/repos/page/page-history.repo.ts

@@ -13,6 +13,7 @@ import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB } from '@docmost/db/types/db';
 import { resolveAgentProvenance } from '../agent-provenance';
+import { PageHistoryKind } from '../../../collaboration/constants';
 
 /**
  * Role-resolution subquery for a page-history row's bound AI chat (#300). Joins
@@ -46,6 +47,9 @@ export class PageHistoryRepo {
     'lastUpdatedById',
     'lastUpdatedSource',
     'lastUpdatedAiChatId',
+    // #370 — intentionality tier ('manual' | 'agent' | 'idle' | 'boundary');
+    // null on legacy rows (= autosave). Selected so callers can read/promote it.
+    'kind',
     'contributorIds',
     'spaceId',
     'workspaceId',
@@ -85,9 +89,15 @@ export class PageHistoryRepo {
 
   async saveHistory(
     page: Page,
-    opts?: { contributorIds?: string[]; trx?: KyselyTransaction },
-  ): Promise<void> {
-    await this.insertPageHistory(
+    opts?: {
+      contributorIds?: string[];
+      // #370 — intentionality tier for this snapshot. Omitted → null (legacy
+      // autosave semantics). Callers derive it server-side, never from a client.
+      kind?: PageHistoryKind;
+      trx?: KyselyTransaction;
+    },
+  ): Promise<PageHistory> {
+    return await this.insertPageHistory(
       {
         pageId: page.id,
         slugId: page.slugId,
@@ -99,6 +109,7 @@ export class PageHistoryRepo {
         // Copy the provenance marker off the page row, as for lastUpdatedById.
         lastUpdatedSource: page.lastUpdatedSource,
         lastUpdatedAiChatId: page.lastUpdatedAiChatId,
+        kind: opts?.kind ?? null,
         contributorIds: opts?.contributorIds,
         spaceId: page.spaceId,
         workspaceId: page.workspaceId,
@@ -107,6 +118,25 @@ export class PageHistoryRepo {
     );
   }
 
+  /**
+   * #370 — promote an existing snapshot's intentionality tier in place. Used by
+   * the manual-save "promote-not-dup" path: when the latest history row already
+   * holds the exact content being versioned, we upgrade its `kind` instead of
+   * duplicating a heavy content row.
+   */
+  async updateHistoryKind(
+    pageHistoryId: string,
+    kind: PageHistoryKind,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .updateTable('pageHistory')
+      .set({ kind })
+      .where('id', '=', pageHistoryId)
+      .execute();
+  }
+
   async findPageHistoryByPageId(pageId: string, pagination: PaginationOptions) {
     const query = this.db
       .selectFrom('pageHistory')

apps/server/src/database/types/db.d.ts

@@ -280,6 +280,7 @@ export interface PageHistory {
   createdAt: Generated<Timestamp>;
   icon: string | null;
   id: Generated<string>;
+  kind: string | null;
   lastUpdatedAiChatId: string | null;
   lastUpdatedById: string | null;
   lastUpdatedSource: string | null;

apps/server/src/integrations/queue/constants/queue.interface.ts

@@ -20,6 +20,10 @@ export interface IStripeSeatsSyncJob {
 
 export interface IPageHistoryJob {
   pageId: string;
+  // #370 — intentionality tier the worker stamps on the snapshot. All jobs on
+  // this queue are trailing idle-flush autosnapshots, so this is 'idle' (absent
+  // → treated as 'idle' by the processor).
+  kind?: 'idle';
 }
 
 /**