antcolony

9.0 KB

1. // relations.hl — mission 022 (ticket antcolony#1; concept docs/scheduler-agent.md §2 "Picking work",
2. // "Creator questions are tickets", "Rejections are work"): what the ticket relations (tickets#4, mission 017:
3. // `parent`, `children`, `blockedBy`, `blocks` on every row) and the history mean for the scheduler.
4. //
5. // * a ticket with any blocker that is not `confirmed` is not eligible ("blocked by X#n (state)");
6. // * a ticket with children is a parent → not work — EXCEPT children that are creator questions (the scheduler's
7. // own: source `colony…:question…`; mission 023: also the architect's hand-filed ones, subject starting with
8. // `Question`): they hang below the ticket they belong to (parent = the ticket) and must not turn it into a
9. // parent (else a ticket with a question could never be reworked);
10. // * rejections: the last `→ rejected` event against the last colony session start (the `→ in progress`
11. // lease event of `work`: `colony-lease:` marker, or v0's "session <S> started on <H>"). Newer → eligible
12. // again. The brief starts with the rejection while no colony report came after it.
13. import { baseUrl } from './tickets.hl'
14. import { NL } from './util.hl'
16. // a creator question the scheduler filed (next --post, report questions / unknown-project issues, Nth controller fail)
17. static isQuestionSource = (src) => {
18. if (src == null || src == '') { return false }
19. return src.startsWith('colony') && src.includes(':question')
20. }
22. // a creator question: filed by the scheduler (source) OR by hand — the architect's convention is a subject that
23. // starts with `Question` (mission 023, creator 2026-09-24). Such children never make their ticket a parent.
24. static isCreatorQuestion = (row) => {
25. if (row == null) { return false }
26. if (isQuestionSource(row.source)) { return true }
27. if (row.subject == null || !row.subject.startsWith('Question')) { return false }
28. if (row.subject.length == 8) { return true }
29. // the whole word: `Question: …`, `Question (x#1): …`, `Questions …` — not `Questionnaire page`
30. let c = row.subject.charCodeAt(8)
31. if (c == 115) { c = row.subject.length == 9 ? 32 : row.subject.charCodeAt(9) }
32. return !((c >= 65 && c <= 90) || (c >= 97 && c <= 122))
33. }
35. // mission 030 (antcolony#1): a question ticket is NEVER work — in no state (open, rejected, on hold, …). The live run
36. // (pre-030) took rejected question tickets ("already answered") as rework: ident#17 once, gitoria#3 twice, gitoria#4
37. // five times. `next` / `run` / `cycle` list it with this reason, `brief` / `work` / `salvage` refuse it, a parked session
38. // on it is not resumed. Its answer reaches workers only through the librarian (DECISIONS.md in every brief).
39. static QUESTION_WHY = 'a question for the creator — the librarian takes its answer'
40. static questionWhy = (row) => { return isCreatorQuestion(row) ? QUESTION_WHY : null }
42. static listOf = (v) => { return v == null ? [] : v }
44. // a relation ref → `alpha#3 [open] subject`
45. static refText = (r) => { return r.project + r.ref + ' [' + r.state + '] ' + r.subject }
46. static refUrl = (r) => { return baseUrl() + r.href }
48. // row = a ticket row; lookup(id) → the child's row (for its `source`) or null
49. // → { has (tickets serves relations), parent, work (children that are work), questions (question children),
50. // blockedBy, openBlockers (not confirmed), blocks }
51. static relationsOf = (row, lookup) => {
52. let workKids = []
53. let questionKids = []
54. for (c of listOf(row.children)) {
55. let cr = lookup(c.id)
56. if (isCreatorQuestion(cr) || isCreatorQuestion(c)) { questionKids.push(c) } else { workKids.push(c) }
57. }
58. let openB = []
59. for (b of listOf(row.blockedBy)) { if (b.state != 'confirmed') { openB.push(b) } }
60. let hasRel = row.keys().includes('children')
61. return { has = hasRel parent = row.parent work = workKids questions = questionKids blockedBy = listOf(row.blockedBy) openBlockers = openB blocks = listOf(row.blocks) }
62. }
64. // why the ticket is not work because of its relations, or null
65. // `rework` = a rejection newer than the last session: the creator's rejection outranks a pending question
66. static blockReason = (rel, rework) => {
67. if (rel.work.length > 0) {
68. let k = 0
69. for (c of rel.work) { if (c.state == 'confirmed') { k = k + 1 } }
70. return 'a parent (' + rel.work.length + ' child ticket' + (rel.work.length == 1 ? '' : 's') + ', ' + k + ' confirmed) — not work itself, its children are'
71. }
72. // antcolony#30: a creator question of the ticket that is not answered yet (confirmed) or refused (rejected) → the ticket
73. // waits for it — a half-done ticket whose worker asked the creator must not be restarted every minute
74. let waiting = []
75. if (rework != true) { for (q of rel.questions) { if (q.state != 'confirmed' && q.state != 'rejected') { waiting.push(q.project + q.ref + ' (' + q.state + ')') } } }
76. if (waiting.length > 0) { return 'waiting for the creator\'s answer on ' + waiting.join(', ') }
77. if (rel.openBlockers.length > 0) {
78. let parts = []
79. for (b of rel.openBlockers) { parts.push(b.project + b.ref + ' (' + b.state + ')') }
80. return 'blocked by ' + parts.join(', ')
81. }
82. return null
83. }
85. // the start of a colony session in a ticket's history: the lease event of `work`
86. static isSessionStart = (e) => {
87. if (e.kind != 'state' || e.to != 'in progress' || e.text == null) { return false }
88. return e.text.includes('colony-lease: ') || (e.text.startsWith('session ') && e.text.includes(' started on '))
89. }
91. // events (oldest first) → { rejection (the last `→ rejected` event or null), lastSessionSeq, eligible (the last
92. // rejection is newer than the last colony session start), pending (a rejection no colony report answered yet),
93. // comments (the rejecting creator's comments since the last colony session before the rejection) }
94. static rejectionOf = (events) => {
95. let rej = null
96. let lastStart = 0
97. let startBefore = 0
98. let answered = false
99. for (e of events) {
100. if (isSessionStart(e)) { lastStart = e.seq }
101. if (e.kind == 'state' && e.to == 'rejected') {
102. rej = e
103. startBefore = lastStart
104. answered = false
105. } else if (rej != null && e.kind == 'comment' && e.text != null && e.text.includes('colony-report: ') && !e.text.includes(' · half done')) {
106. // mission 026: a HALF DONE report does not answer the rejection — the next worker continues and still reads it
107. answered = true
108. }
109. }
110. let cs = []
111. if (rej != null) {
112. for (e of events) {
113. if (e.seq > startBefore && e.kind == 'comment' && e.author == rej.author) { cs.push(e) }
114. }
115. }
116. let elig = rej != null && rej.seq > lastStart
117. let pend = rej != null && !answered
118. return { rejection = rej lastSessionSeq = lastStart eligible = elig pending = pend comments = cs }
119. }
121. // antcolony#30 (safety net): how many colony sessions started on the ticket within the last hour (events oldest first)
122. static startsInLastHour = (events, nowMs) => {
123. let n = 0
124. for (e of events) { if (isSessionStart(e) && e.createdMs != null && nowMs - e.createdMs < 3600000) { n = n + 1 } }
125. return n
126. }
128. static quoted = (text) => {
129. let out = []
130. for (l of text.trim().split(NL)) { out.push('> ' + l) }
131. return out.join(NL)
132. }
134. // the brief's first lines for a rejected ticket (list of lines)
135. static rejectedLines = (rj, ref) => {
136. let o = []
137. let e = rj.rejection
138. let reason = e.text == null || e.text.trim() == '' ? '_(no reason given with the rejection — see the comments / the history)_' : e.text.trim()
139. o.push('REJECTED by the creator: ' + reason)
140. o.push('')
141. o.push('_(' + e.author + ' set ' + ref + ' to `rejected` on ' + e.when + ', event ' + e.seq + ' of the history below.)_')
142. if (rj.comments.length > 0) {
143. o.push('')
144. o.push("The creator's comments since the last session:")
145. for (c of rj.comments) {
146. o.push('')
147. o.push('**' + c.when + '** (event ' + c.seq + '):')
148. o.push('')
149. o.push(quoted(c.text))
150. }
151. }
152. o.push('')
153. o.push('**Build what was described, not a workaround; if impossible, stop and explain** (in the report: `open` + `questions`) — never deliver a different design than the ticket and the creator describe.')
154. o.push('')
155. o.push('---')
156. o.push('')
157. return o
158. }
160. // the brief's "Relations" section (list of lines)
161. static relationLines = (rel) => {
162. let o = []
163. o.push('## Relations (parent / children / blocked by)')
164. if (!rel.has) {
165. o.push('- _(this tickets server serves no relations)_')
166. return o
167. }
168. o.push('- Parent: ' + (rel.parent == null ? 'none' : refText(rel.parent) + ' — ' + refUrl(rel.parent)))
169. let n = rel.work.length + rel.questions.length
170. if (n == 0) { o.push('- Children: none') } else {
171. o.push('- Children (' + n + '):')
172. for (c of rel.work) { o.push(' - ' + refText(c) + ' — ' + refUrl(c)) }
173. for (c of rel.questions) { o.push(' - ' + refText(c) + ' — creator question — ' + refUrl(c)) }
174. }
175. if (rel.blockedBy.length == 0) { o.push('- Blocked by: none') } else {
176. o.push('- Blocked by (' + rel.openBlockers.length + ' not confirmed):')
177. for (b of rel.blockedBy) { o.push(' - ' + refText(b) + (b.state == 'confirmed' ? '' : ' — **blocking**') + ' — ' + refUrl(b)) }
178. }
179. if (rel.blocks.length == 0) { o.push('- Blocks: none') } else {
180. o.push('- Blocks:')
181. for (b of rel.blocks) { o.push(' - ' + refText(b) + ' — ' + refUrl(b)) }
182. }
183. return o
184. }