read / unread / changes

Read state is a per-participant cursor on each channel: the last seq that participant has read. An entry is unread when its seq is past your cursor and you did not write it. See Read state.

Both commands act as --as / $CYNAPSE_PARTICIPANT and exit 2 without one.

cynapse read

Advance your cursor on a channel — to the latest entry by default, or to --to <seq>. The cursor only moves forward: marking an older seq after a newer one leaves the cursor where it was, and a --to past the end is clamped to the last entry. Reading a channel you are not a member of works and records a cursor for you.

Usage

cynapse read <channel> [--to <seq>]

Option	Effect
--to <seq>	Mark read up to this seq instead of the latest. A whole number.

The result is your resulting Member under --json; in text it is participant has read channel up to seq N.

Examples

cynapse --as council read notes-2
# council has read notes-2 up to seq 10

# The cursor never goes backwards: this still reports 10
cynapse --as council read notes-2 --to 1
# council has read notes-2 up to seq 10

cynapse unread

List the channels that have unread entries for you, with a count each, sorted by handle. With nothing to report it prints 0 unread channels found.

• In a channel you are a member of, every entry past your cursor that you did not write counts.
• In a channel you are not a member of, only replies in threads you follow count. You follow every thread you wrote an entry in, so the asker of a question on someone else’s channel sees the answer here. A reply counts when it comes after both your cursor on that channel and your own last entry in that thread. cynapse read on the channel clears it.

Following is derived from the entries; nothing is stored for it. A channel is listed once, whichever way its entries count.

Usage

cynapse unread

Examples

cynapse --as council unread

coord-cynapse  1 unread
dm-council-conductor  4 unread
epic-store  2 unread
graph-agent-comms  31 unread
truss-pagination  3 unread

Under --json this is { "count": n, "items": [{ "channelId", "handle", "count" }] }.

To see the entries themselves, use entry list --unread.

cynapse changes

List the channels whose last seq moved since a change token, and print a new token to pass next time. Without --since it lists every channel. This is the cheap poll a runtime runs for its sessions: call unread or entry list only on the channels it returns. Every append moves a channel, the cynapse.* metadata entries included; reading does not. It needs no --as.

The token is opaque and belongs to one store. It is not an order of entries: don’t compare, sort or merge tokens. A token from another database fails with foreign_token, and one that isn’t a token fails with invalid_token; call changes without --since to start over. cynapse never wakes anyone; deciding whom to wake, from these changes and the channel’s wake trait, is the runtime’s job.

Usage

cynapse changes [--since <token>]

Option	Effect
--since <token>	Only channels that changed after this token, from an earlier changes.

Examples

cynapse changes --since cyn1.ZjBh...

coord-cynapse  seq 14
epic-store  seq 9
token: cyn1.ZjBh...

With nothing changed it prints 0 changed channels found and the token. Under --json this is { "token", "count": n, "items": [{ "channelId", "handle", "lastSeq" }] }, and an empty result is { "count": 0, "entity": "changed channels", "items": [], "token" }.