@oakgreencc/cambium 0.0.3 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/src/marker.mjs +178 -21
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.3",
3
+ "version": "0.0.4",
4
4
  "description": "The scheduler daemon: reads the q:* queues from GitHub every tick, runs headless claude workers in their own worktrees up to a cap, and makes every queue transition itself.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "type": "module",
package/src/marker.mjs CHANGED
@@ -3,16 +3,36 @@
3
3
  * The cambium-owned state comment: a hidden JSON marker that is the truth,
4
4
  * plus a human-readable rendering of it. One per issue; cambium edits it in
5
5
  * place on every transition.
6
+ *
7
+ * Marker v2 names a position in a graph: `{ graph, graphVersion, node, status }`.
8
+ * v1 markers (a `stage` in the fixed task pipeline) are still read and are
9
+ * normalised to v2 in memory; the writer only emits v2.
10
+ *
11
+ * Until the graph runtime replaces the stage tick, v2 also carries the v1
12
+ * fields the tick drives (`phase`, `stage`, `pr`, `host`, …). While `stage` is
13
+ * present it is the tick's view and decides `node` (and `status`) on write.
6
14
  */
7
15
 
8
16
  /**
9
17
  * @typedef {'queued' | 'running' | 'submitted' | 'human' | 'done'} Stage
10
- * @typedef {{ at: string, attempt: number, outcome: string, reason?: string, pr?: number, log?: string }} HistoryEntry
18
+ * @typedef {'waiting' | 'entering' | 'done'} Status
11
19
  * @typedef {{
12
- * v: 1,
13
- * phase: 'task' | 'dispatch',
14
- * stage: Stage,
20
+ * at: string, attempt: number, outcome: string, reason?: string, pr?: number, log?: string,
21
+ * node?: string | null, spanId?: string,
22
+ * }} HistoryEntry
23
+ * @typedef {{
24
+ * v: 2,
25
+ * graph: string,
26
+ * graphVersion: number,
27
+ * node: string,
28
+ * status: Status,
29
+ * input: Record<string, unknown> | null,
15
30
  * attempt: number,
31
+ * traceparent: string | null,
32
+ * enteredAt: string | null,
33
+ * history: HistoryEntry[],
34
+ * phase: 'task' | 'dispatch',
35
+ * stage?: Stage,
16
36
  * pr: number | null,
17
37
  * branch: string | null,
18
38
  * host: string | null,
@@ -21,28 +41,88 @@
21
41
  * queued?: boolean,
22
42
  * failedSha?: string | null,
23
43
  * lastFailure?: string | null,
24
- * history: HistoryEntry[],
25
44
  * }} Marker
45
+ * @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
26
46
  */
27
47
 
28
48
  const PREFIX = '<!-- cambium:state '
29
49
  const RE = /<!-- cambium:state (.*?) -->/s
30
50
  const HISTORY_KEPT = 20
31
51
 
