# Decision Log: Single Supply Chain — Company Codes

**Last updated:** 2026-05-27

---

## How to Read This Log

Each entry captures a decision made during stakeholder discussions or technical analysis. Format:
- **Decision**: What was decided
- **Date / Meeting**: When and where
- **Decided by**: Who made or confirmed the call
- **Rationale**: Why this was chosen over alternatives
- **Status**: Confirmed, Pending, or Superseded

---

## Architecture & Data Model

### D1: Signing Entity remains the legal entity on the contract

**Date:** Feb 4, 2026 — Kickoff with Stakeholders
**Decided by:** Group consensus (Max Lester, Charles Owens, Sean Golden, et al.)
**Rationale:** The signing entity field must always match the actual written legal entity on the paperwork. Financial routing (profit center) is a separate concern.
**Status:** Confirmed

### D2: Decouple signing entity from profit center via a new table

**Date:** Feb 4, 2026 — Kickoff with Stakeholders
**Decided by:** Group consensus
**Rationale:** Instead of duplicating signing entities per profit center (the current workaround), add a new table that maps signing entities to profit centers. One signing entity can map to multiple profit centers. The Feb 4 meeting called this a "servicing entity"; subsequent meetings and the PRD used different terms.
**Note:** Whether this new table is a first-class domain entity (Option A) or a junction/mapping table (Option B) is an open decision. See [SPIKE_SCHEMA_DESIGN.md](SPIKE_SCHEMA_DESIGN.md) section 9.
**Status:** Confirmed (structural approach agreed; naming and framing pending)

### D3: No data migration needed — decouple the link, don't move data

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Rationale:** The `reference_signing_entity` table already contains all the data. The fix is structural: break the rigid 1:1 coupling, not migrate data between tables. "Break legal entity to company code profit center link inside the reference signing entity table."
**Scope:** Applies to the immediate fix (Options A/B). The long-term Option D (see SPIKE_SCHEMA_DESIGN.md section 8) does involve a data migration to retire `reference_signing_entity` — that is a separate follow-on decision.
**Status:** Confirmed

### D4: Settlement feed is NOT impacted

**Date:** Feb 4, 2026 — Kickoff with Stakeholders
**Decided by:** Robert Kordisch
**Rationale:** The settlement feed reads SAP company code and profit center from the contract view (`royalty_accounting_prod_view_dim_abacus_contract_view`). As long as the view is updated to resolve through the new table, the feed itself requires no code changes.
**Status:** Confirmed

### D5: Payment entity derivation stays on signing entity — unchanged

**Date:** Feb 18, 2026 — Account Creation Review
**Decided by:** Kuhuk Goyal
**Rationale:** When a contract is created, the payment entity ID is automatically determined from the signing entity via a lookup table. This relationship is independent of profit center routing and does not need to change.
**Status:** Confirmed

### D6: SAP profit center creation remains out of scope for Abacus

**Date:** Feb 18, 2026 — Account Creation Review
**Decided by:** Humda Rahman
**Rationale:** Profit centers are created by the SAP tech team on the backend and then mapped into the reference table. Abacus consumes this data but does not create profit centers.
**Status:** Confirmed

### D7: Multiple signing entities can share the same profit center mapping

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Rationale:** AWAL Recordings America, Mass Appeal Records, and RED Distribution can all book revenue to the same company code and profit center (USO980) but have different legal relationships (signing entities). The mapping represents a "bookable place of revenue" — it can be shared across legal entities.
**Status:** Confirmed

---

### Technical Recommendations (2026-05-18, pending stakeholder alignment)

The following entries are engineering recommendations from technical analysis, not meeting decisions. They are pending stakeholder sign-off.

### D8: Defer signing entity dedup to after M1

**Date:** 2026-05-18 — Technical analysis
**Decided by:** Michael Rojas (technical recommendation)
**Rationale:** All contract FKs to `reference_signing_entity` use `ON DELETE RESTRICT`. Deduplicating requires reparenting every contract from duplicate IDs to canonical IDs — touching the heaviest table in the system. Too risky to bundle with the initial schema change. Prove the new indirection first, then dedup.
**Status:** Recommended (pending stakeholder alignment)

