Skip to content

[P2][docs] Document performance envelope and bulk-load guidance #34

Description

@cevheri

Summary

The kernel copies the full sorted store per transaction (committed.slice() in transact). Bulk workloads are O(n²) in store size; entire DB lives in RAM. Seed/demo loops can look "hung" with no documented ceiling.

Audit ID: Section 2 Med — Wave 2 (documentation)

Fix (docs-first)

Add README section (or docs/PERFORMANCE.md if preferred):

  • In-memory sorted array model → cost per commit scales with entry count.
  • Guidance: wrap bulk loads in one transact(), not one per row.
  • Honest ceilings: suitable for embedded/dev/test scale; not a server OLTP engine.
  • Reference ARCHITECTURE.md for WAL replay cost on open.

Optional: mention #12 compaction for disk growth (not RAM).

Acceptance criteria

  • Performance envelope documented where new users look (README or linked doc).
  • Bulk-load anti-pattern called out explicitly.
  • No changeset (docs only).

Agent constraints

  • Do not promise future optimizations; document current behavior only.

Verification

Manual doc review.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docsPre-announcement auditdocumentationImprovements or additions to documentationpre-announcementPre-announcement auditpriority/mediumPre-announcement audit

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions