GeezerVison

Two regressions shipped with the v2 API (#5273) where v2 diverged from the v1 path it replaced, plus the hardening that fell out of auditing the whole v2 surface for coverage gaps.

The two regressions

v2 logs bypassed secret redaction. getPublicLog and listPublicLogs called raw materializeExecutionData. Every other reader in the codebase — v1 list and detail, CSV export, fetch-log-detail, and both data-drain sources — calls materializeExecutionDataForDisplay, which applies projectExecutionDataForDisplay, the resolved-secret provenance redaction. Both v2 routes then serialize traceSpans and finalOutput straight onto the wire (app/api/v2/logs/[runId]/route.ts:46-47, app/api/v2/logs/route.ts:80-84), so unredacted resolved secrets could reach the public API.

The projection's own docstring says rows whose provenance is missing or malformed must yield "structural-only content rather than data that cannot be proven safe." v2 skipped that, and also omitted userId from the read context, which the projection consumes. Fixed by swapping to the display projection and threading the principal's subject user through.

Scope limiter: the routes cherry-pick only those two fields, so server-internal keys never reached the wire. Exposure was confined to trace spans and final output — which is also where resolved secrets are most likely to appear.

v2 file download served generation source. GET /api/v2/files/{fileId} used downloadWorkspaceFileStream, which streams file.key raw. AI-generated pdf/docx/pptx/xlsx store their generation source as the primary file, so as the comment at lib/uploads/utils/file-utils.server.ts:391 puts it, a raw download "yields source text under a .pdf name — the file the recipient cannot open." v1, the internal ZIP route, and /api/files/serve all compile first; v2 was the only surface that didn't.

Generated docs now resolve to their compiled artifact. Three things kept this from trading one bug for another:

• Ordinary uploads still stream. Gating on isRenderableDocumentName would have matched every .pdf and turned large uploaded files into full in-memory buffers on a public GET. The gate is the recorded generation-source content type, with the extension as a fallback only for legacy records that carry no type — the same predicate the sibling ZIP path already used, now extracted as needsRenderedArtifact.
• The resolve is capped at MAX_RENDERED_DOCUMENT_BYTES. A source is text and orders of magnitude smaller than what it renders to, so the record's declared size bounds nothing.
• A still-compiling artifact returns a retryable 409, not a 500, matching v1.

Also included

• PUT → PATCH on the two v2 verbs that had PATCH semantics. PUT /v2/knowledge/{id} and PUT /v2/tables/{tableId}/rows both take all-optional partial-update bodies; the row one is literally described in its contract as "a row-data patch applied to every matching row." The other three v2 PUTs are genuine replace/upsert and are unchanged.
• Closed the OpenAPI coverage blind spot. Contract discovery was a non-recursive read of the flat contracts/v2/ directory. The hole was two-dimensional: recursing alone wouldn't have caught the two undocumented upload routes, because their contracts live in contracts/upload-sessions.ts, outside v2/ entirely. The sweep is now recursive over the whole contracts tree (128 → 130 contracts), and those two data-plane routes are named in an explicit allowlist with reasons plus staleness guards.
• DocCompileUserError extracted to a leaf module so recognizing it no longer drags app/api/** and next/server into application modules.
• Corrected the pagination docstring in contracts/v2/shared.ts, which understated the paged list count by ten, and pinned the paged/full-set split in a test so it can't drift again.

Breaking change

The PUT → PATCH rename is breaking for external API-key clients, which will start getting 405. Called out deliberately rather than buried: the v2 surface is dark-launched behind the v2-api feature gate (when off, every route 404s as if it does not exist), it is three commits old, and no in-repo caller issues PUT to either path. If you'd rather keep PUT as a deprecated alias, say so and I'll add it back.

Honest caveats

• The new doc-not-ready module traces clean, but download-workspace-file.ts still reaches app/api/** transitively via workspace-file-manager. That edge predates this change; the change adds no new one.
• Generated docs can now trigger an inline sandbox compile on the download path. This matches what v1 and /api/files/serve already do, and the not-ready case returns 409 rather than blocking, but it is new behavior for v2.
• Per-row log projection adds real cost on GET /v2/logs?includeTraceSpans=true. v1 pays the identical cost on the same path today, so this is parity, not a new tax — but memoizing the decrypted registry per provenance envelope is a worthwhile follow-up.

Related, not included

#6540 is a third regression from #5273, same shape: a route moved from raw body to contract-parsed body and Zod silently stripped a private field the contract never declared. It is already open, green, and against staging, so it should land on its own rather than be duplicated here.

Worth adding to that PR: the KB-search break has a second, quieter victim. lib/guardrails/validate_hallucination.ts also queries that route and always builds the provenance metadata, but swallows the 400 into { context: [] } — so the hallucination guardrail evaluates claims against empty knowledge-base context and returns a confident wrong verdict, with nothing surfaced to the user.

I swept every other tool declaring modelInput and every route #5273 touched for the same bug class. Beyond those three, the count is zero.

Verification

bun run type-check, 1,850 tests across the affected suites, Biome, bun run check:openapi (7 specs / 128 operations / 130 contracts), bun run check:api-validation, and the client-boundary check all pass. Every new test was verified to fail against the unfixed code and pass after — including the one asserting an uploaded PDF still streams, which catches the memory regression the first draft of this fix would have introduced.