# HDGP Case Study Template (Public)

> Purpose: a repeatable, reviewable record for integrating a real system with HDGP, including evidence artifacts.
> Audience: external engineers + reviewers. No secrets should be included.

---

## 0. Summary

- **Project**: <name>
- **Integration mode**: Inline / Sidecar / Hybrid
- **Environment**: sandbox / staging / prod-like
- **Engine version**: <from `GET /hdgp/v1/status`>
- **Policy**: spec/strategy/bundles (from `GET /hdgp/v1/status`)
- **Outcome**:
  - adoption: <what changed in the product>
  - governance: <what evidence was produced>

---

## 1. Architecture & touchpoints

### 1.1 Where HDGP sits

- **Call site(s)**: list every place where user-visible outputs are produced.
- **Decision point**: call `POST /hdgp/v1/evaluate` **before** returning the candidate output to the end user.
- **Timeout budget**: <ms> and fallback behavior (recommend fail-closed in high-risk).

### 1.2 Data flow (minimal)

- Candidate output → `evaluate` → verdict/actions → final output
- Audit evidence:
  - in-memory `/hdgp/v1/audit` (recent)
  - optional append-only NDJSON: `HDGP_AUDIT_LOG_PATH`

---

## 2. Integration steps (copy/paste friendly)

### 2.1 Start Engine (sandbox)

```powershell
go run ./cmd/hdgp-engine
```

### 2.2 First request (curl)

```bash
curl -X POST http://localhost:8080/hdgp/v1/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "request_id": "case-001",
      "scene": { "domain": "general", "intent": "chat", "risk_level": "medium" }
    },
    "subject": { "type": "output_text" },
    "candidate": { "text": "candidate output" }
  }'
```

### 2.3 Mapping verdict → product behavior

- **allow**: return candidate output.
- **modify**: apply `actions` (rewrite / add warnings / require citations) then return.
- **block**: do not return; return a safe refusal / human escalation.
- **fuse**: stop automation; require human.

---

## 3. Evidence & audit trail (what to attach)

### 3.1 Required evidence artifacts (public-safe)

- `GET /hdgp/v1/status` snapshot (redact keys/secrets)
- 1–3 representative `evaluate` requests/responses (redact PII)
- `GET /hdgp/v1/audit?limit=5` output showing matching `request_id`

### 3.2 Optional (recommended) evidence artifacts

- Append-only NDJSON enabled:

```powershell
$env:HDGP_AUDIT_LOG_PATH = "C:\temp\hdgp-audit.ndjson"
go run ./cmd/hdgp-engine
```

- A small excerpt (10–30 lines) from the NDJSON, with PII removed.
- Hash-chain verification results if enabled:
  - `HDGP_AUDIT_HASH_CHAIN_ENABLED=true`
  - `scripts/verify-audit-log-hash-chain.ps1`

---

## 4. Failure modes & rollback

- **Engine unreachable / timeout**:
  - expected product behavior: <block/fuse/queue for later>
  - operator alerting: <where>
- **Unexpected blocks**:
  - how to reproduce with the same `request_id`
  - how to appeal (if applicable)
- **Rollback plan**:
  - feature flag / routing switch
  - evidence retention plan

---

## 5. What we learned

- Latency: <p50/p95>
- False positives/negatives observed: <summary>
- Next hardening steps:
  - <e.g. stricter meta mapping, stricter production guard, additional conformance cases>