Skip to content

docs/storage-model.md still says V1 has no store-directory lock #796

Closed

Description

@kevinswiber

What

docs/storage-model.md:858 opens the Concurrency section with:

V1 has no store-directory lock: Pointbreak does not coordinate writers with lockfiles, leases, a daemon, IPC, or filesystem notifications.

That is no longer true. A per-event authority lock exists and is taken inside the event-store write primitives (src/session/store/authority_lock.rs, STORE_AUTHORITY_LOCK_FILE = "authority.writer.lock"; acquired by record_event_once_acknowledged / record_change_event_once_acknowledged in src/session/store/event_store.rs, and held across an ingest batch by EventWriteBatch).

The rest of the paragraph is still accurate and worth keeping: the content-addressed primitives are what make concurrent writers to one store directory safe, identical events converge, different events never collide, conflicting events under one idempotency key fail loud, and no shared mutable projection file is written. The same section later says "Any store-directory lock added later must be scoped to the store directory, never 'one clone, one writer'" (:872), which now reads as future tense for something that partly exists.

Why it is not a drive-by edit

No public document describes the authority lock today: not its scope (per event write, inside the primitive, not a store-wide session lock), not what it does and does not promise to a concurrent writer, and not how it relates to the "no coordination" claim the paragraph makes. Writing an accurate replacement means deciding what to promise publicly, which belongs with the concurrent-store work rather than an incidental docs fix. A previous change touched this same paragraph for an unrelated reason and deliberately left the sentence alone rather than invent wording.

Acceptance sketch

  • The Concurrency section describes the per-event authority lock truthfully: its scope, that it is not a store-wide or one-writer-per-clone lease, and that content-addressed writes remain the property that makes concurrent writers safe.
  • The forward-looking sentence at :872 is reconciled with what now exists.
  • No new promise is made about cross-process coordination that the implementation does not keep.

Activity

  1. added
    documentationImprovements or additions to documentation
    storageStore layout, migration, retention, indexing, and persistence
    docs-hygieneDocumentation cleanup and public/private wording
    priority:P3-laterPost-1.0, speculative, or low-priority follow-up
    priority:P2-backlogUseful but not necessary for initial 1.0 definition
    and removed
    priority:P3-laterPost-1.0, speculative, or low-priority follow-up
    on Sep 19, 2026
  2. added theissue type on Sep 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docs-hygieneDocumentation cleanup and public/private wordingdocumentationImprovements or additions to documentationeffort:lowSmall, well-bounded change; one focused sessionpriority:P2-backlogUseful but not necessary for initial 1.0 definitionstorageStore layout, migration, retention, indexing, and persistence

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions