@adhdev/mesh-shared 1.0.60-rc.7 → 1.0.60-rc.70

package/dist/types.d.ts

@@ -136,4 +136,15 @@ export interface RepoMeshSessionStatus {
     startedAt?: string | null;
     lastActivityAt?: string | null;
     isCached?: boolean;
+    /**
+     * Worker MCP delivery outcome for this session's launch (present only for a
+     * mesh-delegated launch). `reason` is a short enum code, never free text —
+     * see `WORKER_MCP_DELIVERY_REASONS` (daemon-core's `mesh/worker-mcp-isolation.ts`,
+     * the source of the vocabulary this field's values are drawn from; not
+     * re-exported here so mesh-shared stays a dependency-free leaf).
+     */
+    workerMcp?: {
+        delivered: boolean;
+        reason?: string;
+    };
 }

package/dist/worker-protocol.d.ts

@@ -0,0 +1,69 @@
+/**
+ * worker-protocol — what a delegated worker is told, and what it may call.
+ *
+ * Wiring-unification Phase F1 (docs/design/2026-09-23-wiring-unification.md §7b).
+ *
+ * Measured 2026-09-23 on the live preview ledger: 635 worker attempts in 14
+ * days, 3 `report_completion` calls. The worker MCP was delivered to every
+ * provider and never used, because nothing ever told the worker it existed —
+ * the dispatched task body carried no instruction and the coordinator prompt
+ * did not mention the worker tools at all. The only text a worker saw about
+ * its tools was the tool description.
+ *
+ * This module is the single source for BOTH sides of that contract:
+ *   - `WORKER_TOOLS` — exactly what `adhdev mcp --mode worker` advertises
+ *     (a parity test in mcp-server pins ListTools to this tuple);
+ *   - `renderWorkerProtocolFooter()` — the block appended to EVERY dispatched
+ *     task body, so a worker learns the protocol from the task itself;
+ *   - `renderCoordinatorWorkerSection()` — the matching paragraph the
+ *     coordinator prompt carries, so the coordinator expects structured reports
+ *     and stops polling for them.
+ *
+ * Wiring-unification Phase H2 adds an optional mission-brief block: when a
+ * dispatched task belongs to a mission that carries a `MissionBrief`
+ * (`./mission-brief.ts`), `renderWorkerProtocolFooter` renders it ABOVE the
+ * `WORKER_PROTOCOL_FOOTER_MARKER` line. This is deliberate placement, not an
+ * accident of insertion order: `hasWorkerProtocolFooter` / `stripWorkerProtocolFooter`
+ * both key off the marker line alone, so a body with a brief block strips
+ * identically to one without — the brief is authored content from the
+ * coordinator's point of view (like the task message itself), never part of
+ * the protocol contract the marker demarcates.
+ */
+import { type MissionBrief } from './mission-brief';
+export declare const WORKER_TOOLS: readonly ["report_completion", "progress_update", "peer_context_pull", "git_status", "git_log", "git_diff"];
+export type WorkerTool = typeof WORKER_TOOLS[number];
+export declare function isWorkerTool(value: unknown): value is WorkerTool;
+/** Stable marker line so a body is never footered twice and tests can find it. */
+export declare const WORKER_PROTOCOL_FOOTER_MARKER = "--- adhdev worker protocol ---";
+export interface WorkerProtocolFooterInput {
+    taskId?: string;
+    taskMode?: string;
+    difficulty?: string;
+    readonly?: boolean;
+    /** Number of handoff notes enclosed above the footer, when any. */
+    enclosedHandoffNotes?: number;
+    /** H2: the owning mission's brief, when this task belongs to one. Rendered above the marker line — see module doc. */
+    missionBrief?: MissionBrief;
+}
+export declare function hasWorkerProtocolFooter(body: string): boolean;
+/**
+ * The protocol block appended to a dispatched task. Written for the model that
+ * receives it: imperative, short, and explicit about what is NOT available so
+ * the worker does not go looking for coordinator tools.
+ */
+export declare function renderWorkerProtocolFooter(input?: WorkerProtocolFooterInput): string;
+/**
+ * The authored text of a dispatched body: everything before the footer marker.
+ * Ledger descriptors, replay fixtures and tests compare authored text, never
+ * the protocol block.
+ */
+export declare function stripWorkerProtocolFooter(body: string): string;
+/**
+ * Append the footer to a body that does not carry one yet. Idempotent.
+ */
+export declare function appendWorkerProtocolFooter(body: string, input?: WorkerProtocolFooterInput): string;
+/**
+ * The paragraph the COORDINATOR prompt carries about its workers. Kept next to
+ * the footer so the two halves of the protocol cannot drift apart.
+ */
+export declare function renderCoordinatorWorkerSection(): string;

