@twinsearth/w2m-dsh-plugin 1.3.1 → 1.3.11

package/src/relay/blob-sessions.mjs

@@ -0,0 +1,148 @@
+/**
+ * Chunked blob sessions (M6, v1.3.10-beta.19 slice).
+ *
+ * The current blob endpoint is one PUT with a frame cap: an interrupted upload loses everything, and a large patch cannot be
+ * sent at all. A blob session fixes both: the client declares the final sha256 and size once, uploads chunks in any order (each
+ * PUT is idempotent), asks what is missing, and commits. Only a commit whose assembled bytes hash to the declared sha256 creates
+ * a blob; anything else leaves no artifact behind.
+ *
+ * The store is injected as a set of in-memory sessions here; the relay binds it to its blob store in the wiring slice.
+ */
+import { createHash } from 'node:crypto';
+
+export const CHUNK_LIMITS = Object.freeze({
+  defaultChunkBytes: 1024 * 1024,
+  maxChunkBytes: 8 * 1024 * 1024,
+  maxChunks: 256,
+  maxBlobBytes: 64 * 1024 * 1024,
+  maxSessionsPerMachine: 2,
+  maxUnfinishedBytesPerMachine: 512 * 1024 * 1024,
+  ttlMs: 24 * 60 * 60 * 1000,
+});
+
+export class BlobSessionError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'BlobSessionError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const sha256Hex = (buffer) => createHash('sha256').update(buffer).digest('hex');
+
+export function createBlobSessions({ now = () => Date.now(), limits = CHUNK_LIMITS, onCommit = null } = {}) {
+  const sessions = new Map();
+  let counter = 0;
+
+  const purgeExpired = () => {
+    const at = now();
+    for (const session of [...sessions.values()]) if (session.expires_at_ms <= at) sessions.delete(session.session_id);
+  };
+
+  const requireSession = (sessionId) => {
+    purgeExpired();
+    const session = sessions.get(sessionId);
+    if (session === undefined) throw new BlobSessionError('SESSION_NOT_FOUND', 'session missing or expired', { session_id: sessionId });
+    return session;
+  };
+
+  const describe = (session) => {
+    const received = [...session.chunks.keys()].sort((a, b) => a - b);
+    const missing = [];
+    for (let index = 0; index < session.chunks_total; index += 1) if (!session.chunks.has(index)) missing.push(index);
+    return {
+      session_id: session.session_id,
+      sha256: session.sha256,
+      size: session.size,
+      chunk_bytes: session.chunk_bytes,
+      chunks: session.chunks_total,
+      received,
+      missing,
+      expires_at: new Date(session.expires_at_ms).toISOString(),
+      completed: session.state === 'committed',
+    };
+  };
+
+  return {
+    create({ machineId, sha256, size, chunkBytes = limits.defaultChunkBytes }) {
+      if (typeof machineId !== 'string' || machineId === '') throw new BlobSessionError('INVALID_MACHINE', 'machine_id is required');
+      if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(sha256)) throw new BlobSessionError('INVALID_SHA', 'sha256 must be 64 lowercase hex characters');
+      if (!Number.isInteger(size) || size <= 0) throw new BlobSessionError('INVALID_SIZE', 'size must be a positive integer');
+      if (size > limits.maxBlobBytes) throw new BlobSessionError('BLOB_TOO_LARGE', 'blob exceeds the configured maximum', { size, max_bytes: limits.maxBlobBytes });
+      if (!Number.isInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > limits.maxChunkBytes) throw new BlobSessionError('INVALID_CHUNK_BYTES', 'chunk_bytes out of range', { chunk_bytes: chunkBytes, max: limits.maxChunkBytes });
+      const chunksTotal = Math.ceil(size / chunkBytes);
+      if (chunksTotal > limits.maxChunks) throw new BlobSessionError('CHUNK_TOO_LARGE', 'too many chunks for one blob', { chunks: chunksTotal, max: limits.maxChunks });
+      purgeExpired();
+      const mine = [...sessions.values()].filter((session) => session.machine_id === machineId);
+      if (mine.length >= limits.maxSessionsPerMachine) {
+        throw new BlobSessionError('BLOB_QUOTA', 'too many open sessions for this machine', { open: mine.length, max: limits.maxSessionsPerMachine });
+      }
+      const unfinishedBytes = mine.reduce((sum, session) => sum + session.size, 0);
+      if (unfinishedBytes + size > limits.maxUnfinishedBytesPerMachine) {
+        throw new BlobSessionError('BLOB_QUOTA', 'unfinished session bytes exceed the machine allowance', { unfinished_bytes: unfinishedBytes, size, max_bytes: limits.maxUnfinishedBytesPerMachine });
+      }
+      counter += 1;
+      const session = {
+        session_id: 'bs-' + String(counter).padStart(6, '0'),
+        machine_id: machineId,
+        sha256,
+        size,
+        chunk_bytes: chunkBytes,
+        chunks_total: chunksTotal,
+        chunks: new Map(),
+        state: 'open',
+        created_at: new Date(now()).toISOString(),
+        expires_at_ms: now() + limits.ttlMs,
+      };
+      sessions.set(session.session_id, session);
+      return { ok: true, session: describe(session) };
+    },
+    /** Upload one chunk; re-uploading an index is an overwrite, and order does not matter. */
+    putChunk({ sessionId, index, data }) {
+      const session = requireSession(sessionId);
+      if (session.state === 'committed') throw new BlobSessionError('SESSION_COMMITTED', 'session already committed', { session_id: sessionId });
+      if (!Number.isInteger(index) || index < 0 || index >= session.chunks_total) {
+        throw new BlobSessionError('INVALID_CHUNK_INDEX', 'chunk index out of range', { index, chunks: session.chunks_total });
+      }
+      const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data ?? []);
+      if (buffer.length === 0) throw new BlobSessionError('INVALID_CHUNK', 'chunk is empty', { index });
+      if (buffer.length > session.chunk_bytes) throw new BlobSessionError('CHUNK_TOO_LARGE', 'chunk exceeds chunk_bytes', { index, bytes: buffer.length, chunk_bytes: session.chunk_bytes });
+      const isLast = index === session.chunks_total - 1;
+      const expected = isLast ? session.size - session.chunk_bytes * (session.chunks_total - 1) : session.chunk_bytes;
+      if (buffer.length !== expected) throw new BlobSessionError('INVALID_CHUNK', 'chunk length does not match the declared size', { index, bytes: buffer.length, expected });
+      session.chunks.set(index, buffer);
+      return { ok: true, session: describe(session) };
+    },
+    status({ sessionId }) {
+      return { ok: true, session: describe(requireSession(sessionId)) };
+    },
+    /** Commit only if every chunk arrived and the assembled sha256 equals the declared one. */
+    commit({ sessionId }) {
+      const session = requireSession(sessionId);
+      if (session.state === 'committed') throw new BlobSessionError('SESSION_COMMITTED', 'session already committed', { session_id: sessionId });
+      const detail = describe(session);
+      if (detail.missing.length > 0) {
+        return { ok: false, code: 'BLOB_INCOMPLETE', missing: detail.missing, session_id: sessionId };
+      }
+      const ordered = [];
+      for (let index = 0; index < session.chunks_total; index += 1) ordered.push(session.chunks.get(index));
+      const assembled = Buffer.concat(ordered);
+      if (assembled.length !== session.size) return { ok: false, code: 'BLOB_SIZE_MISMATCH', size: assembled.length, expected: session.size };
+      const actual = sha256Hex(assembled);
+      if (actual !== session.sha256) {
+        sessions.delete(sessionId);
+        return { ok: false, code: 'BLOB_SHA_MISMATCH', expected: session.sha256, actual };
+      }
+      session.state = 'committed';
+      session.chunks.clear();
+      sessions.delete(sessionId);
+      if (typeof onCommit === 'function') onCommit({ machineId: session.machine_id, sha256: session.sha256, size: session.size, bytes: assembled });
+      return { ok: true, sha256: session.sha256, bytes: assembled.length };
+    },
+    size() {
+      purgeExpired();
+      return { open_sessions: sessions.size };
+    },
+  };
+}

