From e391e551501c68fadbed48fde1433fc99cd31971 Mon Sep 17 00:00:00 2001 From: Carl Niklas Rydberg Date: Sun, 21 Dec 2025 21:54:29 +0100 Subject: [PATCH] Added snapshot consistency guidance in the spec and clarified the intended use of snapshot views vs. direct store calls in the public header. --- include/amduat/tgk/store.h | 4 +++- tier1/tgk-store-1.md | 6 ++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/include/amduat/tgk/store.h b/include/amduat/tgk/store.h index 1a16f41..12ee84d 100644 --- a/include/amduat/tgk/store.h +++ b/include/amduat/tgk/store.h @@ -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, 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, amduat_tgk_store_snapshot_t *out_snapshot); void amduat_tgk_store_snapshot_free(amduat_tgk_store_snapshot_t *snapshot); diff --git a/tier1/tgk-store-1.md b/tier1/tgk-store-1.md index d7b80e8..559d464 100644 --- a/tier1/tgk-store-1.md +++ b/tier1/tgk-store-1.md @@ -990,6 +990,12 @@ Requirements: * 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). +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)