feat(audit-policy): spacecat-api-service contract — policy CRUD + 501 scope stubs (SITES-47306)

[iuliag]

1. Abstract

Implements the /sites/{siteId}/audit-policy CRUD contract (E1/E2/E3) plus /sites/{siteId}/audit-scope/* OpenAPI 501 stubs (E4–E6) for the Audit Policy feature.

2. Reasoning

SITES-46352 pinned the customer-facing HTTP contract for Audit Policy — the surface the delegated UI builds against. SITES-47306 is the implementation ticket, building that surface over the B2 audit_policy table.

3. High-level overview of the changes

• GET /sites/{siteId}/audit-policy returns the current policy, or a synthetic version: 0 default when unset (never 404).
• PUT /sites/{siteId}/audit-policy full-replaces the policy via wrpc_upsert_audit_policy. The author attribute is derived server-side from the caller's IMS token — a client-supplied author field in the request body is ignored. Writes require reason and expectedVersion and are optimistic-locked: a stale expectedVersion returns 409 with the server's currentVersion.
• GET /sites/{siteId}/audit-policy/revisions returns policy history newest-first, cursor-paginated.
• GET /sites/{siteId}/audit-scope/{pages,summary,sections} return 501 for now; their real implementations land under separate tickets (B4 / B7) once those blocks are built.
• AuthZ: reads are gated on organization membership; writes additionally require ASO or LLMO product entitlement on the site.
• Routing is wired through the standard controller/route/FACS/required-capabilities layers so the new endpoints are reachable, access-controlled, and documented consistently with the rest of the API.
• Integration tests that exercise the real RPC (including the 409 conflict path) are written as a later, separate step — they depend on a companion data-service change (see Deployment & merge order) and are intentionally not part of this PR yet.

4. Required information

• Jira / issue: SITES-47306 (impl); SITES-46352 (spec)
• Spec: adobe/mysticat-architecture platform/design-audit-policy-api-contract.md (PR feat(trigger): no initial msg for backlink audit #184)
• Implementation plan: docs/plans/2026-06-29-sites-47306-api-contract-policy-crud.md (this branch)

5. Affected / used mysticat-workspace projects

• mysticat-data-service — contract/runtime dependency: this PR calls wrpc_upsert_audit_policy and reads audit_policy / audit_policy_revision, which are created by B2 (SITES-47301) and extended (p_expected_version, effective_at) by the companion PR on the matching feat/sites-47306-api-contract branch in that repo.

7. Test plan

• (a) No manual end-to-end run yet. The integration tests that exercise the real wrpc_upsert_audit_policy RPC and the 409 conflict path are added in a later commit, once the dependent data-service change is available.
• (b) Per-environment, once the data-service dependency lands: exercise GET/PUT /sites/{siteId}/audit-policy and confirm the synthetic-default, optimistic-lock, and entitlement-gate behaviour described above on eph/dev ahead of exposing the contract to the delegated UI on stage/prod.

8. Deployment & merge order

• mysticat-data-service PR on feat/sites-47306-api-contract — depends-on: provides p_expected_version and audit_policy_revision.effective_at that this PR's RPC call and conflict-mapping rely on.
• SITES-47301 (B2 impl) — depends-on: creates the base audit_policy table + RPC that the data-service PR extends.
• Order: (1) SITES-47301 merges → (2) the mysticat-data-service companion PR merges → (3) a new data-service image is cut and pinned in test/it/postgres/docker-compose.yml → (4) this PR's integration tests are added and enabled, then this PR merges.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 89.07104% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/controllers/audit-policy.js	84.96%	40 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

This PR will trigger a minor release when merged.

[iuliag]

@sandsinh, this is the PR implementing the API spec. It's still in progress, however if you can review it and let me know if you see something missing or adjusting depending on what the UI will need.