From 48382a55ba183160aee93587ceef336184349d52 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 16:11:48 +0000 Subject: [PATCH 1/2] docs: ADR for optional centralized snapshot registry (#63) Capture auth, retention, content-addressed blobs, Git baseline relationship, and explicit non-goals for the core install. Link from the snapshot storage design spec. No registry service implemented. Co-authored-by: Abhinaysai Kamineni --- docs/adr-optional-snapshot-registry.md | 73 ++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/adr-optional-snapshot-registry.md diff --git a/docs/adr-optional-snapshot-registry.md b/docs/adr-optional-snapshot-registry.md new file mode 100644 index 0000000..0d2ce00 --- /dev/null +++ b/docs/adr-optional-snapshot-registry.md @@ -0,0 +1,73 @@ +# ADR: Optional centralized snapshot registry + +## Status + +Proposed (design only — **not** implemented in the core `tool-semantics` +package). Tracker: [#63](https://github.com/askmy-stack/tool-semantics/issues/63). + +## Context + +Teams often want **shared approved baselines** across multiple repositories +(platform MCP servers consumed by several product apps). Today the supported +paths are: + +1. **Git baselines** — reviewed JSON under `.tool-semantics/` (or similar) +2. **CI artifacts** — per-run uploads from the compare Action +3. **Provenance sidecars** — local metadata + content digest next to a snapshot + +A centralized registry (object storage + API) would help multi-repo orgs, but it +introduces auth, retention, tenancy, and operational ownership that do not +belong in the core library install. + +Related: [snapshot storage design](superpowers/specs/2026-08-13-snapshot-storage-design.md), +[live MCP capture ADR](adr-live-mcp-capture.md), [downstream](downstream.md). + +## Decision + +### Recommendation + +**Stay with Git baselines as the default and supported path.** Treat a +centralized registry as an **optional companion service** (separate package or +org-internal service), not a dependency of `pip install tool-semantics`. + +### Non-goals for the core library + +- No database, object-store client, or network registry API in the default + install +- No long-lived cloud credentials required for capture / compare / probe +- No multi-tenant ACL engine inside this repository +- No automatic promotion of unreviewed candidate snapshots to “approved” + +### If a companion registry is built later + +| Concern | Proposal | +| --- | --- | +| **Content addressing** | Store immutable snapshot blobs keyed by SHA-256 of canonical JSON (same digest as provenance sidecars). Names/tags are mutable pointers. | +| **Auth** | Short-lived OIDC / workload identity for CI; PAT or SSO for humans. Never embed tokens in snapshot JSON (continue redaction rules). | +| **Retention** | Default: keep content-addressed blobs ≥ 90 days; approved tags indefinitely until explicitly retired. Soft-delete with tombstones. | +| **Relationship to Git** | Registry is a **cache / distribution** layer. Git remains the review surface for policy-critical baselines. Provenance sidecars reference both `git_sha` (when known) and `content_digest`. | +| **API surface** | Minimal: `PUT blob`, `GET blob`, `PUT/GET ref` (e.g. `org/server@approved`). Compare continues to take local paths; a thin CLI helper may `pull` refs into `.tool-semantics/`. | +| **Compatibility** | Blobs are ordinary `InterfaceSnapshot` JSON — no proprietary envelope required beyond optional registry metadata outside the blob. | + +### Explicit out-of-scope for this ADR + +Implementing the registry service in-repo. File a follow-up issue only after +design approval and a clear owning team. + +## Consequences + +- Core Tool-Semantics stays offline-first and credential-light. +- Orgs that need shared baselines either (a) publish a small internal + baseline repo, or (b) build/host a companion registry that speaks content- + addressed snapshot blobs. +- Provenance digests already provide the hook for content addressing without + changing the snapshot schema. + +## Alternatives considered + +1. **Ship MinIO/S3 helpers in-core** — rejected; pulls cloud SDKs and secrets + into the default dependency graph. +2. **Only Git submodules / shared baseline repos** — accepted as the + recommended near-term pattern; no new service required. +3. **Embed a SQLite registry in the CLI** — rejected for multi-repo sharing; + fine as a local cache later if needed, but not a “centralized” registry. From 8859f42482993b73ac676e137306deedb913319c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 16 Sep 2026 16:12:00 +0000 Subject: [PATCH 2/2] docs: link snapshot storage design to registry ADR (#63) Co-authored-by: Abhinaysai Kamineni --- docs/superpowers/specs/2026-08-13-snapshot-storage-design.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/specs/2026-08-13-snapshot-storage-design.md b/docs/superpowers/specs/2026-08-13-snapshot-storage-design.md index 3e3667d..48813ea 100644 --- a/docs/superpowers/specs/2026-08-13-snapshot-storage-design.md +++ b/docs/superpowers/specs/2026-08-13-snapshot-storage-design.md @@ -19,8 +19,9 @@ The first implementation adds three complementary storage paths: Object storage and a centralized snapshot registry are explicitly out of scope for the core library. They require credentials, retention policy, access -control, and an API that this package does not own. A design-only follow-up is -tracked in [#63](https://github.com/askmy-stack/tool-semantics/issues/63). +control, and an API that this package does not own. Design-only follow-up: +[ADR: optional centralized snapshot registry](../../adr-optional-snapshot-registry.md) +([#63](https://github.com/askmy-stack/tool-semantics/issues/63)). Related docs: [adr-live-mcp-capture.md](../../adr-live-mcp-capture.md) (stdio + SSE capture), [downstream.md](../../downstream.md) (consumer handoff).