notes

6.5 KB

1. # Report 002 (w085): notes code order, no behaviour change
3. **Where:** commits on main in loreana:/media/STORAGE/projects/notes.worldapi.org (parent 47dad68):
4. - `8cda541`: file moves (1/4)
5. - `3f8cb38`: topics, map and thin wrappers (2/4)
6. - `47db4fc`: `let` (3/4)
7. - the docs + tests commit (4/4), which also holds this report and the mission brief
9. Not pushed, not deployed. No `.env` read. Only ports 8760–8764 and 8767–8769 were used (8765/8766 skipped). Every server was stopped by its PID; nothing of mine is still running.
11. ## Counts (before → after; `python3 tests/letcount.py .`)
13. | | before (47dad68) | after |
14. |---|---|---|
15. | `.hl` files in the root | 5 | **1** (project.hl) |
16. | project.hl lines | 183 | **91** (index comment, PWA config, routes, audience, server) |
17. | `let` total | 114 | 34 |
18. | `let` never reassigned | **71** | **0** |
20. The 34 `let`s left are all needed:
21. - 19 are reassigned;
22. - 15 are re-bound in a loop body. Hybriel refuses a plain declaration there on its 2nd pass (tickets lesson).
24. ## Layout
26. The full file map is in README "Files". Imports only go one way: util ← users, notes-helpers ← notes ← api-helpers ← api ← project.hl.
28. - **`lib/notes.hl`**: the table and every write to it.
29. - Holds `noteOf`, `metaRows`, `noteView`, `newNote`, `pushNote` (sync and conflict rules) and `removeNote` (tombstone).
30. - `notes-helpers.hl`: `textError` (the size limit), `isAlive`, `stampOf` (version stamps) and `copyMark`.
31. - **`lib/users.hl`**: the users table, the ident config and the exchange.
32. - `userOfLoginCode` is new here: the single exchange + `ensureUser` step. Before, the login route and the `notesLogin` face each had their own copy.
33. - `tagOf` moved here out of project.hl.
34. - **`lib/api.hl`**: every function route, as thin wrappers:
35. - `/login/callback` and `loginFailed` (this was `failed`). Both take `&req` and `&sessions`;
36. - `/api/me`;
37. - `/api/notes`.
38. - **`lib/api-helpers.hl`**: `reply`, `isText`, `isTime`, `safePath`.
39. - **`lib/util.hl`**: `envOr`, `storageDir`, `countOfList`, `firstOf`, `isHex`, `isIdentId`. Before, these were in users.hl and notes.hl imported them from there.
40. - **`lib/jsoncheck.hl`** stays a file of its own: it is the workaround for hybriel #12. Its comment now names the right call site.
41. - **Moved:** `styles.hl` → `components/styles.hl`. `tools/migrate-short-ids.hl` now imports from `lib/`.
42. - **Face made thin:** `notesLogin` → `userOfLoginCode`. The session writes stay in the face, because a face's `session` parameter is the framework's own.
43. - **Removed** (dead since notes#2 moved the notes area to the browser; called nowhere): `createNote`, `saveNote`, `noteRows`, `noteTextOf`, `subjectOf`, `rowOf`, `aliveOf`, `maxSubject`, `untitled`.
44. - `deleteNote`'s one write is now inline in `removeNote`. It was its only caller, and the checks it repeated were already done there.
46. ## Tests
48. | test | result |
49. |---|---|
50. | gate `tests/browser.mjs` (app 8760, ident 8761, Chrome 8767–8769) | **50 passed, 0 failed** before and after each step |
51. | `tests/short-id-switch.mjs` (a copy with its fixed ports moved to 8760/8761) | **18/0** before and after each step |
52. | live-data reads + writes | identical, except **4 intended differences** (below) |
54. The commands are in `.scratch/w085/gates.sh` and `step.sh`, and in README "Test".
56. **Live-data comparison** (new `tests/realdata-baseline.mjs` and `tests/realdata-compare.py`; how to run: README "Test" → "Same output"):
57. - **Data:** a copy of Byrodin's `storage/mpackdb` (1 user, 40 notes), taken 2026-10-03. Each run gets a fresh copy.
58. - **Ident:** a fake ident on port + 5 answers `/api/exchange`, so the successful login paths run too.
59. - **Reads** (243), signed in as az5b2 (users `0muh6o5a3kkd`) through a session file, and signed out:
60. - `/`, every `/note/<id>`, unknown notes and addresses, `/login/failed`;
61. - the static files, the manifest and the browser modules;
62. - `/api/me`, `/api/notes`, every `/api/notes?id=`;
63. - 20 refusals of the POST endpoint;
64. - `/login/callback` failing six ways, with and without a session.
65. - **Writes** (43):
66. - saving a new note, retrying it, saving the same text, an edit;
67. - a conflict both ways, an unknown id, a stale save on a real note;
68. - deleting with the wrong base, then the right one, then again; deleting nothing; saving after the delete;
69. - a successful login callback with seven `next` values, with and without a session;
70. - the faces: four failing logins, one that works, logout;
71. - the pages and API reads that follow.
72. - **Masks:** two runs of the OLD code compare clean (286/286). The masks: source positions, `?v=` hashes, seed time, and for writes the new ids, the `edited` stamps and the login tags.
73. - **Browser modules:** two differ only in imported-statics tables and positions. The script's structural check passes them.
75. **The 4 differences (intended, the same fix as gitoria mission 002):**
76. - **What changed:** `/login/failed`, opened after a failed `/login/callback` in a browser that already has a session, now shows its reason. Examples: "ident refused the login (403: code expired)", "GET only".
77. - **Before:** it always said "the login did not finish — try again".
78. - **Cause:** the old `failed(req, why)` was a second call. It got a COPY of `req`, so its session write was lost.
79. - **Fix:** project.hl hands `&req` and `&server.sessions` to the route.
80. - **To undo it:** pass `req` by value to `loginFailed` in lib/api.hl.
81. - **Unchanged:** after a successful login, the page still shows the default text.
83. **Step 3 (`let`) against step 2:** 0 different.
85. **Other checks:**
86. - A server started without `NOTES_STORAGE` still reads its own `./storage/mpackdb`: 40 notes, on the old tree and the new one.
88. ## Found (in STATUS)
90. 1. **The by-value `failed(req, why)` was a real bug.** The old #48 audit (mission 069) had said no `&` was needed. README now notes that this was wrong.
91. 2. **The live-data run needs a fixed `NOTES_PUBLIC_URL`.** The login link carries the URL, so two runs on two ports only compare when it is the same.
92. 3. **Plain declarations in sibling blocks work.** `ed`, `after`, `cid` and `cp` in pushNote are plain now, and the conflict paths run in the live-data run.
94. ## Not done / open
96. - **Not deployed** (that is the architect's job). Use the normal `deploy.sh`. There is no data change.
97. - deploy.sh's rsync does not delete, so the old root `notes.hl`, `users.hl`, `jsoncheck.hl` and `styles.hl` stay on Byrodin. They are unused and can be removed by hand.
98. - **Scratch** (gitignored) in `.scratch/w085/`:
99. - `old/` (the old tree);
100. - `gates.sh`, `step.sh`, `unlet.py`, `nostore.mjs`;
101. - the gate outputs.
102. - **Deleted after the run:** the live-data copy and every baseline output (they hold live notes).