PSA/ee/docs/plans/2026-03-16-client-owned-contracts-simplification/SCRATCHPAD.md

# Scratchpad — Client-Owned Contracts Simplification

- Plan slug: `client-owned-contracts-simplification`
- Created: `2026-03-16`

## What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also update earlier notes when a decision changes or an open question is resolved.

## Decisions

- (2026-03-16) Target model: keep `contracts`, but make every non-template contract client-owned; templates remain the only reusable contract-definition layer.
- (2026-03-16) Invariant choice: one owning client per non-template contract, not one assignment row ever.
- (2026-03-16) Enforcement choice: add `contracts.owner_client_id` instead of inferring ownership only from `client_contracts`.
- (2026-03-16) Migration strategy for shared contracts with invoice history: preserve the original `contract_id` on the invoiced assignment and clone for the other assignment(s).
- (2026-03-16) Migration strategy for shared contracts without invoice history: preserve the original `contract_id` on the earliest-starting assignment and clone for the other assignment(s).
- (2026-03-16) Scope choice: this pass includes the data migration plus backend guardrails and targeted UI/reporting cleanup needed to stop reinforcing the shared-contract model.
- (2026-03-16) Migration sequencing: keep the existing `20260316120000_add_contract_owner_client_id.cjs` schema migration for `owner_client_id`, and run the shared-contract split as a follow-up migration (`20260316121000_client_owned_contracts_simplification.cjs`) so Knex ordering is deterministic.
- (2026-03-16) Safety boundary: clone-target invoice history is allowed and handled by preserved-assignment selection plus `client_contracts` repointing; only contract-scoped docs, pricing schedules, and contract-line history (`time_entries` / `usage_tracking`) are treated as unsupported retargeting for this migration helper pass.
- (2026-03-16) First implementation batch landed the owner-client invariant in creation/assignment code before the shared-contract split migration: nullable schema column first, code guardrails now, stricter DB not-null/backfill later once migrated data is safe.
- (2026-03-16) Legacy `/contracts` API create path should fail at validation/service time when `owner_client_id` is absent, not silently create another shareable non-template header.
- (2026-03-16) Live-status choice: treat `client_contracts` lifecycle as the contract-facing truth and surface assignment-derived status explicitly in billing loaders/UI instead of recalculating or mutating `contracts.status` on read.
- (2026-03-16) Detail-routing choice: resolve client-contract detail from `clientContractId` first and backfill `contractId` into the URL only for header/line/document lookups, keeping live detail assignment-first without rewriting all existing contract loaders at once.

## Discoveries / Constraints

- (2026-03-16) Billing engine already reads through `client_contracts -> contracts -> contract_lines` and filters by assignment truth (`cc.is_active`, assignment dates), which is compatible with the target model as long as cross-client sharing is eliminated.
- (2026-03-16) `ClientContractsTab` currently renders status from `contracts.status`, which is why live UI can disagree with billing behavior.
- (2026-03-16) `contracts` and `client_contracts` both currently carry lifecycle-ish fields, and reports still read “active contracts” from `contracts.is_active`.
- (2026-03-16) Schema currently does not prevent a single non-template `contract_id` from being linked to multiple clients.
- (2026-03-16) The contract wizard already behaves like contracts are client-specific instantiated records and includes a comment that old replication became redundant because contracts are “already client-specific via client_contracts.”
- (2026-03-16) Direct/legacy backend paths still need explicit owner-client guardrails:
  - `packages/billing/src/actions/contractActions.ts#createContract` forwards raw non-template contract creation without owner semantics.
  - `server/src/lib/api/services/ContractLineService.ts#createContract` inserts raw `contracts` rows directly.
  - `packages/clients/src/actions/clientContractActions.ts#createClientContract` validates contract existence and active state but not client ownership.
  - `packages/billing/src/actions/renewalsQueueActions.ts#createRenewalDraftForQueueItem` inserts draft `contracts` rows directly and must carry owner client onto the draft.
