Pre-Employee Record

1. Overview

The bridge between offer-accepted and start-date: ATS owns the pre-employee lifecycle stage (paperwork in flight, pre-boarding tasks open, background check pending). Realizes the hired state on job_applications. Publishes the pre_employee.activated event that hands the canonical reconciliation to HCM-mastered employees. Formerly NEW-HIRE-HANDOFF, renamed per §7.1 because HCM canonically masters employees.

2. Entity summary

Name	Description
Pre-Employees	ATS-owned pre-employment record covering the post-offer-acceptance window before the new-hire start date: paperwork in flight, background check pending, pre-boarding tasks open. At start-date the pre-employee row is reconciled into HCM-mastered `employees` (the canonical employee record). HCM owns the canonical employee record; ATS owns the pre-employee lifecycle stage so recruiting and HCM can each move at their own pace.
Candidates	Person known to the recruiting org, with or without an active application. Carries contact details, resume, tags, GDPR consent, and source. Distinct from Employee until hired.
Offers	Formal employment offer extended to a candidate. Carries compensation components, start date, terms, approval chain, and status (draft / approved / sent / accepted / declined / rescinded).

flowchart TD
  classDef master fill:#d4f4dd,stroke:#27ae60,color:#0b3d20;
  classDef embedded_master fill:#fff4cc,stroke:#c79100,color:#5b4500;
  classDef platform_builtin fill:#e0e0e0,stroke:#424242,color:#1a1a1a;
  pre_employees["Pre-Employees"]
  candidates["Candidates"]
  job_offers["Offers"]
  users["Users"]
  job_offers -->|"spawns pre-employee record"| pre_employees
  candidates -->|"becomes pre-employee"| pre_employees
  job_offers -->|"has approver"| users
  pre_employees -->|"has owning hr_coordinator"| users
  class pre_employees master;
  class candidates embedded_master;
  class job_offers embedded_master;
  class users platform_builtin;

3. Entities catalog

#	data_object	role	mastered in	necessity	pattern flags	notes
1	`pre_employees` (Pre-Employees)	master	-	required	personal_content	-
2	`candidates` (Candidates)	embedded_master	`ats-candidate-crm`	required	personal_content	-
3	`job_offers` (Offers)	embedded_master	`ats-offers`	required	personal_content, single_approver	-

4. Aliases and industry synonyms

(no industry-scoped aliases or non-synonym alias types loaded for this scope; generic synonyms are omitted as common knowledge.)

5. Relationships

5.1 Intra-scope edges

from	verb	to	cardinality	kind	necessity	owner_side	notes
`job_offers`	spawns pre-employee record	`pre_employees`	one_to_one	reference	required	source	-
`candidates`	becomes pre-employee	`pre_employees`	one_to_one	reference	required	source	-

5.2 Built-in edges (`users` and other platform built-ins)

from	verb	to	cardinality	necessity	owner_side	notes
`job_offers`	has approver	`users`	many_to_many	required	source	-
`pre_employees`	has owning hr_coordinator	`users`	one_to_many	required	source	-

5.3 Cross-scope edges

from	verb	to	cardinality	necessity	notes
`pre_employees`	promotes to	`employees`	one_to_one	required	-
`skill_profiles`	feeds	`candidates`	one_to_many	optional	-
`candidates`	submits	`job_applications`	one_to_many	required	-
`candidate_referrals`	introduces	`candidates`	one_to_many	required	-
`recruitment_sources`	attributes	`candidates`	one_to_many	required	-
`recruitment_agencies`	sources	`candidates`	one_to_many	required	-
`recruitment_events`	attracts	`candidates`	one_to_many	required	-
`talent_pools`	groups	`candidates`	many_to_many	required	-
`job_applications`	results in	`job_offers`	one_to_many	required	-
`job_offers`	is contingent on	`background_checks`	one_to_many	required	-
`job_offers`	spawns	`onboarding_journeys`	one_to_one	required	-
`job_offers`	triggers	`benefit_enrollments`	one_to_one	required	-
`job_offers`	seeds	`compensation_statements`	one_to_one	required	-
`candidates`	becomes	`employees`	one_to_one	required	-

6. Cross-domain context

6.1 Master consumers (other modules / domains that embed this scope’s masters)

data_object	other module / domain	role	necessity	notes
`pre_employees`	HCM-LIFECYCLE-WORKFLOWS (Employee Lifecycle Workflows) - HCM	consumer	required	-

6.2 Outbound handoffs (events this scope publishes)

source module	target domain	target module	trigger_event	payload	integration	friction	description
ATS-PRE-EMPLOYEE-RECORD	HCM	HCM-LIFECYCLE-WORKFLOWS	`pre_employee.activated`	`pre_employees`	event_stream	medium	Pre-employee activation hands the canonical reconciliation to HCM-mastered `employees`. ATS owns the pre-employee lifecycle stage (paperwork, background check, pre-boarding); at start-date the pre_employee row is reconciled into the HCM employee record. Identifier mapping (pre_employee_id → employee_id) is the canonical reconciliation gap. Replaces / complements the older candidate.hired and job_offer.accepted handoffs by carrying the proper post-acceptance reconciliation milestone.

