Skip to main content
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:
  1. Provision a partner integration only after its supplied IDs pass collision checks. It starts in INTERNAL_SUPERVISED_ONLY, without an active external user.
  2. Import, review, and activate the formal partner policy, then create the complete analysis activation set.
No step opens the partner gate implicitly. A successful deployment, health check, or smoke test is not proof that the analysis or review flow is ready for partner use.

​
Gate 1: five real canaries

Ground truth is locked before processing. Run five authorized real operations and reconcile every field, conflict, requirement, score factor, evidence reference, persisted operation state, audit event, and raw-file deletion. Stop on any divergence. Across the canaries, cover illegible, truncated, wrong-document, malware, dependency failure, incompatible provenance, duplicate/concurrent upload, replay, callback, retry, and cross-tenant negative cases. When a callback applies, prove both the real delivery result and the partner’s reconciliation of the persisted operation state.

​
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. Production browser smoke is read-only. It is pinned to the production environment ID, production URL, and integration ID, and confirms authenticated navigation, persisted result rendering, evidence visibility, cross-tenant 404, logout, and rejected session. It must not create customers or operations, upload files, trigger processing, or record a decision. 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. The public documentation release follows the same evidence gate: publish only behavior that is already deployed, compatible, and proven by the required canaries. Reverting documentation restores the previous published explanation; it never changes an immutable analysis, Pack, score, recommendation, or human decision.

​
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.