TML-2761: Target-contributed DDL in query AST + marker bootstrap via adapter

[wmadden-electric]

Linked issue

Refs TML-2761 — foundational slice for marker/ledger via typed query AST commands (related: TML-2753, TML-2754, TML-2253).

At a glance

import { col, fn, lit } from '@prisma-next/sql-relational-core/contract-free';
import { buildControlTableBootstrapAsts } from '@prisma-next/target-postgres/contract-free';

// Migration runner / sign() — no raw CREATE TABLE strings in the execution path
for (const ast of family.bootstrapControlTableAsts()) {
  const { sql, params } = family.lowerAst(ast, { contract });
  await driver.query(sql, params);
}

Before this PR, marker/ledger bootstrap executed pre-built SQL strings from statement-builders / sql-marker. After it, each target builds frozen DDL nodes and the control adapter lowers them through the same visitor path as the runtime adapter.

Decision

This PR ships a target-contributed DDL surface in the SQL query AST — separate from DML AnyQueryAst — with per-target visitors in the Postgres and SQLite adapters, contract-free constructors, and marker/ledger bootstrap as the first real consumer.

Deliverables:

1. Family DdlNode base + isAnyDdlNode guard; Postgres CreateTable/CreateSchema, SQLite CreateTable only.
2. Adapter-owned DDL lowering (renderLoweredDdl + per-target visitors); DML renderer switch untouched.
3. Contract-free builders (col/lit/fn, createTable/createSchema) and per-target bootstrap AST factories.
4. Migration runners and sign() route bootstrap through family.lowerAst() — no ensure*Statement in those paths.

Reviewer notes

