docs(ses): document Compartment availability and OOM limits (#2742)

[kriscendobot]

Summary

Implements endojs/endo#2742 by documenting two threats a Compartment cannot mitigate, both intrinsic to running JavaScript in a single agent.

• Adds a top-level Limitations section to docs/lockdown.md with two subsections:
  • Availability — A guest in an infinite loop, runaway recursion, or any non-terminating synchronous computation denies synchronous progress to every sibling compartment and the start compartment, until the engine intervenes.
  • Memory exhaustion — Because the JS spec does not require an engine to abort the agent on OOM (see the TC39 OOM-fails-fast proposal), a malicious compartment can intentionally exhaust memory; the resulting failure may surface inside an unrelated synchronous call into a victim's exported object, turning an availability concern into an integrity one.
• Cross-links the new section from packages/ses/README.md's ### Compartment section so readers find it where Compartment is introduced.

Both items are phrased as "what a Compartment cannot protect against" rather than as a critique — they are intrinsic to sharing one JavaScript agent.

New section preview

Limitations

Compartments isolate the authority and intrinsics available to guest code, but every compartment in a realm shares the same JavaScript agent — in engine terms, a single thread of execution and a single heap.

Anchor used for the cross-link: ./docs/lockdown.md#limitations (verified by building yarn docs and inspecting the generated api-docs/documents/lockdown.html).

Test plan

• npx prettier --check docs/lockdown.md packages/ses/README.md — clean
• yarn docs — typedoc still builds; new #limitations anchor is generated
• Render markdown in a viewer to confirm internal links resolve

[kriskowal]

Generally avoid em-dashes. Please integrate that feedback into CLAUDE.md in the style guide.

[kriskowal]

Separate sentences in this case. The em-dash is not more clear.

[kriscendobot]

Addressed in 5995742: split the agent-introduction sentence so the en-dash is gone and the second clause stands on its own ("...shares the same JavaScript agent. In engine terms, that is a single thread of execution and a single heap.").

[kriskowal]

Suggested change

	as a separate worker, process, or operating-system sandbox, around the
	suspect code.
	as a separate worker or process around the
	suspect code.

[kriscendobot]

Applied verbatim in 5995742.

[kriskowal]

Consider for (;;) {}, which I like to call a C’thuloop.

[kriscendobot]

Swapped while (true) {} for for (;;) {} in 5995742. Did not include the C'thuloop label inline (the surrounding paragraph already enumerates the failure modes by name); happy to add a parenthetical if you want the label to ship in the doc.

[kriskowal]

Should dedicate a section timing side-channels. Note that the default Compartment does not include any timers of any resolution, but it is very difficult to avoid inadvertently giving a guest program the ability to measure duration. Asynchronous communication to another worker or process is often enough to inadvertently expose a confined guest to a gadget for measuring the passage of time.

[kriscendobot]

Added the Timing side-channels section in f299f8e, placed as a third subsection under Limitations alongside Availability and Memory exhaustion. The section notes that the default Compartment excludes Date, performance.now, setTimeout, setImmediate, and other host scheduling primitives; explains that asynchronous round-trips to any other agent recover wall-clock duration; spells out the audit obligation (every async boundary the guest can reach, not just timer-like APIs in the global scope); and lists the host mitigation menu (separate worker or process; outbound rate throttling; padded guest-visible message timing).

[erights]

The section on timing side channels should cite https://papers.agoric.com/taxonomy-of-security-issues/

[kriscendobot]

Added a reference paragraph at the end of the Timing side-channels section pointing at https://papers.agoric.com/taxonomy-of-security-issues/ as the broader catalog this section samples. Pushed in the latest commit.

[kriscendobot]

Addressed both reviews; ready for another look.

Review 4209498509 (already in tree at 5995742):

• Em-dash split on docs/lockdown.md:1226 -> two sentences.
• Suggestion application at docs/lockdown.md:1231 -> applied verbatim.
• while (true) {} -> for (;;) {} at docs/lockdown.md:1238.

Review 4233409679 (new in f299f8e):

• Added a third subsection under Limitations: Timing side-channels.
  Notes that the default Compartment excludes Date, performance.now,
  setTimeout, setImmediate, and other host scheduling primitives;
  explains that asynchronous round-trips to any other agent recover
  wall-clock duration; states the audit obligation (every async boundary,
  not just timer enumeration); and lists the host mitigation menu
  (separate worker or process; outbound rate throttling; padded
  guest-visible message timing).

Thread replies posted on each of the four inline comments citing the
addressing SHA. Re-requesting review.

[kriskowal]

Ferried upstream as endojs/endo#3275 (head 4d8ed6be74c861472a85df3f38af7081f1d6689c).

The upstream PR squashes 4 of the 5 commits on this branch (8a1fc626, 59957425, f299f8e4, 838d18ff) into one. Commit cb8d6286 (the AGENTS.md prose-style rule) is explicitly excluded as off-topic for issue #2742; a separate ferry can carry it later if desired. The upstream commit message adds Fixes #2742.