kvcatalog

package
v0.1.0-alpha.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 10 Imported by: 0

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 not in SemEngine yet).

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 enforced by review only.

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

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 decision 1). 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. No post-start sweep runs: its one class, a bucket 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

func FrameworkOwnedWriteRefusal(bucket string) string

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

func IsFrameworkOwnedBucket(bucket string) bool

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

func OwnerOf(bucket string) string

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. 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.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL