sharedsection

func (*AssetCache[W]) AdvanceEpoch ¶

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

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

func (*AssetCache[W]) Get ¶

func (inst *AssetCache[W]) Get(key uint64) (ent *AssetEntity, 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 (*AssetCache[W]) GetFetch ¶

func (inst *AssetCache[W]) GetFetch(ctx context.Context, key uint64) (ent *AssetEntity, 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 (*AssetCache[W]) Invalidate ¶

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

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

func (*AssetCache[W]) InvalidateAll ¶

func (inst *AssetCache[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 (*AssetCache[W]) IterateReadyWorkItems ¶

func (inst *AssetCache[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 (*AssetCache[W]) IterateRestWorkItems ¶

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

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

func (*AssetCache[W]) MarkStale ¶

func (inst *AssetCache[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 (*AssetCache[W]) MarkStaleIfOlder ¶

func (inst *AssetCache[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 (*AssetCache[W]) WorkItem ¶

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

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

func (*AssetEntity) Archetype ¶

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

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

func (*AssetEntityBuilder) AddLabel ¶

func (inst *AssetEntityBuilder) AddLabel(row Label) *AssetEntityBuilder

AddLabel contributes the Label 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 (*AssetEntityBuilder) AddState ¶

func (inst *AssetEntityBuilder) AddState(row State) *AssetEntityBuilder

AddState contributes the State 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 (*AssetEntityBuilder) Commit ¶

func (inst *AssetEntityBuilder) 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 (*AssetEntityBuilder) Raw ¶

func (inst *AssetEntityBuilder) Raw() *lowlevel.InEntityAssetTable

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 (*AssetEntityBuilder) Rollback ¶

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

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

func (*AssetStore) Begin ¶

func (inst *AssetStore) Begin(id uint64, ts time.Time) *AssetEntityBuilder

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

func (*AssetStore) Buffered ¶

func (inst *AssetStore) Buffered() int

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

func (*AssetStore) Close ¶

func (inst *AssetStore) 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 (*AssetStore) DiscardPending ¶

func (inst *AssetStore) 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 (*AssetStore) EnsureTable ¶

func (inst *AssetStore) 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 (*AssetStore) Flush ¶

func (inst *AssetStore) 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 (*AssetStore) IngestLabel ¶

func (inst *AssetStore) IngestLabel(ts time.Time, rows []Label) (err error)

IngestLabel buffers one whole entity per row carrying only the Label 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 (*AssetStore) IngestState ¶

func (inst *AssetStore) IngestState(ts time.Time, rows []State) (err error)

IngestState buffers one whole entity per row carrying only the State 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 (*AssetStore) Latest ¶

func (inst *AssetStore) Latest(ctx context.Context, key uint64) (ent *AssetEntity, 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 (*AssetStore) Replay ¶

func (inst *AssetStore) Replay(ctx context.Context, key uint64, fromOrder time.Time, opts recordstore.ReplayOpts) iter.Seq2[*AssetEntity, 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 (*AssetStore) ScanLabel ¶

func (inst *AssetStore) ScanLabel(ctx context.Context, opts recordstore.ScanOpts) iter.Seq2[*AssetEntity, error]

ScanLabel iterates the entities whose rows carry a conforming Label 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 (*AssetStore) ScanState ¶

func (inst *AssetStore) ScanState(ctx context.Context, opts recordstore.ScanOpts) iter.Seq2[*AssetEntity, error]

ScanState iterates the entities whose rows carry a conforming State 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 (*AssetStore) VerifySchema ¶

func (inst *AssetStore) 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 AssetMembershipIds 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.