feat: add schema-aligned db types and test factory primitives

backend/src/api/public/v1/members/createMember.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 
 import { captureApiChange, memberCreateAction, memberEditIdentitiesAction } from '@crowd/audit-logs'
 import { getProperDisplayName } from '@crowd/common'
-import { insertManyMemberIdentities, createMember as insertMember } from '@crowd/data-access-layer'
+import { createMember as insertMember, insertMemberIdentities } from '@crowd/data-access-layer'
 import { MemberIdentityType } from '@crowd/types'
 
 import { optionsQx } from '@/database/sequelizeQueryExecutor'
@@ -49,7 +49,7 @@ export async function createMember(req: Request, res: Response): Promise<void> {
         manuallyCreated: true,
       })
 
-      const dbIdentities = await insertManyMemberIdentities(
+      const dbIdentities = await insertMemberIdentities(
         tx,
         identities.map((identity) => ({
           ...identity,

backend/src/database/repositories/organizationRepository.ts

@@ -16,7 +16,6 @@ import {
   IDbOrganization,
   OrgIdentityField,
   OrganizationField,
-  addOrgIdentity,
   addOrgsToSegments,
   cleanUpOrgIdentities,
   cleanupForOganization,
@@ -27,6 +26,7 @@ import {
   findManyOrgAttributes,
   findOrgAttributes,
   findOrgById,
+  insertOrganizationIdentities,
   markOrgAttributeDefault,
   queryOrgIdentities,
   updateOrgIdentityVerifiedFlag,
@@ -619,16 +619,22 @@ class OrganizationRepository {
   ): Promise<void> {
     const qx = SequelizeRepository.getQueryExecutor(options)
 
-    await addOrgIdentity(qx, {
-      organizationId,
-      platform: identity.platform,
-      source: identity.source,
-      sourceId: identity.sourceId || null,
-      value: identity.value,
-      type: identity.type,
-      verified: identity.verified,
-      integrationId: identity.integrationId || null,
-    })
+    await insertOrganizationIdentities(
+      qx,
+      [
+        {
+          organizationId,
+          platform: identity.platform,
+          source: identity.source,
+          sourceId: identity.sourceId || null,
+          value: identity.value,
+          type: identity.type,
+          verified: identity.verified,
+          integrationId: identity.integrationId || null,
+        },
+      ],
+      false,
+    )
   }
 
   static async getIdentities(

docs/adr/0006-database-schema-types-as-source-of-truth.md

@@ -0,0 +1,61 @@
+# ADR-0006: Database schema types as the source of truth
+
+**Date**: 2026-07-09
+**Status**: accepted
+**Deciders**: Yeganathan S
+
+## Context
+
+Working with entity types in CDP is messy. The same concepts appear as overlapping shapes across `@crowd/types`, DAL inputs, merge helpers, and API/domain models — often incomplete relative to the database, with inconsistent nullability and no single source of truth. That makes it hard to change data access safely, reuse types across packages, and keep tests aligned with production.
+
+We need a durable way to model persisted data that the rest of the codebase can build on, without inventing yet another parallel type family per feature.
+
+## Decision
+
+Treat the database schema as the source of truth for persisted entity shapes. Introduce a dedicated `db/` area under `@crowd/types` for schema-aligned row types, and derive narrower types (create/update payloads, factory options, domain views) from those via composition (`Pick`, `Partial`, `Omit`, intersections) rather than hand-maintaining duplicates.
+
+These types live in `@crowd/types`, not in the data-access layer: they are shared vocabulary for backend, workers, libraries, and test utilities. DAL remains responsible for queries and persistence; it consumes and returns these types instead of owning the canonical shapes.
+
+This applies to entities generally (members, identities, organizations, and others as we touch them), not only the first tables we migrate.
+
+## Conventions
+
+These rules exist so people (and tools) do not confuse the row type with write payloads, or nullability with “field may be omitted.”
+
+1. **One row type per table** — describes the entity as stored. Field nullability matches the schema. Database defaults do not make read fields optional.
+2. **Write payloads are derived from the row type** — use `Pick`, `Partial`, `Omit`, and intersections instead of duplicating the full interface.
+3. **Nullability ≠ optionality** — `| null` means the column can store null; `?` / `Partial` means the caller may omit the key. Both can appear; they mean different things.
+4. **System-owned fields stay off write payloads** — things like tenant id, audit timestamps, and soft-delete markers are set by persistence code, not by every caller.
+5. **Layers that supply defaults may widen further** — e.g. a test factory can take a partial write payload and fill required fields before calling DAL. That does not change the row type or the DAL contract.
+
+## Alternatives Considered
+
+### Alternative 1: Keep defining types ad hoc next to each feature
+- **Pros**: Fast locally; no cross-package coordination.
+- **Cons**: Duplicates and drift continue; nullability and field sets disagree across call sites.
+- **Why not**: That is the current pain. It does not scale as more packages share the same entities.
+
+### Alternative 2: Own canonical entity types inside `@crowd/data-access-layer`
+- **Pros**: Types sit next to SQL; easy for DAL authors to update.
+- **Cons**: Anything that needs a row shape (test-kit, common services, workers, backend) must depend on DAL or re-copy types.
+- **Why not**: Row shapes are shared contracts, not DAL implementation details. Putting them in `@crowd/types` keeps the dependency graph thin and matches how other shared models already live.
+
+### Alternative 3: Generate types from the schema (e.g. introspection tooling)
+- **Pros**: Always in sync with migrations; less manual work.
+- **Cons**: Tooling and review process are not in place; generated output can be noisy and hard to evolve with domain naming.
+- **Why not**: Manual schema-aligned types are enough to establish the pattern now. Generation can be revisited once the convention is stable.
+
+## Consequences
+
+### Positive
+- One place to look for “what does this table look like in TypeScript.”
+- Downstream APIs and tests extend from the same base instead of inventing parallel models.
+- Clearer package boundaries: `@crowd/types` for shapes, DAL for access, factories/services for composition.
+
+### Negative
+- Existing aliases and legacy shapes (`MemberRow`, feature-local inputs, etc.) will coexist during migration.
+- Authors must update `db/` types when migrations change columns or nullability.
+
+### Risks
+- **Partial adoption** — mitigated by migrating types when a table is touched (factories, DAL hardening, new features), not a big-bang rewrite.
+- **Drift from schema** — mitigated by checking live schema (or migrations) when adding or changing `db/` types; optional codegen later.

docs/adr/0007-test-factory-primitives-and-defaults.md

@@ -0,0 +1,83 @@
+# ADR-0007: Test factory primitives and defaults
+
+**Date**: 2026-07-10
+**Status**: accepted
+**Deciders**: Yeganathan S
+
+## Context
+
+Shared test factories are easy to turn into hidden scenario builders: they invent data the test never declared, blur what is under assertion, and drift from the real insert shapes used in production code (see ADR-0006).
+
+We need a simple, durable rule for how test data is created — what the factory does, what defaults may fill, and what the test must own — so the pattern does not divert as more factories are added.
+
+## Decision
+
+Treat test setup as **composition of sharp primitives**, not smart world-builders. Keep three layers separate.
+
+### 1. Primitives
+
+- One job: **persist what they are given**, preferably in bulk, via the DAL.
+- Input stays close to schema insert types (`*DbInsert` and small, explicit extensions when a factory accepts related children in one call).
+- No faker inside primitives. No silent graph scaffolding. No behavioral guesses.
+- When a primitive accepts structured input (for example a hierarchy), it may **derive structural fields** from that shape (links, type/level, denormalized parent labels). That derivation is part of the primitive’s contract — not a default.
+
+### 2. Defaults (opt-in)
+
+- Separate helpers (`withXDefaults`) fill an **allowlist** of missing label / harmless system fields **on rows the caller already wrote**.
+- Call sites opt in: `createX(qx, withXDefaults([...]))`. Defaults are never baked into primitives.
+- Semantics:
+  - **Allowlist only** — unlisted fields are untouched.
+  - **Explicit always wins** — a provided value is never overwritten.
+  - **Only** `undefined` **is missing** — omitted / `undefined` may be filled; `null` **is intentional and sticks**.
+  - **Labels / harmless flags only** — e.g. generated `id`, display names, join timestamps, inactive-path status flags. Ask per field: *if we invent this, could we change which production branch the test hits?* If yes, it does not belong in defaults.
+  - **Caller owns scenario identity** when the value defines the case (names, slugs, platforms, dates, relationship targets, and any field that makes two cases different).
+
+Defaults do **not** build a realistic entity or graph. They only patch allowlisted gaps (e.g. `displayName`, `joinedAt`). Identities, org stints, activities, and other scenario data stay with the test.
+
+### 3. Test composition
+
+- The suite owns behavioral fields and graph shape.
+- Prefer inline fixtures and spreads in the test file.
+- File-local seed helpers only after real repetition; promote into the shared test kit only when a second suite needs the same helper.
+- Do not grow suite-specific “build the whole world” APIs in the shared kit.
+
+This stays aligned with ADR-0006: factories may widen partial write payloads and fill defaults; they do not redefine row or DAL contracts.
+
+## Alternatives Considered
+
+### Alternative 1: Always-on smart factories that scaffold graphs
+
+- **Pros**: Shortest test setup; one call builds a “ready” world.
+- **Cons**: Hides scenario data; easy to pass for the wrong reason; hard to see what a test asserts.
+- **Why not**: Tests must declare behavior. Defaults are ergonomics, not fixtures.
+
+### Alternative 2: No shared defaults — every test passes full insert rows
+
+- **Pros**: Maximum explicitness; zero magic.
+- **Cons**: Noisy boilerplate for ids/labels/flags that rarely matter to the assertion.
+- **Why not**: Opt-in allowlisted defaults keep noise down without hiding scenario data.
+
+### Alternative 3: Defaults baked into every primitive call
+
+- **Pros**: Slightly shorter call sites.
+- **Cons**: Forces defaults even when a test wants raw inserts; harder to see the boundary between persistence and convenience.
+- **Why not**: Opt-in composition keeps primitives sharp and defaults obvious at the call site.
+
+## Consequences
+
+### Positive
+
+- Factories stay readable, composable, and reviewable; scenario intent stays in the test.
+- Same overwrite semantics everywhere (`undefined` fill, `null` preserved, allowlist only).
+- New factories have a clear checklist instead of reinventing “helpful” behavior.
+- Stays aligned with ADR-0006’s insert/row types.
+
+### Negative
+
+- Callers must compose `withXDefaults` explicitly.
+- Suites carry more scenario data in the test file than a mega-helper would.
+
+### Risks
+
+- **Defaults creep** — mitigate by reviewing allowlists against “could this change the branch we hit?” and rejecting behavioral defaults in review.
+- **Scenario helpers leaking into the shared kit** — mitigate by keeping suite-specific seeds file-local until a second suite needs them.

docs/adr/README.md

@@ -12,6 +12,8 @@ Use the `/adr` skill in Claude Code to record new ADRs or query past decisions.
 | [ADR-0003](./0003-deps-bq-table-selection.md) | Use DependencyGraphEdgesLatest for deps ingestion; defer DependenciesLatest until NUGET or GO needed | accepted | 2026-05-29 |
 | [ADR-0004](./0004-go-nuget-transitive-dependent-counts.md) | Compute GO/NUGET transitive dependent counts via exact reverse closure (over HLL approximation) | accepted | 2026-06-23 |
 | [ADR-0005](./0005-pypi-downloads-bigquery-merge-scoping.md) | PyPI downloads via BigQuery bulk export, scoped in the Postgres merge | accepted | 2026-07-01 |
+| [ADR-0006](./0006-database-schema-types-as-source-of-truth.md) | Database schema types as the source of truth | accepted | 2026-07-09 |
+| [ADR-0007](./0007-test-factory-primitives-and-defaults.md) | Test factory primitives and defaults | accepted | 2026-07-10 |
 
 ## Why ADRs?
 

services/apps/members_enrichment_worker/src/activities/enrichment.ts

@@ -36,9 +36,9 @@ import {
 } from '@crowd/data-access-layer/src/old/apps/members_enrichment_worker'
 import OrganizationMergeSuggestionsRepository from '@crowd/data-access-layer/src/old/apps/merge_suggestions_worker/organizationMergeSuggestions.repo'
 import {
-  addOrgIdentity,
   findOrCreateOrganization,
   findOrgByVerifiedIdentity,
+  insertOrganizationIdentities,
 } from '@crowd/data-access-layer/src/organizations'
 import { dbStoreQx, pgpQx } from '@crowd/data-access-layer/src/queryExecutor'
 import { refreshMaterializedView } from '@crowd/data-access-layer/src/utils'
@@ -518,17 +518,23 @@ export async function updateMemberUsingSquashedPayload(
             const mergeSuggestions = []
             const suggestedOwnerIds = new Set<string>()
 
+            const identitiesToInsert = identityOwners
+              .filter((identityOwner) => identityOwner.organizationId !== orgId)
+              .map((identityOwner) => ({
+                organizationId: orgId,
+                platform: identityOwner.identity.platform,
+                value: identityOwner.identity.value,
+                type: identityOwner.identity.type,
+                verified: false,
+                source: orgSource,
+              }))
+
+            if (identitiesToInsert.length > 0) {
+              await insertOrganizationIdentities(qx, identitiesToInsert, false)
+            }
+
             for (const identityOwner of identityOwners) {
               if (identityOwner.organizationId !== orgId) {
-                await addOrgIdentity(qx, {
-                  organizationId: orgId,
-                  platform: identityOwner.identity.platform,
-                  value: identityOwner.identity.value,
-                  type: identityOwner.identity.type,
-                  verified: false,
-                  source: orgSource,
-                })
-
                 const noMergeIds = await mergeSuggestionsRepo.findNoMergeIds(
                   identityOwner.organizationId,
                 )

services/libs/data-access-layer/package.json

@@ -33,7 +33,9 @@
     "validator": "^13.7.0"
   },
   "devDependencies": {
+    "@crowd/test-kit": "workspace:*",
     "@types/node": "^20.8.2",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "vitest": "4.1.7"
   }
 }

services/libs/data-access-layer/src/activities/sql.ts

@@ -9,7 +9,7 @@ import {
   Counter,
   TinybirdClient,
 } from '@crowd/database'
-import { ActivityDisplayService } from '@crowd/integrations'
+import { ActivityDisplayService } from '@crowd/integrations/src/integrations/activityDisplayService'
 import { ActivityTypeSettings, ITimeseriesDatapoint, PageData } from '@crowd/types'
 
 import { getLatestMemberActivityRelations } from '../activityRelations'

services/libs/data-access-layer/src/index.ts

@@ -6,10 +6,12 @@ export * from './dashboards'
 export * from './members'
 export * from './organizations'
 export * from './member-organization-affiliation'
+export * from './member_segment_affiliations'
 export * from './prompt-history'
 export * from './queryExecutor'
 export * from './repositories'
 export * from './security_insights'
+export * from './segments'
 export * from './systemSettings'
 export * from './integrations'
 export * from './auditLogs'
@@ -21,9 +23,6 @@ export * from './osspckgs/maintainers'
 export * from './osspckgs/packages'
 export * from './osspckgs/repos'
 export * from './osspckgs/stewardships'
-export * from './osspckgs/types'
 export * from './osspckgs/versions'
 export * from './osspckgs/nuget'
-export * from './osspckgs/downloads'
-export * from './osspckgs/rubygems'
 export * from './osspckgs/api'