@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,50 @@
1
+ import type { CardSource, CardSink } from './board.js';
2
+ export interface PayloadBoard extends CardSource, CardSink {
3
+ /**
4
+ * Makes every subsequent `get`, `list` and `writeState` call report
5
+ * `unreachable` with this reason (for `createCard` and `annotate` too), regardless of what is stored —
6
+ * reachability is checked independently of content, never inferred
7
+ * from it. Mirrors `InMemoryBoard.setUnreachable`.
8
+ */
9
+ setUnreachable(reason: string): void;
10
+ /** Undoes `setUnreachable`. */
11
+ setReachable(): void;
12
+ /**
13
+ * Puts a raw payload directly into the board, for setting up a
14
+ * scenario — stored exactly as given, unparsed and unvalidated. A real
15
+ * tracker does not validate on your behalf either; validation is what
16
+ * `get` and `list` apply on the way out, never something this board
17
+ * does on the way in. That is what makes it possible to seed a payload
18
+ * that will not parse: this method has to accept it, or there would be
19
+ * no way to exercise the outcome it exists to test.
20
+ *
21
+ * `id` is the key the board answers to — independent of whatever `id`
22
+ * field, valid or not, the payload itself carries. See
23
+ * `UnparseableRecord` for why that independence matters.
24
+ */
25
+ putPayload(id: string, payload: unknown): void;
26
+ /**
27
+ * Returns exactly what is stored under `id` right now — no parsing,
28
+ * no stripping, no rendering. The counterpart to `putPayload`: that
29
+ * seeds the raw state a scenario starts from, this reads the raw
30
+ * state a scenario ends in. Needed because `get`/`list` always strip
31
+ * `revision` (see `stripRevision` below) — a regression that let a
32
+ * write re-render one into storage would be invisible through them
33
+ * regardless, so a test proving "never re-emitted" has to look here,
34
+ * not through `get`.
35
+ */
36
+ peekPayload(id: string): unknown;
37
+ }
38
+ /**
39
+ * The reason given for any write that supplies `expectedRevision` —
40
+ * exported so a test can assert against the exact string this board
41
+ * produces, rather than a loose substring match standing in for "names
42
+ * it". The outcome itself is `unsupported`, not `refused`: this board
43
+ * was reached and understood the request, it simply has no
44
+ * compare-and-set primitive underneath it to honour the guard with.
45
+ */
46
+ export declare const EXPECTED_REVISION_UNSUPPORTED_REASON = "expectedRevision is not supported by PayloadBoard: it has no compare-and-set primitive over its backing payload store";
47
+ export declare function createPayloadBoard(initial?: readonly {
48
+ readonly id: string;
49
+ readonly payload: unknown;
50
+ }[]): PayloadBoard;
@@ -0,0 +1,225 @@
1
+ // A `CardSource` and `CardSink` backed by raw payloads rather than parsed
2
+ // `Card`s. `in-memory-board.ts` is a fake of a tracker that has already
3
+ // been parsed — every card it holds arrived through `put`, already a
4
+ // valid `Card`. A real tracker never hands over anything already parsed;
5
+ // parsing is the step this boundary applies on the way in, not a
6
+ // precondition the tracker meets for it. `PayloadBoard` is what stands in
7
+ // for that: a store of whatever a tracker actually returns, with parsing
8
+ // happening on every read and rendering happening on every write, exactly
9
+ // where they happen against a real one.
10
+ //
11
+ // Why this board does not support `expectedRevision`
12
+ // -----------------------------------------------------
13
+ // `StoreBoard` can honour an optimistic-concurrency guard (see `board.ts`'s
14
+ // `WriteOptions`) honestly because it sits over `Store`'s own
15
+ // compare-and-set: a revision bumped in the same `replace` call that
16
+ // applies a change is a real guard, backed by a real atomic primitive.
17
+ // `PayloadBoard` has no such primitive underneath it — `payloads` is a
18
+ // plain `Map`, written to directly, with nothing resembling a
19
+ // conditional write at all. A side counter that merely increments on
20
+ // every accepted write, with nothing beneath it that could ever actually
21
+ // lose a race, is not a guard; it is a guard-shaped placeholder that
22
+ // would always either match or not match exactly once, telling a caller
23
+ // nothing true about contention. Rather than pretend, this board omits
24
+ // `Card.revision` entirely — it is simply never set — and answers ANY
25
+ // write that supplies `expectedRevision` with the `unsupported`
26
+ // outcome (see `board.ts`'s `WriteResult` doc), naming explicitly that
27
+ // the guard is not supported here, never the unrelated `refused`. A
28
+ // caller that actually needs optimistic concurrency over raw payloads
29
+ // needs a board backed by something with a real conditional write, which
30
+ // is exactly the gap `StoreBoard` exists to fill.
31
+ //
32
+ // "Never set" means never set, even on the way IN. A payload that
33
+ // already carries a *string* `revision` key — written by some other
34
+ // adapter, or left over from a test fixture — has it stripped on every
35
+ // read and never re-emitted on any write; see `stripRevision` below,
36
+ // which only strips the known `Card.revision` field a string revision
37
+ // becomes. A *non-string* `revision` is a different case entirely:
38
+ // `payload.ts` treats it as mistyped and carries it through
39
+ // `unknownFields`, exactly like any other key this boundary does not
40
+ // recognise — `stripRevision` has nothing to strip there, so it rides
41
+ // along and is re-emitted on every write the same as every other
42
+ // unrecognised key, never faked as a real guard either way.
43
+ // `payload.ts`'s `parseCardPayload`/`renderCardPayload` round-trip
44
+ // `revision` generically, because they are shared with boards that DO
45
+ // have a real compare-and-set primitive underneath them — this board is
46
+ // not one of them, and must not let that generic round-tripping leak a
47
+ // fake, never-moving revision through regardless of what a stored
48
+ // payload happens to contain.
49
+ import { parseCardPayload, renderCardPayload } from './payload.js';
50
+ function formatProblems(problems) {
51
+ return problems.map((problem) => `${problem.field}: ${problem.message}`).join('; ');
52
+ }
53
+ /**
54
+ * Strips any `revision` a card carries before this board hands it to a
55
+ * caller, or stores it — see this file's header. Without this,
56
+ * `payload.ts`'s generic round-tripping of `revision` would let one
57
+ * leak through here even though this board has no compare-and-set
58
+ * primitive to make it genuine.
59
+ */
60
+ function stripRevision(card) {
61
+ if (card.revision === undefined) {
62
+ return card;
63
+ }
64
+ return {
65
+ id: card.id,
66
+ state: card.state,
67
+ reference: card.reference,
68
+ source: card.source,
69
+ unknownFields: card.unknownFields,
70
+ ...(card.properties !== undefined ? { properties: card.properties } : {}),
71
+ };
72
+ }
73
+ /**
74
+ * The reason given for any write that supplies `expectedRevision` —
75
+ * exported so a test can assert against the exact string this board
76
+ * produces, rather than a loose substring match standing in for "names
77
+ * it". The outcome itself is `unsupported`, not `refused`: this board
78
+ * was reached and understood the request, it simply has no
79
+ * compare-and-set primitive underneath it to honour the guard with.
80
+ */
81
+ export const EXPECTED_REVISION_UNSUPPORTED_REASON = 'expectedRevision is not supported by PayloadBoard: it has no compare-and-set primitive over its backing payload store';
82
+ export function createPayloadBoard(initial = []) {
83
+ const payloads = new Map();
84
+ for (const { id, payload } of initial) {
85
+ payloads.set(id, payload);
86
+ }
87
+ let unreachableReason;
88
+ return {
89
+ async get(id) {
90
+ if (unreachableReason !== undefined) {
91
+ return { outcome: 'unreachable', reason: unreachableReason };
92
+ }
93
+ const payload = payloads.get(id);
94
+ if (payload === undefined) {
95
+ return { outcome: 'absent' };
96
+ }
97
+ const parsed = parseCardPayload(payload);
98
+ if (parsed.ok) {
99
+ return { outcome: 'found', card: stripRevision(parsed.card) };
100
+ }
101
+ return { outcome: 'unparseable', id, problems: parsed.problems };
102
+ },
103
+ async list() {
104
+ if (unreachableReason !== undefined) {
105
+ return { outcome: 'unreachable', reason: unreachableReason };
106
+ }
107
+ if (payloads.size === 0) {
108
+ return { outcome: 'empty' };
109
+ }
110
+ const cards = [];
111
+ const unparseable = [];
112
+ for (const [id, payload] of payloads) {
113
+ const parsed = parseCardPayload(payload);
114
+ if (parsed.ok) {
115
+ cards.push(stripRevision(parsed.card));
116
+ }
117
+ else {
118
+ unparseable.push({ id, problems: parsed.problems });
119
+ }
120
+ }
121
+ // No index here either — this board enumerates its `payloads` map
122
+ // directly, so there is nothing that could name an id the map
123
+ // itself does not also hold.
124
+ return { outcome: 'cards', cards, unparseable, danglingIds: [] };
125
+ },
126
+ async writeState(id, state, options) {
127
+ if (unreachableReason !== undefined) {
128
+ return { outcome: 'unreachable', reason: unreachableReason };
129
+ }
130
+ const payload = payloads.get(id);
131
+ if (payload === undefined) {
132
+ return { outcome: 'refused', reason: `no card with id ${id}` };
133
+ }
134
+ if (options?.expectedRevision !== undefined) {
135
+ return { outcome: 'unsupported', id, reason: EXPECTED_REVISION_UNSUPPORTED_REASON };
136
+ }
137
+ const parsed = parseCardPayload(payload);
138
+ if (!parsed.ok) {
139
+ // The sink does not need to understand a payload to change one
140
+ // field of it — a blind `{ ...payload, state }` would work
141
+ // whether or not `payload` parses. It is refused anyway. Writing
142
+ // blind to a record nobody can read does not fix the record;
143
+ // it produces a *second* problem — a state that silently
144
+ // changed underneath a payload still nobody can read — on top
145
+ // of the first, and does so by a path that bypasses every check
146
+ // this boundary applies everywhere else it touches a payload.
147
+ // `refused` is the right outcome, not `unreachable`: the board
148
+ // was reached, and it read the record — it is declining an
149
+ // action it knows would be unsafe, which is exactly what
150
+ // `refused` means elsewhere in this boundary (see `board.ts`).
151
+ return {
152
+ outcome: 'refused',
153
+ reason: `stored payload for ${id} does not parse as a card, so its state cannot be safely written: ${formatProblems(parsed.problems)}`,
154
+ };
155
+ }
156
+ const updated = { ...stripRevision(parsed.card), state };
157
+ payloads.set(id, renderCardPayload(updated));
158
+ return { outcome: 'applied' };
159
+ },
160
+ async createCard(card) {
161
+ if (unreachableReason !== undefined) {
162
+ return { outcome: 'unreachable', reason: unreachableReason };
163
+ }
164
+ // A broken record still occupies its id, so occupancy is checked on
165
+ // the raw payload, not on whether it parses.
166
+ if (payloads.get(card.id) !== undefined) {
167
+ return { outcome: 'refused', reason: `card ${card.id} already exists` };
168
+ }
169
+ payloads.set(card.id, renderCardPayload(stripRevision(card)));
170
+ return { outcome: 'applied' };
171
+ },
172
+ async annotate(id, patch, options) {
173
+ if (unreachableReason !== undefined) {
174
+ return { outcome: 'unreachable', reason: unreachableReason };
175
+ }
176
+ const payload = payloads.get(id);
177
+ if (payload === undefined) {
178
+ return { outcome: 'refused', reason: `no card with id ${id}` };
179
+ }
180
+ if (options?.expectedRevision !== undefined) {
181
+ return { outcome: 'unsupported', id, reason: EXPECTED_REVISION_UNSUPPORTED_REASON };
182
+ }
183
+ const parsed = parseCardPayload(payload);
184
+ if (!parsed.ok) {
185
+ return {
186
+ outcome: 'refused',
187
+ reason: `stored payload for ${id} does not parse as a card, so its properties cannot be safely annotated: ${formatProblems(parsed.problems)}`,
188
+ };
189
+ }
190
+ // A `properties` value that is not a flat string record never
191
+ // becomes `Card.properties` — `parseCardPayload` keeps it whole,
192
+ // unchanged, in `unknownFields.properties` instead (see
193
+ // `payload.ts`). Rendering a brand-new known `properties` field
194
+ // over that card would apply AFTER `unknownFields` is spread (see
195
+ // `renderCardPayload`), silently overwriting the tracker's own
196
+ // shape with annotate's patch — the one write this board can make
197
+ // that a caller could never undo by reading it back. Refused
198
+ // instead, exactly as an unparseable payload already is above.
199
+ if (parsed.card.unknownFields.properties !== undefined) {
200
+ return {
201
+ outcome: 'refused',
202
+ reason: `card ${id}'s properties are a tracker-shaped object, not a flat string bag; annotate would overwrite them`,
203
+ };
204
+ }
205
+ const updated = {
206
+ ...stripRevision(parsed.card),
207
+ properties: { ...parsed.card.properties, ...patch.properties },
208
+ };
209
+ payloads.set(id, renderCardPayload(updated));
210
+ return { outcome: 'applied' };
211
+ },
212
+ setUnreachable(reason) {
213
+ unreachableReason = reason;
214
+ },
215
+ setReachable() {
216
+ unreachableReason = undefined;
217
+ },
218
+ putPayload(id, payload) {
219
+ payloads.set(id, payload);
220
+ },
221
+ peekPayload(id) {
222
+ return payloads.get(id);
223
+ },
224
+ };
225
+ }
@@ -0,0 +1,55 @@
1
+ import type { Card, ParseResult } from './card.js';
2
+ /**
3
+ * Turns a raw tracker payload into a `Card`, or refuses it.
4
+ *
5
+ * Recognition is by key name only, never by shape: a key named `id`,
6
+ * `state`, `reference`, `source`, `revision` or `properties` is treated
7
+ * as that known field — except `revision` and `properties`, which have a
8
+ * documented exception below: when present but not the shape they are
9
+ * supposed to be, they are not malformed instances of the known field at
10
+ * all, so they are bucketed into `unknownFields` instead of refusing the
11
+ * whole payload for a problem confined to one optional key. `id`,
12
+ * `state`, `reference` and `source` have no such exception — a malformed
13
+ * one, an `id` that is a number, say, is refused, never silently
14
+ * bucketed into `unknownFields`. Silently demoting a malformed known
15
+ * field into the bag would make a broken card look, from the bag's
16
+ * contents alone, like an ordinary card carrying one harmless extra
17
+ * property — a worse outcome than a refusal, and the same reasoning
18
+ * `parseCard` already applies by reporting every problem rather than
19
+ * stopping at the first. The refusal for one of those four fields is
20
+ * produced by `parseCard` itself, below, under that field's own name —
21
+ * this function does not duplicate that check, it only makes sure the
22
+ * field is never bucketed away from it.
23
+ *
24
+ * Every other key — anything not named above — goes into
25
+ * `unknownFields`, whole and unchanged. Not inspected, not normalised,
26
+ * not coerced. That carrying, unwitnessed until now, is the property
27
+ * under test: a field nobody wrote code for must survive a round trip
28
+ * through `parseCardPayload` and `renderCardPayload`.
29
+ */
30
+ export declare function parseCardPayload(payload: unknown): ParseResult;
31
+ /**
32
+ * Turns a `Card` back into a payload to hand to a tracker.
33
+ *
34
+ * `unknownFields` is spread first, and the known fields are applied
35
+ * over it — not the other way round. That order is the answer to a
36
+ * question this file has to settle: if a caller has put something into
37
+ * `unknownFields` under a key that collides with a known field's name
38
+ * (nothing stops them; the bag's type is `Record<string, unknown>`), which
39
+ * value goes out on the wire? The validated, typed field wins. An
40
+ * unvalidated stray value sitting in the bag silently overriding, say,
41
+ * `id` on the outbound payload would let a caller smuggle an unchecked
42
+ * value into a slot this boundary actually validates, through the one
43
+ * field that is explicitly not supposed to be able to affect it.
44
+ *
45
+ * `revision` and `properties` are included only when the card actually
46
+ * carries them — a card with neither renders with exactly the four
47
+ * required keys on top of `unknownFields`, the same shape this function
48
+ * always produced before either field existed.
49
+ *
50
+ * A card that was never parsed — built by hand, with an empty bag —
51
+ * renders with no extra keys at all: spreading an empty object
52
+ * contributes nothing, so the payload is exactly
53
+ * `{id, state, reference, source}`, four keys, nothing more.
54
+ */
55
+ export declare function renderCardPayload(card: Card): Record<string, unknown>;
@@ -0,0 +1,151 @@
1
+ // The adapter shape that makes `unknownFields` real.
2
+ //
3
+ // `components.md`'s one design statement for this boundary is "unknown
4
+ // fields carried through rather than dropped" — `Card.unknownFields`
5
+ // exists because of it, but nothing in `card.ts` puts anything into that
6
+ // bag or takes anything out of it: `parseCard` validates a payload that
7
+ // already has its fields separated into the known slots plus a bag
8
+ // someone else built. This file is the someone else: turning a raw
9
+ // payload a tracker actually hands over — a flat object with the known
10
+ // fields sitting alongside everything else at the same level — into a
11
+ // `Card`, and turning a `Card` back into such a payload.
12
+ import { isStringRecord, parseCard } from './card.js';
13
+ /**
14
+ * `id`/`state`/`reference`/`source`/`unknownFields` are required on
15
+ * every `Card`; `revision`/`properties` are optional, carried through
16
+ * the same way when present — seven fields in total, but `unknownFields`
17
+ * is a `Card` field, not a payload key, so it is not one of the six
18
+ * names below. A key by one of these six names is never routed to
19
+ * `unknownFields` merely for being unrecognised — the usual reason a key
20
+ * ends up there. `revision` and `properties` are still the two
21
+ * exceptions documented on `parseCardPayload` below: when either is
22
+ * present but not the shape it is supposed to be, it IS bucketed into
23
+ * `unknownFields`, not because the key is unrecognised but because a
24
+ * malformed instance of one of these two optional fields is treated as
25
+ * simply not being that field, rather than as a reason to refuse the
26
+ * whole payload. Missing that bucketing here for `revision`/`properties`
27
+ * was a real bug, not a cosmetic gap: a board's `annotate` computing an
28
+ * updated `Card` with a new `properties` bag, then handing it to
29
+ * `renderCardPayload`, had that bag silently dropped on the way back
30
+ * onto the wire — the patch applied in memory and then vanished, because
31
+ * nothing in the rendered payload carried it for the next `get` to
32
+ * recover.
33
+ */
34
+ const KNOWN_KEYS = ['id', 'state', 'reference', 'source', 'revision', 'properties'];
35
+ function isPlainObject(value) {
36
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
37
+ }
38
+ /**
39
+ * Turns a raw tracker payload into a `Card`, or refuses it.
40
+ *
41
+ * Recognition is by key name only, never by shape: a key named `id`,
42
+ * `state`, `reference`, `source`, `revision` or `properties` is treated
43
+ * as that known field — except `revision` and `properties`, which have a
44
+ * documented exception below: when present but not the shape they are
45
+ * supposed to be, they are not malformed instances of the known field at
46
+ * all, so they are bucketed into `unknownFields` instead of refusing the
47
+ * whole payload for a problem confined to one optional key. `id`,
48
+ * `state`, `reference` and `source` have no such exception — a malformed
49
+ * one, an `id` that is a number, say, is refused, never silently
50
+ * bucketed into `unknownFields`. Silently demoting a malformed known
51
+ * field into the bag would make a broken card look, from the bag's
52
+ * contents alone, like an ordinary card carrying one harmless extra
53
+ * property — a worse outcome than a refusal, and the same reasoning
54
+ * `parseCard` already applies by reporting every problem rather than
55
+ * stopping at the first. The refusal for one of those four fields is
56
+ * produced by `parseCard` itself, below, under that field's own name —
57
+ * this function does not duplicate that check, it only makes sure the
58
+ * field is never bucketed away from it.
59
+ *
60
+ * Every other key — anything not named above — goes into
61
+ * `unknownFields`, whole and unchanged. Not inspected, not normalised,
62
+ * not coerced. That carrying, unwitnessed until now, is the property
63
+ * under test: a field nobody wrote code for must survive a round trip
64
+ * through `parseCardPayload` and `renderCardPayload`.
65
+ */
66
+ export function parseCardPayload(payload) {
67
+ if (!isPlainObject(payload)) {
68
+ // Let parseCard produce the one correctly-worded refusal for a
69
+ // non-object payload, rather than a second copy of that message here.
70
+ return parseCard(payload);
71
+ }
72
+ // `properties` is only ever treated as this boundary's own known
73
+ // field when its value genuinely is a flat string-to-string bag (see
74
+ // `card.ts`'s `isStringRecord`) — the documented contract. Any other
75
+ // shape — a plain object that happens to be named `properties` but
76
+ // holds something else (Notion's nested `{select: {...}}` page
77
+ // shape, a number), or a value that is not even an object at all
78
+ // (`null`, an array, a string, a number) — is not a malformed
79
+ // instance of this field; it simply is not this field, and is
80
+ // carried through whole in `unknownFields` like any other key this
81
+ // boundary does not recognise — never refused, never silently
82
+ // re-typed into a shape it does not have.
83
+ const rawProperties = payload.properties;
84
+ const propertiesIsMistyped = rawProperties !== undefined && !isStringRecord(rawProperties);
85
+ // A `revision` that is present but not a string is not a malformed
86
+ // instance of the known field either — it simply is not this field,
87
+ // exactly like a tracker-shaped `properties` above. It is carried
88
+ // through whole in `unknownFields` rather than taken to `parseCard`,
89
+ // which would refuse the entire payload for a problem confined to one
90
+ // optional key.
91
+ const rawRevision = payload.revision;
92
+ const revisionIsMistyped = rawRevision !== undefined && typeof rawRevision !== 'string';
93
+ const unknownFields = {};
94
+ for (const [key, value] of Object.entries(payload)) {
95
+ if (key === 'properties' && propertiesIsMistyped) {
96
+ unknownFields[key] = value;
97
+ continue;
98
+ }
99
+ if (key === 'revision' && revisionIsMistyped) {
100
+ unknownFields[key] = value;
101
+ continue;
102
+ }
103
+ if (!KNOWN_KEYS.includes(key)) {
104
+ unknownFields[key] = value;
105
+ }
106
+ }
107
+ return parseCard({
108
+ id: payload.id,
109
+ state: payload.state,
110
+ reference: payload.reference,
111
+ source: payload.source,
112
+ unknownFields,
113
+ ...(rawRevision !== undefined && !revisionIsMistyped ? { revision: rawRevision } : {}),
114
+ ...(rawProperties !== undefined && !propertiesIsMistyped ? { properties: rawProperties } : {}),
115
+ });
116
+ }
117
+ /**
118
+ * Turns a `Card` back into a payload to hand to a tracker.
119
+ *
120
+ * `unknownFields` is spread first, and the known fields are applied
121
+ * over it — not the other way round. That order is the answer to a
122
+ * question this file has to settle: if a caller has put something into
123
+ * `unknownFields` under a key that collides with a known field's name
124
+ * (nothing stops them; the bag's type is `Record<string, unknown>`), which
125
+ * value goes out on the wire? The validated, typed field wins. An
126
+ * unvalidated stray value sitting in the bag silently overriding, say,
127
+ * `id` on the outbound payload would let a caller smuggle an unchecked
128
+ * value into a slot this boundary actually validates, through the one
129
+ * field that is explicitly not supposed to be able to affect it.
130
+ *
131
+ * `revision` and `properties` are included only when the card actually
132
+ * carries them — a card with neither renders with exactly the four
133
+ * required keys on top of `unknownFields`, the same shape this function
134
+ * always produced before either field existed.
135
+ *
136
+ * A card that was never parsed — built by hand, with an empty bag —
137
+ * renders with no extra keys at all: spreading an empty object
138
+ * contributes nothing, so the payload is exactly
139
+ * `{id, state, reference, source}`, four keys, nothing more.
140
+ */
141
+ export function renderCardPayload(card) {
142
+ return {
143
+ ...card.unknownFields,
144
+ id: card.id,
145
+ state: card.state,
146
+ reference: card.reference,
147
+ source: card.source,
148
+ ...(card.revision !== undefined ? { revision: card.revision } : {}),
149
+ ...(card.properties !== undefined ? { properties: card.properties } : {}),
150
+ };
151
+ }
@@ -0,0 +1,78 @@
1
+ import type { Card } from './card.js';
2
+ import type { UnparseableRecord } from './board.js';
3
+ /**
4
+ * The `cards`/`unparseable` split `list()` already returns when its
5
+ * outcome is `'cards'` — accepted directly, rather than the two arrays
6
+ * separately, so there is exactly one way to call this and no way to
7
+ * pass an `unparseable` set alongside a `totalRecords` that does not
8
+ * agree with it. A `ListResult` whose outcome is `'cards'` already has
9
+ * this shape; passing it straight through is the whole call.
10
+ */
11
+ export interface UnparseableListing {
12
+ readonly cards: readonly Card[];
13
+ readonly unparseable: readonly UnparseableRecord[];
14
+ }
15
+ /**
16
+ * Every distinct (field, message) pair found among the unparseable
17
+ * records, and which records produced it. Always the full breakdown —
18
+ * every group, not just the one (if any) that crossed the threshold
19
+ * below — because a caller with a different tolerance than this file's
20
+ * cannot recompute a verdict from a verdict; they can only recompute one
21
+ * from the counts. See `assessUnparseable`'s doc comment for why the
22
+ * threshold this file applies is not the only defensible one.
23
+ */
24
+ export interface SchemaChangeGroup {
25
+ readonly field: string;
26
+ readonly message: string;
27
+ readonly count: number;
28
+ readonly ids: readonly string[];
29
+ }
30
+ /**
31
+ * `noEvidence` is deliberately not the same outcome as `isolated` with an
32
+ * empty `groups` array, even though the two are indistinguishable by
33
+ * their practical consequence — a caller acts on neither. They are kept
34
+ * apart for the same reason `absent` and `unreachable` are kept apart on
35
+ * `GetResult` (`board.ts`): "nothing to assess" and "assessed, and found
36
+ * nothing clustered" are different facts about how much evidence this
37
+ * function actually looked at, and collapsing them would let `isolated`
38
+ * be read as a claim ("I checked, and it's fine") in a case where there
39
+ * was nothing to check at all. An empty unparseable set is the case that
40
+ * would otherwise divide by zero computing a ratio against zero broken
41
+ * records — `noEvidence` is returned before that division is ever
42
+ * attempted, not after it produces `NaN`.
43
+ *
44
+ * `schemaChange`'s four fields — `field`, `message`, `count`,
45
+ * `totalRecords` — are the answer to "is this one problem or many?"
46
+ * that a boolean cannot give: which field, what it said, how many
47
+ * records, out of how many examined. `groups` still rides alongside it,
48
+ * carrying every other cluster found, however small — a board can have
49
+ * one dominant schema change and a handful of unrelated single-record
50
+ * problems at the same time, and both facts are worth having in one
51
+ * answer.
52
+ */
53
+ export type SchemaChangeAssessment = {
54
+ readonly outcome: 'noEvidence';
55
+ } | {
56
+ readonly outcome: 'isolated';
57
+ readonly totalRecords: number;
58
+ readonly groups: readonly SchemaChangeGroup[];
59
+ } | {
60
+ readonly outcome: 'schemaChange';
61
+ readonly totalRecords: number;
62
+ readonly field: string;
63
+ readonly message: string;
64
+ readonly count: number;
65
+ readonly groups: readonly SchemaChangeGroup[];
66
+ };
67
+ /**
68
+ * Groups a listing's unparseable records by (field, message) and asks
69
+ * whether any one group looks like a schema change rather than a
70
+ * coincidence of unrelated data problems.
71
+ *
72
+ * Grouping, not counting: a record with two problems contributes to two
73
+ * groups, because it genuinely has two independent things wrong with it
74
+ * — the same discipline `parseCard` already applies by reporting every
75
+ * problem rather than the first (see `card.ts`), carried through here
76
+ * rather than collapsed by picking one problem per record to group by.
77
+ */
78
+ export declare function assessUnparseable(listing: UnparseableListing): SchemaChangeAssessment;
Binary file
@@ -0,0 +1,33 @@
1
+ import type { Card } from './card.js';
2
+ import type { CardSource, CardSink, WriteResult, WriteOptions, AnnotatePatch } from './board.js';
3
+ import type { Store } from './store.js';
4
+ /**
5
+ * The reserved key under which this board keeps the list of every card
6
+ * id it has created — an ordinary value in the same store, not a
7
+ * capability the store itself has to provide. Exported for tests that
8
+ * need to construct a scenario this board's own operations do not
9
+ * produce (a dangling index entry) by writing to the store directly;
10
+ * not part of `StoreBoard`'s own public surface.
11
+ */
12
+ export declare const INDEX_KEY = "index";
13
+ export interface StoreBoard extends CardSource, CardSink {
14
+ /**
15
+ * Creates a new card, seeded with revision `'1'`, and folds its id
16
+ * into the index `list()` reads. The real write path onto a
17
+ * store-backed board — unlike `InMemoryBoard.put`/
18
+ * `PayloadBoard.putPayload`, which exist purely to seed a fake for a
19
+ * test because those boards are otherwise constructed complete via an
20
+ * `initial` array. A store is not constructed; it already exists,
21
+ * persists, and is connected to. This is how a card actually comes to
22
+ * exist on it, in production, not only in a test.
23
+ */
24
+ createCard(card: Card): Promise<WriteResult>;
25
+ /**
26
+ * Patches a card's `properties` without touching `state`, via a
27
+ * read-check-replace retried under the same bound `writeState` uses —
28
+ * no index involvement, since `properties` carries no identity the
29
+ * index needs to track.
30
+ */
31
+ annotate(id: string, patch: AnnotatePatch, options?: WriteOptions): Promise<WriteResult>;
32
+ }
33
+ export declare function createStoreBoard(store: Store<unknown>): StoreBoard;