claudemesh/.artifacts/shipped/2026-05-03-daemon-spec-broker-hardening-followups.md

# `claudemesh daemon` — broker-hardening followups

> **Purpose**: refinements found during the v6 → v10 codex review series
> that are real improvements but **not** v0.9.0 blockers. The
> implementation target is `2026-05-03-daemon-spec-v0.9.0.md`. This
> document lists what was deferred, why, and the trigger that promotes
> each item to "must-do."
>
> **Background**: codex reviewed the daemon spec across 9 rounds (v1
> through v10). Rounds 1–4 found load-bearing architectural issues
> (identity, IPC auth, exactly-once lie, hook tokens, rotation, etc.).
> Rounds 5–9 found progressively finer correctness issues inside one
> subsystem (broker idempotency mechanics). v6 closed the architectural
> review; v7–v10 are increasingly fine-grained idempotency-correctness
> shavings on the same layer. Pre-launch (no users) doesn't need v7–v10
> level rigor. We pulled the cheap wins into v0.9.0; the rest waits.

---

## 1. B0 dedupe fast-path before rate-limit (v10)

**What v10 said**: read `mesh.client_message_dedupe` BEFORE consulting
the rate limiter. Existing id (match or mismatch) returns immediately
without touching rate-limit budget.

**Why deferred**: v0.9.0 doesn't have meaningful rate-limit pressure on
the daemon path. The split-brain failure (broker accepted, daemon
believes failure due to rate-limit-rejection-on-retry) requires
sustained saturated rate-limit windows, which don't exist pre-launch.

**Promote when**: any single mesh sees rate-limit rejections AND has
daemon retries against committed ids. Telemetry to watch:
`cm_broker_rate_limit_rejection_total` per mesh > 0 sustained.

**Implementation cost**: small — one indexed PK lookup before the
existing limiter call. The work is mostly testing the race semantics.

---

## 2. Lua-scripted idempotent rate limiter (v10)

**What v10 said**: limiter keyed by `(mesh_id, client_message_id,
window_bucket)` so retries-within-window consume budget at most once.

**Why deferred**: depends on (1) above. Without B0 fast-path this is
incremental complexity for marginal benefit. With B0 it becomes the
right belt-and-suspenders fix for the rare race where two same-id
requests both miss B0 simultaneously.

**Promote when**: B0 ships. Same trigger.

**Implementation cost**: medium — Lua script in Redis, careful TTL
tuning, integration with existing limiter call sites.

---

## 3. In-tx `mesh.mention_index` (v8)

**What v8 said**: mention-fanout index updates should commit inside the
broker accept transaction so mention-search reads can never see a
mention pointing at an uncommitted message.

**Why deferred**: the lag between accept-commit and async
mention-indexer is small (single-digit milliseconds in expected
deployment). Stale-read window during mention search is acceptable for
v0.9.0; receivers learn of mentions via the `mention` event in their
inbox stream regardless.

**Promote when**: real users complain about "I was mentioned but the
mention search doesn't show it" with reproducible cases that don't
self-heal in seconds.

**Implementation cost**: small — add `INSERT INTO mesh.mention_index`
to the accept transaction. The async indexer becomes a backfill
fallback rather than the primary path.

---

## 4. 4011 / 4012 close-code split (v6 §15.5)

**What v6 said**: split `4010 feature_unavailable` into three codes:
`4010` (missing), `4011` (params invalid), `4012` (params below floor).

**Why deferred**: v0.9.0 ships single `4010` with structured
`close_reason` JSON containing `kind`, `feature`, `detail`. Same
diagnostic information, simpler protocol surface.

**Promote when**: ops tooling or external monitoring needs distinct
status codes (e.g. PagerDuty rules that fire on 4012-only). Probably
never; structured JSON is parseable.

**Implementation cost**: trivial — three constants and a switch on
`close_reason.kind`.

---

## 5. Per-OS fingerprint precedence elaborate table (v8 §2.2.1)

**What v8 said**: comprehensive per-OS table covering Linux machine-id
sources, macOS `IOPlatformUUID`, Windows `MachineGuid`, BSD
`kern.hostuuid`, plus interface exclusion rules.

**Why deferred**: v0.9.0 ships with the simpler "machine-id ||
first-stable-mac" rule from v6. Edge cases (cloud images,
machine-id-not-readable, etc.) are documented when first hit.

