@twinsearth/w2m-dsh-plugin 1.3.1 → 1.4.0

package/src/relay/server.mjs

@@ -767,7 +767,11 @@ export class RelayServer {
         // scanner the surface exists.
         throw new ProtocolError('NOT_FOUND', 'metrics are not enabled on this relay', { hint: 'start the relay with --metrics' });
       }
-      const body = renderMetrics(this.state, { nowMs: this.state.nowMs() });
+      const publishedBody = renderMetrics(this.state, { nowMs: this.state.nowMs() });
+      // v1.3.10-beta.23: the M7 reliability registry is appended. It renders nothing until a call site records something, so
+      // the existing exposition is unchanged on relays that never instrument.
+      const registryBody = typeof this.state.metrics?.renderPrometheus === 'function' ? this.state.metrics.renderPrometheus() : '';
+      const body = registryBody === '' ? publishedBody : publishedBody + '# reliability registry\n' + registryBody;
       res.writeHead(200, {
         'content-type': METRICS_CONTENT_TYPE,
         'content-length': Buffer.byteLength(body, 'utf8'),
@@ -811,6 +815,254 @@ export class RelayServer {
       return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
     }
 
+    /**
+     * v1.3.10-beta.14: project-room writes (M4).
+     *
+     * Above the shared device guard on purpose: an operator token is not a device token, and these change who may act on
+     * shared state, so they take the same credential that dispatches tasks.
+     */
+    if (method === 'POST' && (path === '/v1/projects' || /^\/v1\/projects\/[^/]+\/members$/.test(path))) {
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('FORBIDDEN_ACTION', 'only the operator may change project membership', { required_role: 'owner' });
+      const body = takeJson();
+      const membersMatch = /^\/v1\/projects\/([^/]+)\/members$/.exec(path);
+      if (membersMatch !== null) {
+        const target = decodeURIComponent(membersMatch[1]);
+        const added = this.state.projects.addMember({ projectId: target, member: { kind: body?.member?.kind, id: body?.member?.id, name: body?.member?.name ?? null }, role: body?.role ?? 'worker' });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, member: added.member, snapshot: this.state.projects.snapshot({ projectId: target }) });
+      }
+      const created = this.state.projects.createProject({
+        name: body?.name,
+        origin: body?.origin ?? null,
+        createdBy: { kind: 'operator', id: typeof body?.created_by?.id === 'string' ? body.created_by.id : 'operator', name: typeof body?.created_by?.name === 'string' ? body.created_by.name : null },
+      });
+      const createdId = created.project.project.project_id;
+      if (Array.isArray(body?.members)) {
+        for (const entry of body.members) {
+          this.state.projects.addMember({ projectId: createdId, member: { kind: entry?.kind, id: entry?.id, name: entry?.name ?? null }, role: entry?.role ?? 'worker' });
+        }
+      }
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, project: this.state.projects.snapshot({ projectId: createdId }) });
+    }
+
+
+    /**
+     * v1.3.12-beta.2: grant administration (execution-authorization model).
+     *
+     * Revoking is an operator act: it stops one authorisation from being dispatched. The task list is the audit view --
+     * every task that carried a grant, with the argv hash and key id it was authorised under -- and deliberately returns
+     * only operator-readable data, never result bodies.
+     */
+    if (path === '/v1/grants/revoke' || path === '/v1/grants') {
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'only the operator may administer grants');
+      if (method === 'POST' && path === '/v1/grants/revoke') {
+        const body = takeJson();
+        const revoked = this.state.revokeGrant({ grantId: body?.grant_id, reason: body?.reason ?? null });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...revoked });
+      }
+      if (method === 'GET' && path === '/v1/grants') {
+        const audit = this.state.grantedTasks();
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...audit });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'grants accept GET (audit) or POST /revoke', { method, path });
+    }
+
+    /**
+     * v1.3.13-beta.4: project refs and the merge queue (task model: branch, merge, conflict).
+     *
+     * Reads take the device token of a paired machine; advancing a ref and settling a queue item are operator acts, because
+     * they state where the branch is and what a patch did. A merge that would move the head from a base that is no longer
+     * current is refused and the item stays queued -- the model never silently rewrites history.
+     */
+    const refsMatch = /^\/v1\/projects\/([^/]+)\/refs(?:\/advance)?$/.exec(path);
+    if (refsMatch !== null) {
+      const projectId = decodeURIComponent(refsMatch[1]);
+      const wantsAdvance = path.endsWith('/advance');
+      if (!wantsAdvance && method === 'GET') {
+        const token = bearerToken(req);
+        if (token === null || this.state.authenticate(token) === null) throw new ProtocolError('UNAUTHORIZED', 'reading refs needs a paired device token');
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, refs: this.state.refs.listRefs({ projectId }) });
+      }
+      if (wantsAdvance && method === 'POST') {
+        const auth = this.authorizeTaskDispatch(req);
+        if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'advancing a ref is an operator act');
+        const body = takeJson();
+        const moved = this.state.refs.advance({ projectId, branch: body?.branch, from: body?.from ?? null, to: body?.to, reason: body?.reason ?? null });
+        return sendJson(res, moved.ok === true ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...moved });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'refs accept GET or POST /advance', { method, path });
+    }
+    const mergeMatch = /^\/v1\/projects\/([^/]+)\/merge-queue(?:\/([^/]+))?(?:\/(complete))?$/.exec(path);
+    if (mergeMatch !== null) {
+      const projectId = decodeURIComponent(mergeMatch[1]);
+      const queueId = mergeMatch[2] === undefined ? null : decodeURIComponent(mergeMatch[2]);
+      const action = mergeMatch[3] ?? null;
+      if (method === 'GET' && queueId === null) {
+        const token = bearerToken(req);
+        if (token === null || this.state.authenticate(token) === null) throw new ProtocolError('UNAUTHORIZED', 'reading the merge queue needs a paired device token');
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, items: this.state.refs.listQueue({ projectId }) });
+      }
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'merge queue mutations are operator acts');
+      if (method === 'POST' && queueId === null) {
+        const body = takeJson();
+        const queued = this.state.refs.enqueue({ projectId, branch: body?.branch, patchSha256: body?.patch_sha256, baseCommit: body?.base_commit, sourceTaskId: body?.source_task_id ?? null });
+        return sendJson(res, queued.ok === true ? 200 : 400, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...queued });
+      }
+      if (method === 'POST' && queueId !== null && action === 'complete') {
+        const body = takeJson();
+        const settled = this.state.refs.complete({ queueId, outcome: body?.outcome, headCommit: body?.head_commit ?? null, conflictSha256: body?.conflict_sha256 ?? null });
+        return sendJson(res, settled.ok === true ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...settled });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'merge queue accepts GET, POST enqueue or POST /:id/complete', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.1 (collaboration model): shared objects. Two clients in the same project read the SAME board and the SAME
+     * artifact index; before this they each filtered the global task list and disagreed as soon as one of them looked late.
+     */
+    const sharedMatch = /^\/v1\/projects\/([^/]+)\/(board|artifacts)$/.exec(path);
+    if (sharedMatch !== null) {
+      const projectId = decodeURIComponent(sharedMatch[1]);
+      const resource = sharedMatch[2];
+      const readDevice = () => {
+        const token = bearerToken(req);
+        const caller = token === null ? null : this.state.authenticate(token);
+        if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'reading a project object needs a paired device token');
+        return caller;
+      };
+      if (method === 'GET') {
+        const caller = readDevice();
+        const snapshot = this.state.projectSnapshot(projectId);
+        const isDefault = snapshot.project.project_id === this.state.defaultProjectId;
+        if (!isDefault) {
+          const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+          if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+        }
+        if (resource === 'board') return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...this.state.projectBoard({ projectId }) });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, artifacts: this.state.listArtifacts({ projectId }) });
+      }
+      if (method === 'POST' && resource === 'artifacts') {
+        const auth = this.authorizeTaskDispatch(req);
+        if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'registering a project artifact is an operator act');
+        const body = takeJson();
+        const registered = this.state.registerArtifact({ projectId, sha256: body?.sha256, bytes: body?.bytes, kind: body?.kind ?? 'artifact', sourceTaskId: body?.source_task_id ?? null });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...registered });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'project objects accept GET, or POST artifacts', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.2 (collaboration model): decisions and project memory as shared objects. The board answers "what is
+     * happening", these answer "what did we agree" -- and both are one object per project, not a per-client copy.
+     */
+    const knowledgeMatch = /^\/v1\/projects\/([^/]+)\/(decisions|memory)$/.exec(path);
+    if (knowledgeMatch !== null) {
+      const projectId = decodeURIComponent(knowledgeMatch[1]);
+      const resource = knowledgeMatch[2];
+      const readDevice = () => {
+        const token = bearerToken(req);
+        const caller = token === null ? null : this.state.authenticate(token);
+        if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'reading a project object needs a paired device token');
+        return caller;
+      };
+      const requireReadable = (caller) => {
+        const snapshot = this.state.projectSnapshot(projectId);
+        if (snapshot.project.project_id === this.state.defaultProjectId) return;
+        const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+      };
+      if (method === 'GET') {
+        const caller = readDevice();
+        requireReadable(caller);
+        if (resource === 'decisions') return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, decisions: this.state.listDecisions({ projectId }) });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, document: this.state.getProjectMemory({ projectId }) });
+      }
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'writing shared project objects is an operator act');
+      const body = takeJson();
+      if (method === 'POST' && resource === 'decisions') {
+        const added = this.state.addDecision({ projectId, title: body?.title, text: body?.text ?? null, actor: { kind: 'operator', id: 'operator' }, refs: body?.refs ?? {}, kind: body?.kind ?? 'decision' });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...added });
+      }
+      if (method === 'PUT' && resource === 'memory') {
+        const updated = this.state.setProjectMemory({ projectId, text: body?.text, actor: { kind: 'operator', id: 'operator' } });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...updated });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'decisions accept GET/POST, memory accepts GET/PUT', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.3 (collaboration model): notifications for shared-object events. The rows are broadcast to project
+     * members, read with a per-reader watermark, and deduplicated inside the notifications module; a client that reconnects
+     * asks for everything after its watermark instead of re-reading the whole event stream.
+     */
+    const notifyMatch = /^\/v1\/projects\/([^/]+)\/notifications(?:\/(unread|read))?$/.exec(path);
+    if (notifyMatch !== null) {
+      const projectId = decodeURIComponent(notifyMatch[1]);
+      const action = notifyMatch[2] ?? null;
+      const token = bearerToken(req);
+      const caller = token === null ? null : this.state.authenticate(token);
+      if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'notifications need a paired device token');
+      const snapshot = this.state.projectSnapshot(projectId);
+      if (snapshot.project.project_id !== this.state.defaultProjectId) {
+        const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+      }
+      const reader = { kind: 'machine', id: caller.machine_id };
+      if (method === 'GET' && action === null) {
+        const url = new URL(req.url, 'http://relay.invalid');
+        const sinceMs = Number(url.searchParams.get('since_ms') ?? 0);
+        const limit = Number(url.searchParams.get('limit') ?? 200);
+        const listed = this.state.notifications.list({ projectId, sinceMs: Number.isFinite(sinceMs) ? sinceMs : 0, limit: Number.isFinite(limit) ? Math.max(1, Math.min(500, limit)) : 200 });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...listed });
+      }
+      if (method === 'GET' && action === 'unread') return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...this.state.notifications.unread({ projectId, reader }) });
+      if (method === 'POST' && action === 'read') {
+        const body = takeJson();
+        const marked = this.state.notifications.markRead({ projectId, reader, watermarkMs: body?.watermark_ms });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...marked });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'notifications accept GET, GET /unread or POST /read', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.4 (collaboration model): a project-scoped SSE stream.
+     *
+     * `ready` names the project and its last event seq, `since_seq` replays the room events a client missed, then every new
+     * room event is pushed as `project.event`. Clients in the same project therefore apply the same ordered events instead
+     * of each polling a different view.
+     */
+    const projectStreamMatch = /^\/v1\/projects\/([^/]+)\/stream$/.exec(path);
+    if (projectStreamMatch !== null && method === 'GET') {
+      const projectId = decodeURIComponent(projectStreamMatch[1]);
+      const token = bearerToken(req);
+      const caller = token === null ? null : this.state.authenticate(token);
+      if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'project events need a paired device token');
+      const snapshot = this.state.projectSnapshot(projectId);
+      if (snapshot.project.project_id !== this.state.defaultProjectId) {
+        const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+      }
+      const sinceRaw = url.searchParams.get('since_seq');
+      const sinceSeq = sinceRaw !== null && /^[0-9]+$/.test(sinceRaw) ? Number(sinceRaw) : 0;
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' });
+      const frame = (entry) => {
+        try { res.write('id: ' + entry.seq + '\nevent: project.event\ndata: ' + JSON.stringify({ project_id: entry.project_id, seq: entry.seq, type: entry.type, payload: entry.payload }) + '\n\n'); } catch { /* closed */ }
+      };
+      const replayed = this.state.projects.events({ projectId, sinceSeq });
+      res.write('event: ready\ndata: ' + JSON.stringify({ protocol_version: PROTOCOL_VERSION, project_id: projectId, last_event_seq: replayed.next_seq }) + '\n\n');
+      for (const entry of replayed.events) frame(entry);
+      const unsubscribe = this.state.onProjectEvent((entry) => { if (entry.project_id === projectId) frame(entry); });
+      const keepalive = setInterval(() => { try { res.write(': keepalive\n\n'); } catch { /* closed */ } }, this.keepaliveMs);
+      let closed = false;
+      const done = () => { if (closed) return; closed = true; clearInterval(keepalive); unsubscribe(); try { res.end(); } catch { /* already closed */ } };
+      req.on('close', done);
+      res.on('close', done);
+      return true;
+    }
+
     /* ---- everything below requires `Authorization: Bearer <device_token>` ---- */
     const token = bearerToken(req);
     const device = token ? this.state.authenticate(token) : null;