### D9: Do not add the new FK to contract_template

**Date:** 2026-05-18 — Technical analysis
**Decided by:** Michael Rojas (technical recommendation)
**Rationale:** Templates define contract terms and exclusions, not financial routing. A template's signing entity may map to multiple profit centers after this change. The profit center should be selected at contract creation time, not baked into the template. Note: `contract_template` does not have a direct `reference_sap_profit_center_id` column today — profit center is resolved transitively through `reference_signing_entity`. This decision maintains that pattern.
**Status:** Recommended (pending stakeholder alignment)

### D10: SAP profit center FK on the new table must be NOT NULL

**Date:** 2026-05-18 — Technical analysis
**Decided by:** Michael Rojas (technical recommendation)
**Rationale:** The new table's `reference_sap_profit_center_id` FK should be NOT NULL. Company code and profit center are read from `reference_sap_profit_center` through this FK — if the FK is NULL, there's nowhere to get the financial routing data. The corresponding `reference_sap_profit_center` row must exist before creating a mapping. For Foundation Media entities, this means the SAP profit center rows must be inserted first.
**Status:** Recommended (pending stakeholder alignment)

### D11: No denormalized company_code or profit_center on the new table

**Date:** 2026-05-18 — Technical analysis
**Decided by:** Michael Rojas (technical recommendation)
**Rationale:** `company_code` and `profit_center` already exist on `reference_sap_profit_center`. Duplicating them on the new table creates two sources of truth with risk of drift. Read through the FK instead. One extra JOIN is acceptable for a reference table with ~82 rows.
**Status:** Recommended (pending stakeholder alignment)

### D12: No is_default or is_active columns on the new table

**Date:** 2026-05-18 — Technical analysis
**Decided by:** Michael Rojas (technical recommendation)
**Rationale:** `is_active` is redundant with the SoftDeleteMixin (`deleted_at`) — the existing soft-delete pattern used across the Abacus schema. `is_default` is UI logic (auto-select when list has one item), not a data concern. Neither appeared in the PRD, meeting notes, or stakeholder requirements.
**Status:** Recommended (pending stakeholder alignment)

---

## Process & Workflow

### D13: M1 uses manual email workflow; self-service UI deferred to M2

**Date:** PRD (original, undated) + Feb 24, 2026
**Decided by:** Danielle Vu (PRD author), Charles Owens
**Rationale:** The June/July catalog migration deadline is tight. M1 only needs the backend decoupling and data entry by the Abacus team. Self-service UI (cascading dropdown) can follow in M2 without blocking the Foundation Media onboarding.
**Status:** Confirmed

### D14: Foundation Media may be manually managed until automation is in place

**Date:** Feb 4, 2026 — Kickoff with Stakeholders
**Decided by:** Group consensus
**Rationale:** The current volume is manageable (one delivery in five weeks). Full catalog migration changes the scale, but until then, manual data entry is acceptable.
**Status:** Confirmed

### D15: P&L reconciliation follows the existing signing entity change process

**Date:** PRD (original)
**Decided by:** Nico Lombard (referenced in PRD)
**Rationale:** When a signing entity changes on a contract, CA already notifies Finance so they can make the necessary changes in SAP. Profit center changes will follow the same process. No new notification system needed — extend the existing one.
**Status:** Confirmed

### D16: No consultation with other Sony labels needed

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Rationale:** The theme (Sony) side is not involved in and not aware of this project. The current, imminent need is separation of signing entity from company code/profit center. Other labels' mapping methods are irrelevant to this work.
**Status:** Confirmed

---

## Naming & UI

### D17: New field naming — UNRESOLVED

**Date:** Feb 4 → Feb 24, 2026 (discussed across multiple meetings)
**Decided by:** Pending stakeholder alignment
**Candidates:**
- "Servicing Entity" — Sean Golden's original proposal (Feb 4)
- "Profit Center Name" — PRD language (Danielle Vu)
- "Servicing Center" — Ideal mapping spreadsheet
- "Revenue Servicing Entity" — Feb 11 meeting discussion

