docs(m4): reconcile roadmap CSVs with target schema

docs/MILESTONES/M4/planning/m4-target-schema-blueprint.md

@@ -1,7 +1,7 @@
 # M4 Target Schema Blueprint (Command-Ready)
 
 Status: Draft for team alignment  
-Date: 2026-02-24  
+Date: 2026-02-25  
 Owner: Technical Lead
 
 ## 1) Goal
@@ -36,6 +36,49 @@ flowchart LR
   V --> O
 ```
 
+## 1.2 Stakeholder wheel mapping (current baseline)
+The stakeholder labels from the customer workshop map to schema as follows:
+
+1. Buyer (Procurements):
+- Buyer users inside a business/client account.
+- Schema anchor: `users` + `tenant_memberships` + `team_members` (procurement team scope).
+2. Enterprises (Operator):
+- Tenant operator/admin users running staffing operations.
+- Schema anchor: `tenants`, `team_members`, command-side permissions.
+3. Sectors (Execution):
+- Operational segments or business units executing events.
+- Schema anchor: `teams`, `team_hubs`, `team_hud_departments`, `roles`.
+4. Approved Vendor:
+- Supplier companies approved to fulfill staffing demand.
+- Schema anchor: `vendors`, `workforce`, `vendor_rates`, `vendor_benefit_plans`.
+5. Workforce:
+- Individual workers/staff and their assignments.
+- Schema anchor: `staffs`, `staff_roles`, `applications`, `assignments`, `certificates`, `staff_documents`.
+6. Partner:
+- External integration or service partner (future).
+- Schema anchor: `stakeholder_profiles` extension path + scoped role bindings.
+
+Rule:
+1. Start with baseline stakeholders above.
+2. Add new stakeholders via extension tables and role bindings, not by changing core scheduling and finance tables.
+
+## 1.3 Future stakeholder expansion model
+To add stakeholders later without breaking core schema:
+1. Add `stakeholder_types` (registry).
+2. Add `stakeholder_profiles` (`tenant_id`, `type`, `status`, `metadata`).
+3. Add `stakeholder_links` (relationship graph across stakeholders).
+4. Bind permissions through `role_bindings` with scope (`tenant`, `team`, `hub`, `business`, or specific resource).
+
+## 1.4 Roadmap CSV evidence snapshot
+Evidence source:
+1. `docs/MILESTONES/M4/planning/m4-roadmap-csv-schema-reconciliation.md`
+
+What the exports confirmed:
+1. The product is multi-party and multi-tenant by design (client, operator, vendor, workforce, procurement, partner, dashboard).
+2. Attendance and offense enforcement are core business workflows, not side features.
+3. Finance requires more than invoices (payment runs, remittance, status history, dispute/audit trace).
+4. Compliance requires asynchronous verification and requirement templates by tenant/business/role.
+
 ## 2) First-principles rules
 1. Every critical write must be server-mediated and transactional.
 2. Tenant boundaries must be explicit in data and queries.
@@ -171,6 +214,33 @@ Rules:
 1. Every command write emits a domain event.
 2. Idempotency scope: `(actor_uid, route, idempotency_key)`.
 
+## 4.9 Attendance, Timesheets, and Offense Governance
+Tables:
+1. `attendance_events` (append-only: clock-in/out, source, correction metadata)
+2. `attendance_sessions` (derived work session per assignment)
+3. `timesheets` (approval-ready payroll snapshot)
+4. `timesheet_adjustments` (manual edits with reason and actor)
+5. `offense_policies` (tenant/business scoped policy set)
+6. `offense_rules` (threshold ladder and consequence)
+7. `offense_events` (actual violation events)
+8. `enforcement_actions` (warning, suspension, disable, block)
+
+Rules:
+1. Attendance corrections are additive events, not destructive overwrites.
+2. Offense consequences are computed from policy + history and persisted as explicit actions.
+3. Manual overrides require actor, reason, and timestamp in audit trail.
+
+## 4.10 Stakeholder Network Extensibility
+Tables:
+1. `stakeholder_types` (buyer, operator, vendor, workforce, partner, future types)
+2. `stakeholder_profiles` (tenant-scoped typed profile)
+3. `stakeholder_links` (explicit relationship graph between profiles)
+
+Rules:
+1. New stakeholder categories are added by data, not by schema rewrites to core workflow tables.
+2. Permission scope resolves through role bindings plus stakeholder links where needed.
+3. Scheduling and finance records remain stable while stakeholder topology evolves.
+
 ## 5) Target core model (conceptual)
 
 ```mermaid
