tickets

54.9 KB

1. # tickets.worldapi.org
3. The World Ticket System: the only state store of AntColony (see byrodin
4. `/CONTAINERS/projects/antcolony/README.md`). Projects, tickets, an append-only event
5. history per ticket (created / comment / state change), a web UI with live push, a JSON
6. API for the scheduler/CLI, and an idempotent import of the AntColony ticket files.
8. Written in **Hybriel** on **hl:web** (SSR + WebSocket push; hybriel master since antcolony mission 036), modelled on the hybriel
9. repo's `projects/demo-social-network`. **Login via ident** (ticket #7, `CONCEPT.md` "Login via
10. ident"): reading is public; writing (tickets, comments, states) needs a login; the author is
11. the logged-in user; since ticket #20 roles per project decide who may do what (the creator-only confirm is gone); machine clients write with API tokens.
12. See section "Login (ident)". **Markdown** in text fields and a Markdown read view for LLMs
13. (ticket #6), **editing** by the ticket's author (ticket #8): section "Markdown, editing".
14. **Relations** (ticket #4): parent / child and blocked-by, across projects — section "Relations".
15. **Markdown editor** (ticket #12): every Markdown field is an `<md-editor>` — section "Markdown editor".
17. ## Run
19. ```bash
20. cd /media/STORAGE/projects/tickets.worldapi.org
21. setsid nohup ./bin/hybriel project.hl > server.log 2>&1 < /dev/null & echo $! > server.pid
22. # stop: kill $(cat server.pid)
23. ```
25. * Port **8350** on 0.0.0.0 (`TICKETS_PORT` moves it): http://192.168.178.75:8350 (LAN),
26. http://100.77.141.84:8350 (tailnet), http://127.0.0.1:8350.
27. * Data: `storage/mpackdb/{projects,tickets,events}.*` (hl:mpackdb, primary key = mpackdb
28. UUID `@id` everywhere — creator's convention; `TICKETS_STORAGE=<dir>` moves them).
29. Sessions: `.sessions/` (`TICKETS_SESSIONS`). The OLD global-numbered tables
30. `storage/tickets-*` (before ticket #38) stay as a read-only backup — nothing reads them.
31. * The framework's dev watcher is on: saving a `.hl` file re-analyses and reloads open tabs.
32. A restart is needed after changing `styles.hl` root rules, `shared/tokens.hl`, env vars or the binary.
33. * `HL_HOST` (or `HOST`): interface to bind, default 0.0.0.0; `127.0.0.1` on Byrodin. hl:web
34. reads it itself (hybriel#24; until antcolony mission 036 `project.hl` built the listener). `TICKETS_WATCH=0` turns
35. the dev watcher off (the container).
36. * Login env (section "Login (ident)"): `IDENT_API_KEY`, `IDENT_API_SECRET`,
37. `TICKETS_CREATOR_IDENTITY`, `IDENT_URL`, `IDENT_EXCHANGE_URL`, `TICKETS_PUBLIC_URL`. Without
38. key/secret the app runs read-only for everyone (a login answers "login is not set up").
40. ## Projects, members, roles, new states (ticket #20 — supersedes #19 and the creator-only workflow)
41. - **Projects are records** (`projects` table): title, slug (generated from the title — letters, digits, `.`, `_`, `-`; an admin can change
42. it, the old slug keeps resolving), description (Markdown, the shared `<md-editor>`), members. Tickets point at their project by its **id**
43. (never by name); `path` = `<project id>/<number>`. Pages: `/new-project`, `/projects/<slug>` (the tickets), `/projects/<slug>/settings`
44. (admin: title, slug, description, members, invite link).
45. - **Roles** (`members` table, one row per project + user): `use` = comment + move a ticket between open and review; `edit` = use + create, edit,
46. assign, any state, relations; `admin` = edit + settings and members. A project always keeps at least one admin. Everybody else only reads.
47. Any logged-in user with a display name may open a project and becomes its admin.
48. - **Tickets** carry `createdBy` and `assignee` (members). **States**: open, progress, pending, review, reopened, done, canceled. A ticket that
49. goes to review / pending with nobody assigned is assigned to the project's oldest admin (a second, `assign` event). The **inbox**
50. (`/inbox`, `GET /api/inbox` with a token) shows what is assigned to you, as two lists: pending and review.
51. - **API aliases**: the old state names are accepted as input (`in progress`, `awaiting creator`, `awaiting-creator`, `confirmed`, `rejected`, `on hold`)
52. and mean progress / review / done / reopened / pending. Output uses only the new names.
53. New endpoints: `GET/POST /api/projects`, `GET/POST /api/projects/:slug`, `POST /api/projects/:slug/members` (`{user, role}`; user = display name,
54. ident id or user id), `POST …/members/remove`, `POST …/invites` (`{role, uses?, days?, email?}` → an ident invite link, ident#22),
55. `POST /api/tickets/:ref/assign` (`{assignee}`), `GET /api/inbox`. A refused role → 403.
56. - **Invites**: the person opens ident's link, picks an identity, ident sends them to `/login/callback?ident_code=…&invite=<id>`; only when ident
57. says that identity accepted the invite (`/api/invites/get`) does the person join with the invite's role.
58. - **Migration** (`migrate.hl`, idempotent, runs at every start): old projects `{name}` → records, tickets re-linked by id, states renamed
59. (awaiting creator → review, a "Question…" ticket → pending, confirmed → done, rejected → reopened, in progress → progress, on hold → pending;
60. review / pending tickets go to the creator), `createdBy` from the created event; members: the creator (TICKETS_CREATOR_IDENTITY, read ONLY here)
61. is admin, users named Architect / AntColonyScheduler that wrote in a project are edit, everybody else who wrote is use. It compacts the tables
62. it changed (a second open of a table — the page realm — compacts on open and would rewrite the file under the first handle).
63. - Short ids: `isIdentId` in `users.hl` accepts old 64-hex and new short ids (ident#23); `tools/migrate-short-ids.hl` + `tests/short-id-switch.mjs` kept.
64. - Gate: `tests/browser.mjs` (233 checks). The pre-roles browser checks (creator-only confirm, author-only edit, relations by author, tokens page …)
65. are PARKED in `tests/browser-pre20-parked.txt` — they need porting to the roles.
67. ## Login (ident) — ticket #7
69. * **How it works**: ident's identity selector top right (`<ident-selector key=IDENT_API_KEY>`
70. from `<IDENT_URL>/selector.js`) plus a "Log in with ident" button
71. (`<IDENT_URL>/login?key=…&return=<TICKETS_PUBLIC_URL>/login/callback`). Both hand tickets a
72. one-time code; the SERVER exchanges it (`POST <IDENT_EXCHANGE_URL>/api/exchange` with key +
73. secret) for the **per-app identity id**. Selector: `login.js` bridges the `ident-login` DOM
74. event into the shell's face `identLogin` — no reload, the pages show their forms (`signedIn`
75. push to this session's tabs). Button: `/login/callback` sets the session and redirects back to
76. the page the login started from (ticket #10: at the click `login.js` adds
77. `?next=<path + query>` to the button's return URL; the server follows only a same-origin
78. path — one leading `/`, not `//`, no `\`, URL-safe chars, ≤ 500, not `/login/…` — else `/`).
79. Logout (top right) = the shell's face `logOut`; the selector is reset (class `out` → `loggedIn = false`).
80. * **`login.js` runs more than once per page** (ticket #9): hl:webex re-creates the header —
81. the selector element AND the `<script>` elements — whenever the login state flips, and the
82. browser executes a re-inserted script again. It therefore installs itself once per document
83. (`window.__ticketsLogin`), listens for `ident-login` on `document`, always looks up the
84. CURRENT `#selector`, and hands each one-time code to `#identcode` only once. (Before: one more
85. listener per run → after a logout one selection = two exchanges of the same code → red banner
86. "ident refused the login (400: unknown or already used code)", although the first logged in.)
87. * **Users** (`storage/mpackdb/users.*`, `users.hl`): one per identity id `{identity, name,
88. created}`. The first login asks once for a **display name** (a normal field — ident may fill it
89. later, CONCEPT point 6); writing waits for it; it cannot be changed afterwards (no UI).
90. The session holds only `user = { id = <users @id> }` (hl:webex ships `session.user` to the
91. page); the identity id is never in a page except the user's own `/you`.
92. * **Authors**: new events store `user` (+ the name as `author`); the history shows the user's
93. display name. Old events keep their free-text `author`. The web forms and the API have no
94. author field (API: a body with `author` → 400 naming it).
95. * **Creator**: `TICKETS_CREATOR_IDENTITY` = the creator's per-app identity id. Only that user
96. may set `confirmed` / `rejected` (web: message; API: **403** `{error, field:"state"}`).
97. **Unset = nobody can.** To set it on Byrodin: the creator logs in to tickets, opens **`/you`**
98. ("Your tickets identity id", 32 hex), the architect puts `TICKETS_CREATOR_IDENTITY=<id>`
99. into `/CONTAINERS/projects/tickets.worldapi.org/.env` and restarts the container.
100. `/you` then says "You are the creator".
101. * **API tokens** (`storage/mpackdb/tokens.*`): on `/you` a logged-in user creates (optional
102. label), lists and revokes tokens. Shown ONCE (`tkt_` + 48 hex), stored as sha256 only.
103. `Authorization: Bearer <token>` acts as that user on every API write; no / wrong / revoked
104. token → **401** (checked before the body). Reads need no token.
105. * **Env**: `IDENT_API_KEY` / `IDENT_API_SECRET` (tickets' registration in ident, origin
106. `https://tickets.worldapi.org`), `TICKETS_CREATOR_IDENTITY` — all in `.env` on Byrodin (the
107. hybriel runtime loads `.env` beside project.hl; the real environment wins; never commit it).
108. `IDENT_URL` (default `https://ident.worldapi.org`: selector script + button),
109. `IDENT_EXCHANGE_URL` (server side; default = IDENT_URL; `docker-compose.yml` sets
110. `http://127.0.0.1:45002` = ident's loopback port on Byrodin), `TICKETS_PUBLIC_URL` (default
111. `https://tickets.worldapi.org`: the button's return URL).
112. * **ident down**: a login answers "ident did not answer" (the global `on Error` in project.hl
113. absorbs hl:fetch's failure — it logs `error absorbed: …` for every plugin error).
115. ## Markdown, editing (tickets #6, #8 — mission 007 (old 014))
117. * **Markdown in text fields** (summary, comment text, state note): `markdown.hl` parses the text
118. into plain data (blocks → spans), `components/markdown.hl` builds elements from it — every
119. character ends up in a TEXT node, no HTML string exists, so raw HTML / `<script>` shows as text.
120. Links only when `safeHref` accepts them: `http(s):`, `mailto:`, `/path` (not `//`), `#…`;
121. `javascript:`, `data:`, `vbscript:` etc. stay text. Understood: `#`…`######` headings (shown as
122. h3/h4/h5), `-`/`*`/`+` and `1.`/`1)` lists (one level; a list may interrupt a paragraph), fenced
123. code (``` / ~~~), `code`, `[text](url)`, `<https://…>`, bare http(s) URLs, `*em*`, `**strong**`,
124. `***both***` (also `_`), `\` escapes. Single line breaks inside a paragraph are KEPT (the page
125. showed them before). Not: quotes, tables, images, nested lists. Only pages and pushes carry the
126. parsed blocks (`md`, `summaryMd`, `oldSummaryMd` via `store.hl pageEventOf`); **API JSON unchanged**.
127. * **Read view for LLMs**: `Accept: text/markdown` on `GET /api/tickets`, `/api/projects/:slug/tickets`,
128. `/api/tickets/:ref`, `/api/projects/:slug/tickets/:number` → `text/markdown` (+ `Vary: Accept`),
129. built by `mdview.hl`: one ticket = `# <project> #n: <subject>`, a meta line, URL, the summary as
130. written, `## History` with one `### <seq> · <when> · <author> <what>` per event (texts below, an
131. edit shows "Subject before:" / "Summary before:" quoted); a list = `# Tickets (<filters>): N` +
132. one line per ticket. Markdown wins only if it is listed with q > 0 and preferred to
133. `application/json` (higher q, or same q and first); `*/*` / none → JSON. Errors stay JSON.
134. `curl -s -H 'Accept: text/markdown' http://127.0.0.1:8350/api/projects/tickets.worldapi.org/tickets/6`
135. * **Editing**: the ticket's AUTHOR (the user of its `created` event) edits subject + summary —
136. web: "Edit" on the ticket page (form, Save/Cancel), API: `POST …/edit { subject?, summary? }`.
137. **A ticket from before the login** (created event without a user, only an author string):
138. **only the creator** (`TICKETS_CREATOR_IDENTITY`) may edit it. Anyone else: web message, API
139. **403**. The edit is a new history event `kind:"edit"` with `oldSubject`/`oldSummary` +
140. `newSubject`/`newSummary` (+ `subjectChanged`/`summaryChanged`, `isEdit`) — earlier versions stay
141. (append-only); pushed live like a comment (the page takes over subject + summary). The page
142. shows "X edited the ticket", "Subject before" (struck through) and the previous summary folded.
143. No migration: only NEW events have the edit fields; existing JSON is byte-identical (mission 007 (old 014)
144. `.scratch/m014/compat.sh`).
145. * **SECURITY (hl:webex, patched locally until antcolony mission 036; hl:web escapes it itself, hybriel#34)**: webex put the page's state (= user text) into an
146. inline `<script>` without escaping `</script>` → a summary/comment with
147. `</script><img src=x onerror=…>` RAN in every viewer's browser (stored XSS, reproduced on the
148. pre-m014 code: `node .scratch/m014/xsscheck.mjs <url>` → `__pwned = 1`). Fixed in the vendored
149. `plugins/webex/WebFramework.hl` (seed: every `<` written as `\u003c`); to be filed as a Hybriel issue (mission 007 (old 014) report).
150. The gate's `</script>` check (MD_RICH) still guards it.
152. ## Markdown editor (ticket #12 — missions 009 (old 024) + antcolony 025)
154. * The new-ticket summary, the edit summary, the comment and the state note are `<md-editor>`s
155. around their textareas (`mdEditor { textarea { … } }`): edited visually (formatted while typing,
156. toolbar incl. phones, shortcuts), the textarea keeps the **plain Markdown** and fires `input` as
157. before — members, faces, API and stored data are unchanged. The state note is now a textarea
158. (rows 1): the editor writes line breaks. Ctrl/Cmd+Enter sends the form.
159. * A "Markdown source" button in a footer row at the bottom of every editor (antcolony mission 025, creator's
160. follow-up request) switches it to a plain textarea with the raw Markdown, to copy it out or edit
161. it by hand; "Visual editor" switches back (re-parses the typed text). Same `input`/`change`
162. events and Ctrl+Enter as the visual editor.
163. * The component is **vendored**: `shared/md-editor.js` = verbatim copy of
164. `/media/STORAGE/projects/worldapi-components/md-editor.js` (edit it THERE, test it there, `cp` it
165. here; `cmp` them). Served at `/md-editor.js` (project.hl), loaded once in the shell (main.hl).
166. Its README: attributes, keyboard, lossless rules, restyling. Colours: `mdEditor { '--md-…' = token }`
167. in `styles.hl`.
168. * Without JS the page shows the plain textareas (SSR); the forms themselves need JS as before
169. (webex faces).
170. * Only tickets' Markdown subset exists in the editor (its parser is a port of `markdown.hl`, checked
171. against it by the component's test with `ORACLE_APP`); pasted rich text is reduced to it; an
172. untouched text comes back byte for byte. **Keep `markdown.hl` and md-editor.js's parser in step.**
174. ## Relations: parent / child, blocked by (ticket #4 — mission 008 (old 017))
176. * **Parent / child**: a ticket has at most one parent (any project). The parent's page lists its
177. children with their states ("Children"); a child says "Part of <parent>". **Blocked by**: a ticket
178. can wait on any number of tickets (any project); the blocked page lists "Blocked by", the other
179. side "Blocks" — each with its state.
180. * **Parent state** (smallest rule): `allChildrenConfirmed` = the ticket has children and every child
181. is `confirmed`. The page shows "all children confirmed (n)" in green, else "k of n children
182. confirmed". The parent's own state is NEVER changed by it — only the creator confirms.
183. * **Who may set / remove a relation**: the AUTHOR of either of the two tickets (user of its created
184. event) or the creator (`TICKETS_CREATOR_IDENTITY`). A ticket from before the login has no author:
185. only the creator or the author of the other ticket. Replacing a parent needs the right for the old
186. AND the new pair. Refused: a ticket as its own parent / blocker, loops (a parent below the ticket,
187. a blocker that already waits on it, also transitively), duplicates, unknown tickets.
188. * **Naming a ticket**: `<project>#<number>` (spaces around `#` allowed, e.g. `ident.worldapi.org#1`)
189. or its UUID.
190. * **Storage**: a NEW table `storage/mpackdb/links.*` (`{ kind: 'parent'|'blockedBy', ticket, other,
191. user, created }`, indexes `@ticket`, `@other`), created empty at the first start — no migration. A
192. removed relation is deleted there; the HISTORY keeps every change: an event `kind:"link"` on the
193. child / the blocked ticket ("set the parent to X #1 (was Y #2)", "removed the parent X #1", "marked
194. it blocked by X #5", "removed the blocker X #5"; extra JSON keys `isLink, linkKind ('parent' |
195. 'blockedBy'), linkAction ('set' | 'removed'), otherRef, otherHref, previousRef` — only on link events).
196. * **JSON**: every ticket row (list AND single GET, pushes) has `parent` (a ref or `null`), `children`,
197. `blockedBy`, `blocks` (lists of refs, oldest link first) and `allChildrenConfirmed`. A ref =
198. `{ id, project, number, ref ('#1'), key ('ident.worldapi.org#1'), subject, state, stateSlug, href,
199. apiHref }`. All other keys unchanged (mission 008 (old 017) `.scratch/m017/compat.sh`).
200. * **Markdown view**: under the URL line `Parent: <p> #n [state] subject · url`, `Children (k of n
201. confirmed):` / `Children (all n confirmed):`, `Blocked by:`, `Blocks:` (one `- <p> #n [state]
202. subject · url` line each); a list line ends with ` · parent … · children n, k confirmed | all
203. confirmed · blocked by <p> #n [state], … · blocks …` (only the parts that exist).
204. * **Web** (logged in): under "Respond" the forms "Parent ticket (project#number)" → Set parent /
205. Remove parent, "Blocked by (project#number)" → Add blocker; a "Remove" button per blocker row.
206. Faces `ticketSetParent(id, key)` ('' = remove), `ticketAddBlocker`, `ticketRemoveBlocker`.
207. * **Live**: every relation write, state change and edit pushes `ticketsRelated(views)` — the relation
208. view of the ticket and of every ticket related to it (+ one just unlinked); an open page of any of
209. them follows without a reload (a child confirmed → the parent's "k of n" moves).
210. * **For the scheduler**: parent tickets = rows with `children.length > 0` (don't pick them as work);
211. a ticket waits while any `blockedBy[].state` is not what the scheduler counts as done. A report's
212. `issues[].blocks = true` → create the issue ticket, then `POST <original>/blocked-by {"add":
213. "<project>#<n>"}` with the scheduler's token (it is the issue's author, so it may).
215. ## PWA — installable app, icons, offline shell (antcolony mission 046)
216. Done the way calendar.worldapi.org does it: hl:web generates everything from `project.hl` — no JavaScript of ours.
217. - `appTitle` "tickets", `appIcons` (192/512, `any` + `maskable`, same PNGs), `appTouchIcon`, `appFavicon`,
218. `appThemeColor` = the header's `darker` `rgb(15, 20, 25)` (as tracker), `appBackgroundColor` = dark `rgb(25, 30, 35)` (both from `shared/tokens.hl`).
219. Served: `/__hl/manifest.webmanifest` (linked from every head with apple-touch-icon + theme-color), `/__hl/sw.js`.
220. - `offline = [ TicketList ]`: `/` is the ticket list, so offline it is the list as this browser last loaded it (the worker
221. precaches `/` at install; a visited `/projects/<slug>` is kept too). Every other page offline → hl:web's "Unavailable
222. offline" (503). TicketList's emits are all value-form, so nothing is queued offline.
223. - "You are offline" note in the shell (`components/main.hl` `offline`, `#offline`): hl:web has no connection state and no
224. mount hook, so an invisible `<net-probe>` runs an endless 1 s CSS animation (`styles.hl` `tickets-net-tick`) and every
225. `animationiteration` reads `navigator.onLine` (same trick as tracker).
226. - Icons `icons/`: `icon.svg` is the SOURCE (a tilted ticket stub, purple on dark, inside the maskable safe circle r=205).
227. Rebuild after editing it:
228. ```bash
229. cd icons && for s in 192 512; do rsvg-convert -w $s -h $s icon.svg -o icon-$s.png; done
230. rsvg-convert -w 180 -h 180 icon.svg -o apple-touch-icon.png
231. for s in 16 32 48; do rsvg-convert -w $s -h $s icon.svg -o /tmp/fav-$s.png; done
232. magick /tmp/fav-16.png /tmp/fav-32.png /tmp/fav-48.png favicon.ico
233. ```
234. Each icon has its own `file` route in `project.hl` (`/favicon.ico` serves `icons/favicon.ico`).
235. - Test: the gate's last part (browser C) — see "Test (the gate)".
237. ## Deploy (Byrodin)
239. Target: `/CONTAINERS/projects/tickets.worldapi.org` on Byrodin, container `tickets.worldapi.org`
240. (`docker-compose.yml`: debian:12-slim, host network, `HL_HOST=127.0.0.1`, `TICKETS_PORT=45003`,
241. `TICKETS_WATCH=0`, the folder mounted at `/home/tickets`, `./bin/hybriel project.hl`), public
242. https://tickets.worldapi.org/ via nginx (TLS ends there; the vhost needs the WebSocket Upgrade
243. headers — the live push rides `/__hl/socket`; no baseUrl/tls in the app, like notes).
244. * **First deploy: done by the architect** (folder + data, nginx vhost, cert, DNS).
245. * **Later: `./deploy.sh`** on Loreana, in this folder: runs the gate (refuses on a failure;
246. `--skip-tests` skips it LOUDLY), backs up `storage/`/`.sessions/`/`.env` (what exists) to
247. Loreana's `/media/SLOW1TB2/deploy-backups/<app>/` (newest 5 kept; an empty/failed backup stops
248. the deploy), then rsyncs the code to
249. `[email protected]:/CONTAINERS/projects/tickets.worldapi.org` (never `storage/`, `.sessions/`,
250. `.env`, `.scratch/`, `server.*`, `testapp/`, logs — the preview is checked for them; no
251. `--delete`), `docker compose up -d && docker compose restart` over `ssh -F /dev/null`, then
252. waits for https://tickets.worldapi.org/ to answer 200. Every step is printed.
253. * `./deploy.sh --dry-run` = gate + `rsync -n` + the commands it would run (no restart, no URL
254. check). `--target DIR|HOST:DIR` / `--url URL` point it elsewhere (tested only against a local
255. directory, ident STATUS "ident mission 006 (old 010)").
256. * Import on Byrodin: `TICKETS_URL=http://127.0.0.1:45003 TICKETS_TOKEN=tkt_… ./bin/hybriel import.hl` (in the container
257. or on the host with the vendored binary).
258. * Session cookie `hlsid` (host-only; tickets has its own host on Byrodin). Login: `.env` needs
259. `IDENT_API_KEY`, `IDENT_API_SECRET`, later `TICKETS_CREATOR_IDENTITY` (section "Login (ident)").
260. No migration: `users.*` / `tokens.*` are created empty at the first start; old events keep
261. their authors (checked mission 005 (old 011): every GET of old vs new code on a copy of the store identical).
263. ## Import the AntColony ticket files
265. ```bash
266. # on byrodin — refresh the copies:
267. scp /CONTAINERS/projects/antcolony/tickets/*.md loreana:/media/STORAGE/projects/tickets.worldapi.org/import/tickets/
268. # on loreana, with the server running (an API token of the user who should open them, /you):
269. TICKETS_TOKEN=tkt_… ./bin/hybriel import.hl # TICKETS_IMPORT_DIR (default ./import/tickets), TICKETS_URL (default http://127.0.0.1:8350)
270. ```
272. Format: `project:` and `subject:` header lines, blank line, summary (`ticketfile.hl`). The
273. summary is hard-wrapped text: its lines are joined into paragraphs (one space), a blank line
274. starts a new paragraph; a Markdown list line (`- `, `* `, `1. ` after trimming) starts a new
275. line (`\n`) and following ordinary lines join onto it (wrapped item; nesting indentation is
276. dropped); stored as paragraphs separated by `\n\n`, shown with `white-space: pre-wrap`. CRLF files work. Each file is POSTed to
277. the RUNNING server (`/api/tickets` with `source` = file name); a known source answers the
278. existing ticket, so re-running prints `0 new, N already there`. New tickets are numbered
279. per project in sorted file-name order (output: `NEW 0004-scheduler.md → antcolony #1`).
281. ## Ticket numbers, URLs, the migration (ticket #38)
283. * A ticket's key is the mpackdb UUID (`id`, e.g. `0mufbphip3w7`). People use **project +
284. number**: numbers count per project from 1 (next = highest in the project + 1).
285. * **Slug rule: the project slug IS the project name, as is.** A new project name may only hold
286. letters, digits, `.`, `_`, `-` (all existing names do), so it goes into URLs unescaped.
287. * Ticket page: **`/projects/<project>/<number>`** (e.g. `/projects/tickets.worldapi.org/5`).
288. `/projects/<project>` = the project's list (same as `/project/<project>`).
289. * **Old global numbers** (`#1`…`#39` in docs and comments) are kept on the migrated tickets
290. as `oldNumber`; the ticket page shows "formerly #38"; **`/tickets/<old n>` → 301** to the new
291. URL (also `/tickets/<uuid>`); `/api/tickets/<old n>` keeps answering. New tickets get no old number.
292. * Ordering never uses key order: lists by stored `updated`, a history by (`created`, `seq`),
293. projects by `created`.
294. * Migration 2026-09-24 (`tools/migrate-008.hl`, idempotent, header explains it): old #N →
295. `<project> #k` by creation order. Mapping printed in `.scratch/deploy-008-<ts>/migrate-run1.txt`;
296. or ask the API: `curl -s localhost:8350/api/tickets/38 | jq .ticket.href`.
298. ## Test (the gate)
300. ```bash
301. node tests/browser.mjs # 423 checks, ~2 min; own server on :8352, own ident on :8353,
302. # exchange-counting proxy on :8357 (TICKETS_GATE_EXCHANGE_PORT),
303. # own storage in .scratch/gate-store (ident's code copied WITHOUT
304. # .env to .scratch/gate-store/ident, mail to a sink — never real mail)
305. ```
307. **Ports** (mission 008 (old 017)): `TICKETS_GATE_PORT`, `TICKETS_GATE_IDENT_PORT`, `TICKETS_GATE_EXCHANGE_PORT`,
308. `TICKETS_GATE_CHROME_A` / `TICKETS_GATE_CHROME_B` (`"8810-8814"`; default 8620-8629 / 8630-8639) — a
309. worker with a port range runs e.g. `bash .scratch/m017/gate.sh <out.txt>` (8800-8819).
310. `TICKETS_GATE_CHROME_C` (default 8640-8649) is the PWA browser. antcolony Mission 046 ran it as
311. `TICKETS_GATE_PORT=8750 TICKETS_GATE_IDENT_PORT=8751 TICKETS_GATE_EXCHANGE_PORT=8752 TICKETS_GATE_CHROME_A=8753-8754
312. TICKETS_GATE_CHROME_B=8755-8756 TICKETS_GATE_CHROME_C=8757-8759 node tests/browser.mjs` → 245 passed (~30 s).
314. antcolony Mission 046 part (**PWA**, at the very end, own fresh Chrome C): head links manifest / apple-touch-icon / favicon /
315. theme-color; manifest fields; every icon a real PNG of its size; favicon.ico + icon.svg; the worker registered with
316. scope `/` and controlling; `Page.getInstallabilityErrors` empty; then the SERVER IS STOPPED and the page set offline
317. (CDP) → reload `/` shows header + last list + `#offline`; `/inbox` → "Unavailable offline"; online again → the note goes.
318. Screenshots `.scratch/gate-pwa-phone-online.png` / `gate-pwa-phone-offline.png` (390 px) — LOOK at them.
319. **Ident for the gate**: the gate runs ident's CODE from `../ident.worldapi.org` (or `TICKETS_GATE_IDENT_DIR`). On 2026-10-01 ident was
320. being re-vendored to hybriel master and its own sign-in broke (`ident /code page` timeout at browser.mjs:552; ident's own gate fails
321. the same way). Tickets' gate then ran against a snapshot of ident's code with ident's 837fe120 bin/plugins (what live ident runs):
322. `.scratch/w048/ident-snap` (`TICKETS_GATE_IDENT_DIR=$PWD/.scratch/w048/ident-snap`). Remake it from ident (without .env/storage/.sessions/.scratch) if ident moves on.
323. antcolony Mission 048 "**once:**" checks: after a comment, a state change and adding a member, the new row is in the list exactly once
324. (hybriel 64527baa+ answers a session face with a sync of session-derived members — a handler appending the row too would double it).
325. `connected(page)` in the gate waits until the server has READ the tab's `hello` (a ping on the same socket, its pong),
326. not just an open socket: a push sent before that reaches no component (the inbox-live check failed ~1 in 5 without it).
328. Mission 009 (old 024) part (**#12 Markdown editor**, before the console check): bob on his ticket — SSR has the
329. plain textareas inside `<md-editor>`, `/md-editor.js` served, editors upgraded; a comment by REAL typing
330. (`**x**`, `` `x` ``, `- ` list) sent with Ctrl+Enter → stored Markdown + rendered + editor cleared; a
331. state note with the toolbar "B"; a hostile rich paste (img onerror, script, javascript: link) reduced
332. to the subset, sent, rendered safely; the edit form opens the stored summary formatted and byte for
333. byte, typing at the end changes only that block, saved; at 390px the new-ticket form with toolbar
334. taps (inline code) → stored. Screenshots `gate-{phone,desktop}-mdeditor.png`, `gate-phone-newticket-mdeditor.png`.
335. The component's own test (72 checks): `worldapi-components/test/run.mjs`.
337. Mission 008 (old 017) part (**#4 relations**, after #8/#6): project `rel.example` — the gate user opens P (#1)
338. and C1–C3 (#2–#4), bob X (#5). API: set parent 3 ways (per-project, UUID route + UUID, `rel.example # 1`),
339. P's children + states, list rows carry the relations, row keys = old + exactly the 5 new, 14 refused
340. parent writes (401, 403 ×2, itself, unknown, no `#`, loop, same, none to remove, `{}`, unknown field,
341. non-string, author, 404) write nothing; who: bob (author of the child) sets/removes, a legacy ticket →
342. 403 for bob, 201 for alice (creator); replace (label "(was …)"), a grandchild loop. Blocked-by: add,
343. 13 refusals (401, 403, itself, twice, direct + 2-step loop, add+remove, `{}`, empty, unknown, not
344. blocking, unknown field, 404), remove; non-link events keep the old keys. Markdown: child
345. "Parent:" + "Blocked by:", parent "Children (0 of 3 confirmed):", blocker "Blocks:", list-line tails.
346. Browsers: B (bob) on P sees 3 children + "0 of 3"; signed out: relations yes, forms no; A (alice) on C2
347. "Part of …", "Remove parent" → B drops to 2 live, typed "Set parent" → 3 again, unknown parent →
348. message; B on X "Blocks", A "Add blocker" → both live, bob's face refused, 3 forged faces refused, the
349. row's "Remove"; alice confirms C1, C2 (API) → B "2 of 3", C3 (web) → "all children confirmed (3)" green,
350. P stays open. Screenshots `gate-{phone,desktop}-{parent,blocked}.png` — look at them.
352. Mission 007 (old 014) parts: **#8** — the gate user opens gamma #3 with a Markdown summary, edits subject
353. (per-project URL) and summary (`/api/tickets/<uuid>/edit`), history created/edit/edit with the old
354. values; 9 refused edits (no token 401, bob / alice (creator, not author) 403, `{}`, empty subject,
355. same values, unknown field, non-string, author → 400) write nothing; 404s; legacy alpha #1: gate /
356. bob 403, alice (creator) 201. In Chrome: bob's ticket (gamma #4) — "Edit" only for bob (not
357. alice, not signed out), the form (screenshots `gate-{phone,desktop}-edit.png`,
358. `gate-desktop-editbutton.png`), Cancel writes nothing, an empty subject is refused, Save → both
359. browsers show the new subject + rendered summary + "bob edited the ticket" with the previous
360. values, no reload (`gate-{phone,desktop}-markdown.png`); faces: alice refused, forged session
361. refused; legacy alpha #1: "Edit" for alice only; logout hides it, a selector login brings it back
362. without a reload. **#6** — JSON unchanged (non-edit events keep exactly the old keys;
363. `Accept: application/json` = no Accept); the read view (ticket, uuid form, project list, state
364. list, 7 Accept variants, errors stay JSON); the parser table (`tests/markdown.hl`); the rendered
365. summary in Chrome (headings, em/strong, code, lists, code block; ONLY the 3 safe links; no
366. script/img/handler element; raw HTML incl. `</script><img …>` shown as text; `window.__xss` unset);
367. a Markdown comment pushed live to both, a Markdown state note. **#11** — every page wait is
368. `TICKETS_GATE_SLOW`× (default 3) its timeout; the console check runs BEFORE ident is stopped,
369. both browsers park on `about:blank` first, then "nothing new in the console" after.
370. Load proof (mission 007 (old 014)): `node .scratch/m014/load.mjs <tickets url> 4 6` (4 headless Chromes ×
371. 6 tabs looping pages, ports 8700-8719, SIGTERM closes them) while the gate runs.
373. Ticket #7 part (login via ident, `tests/identkit.mjs`): our own ident from
374. `../ident.worldapi.org` (or `TICKETS_GATE_IDENT_DIR`), accounts alice / bob / gate, tickets
375. registered with origin `http://127.0.0.1:8352`, alice's per-app id computed (selector code +
376. exchange). Server #1 WITHOUT a creator: the machine user "gate" logs in through
377. `/login/callback` (no / unknown / reused code → 400), the name prompt, the name rules (empty,
378. 61 chars, asked once), a token over the face, `/you` shows its id, confirm / reject → 403.
379. Server #2 with `TICKETS_CREATOR_IDENTITY` = alice: the session survives the restart; every API
380. write with the gate token, `author` in a body → 400, 14 unauthenticated cases → 401 (auth before
381. the body), reads without token. Browsers: signed out = history + hint, no forms, a face write
382. refused, screenshots `gate-{phone,desktop}-signedout.png`; A = alice signs in to ident, then the
383. SELECTOR (no reload, `logged-in`, name prompt `gate-*-name.png`, forms appear,
384. `gate-*-loggedin.png`); B = bob via the LOGIN BUTTON (ident /signin → /login/callback → name);
385. writes show alice / bob / gate as authors; bob's confirm / reject refused (web + API 403), alice
386. confirms; bob's token on /you (shown once, `gate-*-tokens.png`, not after reload) → API write as
387. bob → revoke → 401; alice cannot revoke bob's token; 8 faces with a forged session (#31) refused;
388. old events keep "creator" / "worker"; logout resets the selector without a reload; ident stopped
389. → "ident did not answer" (400, no 500). Ident's log: `.scratch/gate-ident.log`.
390. Ticket #9: tickets reaches ident's `/api/exchange` through a proxy in the gate that COUNTS the
391. exchanges. alice gets a 2nd identity "alice two"; on a ticket page: logged in → Log out →
392. selector → "alice two": no `#loginerror`, exactly ONE exchange (200), no reload, `/you` shows
393. alice two's per-app id; then Log out → in-app click to the list → selector → "Default": again
394. one exchange, logged in as alice. Ticket #10: `/login/callback?next=` table (16 cases: paths
395. kept, `//host`, `https://`, `/\host`, `javascript:`, CR/LF, quotes, `/login/…`, 501 chars → `/`);
396. in Chrome bob logs out, clicks to a ticket (pushState URL), "Log in with ident" → ident → back
397. on that ticket, logged in; same from `/state/open`.
398. Manual repro of #9 with instrumentation (listeners, `change`s, socket frames, exchanges):
399. `node .scratch/m012/repro.mjs [appDir]` (`SCEN=ticket-nav|list|ticket-direct`, `SECOND=<identity>`;
400. ident :8363, proxy :8366, tickets :8362, Chrome 8640-8649; output `.scratch/m012/repro-run/out.txt`).
402. Ticket #38 part (runs first): `tests/oldstore.hl` writes an OLD-format store (5 tickets,
403. old #1–#5 in `alpha` / `beta.example.org`, a same-ms tie), `tools/migrate-008.hl` migrates a
404. copy of it TWICE (second run must print `0 new`), the server runs on the migrated tables:
405. old-number and per-project API (GET + POSTs), `/tickets/<n>` 301 (fetch and in Chrome),
406. "formerly #n", a real click on a list row, new tickets continue the numbering (alpha #4,
407. new project gamma #1), pushed rows carry `/projects/…` hrefs (list + inbox in browser B).
408. Screenshots also `gate-{phone,desktop}-legacy.png`.
410. It starts its own server, runs the import twice, drives the API, and opens TWO headless
411. Chromes (debug ports 8620-8629 / 8630-8639, `--disable-gpu`, killed by PID at the end):
412. filters by real clicks, a comment and state changes in browser A appear live in browser B
413. (no reload — checked with a window marker), API writes appear live in both, the inbox and
414. header count follow, the new-ticket form, and the layout at 390px and 1280px (no horizontal
415. overflow; screenshots `.scratch/gate-{phone,desktop}-{list,ticket,inbox}.png`,
416. `gate-phone-newticket.png`, `gate-phone-paragraphs.png` — look at them). Also: the strict-API
417. table (26 refused bodies, nothing written), Vienna time against node's `Intl`
418. (`bin/hybriel tests/localtime.hl` prints DST-edge samples), and a CRLF paragraph fixture
419. imported from `.scratch/gate-import` (→ #7). Ticket #15 (author cases replaced by ticket #7's "no author field"), 13 invalid
420. JSON bodies → 400 at the right character and no source path, valid escapes still accepted,
421. no name field in either form, a list fixture `.scratch/gate-import-lists` (→ #8) rendered as
422. separate lines (`gate-phone-lists.png`). Server log: `.scratch/gate-server.log`.
423. Chrome: `HL_CHROME` (default `/opt/google/chrome/chrome`, google-chrome is not on PATH).
425. Check for leaked Chromes afterwards: `ps -eo pid,args | grep [h]l-browser-tier` (must be empty).
427. ## Pages
429. | Route | Component | |
430. |---|---|---|
431. | `/` | `components/ticket_list.hl` | all tickets, newest update first; project + state filter chips; "New ticket" form |
432. | `/project/:projectName`, `/state/:stateSlug`, `/project/:p/state/:s` | same | filtered (state slug: `in-progress`, `awaiting-creator`, `on-hold`, …) |
433. | `/projects/:projectSlug/:ticketNumber` | `components/ticket.hl` | ticket, history, comment form, state change (select + optional note), "Edit" for the author (#8); texts rendered as Markdown (#6) |
434. | `/projects/:projectName` | `components/ticket_list.hl` | = `/project/:projectName` |
435. | `/tickets/:ref` | function route | 301 → `/projects/<p>/<n>` (`:ref` = old global number or UUID), else 404 |
436. | `/inbox` | `components/inbox.hl` | every ticket in `awaiting creator`, across projects (the creator's comment on one sets it to `answered` and it leaves the inbox) |
437. | `/you` | `components/you.hl` | the logged-in user: display name, own per-app identity id, creator or not; API tokens (create / list / revoke) |
438. | `/login/callback` | function route | the login button's return: `?ident_code=` → exchange → session → 302 to `?next=` (same-origin path only, else `/`; 400 page on failure) |
439. | `/login.js` | file | the selector bridge (`ident-login` → the shell's hidden `#identcode`, once per code) + `next=` on the login button |
441. Shell: `components/main.hl` (header, Inbox link with live count, top right the login: selector +
442. button, or name link to `/you` + Log out; the display-name prompt). All CSS: `styles.hl`
443. (tokens imported from `shared/tokens.hl` — section "Design tokens"; accent `colorAccent = var(purple)`
444. = #c586c0, `--color-danger: var(--red)` = #f44747; domain tags `<ticket-board>`, `<ticket-state>`, `<ticket-view>`,
445. `<event-head>`, …; mobile first, one `min-width: 45rem` block).
447. Live push (audience in `project.hl`): `ticketCreated(row, inboxCount)` and
448. `ticketEvent(ticketId (UUID), event, row, inboxCount)` (public), raised by the web faces AND the
449. API; `signedIn(tag, {name, named, creator})` / `signedOut(tag)` only to the tabs of the session
450. whose login carries that random tag (`session.data.tag`).
452. ## API (JSON)
454. `:ref` = the OLD global number of a migrated ticket (`38`) or the ticket's UUID (`id`).
455. `:slug` = project name, `:number` = per-project number. Both forms answer the same shapes.
457. | Method + path | Body | Answer |
458. |---|---|---|
459. | `GET /api/tickets[?project=&state=]` | — | `{ tickets: [row] }` (state as `awaiting creator` or slug) |
460. | `POST /api/tickets` | `{ project, subject, summary?, source? }` | 201 `{ ticket, existed:false }`; known `source` → 200 `{ ticket, existed:true }` |
461. | `GET /api/tickets/:ref` | — | `{ ticket, events: [event] }` (oldest first); 404 |
462. | `POST /api/tickets/:ref/comments` | `{ text }` | 201 `{ ticket, event }` |
463. | `POST /api/tickets/:ref/state` | `{ state, text? }` | 201 `{ ticket, event }`; 400 unknown/same state; 403 confirmed/rejected by a non-creator |
464. | `GET /api/projects/:slug/tickets[?state=]` | — | `{ tickets }`; 404 unknown project |
465. | `POST /api/projects/:slug/tickets` | `{ subject, summary?, source? }` | as `POST /api/tickets` |
466. | `GET /api/projects/:slug/tickets/:number` | — | `{ ticket, events }`; 404 |
467. | `POST /api/projects/:slug/tickets/:number/comments` | `{ text }` | 201 `{ ticket, event }` |
468. | `POST /api/projects/:slug/tickets/:number/state` | `{ state, text? }` | 201 `{ ticket, event }`; 403 as above |
469. | `POST /api/tickets/:ref/edit`, `POST /api/projects/:slug/tickets/:number/edit` | `{ subject?, summary? }` (≥ 1) | 201 `{ ticket, event (kind edit) }`; 403 not the author; 400 empty subject / nothing changed |
470. | `POST …/parent` (both forms) | `{ parent }` — `<project>#<n>` or UUID; `""` removes it | 201 `{ ticket, event (kind link) }`; 403 neither author nor creator; 400 `field:"parent"` (unknown, itself, loop, same, none to remove) |
471. | `POST …/blocked-by` (both forms) | `{ add }` or `{ remove }` (exactly one) | 201 `{ ticket, event (kind link) }`; 403 as above; 400 `field:"add"`/`"remove"` (unknown, itself, loop, twice, not blocking) |
473. Every ticket GET answers `Accept: text/markdown` with a Markdown document (section "Markdown, editing").
475. **Every POST needs `Authorization: Bearer <token>`** (ticket #7; a token from `/you`): missing,
476. malformed, unknown or revoked → **401** `{ error }` + `WWW-Authenticate: Bearer`, checked
477. before the body. The author is the token's user. GETs need nothing.
478. | `GET /api/projects` | — | `{ projects, states }` (projects in creation order) |
480. Ticket row: `id` (UUID), `project`, `number`, `ref` (`#5`), `href` (`/projects/<p>/<n>`),
481. `apiHref`, `oldNumber` (only if migrated) + `oldRef`/`hasOld`, `subject`, `summary`,
482. `state`, `stateSlug`, `source`, `created`/`updated` (+`Ms`), `events`, `projectHref`.
483. Event row: `id` (UUID), `ticket` (UUID), `project`, `number`, `seq`, `kind`, `author`,
484. `text`, `from`, `to`, `when`, `createdMs`, …
485. **Since #38 `ticket.id` is a UUID, not a number** — scripts that did `/api/tickets/${ticket.id}`
486. keep working (UUIDs are accepted); for display use `project` + `ref`.
488. **Strict** (ticket #10, `bodyError` in `api.hl`): a POST body must be a JSON object; an unknown
489. field, a missing or empty (after trim) required field, or a non-string value (null included)
490. → **400 `{ error, field }`** naming the field, and nothing is written. Semantic refusals
491. (unknown/same state, bad project name) also carry `field`. `author` is gone (ticket #7): a body
492. that has it → 400 `field:"author"` ("no field 'author' any more: the author is the user of your
493. API token"). Invalid JSON → **400 `{ error: "invalid JSON at
494. character N" }`** (no `field`, no source path): `jsoncheck.hl` checks the syntax BEFORE
495. `JSON.parse` — a WORKAROUND for hybriel #12 (no soft parse); remove it (and `readBody`'s call
496. in `api.hl`) once #12 is fixed. A LONE `\uD800`–`\uDFFF` escape is refused
497. too, because hl's `JSON.parse` aborts on it; a valid pair (`\ud83d\ude00`, Python's default
498. `ensure_ascii=True`) is accepted since hybriel#15 (antcolony mission 036). Other errors: `{ error }` with 404/405.
500. **Times**: `created` / `updated` / `when` are Europe/Vienna wall time `YYYY-MM-DD HH:MM`
501. (`localtime.hl`: EU DST rule, correct from 1996 on — hl:time has no time zones);
502. `updatedMs` / `createdMs` and the stored values are epoch ms (UTC). Example:
504. ```bash
505. curl -s -XPOST -H "Authorization: Bearer $TICKETS_TOKEN" -d '{"state":"awaiting creator","text":"done"}' http://127.0.0.1:8350/api/projects/tickets.worldapi.org/tickets/5/state
506. curl -s http://127.0.0.1:8350/api/tickets/38 | jq '.ticket | {project, number, href, oldNumber}' # old number still works
507. ```
509. Query the store directly: `curl -s http://127.0.0.1:8350/api/tickets | jq` (the mpackdb files
510. are binary; the API is the query tool).
512. ## Connecting an app to a project (ticket #21)
514. Another app (first: gitoria) is connected to ONE project; it then gets a key that reaches that project only. Code: `connections.hl`,
515. `components/connect.hl`, the connections line on the project page (`components/ticket_list.hl`), routes in `project.hl`. Data:
516. `storage/mpackdb/connections.db` (created empty at the first start; no migration).
518. 1. The app sends the browser to `GET /connect?app=<name>&label=<owner/repo>&return=<url>&state=<opaque>` (`label` and `state` optional; the state
519. comes back unchanged). The return URL must be https on `worldapi.org` or a subdomain — or start with an origin listed in the env
520. `TICKETS_CONNECT_ORIGINS` (comma separated, for dev copies). Else 400. A valid request is stored (1 hour) and the browser goes to `/connect/<nonce>`.
521. 2. On that page the person, logged in through ident with a display name, picks a project they are ADMIN of or makes a new one (they become its
522. admin) and confirms. The page says which app and host ask, then links back: `<return>?code=<one-time code>&state=<state>` (code valid 5 minutes).
523. A second connection of the same app + label to the same project replaces the first (its key dies).
524. 3. The app's SERVER swaps the code: `POST /api/connect/exchange {"code": "…"}` → `200 {key, project (slug), title, api}`. The key is `tktc_` + 48 hex,
525. shown once, only its sha256 is stored. Wrong / used / expired code → 400.
526. 4. The key: `Authorization: Bearer tktc_…` plus, on every write, `X-Tickets-Identity: <ident public id of the person>`. It works only on
527. `POST /api/projects/<slug>/tickets` and `POST /api/tickets` (create), `…/comments` and `…/state` of tickets of ITS project — the same
528. endpoints a user token uses, so "mentioned in PR" / "fixed by commit" is a comment or a state change with a note. The named person must have
529. logged in to tickets once and chosen a display name; **the project's roles apply to them** (use: comment, open ↔ review; edit / admin: more).
530. The author of what is written is that person. A key on any other endpoint (settings, members, invites, edit, assign, relations, inbox,
531. new project, disconnect) → 401; another project → 403; no / unknown identity → 403 naming the header. Reads need nothing.
532. 5. The project page shows "Connected to <app>: <label>" to everybody; an admin's **Disconnect** deletes the connection — the key is dead at once.
533. `GET /api/projects/<slug>/connections` lists them; `POST /api/projects/<slug>/connections/remove {"id"}` (user token, admin) disconnects.
535. Short copy for app workers: `docs/connect-apps.md` (the architect copies it next to antcolony-docs).
537. Gate: `node tests/connect.mjs` (ports 8700 / 8701 + Chrome 8703–8709; an ident stub, a real headless Chrome) → 60 checks.
539. ## Design tokens (shared, ticket antcolony#3 — antcolony mission 021)
541. * **`shared/tokens.hl`** declares the WorldAPI palette + semantic tokens as hl:web css variables,
542. hand-written: `static dark = var('rgb(25, 30, 35)')`, `static colorText = var(light)`, …
543. (`import { var } from 'hl:web/css'`). It is a copy of the one source
544. `loreana:/media/STORAGE/projects/worldapi-tokens/tokens.hl` (vendored like `plugins/`, no generator):
545. edit it THERE, then `cp /media/STORAGE/projects/worldapi-tokens/tokens.hl shared/tokens.hl` in every
546. app and restart it. Check: `cmp /media/STORAGE/projects/worldapi-tokens/tokens.hl shared/tokens.hl`.
547. (2026-09-26: the apps' copy = gitoria's/ident's; it differs from the source only in 3 COMMENT lines that
548. still say webex — update the source's comments, then the check is byte-exact again.)
549. * `styles.hl` IMPORTS the tokens it uses (`import { colorText, colorBorder, … } from './shared/tokens.hl'`)
550. and writes them as members: `color = colorText`, `border = '1px solid ' + colorBorder`. It sets only
551. its accent: `colorAccent = var(purple)` (#c586c0). A token it uses must be in the import list,
552. a new token must be added to tokens.hl (static) first.
553. * hl:web names each token after its member (`colorTextMuted` → `--color-text-muted`), writes EVERY
554. token of tokens.hl into the one `:root` (declaration order), then the app's `colorAccent` (a second
555. `--color-accent`, later wins), and writes each use as `var(--…)`. Components/JS may still use
556. `var(--color-…)` strings — the custom property names are the same.
557. * hl:web does this itself since hybriel#39 (the webex LOCAL PATCH of antcolony mission 021 is gone, antcolony mission 036).
558. * A change of tokens.hl or of styles.hl root members needs a RESTART: the dev watcher re-analyses
559. but the served sheet keeps the old values (measured, antcolony mission 021).
560. * Deploy: `shared/` is part of the app folder; `deploy.sh`'s rsync sends it (proved in antcolony mission 021:
561. deploy.sh excludes + debian:12-slim container → byte-identical `/__hl/app.css`).
563. ## Vendored Hybriel
565. **hybriel master 06617221** (antcolony mission 074, 2026-10-03; adds the plugin allocators 3a781359 + 413f60e4 (#126:
566. every plugin allocates with malloc via plugin_api.zig), mpackdb 2cb7ae5e (frees per-operation buffers), http1 773de63e (request
567. owns its parse), f0ac2d2d (event order; plugin ABI field — bin and .so must match); no lambda semantics change). sha256
568. `21059cc741459ded8a004d44ed17c071aa296609be9fd0359202383210d77bdb`, built the same way from `git archive 06617221`
569. (`~/scratch-074/src`, removed). Old vendor (190aa11d) in `.scratch/pre-074/`. Gates on 8760–8769: `TICKETS_GATE_PORT=8760
570. TICKETS_GATE_IDENT_PORT=8761 TICKETS_GATE_EXCHANGE_PORT=8762 TICKETS_GATE_CHROME_A=8763-8764 TICKETS_GATE_CHROME_B=8767-8768
571. TICKETS_GATE_CHROME_C=8769-8769 node tests/browser.mjs` → 249/0; connect.mjs as a temp copy (app URL :8762, Chrome 8763–8769,
572. TICKETS_CONNECT_PORT=8760 TICKETS_CONNECT_IDENT_PORT=8761) → 60/0. Memory: `LONG=1 node .scratch/w074/mem.mjs <tag> <app tree>
573. 8760` (live-storage copy in `.scratch/w074/realdata/storage`, deleted after the run; prints RSS + swap): new 315 → 335 (200) →
574. 312 (1200) → 315 MiB (5700 pairs) — **flat**; old 190aa11d 319 → 358 → 451 → 743 MiB.
576. Before: **hybriel master 190aa11d** (antcolony mission 072, 2026-10-02; adds fc838894 GC correctness (string index / plugin error message
577. read freed memory), 038d84b3 (#126 returned closure scopes collected), #127 (d98926c6, 04df4428); no lambda semantics change since
578. 7eea0d32). `bin/hybriel` sha256 `860f5e61878be75fe84a569eee03c95a25f2757940903b2ed0afee0871a23626`, built read-only from
579. `git archive 190aa11d` (`~/scratch-072/src`, removed) with `/media/STORAGE/projects/hybriel/native/zig-toolchain/zig build
580. -Doptimize=ReleaseFast -Dtarget=x86_64-linux-gnu.2.39` in `native/`; old copy (7eea0d32) in `.scratch/pre-072/`.
581. Memory proof: `node .scratch/w072/mem.mjs <tag> <app tree> <port>` (needs a live-storage copy in `.scratch/w072/realdata/storage`,
582. deleted after each run — re-tar it; env LONG=1 adds 3×1500): new 315 → 355 (200) → 418 (1200) → 706 MiB (5700), old 697 → 1365 → 1719 MiB.
583. Before: **hybriel master 7eea0d32** (antcolony mission 069, 2026-10-02; ≥ f685f240 = #126 collector also by bytes, includes #48 #112 #117 #119 #120).
584. `bin/hybriel` sha256 `f0d3019f46f83cbf119d0a426fab18394bfc6c02c58abaa725983fcc4bc734a0`, built read-only
585. (`git -C /media/STORAGE/projects/hybriel archive master | tar -x -C ~/scratch-…/src`, then
586. `cd native && /media/STORAGE/projects/termuplex/.tools/zig/zig build -Dtarget=x86_64-linux-gnu.2.39 -Doptimize=ReleaseFast`).
587. `plugins/{core,crypto,data,fetch,fs,http,http1,mpackdb,proc,time,web}` = master's — **no local patch**.
588. Re-vendor = copy the binary + these plugins, run the gate. The previous copy (73267707, sha 9707e0cc…) is in `.scratch/pre-069/`
589. (the one before, 837fe120, in `.scratch/pre-048/`).
590. **Lambda parameters COPY their argument since hybriel #48** (like methods); `&p` makes it a reference. A lambda that fills a list/record
591. it was given needs `&`: `migrate.hl` `migrateProjects/Tickets/Events/Members = (&log, …)` (without it the gate fails at
592. "migration: at the first start the log says what was migrated"). Audit script `.scratch/w069/audit.py <files>` (param mutations +
593. `for (x of param)` aliases). `store.hl` `sortByUpdated(rows)` sorts its copy and RETURNS it — callers use the return, fine.
594. antcolony Mission 048: `migrate.hl`'s `compactNow()` block (hybriel #110) removed (proof logs `.scratch/w048/`). Lesson (hybriel #122):
595. a post-face session sync must keep the route params — repro `.scratch/w048/repro/` (`node repro.mjs <bin>` must keep "you may edit").
596. The old webex generation (e565176b + LOCAL
597. PATCHes #34 seed escape, #39 tokens) is backed up in `.scratch/pre-036/` (bin, plugins, sources, tests).
599. * Framework pages use content-hashed URLs `/__hl/{hl-runtime.js,web/client.js,app.css}?v=…` (hashed =
600. `immutable`, bare = `no-cache`). Check: `~/scratch-036/hashcheck.sh tickets.worldapi.org TICKETS /` (own server :8730).
601. * Dropped with antcolony mission 036: plugins/webex + both LOCAL PATCHes, the NativeWebSocketServer listener
602. (HL_HOST, #24), `sessions.resolve(cookie)` in /login/callback (→ `req.session`, #11), `realSession()`
603. (→ `session == null`; hl:web refuses a forged trailing session itself, #16 — the gate's 12 forged checks
604. accept that ack `ok:false` "the `session` parameter is filled by the server"), the hand URL encoder
605. (→ `encodeURIComponent`, #14), import.hl's charCodeAt string order (→ `a > b`, #2), jsoncheck's refusal
606. of VALID surrogate pairs (#15; lone surrogates still abort JSON.parse → still 400).
607. * Kept on purpose: `jsoncheck.hl` (JSON.parse still aborts on bad input), `localtime.hl` (no time zones),
608. hand insertion sorts (no list `sort()`), `login.js` once-per-document guard (harmless).
609. The binary finds `plugins/` beside the app (it walks up from the script's directory).
610. `tests/cdp.mjs` + `tests/ports.mjs` are copies of the hybriel repo's `tests/browser/`.
612. ## Files
614. | File | |
615. |---|---|
616. | `project.hl` | manifest: routes (pages + API function routes), audience |
617. | `store.hl` | the tables (UUID keys, `storage/mpackdb/`), rows, reads, writes, per-project numbers; relations + `links` table (#4) |
618. | `users.hl` | ticket #7: users + tokens tables, the ident exchange, sessions → users, the login env |
619. | `login.js` | the selector bridge (plain JS, served at `/login.js`) |
620. | `shared/md-editor.js` | ticket #12: `<md-editor>`, vendored copy of worldapi-components (served at `/md-editor.js`) |
621. | `components/you.hl` | `/you`: account + API tokens |
622. | `tests/identkit.mjs` | the gate's own ident (a copy without .env, mail sink) and its login helpers |
623. | `tools/migrate-008.hl` | one-off (2026-09-24, ticket #38): old global tables → `storage/mpackdb/`, idempotent |
624. | `tests/oldstore.hl` | the gate's old-format fixture for the migration |
625. | `localtime.hl` | epoch ms → Vienna wall time (userland DST rule) |
626. | `ticketfile.hl` | ticket file parser + `paragraphsOf` (shared by import and the fix tool) |
627. | `tools/fix-import-summaries.hl` | one-off (2026-09-24): re-paragraph stored summaries of imported tickets |
628. | `markdown.hl` | ticket #6: Markdown text → blocks/spans (safe links); `components/markdown.hl` renders them |
629. | `mdview.hl` | ticket #6: the `Accept: text/markdown` read view (documents for one ticket / a list); relations (#4) |
630. | `tests/markdown.hl` | prints markdown.hl's blocks for `MD_INPUT` (the gate's parser table) |
631. | `api.hl` | JSON replies, query/body helpers (`readBody` = JSON check + strict fields) |
632. | `jsoncheck.hl` | hand-written JSON syntax check (workaround for hybriel #12) |
633. | `import.hl` | the import command (needs `TICKETS_TOKEN`) |
634. | `styles.hl` | all CSS (imports the tokens from `shared/tokens.hl`, sets the accent) |
635. | `shared/tokens.hl` | the WorldAPI tokens (webex `var()`), verbatim copy of worldapi-tokens/tokens.hl — README "Design tokens" |
636. | `components/` | shell + three pages |
637. | `icons/` | antcolony mission 046: `icon.svg` (source), `icon-192/512.png`, `apple-touch-icon.png`, `favicon.ico` — README "PWA" |
638. | `tests/browser.mjs` | the gate |
639. | `tests/localtime.hl` | prints Vienna renderings of DST edges (the gate compares with `Intl`) |
640. | `docker-compose.yml`, `deploy.sh` | Byrodin container; the deploy from Loreana (section "Deploy") |
641. | `import/tickets/` | copies of the AntColony ticket files (source: byrodin) |
643. ## History and worker briefs
644. - `LOG.md` — append-only history, one dated line per step (moved here from the antcolony LOG on 2026-10-01).
645. - `missions/NNN-*.md` — worker briefs for this app; `reports/NNN-*.md` — their reports (same name). Numbered per
646. project since 2026-10-01 (antcolony#40); older text, code comments and commits use the old antcolony numbers →
647. map: `/media/STORAGE/projects/antcolony-docs/docs/mission-map.md` (Byrodin: `/CONTAINERS/projects/antcolony/docs/mission-map.md`).