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.tsfrom a sibling workspace and port the test files (mostlyjest.fn→vi.fn,jest.mock→vi.mock, drop@jest/globalsimports). - 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({...})ornew Pool({...})outside oflibs/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.
- Use this instead —
createPostgresClientfrom@oshun/database(orcreatePostgresClientFromEnvif the service readsDATABASE_URLstraight 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-configuredbody. 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 §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.jsfor 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.unionConstituentsusage), 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:
- Open the relevant entry above and update it, OR add a new one following the template.
- Mention the deprecation in the PR description so it shows up in release notes.
- If the EOL target is within one quarter, file a tracking task and link it here so the owner can plan the work.