# Pilot Readiness Checklist

Status: **DOCUMENTED**. This file is the entry criteria for any external
pilot. Every item is either satisfied ("yes") with an artefact pointer, or
open ("no") with a mitigation.

## 1. Integration checklist

- [ ] SDK selected: JS/TS (`sdk/js`) or Python (`sdk/python`).
- [ ] Signing key ownership decided (see §7).
- [ ] Receipt-issuance path selected: HTTP `POST /api/v1/receipts` or
      `sign-only` local library mode.
- [ ] Data-minimised mode configured (default; see §3).
- [ ] Receipt ID storage strategy chosen (see §4).
- [ ] Failure / retry / idempotency strategy chosen (see §5, §6).
- [ ] Retention policy documented (see §8).
- [ ] Verification workflow rehearsed with the offline verifier (§10).
- [ ] DBD sector schema chosen and pinned (§11).
- [ ] Policy binding strategy chosen (§12).
- [ ] Pilot success metrics agreed (§13).

## 2. Minimal data-flow diagram

```
                  (customer perimeter)
+----------------------------------------------------+
|                                                    |
|   Application / workflow                           |
|        |                                           |
|        | 1. produces raw content locally           |
|        v                                           |
|   SDK (data-minimised mode)                        |
|        |                                           |
|        | 2. computes input_hash / output_hash     |
|        |    using the chosen Hashing Profile v1    |
|        |    over the raw content — locally         |
|        v                                           |
|   HTTPS: hashes + metadata only                    |
|        |                                           |
+--------|-------------------------------------------+
         v
      Signatrust node
         |
         | 3. seals a Decision Receipt (Ed25519)
         | 4. appends to hash-chained ledger
         v
      receipt_id + verify_url
         |
+--------|-------------------------------------------+
|        v                                           |
|   Application persists receipt_id                  |
|   beside its own case / record id                  |
|                                                    |
+----------------------------------------------------+
```

The raw content never leaves the customer perimeter unless the customer
explicitly opts in to a non-minimised path (not the default).

## 3. Zero / data-minimised mode

Defaults:

- The SDK computes hashes locally.
- The HTTP body sent to the Signatrust node contains only:
  agent id, model attribution, business event, risk level, input_hash,
  output_hash, human_review flag, optional human_review_attestation_hash,
  optional policies[] tags, optional metadata (customer-controlled),
  optional scope_declaration (DBD), and timestamp.
- The Signatrust node does not receive: prompts, outputs, PII, or any
  content beyond hashes and issuer-declared metadata.

Verification:

- `scripts/regression-matrix.ts §privacy` asserts no raw content leaves
  the SDK when data-minimised mode is on.

## 4. Receipt-ID storage guidance for the customer

Signatrust does not know the customer's case / patient / record ids. It
returns a `receipt_id` (`STR-…`). The customer stores that string next to
its own case record:

```
customer database
+---------------------------+
| case_id: internal-XYZ     |
| patient_ref: hash-…       |    <- customer’s own PII (not sent to us)
| decision_at: 2026-08-27   |
| receipt_id: STR-1A2B3C…   |    <- link to the receipt
| receipt_verify_url: …     |    <- optional cache
+---------------------------+
```

Design implication: retrieving a receipt years later requires looking up
`receipt_id` in the customer's own system, then passing it (with the
receipt JSON or via the Offline Verification Bundle) to the verifier.

## 5. Failure behaviour

- The Signatrust node returns 503 during graceful shutdown drains.
  Callers must treat 503 as **retryable**.
- The node returns 429 when a plan rate limit is reached; retry with the
  `Retry-After` header.
- Any 5xx other than 503 is unexpected and MUST be logged customer-side.
- A network failure leaves the receipt unsealed. The customer's own
  workflow decides whether to (a) block the decision, (b) queue for
  later, or (c) proceed without a receipt and record that fact. This is
  a customer policy choice, not a platform decision.

## 6. Retry / idempotency guidance

- Each seal request supports an idempotency key (`Idempotency-Key`
  header). Repeated requests with the same key within the retention
  window return the same `receipt_id`, not a duplicate seal.
