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

# Fingerprint Clearance Card Management — Integration

> Version: 1.0.1 Last Updated: 2026-03-24 Spec: HR-28 Fingerprint Clearance Card Management Constitution Reference: Section 1.2 (Core Independence), Section 1.3…

**Version:** 1.0.1\
**Last Updated:** 2026-03-24\
**Spec:** [HR-28 Fingerprint Clearance Card Management](../../../specs/hr/specs/HR-28-fingerprint-clearance-card-management.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

HR-28 tracks Arizona DPS fingerprint clearance cards per employee, drives expiration notifications, and exposes verification status for HR-03 onboarding and HR-02 credential prerequisites. Cross-core consumers use the Platform Integration Layer or documented events—no direct core-to-core imports.

***

## Integration Points

### Platform Foundation (PF)

| PF area                   | Use                                                                         |
| ------------------------- | --------------------------------------------------------------------------- |
| **PF-10 (Notifications)** | Expiration (90/60/30), suspension/revocation, onboarding block messaging    |
| **PF-04 (Audit)**         | Sensitive mutations (verification, status changes, incident create/resolve) |
| **PF-30 (Permissions)**   | Keys `hr.fingerprint_clearance.{view,manage,verify}`                        |
| **PF-56 (File upload)**   | Card image and GCE document storage paths (RLS-aligned buckets)             |

### Intra-HR dependencies

| Spec      | Relationship                                                            |
| --------- | ----------------------------------------------------------------------- |
| **HR-01** | Employee anchor (`employee_id`)                                         |
| **HR-02** | Prerequisite checks for credentials requiring clearance                 |
| **HR-03** | Onboarding completion gate: active + verified clearance                 |
| **HR-14** | Optional link from clearance incidents to ER cases (reference IDs only) |

***

## Event Contracts (planned)

Names follow `{core}_{entity}_{action}` where possible. Final names MUST be registered in `EVENT_CONTRACTS.md` before production publish.

### `hr_fingerprint_clearance_status_changed`

**Publisher:** HR (HR-28)\
**Subscribers:** HR-02, HR-03 (via platform handlers)\
**Status:** 📋 Planned

**Purpose:** Notify gates and dashboards when clearance moves between blocking and non-blocking states.

```typescript theme={null}
interface HrFingerprintClearanceStatusChangedPayload {
  event_type: 'hr_fingerprint_clearance_status_changed';
  organization_id: string;
  employee_id: string;
  clearance_id: string;
  previous_status: string;
  new_status: string;
  effective_at: string; // ISO timestamp
  timestamp: string;
}
```

### `hr_fingerprint_clearance_expiration_warning`

**Publisher:** HR (HR-28) / scheduled worker\
**Subscribers:** PF-10\
**Status:** 📋 Planned

**Purpose:** Correlate scheduled notifications with idempotent alert flags on the clearance row.

```typescript theme={null}
interface HrFingerprintClearanceExpirationWarningPayload {
  event_type: 'hr_fingerprint_clearance_expiration_warning';
  organization_id: string;
  employee_id: string;
  clearance_id: string;
  /** Must match a threshold from org `fingerprint_clearance_alert_days` (default [90, 60, 30]). */
  days_until_expiration: number;
  expiration_date: string; // ISO date
  timestamp: string;
}
```

***

## API / data access

* **Client:** HR module routes and hooks under `src/cores/hr/`; use Supabase client with tenant filters on mutations.
* **Downstream cores:** Consume published events or platform read APIs—do not query `hr_fingerprint_clearances` from non-HR cores.

***

## Security & tenant isolation

* All rows scoped by `organization_id`; RLS enforced.
* Full card numbers suppressed for all non-authorized roles and internal surfaces (including logs, prompts, error strings, monitoring/telemetry, and debug dumps).
* No secrets or card numbers in logs, prompts, error strings, monitoring/telemetry, or debug outputs.

***

## Related documentation

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md) — matrix row HR-28
* [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md)
* [CONTRACT\_VALIDATION\_CHECKLIST.md](./CONTRACT_VALIDATION_CHECKLIST.md)