* 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>
9.5 KiB
RuntimeStore HTTP contract
This contract exposes the complete RuntimeStore interface over JSON HTTP. All paths below are relative to a deployment-defined base URL. Path segments and query parameter values are percent-encoded UTF-8 strings. Identifiers used as path segments MUST NOT be exactly . or .., because URL parsers normalize those dot segments before routing. Request and response bodies use application/json; successful operations with no return value respond with 204 No Content.
Endpoints
| Method | Path | Purpose | Success |
|---|---|---|---|
POST |
/runtime/sessions |
Create a session from a RuntimeSessionInit. The server stamps runtimeDslVersion; a client-submitted value is ignored. |
201 with the full RuntimeSession |
GET |
/runtime/sessions/{sessionId} |
Get one session. | 200 with the RuntimeSession, or 404 if absent |
PATCH |
/runtime/sessions/{sessionId}/status |
Set status from { "status", "updatedAt", "expectedLastSeq"? }. expectedLastSeq is a non-negative integer or null. |
204 |
DELETE |
/runtime/sessions/{sessionId} |
Delete a session and all of its records. | 204 |
GET |
/runtime/stages/{stageId}/learners/{learnerKey}/sessions |
List a partition's sessions, ordered by the instant represented by createdAt, then by id for deterministic ties. |
200 with RuntimeSession[] |
POST |
/runtime/sessions/{sessionId}/records |
Append a RuntimeRecordInit plus optional top-level expectedLastSeq and sessionTransition; body sessionId must match the path. |
201 with the full RuntimeRecord |
GET |
/runtime/sessions/{sessionId}/records |
List records ordered by seq. Optional ?sceneId={sceneId} returns only records anchored to that scene and excludes unanchored records. |
200 with RuntimeRecord[] |
POST |
/runtime/learners/merge |
Atomically re-key all sessions across all stages from { "fromLearnerKey", "toLearnerKey" }. |
200 with { "moved": number } |
DELETE |
/runtime/stages/{stageId}/learners/{learnerKey} |
Delete one learner's sessions and records on one stage. | 204 |
DELETE |
/runtime/stages/{stageId} |
Cascade-delete every learner's sessions and records on one stage. | 204 |
DELETE |
/runtime |
Delete every runtime session and record. Idempotent; an administrative operation — servers MUST gate it behind an operator-level authorization check, never expose it to learner credentials. | 204 |
GET /runtime/sessions/{sessionId}/records returns an empty array when the session has no records, matching RuntimeStore.listRecords. For an absent session a server MAY answer 404 SESSION_NOT_FOUND instead of 200 [] — authorization-aware servers SHOULD, so absent and unowned sessions are indistinguishable — and the client MUST map that 404 back to an empty array, preserving the store contract. Deleting an absent target succeeds.
Server-assigned sequence
seq is server-assigned. The append request body is a RuntimeRecordInit. If it includes seq, that value is ignored; the store's assigned value is authoritative. The server allocates the next per-session monotonic sequence number atomically with the insert, starting at 0, and the response returns the full RuntimeRecord, including the assigned seq.
Likewise, runtimeDslVersion is server-assigned when a session is created. If the request body includes runtimeDslVersion, that value is ignored; the store's assigned value is authoritative.
Compare guards and session transitions
expectedLastSeq is an optional compare-and-swap guard shared by status updates and record appends. A non-negative integer means the caller observed that sequence at the record tail; null means the caller observed no records. Omission means no precondition. The server compares the value with the actual tail inside the same transaction as the write. A mismatch commits neither the status update nor the append and returns 409 RUNTIME_APPEND_CONFLICT with the expected and actual tails in error.details.
An append may also include a top-level sessionTransition object with { "status", "updatedAt" }. The server validates and commits the completed parent session in the same transaction as the record. A tail conflict or validation failure persists neither change. For example:
{
"id": "record-1",
"sessionId": "session-1",
"createdAt": "2026-01-01T00:00:00.000Z",
"payload": null,
"expectedLastSeq": null,
"sessionTransition": {
"status": "completed",
"updatedAt": "2026-01-01T00:00:01.000Z"
}
}
Payload domain
HTTP implementations carry record payloads through JSON and therefore MUST accept only plain JSON values that survive serialization without changing meaning. They MUST fail loud before sending values such as Map, Set, Date, non-finite numbers, negative zero, nested undefined, bigint, sparse arrays, symbol-keyed properties, non-enumerable properties, arrays with non-index own properties, strings containing U+0000, class instances, and circular references. U+2028 and U+2029 are valid JSON string contents and MUST be accepted. This is intentionally narrower than BrowserRuntimeStore, whose structured-clone persistence can preserve values such as Map, Set, and Date that JSON cannot.
The reference handler streams request bodies into a bounded buffer. maxBodyBytes configures the bound on the runtime, composed-storage, and reference-server factories; it defaults to 32 MiB. A body that crosses the bound is rejected immediately with 413 PAYLOAD_TOO_LARGE.
learnerKey security model
learnerKey appears in paths, query parameters, and request bodies, but the server MUST derive or verify learnerKey from the authenticated session and MUST NOT blindly trust the client-submitted value. learnerKey is an opaque partition key, not proof of identity or authorization; trusting it verbatim creates a lateral-authorization vulnerability that lets one learner read, merge, or delete another learner's runtime data. The same rule applies to both keys in mergeLearner; authorization policy must explicitly permit the authenticated principal to migrate the source partition into the destination partition.
The conformance server in this package is test-only and does not implement an authentication or authorization model; deriving learnerKey from authentication is left to the reference server in #939 Part D.
Errors
Every non-2xx response has this machine-readable JSON shape:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "@openmaic/storage: invalid runtime session ...",
"details": []
}
}
details is optional. message preserves the semantic wording of the backing store error so an HTTP client can reconstitute the fail-loud exceptions callers receive from BrowserRuntimeStore.
| Condition | HTTP status | Error code | Client behavior |
|---|---|---|---|
| Malformed JSON, an invalid envelope or payload, invalid learner keys, a body/path mismatch, or append to a non-active session | 400 |
VALIDATION_FAILED |
Throw HttpRuntimeStoreError (an Error) with the server message |
Request body exceeds maxBodyBytes |
413 |
PAYLOAD_TOO_LARGE |
Throw HttpRuntimeStoreError |
| Session does not exist | 404 |
SESSION_NOT_FOUND |
getSession returns undefined; operations that require the session throw HttpRuntimeStoreError with the browser store's no session semantics |
| Route does not exist | 404 |
ROUTE_NOT_FOUND |
Throw HttpRuntimeStoreError |
| A stored session has a future runtime DSL version | 409 |
FUTURE_VERSION |
Throw HttpRuntimeStoreError with the browser store's fail-loud newer than this client's semantics |
| Session id already exists | 409 |
SESSION_ALREADY_EXISTS |
Throw HttpRuntimeStoreError with the browser store's already exists semantics |
expectedLastSeq does not match the current record tail |
409 |
RUNTIME_APPEND_CONFLICT |
Reconstitute and throw RuntimeAppendConflictError with sessionId, expectedLastSeq, and actualLastSeq from error.details |
| Unexpected server failure | 500 |
INTERNAL_ERROR |
Throw HttpRuntimeStoreError |
The client MUST use the machine-readable code, not status alone, when an operation has special behavior. In particular, only SESSION_NOT_FOUND is translated to undefined by getSession. Sessions returned by reads MUST be forward-migrated through the client's migrateRuntime before they are returned, because the server may lag the client schema version. Corrupt sessions remain fail-loud on direct reads and are omitted from partition listings, matching BrowserRuntimeStore.
Retry and atomicity guarantees
mergeLearner, DELETE /runtime/sessions/{sessionId}, DELETE /runtime/stages/{stageId}/learners/{learnerKey}, and DELETE /runtime/stages/{stageId} MUST be safely retryable. Repeating a completed merge moves 0; repeating a delete succeeds with 204. A merge is atomic across every matching source session and MUST NOT expose a partial move. Delete endpoints cascade atomically to the target sessions' records.
The test-only conformance server may report a future-stamped-row conflict encountered mid-merge as 500 INTERNAL_ERROR; structured classification of that specific case is deferred to the real Part D server implementation.
POST /runtime/sessions and record append are not implicitly retry-safe: clients must not retry them after an ambiguous transport failure unless a deployment adds a separate idempotency-key policy. Session ids and record ids remain caller-owned uniqueness keys, while record seq remains exclusively server-owned.