fix: join-table DB interface uses physical A/B columns (Codec.Encoded)

Implicit M:N join tables were typed in the Kysely DB interface as
Schema.Schema.Type<typeof JoinTable> — the DECODED shape, whose keys are the
semantic *_id names. But Kysely uses DB-interface field names as literal SQL
column identifiers, and an implicit M:N table's physical Postgres columns are
A/B. So `db.selectFrom('_x').where('_x.product_id', ...)` emitted `WHERE
product_id` against an A/B-only table → runtime SQL error.

Emit Schema.Codec.Encoded<typeof JoinTable> instead — the ENCODED shape with
physical A/B keys, carrying the branded columnType values so joins stay
type-safe against the parent table's branded id. The semantic-name mapping
stays only in the schema's Schema.encodeKeys (decode side). Regular model
tables are unchanged.

Tests: unit (encode→{A,B}, decode→{product_id,...}, DB-entry string match) +
pglite integration running the exact previously-broken query
`where('_product_tags.A', '=', productId)` against a real A/B table with
branded values.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: samuelho-dev

.changeset/jointable-db-interface-physical-columns.md

@@ -0,0 +1,21 @@
+---
+'prisma-effect-kysely': patch
+---
+
+Fix: implicit M:N join tables now expose their physical `A`/`B` columns in the
+Kysely `DB` interface.
+
+Kysely uses `DB`-interface field names as literal SQL column identifiers. The
+join-table entry was emitted as `Schema.Schema.Type<typeof JoinTable>`, whose
+keys are the **decoded** semantic names (`product_id`, `product_tag_id`). But an
+implicit many-to-many table's physical Postgres columns are `A`/`B` (Prisma's
+convention), so a query like
+`db.selectFrom('_product_tags').where('_product_tags.product_id', ...)` emitted
+`WHERE product_id` against a table that only has `A`/`B` → runtime SQL error.
+
+The join-table `DB` entry is now `Schema.Codec.Encoded<typeof JoinTable>`, whose
+keys are the **encoded** physical columns `A`/`B` (carrying the branded
+`columnType` values, so joins remain type-safe against the parent table's branded
+id). The semantic-name mapping still lives only in the schema's
+`Schema.encodeKeys`, used when decoding a raw DB row. Regular (non-join) model
+tables are unchanged (`Schema.Schema.Type<typeof Model>`).

CLAUDE.md

@@ -87,6 +87,8 @@ Consumers use `Selectable<typeof User>` / `Insertable<typeof User>` / `Updateabl
 
 Prisma stores `A`/`B` columns; we emit semantic snake_case fields on the struct, then map them to the DB columns with a struct-level `.pipe(Schema.encodeKeys({ <model_a>_id: "A", <model_b>_id: "B" }))`. FK columns are `columnType(Id, Id, Schema.Never)` — insertable (you supply both keys when linking) but read-only on update (composite-PK rows are inserted/deleted, not updated). Join tables get NO branded ID (composite key).
 
+The `DB`-interface entry for a join table uses `Schema.Codec.Encoded<typeof JoinTable>` (the **encoded** `A`/`B` shape), NOT `Schema.Schema.Type` — Kysely uses DB field names as literal SQL identifiers, and the physical columns are `A`/`B`. The semantic `*_id` names exist only on the decode side (`Schema.decode` output). Regular model tables still use `Schema.Schema.Type<typeof Model>`.
+
 ## UUID detection
 
 `isUuidField()` in `src/prisma/type.ts`, priority order:

README.md

@@ -169,6 +169,11 @@ export const ProductToProductTag = Schema.Struct({
 }).pipe(Schema.encodeKeys({ product_id: 'A', product_tag_id: 'B' }));
 ```
 
+In the Kysely `DB` interface the join table is typed by its **encoded** shape
+(`Schema.Codec.Encoded<typeof ProductToProductTag>` → `{ A, B }`), so you query
+the physical columns directly: `db.selectFrom('_product_tags').where('_product_tags.A', '=', productId)`.
+`Schema.decode` of a raw row maps `A`/`B` back to `product_id`/`product_tag_id`.
+
 ## Package Exports
 
 | Entry                            | Contents                                           |

src/__tests__/effect-schema.test.ts

@@ -888,6 +888,25 @@ describe('Effect Schema - Runtime Behavior', () => {
       expect(fieldNamesOf(Updateable(JoinTable))).toEqual([]);
     });
 
