Skip to main content

TRA-745 — BB44 F1+F2+F3 docs sweep + BACKLOG.md soft-delete fixture entry

Pure docs PR against trakrf/docs. No platform, no OpenAPI, no spec_refreshed_at.

Scope (4 edits across 3 files)​

F1 — is_active filter prose scope​

File: docs/api/resource-identifiers.md, section "Effective dating and is_active" (h2 at line 547).

Current shape: a single bullet list enumerates 5 surfaces that apply the currently-effective predicate, then a paragraph says "pass ?is_active=true (or false) to narrow further." Reads as if all 5 accept the filter — only /assets and /locations do.

Fix: split into two clearly labeled bullet lists.

  1. Keep the existing 5-surface list as "Endpoints that apply the currently-effective predicate by default" (no content change; clarifying prose lead-in).
  2. Add a second focused list "Endpoints that accept ?is_active= as a caller filter" with only GET /api/v1/assets and GET /api/v1/locations.
  3. Rewrite the "is_active is an independent filter dimension..." paragraph to scope the filter sentence to the two endpoints; keep the substring-search (?q=) sentence in place.

Don't restructure the section into h3 subsections — the existing h3 at line 572 (### /reports/asset-locations scopes...) is a different concept; nesting two new h3s above it would be heavier than the prose-with-two-lists shape.

F2 — /api/v1/assets/bulk classification​

File: docs/api/private-endpoints.md, Endpoint list table (line 21).

Add row at the end of the Internal block (before the /orgs/me Public row, which sits last):

| `/api/v1/assets/bulk` | POST | SPA asset bulk-CSV upload (`multipart/form-data`) | Internal | Internal |

The existing table has no content-type column; embed it parenthetically in "Used by" rather than refactor the table schema. The changelog.md:125 reference to /api/v1/assets/bulk stays — it's now consistent with the policy.

F3 — Already satisfied; verify and no-op​

File: docs/api/resource-identifiers.md line 134.

The "Always present" row already lists is_active:

| **Always present**    | `id`, `name`, `external_key`, `created_at`, `updated_at`, `is_active`, `valid_from` (and most scalars) | the value itself |

A prior PR landed this between BB44 cycle execution and ticket authorship. No edit needed. PR description will call out the verification.

BACKLOG.md — soft-deleted fixture accumulation​

File: tests/blackbox/BACKLOG.md.

Add a new section "Deliberate fixture states" between the existing "Internal-only deliberate states" and "Deferred work" sections. Single entry recording:

  • State: ~270 soft-deleted assets vs. 8 live in the test org at BB44; smaller-scale accumulation on locations.
  • Disposition: not a service finding — surface only as fixture-maintenance for the orchestrator.
  • Eventual fix (post-launch): build a deliberately scoped fixture (~hundreds of assets, 20–30 locations with 2-deep hierarchy) and reset the test org as part of provisioning.

Place this above "Deferred work" because it's a state observation with future fix, not a deferred work item with a trigger — distinct from the existing Deferred-work entries which have explicit revisit triggers tied to external events.

Adjacent-fix sweep​

Checked:

  • docs/api/pagination-filtering-sorting.md — filter table (lines 105–107) already correctly scopes is_active to /assets and /locations only. Boolean-filters prose (line 92–98) is generic and doesn't claim universal applicability. No edit needed.
  • docs/api/changelog.md:125 — references /api/v1/assets/bulk as historical change context. Becomes properly cross-referenceable once F2 lands the row in private-endpoints; no edit needed.
  • No other docs files reference /api/v1/assets/bulk or imply is_active is universally accepted.

Acceptance​

  • Single PR against main
  • pnpm build clean
  • pnpm typecheck clean if applicable
  • F1, F2, BACKLOG edits applied per shapes above; F3 verified as pre-existing
  • PR description names the four scope items, calls out F3 as already-satisfied, names the adjacent-fix sweep result