Documentation
¶
Overview ¶
Package kvcatalog is the POPULATION half of the framework KV bucket catalog (framework-bucket-catalog): the ONE literal table of every KV bucket whose write-ownership or retention the framework guarantees, and its acquisition. The mechanism half — the BucketSpec type and the Ensure/Open acquisition seam — lives in natsclient/kvspec.go, name-free. The bucket names are the graph package's Bucket* constants; this package holds the descriptors and the NATS edge, so the graph root imports no transport.
Boundary rule (so the catalog cannot grow by accretion): a bucket belongs here ONLY if the framework guarantees its write-ownership or retention. Application/product buckets (AGENT_LOOPS, personas, governance stores, workflow-type Lifecycle buckets, research-graph state, ...) are outside it by rule and keep plain CreateKeyValueBucket.
Every check the framework enforces from is a DERIVED view of this table: IsFrameworkOwnedBucket (the rule update_kv write guard) reads Write == WriteOwnerOnly; the pre-start legacy-drift backstop (EnsureCatalogRetentionClean) filters Retention.Kind == RetentionNoLifecycle. There is no parallel hand-maintained list to forget a member from. That no other non-test file names a catalog bucket in a string literal is review only in SemEngine.
Owner enforcement is call-site selection: owners call natsclient.EnsureFrameworkBucket with their descriptor, readers call natsclient.OpenFrameworkBucket. The framework does not verify caller identity at runtime; that boundary is review-enforced, deliberately.
Index ¶
- func EnsureCatalogBucket(ctx context.Context, client *natsclient.Client, name string) (jetstream.KeyValue, error)
- func EnsureCatalogRetentionClean(ctx context.Context, client *natsclient.Client, logger *slog.Logger) error
- func FrameworkOwnedWriteRefusal(bucket string) string
- func IsFrameworkOwnedBucket(bucket string) bool
- func IsKVTombstone(operation jetstream.KeyValueOp) bool
- func KVCatalog() []natsclient.BucketSpec
- func OwnerOf(bucket string) string
- func SpecFor(name string) (natsclient.BucketSpec, bool)
- type CatalogReader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureCatalogBucket ¶
func EnsureCatalogBucket(ctx context.Context, client *natsclient.Client, name string) (jetstream.KeyValue, error)
EnsureCatalogBucket resolves a catalog bucket by name and acquires it through the OWNER seam (natsclient.EnsureFrameworkBucket): create-or-open, reconcile to the declared policy, verify, or fail the caller's Start closed. Only a bucket's declared owner calls this; readers use OpenCatalogReader. A name outside the catalog is an invalid-config error naming it.
func EnsureCatalogRetentionClean ¶
func EnsureCatalogRetentionClean(ctx context.Context, client *natsclient.Client, logger *slog.Logger) error
EnsureCatalogRetentionClean is the PRE-START LEGACY-DRIFT BACKSTOP for the framework KV catalog's no-lifecycle buckets (ADR-068 D1). It has exactly ONE honest job: a catalog bucket unused by the current composition never has its acquisition seam called — e.g. an EMBEDDING_INDEX left behind by a prior semantic deploy when booting a statistical configuration — so one boot-time pass over the catalog strips prior-boot/out-of-band retention dirt (or fails boot closed) for those inactive buckets.
Everything else is the seam's job, not this pass's: every active component acquires its buckets through natsclient.EnsureFrameworkBucket inside its own Start — create-or-open, reconcile to the declared policy, verify, fail that Start closed — which covers prior-boot dirt AND this boot's create-races AND post-boot dynamic re-acquisition, at the moment of acquisition. There is no post-start sweep pass anymore; deleting it is safe precisely because its justified class (created-dirty during this boot) is reconciled at creation.
Scope: only descriptors declared no-lifecycle. A bounded-ttl bucket's TTL is its declared contract (the seam converges to it; this pass must not strip it) and an unmanaged bucket carries no framework retention guarantee.
Each bucket is bound READ-ONLY / MUST-EXIST (never created) / SKIP-IF-ABSENT: a guarded bucket that does not exist cannot carry a foreign TTL, and its true component creates it clean through the seam. The backstop therefore imposes no bucket-creation ordering and never forces a resourceless deploy to provision a bucket it does not use (feedback_unconditional_resource_wiring).
func FrameworkOwnedWriteRefusal ¶
FrameworkOwnedWriteRefusal explains why a generic KV writer may not write a catalogued bucket, and where the write does belong. It is the ONE home for that wording: the rule engine refuses at three points — load validation, action runtime, and writer acquisition — and three hand-copied sentences drift, as they did when all three told an operator to use "graph mutation APIs" for a bucket holding operational configuration no graph API can write.
The remedy is derived from the descriptor's class rather than a hand list, so a new catalog row gets the right one without anybody remembering to add it.
func IsFrameworkOwnedBucket ¶
IsFrameworkOwnedBucket reports whether a bucket's catalog descriptor declares owner-only writes, so a generic KV writer (rule update_kv) must not mutate it.
func IsKVTombstone ¶
func IsKVTombstone(operation jetstream.KeyValueOp) bool
IsKVTombstone reports whether an authoritative KV watch entry removes the current value. NATS emits both DEL and PURGE tombstones with empty payloads; neither is an entity document and both must drive identical cleanup paths.
func KVCatalog ¶
func KVCatalog() []natsclient.BucketSpec
KVCatalog returns the full descriptor table. The slice is rebuilt per call so no caller can mutate the catalog for another.
func OwnerOf ¶
OwnerOf returns the catalog Owner string for a bucket ("" when the bucket is not in the catalog), for rejection messages that should tell the operator who legitimately writes it.
func SpecFor ¶
func SpecFor(name string) (natsclient.BucketSpec, bool)
SpecFor resolves a bucket name to its catalog descriptor. The second return is false for a name outside the catalog — the F2 boot-failure signal for a configuration-supplied bucket name that resolves to nothing (an operator typo may not silently create a stray unguarded bucket). A member of a name family resolves to its family's row with Name set to the member's name, so acquisition creates the member and every owner-only guard refuses it.
Types ¶
type CatalogReader ¶
type CatalogReader interface {
Get(ctx context.Context, key string) (jetstream.KeyValueEntry, error)
Watch(ctx context.Context, keys string, opts ...jetstream.WatchOpt) (jetstream.KeyWatcher, error)
WatchAll(ctx context.Context, opts ...jetstream.WatchOpt) (jetstream.KeyWatcher, error)
Keys(ctx context.Context, opts ...jetstream.WatchOpt) ([]string, error)
ListKeys(ctx context.Context, opts ...jetstream.WatchOpt) (jetstream.KeyLister, error)
ListKeysFiltered(ctx context.Context, filters ...string) (jetstream.KeyLister, error)
Status(ctx context.Context) (jetstream.KeyValueStatus, error)
}
CatalogReader is the read-only capability returned by OpenCatalogReader. Its method set is the exact union consumed by current framework catalog readers. The underlying write-capable JetStream handle is never exposed.
func OpenCatalogReader ¶
func OpenCatalogReader(ctx context.Context, client *natsclient.Client, name string) (CatalogReader, error)
OpenCatalogReader resolves a catalog bucket by name and binds it must-exist through the READER seam (natsclient.OpenFrameworkBucket): it NEVER creates and never reconciles; an absent bucket yields a classified not-ready error naming the catalog owner. A name outside the catalog is an invalid-config error naming it.