## At a glance

The SQL expression literals project is finished. Raw SQL is one value
everywhere:

```prisma
@@check(expression: sql`
  owner_id > 0
    AND char_length(email) > 0
`, name: "profile_valid")
```

```ts
check({ expression: sql`owner_id > 0 AND char_length(email) > 0`, name: 'profile_valid' });
```

```ts
// generated migration.ts
checkExpression('profile_valid_5901ae2d', sql`owner_id > 0 AND char_length(email) > 0`)
```

This PR closes the project: it deletes
`projects/sql-expression-literals/`, after moving the decisions that
lived only there into ADR 268, and records two lessons from the project
in the team's Drive calibration.

## Decision

The project's transient files go. What must outlive them now lives in
ADRs, the subsystem docs, Drive calibration and Linear:

- **ADR 268** gains four alternatives that were recorded only in the
project's design notes: holding opaque SQL in DDL as the query AST's
`RawExpr`, migration functions that take only `sql` values, leaving
generated migration files on strings, and a public builder for `sql`
values from computed strings. Its status line now lists `sql` values in
generated migration files as built.
- **`drive/calibration/failure-modes.md`** gains F47 (a stack of PRs
outlives its base's squash merge, and the last PR passes 250 commits,
which the DCO check cannot read) and F48 (a new committed contract
fixture fails the planner golden test, which only the merge queue runs).
**`drive/calibration/dod.md`** adds the planner golden step to the slice
gate before queueing.
- **`projects/data-types-completion/design-notes.md`** pointed at this
project's design file; it now points at ADR 231, ADR 254 and TML-3367.

## Where each project decision lives

| Decision (project design notes) | Durable home |
| --- | --- |
| Every place that holds raw SQL takes a `sql` literal | ADR 268, ADR
129 |
| Plain strings are refused | ADR 268 |
| A `sql` literal is a value of the data type `sql/expression`; only
`@default` checks the text | ADR 268, ADR 254, ADR 129 |
| The SQL family defines and registers `sql/expression` (the notes'
first version said each target registers it; the family does) | ADR 268,
ADR 254 |
| The only tag is `sql` | ADR 268, ADR 129 |
| Specs name the data type an argument receives (`dataTypeValue`) | ADR
231, ADR 249, ADR 262 |
| The TypeScript builder takes `sql` values | ADR 268, ADR 129 |
| `contract infer` prints `sql` literals, and skips or notes text that
would not read back | ADR 129, ADR 268 |
| Opaque SQL is its own DDL value, `OpaqueSql` | Migration System
subsystem doc, "Opaque SQL in DDL"; ADR 268 (alternative) |
| Migration files write `sql` values when they read back unchanged | ADR
195 ("Recorded exception"), ADR 268, Migration System doc |
| Wire names keep line breaks in bodies with `--` | ADR 234 |
| One set of codes for cast-rule refusals | ADR 268, ADR 254 |
| The decision gets its own ADR | ADR 268 |
| The typed argument ships first, for the "Data types own column types"
project | Delivered as TML-3367; the default-function argument work is
TML-3389 |
| Grammar versus database values | ADR 231 |

## Project definition of done

- **Delivered:** all seven slices merged.

  | Slice | PR | Linear |
  | --- | --- | --- |
  | 2a | #30534 | TML-3296 |
  | 2t | #30539 | TML-3367 |
  | 1 | #30546 | TML-3287 |
  | 4 | #30554 | TML-3290 |
  | 2b | #30550 | TML-3288 |
  | 3 | #30558 | TML-3289 |
  | 5 | #30677 | TML-3297 |

  Every Linear issue is Done.
- **Review and manual QA:** every slice that changed what a user sees
had design and code reviews, a fixes check, and a manual QA run.
- **Follow-ups filed:**
- TML-3554: two Postgres migration operations paste raw SQL into DDL as
strings.
  - TML-3555: a raw SQL column default cannot hold a `--` comment.

A gap found in QA, `now() - interval '1 day'` failing apply's default
check, is on TML-2362, which replaces that comparison. Two deferred
items need no ticket:
- `contract infer` and defaults that do not read back: slice 3 decided
and built it.
- A builder for `sql` values from computed strings: recorded in ADR 268
as not offered.
- **References:** nothing outside the deleted folder points into it.

## Testing performed

- `pnpm lint:docs`, `pnpm lint:legacy-name` and `pnpm
check:upgrade-coverage --mode pr` pass.
- This PR changes only docs, Drive calibration and the deleted project
folder.

## Linked issue

Closes out the Linear project [SQL expression
literals](https://linear.app/prisma-company/project/sql-expression-literals-c8a6659e7f4c)
(TML-3282).

## Skill update

n/a — docs and project files only.

## Checklist

- [x] All commits are signed off (`git commit -s`) per the
[DCO](../CONTRIBUTING.md#developer-certificate-of-origin-dco).
- [x] I read [CONTRIBUTING.md](../CONTRIBUTING.md) and the change is
scoped to one logical concern.
- [x] Tests are updated (n/a, docs only).
- [x] The PR title is in `TML-NNNN: <sentence-case title>` form.
- [x] The **Skill update** section above is filled in.

## Alternatives considered

- **Keep the project folder as a record.** Rejected: its spec, plan,
design and status describe a project that no longer exists, and the
decisions worth keeping now live in ADRs.
- **Move the design notes into `docs/` as they are.** Rejected: they are
a log written during the project, and each decision now has an ADR or
subsystem-doc home.

Agent: lagertha-65

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified how migration functions and generated migration files
represent SQL, including how DDL is stored and the limits on creating
SQL values from computed strings.
* Updated slice planning guidance to require running the planner golden
test in write mode and reviewing recorded DDL when committed contract
manifests change.
* Added guidance for handling stacked pull requests that exceed the DCO
commit limit and contract-fixture changes that fail merge-queue golden
tests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: willbot <w.a.madden+machine@gmail.com>
Signed-off-by: Will Madden <madden@prisma.io>