spec: /v1/identity/resolve (directory:read)

[yakimoto]

What

Adds GET /identity/resolve to the published machine contract — the fleet agent directory read pane that ships in wave-gateway PR #1170 (API-FIRST-MATRIX gap 2, identity-fabric E1; contract: claude-workstation governance/plans/fleet-epic-queue/QUEUE-V2.md row 6). Without this entry the route exists at runtime but is invisible to OpenAPI-generated clients and route-method discovery (qodo finding on #1170).

Contents

• Identity tag — fleet agent directory: resolve a WAVE agent id to its public channel map.
• identityResolve operation — agent query param (pattern ^[a-z0-9-]{1,64}$), optional org self-assertion (must equal the authenticated principal; mismatch → 400 ORG_MISMATCH). Responses: 200 (IdentityResolveResponse), 400 (MISSING_AGENT / BAD_AGENT / ORG_MISMATCH), 401/403 (Unauthorized/Forbidden refs), 404 (UNKNOWN_AGENT), 429 (RateLimitError ref).
• Schemas — IdentityResolveResponse = { agent, identity } with identity as a oneOf: AgentIdentity (email/key/org/channels) | TelephonyIdentity (org/channels/numbers/keys — the one documented variation, resolve.mjs parity). Both mark key/keys as Doppler key NAMES (^[A-Z0-9_]+$), never values — the directory carries no secret material.
• generated/api-types.d.ts regenerated (openapi-typescript@7.13.0) so the sdk-types drift gate stays green.
• CHANGELOG Unreleased entry.

Gateway-side posture (already in wave-gateway#1170)

Scope directory:read — separately grantable, DISTINCT from the compliance identity:read scope (which gates Stripe verification-session reads and is never in the #19 uniform customer grant). Nested-exact scope rule (/v1/identity/resolve only); errors use the gateway-wide { error: { code, message } } envelope, matching this spec's Error schema.

Gates

• redocly lint openapi.yaml — valid (warnings pre-existing).
• No breaking change (pure addition); oasdiff gate should read clean.

After merge: wave-gateway bumps vendor/api-spec/pin.json to the new SHA + regenerates src/openapi-spec.generated.ts (the pin-verified vendoring flow), closing the loop.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Note

Low Risk
Pure additive OpenAPI surface with no runtime logic changes; public-directory fields only and no secret material in schemas.

Overview
Documents GET /identity/resolve so OpenAPI clients and gateway route discovery match the runtime identity-fabric read pane (wave-gateway #1170).

Adds the Identity tag and identityResolve: required agent query (^[a-z0-9-]{1,64}$), optional org self-assertion (mismatch → ORG_MISMATCH). Success is IdentityResolveResponse, a oneOf discriminated on agent — default agents return AgentIdentity (email, Doppler key name, org, channels); telephony returns TelephonyIdentity (numbers, plural keys, no email). key/keys are names only, never secret values. Errors are typed for MISSING_AGENT, BAD_AGENT, ORG_MISMATCH, and UNKNOWN_AGENT. Auth failures use the shared Unauthorized/Forbidden refs; access is gated by directory:read (not compliance identity:read).

CHANGELOG Unreleased entry and generated/api-types.d.ts regenerated so the sdk-types drift gate stays green.

^{Reviewed by Cursor Bugbot for commit 4b75424. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_07afca06-a127-4883-85f8-ceda0fc03332)

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your current included review allowance is based on your included PR review attempts over the past 7 days.

Next review available in: 12 minutes

Limit details: You’ve used the included review currently available. Your 103 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c4b96e22-ceb8-453e-9bae-759a57dd5f9d

📥 Commits

Reviewing files that changed from the base of the PR and between 4468fda and 4b75424.

⛔ Files ignored due to path filters (1)

• generated/api-types.d.ts is excluded by !**/generated/**

📒 Files selected for processing (2)

• CHANGELOG.md
• openapi.yaml

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Publish identity resolve endpoint in OpenAPI contract

✨ Enhancement 📝 Documentation 🕐 20-40 Minutes

AI Description

• Publishes GET /identity/resolve for scoped fleet-directory lookups.
• Models agent and telephony directory entries without exposing secret values.
• Regenerates TypeScript API types and records the additive contract change.

Diagram

graph TD
  Spec["OpenAPI Contract"] --> Route["Identity Resolve"] --> Variant{"Identity Shape"} --> Agent["Agent Identity"]
  Variant --> Telephony["Telephony Identity"]
  Spec --> Generator["Type Generator"] --> Types["SDK Types"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Single normalized identity schema

• ➕ Simplifies generated client models
• ➕ Avoids union handling for consumers
• ➖ Requires many optional fields
• ➖ Permits invalid combinations not returned by the gateway
• ➖ Obscures the documented telephony variation

2. Separate telephony endpoint

• ➕ Provides one response shape per endpoint
• ➕ Allows independent evolution of telephony fields
• ➖ Expands the public API surface
• ➖ Forces clients to know an agent's identity kind before resolution
• ➖ Diverges from the existing gateway route

Recommendation: Keep the oneOf response matching the gateway runtime. It preserves one lookup route while giving generated clients precise agent and telephony models; a normalized optional-field schema would weaken validation, and separate endpoints would complicate discovery.

Files changed (3) +370 / -97

Enhancement (1) +125 / -0

openapi.yamlDefine the identity resolution API contract +125/-0

Define the identity resolution API contract

• Adds the Identity tag and 'GET /identity/resolve' operation with validated query parameters and documented success, validation, authorization, lookup, and rate-limit responses. Defines a required response envelope whose identity uses distinct agent and telephony schemas while constraining credential references to key names.

openapi.yaml

Documentation (1) +6 / -0

CHANGELOG.mdDocument fleet directory resolution contract +6/-0

Document fleet directory resolution contract

• Adds an Unreleased entry describing the identity resolution route, response variants, public-data boundary, and distinct 'directory:read' scope.

CHANGELOG.md

Other (1) +239 / -97

api-types.d.tsRegenerate identity and search API declarations +239/-97

Regenerate identity and search API declarations

• Adds typed path, operation, response, and schema declarations for 'identityResolve', 'AgentIdentity', and 'TelephonyIdentity'. Regeneration also synchronizes previously drifted search paths, operations, and models with the current OpenAPI source.

generated/api-types.d.ts

[gitar-bot]

Note

Automatic reviews are paused because your team has used its included automatic processing for this billing period (headroom scales with your seat count). You can still comment "Gitar review" to run one anytime, and automatic reviews resume on their own by September 1. Add seats for more headroom.
Learn more

Code Review ✅ Approved

Adds the GET /identity/resolve endpoint to the OpenAPI spec with corresponding IdentityResolveResponse schemas and regenerated TypeScript types. No issues found.

Options

Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Compact

gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📜 Skill insights (0)

1. Identity variant is uncorrelated ✓ Resolved 🐞 Bug ≡ Correctness ⭐ New

Description

IdentityResolveResponse permits a telephony identity for any agent and an agent identity for
telephony, despite documenting telephony as the sole special variant. Generated clients
consequently receive an independent string and union rather than a discriminated response type.

Code

openapi.yaml[R3701-3704]

+        identity:
+          oneOf:
+            - $ref: '#/components/schemas/AgentIdentity'
+            - $ref: '#/components/schemas/TelephonyIdentity'

Relevance

●●● Strong

PR #11 specifically accepted conditional validation for documented field dependencies, matching this
uncorrelated identity variant.

PR-#11

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The operation documentation assigns the plural numbers/keys shape specifically to the telephony
service, but the response schema declares an unconstrained agent string independently from the
identity oneOf. The generated declaration preserves that invalid cross-product instead of producing
correlated response branches.

openapi.yaml[1771-1773]
openapi.yaml[3696-3704]
generated/api-types.d.ts[1770-1775]
PR-#11

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Model `IdentityResolveResponse` so the outer `agent` value determines the permitted identity shape. The current independent properties accept invalid agent/identity pairings and generate a non-discriminated TypeScript type.

## Issue Context
The contract states that `telephony` is the documented service variation. This issue is distinct from allowing undeclared mixed fields: even objects containing only declared fields can currently be paired with the wrong agent.

## Fix Focus Areas
- openapi.yaml[3689-3704]
- generated/api-types.d.ts[1770-1775]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Search SDK endpoints removed ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Regenerating the SDK artifact removes the existing quickSearch, searchSuggest, and
semanticSearch paths and replaces their request/response types, even though this PR contains no
corresponding Search specification change. Existing TypeScript clients using those generated
operations will stop compiling despite the PR being presented as a purely additive identity change.

Code

generated/api-types.d.ts[545]

-    "/search/quick": {
+    "/search/index": {

Relevance

●● Moderate

No close endpoint-removal precedent; the reported SDK break is plausible, but the repository’s
search contract may intentionally have migrated.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The branch OpenAPI says the new Search surface replaces the archived quick, suggest, and semantic
endpoints, while the generated artifact now exposes only that replacement surface. The generation
script and CI gate establish that this checked-in declaration is a maintained SDK contract, so
applying these removals here changes what generated-type consumers can compile against.

openapi.yaml[1266-1348]
generated/api-types.d.ts[534-592]
package.json[7-10]
.github/workflows/foundation-gate.yml[62-84]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The generated SDK artifact contains unrelated, breaking Search API removals in a PR intended to add only identity resolution. Restore the existing Search declarations, or move the Search regeneration into an explicitly documented breaking contract change after reconciling the generated artifact with the source specification.

## Issue Context
The committed declaration is treated as an SDK contract and CI regenerates it from `openapi.yaml`. Removing existing paths and operation names breaks TypeScript consumers even though no Search source change appears in this PR.

## Fix Focus Areas
- generated/api-types.d.ts[534-592]
- generated/api-types.d.ts[3067-3259]
- openapi.yaml[1266-1348]
- .github/workflows/foundation-gate.yml[62-84]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Error codes remain unenforced ✓ Resolved 🐞 Bug ≡ Correctness ⭐ New

Description

The 400 and 404 responses promise specific stable codes but reference the generic Error schema,
where error.code accepts every string. Validators cannot reject undocumented codes and generated
clients cannot statically distinguish MISSING_AGENT, BAD_AGENT, ORG_MISMATCH, or
UNKNOWN_AGENT.

Code

openapi.yaml[R1794-1797]

+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'

Relevance

●●● Strong

Recent schema-contract fixes show the team accepts enforcing documented validation constraints and
generated-client guarantees.

PR-#11
PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added response descriptions name closed sets of machine-readable codes, but both responses
reference the unrestricted common envelope. Its code property is plain string in both OpenAPI and
the generated TypeScript artifact, so none of the newly promised codes are machine-enforced.

openapi.yaml[1792-1807]
openapi.yaml[1942-1959]
generated/api-types.d.ts[831-836]
generated/api-types.d.ts[3692-3709]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Add response-specific error schemas that constrain `error.code` to the codes documented for each identity resolve status while retaining the common WAVE error envelope.

## Issue Context
The 400 response should expose `MISSING_AGENT | BAD_AGENT | ORG_MISMATCH`, while the 404 response should expose `UNKNOWN_AGENT`. Regenerate the SDK declarations so these become literal types rather than plain strings.

## Fix Focus Areas
- openapi.yaml[1792-1807]
- openapi.yaml[1942-1959]
- generated/api-types.d.ts[3692-3709]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Identity variants allow mixed fields ✓ Resolved 🐞 Bug ≡ Correctness

Description

Both identity object schemas allow undeclared properties, so an agent identity can carry
telephony-only fields and a telephony identity can carry agent-only fields despite the documented
mutually exclusive shapes. This weakens response validation and can also make a mixed object satisfy
both branches, which is invalid under oneOf.

Code

openapi.yaml[R3701-3704]

+        identity:
+          oneOf:
+            - $ref: '#/components/schemas/AgentIdentity'
+            - $ref: '#/components/schemas/TelephonyIdentity'

Relevance

●●● Strong

Recent reviews accepted encoding documented response-shape guarantees directly in OpenAPI schemas.

PR-#9
PR-#11
PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The response uses oneOf, and its descriptions state that telephony has numbers/keys instead of
email/key. Neither referenced object schema closes additional properties, so that separation is not
represented by the schema itself.

openapi.yaml[3689-3704]
openapi.yaml[3706-3728]
openapi.yaml[3730-3752]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The two response variants do not prohibit undeclared properties, so their documented field separation is not enforced and sufficiently mixed objects can match both `oneOf` branches. Make the variants structurally exclusive, such as by setting `additionalProperties: false` on each identity schema or introducing an explicit discriminator.

## Issue Context
`AgentIdentity` and `TelephonyIdentity` have distinct required fields, but OpenAPI object schemas permit additional fields by default. Regenerate the SDK declaration after changing the source specification.

## Fix Focus Areas
- openapi.yaml[3689-3704]
- openapi.yaml[3706-3752]
- generated/api-types.d.ts[1770-1800]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. E.164 constraint is unenforced ✓ Resolved 🐞 Bug ≡ Correctness

Description

TelephonyIdentity.numbers is documented as containing E.164 numbers but accepts every string,
including malformed telephone numbers. Contract validators and generated clients therefore cannot
enforce the advertised wire format.

Code

openapi.yaml[R3745-3748]

+        numbers:
+          type: array
+          items: { type: string }
+          description: E.164 numbers

Relevance

●●● Strong

The team accepts strengthening OpenAPI schemas when documented response guarantees otherwise remain
unenforced.

PR-#9
PR-#11
PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The operation and schema describe the values as E.164, but the array item definition supplies only
type: string; consequently no syntax constraint is enforced. A prior accepted review likewise
required a documented structural guarantee to be encoded in the OpenAPI schema rather than prose
alone.

openapi.yaml[1771-1773]
openapi.yaml[3730-3748]
PR-#9

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The telephone-number array documents E.164 values but its item schema accepts arbitrary strings. Add an E.164-compatible constraint, such as a pattern requiring `+`, a nonzero country-code prefix, and at most 15 digits, then regenerate the SDK types.

## Issue Context
The operation and schema descriptions repeatedly promise E.164 numbers, making this part of the published contract rather than an incidental example.

## Fix Focus Areas
- openapi.yaml[3745-3748]
- generated/api-types.d.ts[1796-1799]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (1)

6. openapi.yaml exceeds 500 lines ✗ Dismissed 📘 Rule violation ⚙ Maintainability

Description

The touched API contract contains approximately 3,450 non-empty, non-comment lines, exceeding the
500-line limit. Its size increases maintenance and review complexity.

Code

openapi.yaml[R1756-1757]

+  /identity/resolve:
+    get:

Relevance

●● Moderate

The 500-line rule is explicit, but history only rejects it for generated declarations, not the
monolithic OpenAPI source.

PR-#49

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2497975 requires every touched source file to contain no more than 500 non-empty,
non-comment lines. The changed openapi.yaml contract has 3,752 total lines and approximately 3,450
qualifying lines.

Rule 2497975: Limit source file length to 500 lines of code
openapi.yaml[1-3752]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`openapi.yaml` exceeds the maximum of 500 non-empty, non-comment lines.

## Issue Context
The identity endpoint and schemas add to an API contract containing approximately 3,450 source lines. Modularize the contract while preserving the published API and generated output.

## Fix Focus Areas
- openapi.yaml[1756-1810]
- openapi.yaml[3689-3752]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. api-types.d.ts exceeds 500 lines 📘 Rule violation ⚙ Maintainability

Description

The touched TypeScript declaration source contains approximately 3,050 non-empty, non-comment lines,
exceeding the 500-line limit. Keeping the generated declarations monolithic violates the source-file
size requirement.

Code

generated/api-types.d.ts[796]

+    "/identity/resolve": {

Relevance

● Weak

Recent PR #49 rejected the same oversized generated declaration-file finding under this rule.

PR-#49

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2497975 applies the 500-line maximum to each touched source file. The changed
declaration file has 3,715 total lines and approximately 3,050 qualifying lines, even after
excluding blank and comment-only lines.

Rule 2497975: Limit source file length to 500 lines of code
generated/api-types.d.ts[1-3715]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`generated/api-types.d.ts` exceeds the maximum of 500 non-empty, non-comment lines.

## Issue Context
The generated declaration file contains approximately 3,050 source lines. Adjust generation or artifact organization so declarations are emitted into files within the limit without introducing SDK type drift.

## Fix Focus Areas
- generated/api-types.d.ts[796-826]
- generated/api-types.d.ts[3669-3714]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 1 rule

Review mode: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 11/18, lines 467/200; both must reach the floor). Router rationale: This public API contract change has multiple independent, easy-to-miss risks across auth/error semantics, mutually exclusive schemas, validation constraints, and an unrelated generated-SDK surface regression.

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 4b75424

Results up to commit 3a2781c ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (1) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Search SDK endpoints removed ✗ Dismissed 🐞 Bug ≡ Correctness

Description

Regenerating the SDK artifact removes the existing quickSearch, searchSuggest, and
semanticSearch paths and replaces their request/response types, even though this PR contains no
corresponding Search specification change. Existing TypeScript clients using those generated
operations will stop compiling despite the PR being presented as a purely additive identity change.

Code

generated/api-types.d.ts[545]

-    "/search/quick": {
+    "/search/index": {

Relevance

●● Moderate

No close endpoint-removal precedent; the reported SDK break is plausible, but the repository’s
search contract may intentionally have migrated.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The branch OpenAPI says the new Search surface replaces the archived quick, suggest, and semantic
endpoints, while the generated artifact now exposes only that replacement surface. The generation
script and CI gate establish that this checked-in declaration is a maintained SDK contract, so
applying these removals here changes what generated-type consumers can compile against.

openapi.yaml[1266-1348]
generated/api-types.d.ts[534-592]
package.json[7-10]
.github/workflows/foundation-gate.yml[62-84]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The generated SDK artifact contains unrelated, breaking Search API removals in a PR intended to add only identity resolution. Restore the existing Search declarations, or move the Search regeneration into an explicitly documented breaking contract change after reconciling the generated artifact with the source specification.

## Issue Context
The committed declaration is treated as an SDK contract and CI regenerates it from `openapi.yaml`. Removing existing paths and operation names breaks TypeScript consumers even though no Search source change appears in this PR.

## Fix Focus Areas
- generated/api-types.d.ts[534-592]
- generated/api-types.d.ts[3067-3259]
- openapi.yaml[1266-1348]
- .github/workflows/foundation-gate.yml[62-84]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Identity variants allow mixed fields ✓ Resolved 🐞 Bug ≡ Correctness

Description

Both identity object schemas allow undeclared properties, so an agent identity can carry
telephony-only fields and a telephony identity can carry agent-only fields despite the documented
mutually exclusive shapes. This weakens response validation and can also make a mixed object satisfy
both branches, which is invalid under oneOf.

Code

openapi.yaml[R3701-3704]

+        identity:
+          oneOf:
+            - $ref: '#/components/schemas/AgentIdentity'
+            - $ref: '#/components/schemas/TelephonyIdentity'

Relevance

●●● Strong

Recent reviews accepted encoding documented response-shape guarantees directly in OpenAPI schemas.

PR-#9
PR-#11
PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The response uses oneOf, and its descriptions state that telephony has numbers/keys instead of
email/key. Neither referenced object schema closes additional properties, so that separation is not
represented by the schema itself.

openapi.yaml[3689-3704]
openapi.yaml[3706-3728]
openapi.yaml[3730-3752]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The two response variants do not prohibit undeclared properties, so their documented field separation is not enforced and sufficiently mixed objects can match both `oneOf` branches. Make the variants structurally exclusive, such as by setting `additionalProperties: false` on each identity schema or introducing an explicit discriminator.

## Issue Context
`AgentIdentity` and `TelephonyIdentity` have distinct required fields, but OpenAPI object schemas permit additional fields by default. Regenerate the SDK declaration after changing the source specification.

## Fix Focus Areas
- openapi.yaml[3689-3704]
- openapi.yaml[3706-3752]
- generated/api-types.d.ts[1770-1800]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. E.164 constraint is unenforced ✓ Resolved 🐞 Bug ≡ Correctness

Description

TelephonyIdentity.numbers is documented as containing E.164 numbers but accepts every string,
including malformed telephone numbers. Contract validators and generated clients therefore cannot
enforce the advertised wire format.

Code

openapi.yaml[R3745-3748]

+        numbers:
+          type: array
+          items: { type: string }
+          description: E.164 numbers

Relevance

●●● Strong

The team accepts strengthening OpenAPI schemas when documented response guarantees otherwise remain
unenforced.

PR-#9
PR-#11
PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The operation and schema describe the values as E.164, but the array item definition supplies only
type: string; consequently no syntax constraint is enforced. A prior accepted review likewise
required a documented structural guarantee to be encoded in the OpenAPI schema rather than prose
alone.

openapi.yaml[1771-1773]
openapi.yaml[3730-3748]
PR-#9

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The telephone-number array documents E.164 values but its item schema accepts arbitrary strings. Add an E.164-compatible constraint, such as a pattern requiring `+`, a nonzero country-code prefix, and at most 15 digits, then regenerate the SDK types.

## Issue Context
The operation and schema descriptions repeatedly promise E.164 numbers, making this part of the published contract rather than an incidental example.

## Fix Focus Areas
- openapi.yaml[3745-3748]
- generated/api-types.d.ts[1796-1799]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. openapi.yaml exceeds 500 lines ✗ Dismissed 📘 Rule violation ⚙ Maintainability

Description

The touched API contract contains approximately 3,450 non-empty, non-comment lines, exceeding the
500-line limit. Its size increases maintenance and review complexity.

Code

openapi.yaml[R1756-1757]

+  /identity/resolve:
+    get:

Relevance

●● Moderate

The 500-line rule is explicit, but history only rejects it for generated declarations, not the
monolithic OpenAPI source.

PR-#49

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2497975 requires every touched source file to contain no more than 500 non-empty,
non-comment lines. The changed openapi.yaml contract has 3,752 total lines and approximately 3,450
qualifying lines.

Rule 2497975: Limit source file length to 500 lines of code
openapi.yaml[1-3752]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`openapi.yaml` exceeds the maximum of 500 non-empty, non-comment lines.

## Issue Context
The identity endpoint and schemas add to an API contract containing approximately 3,450 source lines. Modularize the contract while preserving the published API and generated output.

## Fix Focus Areas
- openapi.yaml[1756-1810]
- openapi.yaml[3689-3752]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. api-types.d.ts exceeds 500 lines 📘 Rule violation ⚙ Maintainability

Description

The touched TypeScript declaration source contains approximately 3,050 non-empty, non-comment lines,
exceeding the 500-line limit. Keeping the generated declarations monolithic violates the source-file
size requirement.

Code

generated/api-types.d.ts[796]

+    "/identity/resolve": {

Relevance

● Weak

Recent PR #49 rejected the same oversized generated declaration-file finding under this rule.

PR-#49

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2497975 applies the 500-line maximum to each touched source file. The changed
declaration file has 3,715 total lines and approximately 3,050 qualifying lines, even after
excluding blank and comment-only lines.

Rule 2497975: Limit source file length to 500 lines of code
generated/api-types.d.ts[1-3715]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`generated/api-types.d.ts` exceeds the maximum of 500 non-empty, non-comment lines.

## Issue Context
The generated declaration file contains approximately 3,050 source lines. Adjust generation or artifact organization so declarations are emitted into files within the limit without introducing SDK type drift.

## Fix Focus Areas
- generated/api-types.d.ts[796-826]
- generated/api-types.d.ts[3669-3714]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[cursor]

Risk: medium. Left a non-blocking comment and did not approve because Cursor Bugbot skipped after hitting a usage limit, so the required automated-review signal did not complete. Human review is needed; no reviewers were assigned (only the PR author is assignable).

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[macroscopeapp]

Approvability

Verdict: Would Approve

Macroscope's review found this PR approvable — Additive API specification change adding a new read-only endpoint (GET /identity/resolve) and associated schemas to the OpenAPI spec. No runtime code is modified - this is purely documentation of a new API surface. The author owns all changed files.

Not approved because:

• Credit balance exhausted. Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings. You can add or adjust custom eligibility rules. Learn more.}

[qodo-code-review]

Code review by qodo was updated up to the latest commit 3a2781c

[qodo-code-review]

Qodo Fixer

🍒 Ready to be cherry-picked — ✅ Merged (0) · ☑ Fixed (3)

🔗 Fix PR: #58

This fix PR was closed automatically. Its branch is preserved so you can cherry pick the changes into the original PR.

Prompt for coding agent

This is an automated fix prepared on a separate branch (#58). It is NOT applied to this PR.
To use it: review Fix PR #58 (https://github.com/wave-av/api-spec/pull/58), evaluate each change critically against your local context, and cherry-pick the changes that are correct into this branch. Do not accept them blindly.

Process — 3 fixed

• ☑ Fixed: Identity variant is uncorrelated
• ☑ Fixed: Identity variants allow mixed fields
• ☑ Fixed: E.164 constraint is unenforced
• ⏭ Skipped (3)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_a376e5ca-eea4-4bb6-9450-d2cae1014689)