**Arguments for "Profit Center Name":** Non-finance users understand it; it's what appears on external docs.
**Arguments against:** Nate Lichtenstein and Charles both asked why a new term is needed if it just reflects the financial reporting relationship.

**Note:** This decision is intertwined with the Option A vs B decision (see SPIKE_SCHEMA_DESIGN.md). If Option A, the entity needs a name. If Option B, a `display_name` column avoids the naming debate entirely.
**Status:** **Pending — does not block engineering** (DB column names and UI labels are independent; placeholders used until resolved)

### D18: Display both layman name AND SAP codes in the UI

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Rationale:** Finance people speak in profit center codes. Non-finance users need human-readable names. Best approach: display the layman's name AND the SAP profit center code (and potentially the company code) so all users can understand regardless of financial literacy.
**Note:** The PRD says "Profit Center Name is what is surfaced in external docs," which could be interpreted as display name only. Charles's direction was to show both. This should be confirmed with Danielle Vu if there is a conflict for external-facing documents.
**Status:** Confirmed (for Abacus UI); pending clarification for external documents

### D19: The concept already exists — it just needs a label

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Rationale:** The `reference_sap_profit_center_id` (column G in the mapping sheet) already represents a unique connection between a company code and a profit center. What's missing is a user-friendly name/label for it. The field exists internally — it just isn't exposed in the UI.
**Note:** This framing supports the goal of all three options (add a user-facing label). It most directly describes Option C's mechanism (add a label to the existing table), but Options A and B achieve the same goal through a new table. See SPIKE_SCHEMA_DESIGN.md section 7 for why Option C is ruled out despite D19 supporting its premise.
**Status:** Confirmed

---

## Data & Backfill

### D20: Display names for existing entities — non-blocking

**Date:** Referenced in PRD and multiple meetings
**Decided by:** Engineering decision (2026-05-18)
**Context:** The backfill creates one mapping per existing signing entity row. Each needs a user-facing display name. Finance people may know these by code, but the UI needs human-readable labels.
**Workaround:** Use placeholder names (`legal_name -- profit_center_code`) during backfill. Business provides real names whenever ready — updated via a simple SQL UPDATE, no code change or deploy required.
**Status:** **Pending from business** — does not block engineering

### D21: Signing entity cleanup is already in progress

**Date:** Feb 18, 2026 — Account Creation Review; Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Humda Rahman (executing the cleanup)
**Context:** Redundant signing entity entries exist (e.g., multiple "Orchard Enterprises NY Inc" entries with different company codes/profit centers/paid-by). Humda is already cleaning this up independently. This work should coordinate with but not block on the cleanup effort.
**Status:** In progress (Humda)

---

## Timeline & Urgency

### D22: Summer deadline is critical — full catalog migration expected June/July

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Context:** Current volume is manageable (one delivery in five weeks), but full catalog porting to Foundation Media changes the scale dramatically. Must demonstrate progress by end of following week (from Feb 24).
**Status:** Confirmed

### D23: Decoupling is a net positive for everyone, not just Foundation Media

**Date:** Feb 24, 2026 — Charles / Danielle 1:1
**Decided by:** Charles Owens
**Rationale:** The current structure requires workarounds (duplicate signing entities). Decoupling will demonstrably improve operations for The Orchard broadly, not just the Foundation Media pilot.
**Status:** Confirmed

---

## Schema & Implementation (2026-05-27, after spike review)

### D24: Option B selected — pure junction table, contract has direct FK to PC

**Date:** 2026-05-27 — Spike review
**Decided by:** Michael Rojas
**Rationale:** The diagram circulated 2026-05-27 collapses two SPIKE_SCHEMA_DESIGN open decisions (Option A vs B, and whether the same label can span SAP PCs):

