# Console Search and Downloads

This document defines deterministic ranking, caching rules, and the download manifest shape used by Console search and export-style workflows.

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

## 2) Caching and freshness
- Response headers (recommended defaults): `Cache-Control: private, max-age=300, stale-while-revalidate=60, stale-if-error=300`.
- `ETag` SHOULD be a stable SHA-256 over a canonicalized, sorted payload so identical inputs produce identical validators; clients send `If-None-Match` for revalidation.
- `Last-Modified` SHOULD reflect the newest `updatedAt` present in the result set.
- Retry/backoff: honor `Retry-After` when present; otherwise use deterministic client backoff (for example `1s, 2s, 4s, 8s` capped at 30s).
- Page cursors: opaque base64url, signed; bind to `tenant` and effective sort keys to avoid cross-tenant or cross-sort reuse.

## 3) Download manifest
When a Console workflow produces downloadable artifacts (individual documents or a bundle), services can return a manifest describing:
- What items are available,
- Where to download them (signed URLs or gateway-relative links),
- How to verify them offline (checksums and optional signature metadata).

Top-level fields:
- `version` (string): manifest schema/version label used by the producer.
- `exportId` (string): stable export identifier (content-addressable or run-id style).
- `tenantId` (string): tenant scope for this export.
- `generatedAt` (RFC 3339 / ISO-8601 UTC): generation timestamp.
- `items[]` (array): downloadable artifacts.
- `checksums` (object): checksum(s) for the manifest itself and optional bundle artifact.
- `expiresAt` (RFC 3339 / ISO-8601 UTC): optional expiry for signed URLs.

Item fields:
- `type` (string): artifact type (for example `vuln`, `vex`, `policy`, `scan`, `bundle`).
- `id` (string): stable identifier within the type (CVE id, statement id, export id, etc).
- `format` (string): `json`, `ndjson`, `tar.gz`, etc.
- `url` (string): download URL (often signed).
- `sha256` (string): lowercase hex digest of the bytes at `url`.
- `size` (int): byte size.

### Signed metadata (optional)
Producers MAY ship a DSSE envelope for the manifest checksum:
- Payload type: `stellaops.console.manifest`
- Media type: `application/json`
- Distribution: alongside the manifest (for example `manifest.dsse`) or via a link relation (for example `rel=\"alternate\"` with `type=\"application/dsse+json\"`).

## 4) Error handling
Known error codes for download/manifest flows:
- `ERR_CONSOLE_DOWNLOAD_INVALID_CURSOR`
- `ERR_CONSOLE_DOWNLOAD_EXPIRED`
- `ERR_CONSOLE_DOWNLOAD_RATE_LIMIT`
- `ERR_CONSOLE_DOWNLOAD_UNAVAILABLE`

On error, return the standard error envelope with deterministic fields (stable code/message, plus request/trace identifiers).

## 5) Samples and fixtures
- Download manifest example: `docs/api/console/samples/console-download-manifest.json`