updat

docs/concord-usage.md

@@ -245,7 +245,7 @@ let page = history::page(
 let cached = cache::query_rumors(&client, &channel, None, 50, Some(&cord03::ROW_KINDS)).await?;
 ```
 
-A key's `retired_at` (epoch seconds, set when a rotation supersedes it) is a read
+A key's `retired_at` (a `Timestamp`, set when a rotation supersedes it) is a read
 cutoff: a wrap at that epoch with a later `created_at` is refused, so a retired
 epoch is history and never a live plane an ejected holder can keep writing into.
 
@@ -271,21 +271,24 @@ the handshake completes, so the page waits for the resubscribed answer rather
 than writing off a relay that only wanted to authenticate.
 
 `history::page` walks newest-first across every held epoch, caches what it opens, and
-reports what it saw: `oldest_ms`/`newest_ms` feed the caller's `ChannelCursor`,
+reports what it saw: `oldest`/`newest` feed the caller's `ChannelCursor`,
 `exhausted` is earned only by a short page *after* history was seen, and an
 all-empty answer sets `failed` so a later round re-asks instead of sealing the
 channel at "no more history". `unreadable` counts the wraps the page reached that
 no held key could open — sealed past the cutoff their key's rotation set, or bound
 to another channel — because those are history the reader is missing, not history
-that is not there. Page down with `Window::older_than(seen.oldest_ms)`,
-open a channel with `Window::opening(cursor)` (wide cold, `newest_ms - 60s` warm),
-and read the region between two cursors with `Window::between(..)`. `query_rumors`
-is the read path when the group keys are gone; pass `kinds` to budget rows apart
-from the events that only decorate them. `cache::wrapper_index` reads the cached
-rows back keyed by the wrap they came from, which is what lets `sync::fold` observe
-author and message times without re-opening a wrap it already cached, and
-`cache::purge_expired(client, &channel, now)` runs at the top of every round — the
-timer is cooperative, so the local store is the artifact that has to forget.
+that is not there. Page down with `Window::older_than(seen.oldest)`,
+open a channel with `Window::opening(cursor)` (wide cold, `newest - 60s` warm),
+and read the region between two cursors with `Window::between(..)`. A `Window`
+carries `Timestamp`s, so its bounds go straight into a NIP-01 filter with no unit
+conversion; only a reader's millisecond `at_ms` narrows to a second at the query.
+`query_rumors` is the read path when the group keys are gone; pass `kinds` to
+budget rows apart from the events that only decorate them. `cache::wrapper_index`
+reads the cached rows back keyed by the wrap they came from, which is what lets
+`sync::fold` observe author and message times without re-opening a wrap it already
+cached, and `cache::purge_expired(client, &channel, now)` runs at the top of every
+round — the timer is cooperative, so the local store is the artifact that has to
+forget.
 
 `sync::fold` counts the same thing over the whole store, per channel, in
 `Snapshot.unreadable`. `sync_round` sums a round's pages into
@@ -415,25 +418,25 @@ whether a link still stands, and `fits()` is the write gate.
 ## Rekeys, refounding and dissolution
 
 A rotation is authority plus delivery: `rekey_authorized(&control.roles, &owner, &me, permission, &removed)`
-gates it, `plan_refounding(epoch)` mints the new pair, and `build_rekey_chunks`
-seals one blob per remaining member:
+gates it, `plan_rotation(scope, epoch)` mints what it delivers, and
+`build_rekey_chunks` seals one blob per remaining member:
 
 ```rust
 use concord::derive::epoch_key_commitment;
-use concord::cord06::{self, RekeyScope};
+use concord::cord06::{self, RekeyScope, RotationPlan};
 
 let scope = RekeyScope::Channel(channel_id);                    // or RekeyScope::Base
-let plan = cord06::plan_refounding(Epoch(epoch + 1))?;
+let plan = cord06::plan_rotation(scope, Epoch(epoch + 1))?;
+let new_key = plan.new_key();
 
 // A base rotation delivers the new control-plane keys beside the root; a channel
 // rotation delivers only that channel's fresh key.
-let new_key = plan.new_root;
-let (control_pk, control_root) = match scope {
-    RekeyScope::Base => {
-        let pk = plan.signer(&community_id)?.pk().to_bytes();
-        (Some(pk), is_staff.then_some(&plan.new_control_root))
+let (control_pk, control_root) = match &plan {
+    RotationPlan::Base(refounding) => {
+        let pk = refounding.signer(&community_id)?.pk().to_bytes();
+        (Some(pk), is_staff.then_some(&refounding.new_control_root))
     }
-    RekeyScope::Channel(_) => (None, None),
+    RotationPlan::Channel { .. } => (None, None),
 };
 
 let mut blobs = Vec::with_capacity(members.len());
@@ -441,18 +444,24 @@ let mut blobs = Vec::with_capacity(members.len());
 for member in &members {
     blobs.push(
         cord06::build_blob(
-            &my_keys, member, scope, plan.epoch, &new_key, control_pk.as_ref(), control_root,
+            &my_keys,
+            member,
+            scope,
+            plan.epoch(),
+            &new_key,
+            control_pk.as_ref(),
+            control_root,
         )
         .await?,
     );
 }
 
-let rekey_group = cord06::rekey_group(scope, &community_root, &community_id, plan.epoch)?;
+let rekey_group = cord06::rekey_group(scope, &community_root, &community_id, plan.epoch())?;
 let wraps = cord06::build_rekey_chunks(
     &my_keys,
     &rekey_group,
     scope,
-    plan.epoch,
+    plan.epoch(),
     Epoch(epoch),
     &epoch_key_commitment(Epoch(epoch), &community_root),
     &blobs,
@@ -476,6 +485,18 @@ waiving a gap, never adopting a fork), keeps each stepped-off key as a prior
 with the rotation's publish time as its read cutoff, and reports a removal or a
 strand when a complete rotation carries no blob for the member.
 
+`community::rekey::rotate` is the sender, run against the held state: it resolves
+the epoch and key the scope is stepping off, refuses a rotation that would skip or
+cut off its own rotator, delivers one blob per recipient (`Rewrite.recipients`,
+which the caller names because a private channel's audience is not in the local
+state), marks the rotation severed when it excludes somebody, and — for a base
+scope — carries the settled Control Plane heads onto the new epoch's groups with
+`cord06::compact`. `Community::rotate` checks `Rewrite::authorized` first, the same
+`rekey_authorized` under the same permissions `adopt` applies, publishes to the
+community's relays, and then adopts what it published through `rekey::adopt`
+rather than by construction: a rotation this client wrote and one it received take
+one path.
+
 The blob plaintext is a fixed-width binary record, but a signer's NIP-44 is
 text-only, so `build_blob` carries it base64-encoded inside the envelope.
 `open_blob` mirrors that, so the record layout and the `locator` are unchanged.
@@ -737,5 +758,6 @@ client.subscribe(filter).with_id(sub_id).await?;
   rendered as a notice **and** enforced at write time: `Community::send` refuses
   when `channel_secret` is `None` (a removal, a strand, a channel cut, or a key we
   never held), because a wrap sealed under a superseded root would reach nobody who
-  rotated. The residual gap: this client does not adopt a rotation it published
-  itself, because there is no rekey writer yet.
+  rotated. A rotation this client publishes itself (`Community::rotate`) is adopted
+  through the same `rekey::adopt` an arriving one goes through, so the held state
+  and the wire cannot diverge.