@twinsearth/w2m-dsh-plugin 1.3.1 → 1.4.0

package/src/relay/project-refs.mjs

@@ -0,0 +1,110 @@
+/**
+ * Project refs and merge bookkeeping (v1.3.13-beta.3 slice).
+ *
+ * A workspace task produces a patch against a base; the task model needs one place that says where each branch actually is and
+ * what happened to each patch. This module records monotonic branch heads, a merge queue keyed by patch sha256, and first-class
+ * outcomes (merged / already_merged / base mismatch / conflict). git application belongs to the machine (merge-queue.mjs owns
+ * the repository work); the relay records the decision and refuses a claim it has already answered.
+ */
+const SHA = /^[0-9a-f]{7,64}$/;
+const PATCH = /^[0-9a-f]{64}$/;
+
+export class RefError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'RefError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const keyOf = (projectId, branch) => projectId + '|' + branch;
+
+export function createProjectRefs({ now = () => Date.now(), onEvent = null } = {}) {
+  const heads = new Map();
+  const items = new Map();
+  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;
+  };
+  return {
+    head({ projectId, branch }) {
+      return heads.get(keyOf(projectId, branch)) ?? null;
+    },
+    /**
+     * Advance a branch. The caller names the head it built on; if that is not the current head the advance is refused
+     * (REF_BASE_MISMATCH), because silently moving someone else's base is how intent gets lost.
+     */
+    advance({ projectId, branch, from = null, to, actor = null, reason = null }) {
+      if (typeof projectId !== 'string' || projectId === '') throw new RefError('INVALID_PROJECT', 'project_id is required');
+      if (typeof branch !== 'string' || branch === '') throw new RefError('INVALID_BRANCH', 'branch is required');
+      if (!SHA.test(String(to))) throw new RefError('INVALID_HEAD', 'to must be a hex commit id', { to });
+      const current = heads.get(keyOf(projectId, branch));
+      const currentHead = current?.head_commit ?? null;
+      if (from !== currentHead) {
+        return { ok: false, code: currentHead === null ? 'REF_UNINITIALIZED' : 'REF_BASE_MISMATCH', expected: currentHead, from };
+      }
+      if (from !== null && String(to) === from) return { ok: false, code: 'REF_NO_CHANGE', head: from };
+      const head = { project_id: projectId, branch, head_commit: String(to), version: (current?.version ?? 0) + 1, updated_at: new Date(now()).toISOString() };
+      heads.set(keyOf(projectId, branch), head);
+      emit('ref.advanced', { ...head, from, actor, reason });
+      return { ok: true, head: { ...head }, from };
+    },
+    listRefs({ projectId }) {
+      return [...heads.values()].filter((head) => head.project_id === projectId).map((head) => ({ ...head }));
+    },
+    /** Queue a patch. A patch already merged on that branch is answered, not queued twice. */
+    enqueue({ projectId, branch, patchSha256, baseCommit, sourceTaskId = null }) {
+      if (!PATCH.test(String(patchSha256))) return { ok: false, code: 'INVALID_PATCH_SHA' };
+      if (!SHA.test(String(baseCommit))) return { ok: false, code: 'INVALID_BASE_COMMIT' };
+      for (const item of items.values()) {
+        if (item.project_id === projectId && item.branch === branch && item.patch_sha256 === patchSha256 && item.state === 'merged') {
+          return { ok: true, already_merged: true, item: { ...item } };
+        }
+      }
+      counter += 1;
+      const item = {
+        queue_id: 'mq-' + String(counter).padStart(6, '0'),
+        project_id: projectId,
+        branch,
+        patch_sha256: String(patchSha256),
+        base_commit: String(baseCommit),
+        source_task_id: sourceTaskId,
+        state: 'queued',
+        created_at: new Date(now()).toISOString(),
+      };
+      items.set(item.queue_id, item);
+      emit('merge.queued', { ...item });
+      return { ok: true, already_merged: false, item: { ...item } };
+    },
+    /** Record a terminal outcome. Only 'merged' advances the branch, and only from the recorded base. */
+    complete({ queueId, outcome, headCommit = null, conflictSha256 = null }) {
+      const item = items.get(queueId);
+      if (item === undefined) return { ok: false, code: 'MERGE_ITEM_NOT_FOUND' };
+      if (item.state !== 'queued') return { ok: false, code: 'MERGE_ITEM_ALREADY_SETTLED', state: item.state };
+      if (!['merged', 'conflict', 'failed'].includes(outcome)) return { ok: false, code: 'INVALID_OUTCOME', outcome };
+      if (outcome === 'merged') {
+        const moved = this.advance({ projectId: item.project_id, branch: item.branch, from: item.base_commit, to: headCommit });
+        if (moved.ok !== true) return { ok: false, code: 'REF_ADVANCE_REFUSED', ref: moved };
+      }
+      item.state = outcome;
+      item.head_commit = outcome === 'merged' ? String(headCommit) : null;
+      item.conflict_sha256 = outcome === 'conflict' && PATCH.test(String(conflictSha256)) ? String(conflictSha256) : null;
+      item.settled_at = new Date(now()).toISOString();
+      emit('merge.' + outcome, { ...item });
+      return { ok: true, item: { ...item } };
+    },
+    listQueue({ projectId, branch = null }) {
+      return [...items.values()]
+        .filter((item) => item.project_id === projectId && (branch === null || item.branch === branch))
+        .map((item) => ({ ...item }));
+    },
+    size() {
+      return { heads: heads.size, items: items.size, events: seq };
+    },
+  };
+}

