* ci: whitelist the document-server-backend integration trunk
* feat(storage): DocumentStore HTTP contract + client + reference-server routes (1B PR1) (#975)
Mirrors the runtime line's server-backed delivery for the document store:
a documented /documents HTTP contract (validation/not-found/FUTURE_VERSION
taxonomy; authorization stays a deployment concern via injected hooks with
an any-authenticated default), an HttpDocumentStore that runs the same
validators and migrate-on-read semantics as the browser backend before and
after the wire, and document routes on the shared reference server — one
server, both stores. The backend-agnostic document contract suite now runs
against HTTP → reference server → browser store.
Co-authored-by: Codex <codex@openai.com>
* ci: whitelist the trunk in the storage PG contract workflow too
* feat(storage): PgDocumentStore — Postgres document backend (1B PR2) (#976)
Implements the full DocumentStore contract over document_stages /
document_scenes / document_outlines, reusing the pure adapter split so
every backend shares one aggregate semantics: saveDocument replaces the
aggregate in one transaction under the stage row's FOR UPDATE lock
(vanished scenes deleted, outline row added/removed — omission means
deletion), incremental putStage/putScene/deleteScene take the same
current-version gate as the browser backend, loads read FOR SHARE and
migrate without writing back, listings never touch content, and deletes
cascade by FK. The document contract suite is PG-gated the same way the
runtime one is; local coverage comes from stubbed-queryable unit tests.
Co-authored-by: Codex <codex@openai.com>
* feat(document-store): sealed bootstrap injection seam for the document backend (1B PR3) (#977)
configureDocumentStorage mirrors the runtime seam: module-level bootstrap
injection sealed after first resolution, a factory that receives the app
validators so a server-backed store cannot silently skip them, and
reset-for-tests wiring. A deployment swaps the browser document backend
for HttpDocumentStore without touching app code. Storage README roadmap
updated — the document HTTP/PG backend items are done.
Co-authored-by: Codex <codex@openai.com>
* fix(storage): 1B final-review hardening — error classification, JSON-safety, body limits, parity coverage (#978)
Unversioned legacy incremental writes classify as 400 instead of leaking a
500; document/scene reads assert JSON safety before serialization so a
structured-clone value fails loud (500 NOT_JSON_SAFE naming the path)
instead of silently converting; a shared streaming body reader bounds
request bodies (default 32 MiB, 413 PAYLOAD_TOO_LARGE, option exposed
through every handler factory); the putStage stale/future guards and
corrupt-stamp listing tolerance move into the shared contract suite so all
four backends prove them; both HTTP store errors retain structured details.
Co-authored-by: Codex <codex@openai.com>
* refactor(storage): typed document version/not-found errors replace prose classification (#980)
DocumentVersionError (future | not-current, storedVersion) and
DocumentNotFoundError now carry the classification the server previously
regex-derived from message prose — instanceof matching mirrors the runtime
sibling's RuntimeAppendConflictError pattern, so a wording change can no
longer silently break status mapping. The prose fallback remains, after
the typed checks, solely for third-party DocumentStore implementations.
The HTTP client rematerializes 409s as DocumentVersionError for symmetry,
and http.ts's private validator fields are renamed to match the public
option names all three backends already share.
Co-authored-by: Codex <codex@openai.com>
---------
Co-authored-by: Codex <codex@openai.com>
* feat(runtime): persist quiz attempts in RuntimeStore
* fix(runtime): coalesce quiz draft snapshots
* fix(runtime): recover concurrent quiz attempts
* fix(runtime): handle quiz completion races
* fix(runtime): commit quiz review atomically
* fix(runtime): dedupe concurrent quiz writes
* fix(runtime): drop stale quiz drafts
* fix: harden quiz runtime review recovery
* fix: serialize quiz attempt identity
* feat: read quiz state from runtime store
* fix: persist quiz retries before resetting
* fix: preserve authoritative quiz outcomes
* fix: preserve legacy quiz retries during cutover
* fix: reconcile legacy quiz snapshots safely
* fix: drain rollover quiz write queues
* fix: drain completed quiz retry queues
* fix: reuse concurrent quiz retries
* fix(quiz): preserve drafts across abrupt reloads
* fix(quiz): recover empty retry sessions
* fix(chat): abort stalled runtime state reads
* fix(quiz): expose queued phases to readers
* fix(quiz): retain concurrent writer tails
* fix(quiz): canonicalize retry branches
* fix(quiz): keep retry rollovers monotonic
* fix(quiz): validate skipped retry siblings
* fix(quiz): close read cutover races
* test(classroom): cover legacy quiz summaries
* fix(quiz): reset async consumers on scene changes
* fix(quiz): close scene transition windows
* test(pbl): cover launch freshness guards
* fix(quiz): close cutover concurrency gaps
* fix(quiz): harden retry and context freshness
* fix(quiz): reject malformed legacy answers
* fix(quiz): validate legacy answer values
* test(quiz): cover legacy multi-answer migration
* fix(merge): retire dead ChatRequestTemplate.storeState after quiz read cutover
Main's three call sites built static storeState blocks that runAgentLoopFn
never consumed (it always rebuilds fresh state via getStoreState); the quiz
read cutover replaced that callback with the async two-phase RuntimeStore
read, leaving the template field with zero consumers. Drop it.
* feat(storage): conform HTTP/PG backends and reference server to RuntimeAppendOptions
The quiz write path's expectedLastSeq / sessionTransition / RuntimeAppendConflictError
semantics existed only in the browser backend; server-backed deployments would
silently accept conflicting appends and leave completed sessions active. Forward
the options over the wire, detect conflicts atomically under the PG transaction,
map them to HTTP 409 RUNTIME_APPEND_CONFLICT, and rematerialize the typed error
client-side so quiz retry logic works across every backend.
Co-authored-by: Codex <codex@openai.com>
* fix(chat): Pi single requests build storeState via the async runtime quiz read
Pi bypasses runAgentLoop's per-iteration getStoreState and serializes the
request template straight to /api/chat/pi, which rejects bodies without
storeState. Extract the fresh-snapshot builder (async RuntimeStore quiz read
with the scene-transition guard) and call it on the Pi path too.
* ci: whitelist the runtime-data-cutover integration trunk for PR checks
* feat(runtime): playback cutover — cursor in KV, discussion facts in RuntimeStore (#956)
* feat(runtime): cut playback over to the runtime layer — cursor in KV, facts in RuntimeStore (#869)
The fourth and last runtime family. Consumed-discussion facts become
append-only 'playback' records folded into a set at read (at-least-once
appends, no conflict machinery); the resume cursor is device-scoped
last-write-wins KV per the amended #779/#869 split. sessionStorage keeps
same-tab priority; KV takes over on fresh tabs/reloads. The dead Dexie
playbackState machinery is retired, with a one-time lazy migration of any
legacy row (cursor half + facts half) before deletion, and stage deletion
now clears both the KV cursor and any unmigrated legacy row.
Co-authored-by: Codex <codex@openai.com>
* test(runtime): include playbackState in the stage-delete db mock
---------
Co-authored-by: Codex <codex@openai.com>
* fix(playback): persist discussion facts on every consumption path (#957)
* fix(playback): persist discussion facts on every consumption path (final-review P0+P1s)
- The engine now publishes a progress snapshot the moment a discussion is
consumed (join / skip / unselected-agent auto-skip). onProgress otherwise
fires before the discussion action executes and a discussion is the scene's
last action, so the fact never reached persistence.
- Reads fold records across ALL playback sessions in the learner partition
(mergeLearner deliberately preserves same-kind sessions from both keys).
- Legacy migration appends only not-yet-durable facts, so an interrupted
migration resumes instead of dropping the tail.
- recordConsumedDiscussion reports durability; the component drops failed ids
from its observed set so a later progress tick retries (at-least-once).
* test(e2e): live verification of the playback persistence chain
Seeds a deterministic stage straight into the Dexie DB, starts the lecture
via the canvas overlay, and asserts the full chain: discussion auto-skip
appends a discussionConsumed record to maic-runtime, the device cursor lands
in KV, and both survive a fresh browsing context (empty sessionStorage).
* refactor(playback): consumed-discussion state is volatile by decision — cursor-only persistence (#959)
Product ruling on #869's fourth family: playback learner state is front-end
ephemeral UX, not learner data. A re-shown proactive card auto-skips, joined
discussions' content already lives in chat runtime records, and no replay
export / analytics consumer exists — so durable facts bought nothing over
in-memory + same-tab sessionStorage. Drop lib/playback/runtime.ts and the
RuntimeStore facts wiring; keep the device-scoped KV resume cursor (the half
with real UX value), the engine's consumption-time progress snapshot (cursor
freshness), and the legacy Dexie retirement (cursor half migrates, row
deletes, consumed ids are dropped).
* fix(review): P3 pair from cross-review — scene-id boundary + sessionTransition 400 (#966)
* fix(review): scene-id boundary for quiz context + 4xx for malformed sessionTransition (P3 pair)
Review findings on #955: didActiveSceneRemainUnchanged compared the active
scene by object identity, so a store update reallocating the scene during
the async quiz read dropped the learner's graded answers from that turn's
request — the scene id is the real boundary. The records route now
classifies a malformed sessionTransition as a validation failure instead of
letting the store's throw surface as a 500.
* fix(playback): superseded-engine cursor guard + migration write-window recheck
Second-vendor review of the #959 shrink (requested after the cross-review
noted it had single-vendor coverage) found: an engine orphaned by a scene
switch during async lecture resume could pass the idle-only recheck, be
resurrected, and publish its old scene's progress over the new scene's
debounced cursor — the resume continuation now requires identity with the
installed engine, and onProgress drops snapshots from superseded engines.
The legacy cursor migration also rechecks KV immediately before its write
so a concurrent tab's newer cursor cannot be overwritten and orphaned by
the legacy-row delete.
Co-authored-by: Codex <codex@openai.com>
---------
Co-authored-by: Codex <codex@openai.com>
* fix(review): approval follow-up P3 nits (#967)
* release: v0.3.1
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(review): approval P3 nits — ISO gate on sessionTransition, dead mocks, corrupt-timestamp guard
- The records route's sessionTransition guard now requires an ISO
updatedAt (isIsoTimestamp), matching the sibling PATCH /status route
- Dead vi.mock factories for the deleted playback-storage module dropped
- A corrupt legacy playback timestamp falls back to 'now' instead of
wedging migration into a permanent re-throw that disabled resume
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* ci: run PR checks against the runtime-server-backend integration branch (#939)
* feat(storage): RuntimeStore HTTP contract + HttpRuntimeStore client (#939 Part B) (#940)
* feat(storage): RuntimeStore HTTP contract + HttpRuntimeStore client (#939 Part B)
- documented JSON HTTP contract for every RuntimeStore operation
(server-assigned seq, learnerKey derived from auth — never trusted
from the request, machine-readable error codes, idempotency notes)
- HttpRuntimeStore client with injected fetch + auth headers hook;
session reads (including createSession responses) migrate forward
on the runtime line so an older server cannot leak stale envelopes
- conformance test server bridging the contract onto the browser
backend; full runRuntimeStoreContract green over HTTP plus error
mapping cases
* fix(storage): harden HTTP runtime backend after cross-review (#939 Part B)
Cross-review fixes:
- appendRecord gates payloads through assertJsonValue: fail loud on
values JSON cannot represent (Map, Date, NaN, nested undefined, NUL
strings) instead of silently mangling them in transit; payload
domain documented in the contract
- appendRecord/listRecords responses validate via validateRuntimeRecord
(server-assigned seq is no longer trusted verbatim) and listRecords
sorts by seq like listSessions already sorted defensively
- request headers no longer require an ambient Headers constructor
when fetch is injected
- conformance server classifies errors structurally (existence checks,
DSL validators, version stamps) instead of regex-sniffing messages
that interpolate caller-controlled ids
- router preserves empty path segments so empty-key calls keep browser
no-op semantics instead of shifting onto other routes
- stray runtimeDslVersion/seq in request bodies are ignored (store-
assigned wins), matching the browser reference; docs updated
- loopback integration test exercises the real listening server
- docs state the conformance server is test-only; auth-derived
learnerKey is Part D's reference server
* fix(storage): round-2 cross-review hardening for the HTTP backend (#939 Part B)
- json-value guard rewritten: additionally rejects -0, symbol-keyed and
non-enumerable own properties, and non-index own properties on arrays;
U+2028/U+2029 are accepted again (they round-trip through JSON per
RFC 8259 — rejecting them lost legitimate pasted text)
- conformance server classifies racing duplicate creates as 409 via a
structural post-check, gates payloads and merge learner keys as 400
- segment() rejects '.'/'..' ids the URL layer would fold away
- list responses must be arrays and mergeLearner's moved must be a
finite number, else a typed MALFORMED_RESPONSE error
* fix(storage): round-3 cross-review hardening for the HTTP backend (#939 Part B)
- json-value guard: NUL is rejected in object keys too, and unpaired
UTF-16 surrogates are rejected in string values and keys (jsonb
refuses both; other JSON stacks corrupt lone surrogates to U+FFFD)
- typed storage errors survive non-object 200 responses instead of
degrading into TypeErrors on .id access
- mergeLearner's moved must be a non-negative integer
- conformance server classifies missing/non-object request bodies as
400 VALIDATION_FAILED
- createSession/appendRecord gate the full init envelope, not only the
payload (stray Date/undefined properties, NUL in ids)
* fix(storage): round-4 convergence fixes for the HTTP backend (#939 Part B)
- envelope JSON gate tolerates explicitly-undefined optional anchors
(sceneId: undefined behaves like omission, matching the browser)
- body-carried identifiers reject '.'/'..' so nothing persists that
the URL layer cannot later address; conformance server mirrors it
- mergeLearner keys pass the JSON-domain gate on client and server
- json-value guard v4: rejects enumerable accessors (validation/serialize
TOCTOU), Array subclasses and null-proto arrays, prototype-supplied
array indices; sparse-array test now constructs a genuine hole
* fix(storage): round-5 convergence fixes for the HTTP backend (#939 Part B)
- undefined-stripping is limited to the DSL-declared optional anchors
(sceneId/actionIndex/subAnchor); any other undefined member fails the
JSON gate loud instead of being dropped silently
- json-value guard: array and object prototype checks are realm-agnostic
(chain-shape instead of identity), so ordinary values from another
realm are accepted while subclasses stay rejected; shared
isLosslessJsonString predicate exported for SQL key guards
- conformance server merge route validates target-key addressability
* fix(storage): close the toJSON prototype channel in the JSON guard (#939)
toJSON is the single channel through which a prototype can alter JSON
output — prototype properties never serialize and own accessors are
already rejected — so refusing any value with a callable toJSON closes
prototype influence on serialization entirely, including prototypes
crafted to pass the realm-agnostic chain-shape check.
* fix(storage): probe toJSON via descriptor walk, not property read (#939)
Reading value.toJSON would execute an inherited accessor, letting a
stateful getter hide from validation and reappear at stringify time.
The probe now walks own descriptors up the prototype chain without
invoking any user code. Post-validation mutation of the caller's object
graph is documented as out of scope — it is equally unpreventable for
every other validated property.
* fix(storage): toJSON probe mirrors JSON.stringify semantics exactly (#939)
The own-most descriptor decides: absent is safe, a non-callable data
value is an ordinary shadowing member and is safe, a callable data
value is rejected, and an accessor is rejected because it cannot be
inspected without invoking it. No daylight remains between the guard
and the serializer on this property.
* feat(storage): PgRuntimeStore — Postgres runtime backend (#939 Part C) (#941)
* feat(storage): PgRuntimeStore — Postgres runtime backend over an injected queryable (#939 Part C)
- PgRuntimeStore implements RuntimeStore over a minimal injected
Queryable (node-postgres and PGlite both satisfy it) — the package
keeps zero runtime dependencies beyond @openmaic/dsl
- runtime_sessions / runtime_records schema exported as
RUNTIME_PG_SCHEMA with idempotent ensureSchema()
- appends serialize per session via a session-row lock; MAX(seq)+1
and the insert share one transaction, UNIQUE(session_id, seq) plus
bounded retry backstop non-cooperating writers
- envelope semantics mirror the browser backend: version stamping,
validation gates, migrate-on-read, fail-loud on future-stamped rows
- full runRuntimeStoreContract green on PGlite plus PG-specific cases
(concurrent-append seq atomicity, ensureSchema and mergeLearner
idempotence)
* fix(storage): require pinned transactions + JSON payload gate in PG backend (#939 Part C)
Cross-review fixes:
- withTransaction is now required; the BEGIN/COMMIT fallback is removed
(on a pg Pool it spread BEGIN/body/COMMIT across different connections
— no real transaction, leaked idle-in-transaction clients, broken
mergeLearner atomicity; on a shared pinned client concurrent calls
interleaved transactions)
- single-statement deletes no longer wrap in a transaction hook call
- appendRecord gates payloads through assertJsonValue: fail loud on
values JSON cannot represent (Map, Date, NaN, nested undefined, NUL
strings) instead of silently persisting something different
- append retry also covers 40001/40P01; READ COMMITTED assumption
documented at the retry loop
- ensureSchema documented as create-only; redundant stage index dropped
- deterministic interleaving test proves the 23505 retry path; real
PostgreSQL contract lane added (postgres:16 service workflow, pg
driver suite skipped locally without PG_CONTRACT_URL)
* fix(storage): round-2 cross-review hardening for the PG backend (#939 Part C)
- json-value guard rewritten (shared with the HTTP backend): additionally
rejects -0, symbol-keyed and non-enumerable own properties, and
non-index own properties on arrays; accepts U+2028/U+2029
- storage-pg-contract workflow now triggers for the runtime-server-backend
integration branch and fails loud (STORAGE_PG_CONTRACT_REQUIRED=1)
when PG_CONTRACT_URL is missing instead of silently skipping
- loadSession distinguishes corrupt non-object rows from absent rows so
getSession fails loud instead of reporting the session missing
* fix(storage): round-3 cross-review hardening for the PG backend (#939 Part C)
- json-value guard (shared): NUL rejected in object keys, unpaired
UTF-16 surrogates rejected in values and keys
- createSession/appendRecord gate the full persisted envelope through
assertJsonValue, not only the payload — stray Date/undefined
properties and NUL in ids fail loud instead of silently diverging
from the returned record or leaking raw 22P05
- real-PG lane covers a genuine 23505 conflict from a second
connection and recovery after an aborted transaction
- retry-set asymmetry and mergeLearner's unbounded lock set documented
* fix(storage): round-4 convergence fixes for the PG backend (#939 Part C)
- NUL/lone-surrogate lookup and delete keys resolve to absent/no-op
instead of leaking 22021 driver errors; setSessionStatus reports the
session missing; mergeLearner from-key moves 0
- mergeLearner destination key passes the JSON-domain gate fail-loud
- envelope JSON gate tolerates explicitly-undefined optional anchors,
matching the browser backend
- json-value guard v4 (shared) + tests for accessors, Array subclasses,
prototype-supplied indices
* fix(storage): round-5 convergence fixes for the PG backend (#939 Part C)
- appendRecord pre-checks the session key like every other lookup path,
so a NUL/lone-surrogate sessionId reports 'no session' instead of
leaking a 22021 driver error
- the queryable-key predicate now structurally reuses the shared
isLosslessJsonString export instead of restating the string rule
- undefined-stripping limited to the DSL-declared optional anchors
- json-value guard: realm-agnostic prototype checks (shared)
* fix(storage): close the toJSON prototype channel in the JSON guard (#939)
Shared guard change with the HTTP backend branch; adds the crafted
null-proto-prototype regression test. Both final-gate reviewers
independently converged on this same channel.
* fix(storage): probe toJSON via descriptor walk, not property read (#939)
Reading value.toJSON would execute an inherited accessor, letting a
stateful getter hide from validation and reappear at stringify time.
The probe now walks own descriptors up the prototype chain without
invoking any user code. Post-validation mutation of the caller's object
graph is documented as out of scope — it is equally unpreventable for
every other validated property.
* fix(storage): toJSON probe mirrors JSON.stringify semantics exactly (#939)
The own-most descriptor decides: absent is safe, a non-callable data
value is an ordinary shadowing member and is safe, a callable data
value is rejected, and an accessor is rejected because it cannot be
inspected without invoking it. No daylight remains between the guard
and the serializer on this property.
* fix(storage): conform HTTP/PG backends to the post-#926 RuntimeStore interface (#943)
The chat cutover (#926) added deleteAllRuntime() to the RuntimeStore
contract while the HTTP and Postgres backends were developed in
parallel against the pre-#926 interface. Implements the method on both
backends (single-statement wipe on PG via the FK cascade; DELETE
/runtime on the HTTP contract, documented as an operator-gated
administrative endpoint), restoring a green typecheck and contract
suite on the integration branch.
* feat(runtime): injectable RuntimeStore backend + learner-key provider (#939 Part A) (#944)
* wip(runtime): backend injection seam — pending gate verification
* fix(runtime): cross-review hardening for the storage injection seam
- stage-deletion IndexedDB probe applies only to the default browser
backend; an injected store always receives deleteStageRuntime
- explicit kv argument takes precedence over the configured learner-key
provider, matching the store seam's explicit-beats-global rule
- configured learner-key resolution is latched with in-flight dedup,
mirroring the store singleton; identity changes require app-level
handling
- factory retry semantics documented; seal errors explain the
module-level bootstrap requirement; isRuntimeStorageConfigured()
probe and a test-only reset added
- client-bootstrap-only contract documented (SSR/HMR caveats)
* fix(runtime): snapshot configuration and make the test reset complete
- configureRuntimeStorage copies the option fields so mutating the
caller's object after configuring cannot swap the sealed backend or
identity provider
- resetRuntimeStorageForTests now clears every latched consumer cache
(store singleton, learner-key in-flight promise) via a reset-hook
registry, so a reset-then-reconfigure test actually gets the new
backend
* fix(runtime): reset also clears the default learner-key caches
resetRuntimeStorageForTests left defaultInFlight/defaultKv latched, so
a default-path test could leak its anonymous key or KV store into the
next test despite the documented full-reset promise.
* feat(storage): runtime reference server — auth-derived learnerKey (#939 Part D) (#945)
* wip(storage): reference server — pending deleteAllRuntime route + gates
* feat(storage): runtime reference server — auth-derived learnerKey enforcement (#939 Part D)
- createRuntimeHttpHandler(store, options) wires the documented HTTP
contract onto any injected RuntimeStore over node http
- authenticate is required; every learner-scoped operation verifies the
path/body learnerKey against the authenticated principal (403
FORBIDDEN_LEARNER) — the client-supplied value is never trusted
- mergeLearner requires an explicit authorizeMerge grant and admin
surfaces (stage cascade, DELETE /runtime) require authorizeAdmin;
both default-deny
- runnable reference entry demonstrates a pg Pool withTransaction and
bearer-token authentication, marked as demo-only
- contract suite green through HttpRuntimeStore -> listening reference
handler -> PgRuntimeStore(pglite); security matrix tested (401/403
paths, admin default-deny); threat model documented
* fix(storage): cross-review hardening for the reference server (#939 Part D)
- principal learnerKey is optional: admin/merge-only credentials no
longer fabricate learner identity; learner-scoped routes 403 without
ownership
- full session/record envelopes pass the JSON-domain gate at the
handler, so NUL/lone-surrogate identifiers map to 400 instead of 500
- payload validation follows the injected store's validator map
(options.payloadValidators) instead of imposing DSL defaults
- reference factory accepts authenticate/authorizeMerge/authorizeAdmin/
payloadValidators overrides; docs no longer claim the factory binds
to localhost; demo-impersonation warning hardened
- 500 responses carry a generic message; details go to the server log
- ownership checks precede version checks and unowned sessions read as
404, closing existence/version oracles; cross-learner denial matrix
tested per route
- merge/delete concurrency documented as linearizable-equivalent with
the ownership re-check narrowed to the delete call
* fix(storage): align reference-server semantics with the store contract
- future-stamped sessions read and delete through unchanged; 409
FUTURE_VERSION applies only to guarded writes (status, append, merge)
- check-then-write races reclassify structurally via a post-failure
re-fetch: missing session 404, non-active session 400, never a
message-sniffed or generic 500
* fix(storage): close the reference CLI's pg pool on startup failure
ensureSchema opens connections inside createReferenceRuntimeServer, so
a failed schema init or occupied port left the pool holding database
resources until its idle timeout.
* fix(storage): close the records-route existence oracle
cosarah's review point on #946: the records list answered 200 [] for an
absent session but 404 for another learner's, so the 404 leaked that an
id exists. Absent and foreign sessions now answer identically (404
SESSION_NOT_FOUND) and the HTTP client maps that code back to an empty
list, preserving the store contract's absent-lists-as-empty semantics.
Contract doc records the server MAY/SHOULD and the client MUST.