docs(core): document enableCap contract; remove console dev-features guard

[simeng-li]

Summary

Refs LOG-13434. Stacked on top of #8799.

This is the GA step for the audit-logs count-cap work. The runtime behavior shipped in #8796 (backend) and #8799 (console behind isDevFeaturesEnabled); this PR:

1. Removes the dev-features gate so the Console always passes ?enableCap=true to GET /api/logs in production.
2. Documents the enableCap query param, Total-Number-Is-Capped response header, and the capped-mode Link rel behavior in the OpenAPI specs.
3. Adds a patch-level changeset for the doc-only @logto/core change.

What changed

• packages/console/src/components/AuditLogTable/index.tsx — drops the isDevFeaturesEnabled import and the ...conditional(isDevFeaturesEnabled && { enableCap: 'true' }) spread. The URL builder now always includes enableCap: 'true'.
• packages/core/src/routes/log.openapi.json — /api/logs: adds the enableCap query parameter, documents Total-Number, Total-Number-Is-Capped, and Link response headers, and adds a "Pagination on large result sets" subsection to the endpoint description.
• packages/core/src/routes/hooks.openapi.json — /api/hooks/{id}/recent-logs: same set of doc additions, with a one-liner noting that this endpoint is already scoped to one hook over the last 24h so the cap rarely triggers in practice.
• .changeset/logs-enable-cap-docs.md — @logto/core: patch noting the OpenAPI updates.

Backward compatibility

• API runtime behavior: unchanged (the enableCap semantics shipped in feat(core): add enableCap query param to bound countLogs scan #8796).
• Default GET /api/logs (no enableCap) still returns the exact count. Existing third-party clients are unaffected.
• Console Audit Logs page: production users with tenants > 10,000 matching logs now get the capped UI (Prev/Next only) instead of hitting statement_timeout. Smaller tenants see no visible change.

Reviewer notes

• The Total-Number-Is-Capped header schema is { "type": "string", "enum": ["true"] } — the header is only present when the count is capped, and its value is always the literal string "true". Absent otherwise.
• This PR is stacked on feat(console): adopt enableCap=true on audit logs behind dev-features #8799 (Console) → feat(core): add enableCap query param to bound countLogs scan #8796 (Backend). PR base will retarget to master once those merge.

Testing

Tested locally

Checklist

• .changeset
• unit tests
• integration tests
• necessary TSDoc comments

[github-actions]

COMPARE TO master

Total Size Diff 📈 +3.96 KB

Diff by File

Name	Diff
.changeset/logs-enable-cap-docs.md	📈 +360 Bytes
packages/console/src/components/AuditLogTable/index.tsx	📈 +97 Bytes
packages/core/src/routes/hooks.openapi.json	📈 +1.46 KB
packages/core/src/routes/log.openapi.json	📈 +2.24 KB

[Copilot]

Pull request overview

This PR finalizes the GA rollout for capped-count pagination on large audit-log datasets by (1) having Console always opt into enableCap=true for /api/logs, and (2) documenting the enableCap contract plus capped-mode headers/Link behavior in the core OpenAPI specs, with an accompanying changeset.

Changes:

• Console Audit Logs now always includes enableCap=true when fetching /api/logs.
• OpenAPI specs document enableCap, Total-Number-Is-Capped, and capped-mode pagination Link semantics for /api/logs and /api/hooks/{id}/recent-logs.
• Adds a changeset entry for the release note/version bump.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
packages/core/src/routes/log.openapi.json	Documents enableCap and capped pagination headers/Link behavior for /api/logs.
packages/core/src/routes/hooks.openapi.json	Mirrors the capped pagination documentation for hook recent logs.
packages/console/src/components/AuditLogTable/index.tsx	Removes dev-features gating so enableCap=true is always sent.
.changeset/logs-enable-cap-docs.md	Adds a changeset entry describing the rollout.

Comments suppressed due to low confidence (3)

packages/core/src/routes/log.openapi.json:33

• enableCap description mixes the 10,000 threshold with the 10001 saturation sentinel, which may confuse consumers about what value to expect in Total-Number. Suggest clarifying that the cap threshold is 10,000 matching rows, and when exceeded the server returns Total-Number=10001 as the sentinel and emits Total-Number-Is-Capped: true.

            "name": "enableCap",
            "in": "query",
            "description": "When `true`, the underlying `count(*)` query short-circuits at 10,000 rows to avoid `statement_timeout` on tenants with very large log volumes. `Total-Number` then saturates at `10001` and `Total-Number-Is-Capped: true` is emitted; the `Link` header omits `rel=\"last\"` and `rel=\"next\"` because the real total is unknown. Default `false`; recommended `true` for any client whose tenant volume may exceed 10,000 matching logs."
          }

packages/core/src/routes/log.openapi.json:45

• The Total-Number header description implies counts are exact only when enableCap=false, but enableCap=true still returns an exact count when it does not hit the cap. Also, the “lower-bounded by 10,000” / “treat as ≥ 10,000” wording doesn’t match the actual sentinel value 10001 used when capped. Please update these descriptions to key off presence of Total-Number-Is-Capped and reference 10001 consistently.

              "Total-Number": {
                "description": "Exact match count when `enableCap=false`; lower-bounded by 10,000 when `enableCap=true` and the cap is hit. Inspect `Total-Number-Is-Capped` to distinguish.",
                "schema": { "type": "integer" }
              },
              "Total-Number-Is-Capped": {
                "description": "Present and set to `true` only when `enableCap=true` and the count saturated at the cap. Consumers should treat `Total-Number` as `≥ 10,000` when this header is present.",
                "schema": { "type": "string", "enum": ["true"] }

packages/core/src/routes/hooks.openapi.json:154

• Similar to /api/logs: Total-Number is still exact when enableCap=true and the cap is not hit, so the current header description is misleading. Also, “lower-bounded by 10,000” doesn’t match the 10001 sentinel used when capped. Recommend describing Total-Number as exact unless Total-Number-Is-Capped is present, and referencing 10001 consistently for the capped sentinel value.

              "Total-Number": {
                "description": "Exact match count when `enableCap=false`; lower-bounded by 10,000 when `enableCap=true` and the cap is hit.",
                "schema": { "type": "integer" }
              },
              "Total-Number-Is-Capped": {
                "description": "Present and set to `true` only when `enableCap=true` and the count saturated at the cap.",
                "schema": { "type": "string", "enum": ["true"] }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.