package/src/relay/project-reviews.mjs

@@ -0,0 +1,161 @@
+/**
+ * Project reviews (M5, v1.3.10-beta.16 slice).
+ *
+ * A review is a control-plane task: it points at a content-addressed patch/artifact and asks maintainers for a verdict. The
+ * verdict is a decision record, not a mutable flag: "approve" and "changes_requested" accumulate as history, and the review
+ * status follows from those records. That is what lets a merge gate ask "does this exact patch sha have an approval?" and get
+ * an answer that cannot be edited afterwards.
+ *
+ * Rules (docs/COLLAB/M5-MULTI-CLIENT-PRIMITIVES.md §3):
+ *  - only maintainer/owner may be a reviewer, and only the listed reviewers may decide;
+ *  - nobody reviews their own request (an owner may override, and the override is recorded);
+ *  - a reviewer may not record the same verdict twice; a second approve on the same review is a refusal, not a no-op;
+ *  - any changes_requested closes the round; the submitter opens a new review for a new revision;
+ *  - approvals reach required_approvals -> approved; a due date can expire a pending review.
+ */
+export const REVIEW_STATUSES = Object.freeze(['pending', 'approved', 'changes_requested', 'expired']);
+export const REVIEW_DECISIONS = Object.freeze(['approve', 'changes_requested', 'comment']);
+const REVIEWER_ROLES = Object.freeze(['maintainer', 'owner']);
+
+export class ReviewError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'ReviewError';
+    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 createProjectReviews({ now = () => Date.now(), onEvent = null } = {}) {
+  const reviews = new Map();
+  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;
+  };
+
+  /** Expire pending reviews whose due date passed; each expiry is an event. */
+  const expireDue = () => {
+    const expired = [];
+    for (const review of reviews.values()) {
+      if (review.status === 'pending' && review.due_at_ms !== null && review.due_at_ms <= now()) {
+        review.status = 'expired';
+        expired.push(review);
+        emit('review.expired', { review_id: review.review_id, project_id: review.project_id, target: review.target });
+      }
+    }
+    return expired;
+  };
+
+  const describe = (review) => ({
+    review_id: review.review_id,
+    project_id: review.project_id,
+    target: { ...review.target },
+    requested_by: { ...review.requested_by },
+    reviewers: review.reviewers.map((entry) => ({ ...entry })),
+    required_approvals: review.required_approvals,
+    status: review.status,
+    decisions: review.decisions.map((decision) => ({ ...decision })),
+    created_at: review.created_at,
+    due_at: review.due_at,
+    approvals: review.decisions.filter((decision) => decision.decision === 'approve').length,
+  });
+
+  const approvalsOf = (review) => new Set(review.decisions.filter((decision) => decision.decision === 'approve').map((decision) => memberKey(decision.reviewer))).size;
+
+  return {
+    create({ projectId, target, requestedBy, reviewers, requiredApprovals = 1, dueAt = null, roleOf = null, allowSelfReview = false }) {
+      if (typeof projectId !== 'string' || projectId === '') throw new ReviewError('INVALID_PROJECT', 'project_id is required');
+      if (!target || typeof target !== 'object' || !/^[0-9a-f]{64}$/.test(String(target.sha256 ?? ''))) throw new ReviewError('INVALID_TARGET', 'target needs a sha256', { target });
+      if (!['patch', 'artifact'].includes(target.kind)) throw new ReviewError('INVALID_TARGET', 'target.kind must be patch or artifact', { kind: target.kind });
+      if (memberKey(requestedBy) === null) throw new ReviewError('INVALID_REQUESTER', 'requested_by needs kind and id');
+      if (!Array.isArray(reviewers) || reviewers.length === 0) throw new ReviewError('INVALID_REVIEWERS', 'at least one reviewer is required');
+      if (!Number.isInteger(requiredApprovals) || requiredApprovals < 1) throw new ReviewError('INVALID_APPROVALS', 'required_approvals must be a positive integer');
+      for (const reviewer of reviewers) {
+        if (memberKey(reviewer) === null) throw new ReviewError('INVALID_REVIEWERS', 'every reviewer needs kind and id', { reviewer });
+        if (memberKey(reviewer) === memberKey(requestedBy) && !allowSelfReview) {
+          return { ok: false, code: 'REVIEW_SELF_NOT_ALLOWED', reviewer };
+        }
+        if (typeof roleOf === 'function') {
+          const role = roleOf(reviewer);
+          if (!REVIEWER_ROLES.includes(role)) return { ok: false, code: 'REVIEW_PERMISSION', reviewer, role, required_role: 'maintainer' };
+        }
+      }
+      counter += 1;
+      const reviewId = 'rv-' + String(counter).padStart(6, '0');
+      const dueMs = dueAt === null ? null : Date.parse(dueAt);
+      const review = {
+        review_id: reviewId,
+        project_id: projectId,
+        target: { kind: target.kind, sha256: String(target.sha256), source_task_id: target.source_task_id ?? null, diffstat: target.diffstat ?? null },
+        requested_by: { ...requestedBy },
+        reviewers: reviewers.map((reviewer) => ({ kind: reviewer.kind, id: reviewer.id })),
+        required_approvals: requiredApprovals,
+        status: 'pending',
+        decisions: [],
+        created_at: new Date(now()).toISOString(),
+        due_at: dueMs === null || Number.isNaN(dueMs) ? null : new Date(dueMs).toISOString(),
+        due_at_ms: dueMs === null || Number.isNaN(dueMs) ? null : dueMs,
+      };
+      reviews.set(reviewId, review);
+      emit('review.requested', { review_id: reviewId, project_id: projectId, target: review.target, requested_by: review.requested_by, reviewers: review.reviewers, required_approvals: requiredApprovals });
+      if (allowSelfReview && reviewers.some((reviewer) => memberKey(reviewer) === memberKey(requestedBy))) {
+        emit('review.self_review_override', { review_id: reviewId, project_id: projectId, requested_by: review.requested_by });
+      }
+      return { ok: true, review: describe(review) };
+    },
+    decide({ reviewId, reviewer, decision, comment = null, findings = [] }) {
+      expireDue();
+      const review = reviews.get(reviewId);
+      if (review === undefined) return { ok: false, code: 'REVIEW_NOT_FOUND', review_id: reviewId };
+      if (!REVIEW_DECISIONS.includes(decision)) throw new ReviewError('INVALID_DECISION', 'unknown decision', { decision });
+      if (memberKey(reviewer) === null || !review.reviewers.some((entry) => memberKey(entry) === memberKey(reviewer))) {
+        return { ok: false, code: 'REVIEW_PERMISSION', reviewer, reviewers: review.reviewers };
+      }
+      if (review.status === 'expired') return { ok: false, code: 'REVIEW_EXPIRED', review_id: reviewId };
+      const sameDirection = review.decisions.some((existing) => memberKey(existing.reviewer) === memberKey(reviewer) && existing.decision === decision);
+      if (sameDirection) return { ok: false, code: 'REVIEW_ALREADY_DECIDED', review_id: reviewId, decision };
+      if (review.status === 'changes_requested' && decision !== 'comment') {
+        return { ok: false, code: 'REVIEW_ALREADY_DECIDED', review_id: reviewId, status: review.status };
+      }
+      const record = {
+        reviewer: { kind: reviewer.kind, id: reviewer.id },
+        decision,
+        comment: typeof comment === 'string' ? comment : null,
+        findings: Array.isArray(findings) ? findings.map((finding) => ({ file: finding?.file ?? null, line: Number.isInteger(finding?.line) ? finding.line : null, severity: finding?.severity ?? null, text: finding?.text ?? null })) : [],
+        decided_at: new Date(now()).toISOString(),
+      };
+      review.decisions.push(record);
+      if (decision === 'approve' && review.status === 'pending' && approvalsOf(review) >= review.required_approvals) review.status = 'approved';
+      if (decision === 'changes_requested') review.status = 'changes_requested';
+      emit('review.decided', { review_id: reviewId, project_id: review.project_id, reviewer: record.reviewer, decision, comment: record.comment, findings: record.findings, status: review.status });
+      if (review.status === 'approved') emit('review.approved', { review_id: reviewId, project_id: review.project_id, target: review.target, approvals: approvalsOf(review) });
+      if (review.status === 'changes_requested') emit('review.changes_requested', { review_id: reviewId, project_id: review.project_id, target: review.target, reviewer: record.reviewer });
+      return { ok: true, review: describe(review), decision: record };
+    },
+    get({ reviewId }) {
+      expireDue();
+      const review = reviews.get(reviewId);
+      return review === undefined ? null : describe(review);
+    },
+    list({ projectId, status = null }) {
+      expireDue();
+      return [...reviews.values()]
+        .filter((review) => review.project_id === projectId && (status === null || review.status === status))
+        .map((review) => ({ review_id: review.review_id, target: review.target, status: review.status, approvals: approvalsOf(review), required_approvals: review.required_approvals, created_at: review.created_at, due_at: review.due_at }));
+    },
+    /** Merge gate (§3.2): is this exact patch sha approved by a review on this project? */
+    approvedFor({ projectId, sha256 }) {
+      expireDue();
+      const approved = [...reviews.values()].find((review) => review.project_id === projectId && review.status === 'approved' && review.target.sha256 === sha256);
+      return approved === undefined ? { ok: false, code: 'REVIEW_REQUIRED', sha256 } : { ok: true, review_id: approved.review_id };
+    },
+    size() { return { reviews: reviews.size, events: seq }; },
+  };
+}