package/src/relay/merge-queue.mjs

@@ -0,0 +1,137 @@
+/**
+ * Merge queue (M3, v1.3.10-beta.7 slice).
+ *
+ * Every project+branch has one queue and at most one holder of its merge slot. The queue accepts a patch relative to a
+ * declared base and either advances the branch head, reports that the patch is already merged, refuses a stale base, or
+ * reports a structured conflict. It never force-pushes and never advances the head on a conflict.
+ *
+ * Policy is a project setting:
+ *   strict  base_commit must equal the current head; anything else is BASE_MISMATCH and the submitter rebases.
+ *   replay  the patch is applied with --3way onto the current head; if it applies, it merges, otherwise MERGE_CONFLICT.
+ *
+ * Git access is injected so the tests can drive real repositories without a network or a daemon.
+ */
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+export const MERGE_POLICIES = Object.freeze(['strict', 'replay']);
+
+export function defaultGit() {
+  return (args, cwd) => new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, timeout: 120_000, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) reject(Object.assign(new Error(String(stderr || error.message).trim()), { stdout, stderr }));
+      else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+export function patchSha(patch) {
+  return createHash('sha256').update(String(patch), 'utf8').digest('hex');
+}
+
+export function changedFiles(patch) {
+  const files = new Set();
+  for (const line of String(patch).split('\n')) {
+    const match = /^diff --git a\/(.+?) b\/(.+)$/.exec(line.trim());
+    if (match) files.add(match[2]);
+  }
+  return [...files].sort();
+}
+
+export function createMergeQueue({ policy = 'strict', slotTtlMs = 10 * 60 * 1000, now = () => Date.now() } = {}) {
+  if (!MERGE_POLICIES.includes(policy)) throw new Error('unknown merge policy: ' + policy);
+  const items = new Map();
+  const merged = new Map(); // patchSha + '|' + branch -> { headCommit, queue_id }
+  let slot = null;
+  let seq = 0;
+
+  const queueKey = (sha, branch) => sha + '|' + branch;
+
+  return {
+    policy,
+    enqueue({ patch, baseCommit, branch = 'main', sourceTaskId = null }) {
+      const sha = patchSha(patch);
+      if (merged.has(queueKey(sha, branch))) {
+        return { ok: true, alreadyMerged: true, queueId: merged.get(queueKey(sha, branch)).queue_id, headCommit: merged.get(queueKey(sha, branch)).headCommit };
+      }
+      seq += 1;
+      const item = { queueId: 'mq-' + String(seq).padStart(6, '0'), patchSha: sha, patch, baseCommit, branch, sourceTaskId, state: 'queued', createdAt: now() };
+      items.set(item.queueId, item);
+      return { ok: true, alreadyMerged: false, item };
+    },
+    claim(holder) {
+      const current = now();
+      if (slot !== null && slot.expiresAt > current) return { ok: false, code: 'MERGE_SLOT_BUSY', holder: slot.holder, expiresAt: slot.expiresAt };
+      slot = { holder, expiresAt: current + slotTtlMs, claimedAt: current };
+      return { ok: true, holder };
+    },
+    release(holder) {
+      if (slot === null || slot.holder !== holder) return { ok: false, code: 'MERGE_SLOT_NOT_OWNER' };
+      slot = null;
+      return { ok: true };
+    },
+    next() {
+      for (const item of items.values()) if (item.state === 'queued') return item;
+      return null;
+    },
+    finish(queueId, state) {
+      const item = items.get(queueId);
+      if (!item) return { ok: false, code: 'ITEM_NOT_FOUND' };
+      item.state = state;
+      item.finishedAt = now();
+      return { ok: true, item };
+    },
+    status() {
+      return { policy, slot, items: [...items.values()], mergedCount: merged.size };
+    },
+    /**
+     * Apply one item to a repository checked out at headCommit. Returns a terminal verdict, never an exception.
+     */
+    async apply({ item, queueId, repoDir, headCommit, git = defaultGit() }) {
+      const target = item ?? items.get(queueId);
+      if (!target) return { ok: false, code: 'ITEM_NOT_FOUND' };
+      if (target.state !== 'queued') return { ok: false, code: 'ITEM_NOT_QUEUED', state: target.state };
+      if (policy === 'strict' && target.baseCommit !== headCommit) {
+        this.finish(target.queueId, 'failed');
+        return { ok: false, code: 'BASE_MISMATCH', baseCommit: target.baseCommit, headCommit };
+      }
+      const worktree = mkdtempSync(join(tmpdir(), 'w2m-merge-'));
+      try {
+        await git(['worktree', 'add', '--detach', worktree, headCommit], repoDir);
+        try {
+          const patchFile = join(worktree, '.w2m-merge.patch');
+          writeFileSync(patchFile, target.patch, 'utf8');
+          await git(['apply', '--3way', '--whitespace=nowarn', patchFile], worktree);
+        } catch (error) {
+          this.finish(target.queueId, 'conflict');
+          // The conflict itself is evidence, not just a failure: capture the file state git left behind (conflict markers
+          // included) so a reviewer can see exactly what clashed, and the head can stay where it was.
+          let conflictArtifact = null;
+          try {
+            const diff = await git(['diff'], worktree);
+            const text = diff.stdout;
+            if (typeof text === 'string' && text.trim() !== '') {
+              conflictArtifact = { sha256: patchSha(text), bytes: Buffer.byteLength(text, 'utf8'), text: text.slice(0, 64 * 1024) };
+            }
+          } catch { /* the diff is evidence, not a precondition for reporting the conflict */ }
+          return { ok: false, code: 'MERGE_CONFLICT', files: changedFiles(target.patch), detail: String(error?.message ?? error).split('\n').slice(0, 6), conflictArtifact, baseCommit: target.baseCommit, headCommit };
+        }
+        await git(['add', '--all'], worktree);
+        await git(['-c', 'user.name=w2m-merge', '-c', 'user.email=merge@w2m.invalid', 'commit', '-m', 'merge: ' + target.queueId], worktree);
+        const newHead = (await git(['rev-parse', 'HEAD'], worktree)).stdout.trim();
+        // The commit was made in a detached worktree; the branch must actually advance, and the repository working tree
+        // must follow it, or the next merge would start from a head that no longer matches what was reviewed.
+        await git(['reset', '--hard', newHead], repoDir);
+        this.finish(target.queueId, 'merged');
+        merged.set(queueKey(target.patchSha, target.branch), { headCommit: newHead, queue_id: target.queueId });
+        return { ok: true, code: 'MERGED', headCommit: newHead, queueId: target.queueId, files: changedFiles(target.patch) };
+      } finally {
+        try { await git(['worktree', 'remove', '--force', worktree], repoDir); } catch { /* removal is best effort */ }
+        try { rmSync(worktree, { recursive: true, force: true }); } catch { /* see above */ }
+      }
+    },
+  };
+}

