Expand description
V2-29: the notes service — notes on their own API and in a file
of their own, as a service of v2’s own beside tickets, ui and
media (V2-1: services that coexist, each reaching the others as a
client through the seam). The owner, 2026-11-02: “I would like us to
move the docs onto a new docs api. same fe though.”
A note is writing, not work: an id (8 characters of Crockford’s
base32, TICKETS-35’s form), the organization it is in, a title, a
markdown body, who made it and who wrote it last. The body is a Yjs CRDT
(V2-29’s pairing, the owner: “live co editting”): every hand’s change
is an update merged by the service and streamed to everyone on the
note, who is on it is said as they come and go, every change is kept
with who and when (replayed, squashed by permission), and the markdown is
derived from it. The editor’s surface (#/note/<id>) writes to it.
Who may is the gate’s: a viewer reads, an editor writes, an admin
deletes, on the note’s organization (acme:) or on * — the
method’s grant asked of the running service’s gate on that scope
(Seam::holds); the organizations a caller is in are the tickets
service’s word (orgs.list, over the seam). This service never opens
another’s file.
| module | what |
|---|---|
vocab | the typed parameters: NoteId, NoteTitle, NoteBody, NoteQuery; the id’s minting |
events | Note, HistoryRow, Present, NotesEvent |
store | the file: docs and doc_log; get, list, rename, delete; the channel |
crdt | the body, a Yjs CRDT: create, update, save (a diff merged), state, replay, history, squash, restore |
presence | who is on a note: entries held by a watch, idling out |
threads | V2-30: questions on a range, anchored in the CRDT, and their answers |
slot | NOTES-4: a note’s slot — the component drawn beside it, its props, its fills, the build under way |
marks | NOTES-5: marks on a range — an underline, a link, a line of state — anchored as a question is, never writing the text |
quota | the meter every write is reserved against (always allows until V2-31) |
seam | the gate and orgs.list through the running service; seam::may for a client |
activation | the methods, the one declaration |
Re-exports§
pub use vocab::AgentName;pub use vocab::BuildStep;pub use vocab::ComponentName;pub use vocab::SlotProps;pub use vocab::SlotSay;pub use vocab::VersionRef;pub use vocab::NoteAwareness;pub use vocab::NoteBody;pub use vocab::NoteId;pub use vocab::NoteQuery;pub use vocab::NoteSession;pub use vocab::NoteTitle;pub use vocab::NoteUpdate;pub use vocab::NoteVector;pub use vocab::ThreadId;pub use vocab::ThreadText;pub use vocab::MarkId;pub use vocab::MarkLabel;pub use vocab::MarkLink;pub use events::Anchor;pub use events::Author;pub use events::Building;pub use events::Fill;pub use events::Note;pub use events::NotesEvent;pub use events::HistoryRow;pub use events::Present;pub use events::Reply;pub use events::Resolution;pub use events::Slot;pub use events::Thread;pub use events::WatchEnd;pub use events::Mark;pub use store::Change;pub use store::NotesStore;pub use store::StoreError;pub use seam::Components;pub use seam::Held;pub use seam::Seam;pub use activation::NotesActivation;pub use activation::NotesClient;
Modules§
- activation
- The
notesactivation — the one declaration, astickets,uiandmediaare: theActivationimpl, dispatch, the schema and the methods’ bodies from thisimpl, andNotesClient<T>for a client of it (the media service’snotes.may, a test). - crdt
- The body’s write — a note’s body is a Yjs CRDT (V2-29’s
pairing): every writer’s change is an update, merged by the CRDT, so two hands in one paragraph lose nothing. This module is the one that writes a body, replays it and squashes it. - events
- What the
notesservice streams (NotesEvent) and what it says a note is (Note,HistoryRow,Present). Every method returnsimpl Stream<Item = NotesEvent>; a refusal is in band. - marks
- NOTES-5: marks — what an agent leaves on a note without writing in it (the owner, 2026-11-15: “I want to make sure that agents can listen in on notes, and underline sections, add links, and write components into the docuemtn itself.”). A mark is a range of the note’s characters carrying a link, one line of state, or both; the page underlines it.
- presence
- Who is on a note (V2-29, the owner: “we should see that they
have a connection open on that document too”). Each open connection on
a note is a presence entry — its principal, its name, person or
agent, a colour, and its caret and selection as the browser’s Yjs
awareness says them — relayed to everyone on that note through
watch(present,left). - quota
- The meter’s seam — every byte a note’s body grows by is
reserved before it is written and committed once it is (V2-31: the
quota service will meter
notes.bytesper author; EDITOR-10 does the same for images). Until that service lands,AllowAllallows every write; the call sites arecrate::crdt’s create and append. V2-31: the quota service answers it (src/quota_allowance.rs’sNotesMetered):notes.bytesper change,notes.countper note made. - seam
- The seam — the notes service as a client of the service it is
mounted beside (V2-1; the media service’s
seam.rsis the pattern). The running service is built after this activation is, so the activation holds an emptySeamthe builder fills (Seam::attach). - slot
- NOTES-4: a note’s slot — the component drawn on the note’s right (the owner, 2026-11-15: “every note associated with a plexus-ui slot on it’s right”): a component of a version the ui service keeps, its props, and every fill before it; and what an agent says while it builds the next one (“we instead want to show that the agent is building components as it builds”).
- store
- The notes store — the notes, in a SQLite file of the service’s
own,
notes.db: never the tickets file (V2-1: the file is opened by the tickets service alone). - threads
- V2-30: asking on a selection — a question anchored to a range of a note, answered in a thread beside it by a person or an agent (the owner, 2026-11-02: “I want to have the ability to highlight a line in a doc and ask a question … these docs are really important and will be key locations for paired work.”).
- vocab
- The service’s typed parameters (ACCESS-8,
typed_params) — what names and carries a note:NoteId,NoteTitle,NoteBody,NoteQuery. Each a transparent text whoseDeserializeis its one rule, so a bad value isinvalid_paramsnaming the parameter before the method runs (the media service’svocab.rs, the pattern).
Structs§
- Caller
- A caller the gate admitted: its principal, its identity, and the reach the gate answered for the call.
- Notes
Request - The per-call context every method of the service reads: the identity the connection’s upgrade proved, when one did.
Constants§
- NOTES_
DB_ FILE - The service’s file when
--notes-db-pathnames none:notes.dbbeside the tickets file, never the same file.