package/src/relay/project-room.mjs

@@ -0,0 +1,163 @@
+/**
+ * Project room (M4, v1.3.10-beta.12 slice).
+ *
+ * A project is the shared object a fleet lacks today: tasks, artifacts, memory, decisions and refs belong to it, and every
+ * client reads the same membership and the same event sequence. This module owns the object, its members, the permission
+ * matrix and the snapshot/event protocol; it deliberately holds no relay state of its own so it can be replayed and tested.
+ *
+ * Permissions are deny-by-default: an action is allowed only when the member's role is at or above the role the action
+ * requires. A role change is an event, like every other mutation, so "who could do what, when" is answerable afterwards.
+ */
+export const PROJECT_ROLES = Object.freeze(['observer', 'worker', 'maintainer', 'owner']);
+
+const RANK = Object.freeze({ observer: 0, worker: 1, maintainer: 2, owner: 3 });
+
+/** action -> minimum role */
+export const PROJECT_ACTIONS = Object.freeze({
+  read: 'observer',
+  dispatch: 'worker',
+  artifact: 'worker',
+  lock: 'worker',
+  memory: 'maintainer',
+  decide: 'maintainer',
+  merge: 'maintainer',
+  settings: 'maintainer',
+  members: 'owner',
+});
+
+export class ProjectRoomError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'ProjectRoomError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+export function createProjectRoom({ now = () => Date.now(), onEvent = null } = {}) {
+  const projects = new Map();
+  const events = [];
+  let seq = 0;
+  let counter = 0;
+
+  const emit = (projectId, type, actor, payload) => {
+    seq += 1;
+    const event = { seq, project_id: projectId, type, actor, payload, at: new Date(now()).toISOString() };
+    events.push(event);
+    if (typeof onEvent === 'function') onEvent(event);
+    return event;
+  };
+
+  const requireProject = (projectId) => {
+    const project = projects.get(projectId);
+    if (!project) throw new ProjectRoomError('PROJECT_NOT_FOUND', 'unknown project', { project_id: projectId });
+    return project;
+  };
+
+  const findMember = (project, member) => {
+    if (!member || typeof member !== 'object' || typeof member.kind !== 'string' || typeof member.id !== 'string') return null;
+    return project.members.find((entry) => entry.kind === member.kind && entry.id === member.id) ?? null;
+  };
+
+  return {
+    /** Create a project; the creator becomes its owner. */
+    createProject({ name, origin = null, createdBy, projectId = null }) {
+      if (typeof name !== 'string' || name.trim() === '') throw new ProjectRoomError('BAD_REQUEST', 'project name is required');
+      if (!createdBy || typeof createdBy.kind !== 'string' || typeof createdBy.id !== 'string') throw new ProjectRoomError('BAD_REQUEST', 'createdBy member is required');
+      counter += 1;
+      const assigned = typeof projectId === 'string' && projectId !== '' ? projectId : 'prj-' + String(counter).padStart(4, '0') + '-' + now().toString(36);
+      if (projects.has(assigned)) throw new ProjectRoomError('DUPLICATE_PROJECT', 'project id already exists', { project_id: assigned });
+      const project = {
+        project_id: assigned,
+        name: name.trim(),
+        origin: origin === null ? null : { ...origin },
+        created_at: new Date(now()).toISOString(),
+        created_by: { ...createdBy },
+        settings: { merge_requires_review: false, merge_requires_tests: false },
+        members: [{ ...createdBy, role: 'owner', joined_at: new Date(now()).toISOString() }],
+      };
+      projects.set(assigned, project);
+      emit(assigned, 'project.created', createdBy, { name: project.name });
+      return { ok: true, project: this.snapshot({ projectId: assigned }) };
+    },
+    addMember({ projectId, member, role }) {
+      const project = requireProject(projectId);
+      if (!PROJECT_ROLES.includes(role)) throw new ProjectRoomError('BAD_ROLE', 'unknown role', { role });
+      if (!member || typeof member.kind !== 'string' || typeof member.id !== 'string' || typeof member.id === 'undefined') throw new ProjectRoomError('BAD_REQUEST', 'member needs kind and id');
+      if (findMember(project, member) !== null) throw new ProjectRoomError('DUPLICATE_MEMBER', 'member already belongs to this project', { member });
+      const entry = { kind: member.kind, id: member.id, name: typeof member.name === 'string' ? member.name : null, role, joined_at: new Date(now()).toISOString() };
+      project.members.push(entry);
+      emit(projectId, 'member.added', member, { role });
+      return { ok: true, member: { ...entry } };
+    },
+    removeMember({ projectId, member }) {
+      const project = requireProject(projectId);
+      const index = project.members.findIndex((entry) => entry.kind === member?.kind && entry.id === member?.id);
+      if (index < 0) throw new ProjectRoomError('MEMBER_NOT_FOUND', 'member does not belong to this project', { member });
+      const [removed] = project.members.splice(index, 1);
+      if (removed.role === 'owner' && project.members.every((entry) => entry.role !== 'owner')) {
+        project.members.splice(index, 0, removed);
+        throw new ProjectRoomError('LAST_OWNER', 'a project must keep at least one owner', { member });
+      }
+      emit(projectId, 'member.removed', member, { role: removed.role });
+      return { ok: true };
+    },
+    setRole({ projectId, member, role }) {
+      const project = requireProject(projectId);
+      if (!PROJECT_ROLES.includes(role)) throw new ProjectRoomError('BAD_ROLE', 'unknown role', { role });
+      const entry = findMember(project, member);
+      if (entry === null) throw new ProjectRoomError('MEMBER_NOT_FOUND', 'member does not belong to this project', { member });
+      if (entry.role === role) return { ok: true, member: { ...entry }, changed: false };
+      const previous = entry.role;
+      entry.role = role;
+      emit(projectId, 'member.role_changed', member, { from: previous, to: role });
+      return { ok: true, member: { ...entry }, changed: true };
+    },
+    memberOf({ projectId, member }) {
+      const project = requireProject(projectId);
+      return findMember(project, member);
+    },
+    /** Deny-by-default permission check. Returns a value; the caller decides whether to throw. */
+    mayAct({ projectId, member, action }) {
+      const project = requireProject(projectId);
+      const required = PROJECT_ACTIONS[action];
+      if (!required) throw new ProjectRoomError('BAD_REQUEST', 'unknown action', { action });
+      const entry = findMember(project, member);
+      if (entry === null) return { ok: false, code: 'NOT_A_MEMBER', action, required_role: required, current_role: null };
+      if (RANK[entry.role] >= RANK[required]) return { ok: true, action, role: entry.role };
+      return { ok: false, code: 'FORBIDDEN_ACTION', action, required_role: required, current_role: entry.role };
+    },
+    /** A project snapshot carrying the event sequence it is consistent with. */
+    snapshot({ projectId, extras = {} }) {
+      const project = requireProject(projectId);
+      return {
+        project: {
+          project_id: project.project_id,
+          name: project.name,
+          origin: project.origin,
+          created_at: project.created_at,
+          created_by: project.created_by,
+          settings: { ...project.settings },
+        },
+        members: project.members.map((entry) => ({ ...entry })),
+        ...extras,
+        last_event_seq: seq,
+      };
+    },
+    /** Incremental events for one project, seq strictly greater than sinceSeq. */
+    events({ projectId, sinceSeq = 0, limit = 200 }) {
+      requireProject(projectId);
+      const slice = events.filter((event) => event.project_id === projectId && event.seq > sinceSeq).slice(0, limit);
+      return { events: slice.map((event) => ({ ...event, payload: { ...event.payload } })), next_seq: slice.length > 0 ? slice[slice.length - 1].seq : sinceSeq };
+    },
+    /** Projects a member belongs to. */
+    listProjects({ member }) {
+      return { projects: [...projects.values()].filter((project) => findMember(project, member) !== null).map((project) => ({ project_id: project.project_id, name: project.name, origin: project.origin })) };
+    },
+    appendEvent({ projectId, type, actor, payload = {} }) {
+      requireProject(projectId);
+      return { ok: true, event: emit(projectId, type, actor, payload) };
+    },
+    size() { return { projects: projects.size, events: events.length, last_seq: seq }; },
+  };
+}