@@ -196,6 +266,11 @@ erDiagram
   STAFF ||--o{ APPLICATION : applies
   SHIFT_ROLE ||--o{ ASSIGNMENT : allocates
   WORKFORCE ||--o{ ASSIGNMENT : executes
+  ASSIGNMENT ||--o{ ATTENDANCE_EVENT : emits
+  ASSIGNMENT ||--o{ TIMESHEET : settles
+  OFFENSE_POLICY ||--o{ OFFENSE_RULE : defines
+  ASSIGNMENT ||--o{ OFFENSE_EVENT : may_trigger
+  OFFENSE_EVENT ||--o{ ENFORCEMENT_ACTION : causes
 
   STAFF ||--o{ CERTIFICATE : has
   STAFF ||--o{ STAFF_DOCUMENT : uploads
@@ -207,10 +282,16 @@ erDiagram
   ORDER ||--o{ INVOICE : billed_by
   INVOICE ||--o{ RECENT_PAYMENT : settles
   TENANT ||--o{ ACCOUNT_TOKEN_REF : payout_method
+  INVOICE ||--o{ INVOICE_LINE_ITEM : details
+  PAYMENT_RUN ||--o{ PAYMENT_ALLOCATION : allocates
+  INVOICE ||--o{ PAYMENT_ALLOCATION : receives
+  PAYMENT_RUN ||--o{ REMITTANCE_DOCUMENT : publishes
 
   ORDER ||--o{ DOMAIN_EVENT : emits
   SHIFT ||--o{ DOMAIN_EVENT : emits
   ASSIGNMENT ||--o{ DOMAIN_EVENT : emits
+  STAKEHOLDER_TYPE ||--o{ STAKEHOLDER_PROFILE : classifies
+  STAKEHOLDER_PROFILE ||--o{ STAKEHOLDER_LINK : relates
 ```
 
 ## 6) Command write boundary on this schema
@@ -234,6 +315,8 @@ flowchart LR
 4. `workforce`: unique active `(vendor_id, staff_id)`.
 5. `team_members`: unique `(team_id, user_id)`.
 6. `accounts` (or token ref table): unique primary per owner.
+7. `attendance_events`: unique idempotency tuple (for example `(assignment_id, source_event_id)`).
+8. `offense_rules`: unique `(policy_id, trigger_type, threshold_count)`.
 
 ## 7.2 Indexes
 1. `orders (tenant_id, status, date)`.
@@ -243,6 +326,9 @@ flowchart LR
 5. `assignments (workforce_id, shift_id, role_id, status)`.
 6. `verification_jobs (subject_id, type, status, created_at)`.
 7. `invoices (business_id, vendor_id, status, due_date)`.
+8. `attendance_events (assignment_id, event_time, event_type)`.
+9. `offense_events (staff_id, occurred_at, offense_type, status)`.
+10. `invoice_line_items (invoice_id, line_type, created_at)`.
 
 ## 8) Data type normalization
 1. Monetary: `Float -> DECIMAL(12,2)` (or integer cents).
@@ -271,11 +357,13 @@ flowchart TD
   - run RBAC in shadow mode"]
   P2 --> P3["Phase 3: Scheduling normalization
   - remove order JSON workflow fields
-  - add order_schedule_rules and shift_managers"]
+  - add order_schedule_rules and shift_managers
+  - add attendance and offense base tables"]
   P3 --> P4["Phase 4: Command rollout
   - command writes on hardened schema
   - emit domain events + idempotency
-  - enforce RBAC for command routes"]
+  - enforce RBAC for command routes
+  - add finance settlement tables for payment runs and remittance"]
   P4 --> P5["Phase 5: Read migration + cleanup
   - migrate frontend reads as needed
   - enforce RBAC for sensitive reads
@@ -289,6 +377,8 @@ flowchart TD
 4. Core transaction invariants enforced by schema constraints.
 5. Command API contracts mapped to new normalized tables.
 6. RBAC is in shadow mode with decision logs in place (not hard-blocking yet).
+7. Attendance and offense tables are ready for policy-driven command routes.
+8. Finance settlement tables (`invoice_line_items`, `payment_runs`, `payment_allocations`) are available.
 
 ## 12) Full current model relationship map (all models)