Skip to content

feat(reports): TSE compliance, audit & governance command center backend (#41) - #68

Closed
Villarley wants to merge 1 commit into
Velar-Bonds:mainfrom
Villarley:feat/issue-41-tse-compliance-command-center
Closed

feat(reports): TSE compliance, audit & governance command center backend (#41)#68
Villarley wants to merge 1 commit into
Velar-Bonds:mainfrom
Villarley:feat/issue-41-tse-compliance-command-center

Conversation

@Villarley

Copy link
Copy Markdown
Contributor

Summary

Backend for issue #41 — VELAR's TSE compliance, audit & governance command center. Extends the existing party-side "Monthly report lifecycle" (#40) with the TSE governance layer:

  • Formal workflow + dual control + optimistic concurrency — extends the existing PATCH /reports/:id/review (doesn't replace it) with an optional expectedVersion etag (409 on stale writes, fully backward-compatible when omitted), a new rechazado terminal state, and a "four-eyes" dual-control gate on approvals over a configurable amount threshold, enforced with segregation-of-duties (second approver must differ from the first).
  • Explainable, versioned, backtestable rules engine (reports/rules/) — typed, severity-scored Findings (amount mismatch, missing/unknown bond refs, overdue, threshold breach) with a human-readable reasoning trace; versioned rule sets (v1/v2) with backtest diffing.
  • Eventual-consistency on-chain reconciliation (reports/domain/reconciliation-window.ts) — confirmation/tolerance windows and re-check semantics on top of the existing pure reconcile().
  • ABAC authorization (auth/abac/) — attribute-based decisions covering role, delegated reviewer assignment, and segregation of duties, wired into the review flow.
  • Hash-chained, tamper-evident audit log — every AuditService.emit() call is now chained (sha256 over canonicalized, key-sorted content) transparently, with a verifier that detects tampering and gaps.
  • SLA + escalation engine (sla/) — idempotent, never-de-escalating breach detection against a configurable ladder.
  • BI-grade compliance analytics + forecast (compliance-analytics/) — per-party compliance rate, reviewer workload/SLA attainment, and a deterministic overdue forecast (linear trend / moving average).
  • Streaming, tamper-evident exports (reports/exports/) — CSV (genuine streaming via an async generator) and PDF (pdfkit), both hash-chained row-by-row with a tamper-evidence manifest.

Full design in docs/TSE_GOVERNANCE_ARCHITECTURE.md.

Deliberately backend-only. The frontend command center (assignable queue, reconciliation workspace, audit-trail viewer, KPI/forecast charts, export UI) is out of scope for this PR — the HTTP surface and shared types are ready for a follow-up frontend PR to consume. No VELAR credentials or live infrastructure are used anywhere; every DB-touching piece is exercised only via in-memory fake SupabaseService implementations.

Test plan

  • npm run build --workspace @velar/types — clean
  • npm run build --workspace apps/api — clean
  • npm run lint --workspace apps/api — 0 errors (pre-existing any/hook warnings on untouched files only)
  • cd apps/api && npx jest36 suites, 331 tests passing, including property-based (fast-check) and concurrency-race tests for optimistic-concurrency rejection, dual-control/SoD, hash-chain tamper/gap detection, and rules-engine backtesting
  • npm run build/lint/test --workspace apps/web — unaffected (additive types only), confirmed no regressions
  • Migrations are additive-only SQL (new files under supabase/migrations/), not applied against any live database in this PR

Closes #41

…end (Velar-Bonds#41)

Extends the party-side monthly report lifecycle (Velar-Bonds#40) with the TSE
governance layer: a formally-specified workflow with dual-control
approval and optimistic concurrency (extends the existing
PATCH /reports/:id/review, doesn't replace it), an explainable/
versioned/backtestable rules engine, ABAC authorization with
segregation-of-duties enforcement, a hash-chained tamper-evident audit
log, an SLA/escalation engine, compliance analytics with forecasting,
and streaming tamper-evident CSV/PDF exports.

Backend-only by design: no frontend command center in this PR. Every
DB-touching piece is exercised in tests via in-memory fake
SupabaseService implementations — no VELAR credentials or live infra
anywhere. See docs/TSE_GOVERNANCE_ARCHITECTURE.md for the full design.

Closes Velar-Bonds#41

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@vercel

vercel Bot commented Jul 28, 2026

Copy link
Copy Markdown

@mmongee is attempting to deploy a commit to the josueazc's projects Team on Vercel.

A member of the Team first needs to authorize it.

@Villarley Villarley closed this Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TSE compliance, audit & governance command center (workflow engine, explainable rules, ABAC+dual-control, hash-chained audit) — STAFF-level

2 participants