Competency Validation & Assessment Engine — Integration Contract

Auto-created by validate-spec --auto-fix (2026-04-24) to satisfy the Integration Doc Existence requirement (constitution §2.1). Pre-filled from the Integration Points section of the spec; sections marked TODO require author review before Phase A migration ships.

​

Overview

• GR-INTEGRATION.md — GR module integration anchor (if present)
• CROSS_CORE_INTEGRATIONS.md — integration matrix (TODO: add GR-18 row when this doc is reviewed)
• EVENT_CONTRACTS.md — event payload schemas (TODO: register assessment_passed / assessment_failed)
• PLATFORM_INTEGRATION_LAYERS.md — PIL conventions for @/platform/training

​

Integration Summary

​

Events Published by GR-18

​

assessment_passed

• Channel: gr_events (PF event bus; same pattern as GR-02-EN-01.training_completed)
• Publisher: GR-18 — gr_submit_assessment_attempt SECURITY DEFINER RPC, on the same DB transaction as the grade write (at-least-once delivery; consumers MUST dedupe on attempt_id).
• Subscribers:
  • GR-02 completion-gating logic (intra-RPC; creates gr_training_completions row + CEU credit when linked course verification_method = 'assessment')
  • GR-19 In-Service Compliance Monitor (optional; flips cell to “compliant” when course is assessment-gated)
  • HR-22 LMS transcript surface (optional; refreshes employee transcript view)
• Purpose: Notify downstream consumers that an employee passed an assessment and (if applicable) a GR-02 completion has been created.
• Status: 📝 Planned

{
  organization_id: string;     // UUID — required for tenant routing
  attempt_id: string;          // UUID — gr_assessment_attempts.id (idempotency key)
  assessment_id: string;       // UUID — gr_assessments.id
  course_id: string;           // UUID — gr_training_courses.id (linked course)
  enrollment_id: string;       // UUID — gr_training_enrollments.id
  employee_id: string;         // UUID — hr_employees.id at attempt start
  attempt_number: number;      // 1-based; excludes voided priors
  score_pct: number;           // 0.00–100.00
  passed: true;                // always true for this event
  submitted_at: string;        // ISO 8601 timestamp
}

​

assessment_failed

• Channel: gr_events
• Publisher: GR-18 — gr_submit_assessment_attempt, same transaction as the grade write.
• Subscribers:
  • GR-02 enrollment status updater (sets status = 'failed' when attempt_number = max_attempts and last attempt failed)
  • PF-10 notifications (TODO: register notification key for “retry available” / “no attempts remaining” messages)
  • GR-19 (optional; surfaces failure in compliance monitor)
• Purpose: Notify downstream consumers that an employee failed an attempt; on final failure, the enrollment is marked failed and an admin reset is required.
• Status: 📝 Planned

{
  organization_id: string;
  attempt_id: string;
  assessment_id: string;
  course_id: string;
  enrollment_id: string;
  employee_id: string;
  attempt_number: number;
  score_pct: number;
  passed: false;               // always false for this event
  submitted_at: string;
  attempts_remaining: number;  // 0 when this was the final allowed attempt
  cooldown_until: string | null; // ISO 8601 — when the next attempt becomes available
}

​

Events Consumed by GR-18

​

API Contracts

​

SECURITY DEFINER RPCs (Internal)

​

REST/HTTP APIs

​

Platform Integration Layers Used

​

Permissions

​

Picklists

​

Cross-Core Reads (via PIL only — no direct imports)

• HR (hr_employees) — referenced by gr_assessment_attempts.employee_id FK. Read via existing GR-02 patterns (already established as same-core dependency for GR core’s training tables). No new HR PIL hook required.
• GR-02 tables (gr_training_courses, gr_training_enrollments) — same core; FK references. Not cross-core.

​

Tenant Isolation & Security

• Every GR-18 table includes organization_id (defense-in-depth).
• RLS enabled on all 7 tables (6 entity + 1 audit log) with SECURITY DEFINER helpers pf_current_organization_id(), pf_user_has_permission(), pf_current_employee_id() (no recursive RLS — constitution §5.7).
• Answer-key isolation pattern: employee role has NO direct SELECT policy on gr_assessment_questions; reads go through gr_assessment_questions_safe view (omits correct_answer + rationale).
• Server-side time enforcement on submit; client timer is advisory only.
• Attempts + responses are immutable after submission (no UPDATE policy); admin void via SECURITY DEFINER + audit-log row.
• Event payloads contain UUIDs and metadata only — no question stems, no response text, no PHI.

​

Failure Modes

​

Validation Checklist

• Event payloads documented with TypeScript schema (above)
• No PHI in event payloads (verified above)
• All RPCs marked SECURITY DEFINER SET search_path = public
• Tenant isolation pattern documented (above)
• Permission keys registered in PF-30 seed migration AND src/platform/permissions/constants.ts
• PIL hooks exported from @/platform/training (no direct cross-core imports)
• Cross-core matrix entry added to CROSS_CORE_INTEGRATIONS.md — TODO
• Event contracts registered in EVENT_CONTRACTS.md — TODO

​

References

• Spec: GR-18 Competency Validation & Assessment Engine
• Plan: GR-18 Implementation Plan
• Parent substrate: GR-02 Training & CEU Tracking
• Sibling enhancements: GR-02-EN-01 (events), GR-02-EN-02 (PIL), GR-02-EN-03 (picklists)
• Downstream consumers: GR-19 In-Service Compliance Monitor, HR-22 (LMS transcript per ADR-014)
• Constitution: §1 (Architecture), §4 (Security & PHI), §5.7 (No recursive RLS)
• Templates: docs/architecture/integrations/INTEGRATION_CONTRACT_TEMPLATE.md