package/dist/ws-protocol.d.ts

@@ -1,50 +1,80 @@
 /**
- * ws-protocol — shared string-literal unions for the daemon↔server WS surface
- * and the daemon↔dashboard P2P DataChannel surface.
+ * ws-protocol — name-only aliases for the daemon↔server WS surface and the
+ * daemon↔dashboard P2P DataChannel surface, plus the `auth_ok.payload.limits`
+ * contract.
  *
- * Fragmentation audit: these message types existed as a TypeScript union in
- * exactly ONE package (the proprietary daemon-cloud's server-connection.ts),
- * which is a leaf CONSUMER — the other two participants (the Workers server
- * and OSS daemon-core, which is the primary `status_report` producer) matched
- * bare string literals by hand. Renaming `auth_ok` server-side would compile
- * everywhere and leave the daemon reconnecting forever. Pure literals, zero
- * runtime deps — the textbook mesh-shared leaf.
- *
- * SCOPE HONESTY: this file declares the OSS-visible protocol surface. The
- * proprietary repo's server-connection.ts remains the authority for the full
- * ServerToDaemon command set; it should adopt these unions and extend them
- * (`ServerToDaemonMsg | <proprietary extras>`) rather than re-declaring the
- * shared members. Members here are the ones OSS daemon-core itself produces
- * or matches.
+ * Wiring-unification Phase A2: the typed frame unions now live in ./protocol
+ * (one file per link, payloads included). This file keeps the symbols that
+ * pre-dated them — `DaemonToServerWsMsg`, `ServerToDaemonWsMsg`,
+ * `P2PSignalingWsMsg`, `DashboardP2PMessageKind` and the two name arrays —
+ * DERIVED from the protocol unions rather than re-declared, so they cannot
+ * drift again. Before this derivation the list here said `offer|answer|ice`
+ * while the wire said `p2p_offer|p2p_answer|p2p_ice`, declared a `log` frame
+ * nothing sent or handled, omitted `daemon_mesh_command` (sent by a raw
+ * `ws.send`), and listed 12 of the ~27 P2P kinds — and nothing imported the
+ * drifted members, so nothing noticed.
  */
-/** Messages the daemon sends UP to the Workers server over the WS bridge. */
-export type DaemonToServerWsMsg = 'auth' | 'status_report' | 'status_heartbeat' | 'status_event' | 'command_result' | 'error' | 'agent_event' | 'log'
+import { type DaemonToServerType, type ServerToDaemonControlType, type P2PSignalType, type MeshP2PSignalType, type DashboardToDaemonP2PType, type DaemonToDashboardP2PType } from './protocol';
+/** Messages the daemon sends UP to the Workers server over the WS bridge (see protocol/daemon-server.ts). */
+export type DaemonToServerWsMsg = DaemonToServerType;
 /**
- * seqscribe Beacon vectors (design §7.1). ONE daemon-initiated frame carries
- * both directions — `op: 'put'` stores this node's content-free vector
- * report, `op: 'get'` asks for the board — because the server has no way to
- * wake itself: `DaemonConnectionDO` has neither an alarm nor a timer, and
- * adding one would hit the most request-quota-pressured axis in the system.
+ * Server→daemon CONTROL messages (see protocol/daemon-server.ts). The server
+ * additionally relays an open command namespace as the frame `type`
+ * (`ServerDirectCommandMsg`), which is deliberately not a member here.
  */