- (2026-03-16) Contract-backed client line helpers in both billing and clients packages still derive lines by joining `client_contracts` to `contract_lines` on `contract_id`; they become safe only once shared non-template contracts are eliminated and owner-client enforcement exists.
- (2026-03-16) `ContractDetail` and `ContractDetailSwitcher` still use `contractId` as the primary live-contract identity and show assignment status from `contract.status`, so detail routing and status presentation both reinforce the old shared-contract model.
- (2026-03-16) `ClientContractsTab` and the top-level `Contracts` hub both mutate live state through `updateContract(...status...)`, so assignment lifecycle actions are still wired to contract-header status changes.
- (2026-03-16) Client portal document visibility for contract-linked documents still resolves ownership by joining `document_associations -> contracts -> client_contracts`, so this path needs an explicit regression check after shared contracts are split.
- (2026-03-16) Production has 5 inactive `client_contracts` rows remaining after flipping the previously investigated ConnectWise row active; none of those appear to be historical predecessors of currently active rows.
- (2026-03-16) Production has exactly 2 genuinely shared non-template contracts with multiple contract lines and multiple distinct client assignments:
  - `Managed IT Services` in tenant `Cross Industries, LLC`
  - `Worry-Free Essentials` in tenant `WorryNot Works IT Services`
- (2026-03-16) Accurate blast radius for the two known shared contracts:
  - both have 2 client assignments and 2 contract lines
  - neither has pricing schedules
  - neither has document associations
  - neither has direct `time_entries` or `usage_tracking` tied to those contract-line IDs
  - only `Managed IT Services` has invoice history, and only on the `The Green Thumb` assignment
- (2026-03-16) Contract revenue reporting had one more legacy seam after the live-status UI work: `packages/billing` action code was already mostly assignment-aware, but both report-definition copies (`server` and `packages/reporting`) still counted live contracts from `contracts.is_active`.
- (2026-03-16) The `/api/v1/contracts` and `/api/v2/contracts` surface had drifted behind the new ownership model: the controller still advertised a generic contract list and the list implementation was stubbed. The fix was to return real non-template headers filtered to `owner_client_id` and exclude templates from that resource entirely.
- (2026-03-16) `docs/billing/billing.md` still described `contracts` as a reusable sellable library. Updated it to make templates the only reusable layer, `contracts` the client-owned header table, and `client_contracts` the live lifecycle table.
- (2026-03-16) `BillingEngine#getClientContractLinesAndCycle` remains the core post-migration resolution path for invoiceable contract lines; `T021` now covers preserved-vs-cloned assignments by asserting the same client can only resolve the contract-line set attached to its current `client_contracts.contract_id`.
- (2026-03-16) `server/src/test/unit/billingEngine.test.ts` has broader stale harness failures around the newer `calculateMaterialCharges()` query shape, so the reliable validation for `T021` is a targeted Vitest run of the new assignment-resolution regression instead of the whole legacy file.
- (2026-03-16) The reliable harness for contract-wizard draft resume coverage is a server-side action test with mocked `createTenantKnex`/auth/repository seams; package-local `packages/billing` Vitest still misses the shared `@alga-psa/db` export wiring for this branch.
- (2026-03-16) The renewals queue draft-link regression is likewise best covered from `server` by mocking the transactional knex insert/update path directly; it verifies the owner-client invariant without depending on the package-local alias setup.
- (2026-03-16) `ContractLineService.addContractLine()` is the highest-signal API mutation seam for post-migration contract-line safety: it validates the target contract and source line inside `withTransaction()` before writing the contract-owned mapping, so a focused service unit test covers the legacy `/contracts/:id/lines` path without needing the full controller stack.
- (2026-03-16) Server Vitest coverage output in this worktree can fail on targeted one-file runs when `coverage/.tmp` is missing, even if assertions pass; rerunning the narrow check with `--coverage.enabled false` is the reliable workaround for checklist validation.
- (2026-03-16) `server/src/test/infrastructure/billing/invoices/contractInvoiceManualCredit.test.ts` is the right DB-backed harness for cloned-contract invoice validation, but this workspace does not currently have the test Postgres on `127.0.0.1:5432`, so `T022` could only be implemented and smoke-loaded, not executed end-to-end here.
- (2026-03-16) The migration helper file is strong enough to model the two known production shared-contract scenarios directly. `server/src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts` now uses named fixtures for `Managed IT Services` and `Worry-Free Essentials` to cover preserved assignment choice, clone-target repointing, and clone-line count preservation without needing a live database.
- (2026-03-16) `T032` is covered at the action layer in `server/src/test/unit/contractReportActions.sharedContractResults.test.ts`, which mocks `getContractRevenueReport()` inputs as the two known post-migration shared-contract splits and asserts four client-owned rows come back instead of two shared-contract rows.
- (2026-03-16) Client portal contract-linked document visibility still inferred ownership through `client_contracts`. Updated all 3 portal contract-document branches to resolve through `contracts.owner_client_id` and explicitly exclude templates, so stale shared assignment rows cannot leak documents.
- (2026-03-16) The duplicated `ClientContractLine` helper models in `packages/billing` and `packages/clients` still trusted `client_contracts -> contract_lines` by `contract_id` alone. Added `contracts` joins plus `owner_client_id` and non-template guards on overlap and listing queries so contract-derived helper rows cannot bleed across clients.
- (2026-03-16) The branch already had `F001/F002/F012-F015` runtime wiring in place: `IContract.owner_client_id`, billing dialog/wizard ownership writes, renewal draft ownership propagation, client-assignment ownership checks, and API schema/service ownership validation were already committed before the migration/helper batch.
- (2026-03-16) The missing implementation gap was the shared-contract split itself. Added:
  - `server/migrations/20260316121000_client_owned_contracts_simplification.cjs`
  - `server/migrations/utils/client_owned_contracts_simplification.cjs`
  - `server/src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts`
