fix(api): stabilize report pagination + declare real { data, meta } envelope on v1 single/write endpoints (#811)

* fix(reports): stabilize fetchAllRows paging to stop doubled/dropped balances (#790, #791)

PostgREST `.range()` paging is only correct when the underlying query has a
stable TOTAL order. Several aggregating report queries (general ledger, trial
balance, grundbok, supplier/AR ledgers, etc.) paginated without `.order()`, so
on datasets larger than one 1000-row page Postgres could return rows in a
different order between requests — silently DUPLICATING or SKIPPING rows on a
page boundary and doubling or dropping financial totals.

- fetch-all.ts: document the ordering invariant and add an optional
  `dedupeBy` defense-in-depth that drops cross-page duplicates and warns when
  it fires (surfaces a missing `.order()` in logs instead of corrupting money).
- Add a stable `.order()` (line PK or account_number) to every paginated query
  in lib/reports/ and the account-balances route; pass `dedupeBy` on the
  money-aggregating line queries.
- Add fetch-all unit tests and update report test fixtures to carry row ids.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(api): declare the real { data, meta } envelope on v1 single/write/204 endpoints (#794)

The OpenAPI generator derives each endpoint's documented body purely from its
registered `response.success` Zod schema, and that schema is never validated at
runtime — so a route could advertise a shape its handler never sends. #802
fixed this for list endpoints; the same drift was latent on single-resource and
write endpoints, which declared the bare resource schema instead of the
`{ data, meta }` envelope the handlers actually return.

- registry.ts: extend `ResponseMetaSchema` with the optional `audit` block and
  `partial_expansions` list that writes/expansions emit; add the `NoBodyResponse`
  sentinel so 204 DELETE handlers document a bare 204 instead of a phantom 200.
- Wrap every single/write endpoint's `response.success` in `dataEnvelope(...)`
  (or `NoBodyResponse` for 204s) across the v1 routes.
- Add a response-envelope contract test that fails CI if any JSON endpoint
  forgets to wrap its schema, with binary downloads and 204s as the only
  exemptions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(reports): extend paging dedupeBy to rc-basis-gaps and opening-balances

Address PR review: these two money-aggregating line queries already had the
stable `.order('id')` (so paging was correct) but didn't carry `id` in the
select, so they couldn't use the `dedupeBy` defense-in-depth that general-ledger
and trial-balance got. Select `id` and pass `dedupeBy: r => r.id` so the whole
report layer applies the ordering invariant consistently.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/api/v1/registry.ts

@@ -21,15 +21,31 @@ import type { ZodTypeAny } from 'zod'
 import type { ApiKeyScope } from '@/lib/auth/api-keys'
 import { API_V1_VERSION } from './version'
 
+/**
+ * The audit block surfaced inline on write responses (see `AuditBlock` in
+ * `lib/api/v1/response.ts`) so an agent gets the voucher number / audit-trail
+ * URL without a second round-trip. Every field is optional.
+ */
+const ResponseAuditSchema = z.object({
+  voucher_number: z.string().optional(),
+  voucher_url: z.string().optional(),
+  audit_trail_url: z.string().optional(),
+  immutable_at: z.string().optional(),
+})
+
 /**
  * The `meta` block echoed in every v1 response envelope (see
  * `lib/api/v1/response.ts`). List endpoints additionally populate
- * `next_cursor`; it is absent on the final page.
+ * `next_cursor`; it is absent on the final page. Writes may surface an
+ * `audit` block, and soft-degraded `?expand=` responses a `partial_expansions`
+ * list — both optional, so reads and lists omit them.
  */
 export const ResponseMetaSchema = z.object({
   request_id: z.string(),
   api_version: z.string(),
   next_cursor: z.string().nullable().optional(),
+  audit: ResponseAuditSchema.optional(),
+  partial_expansions: z.array(z.string()).optional(),
 })
 
 /**
@@ -66,6 +82,18 @@ export function dataEnvelope<T extends ZodTypeAny>(data: T) {
   })
 }
 
+/**
+ * Sentinel `response.success` for endpoints that return 204 No Content with an
+ * empty body — e.g. DELETE handlers calling `noContent()`. The OpenAPI
+ * generator emits a bare `204` response (no schema) for these instead of a
+ * `200 { data, meta }`, and the envelope contract test exempts them.
+ *
+ * Identified by REFERENCE equality, so every 204 route MUST import this exact
+ * constant rather than declaring its own `z.object({})` — that is what lets the
+ * generator and the contract test recognise the "no body" intent.
+ */
+export const NoBodyResponse = z.object({})
+
 export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
 
 export type ActionRisk = 'low' | 'medium' | 'high'
@@ -327,6 +355,13 @@ export function generateOpenApiSpec(serverUrl: string): OpenApiSpec {
       ? { [def.response.contentType]: { schema: { type: 'string', format: 'binary' } } }
       : { 'application/json': { schema: zodToJsonSchema(def.response.success) } }
 
+    // 204 No Content endpoints (DELETEs returning noContent()) carry no body —
+    // emit a bare 204 instead of a 200 { data, meta } so the spec stops
+    // advertising a response shape these handlers never send.
+    const successResponse = def.response.success === NoBodyResponse
+      ? { '204': { description: 'No Content' } }
+      : { '200': { description: 'Success', content: successContent } }
+
     const operationDef: Record<string, unknown> = {
       operationId: def.operation,
       summary: def.summary,
@@ -343,10 +378,7 @@ export function generateOpenApiSpec(serverUrl: string): OpenApiSpec {
       'x-dry-run-supported': def.dryRunSupported,
       ...(def.scope ? { 'x-required-scope': def.scope } : {}),
       responses: {
-        '200': {
-          description: 'Success',
-          content: successContent,
-        },
+        ...successResponse,
         '400': { description: 'Validation error', $ref: '#/components/responses/Error' },
         '401': { description: 'Unauthorized', $ref: '#/components/responses/Error' },
         '403': { description: 'Insufficient scope', $ref: '#/components/responses/Error' },