- **Junction table:** `signing_entity_profit_center` is a **pure mapping table** — `(signing_entity_id, sap_profit_center_id)` plus audit and soft-delete columns. No business attributes on the junction itself. Encodes which SAP profit centers a signing entity is authorized to route revenue through.
- **Contract FK:** The contract has a **direct FK to `reference_sap_profit_center`** (`contract.reference_sap_profit_center_id`), not to the junction row. The junction governs *authorization*; the contract stores the *chosen* PC. The application layer validates that the (SE, PC) pair on every contract exists in the junction.

This collapses Option A vs B by removing the new-domain-entity question (no entity, just a mapping) and supersedes TRD_B's "contract → junction" design.

**Status:** Confirmed — implementing in M1

### D25: Display name lives on `reference_sap_profit_center`, not on the junction

**Date:** 2026-05-27 — Spike review
**Decided by:** Michael Rojas
**Rationale:** The user-facing label belongs to the SAP profit center, not to the SE↔PC relationship. Multiple signing entities mapping to the same PC will share the same label automatically. This is consistent with D7 (multiple SEs can share a PC mapping) and simplifies the data model — there is one canonical name per PC.

- Column: `reference_sap_profit_center.display_name VARCHAR(255) NOT NULL` (after backfill)
- **No UNIQUE constraint** on `display_name` — multiple PCs may share a label if business chooses (e.g., "The Orchard" appearing on different PC codes)
- The legacy `profit_center` column (the SAP code) gains a **UNIQUE constraint** in this migration

**Status:** Confirmed

### D26: Backfill both junction and contract.PC from current 1:1 data

**Date:** 2026-05-27 — Implementation planning
**Decided by:** Michael Rojas
**Rationale:** Today's NOT NULL `reference_signing_entity.reference_sap_profit_center_id` gives a deterministic 1:1 SE→PC for every active SE. Backfill:

1. Insert one row per active SE into `signing_entity_profit_center` (carrying the current PC).
2. Populate `contract.reference_sap_profit_center_id` via `contract → SE → SE.reference_sap_profit_center_id`.

Both backfills are safe and deterministic. After backfill, the legacy SE.PC path and the new contract.PC path return identical results — enabling the dual-path FF rollout (D27).

**Status:** Confirmed

### D27: Dual-path rollout gated by Harness Feature Flag `single_supply_chain_company_codes`

**Date:** 2026-05-27 — Implementation planning
**Decided by:** Michael Rojas
**Rationale:** During M1 rollout, both the old SE→PC path and the new direct path exist in the codebase. A Harness FF (default **OFF** = old path; **ON** = new path) lets the switch happen as a control-plane action without a redeploy and supports symmetric rollback. FF gates apply only to application code (`ows-royalties`, `lambda-abacus/sync_contract_sap`, frontend). DB views and Liquibase migrations are atomic forward-only switches — not FF-gated.

**FF lifecycle:**
- M1.7: Create FF (default OFF)
- M1.19: Flip to ON in prod after backfill verification
- M3.7: Remove FF checks from all callsites
- M3.8: Delete the FF

**Status:** Confirmed

### D28: No FK on `contract_template` (D9 carries forward)

**Date:** 2026-05-27 — Confirming under Option B
**Decided by:** Michael Rojas
**Rationale:** Carries D9 forward unchanged. Templates define contract terms and exclusions, not financial routing. A template's signing entity may now map to multiple PCs after this change. The PC is selected at contract creation time, not baked into the template. `contract_template` retains its existing `reference_signing_entity_id` FK only.

**Status:** Confirmed

### D29: Three separate ACC epics (one per milestone)

**Date:** 2026-05-27 — Project structuring
**Decided by:** Michael Rojas
**Rationale:** M1/M2/M3 each have distinct goals, owners, and timelines. Modeling as three Jira Epics (in the ACC project, not COD) keeps each milestone's scope discoverable, mirrors the existing roadmap structure, and aligns with the project tracking convention. Cleanup work (FF removal, column drop, SE dedup) is concentrated in M3 so every intermediate state remains fully functional. See [feedback memory: cleanup-at-end-of-migrations](../../../../../../.claude/projects/-Users-michael-rojas-Documents-projects-ows-coda/memory/feedback_destructive_last.md) for the broader principle.

**Status:** Confirmed