# Deprecations

Patterns, libraries, and code paths slated for removal. This doc exists so
contributors don't accidentally add to the to-be-removed set, and so on-call has
a single source of truth when triaging "should I follow this pattern?"
questions.

The format for each entry is:

- **What** — the deprecated thing in one line.
- **Why** — why it's going away.
- **Use this instead** — the replacement.
- **Tracking** — issue or task ID (or "no formal tracking").
- **EOL target** — the quarter/release we want it gone by.

---

## Test runners

### Jest (in 11 packages)

- **What** — `jest.config.*` files in 11 workspaces.
- **Why** — The monorepo has been migrating to Vitest since the jest 29→30 +
  jsdom 24→29 bump landed (#12). Vitest is faster in watch mode, plays better
  with native ESM, and the rest of the workspace already runs on it.
- **Use this instead** — Vitest. Copy a `vitest.config.ts` from a sibling
  workspace and port the test files (mostly `jest.fn`→`vi.fn`,
  `jest.mock`→`vi.mock`, drop `@jest/globals` imports).
- **Tracking** — task #65 covers the svc-auth piece of this; the remaining 10
  are tracked in this doc.
- **EOL target** — Q3 2026.

## Database access

### Raw `pg.Pool` instantiation

- **What** — `new pg.Pool({...})` or `new Pool({...})` outside of
  `libs/shared/database/*`.
- **Why** — Bypasses the platform's metrics, masked DSN logging, uniform
  health-check shape, and pluggable pool implementation. See
  [docs/runbooks/postgres-client-migration.md](runbooks/postgres-client-migration.md).
- **Use this instead** — `createPostgresClient` from `@oshun/database` (or
  `createPostgresClientFromEnv` if the service reads `DATABASE_URL` straight
  from env).
- **Tracking** — task #77 (closed; 18 migrated, 12 documented as
  blocked-on-domain-knowledge in the runbook).
- **EOL target** — Q3 2026.

## Authentication

### Hardcoded dev credentials in env defaults

- **What** — `process.env.MAAT_BOARD_PASSWORD ?? 'board-secret'` and similar
  defaults in any route handler.
- **Why** — Refusing-to-authenticate is safer than a falling back to a guessable
  default when env vars are unset (#59 covered the maat case).
- **Use this instead** — Refuse the request with a 503 +
  `authentication-not-configured` body. The deployment must explicitly set the
  credential variables.
- **Tracking** — task #59 (closed for maat dashboard); apply the same pattern to
  any new admin / privileged endpoint.
- **EOL target** — n/a — pattern policy.

### Webhook handlers without signature verification

- **What** — Payment / OAuth / SMS webhook routes that parse the request body
  without verifying a provider signature header.
- **Why** — Forged webhook bodies can drive financial state changes, unlock
  entitlements, or simulate user actions.
- **Use this instead** — Verify the provider-specific signature header (e.g.
  `stripe-signature`, `X-CCBill-Signature`, `X-Twilio-Signature`) using the
  provider's documented HMAC scheme before processing.
- **Tracking** — task #93 (open).
- **EOL target** — Q3 2026.

## Cryptography

### SHA-1 / MD5 for non-protocol-mandated uses

- **What** — `crypto.createHash('sha1')` / `'md5'` in any new code.
- **Why** — Collision-weak; broken for cryptographic trust.
- **Use this instead** — SHA-256 (`createHash('sha256')`) by default. See
  [SECURITY.md](../SECURITY.md) §Cryptographic Hash Algorithm Policy for the
  approved-protocol-mandated exceptions (HIBP, TOTP, TURN, OAuth 1.0a).
- **Tracking** — task #73 (closed). Existing protocol-mandated sites are
  annotated `stub:legitimate`. The SECURITY.md doc is the master index — any new
  SHA-1/MD5 needs a matching annotation.
- **EOL target** — n/a — pattern policy.

## ESLint rules

### `@typescript-eslint/prefer-nullish-coalescing` on svc-tts / svc-ai / svc-auth

- **What** — The rule is disabled file-pattern-wide in `eslint.config.js` for
  these three packages.
- **Why** — Two reasons: (a) the existing `||` is intentional for
  falsy-default-OK config paths in svc-auth; (b) the rule crashes under our
  typescript-eslint v8 + tsutils combo on svc-tts + svc-ai
  (`TypeError: tsutils.unionConstituents is not a function`).
- **Use this instead** — Once the upstream type-utils fix ships (replace
  `tsutils.unionConstituents` usage), re-enable the rule on all three packages
  and fix the resulting offenders one by one.
- **Tracking** — no formal upstream issue link yet; investigate
  typescript-eslint v8 release notes.
- **EOL target** — Q4 2026 (after the upstream tooling fix lands).

## Documentation patterns

### Per-app `NATIVE_SCAFFOLDING.md` / `IOS_XCODEPROJ.md` / `JEST_FAILURES.md` files

- **What** — Per-app status files like `apps/iris/mobile/IOS_XCODEPROJ.md`,
  `apps/arete/mobile/JEST_FAILURES.md`.
- **Why** — These are scaffolding-gap explanations from audit pass 1; they
  describe what's missing and how to fix it. They should go away once the
  scaffolding lands.
- **Use this instead** — Delete the file the moment the gap is closed (the ios/
  scaffold is in place, the jest suites are green).
- **Tracking** — tasks #57, #61, #62, #70 (each closed as a doc-only fix; the
  underlying gap still needs landing).
- **EOL target** — Per-app — when the scaffolding lands.

---

## Adding to this doc

When you deprecate a pattern:

1. Open the relevant entry above and update it, OR add a new one following the
   template.
2. Mention the deprecation in the PR description so it shows up in release
   notes.
3. If the EOL target is within one quarter, file a tracking task and link it
   here so the owner can plan the work.
