Governance Session Builder

Build a richly-annotated AI decision trace with EU AI Act metadata, guardrail results, content safety flags, and human oversight records — using the fluent VeriproofSession API directly (no framework adapter required).

TypeScriptGovernanceNode.js ≥ 18

Prerequisites


npm install @veriproof/sdk-core

Environment


VERIPROOF_API_KEY=vp_live_...
VERIPROOF_APPLICATION_ID=loan-decisioning

Complete example


import {
  configureVeriproof,
  VeriproofSdkOptions,
  VeriproofSession,
  AgentRole,
  ContentSafetyFlag,
  DecisionType,
  DeploymentMode,
  GroundingStatus,
  GuardrailAction,
  HumanOversightType,
  RiskLevel,
  RiskSeverity,
  SessionIntent,
  SessionOutcome,
  StepOutcome,
  StepType,
} from '@veriproof/sdk-core';
 
// 1. Configure VeriProof once at startup (call this before any sessions)
const { provider } = configureVeriproof(
  VeriproofSdkOptions.createDevelopment({
    apiKey: process.env.VERIPROOF_API_KEY!,
    applicationId: process.env.VERIPROOF_APPLICATION_ID!,
  }),
  { serviceName: process.env.VERIPROOF_APPLICATION_ID!, setGlobal: true },
);
process.on('SIGTERM', async () => { await provider.shutdown(); });
 
// ─── Build the governance session ───────────────────────────────────────────
 
const session = new VeriproofSession({
  applicationId: process.env.VERIPROOF_APPLICATION_ID!,
  sessionName: 'loan-approval-decision',
 
  // Who initiated this session and why
  intent: SessionIntent.DECISION_SUPPORT,
  deploymentMode: DeploymentMode.PRODUCTION,
 
  // EU AI Act: Article 9 — Risk management & human oversight requirements
  euAiActArticle: 9,
  humanOversightType: HumanOversightType.HUMAN_IN_THE_LOOP,
 
  // Identify the subject of the decision (avoid PII — use opaque IDs)
  subjectId: 'applicant:A-1042',
  correlationId: 'loan-app:LA-20260310-1042',
});
 
// ─── Step 1: Document extraction & validation ─────────────────────────────
 
await session.addStep({
  stepName: 'document-extraction',
  stepType: StepType.PREPROCESSING,
  agentRole: AgentRole.EXTRACTOR,
  input: { documentType: 'pay-stub', pageCount: 2 },
  output: { extractedFields: ['grossIncome', 'employer', 'payPeriod'] },
  outcome: StepOutcome.COMPLETED,
});
 
// ─── Step 2: Creditworthiness assessment ─────────────────────────────────
 
await session.addStep({
  stepName: 'credit-assessment',
  stepType: StepType.ANALYSIS,
  agentRole: AgentRole.ASSESSOR,
  input: { creditScore: 712, debtToIncomeRatio: 0.34 },
 
  // Guardrail: block if hallucination risk is high
  guardrailAction: GuardrailAction.ALLOW,
  groundingStatus: GroundingStatus.GROUNDED,
 
  // Content safety (no flagged content in this step)
  contentSafetyFlags: [],
 
  riskLevel: RiskLevel.LOW,
  outcome: StepOutcome.COMPLETED,
});
 
// ─── Step 3: Final decision ───────────────────────────────────────────────
 
await session.addStep({
  stepName: 'approval-decision',
  stepType: StepType.DECISION,
  agentRole: AgentRole.DECISION_MAKER,
 
  // EU AI Act Article 14: transparency record for the operator
  decisionType: DecisionType.APPROVAL,
  decisionSummary: 'Loan approved: applicant meets income and credit thresholds.',
 
  riskLevel: RiskLevel.MEDIUM,
  riskFactors: [
    {
      factor: 'debt-to-income-ratio',
      severity: RiskSeverity.MEDIUM,
      description: 'DTI of 0.34 is within acceptable range but above preferred threshold of 0.3.',
    },
  ],
 
  // Human reviewer confirmed the AI recommendation before it was actioned
  humanOversightType: HumanOversightType.HUMAN_IN_THE_LOOP,
  humanReviewerId: 'reviewer:R-007',
  humanApproved: true,
 
  outcome: StepOutcome.COMPLETED,
});
 
// ─── Finalise session ─────────────────────────────────────────────────────
 
session.setOutcome(SessionOutcome.SUCCESS);
 
const result = await session.complete();
 
console.log('Session ID   :', result.sessionId);
console.log('Merkle root  :', result.merkleRoot);    // blockchain anchor hash
console.log('Span count   :', result.spanCount);

What you’ll see in VeriProof

Span	Key attributes
`session loan-approval-decision`	`veriproof.session.intent=DECISION_SUPPORT`, `veriproof.eu_ai_act.article=9`, `veriproof.oversight.type=HUMAN_IN_THE_LOOP`
`step document-extraction`	`veriproof.step.type=PREPROCESSING`, `veriproof.agent.role=EXTRACTOR`
`step credit-assessment`	`veriproof.guardrail.action=ALLOW`, `veriproof.grounding.status=GROUNDED`
`step approval-decision`	`veriproof.decision.type=APPROVAL`, `veriproof.risk.level=MEDIUM`, `veriproof.human.approved=true`

The Merkle root returned in result.merkleRoot is anchored to the Solana blockchain — any subsequent tampering with the session data is cryptographically detectable.

The euAiActArticle and humanOversightType fields feed directly into VeriProof’s EU AI Act compliance evidence export. If your application is a high-risk AI system under Annex III, these fields are required for Article 9 conformity documentation.

Recording post-decision outcomes

Link the approved loan’s real-world result back to the session for longitudinal outcome tracking:


import { VeriproofClient } from '@veriproof/sdk-core';
 
const client = new VeriproofClient({
  apiKey: process.env.VERIPROOF_API_KEY!,
  applicationId: process.env.VERIPROOF_APPLICATION_ID!,
});
 
await client.recordOutcome(result.sessionId, {
  outcomeType: 'LOAN_REPAID',
  outcomeValue: 1,       // 1 = positive outcome
  recordedAt: new Date().toISOString(),
  metadata: { loanId: 'L-20260310-1042', finalRepaymentDate: '2028-03-10' },
});

Next steps

Post-Decision Outcome Recording guide — full outcome API
EU AI Act compliance — Article 9–17 evidence packaging
TypeScript SDK Core reference — complete VeriproofSession parameters