example

func (*DeviceCache[W]) AdvanceEpoch ¶

func (inst *DeviceCache[W]) AdvanceEpoch()

AdvanceEpoch advances the cache's pinning epoch — call once per frame / batch so untouched L1 entries become evictable.

func (*DeviceCache[W]) Get ¶

func (inst *DeviceCache[W]) Get(key uint64) (ent *DeviceEntity, found bool)

Get retrieves an entity by Key through the cache; local writes are visible immediately (write-through). A miss queues the key for the next batch fetch (the caching suspend/replay contract). A miss can also mean the batched fetch errored (misses swallow fetch errors; the circuit breaker backs off) — GetFetch surfaces the error instead, and the store's Latest stays the authoritative check. The returned entity is shared with the cache: treat it as immutable.

func (*DeviceCache[W]) GetFetch ¶

func (inst *DeviceCache[W]) GetFetch(ctx context.Context, key uint64) (ent *DeviceEntity, found bool, err error)

GetFetch is the single-lookup read: the cached entity when present, otherwise one immediate batched point fetch — fetch errors surface instead of reading as misses, so found=false with err=nil is the authoritative absent. A key in the dirty write window that the cache could not answer is an error rather than a stale row (see below). Prefer Get plus the work-item protocol when batching lookups across a frame; the initial miss here also queues the key, so a later batch fetch may include it redundantly (harmless).

func (*DeviceCache[W]) GetLive ¶

func (inst *DeviceCache[W]) GetLive(key uint64) (ent *DeviceEntity, found bool)

GetLive is the cached state-view read: the cache's newest row for the key with the tombstone read as absent — exact under this process's single writer (local writes invalidate); external writers need MarkStale / Invalidate. The store's uncached GetLive stays the authoritative read. A miss queues the batch fetch like Get.

func (*DeviceCache[W]) GetLiveAcceptStale ¶

func (inst *DeviceCache[W]) GetLiveAcceptStale(key uint64) (ent *DeviceEntity, found bool, stale bool)

GetLiveAcceptStale is the stale-while-revalidate state-view read: a stale entry is served immediately (stale=true) while the refetch queues in the background — pair with the work-item replay loop. Tombstones read as absent; stale then reports whether that verdict came from a stale entry.

func (*DeviceCache[W]) Invalidate ¶

func (inst *DeviceCache[W]) Invalidate(key uint64)

Invalidate drops the key's cached entry (L1 and stash).

func (*DeviceCache[W]) InvalidateAll ¶

func (inst *DeviceCache[W]) InvalidateAll()