6.3 Inbound handoffs (events this scope reacts to)

target module	source domain	source module	trigger_event	payload	integration	friction	description
ATS-PRE-EMPLOYEE-RECORD	ATS	ATS-OFFERS	`job_offer.accepted`	`pre_employees`	lifecycle_progression	low	-
ATS-PRE-EMPLOYEE-RECORD	ATS	ATS-BACKGROUND-CHECKS	`background_check.cleared`	`pre_employees`	lifecycle_progression	low	-
ATS-PRE-EMPLOYEE-RECORD	ATS	ATS-OFFERS	`job_offer.rescinded`	`pre_employees`	lifecycle_progression	high	-

6.4 Master providers (modules / domains that own masters this scope embeds)

data_object	role here	necessity	canonical owner(s)	slice notes
`candidates`	embedded_master	required	ATS-CANDIDATE-CRM (ATS)	-
`job_offers`	embedded_master	required	ATS-OFFERS (ATS)	-

7. Lifecycle states (per touched entity)

`candidates` (Candidate)

This scope holds candidates as embedded_master; the canonical state machine is owned by ATS-CANDIDATE-CRM.

order	state_name	initial?	terminal?	requires_permission?	derived gate	description
1	`prospect`	✓	-	-	-	Person known to the recruiting org with no active application.
2	`active`	-	-	-	-	Candidate has at least one open application or is actively engaged.
3	`hired`	-	✓	✓	`ats-candidate-crm:hire_candidate`	Candidate accepted an offer and converted to employee.
4	`do_not_hire`	-	✓	✓	`ats-candidate-crm:flag_do_not_hire`	Candidate flagged as ineligible for future consideration; gated decision.
5	`archived`	-	✓	-	-	Candidate kept in the database but not active in any pipeline.

`job_offers` (Offer)

This scope holds job_offers as embedded_master; the canonical state machine is owned by ATS-OFFERS.

order	state_name	initial?	terminal?	requires_permission?	derived gate	description
1	`draft`	✓	-	-	-	Recruiter is composing offer terms and compensation components.
2	`pending_approval`	-	-	-	-	Offer routed to the designated approver for sign-off.
3	`approved`	-	-	✓	`ats-offers:approve_offer`	Approver signed off; offer is ready to send.
4	`sent`	-	-	-	-	Offer delivered to the candidate.
5	`accepted`	-	✓	-	-	Candidate accepted the offer.
6	`declined`	-	✓	-	-	Candidate declined the offer.
7	`rescinded`	-	✓	✓	`ats-offers:rescind_offer`	Offer withdrawn by the employer after being sent; gated action.

`pre_employees` (Pre-Employee)

order	state_name	initial?	terminal?	requires_permission?	derived gate	description
1	`created`	✓	-	-	-	Record created when an offer is accepted. Paperwork packet not yet generated.
2	`paperwork_in_flight`	-	-	-	-	I-9 / W-4 / direct-deposit / banking forms issued; awaiting candidate completion. Background check may run in parallel.
3	`cleared`	-	-	-	-	All paperwork received and background check completed clear. Ready for HCM activation.
4	`activated`	-	✓	✓	`ats-pre-employee-record:activate_pre_employee`	Reconciliation handoff fired to HCM (pre_employee.activated event). Canonical employees row created downstream; ATS record becomes read-only.
5	`cancelled`	-	✓	-	-	Offer rescinded or candidate withdrew before activation. Record retained for audit.

8. Permissions and business rules (derived)

8.1 Permissions

permission	tier	description	included in `:admin`?
`ats-pre-employee-record:read`	baseline-read	Read access to every entity in the module	✓
`ats-pre-employee-record:manage`	baseline-manage	Edit operational records	✓
`ats-pre-employee-record:admin`	baseline-admin	Edit reference data and inherit every workflow gate below	-
`ats-pre-employee-record:activate_pre_employee`	workflow-gate (lifecycle)	Transition `pre_employees` into state `activated`	✓
`ats-pre-employee-record:view_all_pre-employees`	override (personal_content)	View all `pre_employees` rows beyond row-scope	✓
`ats-pre-employee-record:manage_all_pre-employees`	override (personal_content)	Manage all `pre_employees` rows beyond row-scope	✓

8.2 Business rules

rule_name	data_object	source flag	intent
`pre-employee_edit_scope`	`pre_employees`	has_personal_content	Row-scope by default; override via `ats-pre-employee-record:view_all_pre-employees` / `ats-pre-employee-record:manage_all_pre-employees`