@@ -819,12 +1071,92 @@ export class RelayServer {
     }
     this.state.touchDevice(device.machine_id);
 
+    const projectLockMatch = /^\/v1\/projects\/([^/]+)\/locks(?:\/([^/]+)(?:\/(renew))?)?$/.exec(path);
+    if (projectLockMatch !== null && method !== undefined) {
+      const projectId = decodeURIComponent(projectLockMatch[1]);
+      const lockId = projectLockMatch[2] === undefined ? null : decodeURIComponent(projectLockMatch[2]);
+      const action = projectLockMatch[3] ?? null;
+      const roomMember = { kind: 'machine', id: device.machine_id };
+      const snapshot = this.state.projectSnapshot(projectId);
+      const isDefault = snapshot.project.project_id === this.state.defaultProjectId;
+      const membership = isDefault ? { role: 'worker' } : this.state.projects.memberOf({ projectId, member: roomMember });
+      if (membership === null) return sendJson(res, 404, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: false, error: { code: 'NOT_FOUND', message: 'unknown project' } });
+      const roleRank = { observer: 0, worker: 1, maintainer: 2, owner: 3 };
+      const canWrite = roleRank[membership.role] >= roleRank.worker;
+      if (method === 'GET' && lockId === null) {
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, locks: this.state.locks.list({ projectId }) });
+      }
+      if (method === 'POST' && lockId === null) {
+        if (!canWrite) return sendJson(res, 403, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: false, error: { code: 'FORBIDDEN_ACTION', message: 'acquiring a lock needs worker or above', required_role: 'worker', current_role: membership.role } });
+        const body = takeJson();
+        const acquired = this.state.locks.acquire({ projectId, kind: body?.kind, target: body?.target, holder: { kind: "machine", id: device.machine_id }, reason: body?.reason ?? null, leaseMs: Number.isFinite(body?.lease_ms) ? body.lease_ms : undefined });
+        if (acquired.ok === true) this.state.metrics?.inc('wm_lock_acquired_total', { kind: String(body?.kind ?? '') });
+        else if (acquired.code === 'LOCK_HELD') this.state.metrics?.inc('wm_lock_conflict_total', { kind: String(body?.kind ?? '') });
+        return sendJson(res, acquired.ok ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...acquired });
+      }
+      if (method === 'POST' && lockId !== null && action === 'renew') {
+        const renewed = this.state.locks.renew({ projectId, lockId, holder: { kind: "machine", id: device.machine_id } });
+        return sendJson(res, renewed.ok ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...renewed });
+      }
+      if (method === 'DELETE' && lockId !== null) {
+        const force = url.searchParams.get('force') === '1';
+        const reason = url.searchParams.get('reason');
+        const released = force
+          ? this.state.locks.forceRelease({ projectId, lockId, actor: { kind: "machine", id: device.machine_id }, actorRole: membership.role, reason })
+          : this.state.locks.release({ projectId, lockId, holder: { kind: "machine", id: device.machine_id } });
+        return sendJson(res, released.ok ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...released });
+      }
+      return sendJson(res, 405, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: 'unsupported lock operation' } });
+    }
+
+    /**
+     * v1.3.10-beta.14: project-room reads (M4). Below the device guard, so the device is already authenticated.
+     *
+     * A machine sees the default project and the projects it is a member of; a project it is not a member of answers
+     * NOT_FOUND, so a project existence is not leaked. The snapshot carries last_event_seq, and the events route returns
+     * the slice after since_seq, which is what lets a client resume after a disconnect.
+     */
+    if (method === 'GET' && (path === '/v1/projects' || path.startsWith('/v1/projects/'))) {
+      const match = /^\/v1\/projects(?:\/([^/]+))?(?:\/(events|members))?$/.exec(path);
+      if (match === null) throw new ProtocolError('NOT_FOUND', 'unknown route', { path });
+      const projectId = match[1] === undefined ? null : decodeURIComponent(match[1]);
+      const sub = match[2] ?? null;
+      const readSnapshot = (id) => {
+        let snapshot;
+        try {
+          snapshot = this.state.projectSnapshot(id);
+        } catch (error) {
+          if (error?.code === 'BAD_REQUEST' || error?.code === 'PROJECT_NOT_FOUND') throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: id });
+          throw error;
+        }
+        if (snapshot.project.project_id === this.state.defaultProjectId) return snapshot;
+        const member = this.state.projects.memberOf({ projectId: id, member: { kind: 'machine', id: device.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: id });
+        return snapshot;
+      };
+      if (projectId === null) {
+        const mine = this.state.projects.listProjects({ member: { kind: 'machine', id: device.machine_id } }).projects;
+        if (!mine.some((project) => project.project_id === this.state.defaultProjectId)) mine.unshift({ project_id: this.state.defaultProjectId, name: 'default', origin: null });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, projects: mine });
+      }
+      if (sub === null) return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...readSnapshot(projectId) });
+      if (sub === 'events') {
+        readSnapshot(projectId);
+        const raw = url.searchParams.get('since_seq');
+        const sinceSeq = raw !== null && /^[0-9]+$/.test(raw) ? Number(raw) : 0;
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...this.state.projectEvents(projectId, { sinceSeq }) });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'unsupported project route', { method, path });
+    }
+
+
     // v0.3.0 §9: writes are always checked (tolerating unsigned unless required);
     // reads are only checked when the relay was explicitly told to require
     // signatures. See `enforceSignature` for the reasoning.
     this.enforceSignature(req, { method, signedPath, body: rawBody });
 
     /* ---- v1.2.5: members and read watermarks ---- */
+
     if (method === 'GET' && path === '/v1/fleet/members') {
       return sendJson(res, 200, {
         protocol_version: PROTOCOL_VERSION,
@@ -871,6 +1203,38 @@ export class RelayServer {
       const { _instanceKey, ...clean } = result;
       return sendJson(res, 200, clean);
     }
+    /**
+     * v1.3.10-beta.20: chunked blob sessions (M6). A >64 KiB artifact is uploaded in idempotent chunks and only becomes a
+     * blob when the assembled bytes hash to the declared sha256; the session answers "which chunks are missing" so an
+     * interrupted upload resumes instead of restarting.
+     */
+    const blobSessionCreate = method === 'POST' && path === '/v1/fleet/blob-sessions';
+    const blobSessionChunk = /^\/v1\/fleet\/blob-sessions\/([^/]+)\/chunks\/([0-9]+)$/.exec(path);
+    const blobSessionCommit = /^\/v1\/fleet\/blob-sessions\/([^/]+)\/commit$/.exec(path);
+    const blobSessionStatus = /^\/v1\/fleet\/blob-sessions\/([^/]+)$/.exec(path);
+    if (blobSessionCreate || blobSessionChunk !== null || blobSessionCommit !== null || blobSessionStatus !== null) {
+      const wrap = (fn) => { try { return fn(); } catch (error) { if (typeof error?.code === "string") throw new ProtocolError(error.code, error.message, error.detail ?? null); throw error; } };
+      if (blobSessionCreate) {
+        const body = takeJson();
+        const created = wrap(() => this.state.blobSessions.create({ machineId: device.machine_id, sha256: body?.sha256, size: body?.size, chunkBytes: body?.chunk_bytes }));
+        return sendJson(res, 201, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...created });
+      }
+      if (method === 'PUT' && blobSessionChunk !== null) {
+        const data = rawBody ?? Buffer.alloc(0);
+        const stored = wrap(() => this.state.blobSessions.putChunk({ sessionId: decodeURIComponent(blobSessionChunk[1]), index: Number(blobSessionChunk[2]), data }));
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...stored });
+      }
+      if (method === 'POST' && blobSessionCommit !== null) {
+        const committed = wrap(() => this.state.blobSessions.commit({ sessionId: decodeURIComponent(blobSessionCommit[1]) }));
+        return sendJson(res, committed.ok === true ? 201 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...committed });
+      }
+      if (method === 'GET' && blobSessionStatus !== null) {
+        const status = wrap(() => this.state.blobSessions.status({ sessionId: decodeURIComponent(blobSessionStatus[1]) }));
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...status });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'a blob session is created with POST, chunks with PUT, committed with POST', {});
+    }
+
     /**
      * v1.0.7: the content-addressed blob channel (#1).
      *
@@ -956,6 +1320,23 @@ export class RelayServer {
           // Same code and shape for "no such blob" and "not your fleet's" -- deliberately indistinguishable.
           throw new ProtocolError('NOT_FOUND', 'no such blob is readable by this device', { hash });
         }
+        const rangeParam = url.searchParams.get('range');
+        if (rangeParam !== null) {
+          const match = /^([0-9]+)-([0-9]+)$/.exec(rangeParam);
+          if (match === null) throw new ProtocolError('BAD_REQUEST', 'range must be start-end', { range: rangeParam });
+          const start = Number(match[1]);
+          const end = Math.min(Number(match[2]), bytes.length - 1);
+          if (!(start >= 0 && start <= end && start < bytes.length)) throw new ProtocolError('BAD_REQUEST', 'range is outside the blob', { range: rangeParam, bytes: bytes.length });
+          const slice = bytes.subarray(start, end + 1);
+          res.writeHead(206, {
+            'content-type': 'application/octet-stream',
+            'content-length': slice.length,
+            'content-range': 'bytes ' + start + '-' + end + '/' + bytes.length,
+            'cache-control': 'no-store',
+          });
+          res.end(slice);
+          return true;
+        }
         res.writeHead(200, {
           'content-type': 'application/octet-stream',
           'content-length': bytes.length,