- (2026-03-16) `ContractDialog`, `createClientContractFromWizard`, and `createRenewalDraftForQueueItem` were all writing raw `contracts` rows without `owner_client_id`; those paths now stamp the client owner explicitly.
- (2026-03-16) `ClientContract.assignContractToClient` and `createClientContract` needed separate ownership checks because they do not share a single repository helper today.
- (2026-03-16) `updateClientContract` already ignored `contract_id` changes; guardrail now rejects cross-client repoint attempts explicitly instead of silently dropping them.
- (2026-03-16) `Contract.getAllWithClients` was still contract-first and still called `checkAndUpdateExpiredStatus`, so the live client-contract list was mutating header state and rendering `contracts.status` instead of assignment lifecycle.
- (2026-03-16) `ContractDetail` already fetched assignment summaries, but the header/overview panels and list actions still treated `contracts.status` as the visible live status and `updateContract(...status...)` as the lifecycle mutation path.
- (2026-03-16) Renewal/default-date normalization in both `shared/billingClients/clientContracts.ts` and `packages/clients/src/models/clientContract.ts` also needed to stop suppressing renewal dates based on `contract_status`; inactive assignment state is the correct lifecycle gate for those computed fields.

## Commands / Runbooks

- (2026-03-16) Find the billing-engine contract-line resolution path:
  - `rg -n "getClientContractLinesAndCycle|Found .* contract lines for client|client_contracts as cc" packages/billing server packages/clients`
- (2026-03-16) Inspect contract vs assignment status/UI usage:
  - `rg -n "contracts.status|client_contracts.is_active|ClientContractsTab|getContractsWithClients" packages server`
- (2026-03-16) Production query used to find inactive assignment rows:
  - query `client_contracts` for `is_active = false`, grouped by tenant/client/contract
- (2026-03-16) Production query used to find genuinely shared contracts:
  - group `client_contracts` by `(tenant, contract_id)` and filter to `count(distinct client_id) > 1`
- (2026-03-16) Production query used to measure blast radius:
  - join shared contract targets to `client_contracts`, `contracts`, `contract_lines`, `invoices`, `time_entries`, `usage_tracking`, `document_associations`, and `contract_pricing_schedules`
