Catalog: the live resource model of a run #908

Epic: #444 — The resource model.

The catalog is the live model a run consults. ResourceCatalog (pkg/op/resource_catalog.go) is one per graph, cloned per run, and answers the run's questions while it runs: who exists, who made what, what state each entry is in, and which generation of a URI is current.

What it holds

• the append-only entries -- every generation of every resource, in append order (the field the code has called "the ledger"; that name belongs to the record, and the section The catalog and the ledger are not described: 4-resource-management.md has no section for what the catalog holds, what the ledger snapshot records, and when a digest is computed #906 writes retires the double use);
• the namespace -- URI to current id, per addressing regime;
• the per-run lifecycle state of each entry: Pending, Active, Gone;
• the producer stamp (the unit that made an entry, empty for a discovery) and the destroyer stamp;
• the id counter.

Its doors

Discover interns what a run found, with no producer. GetOrCreate interns what a run made, stamped with the caller. Shadow appends a new generation at an occupied URI. MarkGone retires one. Resolve, Lookup, Current, State, VerifyExistence answer questions. Clone gives a run its own copy. The catalog records faithfully which door a provider walks through; a provider that walks through the wrong one puts a false fact in the live model (devlore-cli#907).

Boundary with the ledger

The catalog is the live thing; the ledger (its sibling feature) is the record the run leaves of it. Snapshot is the seam: the catalog projects itself into the record once, at the end of Run. Nothing in the catalog reads the record except Rehydrate on resume.

Documents