- | 'beacon_vectors';
-/** Server→daemon control messages the OSS engine reacts to. */
-export type ServerToDaemonWsMsg = 'auth_ok' | 'auth_error' | 'machine_evicted' | 'force_disconnect' | 'token_revoked' | 'version_mismatch' | 'force_update_required' | 'command' | 'agent_command' | 'resolve_action'
+export type ServerToDaemonWsMsg = ServerToDaemonControlType;
+/** P2P signaling relayed through the server WS — the `p2p_`/`mesh_p2p_` spellings the wire actually uses. */
+export type P2PSignalingWsMsg = P2PSignalType | MeshP2PSignalType;
+/** Every dashboard↔daemon P2P DataChannel JSON kind, both directions (see protocol/dashboard-daemon-p2p.ts). */
+export type DashboardP2PMessageKind = DashboardToDaemonP2PType | DaemonToDashboardP2PType;
+export declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
+export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
+export declare const isDaemonToServerWsMsg: (value: unknown) => value is DaemonToServerWsMsg;
+export declare const isServerToDaemonWsMsg: (value: unknown) => value is ServerToDaemonWsMsg;
 /**
- * Reply to a `beacon_vectors` GET, correlated by `requestId`. A PUT is
- * fire-and-forget and gets no reply at all — the beacon is advisory, so a
- * lost report costs one debounce cycle of prediction accuracy and nothing
- * else, which is not worth an ack round trip.
+ * `auth_ok.payload.limits` — the plan-limit contract the server sends DOWN to
+ * the daemon for client-side enforcement.
+ *
+ * WHY THIS EXISTS: the wire spelling is `maxP2Pconnections` (lowercase `c`),
+ * inherited from `PlanLimits` in the proprietary server's plan-limits.ts. The
+ * daemon-cloud consumer independently declared the same field as
+ * `maxP2PConnections` (capital `C`) and assigned it from a `payload as any`
+ * cast — so the two spellings NEVER met under a type, TypeScript had nothing
+ * to compare, and the limit arrived as `undefined` at every comparison site.
+ * `undefined !== -1` passes the "is it unlimited?" guard, then every
+ * `count >= undefined` is false: enforcement silently degraded to unlimited on
+ * all plans, in production, for months.
+ *
+ * The lesson is NOT "pick a spelling" — it is that a cross-package wire
+ * contract asserted by hand on both ends with an `any` in between cannot fail
+ * loudly. Both producer (server) and consumer (daemon-cloud) must now import
+ * THIS symbol, so a rename breaks the build on both sides instead of silently
+ * disabling a paid-plan limit. Use `normalizeAuthOkLimits()` at the parse
+ * boundary; never re-spell these fields locally.
  */
- | 'beacon_vectors_result';
-/** P2P signaling relayed through the server WS. */
-export type P2PSignalingWsMsg = 'p2p_ready' | 'offer' | 'answer' | 'ice' | 'mesh_p2p_ready' | 'mesh_p2p_offer' | 'mesh_p2p_answer' | 'mesh_p2p_ice';
+export interface AuthOkPlanLimits {
+    /** P2P concurrent connection count (-1 = unlimited). WIRE SPELLING — lowercase `c`. */
+    maxP2Pconnections: number;
+    /** Screenshot send interval floor (seconds). 0 = real-time. */
+    screenshotIntervalSeconds: number;
+    /** Daily screenshot usage budget (minutes). -1 = unlimited. */
+    dailyScreenshotMinutes: number;
+    /** Max connectable machines/daemons (-1 = unlimited). */
+    maxMachines: number;
+}
 /**
- * Dashboard↔daemon P2P DataChannel JSON message kinds. Previously matched as
- * hand-synced literals on both ends with NO shared symbol anywhere —
- * `p2p_evicted` had exactly two occurrences repo-wide (emit + handle).
+ * Parse-boundary normalizer for `auth_ok.payload.limits`.
+ *
+ * Returns `null` when the payload carries no usable limits object, so callers
+ * keep their existing "no limits known yet" branch. Individual non-numeric or
+ * missing fields fall back to the UNLIMITED sentinel (-1) for count-style
+ * limits and 0 for the interval floor, matching how each consumer already
+ * treats "no constraint" — a malformed field must never be coerced to a
+ * MORE restrictive value than the server intended, or a server-side schema
+ * change would start throttling paying users.
+ *
+ * Accepts the capital-`C` misspelling as an input alias ONLY so a daemon
+ * talking to a mixed-version fleet cannot regress; output is always the
+ * canonical wire spelling.
  */