• Largest diff: adapter DDL visitors + control-bootstrap.ts column shapes. Byte-equality against statement-builders constants is the pin — see packages/3-targets/6-adapters/*/test/migrations/ddl-lowering.test.ts.
• PG lowercase/unquoted bootstrap SQL is intentional — matches existing ensure*Statement output for idempotent bootstrap, not contract-derived DDL.
• ensure*Statement constants remain in statement-builders.ts / sql-marker.ts for tests and golden pins; only the execution paths were rerouted.
• Rejected PR TML-2253: SQL DDL query-AST + contract-free builder + control-table bootstrap through the adapter #661 surface (generic-core ColumnType, shared control-tables.ts) is absent; grep gate included in verification.
• Out of scope: marker DML/SPI consolidation (next slice), planner adoption, Mongo.

How it fits together

1. Separate hierarchy — relational-core/src/ast/ddl-types.ts defines the family DDL base; targets own concrete node classes in their packages.
2. Double-dispatch lowering — adapters widen lower() to AnyQueryAst | TargetDdlNode, routing DDL through renderLoweredDdl and DML through the existing renderer.
3. Contract-free construction — @prisma-next/sql-relational-core/contract-free plus @prisma-next/target-{postgres,sqlite}/contract-free build nodes without a contract.
4. Bootstrap factories — buildControlTableBootstrapAsts() / buildSignMarkerBootstrapAsts() on each target; exposed on SqlControlAdapter and the family instance.
5. First consumer — PG/SQLite migration runners and family sign() lower bootstrap ASTs and execute the result.

Behavior changes & evidence

• DDL lowers through per-target visitors, not the DML switch — packages/3-targets/6-adapters/postgres/src/core/ddl-renderer.ts, packages/3-targets/6-adapters/sqlite/src/core/ddl-renderer.ts. Evidence: packages/3-targets/6-adapters/postgres/test/migrations/ddl-lowering.test.ts, sqlite sibling.
• Contract-free column/table builders — packages/2-sql/4-lanes/relational-core/src/contract-free/column.ts, target contract-free/ddl.ts. Evidence: test/contract-free/ in relational-core and target packages.
• Bootstrap execution path uses adapter lowering — packages/3-targets/3-targets/postgres/src/core/migrations/runner.ts, packages/2-sql/9-family/src/core/control-instance.ts. Evidence: runner error integration tests, family-sql test suite.
• sign() is target-correct for SQLite — no longer calls PG-flavored ensureSchemaStatement / ensureTableStatement from sql-marker.ts.

Testing performed

• pnpm --filter @prisma-next/target-postgres --filter @prisma-next/target-sqlite --filter @prisma-next/adapter-postgres --filter @prisma-next/adapter-sqlite --filter @prisma-next/family-sql typecheck
• Package tests for the five packages above (DDL lowering, contract-free, runner errors, family-sql)
• pnpm fixtures:check (DML lowering byte-identical)
• Slice grep gates: no ColumnType/CreateSchemaAst in relational-core; no ensure*Statement in runner/sign bootstrap paths

Follow-ups

• Marker/ledger DML through adapter (TML-2753 slice)
• Migration planner DDL adoption (TML-2754 slice)
• Mongo marker/ledger (separate slice)

Alternatives considered

• Generic-core DDL in AnyQueryAst (PR TML-2253: SQL DDL query-AST + contract-free builder + control-table bootstrap through the adapter #661) — rejected; SQLite would stub CreateSchema, and a neutral ColumnType enum obscures dialect-native types.
• Shared family-sql control-tables surface — rejected; PG and SQLite marker DDL legitimately differ; each target owns its bootstrap shape.
• Single global DdlVisitor with SQLite no-ops — rejected; per-target visitor interfaces keep SQLite from stubbing schema operations it doesn't have.

Skill update

n/a — internal only (framework/target adapter surface; no user-facing CLI or config change).

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern (foundational DDL-in-AST slice).
• Tests are updated.
• The PR title is in TML-2761: … form.
• Skill update section filled in.

[coderabbitai]

Warning

Review limit reached

@wmadden-electric, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 8 minutes and 29 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 29d146e5-9be4-4093-bf63-9e01db28303a

📥 Commits

Reviewing files that changed from the base of the PR and between 7ff5200 and 82be24b.

⛔ Files ignored due to path filters (9)

• projects/migrate-marker-ledger-to-typed-query-ast-commands/design-notes.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/learnings.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/plan.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/slices/ddl-in-query-ast/plan.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/slices/ddl-in-query-ast/spec.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/slices/sql-marker-ops-through-adapter/plan.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/slices/sql-marker-ops-through-adapter/spec.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/spec.md is excluded by !projects/**
• projects/migrate-marker-ledger-to-typed-query-ast-commands/subagent-registry.md is excluded by !projects/**

📒 Files selected for processing (37)

• packages/2-sql/4-lanes/relational-core/package.json
• packages/2-sql/4-lanes/relational-core/src/ast/ddl-types.ts
• packages/2-sql/4-lanes/relational-core/src/contract-free/column.ts
• packages/2-sql/4-lanes/relational-core/src/exports/ast.ts
• packages/2-sql/4-lanes/relational-core/src/exports/contract-free.ts
• packages/2-sql/4-lanes/relational-core/test/contract-free/column.test.ts
• packages/2-sql/4-lanes/relational-core/tsdown.config.ts
• packages/2-sql/9-family/src/core/control-adapter.ts
• packages/2-sql/9-family/src/core/control-instance.ts
• packages/3-targets/3-targets/postgres/package.json
• packages/3-targets/3-targets/postgres/src/contract-free/control-bootstrap.ts
• packages/3-targets/3-targets/postgres/src/contract-free/ddl.ts
• packages/3-targets/3-targets/postgres/src/core/ddl/nodes.ts
• packages/3-targets/3-targets/postgres/src/core/migrations/runner.ts
• packages/3-targets/3-targets/postgres/src/exports/contract-free.ts
• packages/3-targets/3-targets/postgres/src/exports/ddl.ts
• packages/3-targets/3-targets/postgres/test/contract-free/ddl.test.ts
• packages/3-targets/3-targets/postgres/tsdown.config.ts
• packages/3-targets/3-targets/sqlite/package.json
• packages/3-targets/3-targets/sqlite/src/contract-free/control-bootstrap.ts
• packages/3-targets/3-targets/sqlite/src/contract-free/ddl.ts
• packages/3-targets/3-targets/sqlite/src/core/ddl/nodes.ts
• packages/3-targets/3-targets/sqlite/src/core/migrations/runner.ts
• packages/3-targets/3-targets/sqlite/src/exports/contract-free.ts
• packages/3-targets/3-targets/sqlite/src/exports/ddl.ts
• packages/3-targets/3-targets/sqlite/test/contract-free/ddl.test.ts
• packages/3-targets/3-targets/sqlite/tsdown.config.ts
• packages/3-targets/6-adapters/postgres/src/core/adapter.ts
• packages/3-targets/6-adapters/postgres/src/core/control-adapter.ts
• packages/3-targets/6-adapters/postgres/src/core/ddl-renderer.ts
• packages/3-targets/6-adapters/postgres/test/ddl-create-table-lowering.test.ts
• packages/3-targets/6-adapters/postgres/test/migrations/ddl-lowering.test.ts
• packages/3-targets/6-adapters/sqlite/src/core/adapter.ts
• packages/3-targets/6-adapters/sqlite/src/core/control-adapter.ts
• packages/3-targets/6-adapters/sqlite/src/core/ddl-renderer.ts
• packages/3-targets/6-adapters/sqlite/test/ddl-create-table-lowering.test.ts
• packages/3-targets/6-adapters/sqlite/test/migrations/ddl-lowering.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2253-ddl-in-query-ast

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}