- (2026-03-16) Structural plan validation:
  - `python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-03-16-client-owned-contracts-simplification`
- (2026-03-16) Verify assignment-first report wiring:
  - `cd packages/billing && npx vitest run tests/contractReportActions.revenue.assignmentFact.test.ts tests/contractReportActions.summary.wiring.test.ts tests/contractReportActions.expiration.wiring.test.ts`
  - `cd server && npx vitest run src/test/client-owned-contract-report-definitions.test.ts`
- (2026-03-16) Verify contracts-resource semantics and server compile health:
  - `cd server && npx vitest run src/test/client-owned-contracts-resource-semantics.test.ts src/test/client-owned-contract-report-definitions.test.ts`
  - `npx tsc --noEmit -p server/tsconfig.json`
- (2026-03-16) Verify client-owned portal/helper invariants:
  - `cd packages/billing && npx vitest run tests/clientContractLine.ownerInvariant.wiring.test.ts`
  - `cd server && npx vitest run src/test/integration/clientPortalDocuments.integration.test.ts`
- (2026-03-16) Verify billing-engine preserved vs cloned assignment resolution:
  - `cd server && npx vitest run src/test/unit/billingEngine.test.ts -t "T021: resolves preserved and cloned assignment lines from each assignment contract after migration"`
- (2026-03-16) Verify cloned-assignment invoice generation:
  - `cd server && npx vitest run src/test/infrastructure/billing/invoices/contractInvoiceManualCredit.test.ts -t "T022: invoice generation succeeds for a cloned assignment with duplicated contract-line configuration after migration"`
- (2026-03-16) Verify known shared-contract migration sanity cases:
  - `cd server && npx vitest run src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts`
- (2026-03-16) Verify report results keep known split contracts separated:
  - `cd server && npx vitest run src/test/unit/contractReportActions.sharedContractResults.test.ts`
  - `npx tsc --noEmit -p packages/client-portal/tsconfig.json`
  - `npx tsc --noEmit -p packages/clients/tsconfig.json`
  - `npx tsc --noEmit -p packages/billing/tsconfig.json`
- (2026-03-16) Local validation note: `server/src/test/integration/clientPortalDocuments.integration.test.ts` is now updated with real contract-association cases for T045/T046, but it could not run in this workspace because the expected test Postgres on `127.0.0.1:5438` was not available (`ECONNREFUSED`).
- (2026-03-16) Focused ownership + migration verification:
  - `cd server && npx vitest run ../packages/billing/tests/contract.test.ts ../packages/billing/tests/renewalsQueueActions.createDraft.wiring.test.ts ../packages/clients/src/models/clientContract.ownerGuardrails.test.ts ../packages/types/src/interfaces/contractOwnerClient.typecheck.test.ts src/test/unit/api/contractCreateOwnerClientSchema.test.ts src/test/unit/migrations/clientOwnedContractOwnerMigration.test.ts src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts`
- (2026-03-16) Guardrail verification:
  - `npx vitest run tests/contract.test.ts tests/renewalsQueueActions.createDraft.wiring.test.ts` (workdir `packages/billing`)
  - `npx vitest run src/models/clientContract.ownerGuardrails.test.ts` (workdir `packages/clients`)
  - `mkdir -p coverage/.tmp && npx vitest run src/test/unit/api/contractCreateOwnerClientSchema.test.ts src/test/unit/migrations/clientOwnedContractOwnerMigration.test.ts src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts` (workdir `server`)
  - `npx vitest run src/interfaces/contractOwnerClient.typecheck.test.ts` (workdir `packages/types`)
  - `npx tsc -p packages/types/tsconfig.json --noEmit`
  - `npx tsc -p packages/billing/tsconfig.json --noEmit`
  - `npx tsc -p packages/clients/tsconfig.json --noEmit`
  - `npx tsc -p server/tsconfig.json --noEmit`
- (2026-03-16) Live-status/UI verification:
  - `npx vitest run tests/contractsHub.templateSeparation.wiring.test.ts tests/clientContractWorkflowEvents.wiring.test.ts tests/contract.assignmentFirst.wiring.test.ts tests/ClientContractsTab.assignmentLifecycle.test.ts tests/ContractDetail.clientOwnedSemantics.wiring.test.ts tests/clientContractStatus.shared.test.ts tests/clientContractEffectiveRenewalSettings.test.ts` (workdir `packages/billing`)
  - `npx vitest run src/models/clientContract.ownerGuardrails.test.ts` (workdir `packages/clients`)
  - `cd server && npx vitest run ../packages/types/src/interfaces/contractOwnerClient.typecheck.test.ts src/test/unit/api/contractCreateOwnerClientSchema.test.ts src/test/unit/migrations/clientOwnedContractOwnerMigration.test.ts src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts`
  - `npm run typecheck` (workdir `packages/billing`)
  - `npm run typecheck` (workdir `packages/clients`)
  - `npm run typecheck` (workdir `shared`)
- (2026-03-16) Assignment-resolution/report follow-up verification:
  - `cd server && npx vitest run src/test/unit/billingEngine.test.ts -t "T021: resolves preserved and cloned assignment lines from each assignment contract after migration"`
  - `cd server && npx vitest run src/test/unit/migrations/clientOwnedContractsSimplificationMigration.test.ts`
  - `cd server && npx vitest run src/test/unit/contractReportActions.sharedContractResults.test.ts`
  - `cd server && npx vitest run --coverage.enabled false src/test/unit/contractWizardResume.clientOwnedDraft.test.ts`
  - `cd server && npx vitest run src/test/unit/renewalsQueueActions.createDraftBehavior.test.ts`
  - `cd server && npx vitest run src/test/unit/api/contractLineService.clientOwnedMutation.test.ts`

## Progress Log

- (2026-03-16) Completed `F001`/`T001`: added migration `server/migrations/20260316120000_add_contract_owner_client_id.cjs` to add nullable `contracts.owner_client_id` with tenant/client FK and index, without rewriting template rows.
- (2026-03-16) Completed `F002`/`T002`: added `owner_client_id` to shared/server contract interfaces and API contract create/response schemas; added a type contract test.
- (2026-03-16) Completed `F012`/`T013`/`T014`: `Contract.create` now rejects non-template contracts without an owner, while supported billing UI/wizard flows pass the selected client through as `owner_client_id`.
- (2026-03-16) Completed `F013`/`T015`/`T016`: client-contract assignment create/update now reject non-template contracts whose `owner_client_id` is missing or belongs to a different client.
- (2026-03-16) Completed `F014`/`T017`: renewal draft creation now copies the source assignment client onto the draft contract header as `owner_client_id`.
- (2026-03-16) Completed `T021`: added a billing-engine regression that exercises the real `client_contracts -> contracts -> contract_lines` resolution path and proves preserved and cloned assignments resolve different contract IDs and contract-line IDs after the migration split.
- (2026-03-16) Completed `T022`: added a DB-backed invoice-generation regression that seeds preserved and cloned contract headers with duplicated line configuration and asserts the cloned assignment invoices against fresh cloned contract-line IDs with the same billable totals as the preserved assignment.
- (2026-03-16) Completed `T035-T041`: added production-like migration helper coverage for the two known shared contracts, proving the invoiced `Managed IT Services` assignment stays preserved, both clone targets move to fresh contract IDs, clone line counts stay aligned, and the preflight assumption of zero unsupported downstream references still holds for those clone targets.
- (2026-03-16) Completed `T032`: added a report-action runtime test showing the known `Managed IT Services` and `Worry-Free Essentials` splits now appear as four assignment-owned revenue rows, not as two tenant-shared contract rows.
- (2026-03-16) Completed `T042`: added a server-side draft-resume regression showing `getDraftContractForResume()` still returns a client-owned draft contract when the related assignment lifecycle is `renewing`, without inferring that live assignment state back onto the draft header.
- (2026-03-16) Completed `T043`: added a renewals-queue regression showing `createRenewalDraftForQueueItem()` still creates the linked draft contract/client-contract pair after owner-client enforcement and persists `owner_client_id` on the draft header.
- (2026-03-16) Completed `T044`: added a focused `ContractLineService.addContractLine()` regression proving the API/service mutation path still validates the client-owned contract and source line inside the transaction and writes the expected contract-line mapping for cloned non-template contracts.
- (2026-03-16) Completed `F015`/`T018`: legacy API/service contract creation now requires `owner_client_id` via Zod validation plus a service-level runtime check.
- (2026-03-16) Completed `F003-F011` and `T003-T012`: added `server/migrations/20260316121000_client_owned_contracts_simplification.cjs` plus `server/migrations/utils/client_owned_contracts_simplification.cjs` to detect shared non-template contracts, pick the preserved assignment by invoice/earliest-start rules, clone contract headers/lines/configuration rows for clone targets, repoint assignments, backfill `owner_client_id`, and fail closed on invoice/document/pricing/time/usage references that would need explicit historical retargeting.
- (2026-03-16) Completed `F016`/`F017`/`F019-F026` and `T019`/`T020`/`T023-T029`: billing live-contract loaders now read assignment-first rows from `client_contracts`, require `owner_client_id` for normal live rows, derive explicit `assignment_status` through a shared helper, route detail from `clientContractId`, render assignment-first status in list/detail/header UI, mutate lifecycle via `updateClientContractForBilling`, and keep templates visibly separate as the only reusable contract-definition path.

