Files
Marcos Paulo 9993a66fee feat: Bases crate: YAML subset parser, value, date and duration types
notescraft-bases (L2, no I/O): hand-written lossless YAML subset parser and emitter with limits (1 MiB, depth 12, 10000 nodes), value and date types with durations, month clamp and a total order across types (Bases tasks 1 and 4). Built by MiniMax M3.1 Flash (OpenCode Zen free route). Verified as part of the full cargo xtask ci run on the combined tree.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 02:31:52 -03:00

13 KiB

Tasks: comments, suggestions, mentions, activity feed

One task = one agent's work. Each task names the files it owns, the files it must read and the tests that prove it. [ ] open, phases run in order. Tasks 1 to 3 are ready for MiniMax M3.1 Flash (pure Rust, no I/O, no UI). The briefs live in scripts/mm/ once the owner writes them.

Tasks 1 to 6 and 8 are in notescraft-engine; task 7 is in notescraft-sync-server. crates/engine/src/ already holds 12 loose .rs files, so every new module goes into the new folder crates/engine/src/review/ (declared with one line in crates/engine/src/lib.rs). The server side uses the new folder apps/notescraft-sync-server/src/activity/. No new crate, no new dependency, no change to the root Cargo.toml.

Owner decisions (before phase 2)

  1. Comments in the sidecar file (spec D1) or inside the Markdown? The spec recommends the sidecar.
  2. The feed in a dedicated server table or derived from the audit log? The spec recommends a dedicated table with one row per (member, event).
  3. A mention of somebody who is not a member: refused or plain text? The spec recommends plain text.

Phase 1 - the pure model (no I/O)

  • 1. The comment model and the sidecar codec. OWNS: crates/engine/src/review/mod.rs, crates/engine/src/review/model.rs, crates/engine/src/review/sidecar.rs, one line in crates/engine/src/lib.rs, the error variants in crates/engine/src/error.rs. READ FIRST: specs/comments-and-mentions/spec.md (D1, D2), crates/engine/src/error.rs, crates/engine/src/id.rs (the id rules), crates/engine/src/live/config.rs:54 (the random bytes and the hex form the thread ids use), crates/engine/src/share/client.rs:82 (the Member shape). Public API: Comment { id, author, created_ms, updated_ms, body, anchor: Anchor, thread: Vec<Reply>, resolved, resolved_by, mentions }, Anchor { quote, context_before, context_after, start, end }, Sidecar { version, note, comments }, sidecar_path(note) -> String, parse_sidecar(bytes, note) -> Result<Sidecar>, sidecar_to_json(&Sidecar) -> Result<Vec<u8>>. Done when: cargo test -p notescraft-engine review:: runs and passes; a sidecar round trips through JSON; a body over 4 KiB, a quote over 200 characters, 201 replies, 501 threads and a file over 1 MiB are refused with an error (never truncated); an unknown version is refused; cargo clippy -p notescraft-engine --all-targets -- -D warnings is clean.
  • 2. The anchor resolution (drift). OWNS: crates/engine/src/review/anchor.rs. READ FIRST: crates/engine/src/review/model.rs, specs/comments-and-mentions/spec.md (D3), crates/markdown/src/lib.rs (how the ranges of a document are given). Public API: enum AnchorState { Exact, Reanchored, Fuzzy, Orphaned }, resolve(anchor: &Anchor, text: &str) -> Resolved with the resolved range and the state. Done when: the unit tests show an unchanged range is Exact; a quote that moved is Reanchored; a quote with other spacing or case is Reanchored; a reworded quote is Fuzzy; a deleted quote is Orphaned; a quote that appears twice picks the occurrence nearest the old range; an empty quote is refused; the fuzzy ratio needs no new dependency.
  • 3. The CriticMarkup marks of the suggestion layer. OWNS: crates/engine/src/review/suggestion.rs. READ FIRST: specs/comments-and-mentions/spec.md (D4), crates/markdown/src/lib.rs:242 (replace_range). Public API: enum SuggestionKind { Added, Removed, Substituted }, scan(text: &str) -> Vec<Suggestion> (kind, byte range of the whole span, the text), accept(text: &str, span: Range<usize>) -> Result<String>, reject(text: &str, span: Range<usize>) -> Result<String>. Done when: the tests show the three rows of the table in D4 (accept and reject of {++…++}, {--…--}, {~~…~>…~~}); a range that holds no span is an error (stale_range); a mark inside a fenced code block is not a suggestion; two marks of the same kind do not nest; the text of a note without marks is returned unchanged.

Phase 2 - the commands

  • 4. The comment commands and the sidecar on disk. OWNS: crates/engine/src/review/store.rs, crates/engine/src/review/commands.rs, crates/engine/src/commands.rs (the registration call, next to crate::share::commands::register_share(reg)), crates/engine/src/ai/assistant_gate.rs (the id lists), crates/engine/src/lib.rs. READ FIRST: crates/engine/src/spec.rs, crates/engine/src/params.rs:88, crates/engine/src/commands.rs:156 (the write gate), crates/engine/src/share/commands.rs (a command group to copy), crates/engine/src/vault/buffers.rs (the buffer API). Done when: comment.list, comment.add, comment.reply, comment.edit, comment.delete, comment.resolve and comment.reanchor are registered and behave as the table in D8; comment.add writes the sidecar through Vault::write and leaves the note file byte-identical; the write commands are disabled in a read-only session; the new ids are in the right list of crates/engine/src/ai/assistant_gate.rs; the command tests drive the registry, not the internals.
  • 5. The suggestion commands and the role check. OWNS: crates/engine/src/review/commands.rs, crates/engine/src/review/role.rs, crates/engine/src/ai/assistant_gate.rs. READ FIRST: crates/engine/src/review/suggestion.rs, crates/engine/src/share/client.rs:244 (the members list and the roles), crates/engine/src/vault/buffers.rs:92 (Buffer::edit). Done when: suggestion.list, suggestion.accept and suggestion.reject exist; accepting writes the new text through the ordinary buffer path (the live room sees it); a viewer is refused with forbidden and an editor is not; a stale range answers stale_range and the note stays unchanged; a note without pending suggestions saves byte-identical to the same note edited without suggestions.
  • 6. The sidecar under rename and under conflict. OWNS: crates/engine/src/review/store.rs, crates/engine/src/review/merge.rs. READ FIRST: crates/sync/src/conflict.rs:12, crates/sync/src/merge.rs:30, crates/engine/src/sync/conflicts.rs (how the engine resolves a conflict today). Done when: renaming a note renames its sidecar; the merge of two sidecars unions the threads by id and never drops one; a sync conflict on a sidecar is merged instead of leaving two half-files; the tests cover two devices that commented while offline.

Phase 3 - the server and the feed

  • 7. The activity table and the endpoints. OWNS: apps/notescraft-sync-server/src/activity/mod.rs, apps/notescraft-sync-server/src/activity/store.rs, apps/notescraft-sync-server/src/activity/routes.rs, the schema and the route registration in apps/notescraft-sync-server/src/store/mod.rs and apps/notescraft-sync-server/src/api/routes.rs. READ FIRST: apps/notescraft-sync-server/src/api/members.rs (a group to copy), apps/notescraft-sync-server/src/store/audit.rs, apps/notescraft-sync-server/src/roles.rs, apps/notescraft-sync-server/src/limits.rs. Done when: POST /v1/vaults/{v}/activity stores an event for the members it names (the actor must be the token's user, the mentions must be members, the note must exist in the vault); GET /v1/vaults/{v}/activity?since=&limit= answers the events of the caller and their unread count; POST /v1/vaults/{v}/activity/read marks them read; a viewer token and a removed member get 403; the HTTP tests speak real HTTP against the test server; the server never writes a comment body to the log.
  • 8. The activity client, the commands and the outbox. OWNS: crates/engine/src/activity/mod.rs, crates/engine/src/activity/client.rs, crates/engine/src/activity/commands.rs, crates/engine/src/commands.rs (the registration call), crates/engine/src/lib.rs. READ FIRST: crates/engine/src/share/client.rs (the HTTP client to copy), crates/engine/src/sync/worker.rs:175 (the poll loop), crates/engine/src/vault/buffers.rs (the private writes). Done when: activity.list, activity.unread, activity.read and mention.candidates are registered; a comment that mentions a member posts the event when the server is reachable and keeps it in .notescraft/activity-outbox.json when it is not, and posts it with the next sync; the unread cursor is kept in .notescraft/activity.json; a vault without a server answers not_bound instead of failing.

Phase 4 - the UI

  • 9. The comment panel and the margin gutter. OWNS: crates/ui-egui/src/panels/right/comment_panel.rs, the tab in crates/ui-egui/src/panels/right_view.rs, the gutter in crates/ui-egui/src/views/note_view/, crates/ui-egui/src/text/panels/review/mod.rs and crates/ui-egui/src/text/panels/review/comment_panel.rs (the folder text/ and text/panels/ are full at 12 loose files, so the new tables go into a new folder), the tables in crates/i18n/locales/en.toml (new [ui.comment-panel] at the end of the [ui.*] tables). READ FIRST: crates/ui-egui/src/panels/right/backlinks_panel.rs (the shape of a right panel), crates/ui-egui/src/panels/right_view.rs:103 (RightTab), crates/ui-egui/src/design/style/ (the touch targets), .claude/skills/notescraft-egui-screen/SKILL.md. Done when: the panel lists the threads of the open note in document order with the filters All, Open, Resolved and Orphaned; a selection opens the composer and the new thread appears; a reply, a resolve and a re-anchor work; the gutter shows one marker per thread on the line of the anchor; the driven test in crates/ui-egui/tests/ paints the panel and finds the thread text; cargo xtask i18n reports no hardcoded string.
  • 10. The suggestions in the Visual view and the review list. OWNS: crates/ui-egui/src/views/note_view/ (the painting of the marks), crates/ui-egui/src/panels/right/suggestion_panel.rs, crates/ui-egui/src/text/panels/review/suggestion_panel.rs, the tables in crates/i18n/locales/en.toml. READ FIRST: crates/ui-egui/src/views/note_view/painting.rs, the task 3 API, crates/ui-egui/src/design/ (the theme tokens). Done when: an addition is underlined and a deletion struck through in the Visual view; the Source view shows the raw marks; the review list offers accept, reject and accept all; a viewer sees the list without the buttons; the driven test finds the rendered marks.
  • 11. The activity feed, the badge and the phone pages. OWNS: crates/ui-egui/src/panels/right/activity_panel.rs, crates/ui-egui/src/panels/right_view.rs, crates/ui-egui/src/shell/compact/ (the phone pages), crates/ui-egui/src/text/panels/review/activity_panel.rs, the tables in crates/i18n/locales/en.toml. READ FIRST: crates/ui-egui/src/panels/sync_sheet/ (the phone sheet), the task 8 API, crates/ui-egui/src/shell/compact/mod.rs:29 (CompactPage). Done when: the feed lists the events newest first with the unread ones marked; the tab shows the unread count; a click opens the note and the line; on the phone the feed and the comment panel are pages of the compact shell with 44 pt targets.

Phase 5 - the edges

  • 12. The sidecars stay out of the way. OWNS: the file tree in crates/ui-egui/src/panels/tree.rs, the search index in crates/index/src/, the published listings in apps/notescraft-sync-server/src/publish/pages.rs:154 (it keeps only the .md files today). Done when: a *.comments.json file never appears in the explorer, in the search results or in a published site; renaming a note keeps the sidecar with it; deleting a note removes the sidecar with it.
  • 13. The feed over Server-Sent Events (the optimisation of D7). OWNS: apps/notescraft-sync-server/src/activity/routes.rs, crates/engine/src/activity/client.rs, crates/engine/src/live/sse.rs (the parser is reusable). Done when: GET /v1/vaults/{vault}/activity/events streams the events of the vault; the client updates the feed while it is open; the poll of task 8 stays the fallback and the two never deliver the same event twice.
  • 14. The end-to-end proof. OWNS: crates/engine/tests/comments_e2e.rs (or the folder of the crate). Done when: two clients on a stub server: Ana comments on a sentence of a note and mentions Bob; Bob's feed shows the mention and the comment; Ana's feed does not show her own comment; Bob resolves the thread and Ana gets the thread_resolved event; a second run of the sync changes nothing.