# CONCELIER-VULN-29-001 · Concelier ↔ Vuln Explorer bridge (contract v0.1)

Purpose: unblock PREP-CONCELIER-VULN-29-001 by defining the request/response contract Concelier must expose for Vuln Explorer and VEX Lens to consume advisory evidence without merge semantics.

## API shape (Concelier WebService)
- Endpoint: `POST /v1/advisories/search`
- Auth: tenant-scoped token (`concelier.read` scope) with `mergeAllowed=false`.
- Request body:
  ```json
  {
    "query": {
      "advisory_keys": ["GHSA-xxxx-xxxx"],
      "purls": ["pkg:maven/org.example/app@1.2.3"],
      "component_hashes": ["sha256:..."],
      "has_vex": true
    },
    "page": {
      "size": 50,
      "cursor": null
    }
  }
  ```
- Response body:
  ```json
  {
    "results": [
      {
        "advisory_key": "GHSA-xxxx-xxxx",
        "source": "ghsa",
        "observations": [{
          "id": "obs-123",
          "purl": "pkg:maven/org.example/app@1.2.3",
          "version_range": "[1.2.0,2.0.0)",
          "status": "affected",
          "published": "2025-11-01T00:00:00Z",
          "fixed": null,
          "provenance": {
            "source": "ghsa",
            "retrieved_at": "2025-11-18T12:00:00Z",
            "hash": "sha256:..."
          }
        }],
        "vex": [{
          "statement_id": "st-001",
          "status": "not_affected",
          "justification": "component_not_present",
          "impact_statement": "Library not shipped",
          "provenance": {
            "source": "vendor-vex",
            "retrieved_at": "2025-11-18T12:00:00Z",
            "hash": "sha256:..."
          }
        }]
      }
    ],
    "page": {"cursor": "next-token", "size": 50}
  }
  ```

## Determinism requirements
- Sort observations by `purl`, then `published`, then `id`.
- Sort VEX statements by `statement_id`.
- Timestamps UTC ISO-8601 with `Z`.
- Omit merge-derived fields; only surface source-provided values.

## Fields Vuln Explorer expects
- `advisory_key`, `source`, `observations[*].purl`, `observations[*].status`, `observations[*].provenance.hash`.
- VEX fields: `status`, `justification`, `impact_statement`, `provenance.hash`.
- Optional: `fix_version` when present; keep absent otherwise (no empty strings).

## Test fixtures
- Location: `docs/samples/console/console-vex-30-001.json` already includes VEX sample keyed by advisory; add Concelier response sample to `docs/samples/console/concelier-vuln-29-001.json` (to be generated alongside implementation).

## Owners
- Concelier WebService Guild (producer)
- Vuln Explorer Guild / VEX Lens Guild (consumers)

## Next actions to unblock work
- Implement endpoint stub with deterministic ordering and fixture from above sample.
- Hook to Link-Not-Merge storage (fact-only) once available.
- Add contract reference to OAS (Sprint 0114 CONCELIER-OAS-61-001 depends on this).