+    it('ENCODES to the physical A/B columns (what the Kysely DB interface must use)', () => {
+      // The DB interface is typed `Schema.Codec.Encoded<typeof JoinTable>`, i.e. the
+      // encoded shape — physical Postgres columns A/B. Encoding a semantic row must
+      // produce { A, B } so Kysely emits valid SQL against the real columns.
+      const encoded = Schema.encodeUnknownSync(JoinTable)({
+        product_id: 'p1',
+        product_tag_id: 't1',
+      });
+      expect(Object.keys(encoded).sort()).toEqual(['A', 'B']);
+      expect(encoded).toEqual({ A: 'p1', B: 't1' });
+    });
+
+    it('DECODES from the physical A/B columns back to semantic names', () => {
+      // The decode direction (Schema.Schema.Type) keeps the semantic *_id names —
+      // this is what consumers get from Schema.decode of a raw DB row.
+      const decoded = Schema.decodeUnknownSync(JoinTable)({ A: 'p1', B: 't1' });
+      expect(decoded).toEqual({ product_id: 'p1', product_tag_id: 't1' });
+    });
+
     it('an encodeKeys struct NESTED as a field is not misdetected as generated', () => {
       // An encodeKeys transform exposes a `.from` own-property, same as a
       // generated() field. Generated detection is gated on the GeneratedId

src/__tests__/integration/pglite-roundtrip.test.ts

@@ -155,4 +155,64 @@ describe('pglite roundtrip', () => {
     expect(row.title).toBe('n');
     expect(row.body).toBeNull();
   });
+
+  it('implicit M:N join table is queryable by its physical A/B columns', async () => {
+    // Regression: the Kysely DB-interface type for an implicit M:N join table must
+    // use the ENCODED shape (physical Postgres columns A/B), because Kysely emits
+    // DB-interface field names as literal SQL identifiers. The physical table only
+    // has columns A/B; the semantic *_id names live solely in the Schema's
+    // encodeKeys (decode) mapping. This test runs the exact query that previously
+    // failed — `where('_product_tags.A', ...)` — against a real A/B table.
+    const JoinDDL = `
+      CREATE TABLE "_product_tags" (
+        "A" uuid NOT NULL,
+        "B" uuid NOT NULL,
+        PRIMARY KEY ("A", "B")
+      );
+    `;
+    const ProductId = Schema.String.check(Schema.isUUID()).pipe(Schema.brand('ProductId'));
+    const ProductTagId = Schema.String.check(Schema.isUUID()).pipe(Schema.brand('ProductTagId'));
+    const ProductTags = Schema.Struct({
+      product_id: columnType(ProductId, ProductId, Schema.Never),
+      product_tag_id: columnType(ProductTagId, ProductTagId, Schema.Never),
+    }).pipe(Schema.encodeKeys({ product_id: 'A', product_tag_id: 'B' }));
+
+    // The generator emits this exact DB-interface entry for join tables.
+    interface JoinDB {
+      _product_tags: Schema.Codec.Encoded<typeof ProductTags>;
+    }
+
+    // Branded values, as a real consumer would supply them — the encoded A/B
+    // columns are branded (ProductId/ProductTagId), so the join stays type-safe.
+    const pid = Schema.decodeUnknownSync(ProductId)('11111111-1111-4111-8111-111111111111');
+    const tid = Schema.decodeUnknownSync(ProductTagId)('22222222-2222-4222-8222-222222222222');
+
+    const program = Effect.gen(function* () {
+      const db = (yield* KyselyDb) as Kysely<JoinDB>;
+
+      yield* Effect.tryPromise({
+        try: () => db.insertInto('_product_tags').values({ A: pid, B: tid }).execute(),
+        catch: (cause) => new Error(`insert failed: ${String(cause)}`),
+      });
+
+      // The previously-broken query: reference the PHYSICAL column A.
+      const found = yield* Effect.tryPromise({
+        try: () =>
+          db
+            .selectFrom('_product_tags')
+            .selectAll()
+            .where('_product_tags.A', '=', pid)
+            .executeTakeFirst(),
+        catch: (cause) => new Error(`select failed: ${String(cause)}`),
+      });
+
+      // Decode the raw {A,B} row back to semantic names via the schema.
+      return found ? Schema.decodeUnknownSync(ProductTags)(found) : undefined;
+    });
+
+    const Live = makePgliteLayer<JoinDB>(JoinDDL);
+    const decoded = await Effect.runPromise(Effect.scoped(program.pipe(Effect.provide(Live))));
+
+    expect(decoded).toEqual({ product_id: pid, product_tag_id: tid });
+  });
 });

src/__tests__/kysely-integration.test.ts

@@ -191,10 +191,14 @@ describe('Kysely Integration - Functional Tests', () => {
       expect(dbContent).not.toMatch(/Schema\.Schema\.Encoded/);
     });
 
-    it('should support junction table queries with Schema.Schema.Type pattern', () => {
-      // Junction tables (implicit M2M) should be in DB interface
-      // Example: _product_tags, _CategoryToPost
-      expect(typesContent).toMatch(/_product_tags:\s*Schema\.Schema\.Type<typeof \w+>/);
+    it('should expose junction tables by their ENCODED (physical A/B) shape', () => {
+      // Implicit M2M join tables have physical Postgres columns `A`/`B`. Kysely
+      // uses DB-interface field names as literal SQL identifiers, so the join
+      // table must be typed by its ENCODED shape (Schema.Codec.Encoded → { A, B }),
+      // NOT the decoded Schema.Schema.Type (which has the semantic *_id names used
+      // only for decode output). Emitting the decoded names would make
+      // `db.selectFrom('_x').where('_x.A', ...)` impossible / emit invalid SQL.
+      expect(typesContent).toMatch(/_product_tags:\s*Schema\.Codec\.Encoded<typeof \w+>/);
     });
   });
 

src/kysely/type.ts

@@ -91,7 +91,15 @@ export function generateDBInterfaceEntry(model: DMMF.Model) {
 export function generateJoinTableDBInterfaceEntry(joinTable: JoinTableInfo) {
   const { tableName, relationName } = joinTable;
   const schemaName = toPascalCase(relationName);
-  return `  ${tableName}: Schema.Schema.Type<typeof ${schemaName}>;`;
+  // Use the ENCODED type (the `Schema.encodeKeys` mapping), NOT the decoded
+  // `Schema.Schema.Type`. Kysely uses the DB-interface field names as literal SQL
+  // column identifiers, and an implicit M:N join table's physical columns are
+  // `A`/`B` (Prisma's convention) — not the semantic `*_id` names. The decoded
+  // type has the semantic names (for `Schema.decode` output); the encoded type
+  // keeps `A`/`B` with the branded `columnType` values, so queries like
+  // `db.selectFrom('_x').where('_x.A', ...)` emit valid SQL while joins stay
+  // type-safe against the parent table's branded id.
+  return `  ${tableName}: Schema.Codec.Encoded<typeof ${schemaName}>;`;
 }
 
 /**