@verevoir/aigency-work 0.0.0-stage → 0.2.0

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,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
+ }
@@ -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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
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
+ }