[CON-902] Correct the Key-Value Store reference against the live product

[0xsergen]

Part of the CON-901 reference audit. Covers CON-902: kv-reference.md.

Every claim in the file was executed against the live account. 12 defects found and fixed. Post-edit re-run: 38 of 38 passing (12 REST, 18 qnLib, 8 CLI).

Method

• REST kv/rest/v1, live HTTP with x-api-key.
• qnLib helpers run inside qn stream test-filter on ethereum-mainnet block 17811625.
• qn kv CLI, against resources this audit created.
• The three limits were probed to the exact boundary, not estimated.

The worst one first

The contains example destructured a field that does not exist.

const { contains } = await response.json();   // undefined

The real response is { code, msg, data: { exists: true|false } }.

contains is undefined, which is falsy. So every membership check reported "not in the list", including for items that were in it, with a 200 and no error. An allowlist built on that example fails open or fails closed depending on which side of the branch the caller put the allow. Either way, silently, forever.

What was wrong

#	Where	Claimed	Actual
1	GET /sets	{ keys }	{ code, msg, data: [{key, value}], cursor }. There is no keys
2	GET /sets/{key}	{ value }	The value is at data.value
3	contains	{ contains }	{ data: { exists } }. See above
4	PATCH /lists/{key}	not documented	Takes addItems/removeItems. add_items returns 200 "List updated successfully" and writes nothing
5	qnLib casing	not documented	The mirror image of REST. qnUpsertList(k, {add_items}) works; {addItems} returns "OK" and writes nothing
6	qnLib write returns	implied success signal	Every write helper returns "OK", including on the no-op in 4 and 5. It is truthy, so an if guard passes on a write that did nothing
7	"Create or overwrite a list"	overwrite	qnUpsertList merges. ['a','b'] then add_items: ['c'] gives ['a','b','c']. An agent resetting a watchlist accumulates instead
8	"ordered lists"	insertion order	Lexicographically sorted, at both layers
9	Limits, all three rows	see below	see below
10	qnLib surface	9 helpers	21 exposed. qnGetList was missing, so the file documented no way to read a list from inside a filter

The limits table was wrong in all three rows

Row	Claimed	Actual, boundary-probed
Max key length	256 bytes	255 characters. 255 gives 201, 256 gives 400 key exceeds maximum length of 255 characters
Max value size	64 KB	800,000 characters. 800000 gives 201, 800001 gives 400. 512 KiB stores fine
Max list size	10,000 items	Not enforced. The real cap is 1,500 per write, counting addItems + removeItems together. A list grew to 10,503 items with no error

The 64 KB figure was roughly 12 times too small, so an agent chunked data it did not need to chunk. The 10,000 figure named a limit that does not exist, while hiding the per-request one that does, which is the one that actually returns 400.

Note the scope of the 1,500 cap. It is write-only. qnContainsListItems with 1,501 items returns 1,501 booleans.

Two more defects, found on re-verification

Both are the same shape as D1 through D3: a reader destructures a field that is not there and gets undefined instead of an error.

D11. The CLI uses no single JSON envelope. The REST envelope is documented directly above the CLI section, so a reader carries it downward. It does not hold.

Command	Shape
qn kv set list	{ data: [{key, value}], cursor }
qn kv set get	{ value }
qn kv list ls	{ data: { keys: [...] }, cursor }
qn kv list get	{ data: { items: [...] }, cursor }
qn kv list contains	{ exists }

Note keys for sets against items for lists. Note especially that .data.exists on qn kv list contains is undefined, which is falsy. That is exactly the D3 failure, reached through the CLI instead of REST.

D12. Every delete command needs --yes when no terminal is attached. Without it it exits non-zero with operation requires confirmation and deletes nothing. This matters for agents specifically: one scripting its own cleanup leaves the resource in place. Found by hitting it during this audit's own cleanup.

Also recorded: qn kv set get on a missing key exits non-zero with Error: not found. It does not return an empty value.

Checked and found correct, so not changed: qn kv list list is the canonical subcommand with ls as its alias.

Test: lines

6 added, covering 6 of the 7 runnable blocks. They assert the three response envelopes, the three probed limits, and the five CLI shapes above.

The one block without a Test: line is the qnLib example. It runs inside a Streams filter, and it is asserted in streams-reference.md instead, in PR #14.

Left unfixed

• qnGetSet returns null for a missing key instead of throwing. Recorded as fact. Whether that is intended is not for this file to decide.
• Whether a total list-length cap exists above 10,503. Not probed further. Each 1,500-item step is a write, and the documented claim of 10,000 is already disproved.

Resources

All keys were named con901-* and deleted in the same session. A final sweep of GET /sets and GET /lists shows 31 sets, 14 lists, zero con901 leftovers. Nothing this audit did not create was written to.

Worth filing upstream

1. PATCH /lists/{key} accepts unknown body fields and returns 200 "List updated successfully" without writing. Unknown fields should 400.
2. qnLib write helpers return "OK" on a no-op, for the same reason.
3. qn kv list --help calls lists "ordered string collections". They are lexicographically sorted.
4. qnLib takes snake_case option keys while REST takes camelCase for the same operation.

Version bump

None here. The build-web3 patch bump to 1.0.3 lands in the CON-905 PR, which is the last of the three to merge.

Related: CON-906 and CON-905 PRs cover the other four files from the same audit pass.