Documentation
¶
Overview ¶
Package kvcatalog holds the framework KV bucket catalog: the ONE literal table of every KV bucket whose write-ownership or retention the framework guarantees. Around the table it offers:
- KVCatalog, a copy of the whole table, and SpecFor and OwnerOf, lookups by bucket name;
- EnsureCatalogBucket, which a bucket's owner calls to acquire it, and OpenCatalogReader, which readers call;
- EnsureCatalogRetentionClean, the pre-start retention backstop;
- IsFrameworkOwnedBucket and FrameworkOwnedWriteRefusal, the write-guard pair the rule engine's update_kv guard reads (the rule engine is ported in change 6).
The BucketSpec type and the Ensure/Open acquisition seam live in natsclient/kvspec.go and name no bucket. 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 is a DERIVED view of this table: IsFrameworkOwnedBucket 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 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 (SemStreams 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.
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 KVCatalog ¶
func KVCatalog() []natsclient.BucketSpec
KVCatalog returns every framework bucket descriptor. It is framework API for products (graph/README.md). The slice is a copy: a caller's edit changes neither the table SpecFor resolves from nor another caller's list.
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, which callers turn into a boot failure 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.
The runtime configuration row is the one family: its Name is a PREFIX, and every "<Name>_<suffix>" with a nonempty suffix is a member, named per deployment by config.BucketName (SemStreams #1188). The bare prefix is not a member.
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)
WatchFiltered(ctx context.Context, keys []string, opts ...jetstream.WatchOpt) (jetstream.KeyWatcher, 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. It has no Keys: list a catalog bucket with natsclient.FilteredKeys(ctx, reader, ">"), which fails a listing cut short instead of returning the keys so far (#533).
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.