Skip to main content

PERF-NB-001 — Bound notebook save size, rate, and retention

FieldValue
StatusOpen improvement backlog; source-verified, scale boundary unmeasured
Architecture stateSource-backed save path
SeverityMedium
Affected surfaceAutosave, rich output, BFF memory, object versions, and history retention
Componentssparqd/oqullus, sparqd/bff-api, sparqd/workspace-file-management-backend
Associated issuesbff-api #230, workspace-file-management-backend #19, oqullus #524

Where the problem appears​

Generate bounded but increasing notebook output while changes continue, then measure save frequency, payload size, BFF memory, object versions, and history.

Concrete observed case​

During ongoing changes the current timer can serialize and upload the complete notebook every three seconds. Outputs are included. The BFF buffers the complete multipart upload in memory, and each accepted update creates a complete object version and a history row.

Expected condition​

Save rate, notebook/output bytes, proxy/service payload, process memory, object versions, and history retention have documented limits and observable failure states. Ordinary editing coalesces into one bounded save after inactivity.

Cause and evidence​

The reviewed autosave behaves as a repeating interval rather than a true idle debounce. No explicit notebook-size, output-size, upload, or retention boundary was identified across the assessed path.

Why it matters​

Large outputs multiply browser serialization, network transfer, BFF memory, object storage, and history/database cost. Concurrent saves can amplify the same pressure.

Existing controls and workarounds​

Clear unnecessary output before saving and avoid embedding unbounded streams or rich payloads. These user actions do not substitute for enforced limits.

Alternatives considered​

  1. Recommended: true idle debounce, in-flight coalescing, layered size limits, bounded output, streamed or spooled forwarding, and retention policy.
  2. Increase BFF memory — rejected as the only response because payload and storage growth remain unbounded.
  3. Disable output persistence — reduces size but removes a supported notebook behavior; bounded output is preferable.

Component involvement​

  • sparqd/oqullus owns save coalescing and notebook/output limits.
  • sparqd/bff-api owns bounded non-memory-only upload forwarding.
  • sparqd/workspace-file-management-backend owns object/history retention and conflict-safe persistence.

Reproduction and verification​

Follow NB-S018.

Resolution conditions​

Close when measured thresholds are enforced at every layer, overload is actionable, save rate is coalesced, and retention demonstrably removes expired history and object versions.

Validation and blockers​

Source behavior is confirmed. Representative payload, memory, latency, and retention measurements are pending.