InvalidateAll drops every cached entry — the bulk external-writer signal (e.g. after an import). In-flight miss bookkeeping (queued keys, pending work items) and the dirty-window pins are dropped with it: call between frames, with no suspended work and no unflushed local writes (the fetcher's dirty-guard keeps pre-write rows out of the cleared cache until the next Flush, at the cost of misses on those keys).

func (*DeviceCache[W]) IterateReadyWorkItems ¶

func (inst *DeviceCache[W]) IterateReadyWorkItems(ctx context.Context) iter.Seq[W]

IterateReadyWorkItems flushes the queued keys when the fetch criteria are met and replays the work items that had misses.

func (*DeviceCache[W]) IterateRestWorkItems ¶

func (inst *DeviceCache[W]) IterateRestWorkItems(ctx context.Context) iter.Seq[W]

IterateRestWorkItems forces a fetch of all queued keys and replays the pending work items.

func (*DeviceCache[W]) MarkStale ¶

func (inst *DeviceCache[W]) MarkStale(key uint64)

MarkStale flags the key's cached entry as stale — the external-writer signal: the next strict read misses and queues a refetch, while accept-stale reads keep serving the old value until it lands.

func (*DeviceCache[W]) MarkStaleIfOlder ¶

func (inst *DeviceCache[W]) MarkStaleIfOlder(key uint64, order time.Time)

MarkStaleIfOlder is the version-carrying external-writer signal: it stales the cached entry only if its Order is below order, so a redundant signal for a version the view already holds is free — the natural sink for an invalidation stream carrying (key, Order).

func (*DeviceCache[W]) WorkItem ¶

func (inst *DeviceCache[W]) WorkItem(w W) iter.Seq[functional.NilIteratorValueType]

WorkItem marks the current work item for the cache's miss bookkeeping.

func (*DeviceEntity) Archetype ¶

func (inst *DeviceEntity) Archetype() (a []string)

Archetype reports which components the entity carries, in schema order.

func (*DeviceEntity) IsTombstone ¶

func (inst *DeviceEntity) IsTombstone() bool

IsTombstone reports whether this row is a state-view deletion marker — what the tombstone-blind verbs (Latest, Replay, the cache's Get) hand back for a deleted key.

func (*DeviceEntityBuilder) AddBattery ¶

func (inst *DeviceEntityBuilder) AddBattery(row Battery) *DeviceEntityBuilder

AddBattery contributes the Battery component to the open entity.

The attributes are buffered, not written: a section frame closes for good, so a component that closed its own sections would shut out the next component sharing one. Commit writes them, one frame per section in first-seen order (ADR-0183 D4).

A second Add of this component, or an Add on an entity already using Raw(), is refused: both used to mark the row un-mirrorable and carry on, which made its read-back shape depend on a call the writer had probably made by accident.

func (*DeviceEntityBuilder) AddIdentity ¶

func (inst *DeviceEntityBuilder) AddIdentity(row Identity) *DeviceEntityBuilder

AddIdentity contributes the Identity component to the open entity.

The attributes are buffered, not written: a section frame closes for good, so a component that closed its own sections would shut out the next component sharing one. Commit writes them, one frame per section in first-seen order (ADR-0183 D4).

A second Add of this component, or an Add on an entity already using Raw(), is refused: both used to mark the row un-mirrorable and carry on, which made its read-back shape depend on a call the writer had probably made by accident.

func (*DeviceEntityBuilder) AddLocated ¶

func (inst *DeviceEntityBuilder) AddLocated(row Located) *DeviceEntityBuilder

AddLocated contributes the Located component to the open entity.

The attributes are buffered, not written: a section frame closes for good, so a component that closed its own sections would shut out the next component sharing one. Commit writes them, one frame per section in first-seen order (ADR-0183 D4).

A second Add of this component, or an Add on an entity already using Raw(), is refused: both used to mark the row un-mirrorable and carry on, which made its read-back shape depend on a call the writer had probably made by accident.

func (*DeviceEntityBuilder) AddTagged ¶

func (inst *DeviceEntityBuilder) AddTagged(row Tagged) *DeviceEntityBuilder

AddTagged contributes the Tagged component to the open entity.

The attributes are buffered, not written: a section frame closes for good, so a component that closed its own sections would shut out the next component sharing one. Commit writes them, one frame per section in first-seen order (ADR-0183 D4).

A second Add of this component, or an Add on an entity already using Raw(), is refused: both used to mark the row un-mirrorable and carry on, which made its read-back shape depend on a call the writer had probably made by accident.

func (*DeviceEntityBuilder) Commit ¶

func (inst *DeviceEntityBuilder) Commit() (err error)

Commit finishes the open entity, buffers the row, and writes it through to attached cache views: the entity is populated and pinned until the store's Flush makes it durable — reads after writes hit immediately, and the caching version gate plus the pin make a raced refetch of the pre-write row bounce off. A commit that touched Raw() cannot be materialized faithfully and invalidates the key instead. A failed Commit rolls the frame back — the entity is discarded and the store stays usable.

func (*DeviceEntityBuilder) Raw ¶

func (inst *DeviceEntityBuilder) Raw() *lowlevel.InEntityDeviceTable

Raw exposes the underlying DML entity for direct attribute manipulation within the same entity frame. The type lives in internal/lowlevel: callers outside the generated package hold the returned value by inference (raw := b.Raw()) and chain its methods, but cannot name the type in their own signatures.

func (*DeviceEntityBuilder) Rollback ¶

func (inst *DeviceEntityBuilder) Rollback() (err error)

Rollback abandons the open entity frame without committing it; already-buffered rows and the store remain usable.

func (*DeviceStore) Begin ¶

func (inst *DeviceStore) Begin(id uint64, ts time.Time) *DeviceEntityBuilder

Begin opens one entity with the envelope roles as typed arguments (Key, Order) and a live lifecycle.

func (*DeviceStore) Buffered ¶

func (inst *DeviceStore) Buffered() int

Buffered reports the number of committed-but-unflushed rows.

func (*DeviceStore) Close ¶

func (inst *DeviceStore) Close()

Close discards everything unflushed and releases the store's Arrow builder; the store must not be used afterwards. Required for a clean shutdown under tracking/checked allocators — the default Go allocator needs no Close.

func (*DeviceStore) Delete ¶

func (inst *DeviceStore) Delete(id uint64, ts time.Time) (err error)

Delete appends a tombstone row for id (no components; lifecycle marks the deletion). The tombstone writes through to attached cache views like any commit — a versioned deletion, so GetLive reads the key as absent immediately.

func (*DeviceStore) DiscardPending ¶

func (inst *DeviceStore) DiscardPending()

DiscardPending drops every committed-but-unflushed row: records retained by a failed Flush, rows still in the DML builder, and an open (uncommitted) entity frame. It gives a failed Flush "never happened" semantics — ClickHouse state is the truth afterwards. Ambient stamps are cleared with the frame they were pushed for — including any pushed through Raw() — so an abandoned builder cannot leak its stamps onto later entities.

func (*DeviceStore) EnsureTable ¶

func (inst *DeviceStore) EnsureTable(ctx context.Context) (err error)

EnsureTable applies the composed CREATE TABLE (plus the DDLTail suffix, when configured). Idempotent (CREATE TABLE IF NOT EXISTS). The embedded script is issued one statement per Exec — the optional CREATE DATABASE, then the CREATE TABLE — because the ClickHouse HTTP interface rejects a multi-statement body; under a Table override the statements are re-pointed at the override (recordstore.ProvisioningStatements: header and database only, the column block stays byte-identical).

func (*DeviceStore) Flush ¶

func (inst *DeviceStore) Flush(ctx context.Context) (n int, err error)

Flush drains the buffered rows to ClickHouse (Arrow IPC, ADR-0089 pivot). Rows are durable when Flush returns, engine permitting. On insert failure the transferred records are retained and the next Flush ships them — Flush is retryable; DiscardPending drops them instead. An open (uncommitted) entity frame makes Flush error.

func (*DeviceStore) GetLive ¶

func (inst *DeviceStore) GetLive(ctx context.Context, key uint64) (ent *DeviceEntity, found bool, err error)

GetLive is Latest plus tombstone interpretation: newest row wins, a tombstone reads as absent — the state-view read (the cache view carries the cached twin).

func (*DeviceStore) IngestBattery ¶

func (inst *DeviceStore) IngestBattery(ts time.Time, rows []Battery) (err error)

IngestBattery buffers one whole entity per row carrying only the Battery component, all stamped with ts — rows ship on the next Flush, like every write. Keys must be distinct within one call (rows share ts, so duplicates would tie on Order): a duplicate returns recordstore.ErrDuplicateIngestKey. On any error the rows buffered so far remain buffered — Flush ships them, DiscardPending drops them.

func (*DeviceStore) IngestIdentity ¶

func (inst *DeviceStore) IngestIdentity(ts time.Time, rows []Identity) (err error)

IngestIdentity buffers one whole entity per row carrying only the Identity component, all stamped with ts — rows ship on the next Flush, like every write. Keys must be distinct within one call (rows share ts, so duplicates would tie on Order): a duplicate returns recordstore.ErrDuplicateIngestKey. On any error the rows buffered so far remain buffered — Flush ships them, DiscardPending drops them.

func (*DeviceStore) IngestLocated ¶

func (inst *DeviceStore) IngestLocated(ts time.Time, rows []Located) (err error)

IngestLocated buffers one whole entity per row carrying only the Located component, all stamped with ts — rows ship on the next Flush, like every write. Keys must be distinct within one call (rows share ts, so duplicates would tie on Order): a duplicate returns recordstore.ErrDuplicateIngestKey. On any error the rows buffered so far remain buffered — Flush ships them, DiscardPending drops them.

func (*DeviceStore) IngestTagged ¶

func (inst *DeviceStore) IngestTagged(ts time.Time, rows []Tagged) (err error)

IngestTagged buffers one whole entity per row carrying only the Tagged component, all stamped with ts — rows ship on the next Flush, like every write. Keys must be distinct within one call (rows share ts, so duplicates would tie on Order): a duplicate returns recordstore.ErrDuplicateIngestKey. On any error the rows buffered so far remain buffered — Flush ships them, DiscardPending drops them.

func (*DeviceStore) Latest ¶

func (inst *DeviceStore) Latest(ctx context.Context, key uint64) (ent *DeviceEntity, found bool, err error)

Latest returns the newest row for key, tombstone-blind (the raw row-level primitive — a deleted key still returns its tombstone row; GetLive is the interpreted state-view read). Reads see only flushed rows.

func (*DeviceStore) Replay ¶

func (inst *DeviceStore) Replay(ctx context.Context, key uint64, fromOrder time.Time, opts recordstore.ReplayOpts) iter.Seq2[*DeviceEntity, error]

Replay iterates the rows for key with the order column >= fromOrder in ascending order — the event-replay primitive. A zero fromOrder replays everything (zero time.Time has no defined UnixNano; recordstore.SeqTs(0) is the equivalent explicit bound); opts.To bounds the replay exclusively ("state as of To") and opts.Limit caps the row count. The sequence is single-use; ctx must stay valid until iteration completes; the query may execute at call time or lazily during iteration (buffered in v1 — a streaming executor changes nothing visible); an error ends the sequence as a final (nil, err) pair. Reads see only flushed rows.

func (*DeviceStore) ScanBattery ¶

func (inst *DeviceStore) ScanBattery(ctx context.Context, opts recordstore.ScanOpts) iter.Seq2[*DeviceEntity, error]

ScanBattery iterates the entities whose rows carry a conforming Battery component, ordered by (Order, Key) — so entities sharing an Order still come out in a fixed sequence. Rows that tie on BOTH (the same key written twice at the same Order) are not ordered against each other by this clause; the table keeps newest-per-key, so which of them survives is the engine's choice, not the scan's. opts.ExtraPredicate (trusted raw SQL over the physical columns — never untrusted input) further restricts the scan; opts.Limit caps the row count. The Filter artefact uses ClickHouse built-ins only, so this is a single SELECT — no helper UDFs, no multi-statement script (the ExecutorI contract). The sequence is single-use; ctx must stay valid until iteration completes; an error ends it as a final (nil, err) pair. Scans see only flushed rows.

func (*DeviceStore) ScanIdentity ¶

func (inst *DeviceStore) ScanIdentity(ctx context.Context, opts recordstore.ScanOpts) iter.Seq2[*DeviceEntity, error]

ScanIdentity iterates the entities whose rows carry a conforming Identity component, ordered by (Order, Key) — so entities sharing an Order still come out in a fixed sequence. Rows that tie on BOTH (the same key written twice at the same Order) are not ordered against each other by this clause; the table keeps newest-per-key, so which of them survives is the engine's choice, not the scan's. opts.ExtraPredicate (trusted raw SQL over the physical columns — never untrusted input) further restricts the scan; opts.Limit caps the row count. The Filter artefact uses ClickHouse built-ins only, so this is a single SELECT — no helper UDFs, no multi-statement script (the ExecutorI contract). The sequence is single-use; ctx must stay valid until iteration completes; an error ends it as a final (nil, err) pair. Scans see only flushed rows.

func (*DeviceStore) ScanLocated ¶

func (inst *DeviceStore) ScanLocated(ctx context.Context, opts recordstore.ScanOpts) iter.Seq2[*DeviceEntity, error]

ScanLocated iterates the entities whose rows carry a conforming Located component, ordered by (Order, Key) — so entities sharing an Order still come out in a fixed sequence. Rows that tie on BOTH (the same key written twice at the same Order) are not ordered against each other by this clause; the table keeps newest-per-key, so which of them survives is the engine's choice, not the scan's. opts.ExtraPredicate (trusted raw SQL over the physical columns — never untrusted input) further restricts the scan; opts.Limit caps the row count. The Filter artefact uses ClickHouse built-ins only, so this is a single SELECT — no helper UDFs, no multi-statement script (the ExecutorI contract). The sequence is single-use; ctx must stay valid until iteration completes; an error ends it as a final (nil, err) pair. Scans see only flushed rows.

func (*DeviceStore) ScanTagged ¶

func (inst *DeviceStore) ScanTagged(ctx context.Context, opts recordstore.ScanOpts) iter.Seq2[*DeviceEntity, error]

ScanTagged iterates the entities whose rows carry a conforming Tagged component, ordered by (Order, Key) — so entities sharing an Order still come out in a fixed sequence. Rows that tie on BOTH (the same key written twice at the same Order) are not ordered against each other by this clause; the table keeps newest-per-key, so which of them survives is the engine's choice, not the scan's. opts.ExtraPredicate (trusted raw SQL over the physical columns — never untrusted input) further restricts the scan; opts.Limit caps the row count. The Filter artefact uses ClickHouse built-ins only, so this is a single SELECT — no helper UDFs, no multi-statement script (the ExecutorI contract). The sequence is single-use; ctx must stay valid until iteration completes; an error ends it as a final (nil, err) pair. Scans see only flushed rows.

func (*DeviceStore) VerifySchema ¶

func (inst *DeviceStore) VerifySchema(ctx context.Context) (err error)

VerifySchema compares the live table's columns — names and order — against the generated schema. EnsureTable alone cannot detect drift on an existing table (IF NOT EXISTS succeeds against any old shape), and the decode is positional, so drift fails late or, for same-typed column swaps, silently: run VerifySchema at startup after EnsureTable.

It checks the COLUMN contract only. The membership-id contract is not checked and cannot be from the schema alone: the ids live in the membership columns as ordinary values, and a FAT table legitimately carries other kinds' ids beside this store's. Rows written under a different id assignment therefore pass VerifySchema and then match nothing — every component decodes absent, with no error. Compare DeviceMembershipIds against the writer's assignment when pointing this store at rows it did not write.

What it describes is the reader's own projection — DESCRIBE over `SELECT *`, not over the table — because that is what the positional decode consumes. DESCRIBE TABLE lists columns SELECT * does not return (MATERIALIZED, ALIAS, EPHEMERAL), so a table legitimately carrying one beside the generated shape — a derived column added by ALTER after EnsureTable, which is how a store gets a skip index over a value its leeway attributes only encode — would fail a check whose contract still held. Describing the projection also follows the asterisk_include_* settings, which decide what SELECT * returns and which nothing here pins: under those, a derived column IS in the decode, and this notices where a column-kind filter would have blessed the mis-decode.

func (*WidgetCache[W]) AdvanceEpoch ¶ added in v0.0.13

func (inst *WidgetCache[W]) AdvanceEpoch()

AdvanceEpoch advances the cache's pinning epoch — call once per frame / batch so untouched L1 entries become evictable.

func (*WidgetCache[W]) Get ¶ added in v0.0.13

func (inst *WidgetCache[W]) Get(key uint64) (ent *WidgetEntity, found bool)

Get retrieves an entity by Key through the cache; local writes are visible immediately (write-through). A miss queues the key for the next batch fetch (the caching suspend/replay contract). A miss can also mean the batched fetch errored (misses swallow fetch errors; the circuit breaker backs off) — GetFetch surfaces the error instead, and the store's Latest stays the authoritative check. The returned entity is shared with the cache: treat it as immutable.

func (*WidgetCache[W]) GetFetch ¶ added in v0.0.13

func (inst *WidgetCache[W]) GetFetch(ctx context.Context, key uint64) (ent *WidgetEntity, found bool, err error)

GetFetch is the single-lookup read: the cached entity when present, otherwise one immediate batched point fetch — fetch errors surface instead of reading as misses, so found=false with err=nil is the authoritative absent. A key in the dirty write window that the cache could not answer is an error rather than a stale row (see below). Prefer Get plus the work-item protocol when batching lookups across a frame; the initial miss here also queues the key, so a later batch fetch may include it redundantly (harmless).

func (*WidgetCache[W]) GetLive ¶ added in v0.0.13

func (inst *WidgetCache[W]) GetLive(key uint64) (ent *WidgetEntity, found bool)

GetLive is the cached state-view read: the cache's newest row for the key with the tombstone read as absent — exact under this process's single writer (local writes invalidate); external writers need MarkStale / Invalidate. The store's uncached GetLive stays the authoritative read. A miss queues the batch fetch like Get.

func (*WidgetCache[W]) GetLiveAcceptStale ¶ added in v0.0.13

func (inst *WidgetCache[W]) GetLiveAcceptStale(key uint64) (ent *WidgetEntity, found bool, stale bool)

GetLiveAcceptStale is the stale-while-revalidate state-view read: a stale entry is served immediately (stale=true) while the refetch queues in the background — pair with the work-item replay loop. Tombstones read as absent; stale then reports whether that verdict came from a stale entry.

func (*WidgetCache[W]) Invalidate ¶ added in v0.0.13

func (inst *WidgetCache[W]) Invalidate(key uint64)

Invalidate drops the key's cached entry (L1 and stash).

func (*WidgetCache[W]) InvalidateAll ¶ added in v0.0.13

func (inst *WidgetCache[W]) InvalidateAll()

InvalidateAll drops every cached entry — the bulk external-writer signal (e.g. after an import). In-flight miss bookkeeping (queued keys, pending work items) and the dirty-window pins are dropped with it: call between frames, with no suspended work and no unflushed local writes (the fetcher's dirty-guard keeps pre-write rows out of the cleared cache until the next Flush, at the cost of misses on those keys).

func (*WidgetCache[W]) IterateReadyWorkItems ¶ added in v0.0.13

func (inst *WidgetCache[W]) IterateReadyWorkItems(ctx context.Context) iter.Seq[W]

IterateReadyWorkItems flushes the queued keys when the fetch criteria are met and replays the work items that had misses.

func (*WidgetCache[W]) IterateRestWorkItems ¶ added in v0.0.13

func (inst *WidgetCache[W]) IterateRestWorkItems(ctx context.Context) iter.Seq[W]

IterateRestWorkItems forces a fetch of all queued keys and replays the pending work items.

func (*WidgetCache[W]) MarkStale ¶ added in v0.0.13

func (inst *WidgetCache[W]) MarkStale(key uint64)

MarkStale flags the key's cached entry as stale — the external-writer signal: the next strict read misses and queues a refetch, while accept-stale reads keep serving the old value until it lands.

func (*WidgetCache[W]) MarkStaleIfOlder ¶ added in v0.0.13

func (inst *WidgetCache[W]) MarkStaleIfOlder(key uint64, order time.Time)

MarkStaleIfOlder is the version-carrying external-writer signal: it stales the cached entry only if its Order is below order, so a redundant signal for a version the view already holds is free — the natural sink for an invalidation stream carrying (key, Order).

func (*WidgetCache[W]) WorkItem ¶ added in v0.0.13

func (inst *WidgetCache[W]) WorkItem(w W) iter.Seq[functional.NilIteratorValueType]

WorkItem marks the current work item for the cache's miss bookkeeping.

func (*WidgetEntity) Archetype ¶ added in v0.0.13

func (inst *WidgetEntity) Archetype() (a []string)

Archetype reports which components the entity carries, in schema order.

func (*WidgetEntity) IsTombstone ¶ added in v0.0.13

func (inst *WidgetEntity) IsTombstone() bool

IsTombstone reports whether this row is a state-view deletion marker — what the tombstone-blind verbs (Latest, Replay, the cache's Get) hand back for a deleted key.

func (*WidgetEntityBuilder) Commit ¶ added in v0.0.13

func (inst *WidgetEntityBuilder) Commit() (err error)

Commit finishes the open entity, buffers the row, and writes it through to attached cache views: the entity is populated and pinned until the store's Flush makes it durable — reads after writes hit immediately, and the caching version gate plus the pin make a raced refetch of the pre-write row bounce off. A commit that touched Raw() cannot be materialized faithfully and invalidates the key instead. A failed Commit rolls the frame back — the entity is discarded and the store stays usable.

func (*WidgetEntityBuilder) Raw ¶ added in v0.0.13

func (inst *WidgetEntityBuilder) Raw() *lowlevel.InEntityWidgetTable

Raw exposes the underlying DML entity for direct attribute manipulation within the same entity frame. The type lives in internal/lowlevel: callers outside the generated package hold the returned value by inference (raw := b.Raw()) and chain its methods, but cannot name the type in their own signatures.

func (*WidgetEntityBuilder) Rollback ¶ added in v0.0.13

func (inst *WidgetEntityBuilder) Rollback() (err error)

Rollback abandons the open entity frame without committing it; already-buffered rows and the store remain usable.

func (*WidgetStore) Begin ¶ added in v0.0.13

func (inst *WidgetStore) Begin(id uint64, ts time.Time, env WidgetEnvelope) *WidgetEntityBuilder

Begin opens one entity with the envelope roles as typed arguments (Key, Order), a live lifecycle and the pass-through envelope.

func (*WidgetStore) Buffered ¶ added in v0.0.13

func (inst *WidgetStore) Buffered() int

Buffered reports the number of committed-but-unflushed rows.

func (*WidgetStore) Close ¶ added in v0.0.13

func (inst *WidgetStore) Close()

Close discards everything unflushed and releases the store's Arrow builder; the store must not be used afterwards. Required for a clean shutdown under tracking/checked allocators — the default Go allocator needs no Close.

func (*WidgetStore) Delete ¶ added in v0.0.13

func (inst *WidgetStore) Delete(id uint64, ts time.Time) (err error)

Delete appends a tombstone row for id (no components; lifecycle marks the deletion). The tombstone writes through to attached cache views like any commit — a versioned deletion, so GetLive reads the key as absent immediately.

func (*WidgetStore) DiscardPending ¶ added in v0.0.13

func (inst *WidgetStore) DiscardPending()

DiscardPending drops every committed-but-unflushed row: records retained by a failed Flush, rows still in the DML builder, and an open (uncommitted) entity frame. It gives a failed Flush "never happened" semantics — ClickHouse state is the truth afterwards. Ambient stamps are cleared with the frame they were pushed for — including any pushed through Raw() — so an abandoned builder cannot leak its stamps onto later entities.

func (*WidgetStore) EnsureTable ¶ added in v0.0.13

func (inst *WidgetStore) EnsureTable(ctx context.Context) (err error)

EnsureTable applies the composed CREATE TABLE (plus the DDLTail suffix, when configured). Idempotent (CREATE TABLE IF NOT EXISTS). The embedded script is issued one statement per Exec — the optional CREATE DATABASE, then the CREATE TABLE — because the ClickHouse HTTP interface rejects a multi-statement body; under a Table override the statements are re-pointed at the override (recordstore.ProvisioningStatements: header and database only, the column block stays byte-identical).

func (*WidgetStore) Flush ¶ added in v0.0.13

func (inst *WidgetStore) Flush(ctx context.Context) (n int, err error)

Flush drains the buffered rows to ClickHouse (Arrow IPC, ADR-0089 pivot). Rows are durable when Flush returns, engine permitting. On insert failure the transferred records are retained and the next Flush ships them — Flush is retryable; DiscardPending drops them instead. An open (uncommitted) entity frame makes Flush error.

func (*WidgetStore) GetLive ¶ added in v0.0.13

func (inst *WidgetStore) GetLive(ctx context.Context, key uint64) (ent *WidgetEntity, found bool, err error)

GetLive is Latest plus tombstone interpretation: newest row wins, a tombstone reads as absent — the state-view read (the cache view carries the cached twin).

func (*WidgetStore) Latest ¶ added in v0.0.13

func (inst *WidgetStore) Latest(ctx context.Context, key uint64) (ent *WidgetEntity, found bool, err error)

Latest returns the newest row for key, tombstone-blind (the raw row-level primitive — a deleted key still returns its tombstone row; GetLive is the interpreted state-view read). Reads see only flushed rows.

func (*WidgetStore) Replay ¶ added in v0.0.13

func (inst *WidgetStore) Replay(ctx context.Context, key uint64, fromOrder time.Time, opts recordstore.ReplayOpts) iter.Seq2[*WidgetEntity, error]

Replay iterates the rows for key with the order column >= fromOrder in ascending order — the event-replay primitive. A zero fromOrder replays everything (zero time.Time has no defined UnixNano; recordstore.SeqTs(0) is the equivalent explicit bound); opts.To bounds the replay exclusively ("state as of To") and opts.Limit caps the row count. The sequence is single-use; ctx must stay valid until iteration completes; the query may execute at call time or lazily during iteration (buffered in v1 — a streaming executor changes nothing visible); an error ends the sequence as a final (nil, err) pair. Reads see only flushed rows.

func (*WidgetStore) VerifySchema ¶ added in v0.0.13

func (inst *WidgetStore) VerifySchema(ctx context.Context) (err error)

VerifySchema compares the live table's columns — names and order — against the generated schema. EnsureTable alone cannot detect drift on an existing table (IF NOT EXISTS succeeds against any old shape), and the decode is positional, so drift fails late or, for same-typed column swaps, silently: run VerifySchema at startup after EnsureTable.

It checks the COLUMN contract only. The membership-id contract is not checked and cannot be from the schema alone: the ids live in the membership columns as ordinary values, and a FAT table legitimately carries other kinds' ids beside this store's. Rows written under a different id assignment therefore pass VerifySchema and then match nothing — every component decodes absent, with no error. Compare WidgetMembershipIds against the writer's assignment when pointing this store at rows it did not write.

What it describes is the reader's own projection — DESCRIBE over `SELECT *`, not over the table — because that is what the positional decode consumes. DESCRIBE TABLE lists columns SELECT * does not return (MATERIALIZED, ALIAS, EPHEMERAL), so a table legitimately carrying one beside the generated shape — a derived column added by ALTER after EnsureTable, which is how a store gets a skip index over a value its leeway attributes only encode — would fail a check whose contract still held. Describing the projection also follows the asterisk_include_* settings, which decide what SELECT * returns and which nothing here pins: under those, a derived column IS in the decode, and this notices where a column-kind filter would have blessed the mis-decode.