# Console Search & Downloads · Draft v0.2

Scope: unblock WEB-CONSOLE-23-004/005 by defining deterministic ranking, caching rules, and the download manifest structure (including signed metadata option) for console search and offline bundle downloads. Final guild sign-off still required.

## 1) Deterministic search ranking
- Primary sort: `severity (desc)` → `exploitScore (desc)` → `reachability (reachable > unknown > unreachable)` → `policyBadge (fail > warn > pass > waived)` → `vexState (under_investigation > fixed > not_affected > unknown)` → `findingId (asc)`.
- Secondary tie-breakers (when above fields absent): `advisoryId (asc)` then `product (asc)`.
- All pages are pre-sorted server-side; clients MUST NOT re-order.

## 2) Caching + freshness
- Response headers: `Cache-Control: public, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
- `ETag` is a stable SHA-256 over the sorted payload; clients send `If-None-Match` for revalidation.
- `Last-Modified` reflects the newest `updatedAt` in the result set.
- Retry/backoff guidance: honor `Retry-After` when present; default client backoff `1s,2s,4s,8s` capped at 30s.
- Deterministic page cursors: opaque base64url, signed; include `sortKeys` and `tenant` to avoid cross-tenant reuse.

## 3) Download manifest (for `/console/downloads` and export outputs)
Top-level:
```jsonc
{
  "version": "2025-12-07",
  "exportId": "console-export::tenant-default::2025-12-07::0009",
  "tenantId": "tenant-default",
  "generatedAt": "2025-12-07T10:15:00Z",
  "items": [
    {
      "type": "vuln",               // advisory|vex|policy|scan|chart|bundle
      "id": "CVE-2024-12345",
      "format": "json",
      "url": "https://downloads.local/exports/0009/vuln/CVE-2024-12345.json?sig=...",
      "sha256": "f1c5…",
      "size": 18432
    }
  ],
  "checksums": {
    "manifest": "sha256:8bbf…",
    "bundle": "sha256:12ae…"          // optional when a tar/zip bundle is produced
  },
  "expiresAt": "2025-12-14T10:15:00Z"
}
```

### 3.1 Signed metadata
- Optional DSSE envelope for `checksums.manifest`, using `sha256` digest and `application/json` payload type `stellaops.console.manifest`.
- Envelope is attached as `manifest.dsse` or provided via `Link: <...>; rel="alternate"; type="application/dsse+json"`.
- Signers: Authority-issued short-lived key scoped to `console:export`.

### 3.2 Error handling
- Known error codes: `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`, `ERR_CONSOLE_DOWNLOAD_EXPIRED`, `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`, `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`.
- On error, respond with deterministic JSON body including `requestId` and `retryAfterSeconds` when applicable.

## 4) Sample manifest
- `docs/api/console/samples/console-download-manifest.json` illustrates the exact shape above.

## 5) Open items for guild sign-off
- Final TTL values for `max-age` and `stale-*`.
- Whether DSSE envelope is mandatory for sealed tenants.
- Maximum bundle size / item count caps (proposal: 1000 items, 500 MiB compressed per export).