perf: define and enforce a large-document latency and memory support envelope

[seonghobae]

Buyer-visible product gap

Protected Inkspan main has strong correctness, package, browser, conversion, and coverage gates, but it does not publish or enforce a supported large-document performance envelope. Protected main is the only shipped implementation authority; its exact tip is mutable and must be refetched at decision time rather than embedded here as lifecycle truth. The repository currently has no canonical benchmark corpus or merge gate for editor interaction latency, hydration, serialization, revision hashing, autosave coordination, collaboration updates, or Office conversion peak memory.

Enterprise buyers therefore cannot answer basic procurement and capacity questions:

• How large a Markdown/HTML document can be edited responsively?
• How do tables, CJK text, inline images, and collaboration affect latency and memory?
• At what size does Inkspan fail closed rather than freeze or exhaust memory?
• Which browser, device, Node, and Python profiles are supported?
• Will a dependency or feature change regress the supported envelope?

External evidence

• The W3C Event Timing API exposes latency from trusted user input through the following paint and includes keyboard, touch, beforeinput, input, and composition events. Its current Working Draft notes that inputs not handled within about 100 ms are perceived as slow: https://www.w3.org/TR/event-timing/
• Current editor/conversion vendors publish large-document performance work because document conversion that crashes or times out is a direct retention problem. Tiptap reports linear memory scaling and explicit testing above 100 pages for its DOCX conversion service: https://tiptap.dev/blog/release-notes/faster-lighter-and-more-reliable-docx-import-export-with-tiptap

These are measurement and market references, not performance claims for Inkspan.

Required scope

1. Deterministic benchmark corpus

Add committed, synthetic, content-safe fixtures with immutable hashes and no customer data:

• English, Korean, Japanese, Chinese, Vietnamese, and mixed-script paragraphs;
• headings, nested lists, links, code blocks, blockquotes, wide/deep tables, and horizontal rules;
• bounded inline raster images at several supported sizes;
• documents representing at least small, medium, large, and stress profiles;
• Office JSON fixtures that exercise DOCX/XLSX/PPTX limits and realistic 100+ page-equivalent output where supported.

Fixture generation must be deterministic and reviewable. Generated artifacts and their hashes belong in benchmark evidence; document bodies must not enter ordinary telemetry.

2. Measured operations

Measure at minimum:

• SSR shell render and client hydration;
• editor mount and first editable paint;
• trusted keyboard input, IME composition, toolbar action, undo/redo, table edit, paste, and image insertion;
• Markdown and HTML serialization;
• strict envelope parsing/canonicalization;
• strong revision and transition evidence;
• autosave enqueue/coalescing/commit classification;
• host-supplied Yjs update application;
• print-media activation;
• Office parse/render/publication duration and peak RSS.

Record p50, p75, p95, maximum, operation count, browser/runtime revision, reference hardware, document profile, and peak memory where the platform exposes a trustworthy measurement.

3. Support envelope and budgets

Create an accepted ADR and update docs/OPERABILITY.md with:

• named reference hardware/browser/runtime profiles;
• maximum supported document/profile limits;
• explicit graceful-degradation or fail-closed behavior above each limit;
• a reviewed interaction-latency target. For the supported reference profile, trusted input/composition p75 and p95 should target the 100 ms responsiveness boundary unless measured evidence justifies a narrower published envelope;
• explicit mount, serialization, revision, collaboration, and Office conversion budgets derived from the initial baseline;
• memory ceilings and leak/settling criteria derived from repeated-run measurements;
• regression tolerance and the process for deliberately changing a budget.

Do not invent a favorable threshold after a regression. A budget change requires evidence, an ADR update, and buyer-impact wording.

4. CI and scheduled evidence

• Keep a bounded smoke benchmark in PR CI.
• Run the complete matrix on a scheduled/manual exact-head lane with immutable benchmark metadata.
• Compare current results with the protected baseline and fail on a material unapproved regression.
• Store only synthetic fixture IDs, measurements, runtime/hardware metadata, and source/package hashes.
• Distinguish infrastructure noise from product regression through repeated samples and a documented statistical rule; a single best run is not acceptance evidence.

5. Root-cause optimization

After the baseline identifies bottlenecks, fix the owned causes rather than hiding them with higher timeouts. Candidate techniques may include transaction-scoped memoization, incremental conversion, bounded chunking, avoiding duplicate document clones, and worker/off-main-thread execution where semantics remain deterministic.

Rust/GPU is not a default requirement for this editor package. Introduce a new compute boundary only if profiling demonstrates an Inkspan-owned workload, a measurable benefit, parity tests, package portability, and a superseding architecture decision.

Acceptance criteria

• A single command produces reproducible benchmark JSON and a human-readable summary from committed synthetic fixtures.
• The packed npm artifact, not source-only imports, is exercised for buyer-facing editor operations.
• Chromium, Firefox, and WebKit results are captured on exact dependency/browser revisions; Node and supported Python versions cover headless/Office paths.
• The accepted supported envelope is published in README/OPERABILITY and distinguishes supported, degraded, rejected, and unmeasured profiles.
• The reference supported profile meets its reviewed interaction and memory budgets; violations fail CI or the scheduled release gate.
• Repeated mount/edit/serialize/destroy cycles demonstrate no unbounded retained-memory growth under the documented measurement method.
• Over-limit documents fail with stable, privacy-safe, actionable errors where a bounded API exists; no partial Office artifact is reported as successful.
• Benchmark results contain no prompts, tenant identifiers, credentials, comment bodies, or production document content.
• Benchmark harness production code and public APIs satisfy the repository’s 100% coverage and documentation requirements.

Priority and dependency

Priority: P1 commercial reliability. The first benchmark/contract PR can proceed independently of #118, but stable registry publication must not claim large-document support until this issue’s protected evidence exists.

The canonical product/technical maintenance baseline is protected at docs/product-technical-gap-baseline.md; lifecycle state must be refetched rather than inferred from a historical PR. The established performance implementation route is Draft PR #379 (feat/performance-envelope-375) as ownership context only: refetch its open/closed state, exact head, live base, changed paths, and active writers before any write, and never create a competing source writer while that lane remains active.