> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payfi.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Production evaluation release gates

> Controlled rollout, evidence, isolation, and approval gates for PayFi partner evaluation in Railway production.

The operational target is the Railway `production` environment
`b7270b25-8992-4b89-b34d-a88fe40d1a9e`. Browser smoke uses
`https://frontend-production-0ca5.up.railway.app`.

`demo-staging` is a separate environment. It is not a promotion source, rollback
target, or operational alias for this rollout.

## Trust contract

Every new analysis uses the canonical v2 contract. A field result has one of
`FOUND`, `NOT_FOUND`, `CONFLICT`, or `UNCERTAIN`, together with its value,
normalized value, confidence, reason codes, and document evidence.

Every analysis and Decision Pack stores an immutable `AnalysisProvenance`
snapshot containing:

* Analysis contract version.
* Workflow ID, active version ID, and content hash.
* Model provider, name, and profile.
* Prompt and rules versions.
* Partner policy ID, version, and source hash.
* Regulatory corpus version and manifest hash.
* OCR service version and engine.
* RegDocs service version.

`versionMetadata` is a temporary projection of this snapshot. The regulatory
corpus has a single version source; there is no separate evaluation-corpus
version.

`analysisDisposition` is one of `VALID`, `PARTIAL`,
`HUMAN_REVIEW_REQUIRED`, `TECHNICAL_FAILURE`, or `POLICY_NOT_CONFIGURED`.
Technical failures, partial extraction, abstention, conflicts, and human
decisions remain separate. A dependency failure never changes the commercial
risk score.

## Fail-closed activation

The worker may invoke n8n only when all of these controls agree:

* The integration is in the emergency allowlist.
* An approved analysis activation set is active for the integration.
* The partner policy has an approved source file and SHA-256, named external
  approval, human review, and source-referenced rules.
* Contract, workflow, model, prompt, rules, policy, regulatory corpus, OCR, and
  RegDocs versions match the activation set.

If the client has no policy configured, PayFi applies
`system-default-document-policy` version `1`
(`97ff1b55faa3209c1908cdb5b08c55f26f26236b58182fc481e01d6c32fe40c8`),
marks `fallbackUsed=true`, uses disposition `HUMAN_REVIEW_REQUIRED`, and keeps
the operation processable. The fallback can never produce an autonomous ready
result or external authorization. A malformed custom policy falls back only in
`INTERNAL_SUPERVISED_ONLY`; in authorized evaluation it fails closed with
`PARTNER_POLICY_NOT_CONFIGURED` and retains
`DOCUMENT_REQUIREMENT_POLICY_NOT_CONFIGURED` as the legacy alias.

A generic baseline is allowed only in `INTERNAL_SUPERVISED_ONLY`. It records
`fallbackUsed=true`, cannot have disposition `VALID`, and requires human review.
Generative models cannot produce a ready state or resolve a material conflict.

## Production rollout

1. Record application deployments, commits, additive migrations, non-secret
   configuration, and the four active workflow versions. Back up the database
   and export each active workflow before any publication.
2. Complete CI for API, worker, frontend, n8n, OCR, RegDocs, and docs.
3. Configure non-secret v2 settings with rollout disabled. Deploy the API and
   additive migrations, then prove compatibility with the previous worker and
   existing integrations.
4. Deploy RegDocs, digest-pinned ClamAV, OCR, worker, and frontend. Validate
   health metadata, private networking, tenant isolation, and logs.
5. Publish compatible versions of the existing production workflow IDs and
   record their `activeVersionId` and content hash:

| Workflow              | ID                 |
| --------------------- | ------------------ |
| Document requirements | `PAYFIDOCREQ1`     |
| Compliance analysis   | `ZMlinKAKU3uUG9b8` |
| Decision Pack         | `Rsmrc2p5STzykAWj` |
| Risk policy           | `PAYFIRISKPOL1`    |

6. Provision a partner integration only after its supplied IDs pass collision
   checks. It starts in `INTERNAL_SUPERVISED_ONLY`, without an active external
   user.
7. Import, review, and activate the formal partner policy, then create the
   complete analysis activation set.

No step opens the partner gate implicitly.

## Gate 1: one real canary

Ground truth is locked before processing. Run one authorized real operation and
reconcile every field, conflict, requirement, score factor, evidence reference,
audit event, and raw-file deletion. Stop on any divergence.

The canary must include illegible, truncated, wrong-document, malware, dependency
failure, incompatible provenance, duplicate/concurrent upload, replay, callback,
retry, and cross-tenant negative cases.

## Gate 2: supervised partner evaluation

Run 20 authorized real operations, complete every structured review, and observe
logs and metrics for two hours. During the window the release manifest remains
`PENDING_OBSERVATION`.

Only after the run, the observation window, and named approvals pass may the
integration enter `AUTHORIZED_PARTNER_EVALUATION` and the external user be
enabled.

The remote Playwright smoke is pinned to the production environment ID,
production URL, and integration ID. It covers login/password change, customer,
operation, real upload, processing, evidence, structured review, cross-tenant
`404`, logout, and rejected session. Traces, screenshots, and videos are
disabled.

## Gate 3: release comparison

Gate 3 requires 100 labeled real operations, a version-to-version replay
comparison, and formal approval. Replays use approved activation sets, are
idempotent, never change the original operation, never trigger callbacks, and
never extend retention.

Weight fine-tuning is evaluated only after Gate 3 and separate authorization.

## Raw-file retention

Raw operation files are deleted immediately after successful processing or a
terminal failure. An eligible retry may retain the raw object for at most 24
hours. The reconciler deletes expired objects, records success or failure, and
emits a redacted event for alerting.

If no authorized snapshot remains after raw deletion, replay returns
`REPLAY_INPUT_UNAVAILABLE`.

## Rollback

Rollback is scoped to the affected integration:

1. Remove the integration from the emergency allowlist.
2. Deactivate its analysis activation set and external access.
3. Restore the recorded application deployment or workflow
   `activeVersionId` only when contract-compatible.
4. Preserve analyses, review labels, release manifests, and additive schema.

Never perform a destructive schema downgrade, automatically promote an
incompatible workflow, or enable a fallback that emits a ready result.

## Release blockers

The final state remains `BLOCKED_EXTERNAL_INPUT` or
`INTERNAL_SUPERVISED_ONLY` until the approved partner policy and approval
reference, real canary, 20-operation labeled set, qualified ground truth,
retention/training authorization, external-user secret, and two-hour monitored
observation are complete.

Do not publish reliability, productivity, or error-rate claims without a
reproducible corpus, labels, method, and formal approval.