---
id: 01-pii-retention-type-primitives
epic: compliance-manifests-pii-retention-subprocessors
title: PII and retention type primitives in core-shared
type: technical-story
status: done
feature: core-shared
depends-on: []
blocks:
  [
    02-eslint-rule-pii-declaration-complete,
    03-adr-022-amendment-and-evaluate-library-skill,
    04-retention-purge-job,
    05-backfill-template-collections,
    06-compliance-generator-scripts,
  ]
created: 2026-05-18T17:52:09Z
updated: 2026-05-18T18:29:19.373Z
---

## Goal

Produce the TypeScript type primitives (`PiiCategory`, `DataProcessingPurpose`, `RetentionAction`, `RetentionTrigger`, `FieldRetention`, `FieldPii`, `CollectionRetention`, `PurgeSchedule`, `PAYLOAD_AUTH_PII_DEFAULTS`) in `core-shared/payload/` plus the ambient module declaration that extends Payload's `Field` and `CollectionConfig` custom fields to be typed. These are the "manifest" for the whole epic — everything else depends on them existing and compiling.

## Why

All downstream stories need the type contracts before they can compile. Landing these first means every subsequent story gets full TypeScript coverage on Payload config files, and the ESLint rule has a known schema to validate against.

## Done when

- `packages/core-shared/src/payload/pii-types.ts` exports `PiiCategory`, `DataProcessingPurpose`, `RetentionTrigger`, `RetentionAction`, `FieldRetention`, `FieldPii`, and `PAYLOAD_AUTH_PII_DEFAULTS` (with `null` for credential fields: `password`, `salt`, `hash`, `resetPasswordToken`, `resetPasswordExpiration`, `loginAttempts`, `lockUntil`, `apiKey`, `apiKeyIndex`).
- `packages/core-shared/src/payload/retention-types.ts` exports `PurgeSchedule` and `CollectionRetention`.
- `packages/core-shared/src/payload/payload-custom-ambient.d.ts` augments the `payload` module to type `Field.custom.pii?: FieldPii` and `CollectionConfig.custom.retention?: CollectionRetention` / `CollectionConfig.custom.authPii?: Record<string, FieldPii | null>`.
- Both modules are re-exported from the `core-shared` barrel (or a `payload` sub-barrel).
- Vitest tests cover: `@ts-expect-error` on malformed `FieldPii` (missing required fields), `PAYLOAD_AUTH_PII_DEFAULTS` structure (credential fields are `null`, `email` is non-null with correct shape).
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass.

## In scope

- `packages/core-shared/src/payload/pii-types.ts`
- `packages/core-shared/src/payload/retention-types.ts`
- `packages/core-shared/src/payload/payload-custom-ambient.d.ts`
- Vitest tests for both type files.
- Barrel export additions.

## Out of scope

- ESLint rule (Story 02).
- Retention purge job (Story 04).
- Collection backfill (Story 05).
- Generator scripts (Story 06).

## Tasks

- [x] Add `pii-types.ts`, `retention-types.ts`, and `payload-custom-ambient.d.ts` to `packages/core-shared/src/payload/` — complete type contracts per the PRD, ambient Payload module augmentation, `PAYLOAD_AUTH_PII_DEFAULTS` constant with `null` for credential fields, vitest tests verifying shape and defaults, barrel exports — all gates pass on this commit.