## Links / References

- Core contract model: `/Users/roberisaacs/alga-psa/packages/billing/src/models/contract.ts`
- Contract actions: `/Users/roberisaacs/alga-psa/packages/billing/src/actions/contractActions.ts`
- Contract wizard: `/Users/roberisaacs/alga-psa/packages/billing/src/actions/contractWizardActions.ts`
- Billing engine: `/Users/roberisaacs/alga-psa/packages/billing/src/lib/billing/billingEngine.ts`
- Client contract lifecycle helper: `/Users/roberisaacs/alga-psa/packages/clients/src/lib/clientContractWorkflowEvents.ts`
- Shared assignment status helper: `/Users/roberisaacs/alga-psa/shared/billingClients/clientContractStatus.ts`
- Client contracts UI: `/Users/roberisaacs/alga-psa/packages/billing/src/components/billing-dashboard/contracts/ClientContractsTab.tsx`
- Contracts hub UI: `/Users/roberisaacs/alga-psa/packages/billing/src/components/billing-dashboard/contracts/Contracts.tsx`
- Contract detail routing: `/Users/roberisaacs/alga-psa/packages/billing/src/components/billing-dashboard/contracts/ContractDetailSwitcher.tsx`
- Contract reports: `/Users/roberisaacs/alga-psa/packages/billing/src/actions/contractReportActions.ts`
- Report definitions: `/Users/roberisaacs/alga-psa/server/src/lib/reports/definitions/contracts/revenue.ts`
- Client portal documents: `/Users/roberisaacs/alga-psa/packages/client-portal/src/actions/client-portal-actions/client-documents.ts`
- API controller/service: `/Users/roberisaacs/alga-psa/server/src/lib/api/controllers/ApiContractLineController.ts`, `/Users/roberisaacs/alga-psa/server/src/lib/api/services/ContractLineService.ts`
- Client contract line helpers: `/Users/roberisaacs/alga-psa/packages/billing/src/models/clientContractLine.ts`, `/Users/roberisaacs/alga-psa/packages/clients/src/models/clientContractLine.ts`
- Renewal queue actions: `/Users/roberisaacs/alga-psa/packages/billing/src/actions/renewalsQueueActions.ts`

## Open Questions

- Should a later follow-up fully remove live client semantics from `contracts.status`, or is limiting it to draft/header workflow sufficient?
- Should `/contracts` remain the long-term resource name for client-owned instantiated contract headers, or should a later API cleanup rename that concept?