Eve library

Deprecations

Guide

Revision 1

On this page

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.
  • 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 §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.