GES Extension: Emmett binding

Part of the Git Event Store specification family. Extends the core specification (../git-event-store-spec.md); RFC-2119 keywords per core §0.1. An implementation claims this extension per core §1. The methods below are the reference binding of the derived stream view (core §10.0), not of the DCB core itself; core conformance never requires this binding (E-10-0c). Emmett does not implement DCB, so this binding reaches only the subset of the core expressible as a single-state-id append condition. Section and requirement numbering is retained from the pre-family document for E-ID and cross-reference stability.

---

10.1 appendToStream(streamName, events, options?) — Emmett binding of core append

• MUST be atomic across all events of the call, realized as a chain of one-event commits made visible by a single terminal ref CAS (§5.2.1). A crash mid-append leaves nothing visible.
• MUST honor options.expectedStreamVersion per §10.1.1, translated into a core append condition (§18c.1) and checked against the tip observed before building the chain.
• MUST build all objects in memory via plumbing (write blobs → trees → the N chained commits → one CAS ref update). It MUST NOT perform a working-tree checkout, stash, or touch HEAD. (This is what lets many streams coexist without checkout side effects.)
• MUST order durability correctly when durability is claimed: the N commits’ objects MUST be durable before the ref update is made durable (§11), so recovery never finds a tip pointing at a lost object.
• MUST return the next expected stream version (nextExpectedStreamVersion).
• MUST populate every field of §6.2 and, if enabled, §8.3. It MUST write the state-stream tag (§18b) so the appended events are selectable by the core query; it populates no other tags.

10.1.1 expectedStreamVersion as an append condition

The stream view is a materialized query (core §10.0), so every expectedStreamVersion value maps onto a core append condition (§18c.1) whose query selects the one state stream:

Emmett value	Core append condition
ANY	no condition; the ref transaction alone prevents a lost write (§9.3.1)
STREAM_DOES_NOT_EXIST (no-stream)	query selects the state id, after = 0 — equivalently, the ref MUST NOT exist
exact bigint v	query selects the state id, after = the sequence position of that stream’s event at stream position v

The binding MUST derive the stream version from the tip commit’s GES-Position trailer (§7.3.1), not by counting commits: a multi-event append advances the tip by N commits, so one commit is not one append. It MUST verify the exact expectedStreamVersion constants and EventStore signatures against the installed Emmett version (pre-1.0, evolving).

10.2 readStream(streamName, options?) — Emmett binding of core read

• MUST resolve the stream ref, then walk commits from the stream root to the tip (or the range implied by options), reading the single event from each commit, and return ReadEvents in ancestry order.
• MUST reconstruct recorded metadata: streamPosition from the record, streamName from the ref/record, id and timestamp from the record. globalPosition MUST be the event’s sequence position (core §20), which every conforming store maintains (C22); it is undefined only while the event is unsequenced (§20.3.2).
• SHOULD support from/to position bounds and stop the walk early when satisfied.
• If the ref does not exist, MUST return an empty result (not an error).

10.3 aggregateStream(streamName, { evolve, initialState, ... }) — Emmett binding of core read + fold

• MUST read the stream (starting from a snapshot if one exists, §13), fold with evolve over initialState, and return { state, currentStreamVersion } (or the Emmett-named equivalent), where the returned stream version is the stream position of the last applied event.
• Determinism: given identical events and evolve, the result MUST be byte-identical across runs and implementations.

---

Requirements (EARS)

Moved verbatim from the companion catalog (../ges-review-and-ears.md); IDs unchanged.

The binding maps core operations; its behavioural requirements are the E-10 family, which remains in the companion catalog because those obligations bind the core operations themselves, not this binding (§16.1: Emmett method names in tests are reference-binding shorthand).