@push.rocks/smartjmap 1.0.0 → 2.1.0

package/dist_ts/index.d.ts

@@ -1,2 +1,4 @@
 export * from './classes.jmapclient.js';
+export * from './interfaces.backend.js';
+export * from './classes.memorymailbackend.js';
 export * from './classes.jmapserver.js';

package/dist_ts/index.js

@@ -1,3 +1,5 @@
 export * from './classes.jmapclient.js';
+export * from './interfaces.backend.js';
+export * from './classes.memorymailbackend.js';
 export * from './classes.jmapserver.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMseUJBQXlCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLHlCQUF5QixDQUFDIn0=

package/dist_ts/interfaces.backend.d.ts

@@ -0,0 +1,349 @@
+import type { IJmapEmailAddress, IJmapEmailBodyPart, IJmapEmailBodyValue } from './classes.jmapclient.js';
+/**
+ * The authenticated principal a JmapServer `authenticate` hook resolves from an
+ * incoming Request. The backend maps a principal to a JMAP account via
+ * `resolveAccount`.
+ */
+export type TJmapPrincipal = {
+    /** Stable identifier of the authenticated user, e.g. a username or token subject. */
+    username: string;
+};
+/** Account metadata returned by `IJmapMailBackend.resolveAccount`. */
+export interface IJmapAccountInfo {
+    /** The JMAP accountId used in method calls and URL templates. */
+    accountId: string;
+    /** Display name of the account, shown in the session object. */
+    name: string;
+    /** Defaults to true when omitted. */
+    isPersonal?: boolean;
+    /** Defaults to false when omitted. */
+    isReadOnly?: boolean;
+}
+/** A Mailbox record (RFC 8621 §2) as stored/served by a backend. */
+export interface IJmapMailboxRecord {
+    id: string;
+    name: string;
+    role: string | null;
+    parentId: string | null;
+    sortOrder: number;
+    totalEmails: number;
+    unreadEmails: number;
+    totalThreads: number;
+    unreadThreads: number;
+    /** Defaults to true when omitted. */
+    isSubscribed?: boolean;
+    /** Defaults to an all-permissive rights object when omitted. */
+    myRights?: Record<string, boolean>;
+}
+/**
+ * An Email record (RFC 8621 §4) as stored/served by a backend — the full
+ * superset of properties the server can project from. `bodyValues` must hold
+ * the complete body values; the server applies the Email/get fetch flags and
+ * `maxBodyValueBytes` truncation on top.
+ */
+export interface IJmapEmailRecord {
+    id: string;
+    blobId: string;
+    threadId: string;
+    mailboxIds: Record<string, boolean>;
+    keywords: Record<string, boolean>;
+    size: number;
+    receivedAt: string;
+    sentAt: string | null;
+    messageId?: string[] | null;
+    inReplyTo?: string[] | null;
+    references?: string[] | null;
+    sender?: IJmapEmailAddress[] | null;
+    subject: string | null;
+    from: IJmapEmailAddress[] | null;
+    to: IJmapEmailAddress[] | null;
+    cc: IJmapEmailAddress[] | null;
+    bcc: IJmapEmailAddress[] | null;
+    replyTo: IJmapEmailAddress[] | null;
+    hasAttachment: boolean;
+    preview: string;
+    bodyValues: Record<string, IJmapEmailBodyValue>;
+    textBody: IJmapEmailBodyPart[];
+    htmlBody: IJmapEmailBodyPart[];
+    attachments: IJmapEmailBodyPart[];
+}
+/** A Thread record (RFC 8621 §3): emailIds sorted oldest first. */
+export interface IJmapThreadRecord {
+    id: string;
+    emailIds: string[];
+}
+/** A stored blob: raw bytes plus the content type given at upload/creation. */
+export interface IJmapBlobRecord {
+    data: Uint8Array;
+    type: string;
+    name?: string;
+}
+/** An Identity record (RFC 8621 §6). */
+export interface IJmapIdentityRecord {
+    id: string;
+    name: string;
+    email: string;
+    mayDelete: boolean;
+}
+/** An EmailSubmission record (RFC 8621 §7) as returned by `submitEmail`. */
+export interface IJmapSubmissionRecord {
+    id: string;
+    emailId: string;
+    identityId: string;
+    undoStatus: string;
+    sendAt: string;
+}
+/** SMTP-style envelope handed to the backend on submission (RFC 8621 §7). */
+export interface IJmapEnvelope {
+    mailFrom: {
+        email: string;
+    };
+    rcptTo: Array<{
+        email: string;
+    }>;
+}
+/** Everything the backend needs to actually send a message. */
+export interface IJmapSubmissionInput {
+    emailId: string;
+    identityId: string;
+    /** Envelope from the client, or derived by the server from the email's addresses. */
+    envelope: IJmapEnvelope;
+    /** The raw RFC 5322 payload (the email's blob) — the backend performs the actual sending. */
+    message: Uint8Array;
+}
+/**
+ * Authenticated, admitted upload handed to a streaming backend. The backend
+ * must reserve quota before reading `stream`, consume it through EOF, and
+ * abort its storage operation when `signal` fires.
+ */
+export interface IJmapBlobUploadStream {
+    stream: ReadableStream<Uint8Array>;
+    size: number;
+    type: string;
+    signal: AbortSignal;
+}
+/** Standard result shape for the /get-style backend reads. */
+export interface IJmapGetResult<T> {
+    /** Backend-owned opaque state string for the collection at read time. */
+    state: string;
+    list: T[];
+    notFound: string[];
+}
+/** Result shape for the /changes-style backend reads (RFC 8620 §5.2). */
+export interface IJmapChanges {
+    oldState: string;
+    newState: string;
+    hasMoreChanges: boolean;
+    created: string[];
+    updated: string[];
+    destroyed: string[];
+}
+/** The Email/query filter subset a backend must support (RFC 8621 §4.4.1). */
+export interface IJmapEmailFilter {
+    inMailbox?: string;
+    /** Case-insensitive match in subject, body text, or any address field. */
+    text?: string;
+    subject?: string;
+    from?: string;
+    to?: string;
+    /** receivedAt strictly before this UTC date. */
+    before?: string;
+    /** receivedAt at or after this UTC date. */
+    after?: string;
+    hasKeyword?: string;
+    notKeyword?: string;
+}
+/** A query sort comparator; the server only forwards supported properties. */
+export interface IJmapComparator {
+    property: string;
+    isAscending?: boolean;
+}
+/** Options passed to `queryEmails`; the server has already validated them. */
+export interface IJmapEmailQueryOptions {
+    filter?: IJmapEmailFilter | null;
+    /** Only `receivedAt` comparators are forwarded by the server. */
+    sort?: IJmapComparator[];
+    /** Zero-based offset into the full result list. */
+    position?: number;
+    limit?: number | null;
+    /** When true the result must include `total`. */
+    calculateTotal?: boolean;
+}
+export interface IJmapEmailQueryResult {
+    queryState: string;
+    ids: string[];
+    position: number;
+    /** Present when `calculateTotal` was requested. */
+    total?: number;
+}
+/** An Email creation spec (server-validated Email/set create arguments). */
+export interface IJmapEmailCreate {
+    mailboxIds: Record<string, boolean>;
+    keywords?: Record<string, boolean>;
+    from?: IJmapEmailAddress[] | null;
+    to?: IJmapEmailAddress[] | null;
+    cc?: IJmapEmailAddress[] | null;
+    bcc?: IJmapEmailAddress[] | null;
+    replyTo?: IJmapEmailAddress[] | null;
+    sender?: IJmapEmailAddress[] | null;
+    messageId?: string[] | null;
+    inReplyTo?: string[] | null;
+    references?: string[] | null;
+    subject?: string | null;
+    sentAt?: string | null;
+    receivedAt?: string;
+    bodyValues?: Record<string, {
+        value: string;
+    }>;
+    textBody?: IJmapEmailBodyPart[];
+    htmlBody?: IJmapEmailBodyPart[];
+    /** Attachment body parts referencing previously uploaded blobs via `blobId`. */
+    attachments?: IJmapEmailBodyPart[];
+}
+/**
+ * An Email update, normalized by the server from RFC 8620 §5.3 patches:
+ * full replacements and per-key patches never overlap for the same property
+ * (the server rejects such patches before calling the backend).
+ */
+export interface IJmapEmailUpdate {
+    /** Full replacement of the keywords object. */
+    keywords?: Record<string, boolean>;
+    /** Full replacement of the mailboxIds object. */
+    mailboxIds?: Record<string, boolean>;
+    /** Per-keyword patch: true adds, null removes. */
+    keywordsPatch?: Record<string, true | null>;
+    /** Per-mailbox patch: true adds, null removes. */
+    mailboxIdsPatch?: Record<string, true | null>;
+}
+/** A JMAP SetError (RFC 8620 §5.3). */
+export interface IJmapSetError {
+    type: string;
+    description?: string;
+    properties?: string[];
+}
+/** The batch handed to `setEmails`; entries are already server-validated. */
+export interface IJmapEmailSetRequest {
+    /** Keyed by client creation id. */
+    create?: Record<string, IJmapEmailCreate>;
+    /** Keyed by email id. */
+    update?: Record<string, IJmapEmailUpdate>;
+    destroy?: string[];
+}
+/** The outcome of a `setEmails` batch; `created` carries the full new records. */
+export interface IJmapEmailSetResult {
+    oldState: string;
+    newState: string;
+    created: Record<string, IJmapEmailRecord>;
+    notCreated: Record<string, IJmapSetError>;
+    updated: string[];
+    notUpdated: Record<string, IJmapSetError>;
+    destroyed: string[];
+    notDestroyed: Record<string, IJmapSetError>;
+}
+/**
+ * A change notification the backend emits when data mutates — both for
+ * mutations performed through the JMAP server and for out-of-band mutations
+ * (e.g. new mail arriving via an IMAP bridge). `changed` maps JMAP type names
+ * ('Email', 'Mailbox', 'Thread', ...) to the new opaque state string.
+ */
+export interface IJmapStateChange {
+    accountId: string;
+    changed: Record<string, string>;
+}
+export type TJmapChangeListener = (change: IJmapStateChange) => void;
+/**
+ * Error a backend may throw from set-style operations to control the JMAP
+ * SetError `type` the server reports (e.g. 'notFound', 'invalidProperties').
+ * Any other thrown error is mapped to a generic SetError.
+ */
+export declare class JmapBackendError extends Error {
+    type: string;
+    constructor(type: string, description?: string);
+}
+/**
+ * The storage contract `JmapServer` dispatches into. Implement this against a
+ * real store (SQL, MongoDB, ...) to expose it as a JMAP server; the bundled
+ * `MemoryMailBackend` is the in-memory reference implementation.
+ *
+ * All state strings are backend-owned opaque strings: the server never
+ * interprets them beyond equality comparison and echoing them to clients.
+ */
+export interface IJmapMailBackend {
+    /**
+     * Maps an authenticated principal to its JMAP account, or null when the
+     * principal has no account (the server then responds 403).
+     */
+    resolveAccount(principal: TJmapPrincipal): Promise<IJmapAccountInfo | null>;
+    /**
+     * Returns mailboxes by id (`ids: null` returns all mailboxes of the
+     * account) together with the current Mailbox collection state. Counter
+     * fields (totalEmails, unreadEmails, ...) must be accurate at read time.
+     */
+    getMailboxes(accountId: string, ids: string[] | null): Promise<IJmapGetResult<IJmapMailboxRecord>>;
+    /**
+     * Returns mailbox changes since the given state, or null when the state is
+     * unknown/too old (the server then answers `cannotCalculateChanges`).
+     * When `maxChanges` is given, the result may be partial with
+     * `hasMoreChanges: true` and an intermediate `newState` to resume from.
+     */
+    getMailboxChanges(accountId: string, sinceState: string, maxChanges?: number): Promise<IJmapChanges | null>;
+    /**
+     * Returns emails by id together with the current Email collection state.
+     * `properties` is a projection hint (null/undefined = all): backends may
+     * use it to avoid loading bodies, but returning full records is always
+     * correct — the server applies the final projection itself.
+     */
+    getEmails(accountId: string, ids: string[], properties?: string[] | null): Promise<IJmapGetResult<IJmapEmailRecord>>;
+    /**
+     * Runs an Email query: apply the filter, sort, then slice by
+     * position/limit. `total` must be included when `calculateTotal` is set.
+     */
+    queryEmails(accountId: string, options: IJmapEmailQueryOptions): Promise<IJmapEmailQueryResult>;
+    /**
+     * Returns email changes since the given state, or null when the state is
+     * unknown/too old (the server then answers `cannotCalculateChanges`).
+     */
+    getEmailChanges(accountId: string, sinceState: string, maxChanges?: number): Promise<IJmapChanges | null>;
+    /**
+     * Applies an Email/set batch: creates (assigning ids, blobIds, and thread
+     * ids), updates (keyword/mailbox replacements and patches), and destroys.
+     * Per-item failures go into the not* maps; the whole batch must never
+     * throw for item-level problems. Must bump the Email state exactly when
+     * something changed and report old/new state.
+     */
+    setEmails(accountId: string, request: IJmapEmailSetRequest): Promise<IJmapEmailSetResult>;
+    /**
+     * Returns threads by id (each thread lists its emailIds oldest first)
+     * together with the current Thread collection state.
+     */
+    getThreads(accountId: string, ids: string[]): Promise<IJmapGetResult<IJmapThreadRecord>>;
+    /** Stores an uploaded blob and returns its id and byte size (RFC 8620 §6.1). */
+    uploadBlob(accountId: string, data: Uint8Array, type: string): Promise<{
+        blobId: string;
+        size: number;
+    }>;
+    /**
+     * Optional streaming upload path. When present, JmapServer requires a valid
+     * Content-Length and never buffers the request before invoking this method.
+     */
+    uploadBlobStream?(accountId: string, upload: IJmapBlobUploadStream): Promise<{
+        blobId: string;
+        size: number;
+    }>;
+    /** Returns a blob's bytes and metadata, or null when unknown. */
+    getBlob(accountId: string, blobId: string): Promise<IJmapBlobRecord | null>;
+    /** Returns the sending identities of the account with their collection state. */
+    getIdentities(accountId: string): Promise<IJmapGetResult<IJmapIdentityRecord>>;
+    /**
+     * Accepts an email for sending: the server has already resolved the
+     * envelope and fetched the raw RFC 5322 payload — the backend performs (or
+     * queues) the actual delivery and returns the submission record.
+     */
+    submitEmail(accountId: string, submission: IJmapSubmissionInput): Promise<IJmapSubmissionRecord>;
+    /**
+     * Subscribes to change notifications so the server can emit StateChange
+     * pushes — including for mutations that happen outside a JMAP request.
+     * Returns an unsubscribe function; the server always calls it on teardown.
+     */
+    subscribeToChanges(listener: TJmapChangeListener): () => void;
+}

package/dist_ts/interfaces.backend.js

@@ -0,0 +1,13 @@
+/**
+ * Error a backend may throw from set-style operations to control the JMAP
+ * SetError `type` the server reports (e.g. 'notFound', 'invalidProperties').
+ * Any other thrown error is mapped to a generic SetError.
+ */
+export class JmapBackendError extends Error {
+    constructor(type, description) {
+        super(description ?? type);
+        this.type = type;
+        this.name = 'JmapBackendError';
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5iYWNrZW5kLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvaW50ZXJmYWNlcy5iYWNrZW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQW9SQTs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLGdCQUFpQixTQUFRLEtBQUs7SUFDekMsWUFBbUIsSUFBWSxFQUFFLFdBQW9CO1FBQ25ELEtBQUssQ0FBQyxXQUFXLElBQUksSUFBSSxDQUFDLENBQUM7UUFEVixTQUFJLEdBQUosSUFBSSxDQUFRO1FBRTdCLElBQUksQ0FBQyxJQUFJLEdBQUcsa0JBQWtCLENBQUM7SUFDakMsQ0FBQztDQUNGIn0=

package/npmextra.json

@@ -5,8 +5,8 @@
       "githost": "code.foss.global",
       "gitscope": "push.rocks",
       "gitrepo": "smartjmap",
-      "shortDescription": "JMAP client for mail (RFC 8620/8621)",
-      "description": "A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.",
+      "shortDescription": "JMAP client and server core for mail (RFC 8620/8621)",
+      "description": "A TypeScript JMAP toolkit (RFC 8620/8621): an event-driven mail client for reading, sending, and watching mail, plus an embeddable JMAP server core with pluggable storage.",
       "npmPackagename": "@push.rocks/smartjmap",
       "license": "MIT",
       "projectDomain": "push.rocks",
@@ -21,6 +21,8 @@
         "json",
         "http",
         "client",
+        "server",
+        "deno",
         "typescript",
         "event-driven",
         "push",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@push.rocks/smartjmap",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "private": false,
-  "description": "A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.",
+  "description": "A TypeScript JMAP toolkit (RFC 8620/8621): an event-driven mail client for reading, sending, and watching mail, plus an embeddable JMAP server core with pluggable storage.",
   "exports": {
     ".": "./dist_ts/index.js"
   },
@@ -12,12 +12,11 @@
   "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsrun": "^2.0.3",
-    "@git.zone/tstest": "^3.6.3",
-    "@types/node": "^25.6.0"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsrun": "^2.0.5",
+    "@git.zone/tstest": "^3.6.6",
+    "@types/node": "^26.1.1"
   },
-  "dependencies": {},
   "repository": {
     "type": "git",
     "url": "git+https://code.foss.global/push.rocks/smartjmap.git"
@@ -54,6 +53,8 @@
     "json",
     "http",
     "client",
+    "server",
+    "deno",
     "typescript",
     "event-driven",
     "push",

package/readme.hints.md

@@ -2,33 +2,44 @@
 
 Design notes for @push.rocks/smartjmap.
 
+## Architecture (2.x)
+
+- Three layers: `JmapClient` (consumer), `JmapServer` (protocol core), `IJmapMailBackend` (storage contract, `ts/interfaces.backend.ts`). The server owns everything protocol-shaped (request envelope, limits, back-references, projection, bodyValue fetch flags, patch normalization, envelope derivation, SSE); the backend owns storage, ids, and state strings (opaque to the server, compared only for equality).
+- `MemoryMailBackend` is the reference backend and the default, keeping the no-options `JmapServer` an offline test helper. Accounts are keyed by username (`accountId = account_<username>`) and auto-created on first reference, so `resolveAccount` never fails for the default auth registry.
+- Auth is two-step: `authenticate(request) -> TJmapPrincipal | null` (custom hook replaces the built-in Basic/Bearer registry entirely), then `backend.resolveAccount(principal)` (null -> 403). `addUser`/`addBearerToken` only feed the default registry.
+- Email/set update patches are normalized server-side into `IJmapEmailUpdate` (full `keywords`/`mailboxIds` replacements vs `keywordsPatch`/`mailboxIdsPatch` per-key patches, mutually exclusive per property) so real backends can apply patches natively (e.g. MongoDB `$set`/`$unset`). Emails are otherwise immutable per RFC 8621 §4.6; any other patched property is rejected.
+- `submitEmail` hands the backend the resolved envelope (client-supplied or derived from from/to/cc/bcc) plus the raw RFC 5322 payload from the email's blob; the app performs actual delivery.
+
 ## HTTP layer
 
-- Zero runtime dependencies: global `fetch` (Node.js 18+ floor; developed against @types/node 25). smartrequest would add no value for plain JSON-over-HTTP.
-- SSE is parsed by hand over a fetch body stream (~50 lines in `runEventStream`). The global `EventSource` was rejected deliberately: it is only default-enabled from Node 22.3 and, more importantly, the WHATWG EventSource API cannot send the `Authorization` header JMAP requires.
+- Zero runtime dependencies: global `fetch`/`Request`/`Response`/`ReadableStream` (Node.js 18+ floor; developed against @types/node 25). `fetchHandler(request)` is the primary server API and is runtime-agnostic (Deno/Bun-mountable, covered by tests that use bare Request objects); `start(port)` wraps it in node:http, buffering request bodies (capped at maxSizeUpload + 1 -> 413) and piping response streams to the socket, cancelling the stream reader when the client disconnects.
+- Client SSE is parsed by hand over a fetch body stream (~50 lines in `runEventStream`). The global `EventSource` was rejected deliberately: it is only default-enabled from Node 22.3 and, more importantly, the WHATWG EventSource API cannot send the `Authorization` header JMAP requires.
+- Server SSE is a `ReadableStream` Response; per-stream state (ping interval timer, `types` filter, closeafter flag, last-pushed state per type) is registered in a set and torn down on stream cancel, `closeafter=state` delivery, enqueue failure, `stop()`, and stream-setup failure (a throwing `backend.subscribeToChanges` unwinds the ping timer and registry entry before the request 500s). The backend change-feed subscription is created when the first stream connects and dropped when the last one closes, so an idle server holds no listener.
+- Push dedupe: a mutation may be reported twice (backend change feed fires during the request + the server pushes after mutating requests for backends whose feed only covers out-of-band changes). Streams track the last state pushed per type and skip repeats.
 
-## Watching semantics
+## Watching semantics (client)
 
 - `connect()`: session GET → capability/account validation → mailbox resolution (role match on the lowercased mailbox name, e.g. 'INBOX' → role 'inbox', falling back to case-insensitive name match) → Email state snapshot → 'connected' → initial sweep (Email/query + Email/get, emitted oldest-first) → event stream.
 - The Email state is snapshotted *before* the initial sweep and `fetchDeltas()` runs once right after the SSE stream is established, so mail arriving between connect and stream establishment is not lost; `seenEmailIds` deduplicates the overlap.
 - Event stream errors/end → silent fallback to `Email/changes` polling on `pollIntervalMs`. `cannotCalculateChanges` → full re-query resync.
 - `connect()` emits 'error' instead of throwing (mirrors smartimap). Unlike smartimap, the same instance may call `connect()` again — JMAP is stateless HTTP.
-- `disconnect()` aborts the SSE fetch and clears the poll timer; the connect-failure path also tears both down, so no handles leak either way.
+- `disconnect()` aborts the SSE fetch and clears the poll timer; the connect-failure path also tears both down, so no handles leak either way. The teardown-at-connect-entry, abort-in-catch, last-stream-wins, and guarded done-path pieces in `runEventStream` are all deliberate lifecycle fixes — keep them.
 
-## RFC subset covered (1.0.0)
+## RFC subset covered (2.x)
 
-- RFC 8620: session resource, method calls/responses, `error` method responses, RFC 7807 problem details, `#creationId` back-references (client-side use; server resolves them in EmailSubmission/set), download URL template expansion, event source (SSE StateChange).
-- RFC 8621: Mailbox/get(+query on server), Email/query, Email/get with `fetchAllBodyValues`, Email/changes, Email/set (create/update with keyword patches/destroy), Identity/get, EmailSubmission/set.
+- RFC 8620: session resource, method calls/responses, `error` method responses, RFC 7807 problem details, enforced limits (`limit` request errors, `requestTooLarge` method errors), `using` validation (`unknownCapability`), `#creationId` back-references and full `ResultReference` `{resultOf, name, path}` resolution with `/*` array expansion, request/response `createdIds` maps, upload/download endpoints, event source (§7.3: `types`, `closeafter=state`, `ping` keepalives).
+- RFC 8621: Mailbox/get(+query, +changes), Thread/get, Email/get (projection, bodyValue fetch flags, `maxBodyValueBytes`), Email/query (flat FilterCondition subset + receivedAt sort + position/limit/calculateTotal), Email/changes (incl. maxChanges), Email/set (create/update with §5.3 patches for keywords/mailboxIds/destroy, `ifInState`), Identity/get, EmailSubmission/set (envelope derivation, onSuccessUpdateEmail/onSuccessDestroyEmail with the implicit Email/set response).
 
-## Known gaps
+## Known gaps / phase-1 exclusions
 
-- No upload endpoint / Blob upload (`uploadUrl` is advertised by the test server but not implemented), so `sendEmail` supports text/html bodies but not attachments.
-- No Thread/*, SearchSnippet/*, VacationResponse/*, Mailbox/set, Mailbox/changes, EmailSubmission onSuccessUpdateEmail, or result references (`resultOf`) — the client issues explicit-id calls instead.
-- `Email/get` on the test server ignores the `properties` projection and always returns the full superset; `Email/query` supports only `inMailbox`/`subject`/`text` filters and `receivedAt` sorting.
-- The client requests event-source pushes with `types=*` and reacts to Email state changes only; Mailbox counters are not tracked incrementally.
-- Initial-sweep race: an email created between the Email/query and Email/get of the sweep is picked up by the following delta fetch, not the sweep itself (dedupe prevents double emission).
+- No `Email/queryChanges` (explicit `cannotCalculateChanges` error, not unknownMethod — clients like the bundled one re-query), no `Mailbox/set`, no `Email/copy`/`Email/import`/`Email/parse`, no `SearchSnippet/*`, no `VacationResponse/*`, no `PushSubscription` (§7.2) — the §7.3 event source is the only push channel.
+- No `FilterOperator` trees (AND/OR/NOT → `unsupportedFilter`) and no `anchor` pagination (→ `invalidArguments`); Email sorting is `receivedAt` only, Mailbox sorting `name`/`sortOrder` only.
+- EmailSubmission has no state tracking (`newState` is constant '0', updates/destroys are rejected with `forbidden`) and no EmailSubmission/get|changes.
+- Session `state` and `sessionState` are the constant '0': the session object never changes at runtime for a given account.
+- Memory backend simplifications: thread ids derive from normalized subjects (reply/forward prefixes stripped), not References headers — emails with an empty subject get their own thread; raw RFC 5322 blobs render headers + text body only (attachments stay separate blobs, not MIME-encoded into the raw message); date filters compare ISO strings lexicographically, assuming normalized UTC ('Z') timestamps.
+- Initial-sweep race (client): an email created between the Email/query and Email/get of the sweep is picked up by the following delta fetch, not the sweep itself (dedupe prevents double emission).
 
 ## By-design unbounded state (accepted)
 
 - Client: `seenEmailIds` retains every emitted email id for the instance lifetime — required for dedupe across reconnects and sweep/delta overlap; on a very long-lived, high-volume connection this grows without a pruning hook. Recreate the client to reset it.
-- Test server (in-memory helper, not production code): the per-account change log grows one entry per mutation (needed by `Email/changes`), destroyed emails leave their blobs in the blob store, and request bodies are buffered without enforcing the advertised `maxSizeRequest`.
+- MemoryMailBackend (in-memory helper, not production storage): the per-account email and mailbox change logs grow one entry per mutation (needed by the /changes methods), destroyed emails leave their blobs and thread-subject mappings in place, and uploaded blobs are never expired. The node wrapper buffers request bodies in memory up to maxSizeUpload + 1 bytes before dispatch (test-helper convenience; the JMAP per-endpoint limits are enforced inside `fetchHandler`).