**Promote when**: operators report fingerprint false-positives we can't
explain from the v6 rule. Each report adds one row to the per-OS
table.

**Implementation cost**: incremental — each OS-specific source is a
small probe function with a fallback chain.

---

## 6. `request_fingerprint` schema-version-2 in feature negotiation (v6 §15.1)

**What v6 said**: `client_message_id_dedupe` feature parameters
versioned independently. v0.9.0 ships at version 1 with a single
`request_fingerprint: bool` flag.

**Why deferred**: we don't yet need parameterized fingerprint variants
(different canonical forms, different hash algos). Version-bump path
is documented; we'll use it when we add the second fingerprint mode.

**Promote when**: we want a fingerprint algo other than sha256/JCS
(e.g. a faster hash, or a normalized canonical form).

**Implementation cost**: small — single feature-bit version bump
following the documented pattern.

---

## 7. Force-expiry / quarantine semantics for `keypair-archive.json` (v8 §14.1.1)

**What v8 said**: `max_archived_keys` cap with force-expiry; explicit
quarantine of malformed archive (`keypair-archive.json.malformed-<ts>`);
duplicate `key_id` rejection; mode-mismatch warning behavior.

**Why deferred**: v0.9.0 ships the simpler v6 rule — drop expired
entries on cleanup pass; refuse to start on malformed archive (loud,
operator-actionable). The v8 elaboration makes archive corruption
non-blocking, which is operationally nicer but trades off audit
clarity.

**Promote when**: a real operator hits an archive corruption that
shouldn't have brought the daemon down (e.g. mid-rotation crash leaves
a partially-written archive).

**Implementation cost**: small — quarantine logic + one extra startup
check.

---

## 8. Cross-language JCS conformance for `request_fingerprint` (v6 §4.4 round-6 question)

**What v6 asked**: does JCS work cross-language for
`meta_canonical_json`? Python json.dumps, Go encoding/json, and JS
JSON.stringify all behave differently. Should we ship a vetted JCS lib
in each SDK?

**Why deferred from v0.9.0**: the daemon ships in TypeScript only for
v0.9.0 (the `claudemesh-cli` package). Single-language JCS is trivial.
SDK ports come post-v0.9.0.

**Promote when**: we ship the Python or Go SDK. Each SDK port gets a
JCS conformance test against a corpus of envelopes.

**Implementation cost**: small per-language — a conformance fixture
file and a unit test.

---

## Sprint 7 (this session) — what landed vs deferred

**Landed in code** (not yet deployed):
- `packages/db/migrations/0028_message_queue_idempotency_fields.sql` adds
  nullable `client_message_id` and `request_fingerprint` columns to
  `mesh.message_queue` (additive, online-safe).
- `apps/broker/src/broker.ts` — `queueMessage` and `drainForMember`
  thread the new columns through.
- `apps/broker/src/index.ts` — `handleSend` picks them up from the
  daemon's wire envelope; outbound push echoes them back so receiving
  daemons can dedupe.
- `apps/broker/src/types.ts` — `WSPushMessage` declares the optional
  fields.

**Deployment plan (not auto-applied)**:
1. Apply migration against prod DB (the broker's filename-tracked
   migrator picks up `0028_*.sql` on next startup).
2. Deploy the broker with the code changes via Coolify.
3. Verify a daemon-originated send shows non-null `client_message_id`
   in `mesh.message_queue` afterwards.

**Still deferred** (full broker hardening):
- `mesh.client_message_dedupe` table with `request_fingerprint BYTEA`
  and atomic accept transaction (spec §4.7).
- Feature-bit advertisement on hello_ack of
  `client_message_id_dedupe` v1, with daemon-side enforcement (spec §15).
- Partial unique index `(mesh_id, client_message_id) WHERE NOT NULL`.

These sit behind the same trigger as the followups below: do them when
real users hit operational corners that this addressing doesn't cover.

---

## How to use this document

When picking up post-v0.9.0 work on the daemon:

1. Check whether any of the "promote when" triggers above have fired.
2. If yes, consult the corresponding versioned spec (v6/v7/v8/v9/v10)
   for the full proposed change.
3. Implement the lift, update `daemon-spec-v0.9.0.md` to reflect the
   merge, and remove the item from this followups list.

The versioned specs live in `.artifacts/specs/` indefinitely as a
review-trail audit.