Explanation: Compliance Ledger Design

The Compliance Ledger is the scheduled-expectation compatibility projection; the authoritative worked-shift fact is report_obligations. This document explains their boundary, service-day keys, deadline/certification states, and dual-obligation behavior.

---

Why a Decoupled Ledger?Copy Anchor Link

In earlier iterations of Danvas, compliance was evaluated on the fly by joining schedules (management_shifts) and submissions (server_reports). While simple, this approach introduced significant issues:

1. Schedule Mutability: Reopening or modifying a schedule after a shift had already occurred would retroactively delete or alter compliance records, destroying the historical audit trail.
2. Line-Up Mismatches: Staff shift expectations are driven by a mix of published schedules (for Front-of-House) and Daily Line-Up assignments (for floor roles). On-the-fly calculations became too complex and error-prone.

The compliance table remains a transaction-secured compatibility ledger whose rows are generated at discrete lifecycle moments. Authoritative expected obligations are reconciled separately from canonical worked labor:

• Schedule finalization → manager compatibility rows and provisional manager-obligation candidates (one row per employee/service day)
• Lineup publish → staff compatibility rows and provisional shift-obligation candidates (service-day grain — one row per employee per service date)
• Worked-shift reconciliation → authoritative report_obligations rows from canonical f_time_entries, with source digest and certification state
• Draft lineup saves do not seed staff compliance

Once expectations are filed, historical rows remain even if schedules are reopened.

---

Staff service-day grain (ADR-0070)Copy Anchor Link

Staff shift reports use one compliance row per employee per service date per location, not one row per daypart. A bartender on Lunch and Dinner lineups files one shift report. The report's shift field stores the primary daypart (longest scheduled segment); goals sum across daypart assignments.

---

Saturday–Friday Service Week RationaleCopy Anchor Link

Weekly compliance percentages are calculated strictly on a Saturday–Friday service week boundary. This matches the payroll and scheduling configuration of our primary integration anchors (7shifts and Toast POS).

Using a standard calendar week (Monday–Sunday) would cause:

• Double-counting: Weekend shifts would span across payroll periods.
• Goal mismatch: Sales targets set for the weekend would split across two different compliance cycles.

---

Worked-shift authority and filingCopy Anchor Link

report_obligations is unique on (teamId, locationId, serviceDate, subjectType, subjectId, reportType) via uniq_report_obligation. Reconciliation is partition replacement for one exact team/location/service-date scope. It records canonical time-entry and job lineage, computes a next-day 4:00 a.m. deadline in the location timezone, and uses certificationStatus (provisional or certified) separately from status (unfiled, draft, filed, late, excused, cancelled, superseded, quarantined, or provisional).

Report submission is fail-closed: fileReportObligation matches an existing applicable obligation and returns no_applicable_obligation when one is absent; it never creates the expected row. A provisional submission is retained until reconciliation can certify it. A certified submission links the exact report and becomes filed or late. The legacy compliance projection is updated only after this match.

Dual Obligations DesignCopy Anchor Link

A key design challenge was how to handle managers who also work floor shifts. In restaurants, a Salaried Manager may be scheduled for a MOD (Manager on Duty) shift but also assigned to a floor section (e.g., Bartender) on the Daily Line-Up card.

To handle this, the ledger decouples report types:

• type: manager rows are seeded from schedule finalization (one per employee/service day).
• type: staff rows are seeded from published Daily Line-Up assignments (service-day grain).

A single user can have one manager row and one staff row for the same service day when scheduled and assigned on a published lineup. The compatibility shift value remains for primary-daypart attribution and legacy readers; it is not the accountability key.