-export type DashboardP2PMessageKind = 'ping' | 'pong' | 'status_report' | 'status_event' | 'p2p_evicted' | 'command' | 'command_result' | 'command_result_chunk' | 'screenshot_start' | 'screenshot_stop' | 'pty_input' | 'pty_resize';
-export declare const DAEMON_TO_SERVER_WS_MSGS: readonly DaemonToServerWsMsg[];
-export declare const SERVER_TO_DAEMON_WS_MSGS: readonly ServerToDaemonWsMsg[];
-export declare function isDaemonToServerWsMsg(value: unknown): value is DaemonToServerWsMsg;
-export declare function isServerToDaemonWsMsg(value: unknown): value is ServerToDaemonWsMsg;
+export declare function normalizeAuthOkLimits(raw: unknown): AuthOkPlanLimits | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/mesh-shared",
-  "version": "1.0.60-rc.7",
+  "version": "1.0.60-rc.70",
   "description": "ADHDev mesh-shared — pure mesh/git status normalizers shared by daemon-core and web-core",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/brain-routing.ts

@@ -66,7 +66,7 @@ export function isMeshTaskDifficulty(value: unknown): value is MeshTaskDifficult
  *      a value that should never have been stamped provider-blind.
  *
  *   2. IT FOUGHT THE SLOTS. Operators express model choice per node via
- *      capability slots (`mesh_node_slots_set`), which know the provider. A
+ *      capability slots (`mesh_node_slots` action "set"), which know the provider. A
  *      mesh-wide preset that also picks a model duplicated that decision from a
  *      position with strictly less information, and needed the modelSource
  *      ('explicit' vs 'preset') precedence machinery plus a fail-closed