package/src/relay/reliability-metrics.mjs

@@ -0,0 +1,180 @@
+/**
+ * Reliability metrics registry (M7, v1.3.10-beta.22 slice).
+ *
+ * M7 requires every capability to be measurable from relay-owned data with one definition per metric. This registry is that
+ * definition: it declares which metric names exist, which labels each one may carry, and which are histograms. An undeclared
+ * name, or a label the definition does not allow, is refused immediately rather than producing a surprise on a dashboard.
+ *
+ * Cardinality is a rule, not a suggestion: high-cardinality identifiers (task ids, dedupe keys, review ids) are REJECTED as
+ * label keys, because one label per task is how a metrics endpoint becomes a memory leak.
+ */
+export const FORBIDDEN_LABELS = Object.freeze(['task_id', 'dedupe_key', 'review_id', 'lock_id', 'notification_id', 'session_id']);
+
+const DEFAULT_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10_000, 30_000, 60_000, 300_000];
+
+/** name -> {type, labels, buckets?}: the whole contract, in one place. */
+export const METRIC_DEFINITIONS = Object.freeze({
+  wm_tasks_total: { type: 'counter', labels: ['status', 'mode'] },
+  wm_task_duration_ms: { type: 'histogram', labels: ['status', 'mode'], buckets: DEFAULT_BUCKETS },
+  wm_task_requeued_total: { type: 'counter', labels: ['reason'] },
+  wm_lease_expired_total: { type: 'counter', labels: ['reason'] },
+  wm_result_duplicate_total: { type: 'counter', labels: [] },
+  wm_dependency_released_total: { type: 'counter', labels: [] },
+  wm_grant_issued_total: { type: 'counter', labels: ['machine_scope'] },
+  wm_grant_denied_total: { type: 'counter', labels: ['code'] },
+  wm_grant_expired_total: { type: 'counter', labels: [] },
+  wm_maintenance_requests_total: { type: 'counter', labels: ['action', 'outcome'] },
+  wm_maintenance_rollback_total: { type: 'counter', labels: [] },
+  wm_blob_upload_sessions_total: { type: 'counter', labels: ['state'] },
+  wm_blob_chunks_total: { type: 'counter', labels: ['retried'] },
+  wm_blob_resume_total: { type: 'counter', labels: [] },
+  wm_blob_bytes_total: { type: 'counter', labels: ['mode'] },
+  wm_blob_sha_mismatch_total: { type: 'counter', labels: [] },
+  wm_agent_outbox_depth: { type: 'gauge', labels: [] },
+  wm_agent_outbox_dropped_total: { type: 'counter', labels: [] },
+  wm_worktree_active: { type: 'gauge', labels: [] },
+  wm_worktree_cleaned_total: { type: 'counter', labels: [] },
+  wm_merge_queue_depth: { type: 'gauge', labels: ['project', 'branch'] },
+  wm_merge_conflict_total: { type: 'counter', labels: [] },
+  wm_merge_merged_total: { type: 'counter', labels: [] },
+  wm_project_events_total: { type: 'counter', labels: ['type'] },
+  wm_event_lag_ms: { type: 'histogram', labels: ['client'], buckets: DEFAULT_BUCKETS },
+  wm_sse_reconnects_total: { type: 'counter', labels: [] },
+  wm_lock_acquired_total: { type: 'counter', labels: ['kind'] },
+  wm_lock_conflict_total: { type: 'counter', labels: ['kind'] },
+  wm_lock_force_released_total: { type: 'counter', labels: [] },
+  wm_review_pending: { type: 'gauge', labels: [] },
+  wm_review_decision_total: { type: 'counter', labels: ['decision'] },
+  wm_review_latency_ms: { type: 'histogram', labels: [], buckets: DEFAULT_BUCKETS },
+  wm_notification_sent_total: { type: 'counter', labels: ['kind'] },
+  wm_notification_digest_total: { type: 'counter', labels: [] },
+  wm_notification_unread: { type: 'gauge', labels: [] },
+  wm_p2p_push_attempts_total: { type: 'counter', labels: [] },
+  wm_p2p_push_success_total: { type: 'counter', labels: [] },
+  wm_p2p_fallback_total: { type: 'counter', labels: [] },
+  wm_p2p_crypto_refusals_total: { type: 'counter', labels: [] },
+  wm_relay_restarts_total: { type: 'counter', labels: [] },
+});
+
+export class MetricsError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'MetricsError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const labelKey = (labels) => Object.keys(labels ?? {}).sort().map((name) => name + "=" + labels[name]).join(",");
+
+const escapeLabel = (value) => String(value).replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+
+export function normalizeLabels(name, labels) {
+  const definition = METRIC_DEFINITIONS[name];
+  if (definition === undefined) throw new MetricsError('UNKNOWN_METRIC', 'metric is not declared in METRIC_DEFINITIONS', { name });
+  const allowed = new Set(definition.labels);
+  const result = {};
+  for (const [key, value] of Object.entries(labels ?? {})) {
+    if (FORBIDDEN_LABELS.includes(key)) throw new MetricsError('FORBIDDEN_LABEL', 'high-cardinality label is not allowed', { name, label: key });
+    if (!allowed.has(key)) throw new MetricsError('UNKNOWN_LABEL', 'label is not declared for this metric', { name, label: key, allowed: definition.labels });
+    const text = String(value);
+    if (text === '' || text.length > 128 || /[\n\r]/.test(text)) throw new MetricsError('INVALID_LABEL_VALUE', 'label value must be 1..128 characters on one line', { name, label: key });
+    result[key] = text;
+  }
+  return result;
+}
+
+function labelsText(labels) {
+  const names = Object.keys(labels ?? {}).sort();
+  if (names.length === 0) return '';
+  return '{' + names.map((name) => name + '="' + escapeLabel(labels[name]) + '"').join(',') + '}';
+}
+
+export function createMetrics() {
+  const counters = new Map();
+  const gauges = new Map();
+  const histograms = new Map();
+  let seq = 0;
+
+  const ensure = (store, name) => {
+    if (!store.has(name)) store.set(name, new Map());
+    return store.get(name);
+  };
+
+  return {
+    /** Add to a counter. The increment must be a non-negative integer so a counter can never go backwards. */
+    inc(name, labels = {}, by = 1) {
+      const definition = METRIC_DEFINITIONS[name];
+      if (definition === undefined) throw new MetricsError('UNKNOWN_METRIC', 'metric is not declared', { name });
+      if (definition.type !== 'counter') throw new MetricsError('WRONG_METRIC_TYPE', 'not a counter', { name, type: definition.type });
+      if (!Number.isInteger(by) || by < 0) throw new MetricsError('INVALID_INCREMENT', 'counter increment must be a non-negative integer', { by });
+      const normalized = normalizeLabels(name, labels);
+      const map = ensure(counters, name);
+      const key = labelKey(normalized);
+      const current = map.get(key) ?? { labels: normalized, value: 0 };
+      current.value += by;
+      map.set(key, current);
+      return current.value;
+    },
+    /** Set a gauge to the current value. */
+    set(name, labels = {}, value) {
+      const definition = METRIC_DEFINITIONS[name];
+      if (definition === undefined) throw new MetricsError('UNKNOWN_METRIC', 'metric is not declared', { name });
+      if (definition.type !== 'gauge') throw new MetricsError('WRONG_METRIC_TYPE', 'not a gauge', { name, type: definition.type });
+      if (!Number.isFinite(value)) throw new MetricsError('INVALID_GAUGE_VALUE', 'gauge value must be finite', { value });
+      const normalized = normalizeLabels(name, labels);
+      ensure(gauges, name).set(labelKey(normalized), { labels: normalized, value });
+      return value;
+    },
+    /** Record one observation into a histogram. */
+    observe(name, labels = {}, valueMs) {
+      const definition = METRIC_DEFINITIONS[name];
+      if (definition === undefined) throw new MetricsError('UNKNOWN_METRIC', 'metric is not declared', { name });
+      if (definition.type !== 'histogram') throw new MetricsError('WRONG_METRIC_TYPE', 'not a histogram', { name, type: definition.type });
+      if (!Number.isFinite(valueMs) || valueMs < 0) throw new MetricsError('INVALID_OBSERVATION', 'observation must be a non-negative finite number', { value: valueMs });
+      const normalized = normalizeLabels(name, labels);
+      const map = ensure(histograms, name);
+      const key = labelKey(normalized);
+      const entry = map.get(key) ?? { labels: normalized, bucketCounts: definition.buckets.map(() => 0), sum: 0, count: 0 };
+      for (let index = 0; index < definition.buckets.length; index += 1) if (valueMs <= definition.buckets[index]) entry.bucketCounts[index] += 1;
+      entry.sum += valueMs;
+      entry.count += 1;
+      map.set(key, entry);
+      seq += 1;
+      return entry.count;
+    },
+    snapshot() {
+      const out = { counters: {}, gauges: {}, histograms: {} };
+      for (const [name, map] of counters) out.counters[name] = Object.fromEntries([...map.values()].map((entry) => [labelKey(entry.labels), { labels: { ...entry.labels }, value: entry.value }]));
+      for (const [name, map] of gauges) out.gauges[name] = Object.fromEntries([...map.values()].map((entry) => [labelKey(entry.labels), { labels: { ...entry.labels }, value: entry.value }]));
+      for (const [name, map] of histograms) {
+        const definition = METRIC_DEFINITIONS[name];
+        out.histograms[name] = [...map.values()].map((entry) => ({ labels: { ...entry.labels }, count: entry.count, sum: entry.sum, buckets: definition.buckets.map((le, index) => ({ le, count: entry.bucketCounts[index] })) }));
+      }
+      return out;
+    },
+    renderPrometheus() {
+      const lines = [];
+      for (const [name, map] of counters) {
+        lines.push('# TYPE ' + name + ' counter');
+        for (const entry of map.values()) lines.push(name + labelsText(entry.labels) + ' ' + entry.value);
+      }
+      for (const [name, map] of gauges) {
+        lines.push('# TYPE ' + name + ' gauge');
+        for (const entry of map.values()) lines.push(name + labelsText(entry.labels) + ' ' + entry.value);
+      }
+      for (const [name, map] of histograms) {
+        const definition = METRIC_DEFINITIONS[name];
+        lines.push('# TYPE ' + name + ' histogram');
+        for (const entry of map.values()) {
+          for (let index = 0; index < definition.buckets.length; index += 1) lines.push(name + "_bucket" + labelsText({ ...entry.labels, le: String(definition.buckets[index]) }) + " " + entry.bucketCounts[index]);
+          lines.push(name + "_bucket" + labelsText({ ...entry.labels, le: "+Inf" }) + " " + entry.count);
+          lines.push(name + "_sum" + labelsText(entry.labels) + " " + entry.sum);
+          lines.push(name + "_count" + labelsText(entry.labels) + " " + entry.count);
+        }
+      }
+      return lines.join('\n') + '\n';
+    },
+    size() { return { counters: counters.size, gauges: gauges.size, histograms: histograms.size, observations: seq }; },
+  };
+}