niklas/amduat
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Added snapshot consistency guidance in the spec and clarified the intended use of snapshot views vs. direct store calls in the public header.

Browse source
This commit is contained in:
Carl Niklas Rydberg 2025-12-21 21:54:29 +01:00
parent a945a117f6
commit e391e55150
2 changed files with 9 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
include/amduat/tgk/store.h
View file

@ -146,7 +146,9 @@ bool amduat_tgk_store_get_config(amduat_tgk_store_t *store,
bool amduat_tgk_store_snapshot_id(amduat_tgk_store_t *store, bool amduat_tgk_store_snapshot_id(amduat_tgk_store_t *store,
amduat_tgk_snapshot_id_t *out_id); amduat_tgk_snapshot_id_t *out_id);
/* Snapshot views are read-only; release with amduat_tgk_store_snapshot_free. */ /* Snapshot views pin a consistent graph snapshot for multi-call workflows.
* Direct store calls may observe a moving snapshot; use snapshot views when
* you need stable pagination or cross-call consistency. */
bool amduat_tgk_store_snapshot(amduat_tgk_store_t *store, bool amduat_tgk_store_snapshot(amduat_tgk_store_t *store,
amduat_tgk_store_snapshot_t *out_snapshot); amduat_tgk_store_snapshot_t *out_snapshot);
void amduat_tgk_store_snapshot_free(amduat_tgk_store_snapshot_t *snapshot); void amduat_tgk_store_snapshot_free(amduat_tgk_store_snapshot_t *snapshot);

6
tier1/tgk-store-1.md
View file

@ -990,6 +990,12 @@ Requirements:
* Each individual invocation of a graph operation MUST be interpreted with respect to some well-defined snapshot. * Each individual invocation of a graph operation MUST be interpreted with respect to some well-defined snapshot.
* Implementations MAY use different snapshots for different operations, but SHOULD document their consistency model (e.g. “read-your-writes” guarantees if combined with local Artifact injection). * Implementations MAY use different snapshots for different operations, but SHOULD document their consistency model (e.g. “read-your-writes” guarantees if combined with local Artifact injection).
Consistency model guidance:
* If a GraphStoreInstance represents a moving snapshot, back-to-back calls are allowed to observe different snapshots unless the implementation documents stronger guarantees.
* If an API exposes explicit snapshot views (i.e., a GraphStoreSnapshot handle), all graph operations performed through that view MUST be evaluated against the same snapshot and MUST NOT reflect later ingests/removals.
* Clients that need stable pagination, cross-operator comparisons, or multi-call invariants SHOULD use snapshot views or versioned endpoints rather than relying on repeated calls against a moving instance.
--- ---
## 8. Interaction with Other Layers (Informative) ## 8. Interaction with Other Layers (Informative)