@verevoir/aigency-work 0.0.0-stage → 0.2.1

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.
@@ -0,0 +1,826 @@
1
+ // ASF as a board: a CardSource/CardSink pair over ASF's own task-and-resource
2
+ // HTTP API.
3
+ //
4
+ // THIS FILE DEFINES ITS OWN MINIMAL `AsfFetchInit`/`AsfFetchResponse`/
5
+ // `AsfFetch` SHAPES (below), RATHER THAN THE REAL DOM `RequestInit`/
6
+ // `Response`/`typeof fetch`, BECAUSE THIS PACKAGE'S tsconfig DECLARES NO DOM
7
+ // LIB -- those ambient identifiers do not exist as types here at all. The
8
+ // real global `fetch` satisfies `AsfFetch`'s shape structurally at runtime,
9
+ // so a caller can hand it straight in; these types exist purely because
10
+ // this file has nothing else to name that shape with. Every doc comment in
11
+ // this file (and in this file's own test file) that says "see the file
12
+ // header" for this is pointing at this paragraph.
13
+ //
14
+ // `fetchImpl` IS REQUIRED, WITH NO FALLBACK TO THE REAL GLOBAL `fetch`: no
15
+ // live ASF call can happen outside an explicitly supplied `fetchImpl`.
16
+ // Requiring the parameter, with nothing for a missing one to fall back to,
17
+ // means there is no code path in this file that can reach a real network
18
+ // without a caller handing it the means to. The token is never read from an
19
+ // environment variable here, logged, or echoed in any outcome this file
20
+ // returns.
21
+ //
22
+ // CARD ID = THE NATIVE ASF TASK ID, NEVER THE TICKET. `Card.id` here is
23
+ // ASF's own id for the task (e.g. "asf-1") -- the same key `reference`
24
+ // already builds a URL from. `properties.ticket` carries the
25
+ // externally-meaningful ticket (e.g. "BL-10") whenever ASF's own
26
+ // `properties.ticket` field is set, but it is ONLY ever a property: never
27
+ // substituted for `id`, and never the key `writeState`/`annotate` address
28
+ // their URLs with. A caller that reads a card back and then writes to it
29
+ // therefore always uses the exact id the read handed it -- there is no
30
+ // silent id-rewrite to reconcile between read and write. Mapping another
31
+ // system's id onto `properties.ticket` is that other system's own adapter's
32
+ // concern, not this file's: this file speaks only ASF's native id,
33
+ // verbatim, in both directions.
34
+ //
35
+ // `properties.ticket` ON READ IS NOT PURELY VERBATIM: it is ASF's own
36
+ // top-level `key` (e.g. "PROJ-9") when the task carries one, overriding
37
+ // whatever this file's catch-all `properties.ticket` parsing read in
38
+ // underneath it; only a task with no top-level `key` at all falls back to
39
+ // its raw `properties.ticket`. `properties.hierarchy` is mapped the same
40
+ // way from the task's top-level `parentId`. Both are READ-SIDE ONLY:
41
+ // `createCard`'s write side is unchanged and still sends whatever the
42
+ // caller's own `Card.properties.ticket`/`key` already is, verbatim, because
43
+ // a card being created has no ASF-assigned `key` yet to prefer.
44
+ //
45
+ // WHO A CLAIM IS ATTRIBUTED TO: when the credential this file authenticates
46
+ // with is a person principal with no runner bound, the claim and its Run
47
+ // are attributed to that person alone -- the API names no separate
48
+ // machine/"runner" identity in that case, and `run.runner` on every run
49
+ // this file's `claimNext`/`claim` mint is that same person. A runner-bound
50
+ // credential may be attributed differently; this file makes no claim about
51
+ // that case.
52
+ //
53
+ // DUPLICATE TICKETS are therefore no longer an id collision: native ids are
54
+ // already unique (ASF guarantees that), so two tasks sharing one ticket can
55
+ // still each be read, listed and written to individually by their own ids
56
+ // without any ambiguity about which one a lookup meant. It remains a real
57
+ // data-quality signal worth surfacing, so `list()` surfaces it as a
58
+ // property-level problem recorded against BOTH tasks' entries in
59
+ // `unparseable` -- ALONGSIDE their normal appearance in `cards`, not
60
+ // instead of it. `get()` by native id is unaffected either way: each task
61
+ // is still found by its own unambiguous id.
62
+ //
63
+ // READ LOGIC (the one GET per read, the properties/column mapping,
64
+ // non-string properties landing in `unknownFields`) maps the API's task
65
+ // shape to this boundary's `CardSource`/`CardSink` shape. `Card.state` is
66
+ // deliberately the RAW column the API returns, never mapped onto a closed
67
+ // status union: board.ts's own `State` doc is explicit it "must not become
68
+ // a union" -- there is no tracker-independent taxonomy this boundary owns.
69
+ // A readiness/queue filter is NOT applied here: `CardSource.list()` is
70
+ // documented as "what is on the board this source already points at" -- a
71
+ // filtered subset is a caller's concern, not this boundary's.
72
+ //
73
+ // THE WRITE MAPPING below (a moves endpoint, a read-merge-write annotate
74
+ // under If-Match, create-by-fields) answers the request/response shapes and
75
+ // status codes per the platform's published HTTP contract; see each
76
+ // method's own comments for the exact mapping.
77
+ //
78
+ // annotate's READ-MERGE-WRITE MERGES INTO THE RAW PROPERTIES OBJECT, not a
79
+ // string-filtered copy of it: every property the API returns -- arrays,
80
+ // nested objects, whatever is not a plain string -- survives an annotate
81
+ // untouched unless the patch itself replaces that key. It also never PUTs
82
+ // unless the GET it just did parsed as a safe `{revision: string,
83
+ // properties?: object}` shape: a read it could not trust to hand back a
84
+ // real, current revision is refused outright rather than risked as a PUT
85
+ // with no `If-Match` at all, which would silently overwrite the resource's
86
+ // real properties with whatever this file guessed.
87
+ import { z } from 'zod';
88
+ const PropertiesSchema = z
89
+ .object({
90
+ ticket: z.string().optional(),
91
+ builtBy: z.string().optional(),
92
+ requires: z.union([z.string(), z.array(z.string())]).optional(),
93
+ })
94
+ .passthrough()
95
+ .optional()
96
+ .default({});
97
+ // No refine requiring a non-empty ticket-or-id: `id` alone is this file's
98
+ // identity now (see the file header), so it is the only field that must be
99
+ // non-empty.
100
+ const RawTaskSchema = z
101
+ .object({
102
+ id: z.string().min(1),
103
+ column: z.string(),
104
+ title: z.string().optional(),
105
+ revision: z.string().optional(),
106
+ properties: PropertiesSchema,
107
+ // Per the platform's published HTTP contract, not guessed: `key` is
108
+ // the task's human-facing name (a non-empty string when present), and
109
+ // `parentId` names the task's parent resource (also a non-empty string
110
+ // when present). Both
111
+ // optional here even though a well-formed task always carries `key`:
112
+ // a fixture or an older server response that omits it must still
113
+ // parse, per this file's own "never guess past what parsed" discipline.
114
+ key: z.string().min(1).optional(),
115
+ parentId: z.string().min(1).optional(),
116
+ })
117
+ .passthrough();
118
+ function isPlainObject(value) {
119
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
120
+ }
121
+ /** The ticket identity this task maps to `properties.ticket`: its
122
+ * top-level `key` when present (ASF's own human-facing name for the task),
123
+ * else its raw `properties.ticket` -- the same preference `cardFrom`
124
+ * applies; see the file header's note on this. Used only for the
125
+ * duplicate-ticket signal below -- never for identity; see the file
126
+ * header. */
127
+ function ticketOf(task) {
128
+ if (typeof task.key === 'string' && task.key.trim() !== '') {
129
+ return task.key;
130
+ }
131
+ const ticket = task.properties.ticket;
132
+ return typeof ticket === 'string' && ticket.trim() !== '' ? ticket : undefined;
133
+ }
134
+ /** Splits a raw properties bag into the flat string record `Card.properties`
135
+ * can carry, and everything else -- arrays, numbers, nested objects -- which
136
+ * goes to `Card.unknownFields` instead of being silently dropped or coerced. */
137
+ function splitProperties(properties) {
138
+ const stringProps = {};
139
+ const nonStringProps = {};
140
+ for (const [key, value] of Object.entries(properties)) {
141
+ if (typeof value === 'string') {
142
+ stringProps[key] = value;
143
+ }
144
+ else {
145
+ nonStringProps[key] = value;
146
+ }
147
+ }
148
+ return { stringProps, nonStringProps };
149
+ }
150
+ function cardFrom(task, spaceId, baseUrl) {
151
+ const { stringProps, nonStringProps } = splitProperties(task.properties);
152
+ const properties = { ...stringProps };
153
+ // A real `properties.title` string ASF already set is never overwritten
154
+ // by the top-level `title` field below -- silently replacing one
155
+ // property's value with an unrelated field of the same name would be
156
+ // exactly the kind of drop this file's own header rules out. The
157
+ // top-level title is used only as a fallback when properties carries
158
+ // none at all.
159
+ if (typeof task.title === 'string' && properties.title === undefined) {
160
+ properties.title = task.title;
161
+ }
162
+ // The task's own `key` (e.g. "PROJ-9") is ASF's human-facing name for it --
163
+ // authoritative over whatever this file's catch-all `properties.ticket`
164
+ // carried in, so it is applied AFTER the string-properties spread above
165
+ // and overwrites any `ticket` already there.
166
+ if (typeof task.key === 'string' && task.key.trim() !== '') {
167
+ properties.ticket = task.key;
168
+ }
169
+ // `parentId` is the task's place in ASF's resource hierarchy -- surfaced
170
+ // as a flat property, like `ticket`, rather than added to `Card`'s own
171
+ // shape: this boundary's `Card` carries no tracker-specific hierarchy
172
+ // concept of its own (see card.ts's `state` doc on why this boundary
173
+ // does not invent taxonomy).
174
+ if (typeof task.parentId === 'string' && task.parentId.trim() !== '') {
175
+ properties.hierarchy = task.parentId;
176
+ }
177
+ const known = new Set(['id', 'column', 'title', 'revision', 'properties', 'key', 'parentId']);
178
+ const extraTop = {};
179
+ for (const [key, value] of Object.entries(task)) {
180
+ if (!known.has(key)) {
181
+ extraTop[key] = value;
182
+ }
183
+ }
184
+ return {
185
+ id: task.id,
186
+ state: task.column,
187
+ reference: `${baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/tasks/${encodeURIComponent(task.id)}`,
188
+ source: `asf:${spaceId}`,
189
+ properties,
190
+ unknownFields: { ...nonStringProps, ...extraTop },
191
+ ...(typeof task.revision === 'string' ? { revision: task.revision } : {}),
192
+ };
193
+ }
194
+ /** See the file header's "DUPLICATE TICKETS" -- one `unparseable` entry per
195
+ * task that shares its ticket with at least one other task on this read,
196
+ * naming every id in that ticket's group. Tasks are NOT removed from the
197
+ * caller's `tasks` list for this -- they remain normal, findable cards. */
198
+ function duplicateTicketProblems(tasks) {
199
+ const idsByTicket = new Map();
200
+ for (const task of tasks) {
201
+ const ticket = ticketOf(task);
202
+ if (ticket === undefined)
203
+ continue;
204
+ const ids = idsByTicket.get(ticket) ?? [];
205
+ ids.push(task.id);
206
+ idsByTicket.set(ticket, ids);
207
+ }
208
+ const problems = [];
209
+ for (const task of tasks) {
210
+ const ticket = ticketOf(task);
211
+ if (ticket === undefined)
212
+ continue;
213
+ const ids = idsByTicket.get(ticket) ?? [];
214
+ if (ids.length <= 1)
215
+ continue;
216
+ problems.push({
217
+ id: task.id,
218
+ problems: [
219
+ {
220
+ field: 'properties.ticket',
221
+ message: `ticket "${ticket}" is shared by tasks: ${[...ids].sort().join(', ')}`,
222
+ },
223
+ ],
224
+ });
225
+ }
226
+ return problems;
227
+ }
228
+ function errorNameOf(cause) {
229
+ return cause instanceof Error ? cause.name : 'unknown error';
230
+ }
231
+ function rawIdOf(raw, index) {
232
+ if (isPlainObject(raw) && typeof raw.id === 'string' && raw.id.trim() !== '') {
233
+ return raw.id;
234
+ }
235
+ return `(unreadable id at index ${index})`;
236
+ }
237
+ async function safeJson(response) {
238
+ try {
239
+ return await response.json();
240
+ }
241
+ catch {
242
+ return undefined;
243
+ }
244
+ }
245
+ async function fetchTasks(options) {
246
+ const fetchFn = options.fetchImpl;
247
+ let token;
248
+ try {
249
+ token = await options.getToken();
250
+ }
251
+ catch (cause) {
252
+ return { kind: 'unreachable', reason: `getToken() rejected with ${errorNameOf(cause)}` };
253
+ }
254
+ const url = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/tasks`;
255
+ let response;
256
+ try {
257
+ response = await fetchFn(url, { method: 'GET', headers: { Authorization: `Bearer ${token}` } });
258
+ }
259
+ catch (cause) {
260
+ return { kind: 'unreachable', reason: `fetch failed: ${errorNameOf(cause)}` };
261
+ }
262
+ if (response.status === 401 || response.status === 403) {
263
+ return { kind: 'unreachable', reason: `auth: ASF responded ${response.status}` };
264
+ }
265
+ if (!response.ok) {
266
+ return { kind: 'unreachable', reason: `ASF responded ${response.status} to the tasks read` };
267
+ }
268
+ const body = await safeJson(response);
269
+ const arrayResult = z.array(z.unknown()).safeParse(body);
270
+ if (!arrayResult.success) {
271
+ return {
272
+ kind: 'malformedBody',
273
+ problems: [{ field: 'body', message: 'response body is not an array' }],
274
+ };
275
+ }
276
+ const parsedTasks = [];
277
+ const parseFailures = [];
278
+ arrayResult.data.forEach((raw, index) => {
279
+ const parsed = RawTaskSchema.safeParse(raw);
280
+ if (!parsed.success) {
281
+ parseFailures.push({
282
+ id: rawIdOf(raw, index),
283
+ problems: parsed.error.issues.map((issue) => ({
284
+ field: issue.path.length > 0 ? issue.path.join('.') : '(root)',
285
+ message: issue.message,
286
+ })),
287
+ });
288
+ return;
289
+ }
290
+ parsedTasks.push(parsed.data);
291
+ });
292
+ return {
293
+ kind: 'ok',
294
+ data: {
295
+ tasks: parsedTasks,
296
+ unparseable: [...parseFailures, ...duplicateTicketProblems(parsedTasks)],
297
+ },
298
+ };
299
+ }
300
+ function hasDetails(body) {
301
+ return isPlainObject(body) && body.details !== undefined;
302
+ }
303
+ function detailsReasonOf(body) {
304
+ if (!isPlainObject(body))
305
+ return undefined;
306
+ const details = body.details;
307
+ if (!isPlainObject(details))
308
+ return undefined;
309
+ return typeof details.reason === 'string' ? details.reason : undefined;
310
+ }
311
+ function currentRevisionOf(body) {
312
+ if (!isPlainObject(body))
313
+ return undefined;
314
+ return typeof body.revision === 'string' ? body.revision : undefined;
315
+ }
316
+ function parseResource(body) {
317
+ if (!isPlainObject(body))
318
+ return undefined;
319
+ const revision = body.revision;
320
+ if (typeof revision !== 'string' || revision.trim() === '')
321
+ return undefined;
322
+ const propsRaw = body.properties;
323
+ if (propsRaw !== undefined && !isPlainObject(propsRaw))
324
+ return undefined;
325
+ return { revision, properties: isPlainObject(propsRaw) ? propsRaw : {} };
326
+ }
327
+ /**
328
+ * Both the queue claim and the nominate claim answer `201` with a bare run
329
+ * object -- never the task, never a combined envelope. Only `id` (the run
330
+ * id to pass to `completeRun`) and `taskId` (what to re-read to build the
331
+ * claimed `Card`) are read from it; every other field (`status`, `runner`,
332
+ * `number`, ...) is left alone by `.passthrough()`, because this file has
333
+ * no use for them yet and stripping them would be guessing at a shape
334
+ * narrower than what the API actually sends.
335
+ */
336
+ const ClaimedRunSchema = z
337
+ .object({
338
+ id: z.string().min(1),
339
+ taskId: z.string().min(1),
340
+ })
341
+ .passthrough();
342
+ /** Reads a bare `id` out of a claim's `201` body WITHOUT requiring the rest
343
+ * of it to parse as a `Run` -- used only to carry a best-effort `runId` on
344
+ * `claimed-unverified`, never to decide anything. `undefined` means no
345
+ * usable id could be read, not that the claim failed: the claim already
346
+ * happened on ASF's side regardless of what this finds. */
347
+ function looseRunIdOf(body) {
348
+ if (!isPlainObject(body))
349
+ return undefined;
350
+ return typeof body.id === 'string' && body.id.trim() !== '' ? body.id : undefined;
351
+ }
352
+ export function asfBoard(options) {
353
+ const fetchFn = options.fetchImpl;
354
+ async function authorizedFetch(url, init) {
355
+ let token;
356
+ try {
357
+ token = await options.getToken();
358
+ }
359
+ catch (cause) {
360
+ return { kind: 'unreachable', reason: `getToken() rejected with ${errorNameOf(cause)}` };
361
+ }
362
+ try {
363
+ const response = await fetchFn(url, {
364
+ ...init,
365
+ headers: { ...(init.headers ?? {}), Authorization: `Bearer ${token}` },
366
+ });
367
+ return { kind: 'ok', response };
368
+ }
369
+ catch (cause) {
370
+ return { kind: 'unreachable', reason: `fetch failed: ${errorNameOf(cause)}` };
371
+ }
372
+ }
373
+ async function get(id) {
374
+ const outcome = await fetchTasks(options);
375
+ if (outcome.kind === 'unreachable') {
376
+ return { outcome: 'unreachable', reason: outcome.reason };
377
+ }
378
+ if (outcome.kind === 'malformedBody') {
379
+ return { outcome: 'unparseable', id, problems: outcome.problems };
380
+ }
381
+ const { tasks, unparseable } = outcome.data;
382
+ const found = tasks.find((task) => task.id === id);
383
+ if (found !== undefined) {
384
+ return { outcome: 'found', card: cardFrom(found, options.spaceId, options.baseUrl) };
385
+ }
386
+ const direct = unparseable.find((record) => record.id === id);
387
+ if (direct !== undefined) {
388
+ return { outcome: 'unparseable', id, problems: direct.problems };
389
+ }
390
+ return { outcome: 'absent' };
391
+ }
392
+ async function list() {
393
+ const outcome = await fetchTasks(options);
394
+ if (outcome.kind === 'unreachable') {
395
+ return { outcome: 'unreachable', reason: outcome.reason };
396
+ }
397
+ if (outcome.kind === 'malformedBody') {
398
+ return {
399
+ outcome: 'cards',
400
+ cards: [],
401
+ unparseable: [{ id: '(response body)', problems: outcome.problems }],
402
+ danglingIds: [],
403
+ };
404
+ }
405
+ const { tasks, unparseable } = outcome.data;
406
+ if (tasks.length === 0 && unparseable.length === 0) {
407
+ return { outcome: 'empty' };
408
+ }
409
+ return {
410
+ outcome: 'cards',
411
+ cards: tasks.map((task) => cardFrom(task, options.spaceId, options.baseUrl)),
412
+ unparseable,
413
+ danglingIds: [],
414
+ };
415
+ }
416
+ async function writeState(id, state, writeOptions) {
417
+ const url = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/tasks/${encodeURIComponent(id)}/moves`;
418
+ const body = { column: state };
419
+ if (writeOptions?.expectedRevision !== undefined) {
420
+ body.expectedRevision = writeOptions.expectedRevision;
421
+ }
422
+ const result = await authorizedFetch(url, {
423
+ method: 'POST',
424
+ headers: { 'Content-Type': 'application/json' },
425
+ body: JSON.stringify(body),
426
+ });
427
+ if (result.kind === 'unreachable') {
428
+ return { outcome: 'unreachable', reason: result.reason };
429
+ }
430
+ const { response } = result;
431
+ if (response.status === 401 || response.status === 403) {
432
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${response.status}` };
433
+ }
434
+ if (response.status === 404) {
435
+ return { outcome: 'refused', reason: `no task exists for id "${id}"` };
436
+ }
437
+ if (response.status === 400) {
438
+ return { outcome: 'refused', reason: `ASF rejected the move to column "${state}" (400)` };
439
+ }
440
+ if (response.status === 409) {
441
+ const responseBody = await safeJson(response);
442
+ if (!hasDetails(responseBody)) {
443
+ if (writeOptions?.expectedRevision === undefined) {
444
+ // No guard was sent, so this cannot be a staleness conflict --
445
+ // ASF refused the move for some other, undisclosed reason. Never
446
+ // report `stale` naming a mismatch that was never checked.
447
+ return {
448
+ outcome: 'refused',
449
+ reason: 'ASF rejected the move with 409 and no further detail, and no expectedRevision ' +
450
+ 'guard was supplied, so this is not reported as a staleness conflict',
451
+ };
452
+ }
453
+ const currentRevision = currentRevisionOf(responseBody);
454
+ return {
455
+ outcome: 'stale',
456
+ id,
457
+ reason: "ASF rejected the move: expectedRevision did not match the task's current revision",
458
+ ...(currentRevision !== undefined ? { currentRevision } : {}),
459
+ };
460
+ }
461
+ const reason = detailsReasonOf(responseBody);
462
+ if (reason === 'archived') {
463
+ return {
464
+ outcome: 'refused',
465
+ reason: 'archived: this task has been archived and cannot be moved',
466
+ };
467
+ }
468
+ return {
469
+ outcome: 'refused',
470
+ reason: reason !== undefined
471
+ ? `ASF refused the move: ${reason}`
472
+ : 'ASF refused the move (409, unspecified reason)',
473
+ };
474
+ }
475
+ if (!response.ok) {
476
+ // Any OTHER non-ok status (5xx, or anything not named explicitly
477
+ // above) is never a DELIBERATE ASF refusal -- it is reported exactly
478
+ // as the same status would be on a read, so a caller can tell a
479
+ // broken/unavailable server apart from a considered "no".
480
+ return {
481
+ outcome: 'unreachable',
482
+ reason: `ASF responded ${response.status} to the move`,
483
+ };
484
+ }
485
+ return { outcome: 'applied' };
486
+ }
487
+ async function createCard(card) {
488
+ const { stringProps } = splitProperties(card.properties ?? {});
489
+ const subtype = typeof card.unknownFields.subtype === 'string'
490
+ ? card.unknownFields.subtype
491
+ : 'task';
492
+ const title = stringProps.title ?? card.id;
493
+ const bodyField = typeof card.unknownFields.body === 'string' ? card.unknownFields.body : undefined;
494
+ const key = stringProps.ticket ?? card.id;
495
+ // `title` is sent as its own top-level field above; `cardFrom` copies a
496
+ // read task's `title` into `Card.properties.title` purely as a read-side
497
+ // convenience (see cardFrom), so strip it back out here -- otherwise a
498
+ // round-tripped card writes the same title into ASF's properties bag a
499
+ // second time, alongside the dedicated `title` field.
500
+ const propertiesToSend = { ...stringProps };
501
+ delete propertiesToSend.title;
502
+ const fields = {
503
+ subtype,
504
+ title,
505
+ ...(bodyField !== undefined ? { body: bodyField } : {}),
506
+ properties: propertiesToSend,
507
+ key,
508
+ ...(card.state !== undefined && card.state !== '' ? { column: card.state } : {}),
509
+ };
510
+ const url = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/resources`;
511
+ const result = await authorizedFetch(url, {
512
+ method: 'POST',
513
+ headers: { 'Content-Type': 'application/json' },
514
+ body: JSON.stringify(fields),
515
+ });
516
+ if (result.kind === 'unreachable') {
517
+ return { outcome: 'unreachable', reason: result.reason };
518
+ }
519
+ const { response } = result;
520
+ if (response.status === 401 || response.status === 403) {
521
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${response.status}` };
522
+ }
523
+ if (response.status === 409) {
524
+ return { outcome: 'refused', reason: `key "${key}" already exists` };
525
+ }
526
+ if (!response.ok) {
527
+ // See writeState's own comment on this same branch.
528
+ return {
529
+ outcome: 'unreachable',
530
+ reason: `ASF responded ${response.status} to the create`,
531
+ };
532
+ }
533
+ return { outcome: 'applied' };
534
+ }
535
+ async function annotate(id, patch, writeOptions) {
536
+ const MAX_ATTEMPTS = 3;
537
+ const resourceUrl = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/resources/${encodeURIComponent(id)}`;
538
+ for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
539
+ const getResult = await authorizedFetch(resourceUrl, { method: 'GET' });
540
+ if (getResult.kind === 'unreachable') {
541
+ return { outcome: 'unreachable', reason: getResult.reason };
542
+ }
543
+ const getResponse = getResult.response;
544
+ if (getResponse.status === 401 || getResponse.status === 403) {
545
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${getResponse.status}` };
546
+ }
547
+ if (getResponse.status === 404) {
548
+ return { outcome: 'refused', reason: `no resource exists for id "${id}"` };
549
+ }
550
+ if (!getResponse.ok) {
551
+ // See writeState's own comment: an unnamed non-ok status is never
552
+ // a deliberate refusal.
553
+ return {
554
+ outcome: 'unreachable',
555
+ reason: `ASF responded ${getResponse.status} reading the resource to annotate`,
556
+ };
557
+ }
558
+ const resourceBody = await safeJson(getResponse);
559
+ const parsed = parseResource(resourceBody);
560
+ if (parsed === undefined) {
561
+ // NO PUT. A read this file cannot trust to hand back a real,
562
+ // current revision must never be followed by a write with no safe
563
+ // `If-Match` to pin -- see the file header's "annotate's
564
+ // READ-MERGE-WRITE".
565
+ return {
566
+ outcome: 'refused',
567
+ reason: `resource "${id}" could not be read back safely (its body did not parse as ` +
568
+ `{revision: string, properties?: object}); refusing to annotate without a safe ` +
569
+ `revision to pin If-Match to`,
570
+ };
571
+ }
572
+ const { revision: currentRevision, properties: currentProperties } = parsed;
573
+ if (writeOptions?.expectedRevision !== undefined &&
574
+ currentRevision !== writeOptions.expectedRevision) {
575
+ return {
576
+ outcome: 'stale',
577
+ id,
578
+ reason: "ASF's resource revision did not match expectedRevision",
579
+ currentRevision,
580
+ };
581
+ }
582
+ // Merges into the RAW properties object -- every non-string property
583
+ // ASF returned survives untouched unless `patch` itself replaces that
584
+ // key. See the file header's "annotate's READ-MERGE-WRITE".
585
+ const mergedProperties = {
586
+ ...currentProperties,
587
+ ...patch.properties,
588
+ };
589
+ const putResult = await authorizedFetch(resourceUrl, {
590
+ method: 'PUT',
591
+ headers: { 'Content-Type': 'application/json', 'If-Match': currentRevision },
592
+ body: JSON.stringify({ properties: mergedProperties }),
593
+ });
594
+ if (putResult.kind === 'unreachable') {
595
+ return { outcome: 'unreachable', reason: putResult.reason };
596
+ }
597
+ const putResponse = putResult.response;
598
+ if (putResponse.status === 401 || putResponse.status === 403) {
599
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${putResponse.status}` };
600
+ }
601
+ if (putResponse.status === 404) {
602
+ return { outcome: 'refused', reason: `no resource exists for id "${id}"` };
603
+ }
604
+ if (putResponse.status === 412) {
605
+ if (attempt === MAX_ATTEMPTS) {
606
+ return {
607
+ outcome: 'contentionExhausted',
608
+ reason: `annotate(${id}) lost the If-Match race ${MAX_ATTEMPTS} times in a row`,
609
+ };
610
+ }
611
+ continue;
612
+ }
613
+ if (!putResponse.ok) {
614
+ // See writeState's own comment: an unnamed non-ok status is never
615
+ // a deliberate refusal.
616
+ return {
617
+ outcome: 'unreachable',
618
+ reason: `ASF responded ${putResponse.status} writing the annotated resource`,
619
+ };
620
+ }
621
+ return { outcome: 'applied' };
622
+ }
623
+ return {
624
+ outcome: 'contentionExhausted',
625
+ reason: `annotate(${id}) lost the If-Match race ${MAX_ATTEMPTS} times in a row`,
626
+ };
627
+ }
628
+ /**
629
+ * Reads back the task a claim just minted a run for, and maps it exactly
630
+ * as a `CardSource` read would. The claim itself already landed on ASF's
631
+ * side by the time this runs -- a run exists and the card moved -- so a
632
+ * failure here (unreachable, or a body that does not parse) is reported
633
+ * as `{kind:'failed', reason}`, NEVER as a fabricated card standing in
634
+ * for one that was never actually read: inventing `state`/`properties`
635
+ * here would be indistinguishable downstream from a genuine read, which
636
+ * is exactly the dishonesty `annotate` already refuses elsewhere (see its
637
+ * own refusal to PUT on an unparseable GET, for the same reason).
638
+ */
639
+ async function cardForClaimedTask(taskId) {
640
+ const url = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/tasks/${encodeURIComponent(taskId)}`;
641
+ const result = await authorizedFetch(url, { method: 'GET' });
642
+ if (result.kind === 'unreachable') {
643
+ return { kind: 'failed', reason: result.reason };
644
+ }
645
+ const { response } = result;
646
+ if (!response.ok) {
647
+ return {
648
+ kind: 'failed',
649
+ reason: `ASF responded ${response.status} reading the claimed task back`,
650
+ };
651
+ }
652
+ const body = await safeJson(response);
653
+ const parsed = RawTaskSchema.safeParse(body);
654
+ if (!parsed.success) {
655
+ return {
656
+ kind: 'failed',
657
+ reason: 'the claimed task could not be read back: its body did not parse as a task',
658
+ };
659
+ }
660
+ return { kind: 'ok', card: cardFrom(parsed.data, options.spaceId, options.baseUrl) };
661
+ }
662
+ async function claimNext() {
663
+ const url = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/claims`;
664
+ const result = await authorizedFetch(url, { method: 'POST' });
665
+ if (result.kind === 'unreachable') {
666
+ return { outcome: 'unreachable', reason: result.reason };
667
+ }
668
+ const { response } = result;
669
+ if (response.status === 401 || response.status === 403) {
670
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${response.status}` };
671
+ }
672
+ // ASF's own two "nothing claimed" answers -- 404 (no ready work at all)
673
+ // and 409 (ready work exists, all of it spoken for) -- are collapsed
674
+ // into one `none` here: this boundary has nothing distinct to do with
675
+ // either (see board.ts's own doc on this).
676
+ if (response.status === 404 || response.status === 409) {
677
+ return { outcome: 'none' };
678
+ }
679
+ if (response.status === 400) {
680
+ return { outcome: 'refused', reason: 'ASF rejected the claim (400, invalid space id)' };
681
+ }
682
+ if (response.status !== 201) {
683
+ return {
684
+ outcome: 'unreachable',
685
+ reason: `ASF responded ${response.status} to the queue claim`,
686
+ };
687
+ }
688
+ const body = await safeJson(response);
689
+ const parsed = ClaimedRunSchema.safeParse(body);
690
+ if (!parsed.success) {
691
+ // ASF has ALREADY COMMITTED this claim -- the run was minted and the
692
+ // card moved -- by the time this 201 arrived; its body merely failed
693
+ // to parse as a Run. Reporting `unreachable` here would read as
694
+ // "nothing happened" and invite a caller to retry, claiming a second
695
+ // task for work ASF already assigned. `claimed-unverified` says the
696
+ // opposite plainly: the claim happened; do not retry; reconcile.
697
+ const looseId = looseRunIdOf(body);
698
+ return {
699
+ outcome: 'claimed-unverified',
700
+ ...(looseId !== undefined ? { runId: looseId } : {}),
701
+ reason: 'ASF answered 201 to the queue claim with a body that did not parse as a Run',
702
+ };
703
+ }
704
+ const cardRead = await cardForClaimedTask(parsed.data.taskId);
705
+ if (cardRead.kind === 'failed') {
706
+ return {
707
+ outcome: 'claimed',
708
+ card: undefined,
709
+ runId: parsed.data.id,
710
+ cardReadFailed: { reason: cardRead.reason },
711
+ };
712
+ }
713
+ return { outcome: 'claimed', card: cardRead.card, runId: parsed.data.id };
714
+ }
715
+ async function claim(id) {
716
+ const url = `${options.baseUrl}/api/spaces/${encodeURIComponent(options.spaceId)}/tasks/${encodeURIComponent(id)}/claims`;
717
+ const result = await authorizedFetch(url, { method: 'POST' });
718
+ if (result.kind === 'unreachable') {
719
+ return { outcome: 'unreachable', reason: result.reason };
720
+ }
721
+ const { response } = result;
722
+ if (response.status === 401 || response.status === 403) {
723
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${response.status}` };
724
+ }
725
+ if (response.status === 404) {
726
+ return { outcome: 'refused', reason: `no task exists for id "${id}"` };
727
+ }
728
+ if (response.status === 400) {
729
+ return { outcome: 'refused', reason: 'ASF rejected the claim (400, invalid task id)' };
730
+ }
731
+ if (response.status === 412) {
732
+ const body = await safeJson(response);
733
+ const reason = detailsReasonOf(body);
734
+ return {
735
+ outcome: 'refused',
736
+ reason: reason !== undefined
737
+ ? `the task is not claimable: ${reason}`
738
+ : 'the task is not claimable (412, unspecified precondition)',
739
+ };
740
+ }
741
+ if (response.status === 409) {
742
+ // The API answers a 409 with one of a named set of reasons --
743
+ // alreadyClaimed, diverged, faulted, requested, unbound -- a real
744
+ // decision ASF made about this one named task, never passed over
745
+ // silently the way the queue claim passes a task over.
746
+ const body = await safeJson(response);
747
+ const reason = detailsReasonOf(body);
748
+ return { outcome: 'conflict', reason: reason ?? 'unspecified' };
749
+ }
750
+ if (response.status !== 201) {
751
+ return {
752
+ outcome: 'unreachable',
753
+ reason: `ASF responded ${response.status} to the nominate claim`,
754
+ };
755
+ }
756
+ const body = await safeJson(response);
757
+ const parsed = ClaimedRunSchema.safeParse(body);
758
+ if (!parsed.success) {
759
+ // Same reasoning as claimNext's own: the claim already landed on ASF's
760
+ // side, so this is `claimed-unverified`, never `unreachable`.
761
+ const looseId = looseRunIdOf(body);
762
+ return {
763
+ outcome: 'claimed-unverified',
764
+ ...(looseId !== undefined ? { runId: looseId } : {}),
765
+ reason: 'ASF answered 201 to the nominate claim with a body that did not parse as a Run',
766
+ };
767
+ }
768
+ const cardRead = await cardForClaimedTask(parsed.data.taskId);
769
+ if (cardRead.kind === 'failed') {
770
+ return {
771
+ outcome: 'claimed',
772
+ card: undefined,
773
+ runId: parsed.data.id,
774
+ cardReadFailed: { reason: cardRead.reason },
775
+ };
776
+ }
777
+ return { outcome: 'claimed', card: cardRead.card, runId: parsed.data.id };
778
+ }
779
+ async function completeRun(runId, completionOptions) {
780
+ const url = `${options.baseUrl}/api/runs/${encodeURIComponent(runId)}/completion`;
781
+ const requestBody = { status: completionOptions.outcome };
782
+ // `reason` is sent ONLY for `'failed'` -- see `CompletionOptions`'s own
783
+ // doc ("Never sent for 'completed'"). A caller that supplies one
784
+ // alongside `'completed'` anyway has it silently dropped here, never
785
+ // forwarded to ASF.
786
+ if (completionOptions.outcome === 'failed' && completionOptions.reason !== undefined) {
787
+ requestBody.reason = completionOptions.reason;
788
+ }
789
+ const result = await authorizedFetch(url, {
790
+ method: 'POST',
791
+ headers: { 'Content-Type': 'application/json' },
792
+ body: JSON.stringify(requestBody),
793
+ });
794
+ if (result.kind === 'unreachable') {
795
+ return { outcome: 'unreachable', reason: result.reason };
796
+ }
797
+ const { response } = result;
798
+ if (response.status === 401 || response.status === 403) {
799
+ return { outcome: 'unreachable', reason: `auth: ASF responded ${response.status}` };
800
+ }
801
+ if (response.status === 404) {
802
+ return { outcome: 'refused', reason: `no run exists for id "${runId}"` };
803
+ }
804
+ if (response.status === 400) {
805
+ return { outcome: 'refused', reason: 'ASF rejected the completion body (400)' };
806
+ }
807
+ if (response.status === 409) {
808
+ const body = await safeJson(response);
809
+ const reason = detailsReasonOf(body);
810
+ return {
811
+ outcome: 'refused',
812
+ reason: reason !== undefined
813
+ ? `the run could not be completed: ${reason}`
814
+ : 'the run could not be completed (409, unspecified reason)',
815
+ };
816
+ }
817
+ if (response.status !== 200) {
818
+ return {
819
+ outcome: 'unreachable',
820
+ reason: `ASF responded ${response.status} to the completion`,
821
+ };
822
+ }
823
+ return { outcome: 'applied' };
824
+ }
825
+ return { get, list, writeState, createCard, annotate, claimNext, claim, completeRun };
826
+ }