PSA/ee/docs/plans/2026-03-20-multi-active-contracts-per-client/SCRATCHPAD.md

Scratchpad — Multi-Active Contracts Per Client

• Plan slug: multi-active-contracts-per-client
• Created: 2026-03-20

Decisions

• 2026-03-20: This plan assumes true concurrent active assignments are allowed, including overlapping active windows for the same client.
• 2026-03-20: This plan preserves single-assignment invoices. Removing the single-active-contract rule does not imply mixed-contract invoices.
• 2026-03-20: PO scope remains invoice-level and therefore remains assignment-scoped because invoices remain assignment-scoped.
• 2026-03-20: client_contract_id, not contract_id, is the canonical identity for assignment-scoped UI and execution.
• 2026-03-20: Ambiguous legacy surfaces must stop guessing. Prefer explicit assignment identity or an explicit ambiguity failure.
• 2026-03-20: Mixed-currency behavior is explicitly preserved as a separate policy; multi-active assignment support does not imply mixed-currency active assignments for the same client.
• 2026-03-20: Invoice tables already snapshot client_contract_id, so removing singleton active-contract assumptions does not require invoice schema redesign to preserve single-assignment invoices.

Discoveries / Constraints

• 2026-03-20: There is no DB-level uniqueness or exclusion constraint enforcing one active contract per client. The rule is app-layer only.
• 2026-03-20: The billing wizard path is asymmetric today. It only preflights mixed-currency active contracts and can already create same-client same-currency active contracts through a different path than packages/clients.
• 2026-03-20: packages/clients has the most dangerous identity bugs for this change. Several reads and UI flows still key by contract_id, which is not unique once a client can hold multiple active assignments to the same header/base contract.
• 2026-03-20: Recurring due-work grouping is already closer to the desired behavior than preview/generation. Candidate grouping already splits by client_contract_id; the execution path is the risky part.
• 2026-03-20: Invoice generation, PO consumption, invoice queries, and exports all still assume one invoice belongs to one client_contract_id. That assumption is workable and should be preserved in this plan.
• 2026-03-20: Fixed recurring charge attribution can still collapse sibling concurrent assignments if they share the same base line/template identity.
• 2026-03-20: Bucket usage currently picks the latest active matching assignment. That behavior becomes actively wrong when concurrent active contracts are allowed.
• 2026-03-20: BillingCycles still collapses multiple active assignments for a client to the first active row returned, ordered by latest start date.
• 2026-03-20: calculateBillingForSelectionInput(...) previously fetched persisted recurring timing selections at client + invoice window scope and passed them through unchanged, which could re-expand selected-candidate preview/generation into sibling assignment work.
• 2026-03-20: Client-cadence selector scheduleKey encodes assignment line identity (client_contract_line:<id>), which can be used to enforce assignment-scoped recurring selection filtering before billing calculation.
• 2026-03-20: Singleton active-contract UI/action blockers were still live in ContractBasicsStep, ContractDialog, ClientContractsTab, Contracts.tsx, contractActions, and shared/model helper layers.
• 2026-03-20: Wizard assignment writes inserted directly into client_contracts, so shared assignment validation was bypassed and mixed-currency policy could diverge from clients flows.

Agent Audit Summary

• UI enforcement audit:
  • packages/billing/src/components/billing-dashboard/contracts/wizard-steps/ContractBasicsStep.tsx
  • packages/billing/src/components/billing-dashboard/contracts/ContractDialog.tsx
  • packages/billing/src/components/billing-dashboard/contracts/ClientContractsTab.tsx
  • packages/billing/src/components/billing-dashboard/contracts/Contracts.tsx
• Shared/server invariant audit:
  • shared/billingClients/contracts.ts
  • shared/billingClients/clientContracts.ts
  • packages/billing/src/actions/contractActions.ts
  • packages/billing/src/models/contract.ts
• Clients identity/scoping audit:
  • packages/clients/src/components/clients/ClientContractAssignment.tsx
  • packages/clients/src/components/clients/BillingConfiguration.tsx
  • packages/clients/src/components/clients/ContractLines.tsx
  • packages/clients/src/actions/clientContractLineActions.ts
  • packages/clients/src/models/clientContractLine.ts
• Recurring/invoice/PO audit:
  • packages/billing/src/actions/invoiceGeneration.ts
  • packages/billing/src/lib/billing/billingEngine.ts
  • packages/billing/src/services/invoiceService.ts
  • packages/billing/src/services/purchaseOrderService.ts
  • packages/billing/src/actions/billingAndTax.ts
• Secondary-surface audit:
  • packages/billing/src/components/billing-dashboard/BillingCycles.tsx
  • packages/billing/src/services/bucketUsageService.ts
  • packages/billing/src/actions/contractReportActions.ts
• Fixture/schema/docs audit:
  • server/test-utils/billingTestHelpers.ts
  • server/test-utils/testContext.ts
  • docs/billing/billing.md
  • ee/docs/plans/2026-01-05-contract-purchase-order-support/*

Key File Pointers

• Singleton helpers:
  • shared/billingClients/contracts.ts
  • shared/billingClients/clientContracts.ts
• Billing UI blockers:
  • packages/billing/src/components/billing-dashboard/contracts/wizard-steps/ContractBasicsStep.tsx
  • packages/billing/src/components/billing-dashboard/contracts/ContractDialog.tsx
  • packages/billing/src/components/billing-dashboard/contracts/ClientContractsTab.tsx
• Clients UI identity/scoping:
  • packages/clients/src/components/clients/ClientContractAssignment.tsx
  • packages/clients/src/actions/clientContractLineActions.ts
  • packages/clients/src/models/clientContractLine.ts
• Invoice/PO boundary:
  • packages/billing/src/actions/invoiceGeneration.ts
  • packages/billing/src/services/purchaseOrderService.ts
  • packages/billing/src/actions/invoiceQueries.ts
• Secondary ambiguity surfaces:
  • packages/billing/src/services/bucketUsageService.ts
  • packages/billing/src/components/billing-dashboard/BillingCycles.tsx

Commands / Runbooks

• 2026-03-20: Singleton-rule repo scan
  • rg -n "hasActiveContractForClient|getClientIdsWithActiveContracts|already has an active contract|active contract overlapping|disabledClientIds" shared packages/billing packages/clients server/src/test ee/docs/plans docs/billing
• 2026-03-20: Commit provenance for the UI client-disable behavior
  • git show --stat --summary 3aa57cd62f62ba70b2d05e657d6d1bc9d67b7b05
• 2026-03-20: Plan scaffold
  • python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/scaffold_plan.py "Multi-Active Contracts Per Client" --slug multi-active-contracts-per-client
• 2026-03-20: Singleton-blocker removal audit
  • rg -n "disabledClientIds|already has an active contract|terminate their current contract|save as draft|checkClientHasActiveContract|fetchClientIdsWithActiveContracts|getClientIdsWithActiveContracts|hasActiveContractForClient" packages/billing/src/components/billing-dashboard/contracts packages/billing/src/actions shared/billingClients packages/clients/src
• 2026-03-20: Post-change verification scan
  • rg -n "checkClientHasActiveContract|fetchClientIdsWithActiveContracts|hasActiveContractForClient|getClientIdsWithActiveContracts" packages/billing/src packages/billing/tests shared/billingClients packages/billing/src/models
• 2026-03-20: Shared overlap/mixed-currency follow-up scan
  • rg -n "join\\('client_contracts as cc'|already has an active contract overlapping the specified range|where\\(function overlap\\(" packages/billing/src/actions/contractWizardActions.ts shared/billingClients/clientContracts.ts packages/clients/src/actions/clientContractActions.ts packages/clients/src/models/clientContract.ts
• 2026-03-20: Targeted billing test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/contract.test.ts tests/ClientContractsTab.assignmentLifecycle.test.ts tests/multiActiveContracts.singletonGuardRemoval.wiring.test.ts tests/multiActiveContracts.assignmentWritePath.wiring.test.ts
• 2026-03-20: Clients identity wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.singletonGuardRemoval.wiring.test.ts tests/multiActiveContracts.assignmentWritePath.wiring.test.ts tests/multiActiveContracts.clientsAssignmentIdentity.wiring.test.ts tests/ClientContractsTab.assignmentLifecycle.test.ts tests/contract.test.ts
• 2026-03-20: Client contract-line assignment read wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.singletonGuardRemoval.wiring.test.ts tests/multiActiveContracts.assignmentWritePath.wiring.test.ts tests/multiActiveContracts.clientsAssignmentIdentity.wiring.test.ts tests/multiActiveContracts.clientContractLineReads.wiring.test.ts tests/ClientContractsTab.assignmentLifecycle.test.ts tests/contract.test.ts
• 2026-03-20: Client contract-line mutation-scope wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.singletonGuardRemoval.wiring.test.ts tests/multiActiveContracts.assignmentWritePath.wiring.test.ts tests/multiActiveContracts.clientsAssignmentIdentity.wiring.test.ts tests/multiActiveContracts.clientContractLineReads.wiring.test.ts tests/multiActiveContracts.clientContractLineMutationScope.wiring.test.ts tests/ClientContractsTab.assignmentLifecycle.test.ts tests/contract.test.ts
• 2026-03-20: Assignment detail scope wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.assignmentDetails.wiring.test.ts tests/multiActiveContracts.clientsAssignmentIdentity.wiring.test.ts tests/multiActiveContracts.clientContractLineReads.wiring.test.ts tests/multiActiveContracts.clientContractLineMutationScope.wiring.test.ts
• 2026-03-20: Disambiguation-copy fallback removal wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.disambiguationCopy.wiring.test.ts tests/multiActiveContracts.assignmentDetails.wiring.test.ts
• 2026-03-20: Clients UI identity audit wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.clientsUiIdentityAudit.wiring.test.ts tests/multiActiveContracts.disambiguationCopy.wiring.test.ts tests/multiActiveContracts.assignmentDetails.wiring.test.ts
• 2026-03-20: Recurring due-work assignment-split integration test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/recurringDueWorkReader.integration.test.ts
• 2026-03-20: Recurring selector-scope preview/generation regression test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/invoiceGeneration.preview.test.ts src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts
• 2026-03-20: Fixed recurring persistence assignment-separation regression test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/invoiceService.fixedPersistence.test.ts
• 2026-03-20: Client-cadence assignment-scoped materialization-gap regression test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/recurringDueWorkReader.integration.test.ts
• 2026-03-20: Mixed-assignment single-invoice invariant regression test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts
• 2026-03-20: Recurring preview identity-context wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.recurringPreviewIdentity.wiring.test.ts
• 2026-03-20: Invoice assignment-scoping wiring regression test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.invoiceAssignmentScoping.wiring.test.ts tests/ContractDetail.clientOwnedSemantics.wiring.test.ts tests/invoiceQueries.recurringDetailRefresh.wiring.test.ts
• 2026-03-20: Invoice PO assignment-scope unit regression test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/invoiceQueries.purchaseOrderSummary.test.ts
• 2026-03-20: BillingCycles multi-assignment summary wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.billingCyclesSummary.wiring.test.ts
• 2026-03-20: Recurring PO-scope grouping wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.recurringPurchaseOrderScope.wiring.test.ts
• 2026-03-20: Bucket usage ambiguity regression test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/bucketUsageService.periods.test.ts
• 2026-03-20: Contract reports wording wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/ContractReports.summaryCopy.wiring.test.ts tests/contractReportActions.summary.wiring.test.ts tests/contractReportActions.expiration.wiring.test.ts
• 2026-03-20: Reporting/export/accounting assignment-safety audit wiring test run
  • cd packages/billing && npx vitest run --config vitest.config.ts tests/multiActiveContracts.reportingExportAudit.wiring.test.ts
• 2026-03-20: Billing test helper concurrent-assignment fixture wiring test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/billingTestHelpers.concurrentAssignments.wiring.test.ts
• 2026-03-20: Direct concurrent-assignment seeding helper wiring test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/billingTestHelpers.concurrentAssignments.wiring.test.ts src/test/unit/billing/billingTestHelpers.directConcurrentSeed.wiring.test.ts
• 2026-03-20: Legacy test assignment-identity regression wiring test run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/multiActiveContracts.legacyAssignmentTestAssumptions.wiring.test.ts src/test/unit/billing/billingTestHelpers.directConcurrentSeed.wiring.test.ts
• 2026-03-20: Multi-active docs + singleton-regression static guard run
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/docs/multiActiveContracts.docsAndGuards.test.ts
• 2026-03-20: T055 DB-backed integration attempt (environment blocked)
  • cd server && npx vitest run --config vitest.config.ts src/test/integration/billing/contractPurchaseOrderSupport.integration.test.ts --testNamePattern "T055"
  • Local run blocked by ECONNREFUSED to PostgreSQL on localhost:5438.
• 2026-03-20: Remaining checklist static/wiring coverage run (T055/T056/T057/T058/T059/T060/T061/T065/T066/T067/T068/T069/T070/T072)
  • cd server && npx vitest run --config vitest.config.ts src/test/unit/billing/multiActiveContracts.remainingChecklist.wiring.test.ts

Implementation Log

• 2026-03-20: Removed billing wizard/client-dialog active-contract singleton gating (client disable lists, active-contract warning copy, and submit-disable behavior tied to sibling active contracts).
• 2026-03-20: Removed restore/set-active prechecks in both contract shells (ClientContractsTab and legacy Contracts.tsx) so activation no longer blocks on “another active contract exists”.
• 2026-03-20: Removed action/model/shared singleton helper path:
  • deleted checkClientHasActiveContract(...) and fetchClientIdsWithActiveContracts(...) action exports
  • removed updateContract(... status: 'active') active-contract singleton rejection
  • removed shared/model hasActiveContractForClient(...) and getClientIdsWithActiveContracts(...) wrappers
  • removed expired-contract reactivation singleton precheck in shared contract reactivation helper
• 2026-03-20: Updated contract-related billing tests/mocks to align with removed singleton helper exports and revised activation callback signatures.
• 2026-03-20: Routed wizard assignment persistence through shared createClientContractAssignment(...) and removed wizard-local mixed-currency preflight query so create semantics come from shared assignment writes.
• 2026-03-20: Removed shared assignment overlap-window create/update blockers while preserving the clients action-layer invoiced-period guard.
• 2026-03-20: Centralized packages/clients assignment create/update persistence through shared helpers (createClientContractAssignment / updateClientContractAssignment) and removed duplicate overlap enforcement in clients actions/models.
• 2026-03-20: Updated ClientContractAssignment to keep assignment flows keyed by client_contract_id:
  • add/apply now uses the returned assignment id from assignContractToClient(...)
  • removed contract-header de-dup filtering that blocked creating a second active assignment for the same contract_id
• 2026-03-20: Refactored clients contract-line reads to emit assignment-scoped synthetic identity (contract-<client_contract_id>-<contract_line_id>) instead of aliasing raw contract_line_id as client_contract_line_id.
• 2026-03-20: Added synthetic identity parsing in clients contract-line action/model paths so historical invoice guards and mutations can resolve back to underlying contract-line IDs without reintroducing contract-header-only read identity.
• 2026-03-20: Made contract-line mutation scope explicit by requiring assignment-scoped synthetic line identity and failing with an explicit ambiguity error when multiple active assignments share the same contract header.
• 2026-03-20: Added explicit assignment selection context to the clients Contract Lines UI and plumbed selected client_contract_id into add-line payloads.
• 2026-03-20: Wired ClientContractAssignment mutation callbacks into BillingConfiguration (onAssignmentsChanged) so assignment create/edit/deactivate refreshes line/overlap data immediately instead of leaving stale assignment-scoped views.
• 2026-03-20: Scoped client assignment detail metadata to the selected assignment in ClientContract.getDetailedClientContract(...):
  • contract line names/count now come from active client_contract_lines rows filtered by client_contract_id
  • removed contract-header-wide contract_lines lookup that collapsed sibling active assignments sharing a contract_id
• 2026-03-20: Added T030 static wiring coverage (multiActiveContracts.assignmentDetails.wiring.test.ts) asserting assignment-detail data is sourced by client_contract_id and edit dialog consumes selected-assignment line names.
• 2026-03-20: Removed disambiguation guide wording that implied hidden fallback selection (for example “most recently created contract line” and implicit system default picks) and replaced with explicit ambiguity-error/user-choice guidance.
• 2026-03-20: Added T031 static wiring coverage (multiActiveContracts.disambiguationCopy.wiring.test.ts) to prevent fallback copy regressions.
• 2026-03-20: Audited targeted packages/clients UI identity surfaces and removed remaining ambiguous assignment picker labeling in ContractLines by including explicit assignment identity (client_contract_id prefix) in option labels.
• 2026-03-20: Added T032 focused wiring coverage (multiActiveContracts.clientsUiIdentityAudit.wiring.test.ts) asserting assignment picker/state/overlap matrix flows remain keyed to assignment-scoped identities instead of contract_id uniqueness assumptions.
• 2026-03-20: Added T033 regression coverage in server/src/test/unit/billing/recurringDueWorkReader.integration.test.ts proving same-client/same-window recurring rows with different client_contract_id values remain split into separate invoice candidates (with split reasons reflecting single-contract and PO-scope boundaries).
• 2026-03-20: Scoped recurring preview/generation billing selection execution to the selected selector identity in calculateBillingForSelectionInput(...):
  • client-cadence selection now filters persisted recurring timing selections to the selected client_contract_line parsed from selector scheduleKey
  • contract-cadence selection now filters persisted recurring timing selections to the selected contractLineId
  • both paths now fail explicitly when selector-scoped rows are missing instead of silently re-expanding to sibling due work
• 2026-03-20: Added selector-scope regression coverage:
  • T034/T036 in server/src/test/unit/billing/invoiceGeneration.preview.test.ts
  • T035/T037 in server/src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts
  • Expanded both test harness query builders to support whereIn and overloaded where(...) signatures used by selector normalization paths.
• 2026-03-20: Fixed fixed-recurring consolidated parent grouping in persistFixedInvoiceCharges(...) so grouping identity is client_contract_id + client_contract_line_id (assignment-scoped), not line-id-only.
• 2026-03-20: Updated consolidated-plan metadata lookup to query by source line identity while retaining assignment-scoped grouping keys.
• 2026-03-20: Added T038 regression in server/src/test/unit/billing/invoiceService.fixedPersistence.test.ts proving sibling assignments sharing one base contract line persist as separate parent invoice charges with distinct client_contract_id attribution.
• 2026-03-20: Refined client-cadence materialization-gap candidate blocking to match assignment-scoped recurring identities instead of broad client + invoice window keys.
• 2026-03-20: Added T039 regression in server/src/test/unit/billing/recurringDueWorkReader.integration.test.ts proving a materialization gap on one assignment does not block sibling assignment candidates in the same client invoice window.
• 2026-03-20: Preserved explicit single-assignment invoice failure behavior by attaching recurring execution-window context when selector-input generation encounters mixed client_contract_id charge sets.
• 2026-03-20: Added T040 regression in server/src/test/unit/billing/invoiceGeneration.selectorInputGenerate.test.ts proving selector-input generation fails explicitly (with user-readable single-assignment invariant message) when billing charges span multiple assignments.
• 2026-03-20: Enhanced recurring ready-to-invoice contract rendering with explicit assignment-context labels (assignment line/schedule identity fallback) so same-named concurrent contract candidates remain visually distinct.
• 2026-03-20: Added T041 wiring coverage in packages/billing/tests/multiActiveContracts.recurringPreviewIdentity.wiring.test.ts asserting assignment-context rendering tokens are present in AutomaticInvoices.
• 2026-03-20: Corrected fetchInvoicesByContract(...) assignment scoping by filtering invoice reads with invoices.client_contract_id instead of client_contracts.contract_id (header identity), preventing sibling-assignment invoice leakage when one contract header has multiple active assignments.
• 2026-03-20: Updated ContractDetail invoice-tab loading to scope invoice reads by selected clientContractId (fallback first assignment) and clarified assignment-scoped error copy.
• 2026-03-20: Added T042 wiring coverage in packages/billing/tests/multiActiveContracts.invoiceAssignmentScoping.wiring.test.ts asserting invoice query and contract-detail invoice tab use assignment (client_contract_id) identity.
• 2026-03-20: Added T043 unit coverage in server/src/test/unit/billing/invoiceQueries.purchaseOrderSummary.test.ts proving PO context/consumption lookups are keyed by invoice.client_contract_id and do not drift to sibling active assignments.
• 2026-03-20: Updated BillingCycles assignment summary mapping to retain and render all active client_contract_id rows per client (with assignment identity labels) instead of collapsing to the first contract row.
• 2026-03-20: Added T045 wiring coverage in packages/billing/tests/multiActiveContracts.billingCyclesSummary.wiring.test.ts asserting multi-assignment summary rendering path remains active.
• 2026-03-20: Added T044 wiring coverage in packages/billing/tests/multiActiveContracts.recurringPurchaseOrderScope.wiring.test.ts asserting recurring candidate grouping retains purchaseOrderScopeKey = client_contract_id.
• 2026-03-20: Replaced implicit bucket assignment fallback in calculatePeriod(...) by detecting conflicting active assignment matches and throwing an explicit ambiguity error instead of silently choosing one.
• 2026-03-20: Added T046 regression in server/src/test/unit/billing/bucketUsageService.periods.test.ts proving overlapping eligible assignments fail explicitly with actionable assignment context.
• 2026-03-20: Updated Contract Reports summary wording so assignment-based counts are labeled as Active assignments instead of Billable clients.
• 2026-03-20: Added T047 wiring coverage in packages/billing/tests/ContractReports.summaryCopy.wiring.test.ts to prevent report-label regressions that conflate assignment counts with client counts.
• 2026-03-20: Completed reporting/export/accounting audit with focused assignment-safety checks:
  • contractReportActions.ts summary keeps assignment-grain counting (countDistinct client_contract_id) for renewal-decision totals.
  • invoiceQueries.ts PO summary reads invoice header assignment (invoice.client_contract_id) and resolves PO context/consumption by that assignment only.
  • purchaseOrderService.ts consumed/authorized PO lookups are scoped to client_contract_id (not client-level active-contract selection).
  • accountingExportService.ts contains no active-contract singleton selector/helper usage; export execution remains invoice-line authoritative.
• 2026-03-20: Added T048 audit wiring coverage in packages/billing/tests/multiActiveContracts.reportingExportAudit.wiring.test.ts to lock audited assignment-safe semantics and fail if singleton selector helpers reappear in targeted files.
• 2026-03-20: Expanded createFixedPlanAssignment(...) fixture controls for multi-active scenarios with explicit lifecycle knobs:
  • contract header lifecycle (contractHeaderIsActive, contractHeaderStatus)
  • assignment lifecycle (assignmentIsActive, assignmentStatus)
  • assignment PO fields (assignmentPoRequired, assignmentPoNumber, assignmentPoAmount)
  • assignment-line active toggle (clientContractLineIsActive)
• 2026-03-20: Added createConcurrentFixedPlanAssignments(...) helper to seed two or more intentionally concurrent assignment fixtures via one call.
• 2026-03-20: Added T049 wiring coverage in server/src/test/unit/billing/billingTestHelpers.concurrentAssignments.wiring.test.ts asserting lifecycle knobs and concurrent-assignment helper are present and wired.
• 2026-03-20: Added seedConcurrentClientContractAssignmentsDirect(...) helper for explicit direct DB fixture seeding through TestContext.createEntity(...):
  • requires contracts + client_contracts tables
  • supports per-assignment header/assignment lifecycle overrides
  • intentionally bypasses production write paths for tests that need concurrent states directly
• 2026-03-20: Added T050 wiring coverage in server/src/test/unit/billing/billingTestHelpers.directConcurrentSeed.wiring.test.ts asserting direct concurrent seeding uses createEntity(...) on contracts and client_contracts.
• 2026-03-20: Updated legacy integration assertions that previously depended on client_id + first() / latest-row behavior:
  • contractWizard.integration.test.ts now reads client assignment using explicit contract_id: result.contract_id
  • contractPurchaseOrderSupport.integration.test.ts now captures wizard result and reads assignment by explicit contract_id: wizardResult.contract_id (removed orderBy(created_at desc) fallback)
• 2026-03-20: Added T051 wiring coverage in server/src/test/unit/billing/multiActiveContracts.legacyAssignmentTestAssumptions.wiring.test.ts to prevent reintroduction of latest-assignment test assumptions in targeted integration suites.
• 2026-03-20: Updated product docs/runbooks to remove singleton-active assumptions and preserve explicit invoice boundary:
  • docs/billing/billing.md assignment lifecycle section now states concurrent active assignments are allowed (with mixed-currency still blocked as a separate rule)
  • ee/docs/plans/2026-01-05-contract-purchase-order-support/PRD.md now describes invoices.client_contract_id as single-assignment invoice scope (not single-active prerequisite)
  • ee/docs/plans/2026-01-05-contract-purchase-order-support/SCRATCHPAD.md now states one PO per invoice without assuming one active contract per client
• 2026-03-20: Added consolidated static/docs guard coverage in server/src/test/unit/docs/multiActiveContracts.docsAndGuards.test.ts:
  • T052: singleton UI/action guard patterns stay removed
  • T053: billing docs no longer claim active-assignment overlap blocking
  • T054: contract PO plan docs no longer depend on single-active-client prerequisite
  • T062: mixed-currency guard remains explicit and separate from removed singleton helpers
  • T063/T064: repo-wide static guard for removed singleton helper usage
  • T071: runbook notes explicitly record invoice.client_contract_id snapshot boundary and no schema redesign requirement
• 2026-03-20: Added T055 DB-backed integration scenario in contractPurchaseOrderSupport.integration.test.ts:
  • first active assignment via wizard (createClientContractFromWizard)
  • second active assignment via quick-add/action path (createContract + assignContractToClient)
  • asserts same-client active assignments include both contract paths
• 2026-03-20: Added consolidated remaining-checklist guard coverage in server/src/test/unit/billing/multiActiveContracts.remainingChecklist.wiring.test.ts:
  • T056/T057/T058/T059: clients assignment rendering, line add/edit/remove scope, and overlap identity remain assignment-scoped
  • T060/T061: recurring due-work selection and invoice/history reads remain assignment-scoped (client_contract_id)
  • T065: BillingCycles continues rendering multiple active assignments per client
  • T066: bucket ambiguity errors include conflicting assignment context
  • T067: recurring preview displays explicit assignment context for same-named contracts
  • T068: wizard and clients flows both route through shared assignment-create semantics
  • T069: header activation/reactivation paths remain free of sibling-active singleton blockers
  • T070: mixed-currency behavior remains explicitly covered and separate from singleton removal
  • T072: reporting/export/accounting assignment-safe wording and audit coverage remain in place

Links / References

• Related plans:
  • ee/docs/plans/2026-03-18-service-driven-invoicing-cutover/
  • ee/docs/plans/2026-03-20-template-runtime-normalization-completion/
  • ee/docs/plans/2026-01-05-contract-purchase-order-support/
• Product docs:
  • docs/billing/billing.md

Open Questions

• Should the mixed-currency rule remain a separate restriction, or should this plan remove it too?
• For bucket usage ambiguity, should product UX require explicit assignment identity upstream or accept a hard failure at billing time?
• Are there any remaining client-facing surfaces where “contract” is actually intended to mean assignment and should be renamed in this plan?