@@ -112,7 +112,7 @@ export function normalizeDifficultyBrainMap(raw: unknown): DifficultyBrainMap {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Node capability slots (ORCHESTRATION_NODE_SLOTS.md)
+// Node capability slots (node capability slots design, 2026-07-09)
 //
 // A node's "Preferred AI tools" list is redefined as an ordered array of
 // capability slots. Each slot bundles what used to be scattered across
@@ -252,7 +252,7 @@ export function deriveSlotsFromLegacy(input: {
  * The reverse direction of deriveSlotsFromLegacy: derive the legacy
  * `providerPriority` order from capability slots — each slot's provider, in
  * first-appearance order, de-duplicated. Slot order = preference is the settled
- * slots semantics (ORCHESTRATION_NODE_SLOTS.md), so this is what readers of the
+ * slots semantics (node capability slots design, 2026-07-09), so this is what readers of the
  * legacy `policy.providerPriority` field must fall back to when a node declares
  * slots but no explicit providerPriority (otherwise such a node reads as
  * unlaunchable even though its slots fully determine the preference order).

package/src/index.ts

@@ -29,3 +29,15 @@ export * from './rpc-chunking'
 export * from './semver-compare'
 export * from './ws-protocol'
 export * from './interactive-prompt-constants'
+export * from './session-status'
+export * from './mesh-vocabulary'
+export * from './outbound-message'
+export * from './worker-protocol'
+export * from './protocol'
+export * from './turn-evidence'
+export * from './session-launch'
+export * from './turn-ipc'
+export * from './path-ownership'
+export * from './mission-brief'
+export * from './keyed-status-delta'
+export * from './keyed-doc-delta'

package/src/keyed-doc-delta.ts

@@ -0,0 +1,348 @@
+/**
+ * Keyed document delta — the diff/fold pair behind the `mesh.status` lane
+ * (the dashboard's mesh view; data-path audit 2026-09-29 P1-5).
+ *
+ * A document is plain top-level fields plus named keyed COLLECTIONS (arrays of
+ * rows identified by an id field, possibly nested one object deep, e.g.
+ * `queue.tasks`). The daemon digests every body it would have sent, diffs it
+ * against the digest of the last body DELIVERED to a subscription, and sends
+ * only the difference: changed top-level fields, and per collection the rows
+ * whose content changed (changed fields only), the fields a row lost, and the
+ * rows that disappeared. An unchanged document diffs to `null` — zero bytes on
+ * the wire. The dashboard folds each delta into its held snapshot; the fold of
+ * every delta since a snapshot equals the latest snapshot (pinned by
+ * keyed-doc-delta.test.ts).
+ *
+ * `volatileTopLevel` fields (a build stamp, live process counters) are not a
+ * change by themselves; when something else changed they ride along.
+ *
+ * Pure leaf: plain objects in, plain objects out; no transport, no clock.
+ */
+
+export interface KeyedDocSpec {
+    /** Collection path (`nodes`, `queue.tasks`) → the id field of its rows. */
+    collections: Readonly<Record<string, string>>
+    /** Top-level fields that change on every build without meaning anything. */
+    volatileTopLevel?: readonly string[]
+    /**
+     * The part of a collection row that decides whether it CHANGED (drop the
+     * per-build stamps inside it). A row whose stable view is unchanged sends
+     * nothing; a changed field is sent with its full current value, stamps
+     * included. Must not mutate `row`.
+     */
+    stableRow?: (collection: string, row: Record<string, unknown>) => Record<string, unknown>
+}
+
+type Row = Record<string, unknown>
+
+interface RowDigest {
+    readonly value: Row
+    /** The row as compared (stableRow view). */
+    readonly stable: Row
+    readonly sig: string
+    fieldSigs?: Map<string, string>
+}
+
+interface CollectionDigest {
+    readonly rows: ReadonlyMap<string, RowDigest>
+    readonly order: readonly string[]
+}
+
+export interface KeyedDocDigest {
+    readonly top: ReadonlyMap<string, string>
+    readonly topValues: Readonly<Record<string, unknown>>
+    readonly collections: ReadonlyMap<string, CollectionDigest>
+    readonly volatile: ReadonlySet<string>
+}
+
+export interface KeyedCollectionDelta {
+    /** New rows (whole) and changed rows (id + changed fields). */
+    upsert?: Row[]
+    /** Fields a row lost, by row id. */
+    unsetFields?: Record<string, string[]>
+    removed?: string[]
+    order?: string[]
+    /** The collection is no longer present in the document at all. */
+    absent?: true
+}
+
+export interface KeyedDocDelta {
+    set?: Record<string, unknown>
+    unset?: string[]
+    collections?: Record<string, KeyedCollectionDelta>
+}
+
+function sig(value: unknown): string | undefined {
+    if (value === undefined) return undefined
+    try {
+        return JSON.stringify(value)
+    } catch {
+        return undefined
+    }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Read the array at `path` (`a` or `a.b`) — undefined when absent. */
+function readPath(doc: Record<string, unknown>, path: string): unknown {
+    const [head, tail] = splitPath(path)
+    if (!tail) return doc[head]
+    const parent = doc[head]
+    return isRecord(parent) ? parent[tail] : undefined
+}
+
+function splitPath(path: string): [string, string | undefined] {
+    const dot = path.indexOf('.')
+    return dot < 0 ? [path, undefined] : [path.slice(0, dot), path.slice(dot + 1)]
+}
+
+/**
+ * The document minus its collections (a nested collection is removed from a
+ * shallow copy of its parent, so the parent's other fields stay top-level data).
+ */
+function stripCollections(doc: Record<string, unknown>, spec: KeyedDocSpec): Record<string, unknown> {
+    const out: Record<string, unknown> = { ...doc }
+    for (const path of Object.keys(spec.collections)) {
+        const [head, tail] = splitPath(path)
+        if (!tail) {
+            delete out[head]
+            continue
+        }
+        const parent = out[head]
+        if (!isRecord(parent) || !(tail in parent)) continue
+        const copy = { ...parent }
+        delete copy[tail]
+        out[head] = copy
+    }
+    return out
+}
+
+function fieldSigsOf(digest: RowDigest): Map<string, string> {
+    if (!digest.fieldSigs) {
+        const sigs = new Map<string, string>()
+        for (const [key, value] of Object.entries(digest.stable)) {
+            const s = sig(value)
+            if (s !== undefined) sigs.set(key, s)
+        }
+        digest.fieldSigs = sigs
+    }
+    return digest.fieldSigs
+}
+
+/** Digest one document. Cheap to hold: values are referenced, not copied. */
+export function digestKeyedDoc(doc: Record<string, unknown>, spec: KeyedDocSpec): KeyedDocDigest {
+    const top = new Map<string, string>()
+    const topValues: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(stripCollections(doc, spec))) {
+        const s = sig(value)
+        if (s === undefined) continue
+        top.set(key, s)
+        topValues[key] = value
+    }
+    const collections = new Map<string, CollectionDigest>()
+    for (const [path, idField] of Object.entries(spec.collections)) {
+        const list = readPath(doc, path)
+        if (!Array.isArray(list)) continue
+        const rows = new Map<string, RowDigest>()
+        const order: string[] = []
+        for (const row of list) {
+            if (!isRecord(row)) continue
+            const id = row[idField]
+            if (typeof id !== 'string' || !id || rows.has(id)) continue
+            const stable = spec.stableRow ? spec.stableRow(path, row) : row
+            rows.set(id, { value: row, stable, sig: sig(stable) ?? '' })
+            order.push(id)
+        }
+        collections.set(path, { rows, order })
+    }
+    return { top, topValues, collections, volatile: new Set(spec.volatileTopLevel ?? []) }
+}
+
+function sameOrder(a: readonly string[], b: readonly string[]): boolean {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false
+    return true
+}
+
+function diffCollection(prev: CollectionDigest | undefined, next: CollectionDigest | undefined, idField: string): KeyedCollectionDelta | null {
+    if (!next) return prev ? { absent: true } : null
+    const delta: KeyedCollectionDelta = {}
+    const prevRows = prev?.rows ?? new Map<string, RowDigest>()
+    const nextRows = next?.rows ?? new Map<string, RowDigest>()
+    for (const [id, nextRow] of nextRows) {
+        const prevRow = prevRows.get(id)
+        if (!prevRow) {
+            ;(delta.upsert ??= []).push(nextRow.value)
+            continue
+        }
+        if (prevRow.sig === nextRow.sig) continue
+        const prevSigs = fieldSigsOf(prevRow)
+        const nextSigs = fieldSigsOf(nextRow)
+        const change: Row = { [idField]: id }
+        let changed = false
+        for (const [key, s] of nextSigs) {
+            if (key === idField || prevSigs.get(key) === s) continue
+            change[key] = nextRow.value[key]
+            changed = true
+        }
+        const gone: string[] = []
+        for (const key of prevSigs.keys()) if (!nextSigs.has(key) && !(key in nextRow.value)) gone.push(key)
+        if (changed) (delta.upsert ??= []).push(change)
+        if (gone.length > 0) (delta.unsetFields ??= {})[id] = gone
+    }
+    for (const id of prevRows.keys()) {
+        if (!nextRows.has(id)) (delta.removed ??= []).push(id)
+    }
+    if (!sameOrder(prev?.order ?? [], next?.order ?? [])) delta.order = [...(next?.order ?? [])]
+    return Object.keys(delta).length > 0 ? delta : null
+}
+
+/**
+ * The difference `prev → next`, or `null` when nothing a consumer can observe
+ * changed (volatile top-level fields alone are not a change).
+ */
+export function diffKeyedDoc(prev: KeyedDocDigest, next: KeyedDocDigest, spec: KeyedDocSpec): KeyedDocDelta | null {
+    const delta: KeyedDocDelta = {}
+    let meaningful = false
+    let set: Record<string, unknown> | undefined
+    let unset: string[] | undefined
+    for (const [key, s] of next.top) {
+        if (prev.top.get(key) === s) continue
+        ;(set ??= {})[key] = next.topValues[key]
+        if (!next.volatile.has(key)) meaningful = true
+    }
+    for (const key of prev.top.keys()) {
+        if (next.top.has(key)) continue
+        ;(unset ??= []).push(key)
+        if (!next.volatile.has(key)) meaningful = true
+    }
+    for (const [path, idField] of Object.entries(spec.collections)) {
+        const change = diffCollection(prev.collections.get(path), next.collections.get(path), idField)
+        if (!change) continue
+        ;(delta.collections ??= {})[path] = change
+        meaningful = true
+    }
+    if (!meaningful) return null
+    if (set) delta.set = set
+    if (unset) delta.unset = unset
+    return delta
+}
+
+function foldCollection(held: unknown, change: KeyedCollectionDelta, idField: string): Row[] {
+    const byId = new Map<string, Row>()
+    const heldOrder: string[] = []
+    for (const row of Array.isArray(held) ? held : []) {
+        if (!isRecord(row) || typeof row[idField] !== 'string') continue
+        byId.set(row[idField] as string, row)
+        heldOrder.push(row[idField] as string)
+    }
+    for (const id of change.removed ?? []) byId.delete(id)
+    for (const row of change.upsert ?? []) {
+        const id = row[idField]
+        if (typeof id !== 'string') continue
+        const base = byId.get(id)
+        byId.set(id, base ? { ...base, ...row } : { ...row })
+    }
+    for (const [id, keys] of Object.entries(change.unsetFields ?? {})) {
+        const base = byId.get(id)
+        if (!base) continue
+        const trimmed = { ...base }
+        for (const key of keys) delete trimmed[key]
+        byId.set(id, trimmed)
+    }
+    const order = change.order ?? heldOrder
+    const out: Row[] = []
+    const placed = new Set<string>()
+    for (const id of order) {
+        const row = byId.get(id)
+        if (!row || placed.has(id)) continue
+        out.push(row)
+        placed.add(id)
+    }
+    for (const [id, row] of byId) if (!placed.has(id)) out.push(row)
+    return out
+}
+
+/** Rebuild the full document from a held one plus a delta. Never mutates `held`. */
+export function foldKeyedDoc<T extends Record<string, unknown>>(held: T, delta: KeyedDocDelta, spec: KeyedDocSpec): T {
+    // Collections are re-inserted below from the held ones, so the plain fields
+    // are folded on the stripped view (a nested parent keeps its other fields).
+    const heldCollections = new Map<string, unknown>()
+    for (const path of Object.keys(spec.collections)) heldCollections.set(path, readPath(held, path))
+    const next: Record<string, unknown> = stripCollections(held, spec)
+    for (const key of delta.unset ?? []) delete next[key]
+    Object.assign(next, delta.set ?? {})
+    for (const [path, idField] of Object.entries(spec.collections)) {
+        const change = delta.collections?.[path]
+        const heldList = heldCollections.get(path)
+        if (change?.absent) {
+            const [head, tail] = splitPath(path)
+            if (!tail) delete next[head]
+            continue
+        }
+        if (!change && heldList === undefined) continue
+        const list = change ? foldCollection(heldList, change, idField) : heldList
+        const [head, tail] = splitPath(path)
+        if (!tail) {
+            next[head] = list
+            continue
+        }
+        const parent = isRecord(next[head]) ? { ...(next[head] as Record<string, unknown>) } : {}
+        parent[tail] = list
+        next[head] = parent
+    }
+    return next as T
+}
+
+/**
+ * The `mesh.status` document: nodes keyed by `nodeId`, queue tasks and missions
+ * by `id`. `refreshedAt` and `sourceOfTruth` (its aggregate-cache age /
+ * returnedAt) are per-call stamps and the counters are live process tallies —
+ * none of them is a change by itself.
+ */
+export const MESH_STATUS_DOC_SPEC: KeyedDocSpec = {
+    collections: { nodes: 'nodeId', 'queue.tasks': 'id', missions: 'id' },
+    volatileTopLevel: [
+        'refreshedAt', 'sourceOfTruth',
+        'turnPresentationCounters', 'meshProtocolV2Counters', 'pendingRetentionCounters', 'meshProtocolMetrics',
+    ],
+    stableRow: (collection, row) => (collection === 'nodes' ? stableMeshNodeRow(row) : row),
+}
+
+function without(value: unknown, keys: readonly string[]): unknown {
+    if (!isRecord(value)) return value
+    const out = { ...value }
+    for (const key of keys) delete out[key]
+    return out
+}
+
+/**
+ * A mesh node minus the stamps an aggregate rebuild re-derives from the clock
+ * (last-seen / updated / freshness age, the local read's check time, a local
+ * facts bundle's reportedAt). A REMOTE node's `gitObservation.observedAt` is
+ * real news (the member's own check time — the dashboard's "aged" hint) and
+ * is compared; the coordinator's own / local checkout's is its read time.
+ */
+function stableMeshNodeRow(row: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = { ...row }
+    delete out.lastSeenAt
+    delete out.updatedAt
+    delete out.last_seen_at
+    delete out.updated_at
+    if ('dataFreshness' in out) out.dataFreshness = without(out.dataFreshness, ['ageMs', 'lastProbeAt', 'staleness'])
+    if ('connection' in out) out.connection = without(out.connection, ['lastStateChangeAt'])
+    if ('git' in out) {
+        const git = without(out.git, ['lastCheckedAt'])
+        // "No submodules" is the same fact whether a read listed none or skipped the scan.
+        if (isRecord(git) && Array.isArray(git.submodules) && git.submodules.length === 0) delete git.submodules
+        out.git = git
+    }
+    if ('nodeFacts' in out) out.nodeFacts = without(out.nodeFacts, ['reportedAt'])
+    const observation = out.gitObservation
+    if (isRecord(observation) && (observation.source === 'self' || observation.source === 'local')) {
+        out.gitObservation = without(observation, ['observedAt'])
+    }
+    return out
+}