- The SDK generates a per-attempt idempotency key by default; customers
  who need deduplication across process restarts should supply a stable
  key derived from their own case id.

## 7. Key management options

Trade-off matrix:

| Option | Key custody | Ease of integration | Long-term auditability |
|--------|-------------|---------------------|------------------------|
| Managed (default) | Signatrust node | Highest | Depends on issuer's trust bundle publication (§10) |
| Bring-your-own-key (BYOK) | Customer | Medium | Customer controls trust bundle; strongest long-term posture |
| Sign-only local SDK | Customer | Low (more work) | Customer signs offline; node stores signed receipt only |

Recommendation for regulated pilots: **BYOK** if the customer can
operate a KMS/HSM path.

## 8. Retention responsibilities

- **Signatrust node** retains the append-only ledger with all receipts
  produced through it, unless the deployment configures a retention
  policy explicitly.
- **Customer** retains original content, decision context, policy
  documents (if using `policy_bindings`), and any human-reviewer
  identity data.
- **Third-party auditor** typically receives a per-case Offline
  Verification Bundle (§10) — not the customer's full archive.

## 9. What Signatrust stores and does not store

Stores (per receipt): agent id, model attribution string, `input_hash`,
`output_hash`, risk level, `human_review` boolean, optional
`human_review_attestation_hash`, optional `policies[]` tags, optional
metadata (customer-supplied and canonicalised), optional
`scope_declaration`, `timestamp`, `sequence`, `previous_hash`,
`receipt_hash`, `signature`.

Does not store: raw prompts, raw outputs, PII, reviewer names,
patient/case identifiers, policy document bodies, or any content beyond
hashes and issuer-declared metadata.

## 10. Verification workflow for an external auditor

1. Customer exports an Offline Verification Bundle for the receipt(s)
   under review (`OFFLINE_VERIFICATION_SPEC.md`).
2. Auditor runs `node scripts/verify-offline.mjs --bundle …`.
3. Auditor optionally supplies the original content, in which case the
   verifier recomputes input/output hashes under the receipt's declared
   hashing profile.
4. Auditor reads the structured report.

The verifier is designed to run without Signatrust being reachable.

## 11. DBD schema selection

- Choose the sector schema that best represents the decision boundary
  the workflow claims to disclose.
- Pin `sector_schema_id` and `sector_schema_hash` in every receipt.
- Do not adopt a schema whose domain list you cannot honestly evaluate.
  Declaring a domain as `excluded` with a truthful reason is stronger
  evidence than pretending to have evaluated it.
- Full coverage is **"all domains in this schema version were
  evaluated"**. It is not "all real-world factors were considered".

## 12. Policy binding workflow

If the workflow depends on a specific version of a written protocol:

1. Freeze the protocol document at issuance time.
2. Compute `sha256(canonical(protocol_document))` and include a
   `policy_bindings[]` entry.
3. Archive the document in a customer-controlled store keyed by the
   hash.
4. Include the document in the Offline Verification Bundle when handing
   off to an auditor.

## 13. Metrics and pilot success criteria

Recommended target:

- **Duration:** ≥ 30 operational days.
- **Volume:** enough real (or realistically simulated) decisions to
  exercise the workflow's error paths, not a curated demo set.
- **Data minimisation:** verified by inspection — no raw content leaves
  the customer perimeter under the data-minimised path.
- **Latency overhead:** measured at p50 / p95 / p99 vs the workflow's
  pre-existing latency. Report as a table, not a marketing headline.
- **Independent verification:** ≥ 1 externally-conducted verification
  pass using the offline verifier.
- **Documented failure / recovery events:** at least one exercised
  restart, one exercised 503, and one exercised idempotency retry with
  the customer's actual retry logic.
- **End-user feedback:** captured qualitatively; not a NPS number.

## 14. What "ready" means

The pilot is **ready** when every item in §1 is checked, the mandatory
tests in `scripts/regression-matrix.ts` pass in the customer's target
environment, and the Offline Verification Bundle can be produced and
verified end-to-end by a party outside both the customer and the
Signatrust maintainer.