32
- /** @param {Partial<Marker>} [from] @returns {Marker} */
33
- export function newMarker(from = {}) {
34
- return {
35
- v: 1,
36
- phase: 'task',
37
- stage: 'queued',
52
+ /** The task graph's entry node: where a fresh or reset task issue starts. */
53
+ export const TASK_ENTRY = 'start-worker'
54
+
55
+ /** v1 `stage` → the task-graph node it corresponds to. */
56
+ export const STAGE_NODE = Object.freeze({
57
+ queued: TASK_ENTRY,
58
+ running: 'worker-running',
59
+ submitted: 'ci-running',
60
+ human: 'to-human',
61
+ done: 'close-out',
62
+ })
63
+
64
+ /**
65
+ * Markers written by the stage tick (and v1 markers) predate graph versions.
66
+ * A real graph version is ≥ 1, so a stage-era marker always goes through the
67
+ * node-still-exists check the first time the graph runtime sees it.
68
+ */
69
+ const STAGE_ERA_VERSION = 0
70
+
71
+ /** v2 defaults, without the stage tick's `stage`. @param {Partial<Marker>} from @returns {Marker} */
72
+ const withDefaults = (from) =>
73
+ syncStage({
74
+ graph: 'task',
75
+ graphVersion: STAGE_ERA_VERSION,
76
+ node: TASK_ENTRY,
77
+ status: 'waiting',
78
+ input: null,
38
79
  attempt: 1,
80
+ traceparent: null,
81
+ enteredAt: null,
82
+ phase: 'task',
39
83
  pr: null,
40
84
  branch: null,
41
85
  host: null,
42
86
  start: null,
43
87
  history: [],
44
88
  ...from,
45
- }
89
+ v: 2,
90
+ })
91
+
92
+ /**
93
+ * A fresh marker. Unless a `node` is given it is the stage tick's: `queued`
94
+ * at the task graph's entry.
95
+ *
96
+ * @param {Partial<Marker>} [from] @returns {Marker}
97
+ */
98
+ export const newMarker = (from = {}) => withDefaults(from.node ? from : { stage: 'queued', ...from })
99
+
100
+ /**
101
+ * While the stage tick drives the marker, `stage` decides the node: the tick
102
+ * only ever spreads a new `stage` into the marker.
103
+ *
104
+ * @param {Marker} m @returns {Marker}
105
+ */
106
+ function syncStage(m) {
107
+ if (!m.stage || !(m.stage in STAGE_NODE)) return m
108
+ return { ...m, node: STAGE_NODE[m.stage], status: m.stage === 'done' ? 'done' : 'waiting' }
109
+ }
110
+
111
+ /**
112
+ * A v1 marker as v2: stage → node, phase → graph, `start` → `enteredAt`. The
113
+ * v1 fields stay, so the stage tick keeps working on the result.
114
+ *
115
+ * @param {Record<string, any>} v1 @returns {Marker}
116
+ */
117
+ export function migrateV1(v1) {
118
+ return withDefaults({
119
+ stage: 'queued',
120
+ ...v1,
121
+ graph: v1.phase ?? 'task',
122
+ graphVersion: STAGE_ERA_VERSION,
123
+ enteredAt: v1.start ?? null,
124
+ history: Array.isArray(v1.history) ? v1.history : [],
125
+ })
46
126
  }
47
127
 
48
128
  /** @param {string | null | undefined} body @returns {Marker | null} */
@@ -51,28 +131,41 @@ export function parseMarker(body) {
51
131
  if (!m) return null
52
132
  try {
53
133
  const parsed = JSON.parse(m[1])
54
- return parsed && typeof parsed === 'object' ? newMarker(parsed) : null
134
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
135
+ if (parsed.v === 2) return withDefaults(parsed)
136
+ if (parsed.v === 1 || parsed.v === undefined) return migrateV1(parsed)
137
+ return null
55
138
  } catch {
56
139
  return null
57
140
  }
58
141
  }
59
142
 
60
- /** @param {Marker} marker @param {HistoryEntry} entry @returns {Marker} */
61
- export const withHistory = (marker, entry) => ({ ...marker, history: [...marker.history, entry].slice(-HISTORY_KEPT) })
143
+ /**
144
+ * Appends to the history (newest 20 kept). An entry without a `node` records
145
+ * the node the marker is at, i.e. where the outcome happened.
146
+ *
147
+ * @param {Marker} marker @param {HistoryEntry} entry @returns {Marker}
148
+ */
149
+ export const withHistory = (marker, entry) => ({
150
+ ...marker,
151
+ history: [...marker.history, { node: marker.node, ...entry }].slice(-HISTORY_KEPT),
152
+ })
62
153
 
63
154
  /**
64
155
  * The comment body. `--` inside the JSON would end the HTML comment early, so
65
- * it is written as a JSON escape.
156
+ * it is written as a JSON escape. Always emits v2.
66
157
  *
67
- * @param {Marker} marker
158
+ * @param {Marker} input
68
159
  * @param {{ maxAttempts?: number }} [opts]
69
160
  */
70
- export function renderMarker(marker, { maxAttempts } = {}) {
161
+ export function renderMarker(input, { maxAttempts } = {}) {
162
+ const marker = withDefaults(input)
71
163
  const json = JSON.stringify(marker).replace(/--/g, '-\\u002d')
72
164
  const of = maxAttempts ? `/${maxAttempts}` : ''
73
165
  const lines = [
74
166
  `${PREFIX}${json} -->`,
75
- `**cambium** · ${marker.phase} · ${marker.stage} · attempt ${marker.attempt}${of}` +
167
+ `**cambium** · ${marker.graph} · ${marker.node}${marker.status === 'waiting' ? '' : ` (${marker.status})`}` +
168
+ ` · attempt ${marker.attempt}${of}` +
76
169
  (marker.pr ? ` · PR #${marker.pr}` : '') +
77
170
  (marker.host ? ` · host \`${marker.host}\`` : '') +
78
171
  (marker.start ? ` · started ${marker.start}` : ''),
@@ -88,10 +181,10 @@ export function renderMarker(marker, { maxAttempts } = {}) {
88
181
  '</details>',
89
182
  )
90
183
  if (marker.history.length) {
91
- lines.push('', '| at | attempt | outcome | detail |', '|---|---|---|---|')
184
+ lines.push('', '| at | node | attempt | outcome | detail |', '|---|---|---|---|---|')
92
185
  for (const h of marker.history)
93
186
  lines.push(
94
- `| ${h.at} | ${h.attempt} | ${h.outcome} | ${[
187
+ `| ${h.at} | ${h.node ?? ''} | ${h.attempt} | ${h.outcome} | ${[
95
188
  h.pr ? `#${h.pr}` : '',
96
189
  h.reason ?? '',
97
190
  h.log ? `log \`${h.log}\`` : '',
@@ -105,3 +198,67 @@ export function renderMarker(marker, { maxAttempts } = {}) {
105
198
  lines.push('', '_Written by cambium. Only cambium moves this issue’s labels._')
106
199
  return lines.join('\n')
107
200
  }
201
+
202
+ // ---- Rules for the graph runtime (pure; the runtime applies them)
203
+
204
+ /**
205
+ * Label vs node: the queue label wins. If the issue's queue label is owned by
206
+ * a different graph than the marker's, or (when the owner lists its `nodes`)
207
+ * the marker's node does not sit in that queue, or the marker's graph is done,
208
+ * the issue restarts at the owning graph's entry node.
209
+ *
210
+ * No queue label known to `queues`: the marker stands (nothing to compare).
211
+ * No marker: a fresh start at the entry node, which is not a reset.
212
+ *
213
+ * @param {string[]} labels
214
+ * @param {Marker | null} marker
215
+ * @param {Record<string, QueueOwner>} queues queue label → owning graph
216
+ * @returns {{ graph: string, node: string, reset: boolean } | null} null: no queue label and no marker
217
+ */
218
+ export function effectivePosition(labels, marker, queues) {
219
+ const label = labels.find((l) => Object.hasOwn(queues, l))
220
+ if (!label) return marker ? { graph: marker.graph, node: marker.node, reset: false } : null
221
+ const owner = queues[label]
222
+ if (!marker) return { graph: owner.graph, node: owner.entryNode, reset: false }
223
+ const agrees =
224
+ marker.graph === owner.graph && marker.status !== 'done' && (!owner.nodes || new Set(owner.nodes).has(marker.node))
225
+ return agrees
226
+ ? { graph: marker.graph, node: marker.node, reset: false }
227
+ : { graph: owner.graph, node: owner.entryNode, reset: true }
228
+ }
229
+
230
+ /**
231
+ * Graph versioning: a marker written under an older version keeps running if
232
+ * its node still exists in the current version; otherwise it restarts at the
233
+ * entry node, with a history note saying why.
234
+ *
235
+ * @param {Marker} marker
236
+ * @param {{ version: number, nodes: Iterable<string>, entryNode: string, at: string }} current
237
+ * @returns {{ action: 'keep' } | { action: 'restart', node: string, note: HistoryEntry }}
238
+ */
239
+ export function graphVersionDecision(marker, { version, nodes, entryNode, at }) {
240
+ if (marker.graphVersion === version || new Set(nodes).has(marker.node)) return { action: 'keep' }
241
+ return {
242
+ action: 'restart',
243
+ node: entryNode,
244
+ note: {
245
+ at,
246
+ attempt: marker.attempt,
247
+ node: marker.node,
248
+ outcome: 'graph-changed',
249
+ reason: `${marker.graph} v${marker.graphVersion} → v${version}: node ${marker.node} no longer exists; restarting at ${entryNode}`,
250
+ },
251
+ }
252
+ }
253
+
254
+ /**
255
+ * `status: 'entering'` is written before a step node runs. On a later tick,
256
+ * a marker still `entering` with no tracked process means the step died
257
+ * mid-flight: the node's `recover` runs (default: requeue). Anything else
258
+ * resumes normally.
259
+ *
260
+ * @param {Marker} marker @param {boolean} hasTrackedProcess
261
+ * @returns {'resume' | 'recover'}
262
+ */
263
+ export const enteringDecision = (marker, hasTrackedProcess) =>
264
+ marker.status === 'entering' && !hasTrackedProcess ? 'recover' : 'resume'