# Tooling API Contract Compatibility Report

Last updated: 2026-03-21

## Scope

This report covers the repository-implemented Tooling REST subset under [tests/contract/tooling_api](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api).

## Current Status

- `catalog.yaml` is endpoint-level and aligned to the routes mounted under `/services/data/v63.0/tooling`.
- A live smoke test now covers `GET /services/data/v63.0/tooling/query` in [get_query_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/query/get_query_test.go).
- Additional live smoke coverage now includes `GET /services/data/v63.0/tooling/sobjects/CustomApplication` and `GET /services/data/v63.0/tooling/sobjects/FlowDefinition`.
- The same smoke file also exercises `GET /services/data/v63.0/tooling/sobjects/Flow`.
- This run re-read the current [catalog.yaml](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/catalog.yaml), [tooling_api.postman_collection.json](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/tooling_api.postman_collection.json), existing `_test.go` files, and this report before editing.
- The current catalog now tracks `18` doc-backed Tooling endpoints: `7` are `coverage: covered`, `11` remain `coverage: todo`.
- New contract coverage now exists for `POST /services/data/v63.0/tooling/sobjects/QuickActionDefinition` in [post_quick_action_definition_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/quick_actions/post_quick_action_definition_test.go).
- Existing [get_custom_applications_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/custom_applications/get_custom_applications_test.go) was rewritten into official-doc AAA coverage with file-level doc headers, authenticated and anonymous cases, JSON content-type checks, and field assertions for documented `DeveloperName`, `Label`, `NavType`, and `UiType` semantics instead of the earlier local-backend-shaped lowercase payload checks.
- New live contract coverage now exists for `GET /services/data/v63.0/tooling/sobjects/FlowDefinition/{id}` in [get_flow_definition_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/flow_definitions/get_flow_definition_test.go) and `GET /services/data/v63.0/tooling/sobjects/Flow/{id}` in [get_flow_version_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/flow_definitions/get_flow_version_test.go).
- Existing [get_flow_definitions_test.go](/Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract/tooling_api/flow_definitions/get_flow_definitions_test.go) was also strengthened with doc headers, content-type checks, ID assertions, and key field assertions for both FlowDefinition and Flow list responses.
- The new tests follow the repo AAA/table-driven/testify contract style and assert key response fields from the official Tooling API object definitions plus anonymous auth rejection.
- This run also corrected four historical catalog rows that conflict with the official Tooling object method matrix:
  - removed `DELETE /tooling/sobjects/CustomApplication/{id}` because the CustomApplication object page lists only `Query, GET, POST, PATCH`
  - removed `DELETE /tooling/sobjects/FlowDefinition/{id}` because the FlowDefinition object page lists only `GET, HEAD, PATCH, POST`
  - removed `POST /tooling/sobjects/Flow/{id}/activate`
  - removed `POST /tooling/sobjects/Flow/{id}/deactivate`
- The Flow object page explicitly says to activate a flow by updating the `Status` field to `Active`, so those `activate` and `deactivate` route-shaped entries remain local implementation details, not official v63 contract endpoints.
- Official Salesforce Tooling documentation still conflicts with some historical expectations: the FlowDefinition object page says FlowDefinition records are implicitly created and can only be updated even though the same object reference lists `POST` among supported REST methods. The remaining FlowDefinition create coverage stays unresolved until that contradiction is closed with more precise official evidence.

## Verification

Compile check:

```bash
cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract
go test ./tooling_api/... -run '^$'
```

Live run:

```bash
cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract
CONTRACT_TARGET=sandbox go test ./tooling_api/... -count=1
```

Targeted live runs for this iteration:

```bash
cd /Users/liangzhiyuan/Projects/MetaDrivenPlatform4AI/tests/contract
CONTRACT_TARGET=local go test -p 1 ./tooling_api/custom_applications ./tooling_api/quick_actions -count=1 -v
CONTRACT_TARGET=sandbox go test -p 1 ./tooling_api/custom_applications ./tooling_api/quick_actions -count=1 -v
```

Results from this run:

- `GOCACHE=/tmp/gocache-testcases GOMODCACHE=/tmp/gomodcache-testcases go test -p 1 ./tooling_api/... -run '^$' -count=1` passed.
- Starting the local backend directly with `set -a; source .env.backup; set +a; ./backend/bin/server` also failed in this execution sandbox before the HTTP server came up, because its TiDB dependency at `127.0.0.1:4000` is unreachable here (`dial tcp 127.0.0.1:4000: connect: operation not permitted`).
- `GOCACHE=/tmp/gocache-testcases GOMODCACHE=/tmp/gomodcache-testcases CONTRACT_TARGET=local go test -p 1 ./tooling_api/custom_applications ./tooling_api/quick_actions -count=1 -v` failed before endpoint execution because neither token minting nor anonymous probes can reach `http://127.0.0.1:3001` in this sandbox (`dial tcp 127.0.0.1:3001: connect: operation not permitted`).
- `GOCACHE=/tmp/gocache-testcases GOMODCACHE=/tmp/gomodcache-testcases CONTRACT_TARGET=sandbox go test -p 1 ./tooling_api/custom_applications ./tooling_api/quick_actions -count=1 -v` failed before endpoint execution because the configured Salesforce My Domain host still does not resolve in this environment (`lookup pingcap--partialcop.sandbox.my.salesforce.com: no such host`).