package/src/relay/project-locks.mjs

@@ -0,0 +1,179 @@
+/**
+ * Project locks (M5, v1.3.10-beta.15 slice).
+ *
+ * Two coordination primitives, one module: an exclusive branch lock and an exclusive file lock. They exist so two clients
+ * disagree about *who is editing what* before they disagree about merge conflicts, and so a crashed client's claim expires
+ * instead of blocking the project forever.
+ *
+ * Rules (docs/COLLAB/M5-MULTI-CLIENT-PRIMITIVES.md §2):
+ *  - one exclusive holder per (project, branch) or (project, path);
+ *  - a lock has a lease and is renewed by its holder; an expired lock does not block a newcomer (it is released as it is taken,
+ *    and both the expiry and the new acquisition are events);
+ *  - nobody steals a live lock; the owner may force-release with a reason, which is also an event;
+ *  - every mutation is recorded as an event for the project room to append.
+ *
+ * This module holds no relay state of its own; state is injected so it can be tested and replayed.
+ */
+export const LOCK_KINDS = Object.freeze(['branch', 'file']);
+export const DEFAULT_LOCK_LEASE_MS = 30 * 60 * 1000;
+export const DEFAULT_LOCK_LIMITS = Object.freeze({ perProject: 20, perHolder: 10 });
+
+export class LockError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'LockError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const holderKey = (holder) => holder.kind + ':' + holder.id;
+
+export function createProjectLocks({ now = () => Date.now(), defaultLeaseMs = DEFAULT_LOCK_LEASE_MS, limits = DEFAULT_LOCK_LIMITS, onEvent = null } = {}) {
+  const locks = new Map(); // lock_id -> lock
+  let counter = 0;
+  let seq = 0;
+
+  const emit = (type, payload) => {
+    seq += 1;
+    const event = { seq, type, at: new Date(now()).toISOString(), payload };
+    if (typeof onEvent === 'function') onEvent(event);
+    return event;
+  };
+
+  const targetKey = (projectId, kind, target) => projectId + '|' + kind + '|' + (kind === 'branch' ? target.branch : target.path);
+
+  /** Expire every lock whose lease ran out, recording one event each. Called lazily by every operation. */
+  const expireDue = () => {
+    const expired = [];
+    for (const lock of locks.values()) {
+      if (lock.state === 'held' && lock.expires_at_ms <= now()) {
+        lock.state = 'expired';
+        expired.push(lock);
+        emit('lock.expired', { lock_id: lock.lock_id, project_id: lock.project_id, kind: lock.kind, target: lock.target, holder: lock.holder });
+      }
+    }
+    return expired;
+  };
+
+  const describe = (lock) => ({
+    lock_id: lock.lock_id,
+    project_id: lock.project_id,
+    kind: lock.kind,
+    target: lock.target,
+    mode: 'exclusive',
+    holder: lock.holder,
+    reason: lock.reason,
+    acquired_at: lock.acquired_at,
+    expires_at: lock.expires_at,
+    lease_ms: lock.lease_ms,
+    renewed_at: lock.renewed_at,
+    state: lock.state,
+  });
+
+  return {
+    /** Acquire an exclusive lock. An expired lock on the same target does not block the newcomer. */
+    acquire({ projectId, kind, target, holder, reason = null, leaseMs = defaultLeaseMs }) {
+      if (typeof projectId !== 'string' || projectId === '') throw new LockError('INVALID_PROJECT', 'project_id is required');
+      if (!LOCK_KINDS.includes(kind)) throw new LockError('INVALID_LOCK_KIND', 'kind must be branch or file', { kind });
+      if (!target || typeof target !== 'object') throw new LockError('INVALID_TARGET', 'target is required', { kind });
+      if (kind === 'branch' && (typeof target.branch !== 'string' || target.branch === '')) throw new LockError('INVALID_TARGET', 'a branch lock needs target.branch', { target });
+      if (kind === 'file' && (typeof target.path !== 'string' || target.path === '')) throw new LockError('INVALID_TARGET', 'a file lock needs target.path', { target });
+      if (!holder || typeof holder.kind !== 'string' || typeof holder.id !== 'string' || holder.id === '') throw new LockError('INVALID_HOLDER', 'holder needs kind and id');
+      if (!Number.isFinite(leaseMs) || leaseMs <= 0) throw new LockError('INVALID_LEASE', 'lease_ms must be positive', { lease_ms: leaseMs });
+      expireDue();
+      const key = targetKey(projectId, kind, target);
+      const existing = [...locks.values()].find((lock) => lock.state === 'held' && targetKey(lock.projectId, lock.kind, lock.target) === key);
+      if (existing !== undefined) {
+        return { ok: false, code: 'LOCK_HELD', holder: existing.holder, lock_id: existing.lock_id, expires_at: existing.expires_at };
+      }
+      const current = [...locks.values()].filter((lock) => lock.state === 'held' && lock.projectId === projectId);
+      if (current.length >= limits.perProject) return { ok: false, code: 'LOCK_LIMIT', limit: limits.perProject, scope: 'project' };
+      const mine = current.filter((lock) => holderKey(lock.holder) === holderKey(holder));
+      if (mine.length >= limits.perHolder) return { ok: false, code: 'LOCK_LIMIT', limit: limits.perHolder, scope: 'holder' };
+      counter += 1;
+      const acquired = now();
+      const lock = {
+        lock_id: 'lk-' + String(counter).padStart(6, '0'),
+        projectId,
+        kind,
+        target: kind === 'branch' ? { branch: target.branch } : { path: target.path },
+        holder: { kind: holder.kind, id: holder.id },
+        reason,
+        lease_ms: leaseMs,
+        acquired_at: new Date(acquired).toISOString(),
+        expires_at: new Date(acquired + leaseMs).toISOString(),
+        expires_at_ms: acquired + leaseMs,
+        renewed_at: null,
+        state: 'held',
+      };
+      locks.set(lock.lock_id, lock);
+      emit('lock.acquired', { lock_id: lock.lock_id, project_id: projectId, kind, target: lock.target, holder: lock.holder, reason, lease_ms: leaseMs });
+      return { ok: true, lock: describe(lock) };
+    },
+    /** Renew a lock you hold. Never extends a lock someone else holds, and an expired lock cannot be revived. */
+    renew({ projectId, lockId, holder, leaseMs = defaultLeaseMs }) {
+      expireDue();
+      const lock = locks.get(lockId);
+      if (lock === undefined) return { ok: false, code: 'LOCK_NOT_FOUND', lock_id: lockId };
+      if (lock.project_id !== undefined) { /* set below */ }
+      if (lock.projectId !== projectId) return { ok: false, code: 'LOCK_NOT_FOUND', lock_id: lockId };
+      if (lock.state === 'expired') return { ok: false, code: 'LOCK_EXPIRED', lock_id: lockId };
+      if (holderKey(lock.holder) !== holderKey(holder)) return { ok: false, code: 'LOCK_NOT_OWNER', holder: lock.holder };
+      const renewedAt = now();
+      lock.lease_ms = leaseMs;
+      lock.expires_at_ms = renewedAt + leaseMs;
+      lock.expires_at = new Date(lock.expires_at_ms).toISOString();
+      lock.renewed_at = new Date(renewedAt).toISOString();
+      emit('lock.renewed', { lock_id: lock.lock_id, project_id: projectId, holder: lock.holder, expires_at: lock.expires_at });
+      return { ok: true, lock: describe(lock) };
+    },
+    /** Release your own lock. */
+    release({ projectId, lockId, holder }) {
+      expireDue();
+      const lock = locks.get(lockId);
+      if (lock === undefined || lock.projectId !== projectId) return { ok: false, code: 'LOCK_NOT_FOUND', lock_id: lockId };
+      if (lock.state === 'expired') return { ok: false, code: 'LOCK_EXPIRED', lock_id: lockId };
+      if (holderKey(lock.holder) !== holderKey(holder)) return { ok: false, code: 'LOCK_NOT_OWNER', holder: lock.holder };
+      lock.state = 'released';
+      emit('lock.released', { lock_id: lock.lock_id, project_id: projectId, holder: lock.holder });
+      return { ok: true };
+    },
+    /** Owner-only force release; a reason is mandatory and is recorded with the decision. */
+    forceRelease({ projectId, lockId, actor, actorRole, reason }) {
+      expireDue();
+      const lock = locks.get(lockId);
+      if (lock === undefined || lock.projectId !== projectId) return { ok: false, code: 'LOCK_NOT_FOUND', lock_id: lockId };
+      if (actorRole !== 'owner') return { ok: false, code: 'LOCK_FORCE_DENIED', required_role: 'owner', actor_role: actorRole };
+      if (typeof reason !== 'string' || reason.trim() === '') return { ok: false, code: 'LOCK_FORCE_DENIED', required: 'reason' };
+      const wasHolder = { ...lock.holder };
+      lock.state = 'force_released';
+      emit('lock.force_released', { lock_id: lock.lock_id, project_id: projectId, holder: wasHolder, actor, reason: reason.trim() });
+      return { ok: true, previous_holder: wasHolder };
+    },
+    /** Locks a reader should show for a project (live ones only; expired ones are history). */
+    list({ projectId }) {
+      expireDue();
+      return [...locks.values()]
+        .filter((lock) => lock.projectId === projectId && lock.state === 'held')
+        .map((lock) => describe(lock));
+    },
+    /** Would a write to this branch / these paths collide with someone else's claim? Used by the merge preflight (§2.3). */
+    conflicts({ projectId, branch = null, paths = [] }) {
+      expireDue();
+      const result = [];
+      for (const lock of locks.values()) {
+        if (lock.projectId !== projectId || lock.state !== 'held') continue;
+        const branchHit = branch !== null && lock.kind === 'branch' && lock.target.branch === branch;
+        const pathHit = lock.kind === 'file' && paths.includes(lock.target.path);
+        if (branchHit || pathHit) result.push({ lock_id: lock.lock_id, kind: lock.kind, target: lock.target, holder: lock.holder, expires_at: lock.expires_at });
+      }
+      return result;
+    },
+    expiresAt({ lockId }) {
+      const lock = locks.get(lockId);
+      return lock === undefined ? null : lock.expires_at;
+    },
+    size() { return { held: [...locks.values()].filter((lock) => lock.state === 'held').length, recorded: locks.size, events: seq }; },
+  };
+}

package/src/relay/project-notifications.mjs

@@ -0,0 +1,182 @@
+/**
+ * Project notifications (M5, v1.3.10-beta.17 slice).
+ *
+ * Notifications answer "what happened while I was away" without a websocket: every one is an event on the project stream
+ * (live) and a row returned by the list route (catch-up), and each reader has a watermark rather than per-row read flags.
+ *
+ * Rules (docs/COLLAB/M5-MULTI-CLIENT-PRIMITIVES.md §4):
+ *  - a notification is (project, kind, target, subject, refs, requires_action), addressed to a member or broadcast;
+ *  - the same (kind, primary ref, target) inside 60s is one notification, not two;
+ *  - more than 120 in a minute for one project collapses into a digest row carrying the count;
+ *  - retention is 7 days or 2000 rows per project, whichever cuts first;
+ *  - reading is a watermark per reader: unread = rows after the watermark; a watermark never moves backwards.
+ */
+export const NOTIFICATION_KINDS = Object.freeze([
+  'task.assigned', 'review.requested', 'review.decided', 'lock.conflict', 'merge.conflict',
+  'merge.merged', 'ref.updated', 'mention', 'maintenance.result', 'digest',
+]);
+export const DEFAULT_NOTIFICATION_LIMITS = Object.freeze({
+  dedupeWindowMs: 60 * 1000,
+  ratePerMinute: 120,
+  retentionMs: 7 * 24 * 60 * 60 * 1000,
+  maxPerProject: 2000,
+});
+
+export class NotificationError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'NotificationError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const memberKey = (member) => (member && typeof member.kind === 'string' && typeof member.id === 'string' ? member.kind + ':' + member.id : null);
+
+export function createProjectNotifications({ now = () => Date.now(), onEvent = null, limits = DEFAULT_NOTIFICATION_LIMITS } = {}) {
+  const rows = new Map(); // notification_id -> row
+  const dedupe = new Map(); // dedupe key -> { id, at_ms }
+  const watermarks = new Map(); // member key -> { ms, updated_at }
+  const digests = new Map(); // project_id -> { window_start_ms, id, count }
+  let counter = 0;
+  let seq = 0;
+
+  const emit = (type, payload) => {
+    seq += 1;
+    const event = { seq, type, at: new Date(now()).toISOString(), payload };
+    if (typeof onEvent === 'function') onEvent(event);
+    return event;
+  };
+
+  const primaryRef = (refs) => {
+    if (!refs || typeof refs !== 'object') return '';
+    for (const key of ['task_id', 'review_id', 'lock_id', 'merge_queue_id', 'sha256']) if (typeof refs[key] === 'string' && refs[key] !== '') return key + ':' + refs[key];
+    return '';
+  };
+
+  const targetKey = (target) => (!target || typeof target !== 'object' ? 'none' : target.kind === 'broadcast' ? 'broadcast' : memberKey(target) ?? 'none');
+
+  /** Drop rows the retention rule no longer keeps; oldest first. Called before every write. */
+  const prune = (projectId) => {
+    const mine = [...rows.values()].filter((row) => row.project_id === projectId).sort((a, b) => a.created_at_ms - b.created_at_ms);
+    const cutoff = now() - limits.retentionMs;
+    const keep = [];
+    for (const row of mine) {
+      if (row.created_at_ms >= cutoff) keep.push(row);
+      else rows.delete(row.notification_id);
+    }
+    while (keep.length > limits.maxPerProject) {
+      const dropped = keep.shift();
+      rows.delete(dropped.notification_id);
+    }
+  };
+
+  /** The digest row for this minute, created on demand and updated in place. */
+  const digestFor = (projectId, target) => {
+    const windowStart = Math.floor(now() / 60000) * 60000;
+    const current = digests.get(projectId);
+    if (current !== undefined && current.window_start_ms === windowStart) return rows.get(current.id);
+    counter += 1;
+    const id = 'nt-' + String(counter).padStart(6, '0');
+    const row = {
+      notification_id: id,
+      project_id: projectId,
+      kind: 'digest',
+      target: target ?? { kind: 'broadcast' },
+      subject: 'digest',
+      refs: {},
+      requires_action: false,
+      created_at: new Date(windowStart).toISOString(),
+      created_at_ms: windowStart,
+      count: 1,
+    };
+    rows.set(id, row);
+    digests.set(projectId, { window_start_ms: windowStart, id, count: 1 });
+    emit('notification.digest', { notification_id: id, project_id: projectId, count: row.count, window_start_ms: windowStart });
+    return row;
+  };
+
+  return {
+    notify({ projectId, kind, target = { kind: 'broadcast' }, subject = null, refs = {}, requiresAction = false }) {
+      if (typeof projectId !== 'string' || projectId === '') throw new NotificationError('INVALID_PROJECT', 'project_id is required');
+      if (!NOTIFICATION_KINDS.includes(kind)) throw new NotificationError('INVALID_KIND', 'unknown notification kind', { kind });
+      if (kind !== 'digest' && (!target || typeof target !== 'object')) throw new NotificationError('INVALID_TARGET', 'target is required');
+      prune(projectId);
+      const at = now();
+      const dedupeKey = projectId + '|' + kind + '|' + targetKey(target) + '|' + primaryRef(refs);
+      const seen = dedupe.get(dedupeKey);
+      if (seen !== undefined && at - seen.at_ms <= limits.dedupeWindowMs && rows.has(seen.id)) {
+        return { ok: true, duplicate: true, notification: rows.get(seen.id) };
+      }
+      // Rate limit: one digest rows carries the overflow instead of 120 individual rows.
+      const minuteStart = at - 60000;
+      const recent = [...rows.values()].filter((row) => row.project_id === projectId && row.kind !== 'digest' && row.created_at_ms > minuteStart);
+      if (recent.length >= limits.ratePerMinute) {
+        counter += 1;
+        const digest = digestFor(projectId, target);
+        digest.count += 1;
+        digests.set(projectId, { window_start_ms: digest.created_at_ms, id: digest.notification_id, count: digest.count });
+        return { ok: true, digest: true, notification: digest };
+      }
+      counter += 1;
+      const id = 'nt-' + String(counter).padStart(6, '0');
+      const row = {
+        notification_id: id,
+        project_id: projectId,
+        kind,
+        target,
+        subject,
+        refs: { ...refs },
+        requires_action: requiresAction === true,
+        created_at: new Date(at).toISOString(),
+        created_at_ms: at,
+      };
+      rows.set(id, row);
+      dedupe.set(dedupeKey, { id, at_ms: at });
+      emit('notification.created', { notification_id: id, project_id: projectId, kind, target, subject, refs: row.refs, requires_action: row.requires_action });
+      return { ok: true, notification: row };
+    },
+    /** Notifications after a millisecond watermark, oldest first, bounded by limit. */
+    list({ projectId, sinceMs = 0, limit = 200 }) {
+      prune(projectId);
+      const slice = [...rows.values()]
+        .filter((row) => row.project_id === projectId && row.created_at_ms > sinceMs)
+        .sort((a, b) => a.created_at_ms - b.created_at_ms || a.notification_id.localeCompare(b.notification_id))
+        .slice(0, Math.max(1, limit))
+        .map((row) => ({ ...row, refs: { ...row.refs } }));
+      return { notifications: slice, next_since_ms: slice.length === 0 ? sinceMs : slice[slice.length - 1].created_at_ms };
+    },
+    /** Count and summarise what this reader has not acknowledged yet. */
+    unread({ projectId, reader }) {
+      const key = memberKey(reader);
+      if (key === null) throw new NotificationError('INVALID_READER', 'reader needs kind and id');
+      const watermark = watermarks.get(projectId + '|' + key)?.ms ?? 0;
+      const pending = [...rows.values()].filter((row) => row.project_id === projectId && row.created_at_ms > watermark);
+      return {
+        count: pending.length,
+        since_ms: watermark,
+        requires_action: pending.filter((row) => row.requires_action === true).length,
+        summary: pending.slice(-10).map((row) => ({ notification_id: row.notification_id, kind: row.kind, subject: row.subject, created_at: row.created_at })),
+      };
+    },
+    /** Advance a reader's watermark; it never moves backwards. */
+    markRead({ projectId, reader, watermarkMs = null }) {
+      const key = memberKey(reader);
+      if (key === null) throw new NotificationError('INVALID_READER', 'reader needs kind and id');
+      if (!Number.isFinite(watermarkMs)) throw new NotificationError('INVALID_WATERMARK', 'watermark_ms must be finite');
+      const storageKey = projectId + '|' + key;
+      const previous = watermarks.get(storageKey)?.ms ?? 0;
+      const next = Math.max(previous, watermarkMs);
+      watermarks.set(storageKey, { ms: next, updated_at: new Date(now()).toISOString() });
+      return { ok: true, watermark_ms: next, advanced: next !== previous };
+    },
+    readWatermark({ projectId, reader }) {
+      const key = memberKey(reader);
+      return watermarks.get(projectId + '|' + key)?.ms ?? 0;
+    },
+    size({ projectId = null } = {}) {
+      const all = [...rows.values()];
+      return { rows: projectId === null ? all.length : all.filter((row) => row.project_id === projectId).length, events: seq };
+    },
+  };
+}