Ship an authoritative embedded tool Catalog distilled from the SDK's own spec

[jeremy]

What

Ships an authoritative, embedded tool Catalog in the Go module — the
operation-shaped sibling of the existing url-routes.json embed. Downstream
consumers generate their tool catalog directly from the pinned SDK dependency
instead of vendoring openapi.json + behavior-model.json and re-joining them.

scripts/gen-catalog distills one self-contained go/pkg/basecamp/catalog/catalog.json
by joining, at the source:

• openapi.json → operationId, tag, HTTP method + path, description, path/query
  params, request-body JSON schema (component $refs inlined, x-go-* codegen
  noise stripped)
• behavior-model.json → per-operation readonly / idempotent / retry /
  pagination / write traits

Result: 396 KB vs the 1.1 MB raw openapi.json, self-contained (0 residual
$refs), 265 operations across 27 tags.

Public API (github.com/basecamp/basecamp-sdk/go/pkg/basecamp/catalog)

func Load() (*Catalog, error)        // parses the embedded catalog once, cached & shared
func Operations() ([]*Operation, error)

type Catalog struct {
    Schema, Version, ModelVersion string
    Generated  bool
    Operations []*Operation          // sorted by ID
}
func (c *Catalog) Operation(id string) (*Operation, bool)
func (c *Catalog) ByTag() map[string][]*Operation

type Operation struct {
    ID          string          // operationId, e.g. "CreateTodo"
    Tag         string          // single OpenAPI tag = domain
    Method      string          // "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
    Path        string          // "/{accountId}/buckets/{bucketId}/todos.json"
    Doc         string
    ReadOnly    bool
    Idempotent  bool
    Destructive *bool           // tri-state; nil = model does not declare it (today)
    Retry       *Retry
    Pagination  *Pagination
    Write       *WriteSemantics
    Params      []Param         // schema $refs inlined
    Body        map[string]any  // request-body JSON schema, $refs inlined; nil if none/non-JSON
    BodyMediaType string         // e.g. "multipart/form-data" for the 3 binary uploads
    BodyRequired  bool
}
func (o *Operation) Paginated() bool
func (o *Operation) IsDestructive() bool

This is a strict superset of what basecamp-mcp-server's domains.json needs per
operation, so the cutover is a mechanical field map. Product-specific concerns stay
with the consumer: tool prefix, tag→domain grouping, and the action-name spelling
(snake_case(Operation.ID)).

The design deliberately prefers a distilled artifact over embedding the raw
1.1 MB openapi.json: smaller, focused, stable, and self-contained (no components
section needed at read time). It follows the repo's existing url-routes.json
precedent — a distilled openapi.json join embedded beside the code that reads it.

Generated, not hand-maintained + drift gate

• make catalog regenerates the artifact (also wired into make generate after url-routes).
• make catalog-check runs the generator's unit tests, regenerates to a temp file,
  and fails unless the committed catalog.json is byte-identical. Wired into
  check-targets and its own CI step in the test-go job — because make check
  membership is not enforcement in this repo (no CI job runs the full make check),
  matching the url-routes-check / behavior-model-check posture.
• The join is strict both ways (every operation in both files, exactly one tag),
  mirroring the toolkit loader's contract so a torn regeneration fails loudly.

scripts/gen-catalog is a stdlib-only module in go.work (like
scripts/check-wrapper-drift), so go run needs no network.

The destructive trait gap (important)

behavior-model.json carries no destructive trait today — it has only
readonly, idempotent, pagination, retry, write. The Catalog carries
Destructive *bool sourced only from that (absent) trait, so it is nil on
every operation today and a consumer keeps bridging from the action name
(mcp/catalog.BridgeDestructive). The loader surfaces the real trait the moment the
model grows one, retiring the bridge.

It is deliberately not derived from the HTTP method. Empirically, neither method
nor name is authoritative here:

• 9 DELETE-method operations are reversible toggles, not destructive:
  UncompleteTodo, UnpinMessage, UnspotlightRecording, DeprioritizeAssignment,
  DisableTool, DisableOutOfOffice, DisableProjectClients, DisableCardColumnOnHold,
  ResumeQuestion. "DELETE == destructive" would misclassify all nine.
• One genuinely destructive operation, TrashRecording, is a PUT — a method rule
  misses it.

So destructive is a curated semantic judgment that belongs in the Smithy model,
not a derived rule. Smallest upstream fix (a focused follow-up, kept out of this PR
to stay additive and clear of in-flight spec work):

1. Add a marker trait basecampDestructive to spec/basecamp-traits.smithy.
2. Apply it to the ~20–30 genuinely-destructive operations in spec/basecamp.smithy
   (the semantic judgment — trash/delete/purge/archive that lose or hide data, not
   reversible toggles).
3. One line in scripts/generate-behavior-model:
   destructive: (if has_trait("basecamp.traits#basecampDestructive") then true else null end).

Then make behavior-model + make catalog flow the trait through with zero code
change here — the plumbing already reads it — and basecamp-mcp-server's
BridgeDestructive heuristic and its tripwire test retire.

Coordination

Built on origin/main. Additive to the generate pipeline; does not touch
scripts/check-required-tags.rb, spec/overlays/tags.smithy, or the recordings
retag (in flight on sdk/tag-events-recordings, #922). Once #922 merges, this
catalog should be regenerated (make catalog) so it reflects the corrected
Recordings/EventFeed tags — and consumers get the corrected tags for free from the
pinned dependency, no consumer change needed.

Includes all 265 operations, including the 3 binary-upload operations
(CreateAttachment, CreateCampfireUpload, UpdateAccountLogo) flagged via
BodyMediaType (they carry no JSON body). A consumer that wants only JSON-body/bodyless
operations filters BodyMediaType == "".

Verification

• go build ./... (go module), go vet ./..., gofmt clean
• go test ./pkg/basecamp/catalog/ and go test ./scripts/gen-catalog/ pass
• make catalog-check green; regeneration is byte-identical; drift gate verified
  to fail on a mutated artifact
• No existing exports touched; new package only

---

Summary by cubic

Ships an authoritative, embedded tool Catalog in the Go module so downstream consumers get all operations and traits from one self-contained file instead of vendoring and re-joining openapi.json and behavior-model.json.

• Adds go/pkg/basecamp/catalog with a typed loader (Load, Operations) and a Catalog/Operation model covering method, path, tags, readonly/idempotent traits, retry, pagination, write semantics, params, and body schemas with $refs inlined.
• Adds scripts/gen-catalog, a stdlib-only generator wired into go.work, that distills a 396 KB catalog.json (265 operations, 27 tags) from the two model files.
• Adds make catalog and make catalog-check; the check fails unless the committed artifact is byte-identical to a fresh generation and is wired into check-targets plus a dedicated CI step.

Behavior notes

• The join is strict both ways: any operation missing from either file, carrying zero/multiple/blank tags, or on a verb outside the generated GET/PUT/POST/DELETE/PATCH set aborts generation (non-generated verbs reference Generators iterate a five-verb list, so an operation on any other HTTP method is silently dropped from every SDK #925 and are registered in spec/tracking-issues.yml).
• The catalog is framed as the tag-based operation view, not a claim about any per-language SDK's internal service grouping.
• Operation.Destructive is nil until the behavior model declares the trait; it is not derived from the HTTP method because nine DELETE operations are reversible toggles and one destructive operation is a PUT, so consumers keep bridging from action names until then.

^{Written for commit 5ec145a. Summary will update on new commits.}

---

Update: catalog framed as the tag view, generation-time invariants hardened

Per review from the #922/#925 tag-pipeline owner:

• This catalog is the TAG-BASED operation view (what the mcp-server domain gateway consumes), not a claim about any SDK's internal service grouping — per-language SDKs derive services from their own split tables, and Rust (Let the Recordings tag reach the Rust generator #928) consults names.toml overrides before the tag. Package/type docs updated to say so plainly.
• One-tag-per-operation is enforced at GENERATION time, not trusted to CI: the require-tags gate (Spec Gates) is not in main's required contexts, so it is loud, not enforced. gen-catalog refuses to emit from a document with any ≠1-tag operation.
• Tag values are asserted, not just presence: empty/blank/whitespace tags (which have silently split SDKs) are rejected with a clear error.
• The catalog describes the GENERATED surface (Generators iterate a five-verb list, so an operation on any other HTTP method is silently dropped from every SDK #925): every SDK generator iterates only get/put/post/delete/patch, but Smithy @http.method is free-form, so openapi.json can carry HEAD/OPTIONS/TRACE ops no client exposes. gen-catalog walks each path item by exclusion (skipping $ref/summary/description/servers/parameters/x-*, the same fail-closed shape as Tag the recordings operations as their own domain, and require a tag on every operation #922's gate) and fails loud, naming basecamp-sdk#925, on any operation slot whose verb is outside the generated set — rather than emitting a phantom op that would break the downstream cutover.
  • No new bare verb literal. The five-verb list is already copied across the six per-language generators and generate-url-routes; adding a seventh bare copy would make Generators iterate a five-verb list, so an operation on any other HTTP method is silently dropped from every SDK #925 a seven-place fix. No shared source or Go constant exists to derive/import from, so the restated set carries a canonical tracked in #925 claim and a registered row in spec/tracking-issues.yml — the known-defect gate fails when Generators iterate a five-verb list, so an operation on any other HTTP method is silently dropped from every SDK #925 closes, dragging this copy back into view.
  • Found today: zero non-generated-verb ops and zero blank tags in the current spec, so catalog.json is unchanged (byte-identical) — the guards are inert but in place.

New generator tests cover each invariant: non-generated-verb rejection (#925), blank/multi/zero-tag rejection, and structural-path-key exclusion.

Inherited CI red (not this change): main is red at ebe5fd5 on Known-defect tracking issues are open because #922 added a tracked in #925 comment to scripts/check-required-tags.rb without registering its row; #927 is the one-row fix. Every open PR inherits it. This PR's own #925 registry row is consistent (registered count = swept count = 1).

[github-actions]

Sensitive Change Detection (shadow mode)

This PR modifies control-plane files:

• .github/workflows/test.yml

Shadow mode — this check is informational only. When activated, changes to these paths will require approval from a maintainer.

[Copilot]

🟡 Changes recommended

The generator accepts blank tags, allowing operations to be emitted without a usable domain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a generated, embedded Go catalog combining OpenAPI operations with behavioral metadata.

Changes:

• Adds the catalog generator, artifact, loader, and tests.
• Integrates generation and drift checks into Make and CI.
• Exposes typed operation lookup and grouping APIs.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File summaries

File	Description
scripts/gen-catalog/main.go	Generates the catalog from source artifacts.
scripts/gen-catalog/main_test.go	Tests joins, references, and invariants.
scripts/gen-catalog/go.mod	Defines the generator module.
go/pkg/basecamp/catalog/catalog.go	Provides the public catalog API.
go/pkg/basecamp/catalog/catalog_test.go	Tests loading and catalog integrity.
go/pkg/basecamp/catalog/catalog.json	Contains the generated embedded catalog.
Makefile	Adds generation and drift-check targets.
go.work	Registers the generator module.
.github/workflows/test.yml	Enforces catalog freshness in CI.

Review details

• Files reviewed: 8/9 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aeb6f28528

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-18T07:44:35.548708Z	5ec145a	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ec145aff3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Serialize catalog generation after the behavior model

When make -j generate follows a Smithy change that affects behavior traits, this sub-make may schedule catalog concurrently with behavior-model; the catalog generator can therefore read the previous behavior-model.json before the atomic replacement completes and leave catalog.json stale, despite the surrounding comment promising ordered phases. Put catalog in a subsequent sub-make or add an explicit dependency so it cannot start until behavior-model finishes.

AGENTS.md reference: AGENTS.md:L123-L132

Useful? React with 👍 / 👎.