@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.
- package/CHANGELOG.md +85 -0
- package/LICENSE +201 -0
- package/README.md +23 -2
- package/dist/asf-board.d.ts +29 -0
- package/dist/asf-board.js +826 -0
- package/dist/board.d.ts +428 -0
- package/dist/board.js +6 -0
- package/dist/card.d.ts +94 -0
- package/dist/card.js +89 -0
- package/dist/in-memory-board.d.ts +16 -0
- package/dist/in-memory-board.js +160 -0
- package/dist/in-memory-store.d.ts +26 -0
- package/dist/in-memory-store.js +79 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.js +15 -0
- package/dist/move-card.d.ts +141 -0
- package/dist/move-card.js +104 -0
- package/dist/multiplexer.d.ts +55 -0
- package/dist/multiplexer.js +54 -0
- package/dist/notion-board.d.ts +47 -0
- package/dist/notion-board.js +733 -0
- package/dist/payload-board.d.ts +50 -0
- package/dist/payload-board.js +225 -0
- package/dist/payload.d.ts +55 -0
- package/dist/payload.js +151 -0
- package/dist/schema-change.d.ts +78 -0
- package/dist/schema-change.js +0 -0
- package/dist/store-board.d.ts +33 -0
- package/dist/store-board.js +426 -0
- package/dist/store.d.ts +105 -0
- package/dist/store.js +13 -0
- package/package.json +45 -4
|
@@ -0,0 +1,426 @@
|
|
|
1
|
+
// A board — a `CardSource` and a `CardSink` — backed by a three-verb
|
|
2
|
+
// store (`store.ts`) rather than held in a process's own memory.
|
|
3
|
+
// `in-memory-board.ts` is honest about what it is: a fake, good enough
|
|
4
|
+
// to stand in for a real tracker in a demo or a test. Nothing this
|
|
5
|
+
// repository has ever stored has outlived the process that stored it.
|
|
6
|
+
// This file is the first board whose writes survive that process
|
|
7
|
+
// ending — not by owning a database, but by sitting over the narrowest
|
|
8
|
+
// store this repository could define: create, read, replace, on opaque
|
|
9
|
+
// keys and opaque values, mapping onto object storage with conditional
|
|
10
|
+
// writes rather than onto a database.
|
|
11
|
+
//
|
|
12
|
+
// list() and the index
|
|
13
|
+
// ---------------------
|
|
14
|
+
// This board once threw from list(), reporting "no enumeration
|
|
15
|
+
// primitive" as a finding rather than widening the store. That finding
|
|
16
|
+
// was wrong, or at least incomplete: the store has no enumeration
|
|
17
|
+
// primitive, but a board built over it can still keep its own list of
|
|
18
|
+
// keys — as an ordinary value, under a well-known key, maintained by
|
|
19
|
+
// the same `create` and `replace` every other write here already uses.
|
|
20
|
+
// `INDEX_KEY` names that value: an array of every card id this board
|
|
21
|
+
// has created. `createCard` adds to it; `list()` reads it and resolves
|
|
22
|
+
// each id. No new verb on `Store`. The set of keys becomes an object
|
|
23
|
+
// like any other, which is the answer the constraint was actually
|
|
24
|
+
// pointing at.
|
|
25
|
+
//
|
|
26
|
+
// Ordering, and which failure this board chooses to be recoverable
|
|
27
|
+
// -------------------------------------------------------------------
|
|
28
|
+
// `createCard` cannot atomically write a card and update the index in
|
|
29
|
+
// one step — the store has no transaction spanning two keys, only a
|
|
30
|
+
// compare-and-set on one key at a time. So one of the two writes
|
|
31
|
+
// happens first, and a failure between them is possible and must be
|
|
32
|
+
// reasoned about, not assumed away.
|
|
33
|
+
//
|
|
34
|
+
// This board writes the card first, and folds the id into the index
|
|
35
|
+
// second. A failure between them leaves a card that exists but is not
|
|
36
|
+
// yet listed — a leak, not a lie: `get(id)` still finds it (get never
|
|
37
|
+
// consults the index), and `list()` simply does not show it yet, which
|
|
38
|
+
// is indistinguishable from "not created yet", an entirely ordinary
|
|
39
|
+
// state for any board a caller might ask about mid-write. It is also
|
|
40
|
+
// self-healing: `createCard` is idempotent (`store.create` will report
|
|
41
|
+
// `alreadyExists`), so the exact same caller retrying the exact same
|
|
42
|
+
// call finishes the interrupted index update and the board converges.
|
|
43
|
+
//
|
|
44
|
+
// The other ordering — index first, card second — produces the opposite
|
|
45
|
+
// failure: an id the index names with no card behind it. Unlike the
|
|
46
|
+
// leak, that is not silently invisible; a caller who lists and then
|
|
47
|
+
// gets the id is told nothing is there, having just been told something
|
|
48
|
+
// was. And it does not self-heal the same way: a *different* caller who
|
|
49
|
+
// only sees the dangling id has no way to know what the card should
|
|
50
|
+
// have contained, so recovery depends on the original creator retrying,
|
|
51
|
+
// which nothing forces to happen. Between a failure mode that stays
|
|
52
|
+
// quiet until it is retried away and one that actively misleads a
|
|
53
|
+
// caller who was never part of the original write, the first is the one
|
|
54
|
+
// worth choosing. `list()` still reports the second kind honestly, as
|
|
55
|
+
// `danglingIds` (see `board.ts`), because choosing the safer ordering
|
|
56
|
+
// does not make it *impossible* — a store touched by something other
|
|
57
|
+
// than this board's own `createCard`, or a bug, could still produce
|
|
58
|
+
// one — only much less likely, and only ever from this board's own
|
|
59
|
+
// write path when it happens at all.
|
|
60
|
+
//
|
|
61
|
+
// The index is the hot key
|
|
62
|
+
// -------------------------
|
|
63
|
+
// Every `createCard` call, for every card, contends on the same
|
|
64
|
+
// `INDEX_KEY` — unlike `writeState`, whose compare-and-set is scoped to
|
|
65
|
+
// one card's own key and so only contends when two callers race the
|
|
66
|
+
// *same* card. A retry bound sized for "occasional collision between
|
|
67
|
+
// two callers of the same record" (`MAX_WRITE_STATE_ATTEMPTS`, argued
|
|
68
|
+
// below) is the wrong number for "every creator, of every card, touches
|
|
69
|
+
// this one key" — under real concurrent creation, losing the index race
|
|
70
|
+
// is not bad luck at the margin, it is the ordinary cost of writing
|
|
71
|
+
// through a single serialization point, and it happens to every writer
|
|
72
|
+
// in proportion to how many others are racing it at the same moment,
|
|
73
|
+
// not to some small independent chance each one carries alone.
|
|
74
|
+
// `MAX_INDEX_ATTEMPTS`, argued at its own definition below, gives this
|
|
75
|
+
// specific loop more headroom for exactly that reason — and is still
|
|
76
|
+
// wrong at its edge in the same way every bound here is: a burst of
|
|
77
|
+
// concurrent creation large enough will still exhaust it, honestly,
|
|
78
|
+
// rather than pretending it cannot happen.
|
|
79
|
+
//
|
|
80
|
+
// Contention as a typed outcome, not a string
|
|
81
|
+
// ---------------------------------------------
|
|
82
|
+
// Exhausted contention used to be reported as `refused`, with a reason
|
|
83
|
+
// that started with an exported prefix a caller could check for. That
|
|
84
|
+
// was named as a real cost when it was written — checkable only by
|
|
85
|
+
// convention, surviving no refactor that touched the message — and is
|
|
86
|
+
// fixed here rather than left, now that the index makes this outcome
|
|
87
|
+
// common rather than rare: `WriteResult` and `MoveResult` both gained a
|
|
88
|
+
// `contentionExhausted` variant (see `board.ts`, `move-card.ts`), and
|
|
89
|
+
// `moveCard`'s handling of it was added explicitly rather than left to
|
|
90
|
+
// fall through — a write result nothing recognises is not skipped, it
|
|
91
|
+
// silently reads as success, which is worse than the string-prefix
|
|
92
|
+
// problem it replaces.
|
|
93
|
+
//
|
|
94
|
+
// The revision lives IN the card's own record, not beside it
|
|
95
|
+
// -------------------------------------------------------------
|
|
96
|
+
// An earlier version of this board kept a card's optimistic-concurrency
|
|
97
|
+
// revision (see `board.ts`'s `WriteOptions`) under a second key,
|
|
98
|
+
// `rev:<id>`, written independently of the card itself. That was wrong
|
|
99
|
+
// in a way that made the whole feature inert: nothing ever created
|
|
100
|
+
// `rev:<id>` except a guarded write that had ALREADY matched an
|
|
101
|
+
// expected revision against it — so on a freshly created card, before
|
|
102
|
+
// any guarded write had ever succeeded once, the key never existed, a
|
|
103
|
+
// guarded write always compared its `expectedRevision` against
|
|
104
|
+
// "nothing", and every such write failed as `contentionExhausted`,
|
|
105
|
+
// permanently. Worse, checking the side key and bumping it were two
|
|
106
|
+
// separate, non-atomic operations — a write could apply to the card
|
|
107
|
+
// while its revision bump silently failed (the old code discarded the
|
|
108
|
+
// bump's own result), after which a STALE `expectedRevision` would
|
|
109
|
+
// still match the un-bumped key and a write that should have been
|
|
110
|
+
// rejected would be accepted instead. A guard that can let a stale
|
|
111
|
+
// caller through is not a guard.
|
|
112
|
+
//
|
|
113
|
+
// The fix: the revision is a field on the stored `Card` itself (exactly
|
|
114
|
+
// as `createInMemoryBoard` already does it), so `createCard`'s own
|
|
115
|
+
// `store.create` seeds it, and `writeState`/`annotate`'s own
|
|
116
|
+
// `store.replace` bumps it IN THE SAME CALL as the change it is
|
|
117
|
+
// guarding — there is no window in which the card changes without its
|
|
118
|
+
// revision changing with it, and no separate write that can fail on its
|
|
119
|
+
// own. `get`/`list` need no special handling: the revision is already
|
|
120
|
+
// part of the value they read.
|
|
121
|
+
/**
|
|
122
|
+
* The reserved key under which this board keeps the list of every card
|
|
123
|
+
* id it has created — an ordinary value in the same store, not a
|
|
124
|
+
* capability the store itself has to provide. Exported for tests that
|
|
125
|
+
* need to construct a scenario this board's own operations do not
|
|
126
|
+
* produce (a dangling index entry) by writing to the store directly;
|
|
127
|
+
* not part of `StoreBoard`'s own public surface.
|
|
128
|
+
*/
|
|
129
|
+
export const INDEX_KEY = 'index';
|
|
130
|
+
function cardKey(id) {
|
|
131
|
+
// Namespaced so a card id can never collide with `INDEX_KEY` — every
|
|
132
|
+
// card key carries a prefix the index key does not and never will.
|
|
133
|
+
return `card:${id}`;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* The next revision after `current`, as a string.
|
|
137
|
+
*
|
|
138
|
+
* `current` is `undefined` only for a record this board's own write
|
|
139
|
+
* path never seeded one for — never expected in practice, since
|
|
140
|
+
* `createCard` always seeds `'1'`, but a store this board does not
|
|
141
|
+
* control could in principle hold a record without one. That case
|
|
142
|
+
* becomes `'1'` — the same starting point `createCard` itself would
|
|
143
|
+
* have produced.
|
|
144
|
+
*
|
|
145
|
+
* A `current` that is defined but not a plain integer is a DIFFERENT
|
|
146
|
+
* fact, and must not be treated the same way: it is not "never
|
|
147
|
+
* seeded", it is "seeded once, then changed into something this
|
|
148
|
+
* board's own write path could never have produced" — by something
|
|
149
|
+
* outside this board's control. Collapsing it to the same `'1'` a
|
|
150
|
+
* fresh card gets would let a caller holding an old, genuinely-issued
|
|
151
|
+
* `'1'` — read long before whatever corrupted this record — match
|
|
152
|
+
* again and get `applied` where `stale` was owed. Instead it is
|
|
153
|
+
* bumped into a `recovered:N` namespace no ordinary integer sequence
|
|
154
|
+
* this function produces can ever enter, so it can never again
|
|
155
|
+
* coincide with an old numeric `expectedRevision`, and is bumped
|
|
156
|
+
* further the same deterministic way on every subsequent write.
|
|
157
|
+
*/
|
|
158
|
+
function nextRevision(current) {
|
|
159
|
+
if (current === undefined) {
|
|
160
|
+
return '1';
|
|
161
|
+
}
|
|
162
|
+
const asPlainInteger = /^(\d+)$/.exec(current);
|
|
163
|
+
if (asPlainInteger !== null) {
|
|
164
|
+
return String(Number.parseInt(asPlainInteger[1], 10) + 1);
|
|
165
|
+
}
|
|
166
|
+
const alreadyRecovered = /^recovered:(\d+)$/.exec(current);
|
|
167
|
+
if (alreadyRecovered !== null) {
|
|
168
|
+
return `recovered:${Number.parseInt(alreadyRecovered[1], 10) + 1}`;
|
|
169
|
+
}
|
|
170
|
+
return 'recovered:1';
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* How many times `writeState` and `annotate` each retry a losing
|
|
174
|
+
* compare-and-set on one card's own key before giving up. Scoped to a
|
|
175
|
+
* single card: two callers racing to write the *same* card is an
|
|
176
|
+
* occasional event on a shared board, not the common case.
|
|
177
|
+
*
|
|
178
|
+
* Too low, and this loop stops doing the one thing it exists for: `1`
|
|
179
|
+
* means the very first ordinary collision surrenders the write outright,
|
|
180
|
+
* indistinguishable from not retrying at all. Too high, and a caller
|
|
181
|
+
* stuck behind a genuinely hot record waits far longer than the answer
|
|
182
|
+
* is worth — a slow, eventually-successful write is not obviously better
|
|
183
|
+
* than a fast, clear failure a caller can act on.
|
|
184
|
+
*
|
|
185
|
+
* `5` is small enough to fail fast under sustained contention on one
|
|
186
|
+
* record, and large enough that the ordinary case — a handful of
|
|
187
|
+
* occasional, overlapping writers on that record, not a high-throughput
|
|
188
|
+
* hot key — converges well within it. Wrong at its own edge in exactly
|
|
189
|
+
* the way worth naming: five writers genuinely racing the same card at
|
|
190
|
+
* the same instant could plausibly exhaust five attempts on bad luck
|
|
191
|
+
* alone, even though the store is healthy.
|
|
192
|
+
*/
|
|
193
|
+
const MAX_WRITE_STATE_ATTEMPTS = 5;
|
|
194
|
+
/**
|
|
195
|
+
* How many times the index update inside `createCard` retries a losing
|
|
196
|
+
* compare-and-set on `INDEX_KEY` before giving up. Deliberately larger
|
|
197
|
+
* than `MAX_WRITE_STATE_ATTEMPTS`, and argued separately, because it
|
|
198
|
+
* answers a different question: not "how much bad luck should one
|
|
199
|
+
* card's occasional collision survive" but "how much contention should
|
|
200
|
+
* the single busiest key in this whole board survive", since every
|
|
201
|
+
* creator of every card contends here, not just two callers who happen
|
|
202
|
+
* to want the same record.
|
|
203
|
+
*
|
|
204
|
+
* `20` gives real headroom for the kind of concurrency this board is
|
|
205
|
+
* actually meant for — several to a dozen or so overlapping creators,
|
|
206
|
+
* the ordinary shape of a handful of adapters or a moderate sync job
|
|
207
|
+
* running at once — while still being wrong at its edge, and honestly
|
|
208
|
+
* so: a bulk import launching tens of creations at the same instant
|
|
209
|
+
* against the same board could still exhaust even this many attempts
|
|
210
|
+
* for whichever writer is unlucky enough to keep losing. That is not a
|
|
211
|
+
* case this bound is supposed to make impossible — `contentionExhausted`
|
|
212
|
+
* exists precisely to report that case truthfully rather than hide it
|
|
213
|
+
* behind a bound large enough to look like it never happens. A caller
|
|
214
|
+
* doing genuinely bulk creation is better served serializing through a
|
|
215
|
+
* single writer than firing many truly-concurrent creates at one index
|
|
216
|
+
* and leaning on this number to save it.
|
|
217
|
+
*/
|
|
218
|
+
const MAX_INDEX_ATTEMPTS = 20;
|
|
219
|
+
async function addIdToIndex(store, id) {
|
|
220
|
+
for (let attempt = 1; attempt <= MAX_INDEX_ATTEMPTS; attempt += 1) {
|
|
221
|
+
const read = await store.read(INDEX_KEY);
|
|
222
|
+
if (read.outcome === 'unreachable') {
|
|
223
|
+
return { ok: false, outcome: 'unreachable', reason: read.reason };
|
|
224
|
+
}
|
|
225
|
+
if (read.outcome === 'absent') {
|
|
226
|
+
const created = await store.create(INDEX_KEY, [id]);
|
|
227
|
+
if (created.outcome === 'created') {
|
|
228
|
+
return { ok: true };
|
|
229
|
+
}
|
|
230
|
+
if (created.outcome === 'unreachable') {
|
|
231
|
+
return { ok: false, outcome: 'unreachable', reason: created.reason };
|
|
232
|
+
}
|
|
233
|
+
// 'alreadyExists': another creator won the race to create the
|
|
234
|
+
// index itself between this attempt's read and this create. Loop
|
|
235
|
+
// — the next attempt's read will see it and fall into the replace
|
|
236
|
+
// branch below, the same as if it had been there all along.
|
|
237
|
+
continue;
|
|
238
|
+
}
|
|
239
|
+
const currentIds = read.value;
|
|
240
|
+
if (currentIds.includes(id)) {
|
|
241
|
+
// Already indexed — either a retry of a createCard whose card
|
|
242
|
+
// write landed and whose index update already succeeded, or a
|
|
243
|
+
// second creator that lost the race to add this id but finds it
|
|
244
|
+
// already folded in by whoever won. Either way, nothing left to
|
|
245
|
+
// do, and no replace call needed to say so.
|
|
246
|
+
return { ok: true };
|
|
247
|
+
}
|
|
248
|
+
const replaced = await store.replace(INDEX_KEY, [...currentIds, id], currentIds);
|
|
249
|
+
if (replaced.outcome === 'applied') {
|
|
250
|
+
return { ok: true };
|
|
251
|
+
}
|
|
252
|
+
if (replaced.outcome === 'unreachable') {
|
|
253
|
+
return { ok: false, outcome: 'unreachable', reason: replaced.reason };
|
|
254
|
+
}
|
|
255
|
+
// 'conflict': another creator's id landed between this attempt's
|
|
256
|
+
// read and this replace. Loop, and read again — the next attempt's
|
|
257
|
+
// `currentIds` is whatever they left, not this attempt's stale
|
|
258
|
+
// snapshot, so this id is still added on top of theirs rather than
|
|
259
|
+
// overwriting it.
|
|
260
|
+
//
|
|
261
|
+
// 'absent': this store has no delete verb, so a key this attempt's
|
|
262
|
+
// own read just found should never report absent on replace. Not
|
|
263
|
+
// assumed impossible regardless — a store implementation this board
|
|
264
|
+
// does not control is not this file's to trust blindly — so it is
|
|
265
|
+
// handled the same as 'conflict': loop and re-read.
|
|
266
|
+
}
|
|
267
|
+
return {
|
|
268
|
+
ok: false,
|
|
269
|
+
outcome: 'contentionExhausted',
|
|
270
|
+
reason: `kept losing the race to add ${id} to the index after ${MAX_INDEX_ATTEMPTS} attempts`,
|
|
271
|
+
};
|
|
272
|
+
}
|
|
273
|
+
export function createStoreBoard(store) {
|
|
274
|
+
return {
|
|
275
|
+
async get(id) {
|
|
276
|
+
const read = await store.read(cardKey(id));
|
|
277
|
+
if (read.outcome === 'unreachable') {
|
|
278
|
+
return { outcome: 'unreachable', reason: read.reason };
|
|
279
|
+
}
|
|
280
|
+
if (read.outcome === 'absent') {
|
|
281
|
+
return { outcome: 'absent' };
|
|
282
|
+
}
|
|
283
|
+
return { outcome: 'found', card: read.value };
|
|
284
|
+
},
|
|
285
|
+
async list() {
|
|
286
|
+
const index = await store.read(INDEX_KEY);
|
|
287
|
+
if (index.outcome === 'unreachable') {
|
|
288
|
+
return { outcome: 'unreachable', reason: index.reason };
|
|
289
|
+
}
|
|
290
|
+
if (index.outcome === 'absent') {
|
|
291
|
+
return { outcome: 'empty' };
|
|
292
|
+
}
|
|
293
|
+
const ids = index.value;
|
|
294
|
+
if (ids.length === 0) {
|
|
295
|
+
return { outcome: 'empty' };
|
|
296
|
+
}
|
|
297
|
+
const cards = [];
|
|
298
|
+
const danglingIds = [];
|
|
299
|
+
for (const id of ids) {
|
|
300
|
+
const read = await store.read(cardKey(id));
|
|
301
|
+
if (read.outcome === 'unreachable') {
|
|
302
|
+
return { outcome: 'unreachable', reason: read.reason };
|
|
303
|
+
}
|
|
304
|
+
if (read.outcome === 'absent') {
|
|
305
|
+
// The index names this id; there is no record behind it — the
|
|
306
|
+
// index lied, or was overtaken. See this file's header for
|
|
307
|
+
// why this board's own write path makes it unlikely, and why
|
|
308
|
+
// it is reported rather than assumed away regardless.
|
|
309
|
+
danglingIds.push(id);
|
|
310
|
+
continue;
|
|
311
|
+
}
|
|
312
|
+
cards.push(read.value);
|
|
313
|
+
}
|
|
314
|
+
return { outcome: 'cards', cards, unparseable: [], danglingIds };
|
|
315
|
+
},
|
|
316
|
+
async writeState(id, state, options) {
|
|
317
|
+
for (let attempt = 1; attempt <= MAX_WRITE_STATE_ATTEMPTS; attempt += 1) {
|
|
318
|
+
const read = await store.read(cardKey(id));
|
|
319
|
+
if (read.outcome === 'unreachable') {
|
|
320
|
+
return { outcome: 'unreachable', reason: read.reason };
|
|
321
|
+
}
|
|
322
|
+
if (read.outcome === 'absent') {
|
|
323
|
+
return { outcome: 'refused', reason: `no card with id ${id}` };
|
|
324
|
+
}
|
|
325
|
+
// Recomputed from *this attempt's own read*, every time — never
|
|
326
|
+
// from a value captured before an earlier attempt's conflict. A
|
|
327
|
+
// retry that resent its original computation would be a lost
|
|
328
|
+
// update wearing a success; this line is what keeps it from
|
|
329
|
+
// being one. The expectedRevision check is recomputed here too,
|
|
330
|
+
// against this same fresh read — a CAS loss on a previous
|
|
331
|
+
// attempt re-reads and re-checks the guard against whatever is
|
|
332
|
+
// actually there now, not against a stale snapshot.
|
|
333
|
+
const current = read.value;
|
|
334
|
+
if (options?.expectedRevision !== undefined &&
|
|
335
|
+
current.revision !== options.expectedRevision) {
|
|
336
|
+
return {
|
|
337
|
+
outcome: 'stale',
|
|
338
|
+
id,
|
|
339
|
+
reason: `revision mismatch for card ${id}: expected ${options.expectedRevision}, found ${current.revision ?? 'none'}`,
|
|
340
|
+
...(current.revision !== undefined ? { currentRevision: current.revision } : {}),
|
|
341
|
+
};
|
|
342
|
+
}
|
|
343
|
+
const updated = { ...current, state, revision: nextRevision(current.revision) };
|
|
344
|
+
// The state/properties change and the revision bump happen in
|
|
345
|
+
// this one `replace` call, conditioned on the exact record the
|
|
346
|
+
// guard above just checked — there is no window between
|
|
347
|
+
// "checked the revision" and "changed the card" for another
|
|
348
|
+
// writer to land unnoticed.
|
|
349
|
+
const replaced = await store.replace(cardKey(id), updated, current);
|
|
350
|
+
if (replaced.outcome === 'applied') {
|
|
351
|
+
return { outcome: 'applied' };
|
|
352
|
+
}
|
|
353
|
+
if (replaced.outcome === 'unreachable') {
|
|
354
|
+
return { outcome: 'unreachable', reason: replaced.reason };
|
|
355
|
+
}
|
|
356
|
+
if (replaced.outcome === 'absent') {
|
|
357
|
+
return { outcome: 'refused', reason: `no card with id ${id}` };
|
|
358
|
+
}
|
|
359
|
+
// 'conflict': another writer won this attempt. Loop, and read
|
|
360
|
+
// again — the next attempt's `current` is whatever that writer
|
|
361
|
+
// left behind, not this attempt's now-stale snapshot.
|
|
362
|
+
}
|
|
363
|
+
return {
|
|
364
|
+
outcome: 'contentionExhausted',
|
|
365
|
+
reason: `kept losing the race to write ${id} after ${MAX_WRITE_STATE_ATTEMPTS} attempts`,
|
|
366
|
+
};
|
|
367
|
+
},
|
|
368
|
+
async createCard(card) {
|
|
369
|
+
const seeded = { ...card, revision: '1' };
|
|
370
|
+
const created = await store.create(cardKey(card.id), seeded);
|
|
371
|
+
if (created.outcome === 'unreachable') {
|
|
372
|
+
return { outcome: 'unreachable', reason: created.reason };
|
|
373
|
+
}
|
|
374
|
+
const indexed = await addIdToIndex(store, card.id);
|
|
375
|
+
if (!indexed.ok) {
|
|
376
|
+
return { outcome: indexed.outcome, reason: indexed.reason };
|
|
377
|
+
}
|
|
378
|
+
if (created.outcome === 'created') {
|
|
379
|
+
return { outcome: 'applied' };
|
|
380
|
+
}
|
|
381
|
+
return { outcome: 'refused', reason: `card ${card.id} already exists` };
|
|
382
|
+
},
|
|
383
|
+
async annotate(id, patch, options) {
|
|
384
|
+
for (let attempt = 1; attempt <= MAX_WRITE_STATE_ATTEMPTS; attempt += 1) {
|
|
385
|
+
const read = await store.read(cardKey(id));
|
|
386
|
+
if (read.outcome === 'unreachable') {
|
|
387
|
+
return { outcome: 'unreachable', reason: read.reason };
|
|
388
|
+
}
|
|
389
|
+
if (read.outcome === 'absent') {
|
|
390
|
+
return { outcome: 'refused', reason: `no card with id ${id}` };
|
|
391
|
+
}
|
|
392
|
+
const current = read.value;
|
|
393
|
+
if (options?.expectedRevision !== undefined &&
|
|
394
|
+
current.revision !== options.expectedRevision) {
|
|
395
|
+
return {
|
|
396
|
+
outcome: 'stale',
|
|
397
|
+
id,
|
|
398
|
+
reason: `revision mismatch for card ${id}: expected ${options.expectedRevision}, found ${current.revision ?? 'none'}`,
|
|
399
|
+
...(current.revision !== undefined ? { currentRevision: current.revision } : {}),
|
|
400
|
+
};
|
|
401
|
+
}
|
|
402
|
+
const updated = {
|
|
403
|
+
...current,
|
|
404
|
+
properties: { ...current.properties, ...patch.properties },
|
|
405
|
+
revision: nextRevision(current.revision),
|
|
406
|
+
};
|
|
407
|
+
const replaced = await store.replace(cardKey(id), updated, current);
|
|
408
|
+
if (replaced.outcome === 'applied') {
|
|
409
|
+
return { outcome: 'applied' };
|
|
410
|
+
}
|
|
411
|
+
if (replaced.outcome === 'unreachable') {
|
|
412
|
+
return { outcome: 'unreachable', reason: replaced.reason };
|
|
413
|
+
}
|
|
414
|
+
if (replaced.outcome === 'absent') {
|
|
415
|
+
return { outcome: 'refused', reason: `no card with id ${id}` };
|
|
416
|
+
}
|
|
417
|
+
// 'conflict': another writer won this attempt. Loop, and re-read
|
|
418
|
+
// — same discipline as writeState above.
|
|
419
|
+
}
|
|
420
|
+
return {
|
|
421
|
+
outcome: 'contentionExhausted',
|
|
422
|
+
reason: `kept losing the race to annotate ${id} after ${MAX_WRITE_STATE_ATTEMPTS} attempts`,
|
|
423
|
+
};
|
|
424
|
+
},
|
|
425
|
+
};
|
|
426
|
+
}
|
package/dist/store.d.ts
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `create` is the other conditional write, alongside `replace` — the one
|
|
3
|
+
* idempotency is usually built on. `created` and `alreadyExists` are
|
|
4
|
+
* kept apart because they answer different questions a caller asks
|
|
5
|
+
* afterwards: "did I just make this?" and "was it already there?" are
|
|
6
|
+
* not the same fact, even though both leave the store in the same state
|
|
7
|
+
* (the key holds *some* value either way). Collapsing them into one "ok"
|
|
8
|
+
* outcome would make a caller unable to tell "I created the record"
|
|
9
|
+
* from "someone else already had, possibly me on a retry" — exactly the
|
|
10
|
+
* distinction idempotent retry logic is built to use: a caller that
|
|
11
|
+
* retried a `create` after a timeout, not knowing whether the first
|
|
12
|
+
* attempt actually landed, needs `alreadyExists` to mean "yes, safely,
|
|
13
|
+
* this exists now", not a second `created` implying a second record.
|
|
14
|
+
*
|
|
15
|
+
* `create` never overwrites. A key that already holds a value keeps
|
|
16
|
+
* that value; the `value` passed to a `create` that reports
|
|
17
|
+
* `alreadyExists` is discarded, not applied. That is the whole point of
|
|
18
|
+
* having a `create` distinct from `replace`.
|
|
19
|
+
*/
|
|
20
|
+
export type CreateResult = {
|
|
21
|
+
readonly outcome: 'created';
|
|
22
|
+
} | {
|
|
23
|
+
readonly outcome: 'alreadyExists';
|
|
24
|
+
} | {
|
|
25
|
+
readonly outcome: 'unreachable';
|
|
26
|
+
readonly reason: string;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* `absent` and `unreachable` are kept apart for the same reason this
|
|
30
|
+
* boundary keeps them apart everywhere else it reads something (see
|
|
31
|
+
* `board.ts`): "nothing under this key" and "the store was never asked"
|
|
32
|
+
* are different facts, and a caller told only "not found" for both would
|
|
33
|
+
* treat a store outage as if the key had never existed.
|
|
34
|
+
*/
|
|
35
|
+
export type ReadResult<V> = {
|
|
36
|
+
readonly outcome: 'found';
|
|
37
|
+
readonly value: V;
|
|
38
|
+
} | {
|
|
39
|
+
readonly outcome: 'absent';
|
|
40
|
+
} | {
|
|
41
|
+
readonly outcome: 'unreachable';
|
|
42
|
+
readonly reason: string;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* A compare-and-set: replace the value at `key` with `value`, but only
|
|
46
|
+
* if what is currently stored there equals `expected`. This is where
|
|
47
|
+
* concurrent writers meet. Two callers can both `read` the same value,
|
|
48
|
+
* both compute a new one from it, and both call `replace` — at most one
|
|
49
|
+
* of those calls can succeed, because once the first one lands, the
|
|
50
|
+
* second's `expected` no longer matches what is stored. `conflict` is
|
|
51
|
+
* that fact reported back plainly: not an error, not evidence the store
|
|
52
|
+
* is broken, but the store doing exactly its job — refusing a write made
|
|
53
|
+
* against data that is no longer current. A caller that gets `conflict`
|
|
54
|
+
* has one correct response: read again, recompute against the value
|
|
55
|
+
* that actually won, and try again (see `store-board.ts`'s retry loop,
|
|
56
|
+
* the reason this file exists).
|
|
57
|
+
*
|
|
58
|
+
* `absent` is kept apart from `conflict` for the same reason `get`'s
|
|
59
|
+
* `absent` is kept apart from `unreachable` elsewhere in this boundary:
|
|
60
|
+
* "there is nothing here to replace" and "there is something here, but
|
|
61
|
+
* not what you expected" are different facts, and a caller that sees
|
|
62
|
+
* only one undifferentiated failure cannot tell "this key was never
|
|
63
|
+
* created" from "someone else is writing it right now".
|
|
64
|
+
*
|
|
65
|
+
* Equality for `expected` is checked by value, not by an opaque token
|
|
66
|
+
* this store hands back on `read` — deliberately, to keep this port to
|
|
67
|
+
* exactly three verbs with no fourth concept (a version, an ETag)
|
|
68
|
+
* threaded through every call. That is adequate for the plain,
|
|
69
|
+
* JSON-shaped values this repository ever stores here, and is a real
|
|
70
|
+
* cost for a store asked to hold something equality-by-value cannot
|
|
71
|
+
* describe honestly — a value containing a function, a class instance
|
|
72
|
+
* with private state, or anything else where "equal" is not obviously
|
|
73
|
+
* "same bytes". This store is not meant to hold those, and nothing here
|
|
74
|
+
* pretends otherwise.
|
|
75
|
+
*/
|
|
76
|
+
export type ReplaceResult = {
|
|
77
|
+
readonly outcome: 'applied';
|
|
78
|
+
} | {
|
|
79
|
+
readonly outcome: 'conflict';
|
|
80
|
+
} | {
|
|
81
|
+
readonly outcome: 'absent';
|
|
82
|
+
} | {
|
|
83
|
+
readonly outcome: 'unreachable';
|
|
84
|
+
readonly reason: string;
|
|
85
|
+
};
|
|
86
|
+
/**
|
|
87
|
+
* Three verbs. No `list`, no `scan`, no `query` — a key has to already
|
|
88
|
+
* be known to be read, replaced, or found absent. That is deliberate,
|
|
89
|
+
* not an oversight: this is the shape of object storage with
|
|
90
|
+
* conditional writes, and a store that grew an enumeration verb would
|
|
91
|
+
* be a store that had stopped being honestly implementable by that
|
|
92
|
+
* backend. Anything built over this store that finds it needs to
|
|
93
|
+
* enumerate keys has found a real limit of this store, not license to
|
|
94
|
+
* widen it — the right response is a data structure, not a fourth verb.
|
|
95
|
+
* `store-board.ts` is that response: a known key holds the list of ids a
|
|
96
|
+
* board over this store has created, maintained by the same `create`
|
|
97
|
+
* and `replace` every other write here uses, and `list()` reads it like
|
|
98
|
+
* any other value. The set of keys becomes an object like any other,
|
|
99
|
+
* rather than a capability this port has to grow to answer for.
|
|
100
|
+
*/
|
|
101
|
+
export interface Store<V> {
|
|
102
|
+
create(key: string, value: V): Promise<CreateResult>;
|
|
103
|
+
read(key: string): Promise<ReadResult<V>>;
|
|
104
|
+
replace(key: string, value: V, expected: V): Promise<ReplaceResult>;
|
|
105
|
+
}
|
package/dist/store.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// The store this repository's first surviving board is built over: three
|
|
2
|
+
// verbs, opaque keys, opaque values, no list, no scan, no query. That
|
|
3
|
+
// maps onto object storage with conditional writes — a key is an object
|
|
4
|
+
// name, a value is its bytes, `replace`'s `expected` is the conditional
|
|
5
|
+
// write guard a real backend expresses as an ETag or a generation number
|
|
6
|
+
// — rather than onto a database. A port that quietly grew a fourth verb
|
|
7
|
+
// to make some later caller's life easier would be a port that had
|
|
8
|
+
// stopped being implementable by the thing it was designed for. Nothing
|
|
9
|
+
// here does that — even the felt constraint of no enumeration was
|
|
10
|
+
// resolved by keeping the set of keys as an ordinary value under a
|
|
11
|
+
// well-known key (see `store-board.ts`'s header for how and why), not by
|
|
12
|
+
// adding a verb.
|
|
13
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,47 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@verevoir/aigency-work",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"license": "Apache-2.0",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"README.md",
|
|
17
|
+
"LICENSE",
|
|
18
|
+
"CHANGELOG.md"
|
|
19
|
+
],
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=22"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"build": "tsc -p tsconfig.build.json",
|
|
25
|
+
"typecheck": "tsc --noEmit",
|
|
26
|
+
"test": "vitest run",
|
|
27
|
+
"lint": "eslint . && prettier --check .",
|
|
28
|
+
"verify": "npm run typecheck && npm run test && npm run lint",
|
|
29
|
+
"format": "prettier --write .",
|
|
30
|
+
"prepublishOnly": "npm run verify && npm run build"
|
|
31
|
+
},
|
|
32
|
+
"publishConfig": {
|
|
33
|
+
"access": "public"
|
|
34
|
+
},
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"yaml": "^2.0.0",
|
|
37
|
+
"zod": "^4.6.7"
|
|
38
|
+
},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"@eslint/js": "^9.0.0",
|
|
41
|
+
"eslint": "^9.0.0",
|
|
42
|
+
"prettier": "^3.0.0",
|
|
43
|
+
"typescript": "^5.5.0",
|
|
44
|
+
"typescript-eslint": "^8.0.0",
|
|
45
|
+
"vitest": "^3.0.0"
|
|
46
|
+
}
|
|
47
|
+
}
|