Skip to content

syncbat: add atomic typed batch append effect capability #229

Description

@heyoub

Problem

syncbat::EffectBackend and EventAppendHandle currently mediate only one durable append at a time. The store backend can lower a typed event to Store::append_typed, while BatPak itself already exposes atomic Store::append_batch[_with_options].

A downstream operation with a large, fully planned event set therefore has two bad choices:

  1. append each item separately, losing atomic batch durability and paying one writer round-trip per item; or
  2. call the Store batch API directly, bypassing the runtime-owned effect capability and falsifying the invocation's observed effect row/receipt semantics.

The second choice is not acceptable: the effect backend is documented as the only path through which a handler may reach durable effects.

Requested neutral contract

Add an object-safe atomic typed batch capability to syncbat:

  • an EventAppendHandle batch method and matching EffectBackend method;
  • per-item coordinate, kind/version, canonical payload, append options/idempotency, and causation metadata;
  • preflight validation against every declared append target before submitting anything;
  • StoreEffectBackend lowering to BatPak's atomic batch API;
  • per-item AppendReceipt values returned in input order;
  • observed effect state updated only after the batch commits;
  • all-or-nothing behavior for encode, declaration, gate, store, and receipt failures.

The carrier must remain object-safe and must not require domain vocabulary.

Proof requested

  • mixed-coordinate and mixed-kind typed batches;
  • duplicate idempotency keys returning the original receipts;
  • declaration denial before any append;
  • injected failure before append and during store submission;
  • crash/reopen witness proving either the complete batch or none;
  • observed effect row remains empty on failure and records the batch only after success;
  • equivalence of single-item batch bytes/receipt with the existing typed append path.

Downstream containment

The downstream keeps its correct sequential effect-mediated append loop rather than bypassing syncbat. A narrow compatibility seam can switch to this API when released.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions