@tailor-platform/sdk 2.2.0 → 2.4.0

package/docs/services/tailordb-migration.md

@@ -59,7 +59,7 @@ If your local tables and remote schema have **diverged**, reconcile them before
 
 ### Resetting
 
-`tailor tailordb migration generate --init` deletes the existing `migrations/` directory and creates `0000` from the current local types. Use it only before the project is deployed. For a deployed migration history, use [`migration rebaseline`](#re-baselining-a-deployed-migration-history), which verifies the history and connected workspace before replacing any files.
+`tailor tailordb migration generate --init` deletes the existing `migrations/` directory and creates `0000` from the current local tables. Use it only before the project is deployed. For a deployed migration history, use [`migration rebaseline`](#re-baselining-a-deployed-migration-history), which verifies the history and connected workspace before replacing any files.
 
 ## Migration Workflow
 
@@ -115,7 +115,7 @@ A typical change cycle:
 
 ### Warnings and optional migration scripts
 
-Some non-breaking changes can still cause data loss — most notably removing a field (`field_removed`) or removing a table (`type_removed`). `migration generate` reports these as **warnings**:
+Some non-breaking changes can still cause data loss — most notably removing a field (`field_removed`) or removing a table (`table_removed`). `migration generate` reports these as **warnings**:
 
 ```
 Warning: data loss possible:
@@ -139,6 +139,58 @@ tailor tailordb migration script 0002 --no-script --reason "column no longer nee
 
 In an interactive session, `migration generate` offers to record the reason on the spot when it detects warnings. The acknowledgment is stored in `diff.json`, so it is reviewable in the PR, and it satisfies `migration validate --strict` — useful for enforcing in CI that destructive changes are explicitly acknowledged before merge (see [Schema verification](#schema-verification)).
 
+### Renaming a field
+
+Renaming a field in a table definition looks like a removal plus an addition to the diff engine. Left as-is, that combination silently drops the old field's data: the removal is only a warning, so nothing forces a data copy.
+
+To prevent that, when `migration generate` finds a removed field and an added field in the same table whose stored values can be copied without changing their meaning, it asks whether the change is a rename. Serial fields are never rename candidates, and an enum field only qualifies when it keeps every value of the removed field:
+
+```
+? User.fullName was removed and displayName was added with a compatible type. Was it renamed to displayName? (Y/n)
+```
+
+In non-interactive environments (or with `--yes`), no prompt is shown and the command fails while a rename candidate is left unresolved — writing it as remove + add would silently drop the field's data at deploy. Resolve every candidate explicitly: pass the rename, or confirm a genuine removal with `--drop`:
+
+```bash
+tailor tailordb migration generate --rename "User.fullName:displayName"
+tailor tailordb migration generate --drop "User.fullName"
+```
+
+Repeat `--rename` and `--drop` for multiple fields. A `--rename` that does not match a compatible removed + added pair, or a `--drop` that does not match a removed field, fails with an error.
+
+A confirmed rename is recorded as a single `field_renamed` change and treated as **breaking**, so a migration script is required. The generated `migrate.ts` copies the old field into the new one with a single set-based update, and the generated `db.ts` exposes both the old field (readable) and the new field (writable). The copy intentionally overwrites every row without checking for existing values: values of removed fields are retained in storage, so a stale value could otherwise resurface under the new name later. If the new field adds a unique constraint, the script also includes a duplicate-resolution block to run before the constraint is enforced.
+
+During deploy, the pre-migration phase keeps the old field and adds the new field with its constraints relaxed, the script copies the data, and the post-migration phase drops the old field and enforces the new field's constraints — all within a single `tailor deploy`.
+
+If you decline the prompt (or confirm the removal with `--drop`), the change stays a plain removal + addition with the usual data-loss warning.
+
+Renaming a member inside a **nested field** is not detected, and it is quieter: `User.address.zip` → `zipCode` becomes a single `field_modified` on `address` with no breaking change, no warning, and no generated script, so the member's values are not carried over. Copy them with a custom `tailordb migration script` if they must survive.
+
+### Renaming a table
+
+Renaming a whole table is detected the same way: when `migration generate` finds a removed table and an added table with a matching shape, it asks whether the change is a rename:
+
+```
+? User was removed and Person was added with a compatible schema. Was it renamed to Person? (Y/n)
+```
+
+In non-interactive environments the command fails while a candidate is left unresolved, exactly like field renames. Resolve it with the table forms of the same flags (a value without a `.` targets a table):
+
+```bash
+tailor tailordb migration generate --rename "User:Person"
+tailor tailordb migration generate --drop "User"
+```
+
+Two tables qualify as a rename pair only when copying every row preserves the data: every field must keep its name, type, array-ness, required/unique constraints, foreign key target, and decimal scale; enum fields may gain values but not lose them; indexes must match. A self-referential foreign key is compared against the new table name and must be optional. Tables with serial fields (their values cannot be written by a script) or file fields (file contents are not copied) are never candidates. Name-derived and data-independent settings — `pluralForm`, description, table settings, permissions, hooks, and validations — may differ.
+
+A confirmed rename is recorded as a single `table_renamed` change and treated as **breaking** for two reasons: existing records must be copied by the migration script, and the table's GraphQL API names (derived from the table name and `pluralForm`) change, which breaks API clients. The generated `migrate.ts` copies every row from the old table into the new one in id-ordered batches, preserving ids so stored foreign key references stay valid, and the generated `db.ts` exposes both the old table (readable) and the new table (writable). Self-referential foreign keys are inserted as null and backfilled after every row exists, so a reference to a row in a later batch cannot fail the copy.
+
+Two caveats apply to the copy. The old table is not write-protected: rows written to it after the script's transaction commits — and before post-migration cleanup drops it — are not carried over, so pause writers to the renamed table for the duration of the deploy. And platform-managed record metadata (creation/update timestamps and actors) cannot be written by the script, so the new table's records carry the migration run's metadata instead of the original values.
+
+Fields on other tables that reference the renamed table via `foreignKeyType` must be retargeted at the new name in the same change. That retarget is recognized as part of the rename: it is not flagged as a breaking foreign-key change and needs no reference fixup, because record ids are preserved by the copy.
+
+During deploy, the pre-migration phase creates the new table with its full constraints while the old table stays on the namespace, the script copies the rows, and the old table is dropped in post-migration cleanup after the checkpoint advances — all within a single `tailor deploy`.
+
 ### Breaking changes without a script
 
 Breaking changes require `migrate.ts`. If it is missing at deploy time (for example, the generated script was deleted), `tailor deploy` fails before applying the migration or anything after it. When there is genuinely nothing to migrate — say, the affected table holds no data yet — record an explicit acknowledgment instead of keeping an empty script:
@@ -147,7 +199,7 @@ Breaking changes require `migrate.ts`. If it is missing at deploy time (for exam
 tailor tailordb migration script 0002 --no-script --reason "no data yet, safe to skip"
 ```
 
-This stores the reason in `migrations/0002/diff.json` (commit the change). The next `tailor deploy` applies the schema change as usual, skips only the script step, and logs the recorded reason. The command refuses to record a skip while `migrate.ts` exists — delete the script first. If `migrate.ts` is added back later, the script takes precedence over the acknowledgment and runs; run `tailor tailordb migration script 0002` again to clear the now-stale acknowledgment from `diff.json`.
+This stores the reason in `migrations/0002/diff.json` (commit the change). The next `tailor deploy` applies the schema change as usual, skips only the script step, and logs the recorded reason. The command refuses to record a skip while `migrate.ts` exists — delete the script first. If `migrate.ts` is added back later, `tailor deploy` fails rather than choosing between the script and the acknowledgment; run `tailor tailordb migration script 0002` again to clear the now-stale acknowledgment from `diff.json` (the script then runs on the next deploy), or delete `migrate.ts` to keep the skip.
 
 ## Configuration
 
@@ -187,7 +239,7 @@ export default defineConfig({
 
 ### Migration file format compatibility
 
-Migration files are versioned independently of the SDK package. This SDK writes format version `2` and reads versions `1` through `2`. It normalizes supported older formats in memory; it never rewrites applied migration files on disk.
+Migration files are versioned independently of the SDK package. This SDK writes format version `3` and reads versions `1` through `3`. It normalizes supported older formats in memory; it never rewrites applied migration files on disk.
 
 If a future SDK can no longer replay an old migration format, re-baseline while using an SDK version that still supports the complete history, commit the new baseline, deploy it to every environment, and then upgrade the SDK. A file from a newer unsupported format instead requires upgrading the SDK first. The CLI rejects both cases with guidance rather than attempting a best-effort replay.
 
@@ -268,29 +320,56 @@ The `env` values are injected at bundle time (the same mechanism as resolvers/ex
 
 ## Supported Schema Changes
 
-| Change Type                       | Breaking? | Migration Script? | Notes                                                                                                                                                                                                                                  |
-| --------------------------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Add optional field                | No        | No                | Schema change only                                                                                                                                                                                                                     |
-| Add required field                | Yes       | Yes               | Script populates default values                                                                                                                                                                                                        |
-| Remove field                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve or clear data before the field leaves the active schema. The field stays readable from `migrate.ts` during Pre-migration. |
-| Change optional → required        | Yes       | Yes               | Script sets defaults for null values                                                                                                                                                                                                   |
-| Change required → optional        | No        | No                | Schema change only                                                                                                                                                                                                                     |
-| Add index (non-unique)            | No        | No                | Schema change only                                                                                                                                                                                                                     |
-| Add unique index                  | Yes       | Yes               | Script must resolve duplicate value combinations across the index fields                                                                                                                                                               |
-| Change unique index fields        | Yes       | Yes               | Treated like adding a new unique constraint over the new field set                                                                                                                                                                     |
-| Remove index                      | No        | No                | Schema change only (removing the unique constraint from an index is also non-breaking)                                                                                                                                                 |
-| Add unique constraint             | Yes       | Yes               | Script must resolve duplicate values                                                                                                                                                                                                   |
-| Remove unique constraint          | No        | No                | Schema change only                                                                                                                                                                                                                     |
-| Change decimal scale              | Yes       | Yes               | Auto-generated script re-saves existing rows under the new scale. Decreasing scale rounds values half-up and can lose precision. If the same change adds a unique constraint, duplicate handling runs after re-saving.                 |
-| Add enum value                    | No        | No                | Schema change only                                                                                                                                                                                                                     |
-| Remove enum value                 | Yes       | Yes               | Script migrates records with removed values                                                                                                                                                                                            |
-| Add table                         | No        | No                | Schema change only                                                                                                                                                                                                                     |
-| Remove table                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve data before the table leaves the active schema. The table stays readable from `migrate.ts` during Pre-migration.          |
-| Change foreign key target table   | Yes       | Yes               | Script updates references to the new target                                                                                                                                                                                            |
-| Change field type (verified pair) | Yes       | Yes               | In-place for `uuid` → `string`, `enum` → `string`, `decimal` → `string`, and `integer` → `float`; review the generated normalization scaffold and customize it only when existing values need transformation                           |
-| Change field type (other pair)    | -         | -                 | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes)                                                                                                                                                  |
-| Change array → single value       | -         | -                 | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes)                                                                                                                                                  |
-| Change single value → array       | -         | -                 | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes)                                                                                                                                                  |
+| Change Type                       | Breaking? | Migration Script? | Notes                                                                                                                                                                                                                                              |
+| --------------------------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Add optional field                | No        | No                | Schema change only                                                                                                                                                                                                                                 |
+| Add required field                | Yes       | Yes               | Script populates default values                                                                                                                                                                                                                    |
+| Remove field                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve or clear data before the field leaves the active schema. The field stays readable from `migrate.ts` during Pre-migration.             |
+| Rename field                      | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "Table.oldField:newField"` — see [Renaming a field](#renaming-a-field). Auto-generated script copies values from the old field to the new one; both fields coexist during Pre-migration. |
+| Change optional → required        | Yes       | Yes               | Script sets defaults for null values                                                                                                                                                                                                               |
+| Change required → optional        | No        | No                | Schema change only                                                                                                                                                                                                                                 |
+| Add index (non-unique)            | No        | No                | Schema change only                                                                                                                                                                                                                                 |
+| Add unique index                  | Yes       | Yes               | Script must resolve duplicate value combinations across the index fields                                                                                                                                                                           |
+| Change unique index fields        | Yes       | Yes               | Treated like adding a new unique constraint over the new field set                                                                                                                                                                                 |
+| Remove index                      | No        | No                | Schema change only (removing the unique constraint from an index is also non-breaking)                                                                                                                                                             |
+| Add unique constraint             | Yes       | Yes               | Script must resolve duplicate values                                                                                                                                                                                                               |
+| Remove unique constraint          | No        | No                | Schema change only                                                                                                                                                                                                                                 |
+| Change decimal scale              | Yes       | Yes               | Auto-generated script re-saves existing rows under the new scale. Decreasing scale rounds values half-up and can lose precision. If the same change adds a unique constraint, duplicate handling runs after re-saving.                             |
+| Add enum value                    | No        | No                | Schema change only                                                                                                                                                                                                                                 |
+| Remove enum value                 | Yes       | Yes               | Script migrates records with removed values                                                                                                                                                                                                        |
+| Add table                         | No        | No                | Schema change only                                                                                                                                                                                                                                 |
+| Remove table                      | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve data before the table leaves the active schema. The table stays readable from `migrate.ts` during Pre-migration.                      |
+| Rename table                      | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "OldTable:NewTable"` — see [Renaming a table](#renaming-a-table). Auto-generated script copies all rows preserving ids; both tables coexist until post-migration cleanup.                |
+| Change foreign key target table   | Yes       | Yes               | Script updates references to the new target                                                                                                                                                                                                        |
+| Change field type (verified pair) | Yes       | Yes               | In-place for the pairs listed under [Field type changes](#field-type-changes); review the generated normalization scaffold and customize it only when existing values need transformation                                                          |
+| Change field type (other pair)    | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Edit the conversion in the first; the second needs no changes.                                                                     |
+| Change array → single value       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
+| Change single value → array       | -         | -                 | **Not supported** — see [Converting a field type](#converting-a-field-type)                                                                                                                                                                        |
+
+### Field type changes
+
+These pairs change in place, in a single migration:
+
+| From      | To                           |
+| --------- | ---------------------------- |
+| `integer` | `string`, `float`, `decimal` |
+| `float`   | `string`, `decimal`          |
+| `decimal` | `string`, `float`            |
+| `boolean` | `string`                     |
+| `uuid`    | `string`                     |
+| `enum`    | `string`                     |
+
+Every pair here accepts every value its source type allows, which is what lets the change happen in one migration: the field keeps its previous type until the migration finishes, so your application can keep writing to it throughout.
+
+Every other scalar pair needs a temporary field. Eligible fields can use the generated [expand-contract pair](#converting-a-field-type); fields the generator rejects still need the manual three-step sequence described below. Three groups are worth calling out:
+
+- Converting to a narrower type — `string` → `integer`, `string` → `uuid`, `integer` → `boolean` and similar — is excluded because values the source type still accepts, such as `"abc"` in a `string` field, cannot be cast. Your script could clean up the rows it sees, but the field goes on accepting new uncastable values until the migration completes.
+- `boolean` → `integer`, `float` → `integer`, and `string` → `date` are excluded because the stored values cannot be cast to the new type.
+- `date`, `datetime`, and `time` fields are not stored in the textual form you wrote them in, so converting them to or from another type reads back as a different instant. Convert them through a temporary field where your script controls the formatting.
+
+Converting to `decimal` reformats values to the field's scale, so `42` reads back as `42.000000`. Values with more decimal places than the scale allows are rounded half-up, so `1.1234567` becomes `1.123457` at the default scale of 6.
+
+A `float` field that is already unique cannot convert to `decimal` in place, because rounding can turn two distinct values into the same one and the existing constraint leaves no room to resolve the collision. Use the 3-step migration for those.
 
 ### Generated normalization script for field type changes
 
@@ -337,17 +416,40 @@ export async function main(trx: Transaction): Promise<void> {
 
 The generated `never` annotation intentionally causes a TypeScript error until you review the normalization. If the existing values are already suitable for the target type, remove the annotation and review marker to accept the identity transformation; it does not write any rows. If values need application-specific normalization, replace the expression and remove the annotation and marker while keeping the result valid for both the active source type and the target type. The source field contract remains active until the script finishes; for example, an `integer` → `float` script cannot write fractional values during this phase.
 
-### 3-step migration for unsupported changes
+### Converting a field type
+
+A field type change outside the verified in-place pairs — `string` → `integer`, for example — cannot be applied in one step, because the field would have to hold both shapes at once. `migration generate` offers to carry the values through a temporary field instead:
+
+```
+User.price changes from string to integer, which cannot be applied in one step.
+? Generate two migrations to convert User.price through a temporary field? (Y/n)
+```
+
+Confirming writes two migrations:
+
+1. **The conversion.** Adds a temporary field (`priceMigrate`), converts each stored value into it, and clears and removes the original field. Edit the conversion expression before deploying: the generated `never` annotation fails your typecheck, and `tailordb migration validate` rejects the migration while the review marker is still there.
+2. **The rename.** Renames the temporary field back to `price`. Its copy script is complete, but this migration also carries every other schema change the same run picked up, so review it as you would any generated migration.
+
+`tailor deploy` applies both. Because the conversion only touches rows whose original value is still set, a re-run resumes where it stopped rather than converting a row twice.
+
+The original field is removed in the first migration rather than the second, because the rename needs its name free. Your script can still read it while the conversion runs.
+
+In a non-interactive run — `--yes`, or CI — name each field explicitly:
+
+```bash
+tailor tailordb migration generate --yes --expand-contract "User.price"
+```
+
+Without the flag the command fails rather than converting anything, so a scripted run cannot start a two-migration change by accident.
 
-Field type changes outside the verified in-place pairs (for example, `string` → `integer`) and array-cardinality changes are detected but rejected by the diff engine. Use an expand-contract strategy:
+> **Why the conversion clears the original field.** Removing a field from the schema does not necessarily remove its stored value. Reusing the name for an incompatible type while a stale value remains can deploy successfully and then make subsequent reads fail. Clearing the original in the same update is what prevents that, which is why the generated script writes both fields at once.
 
-1. **Migration N**: Add an optional field with the desired type (e.g., `fieldName_new`). If the old field is required, make it optional in the same migration. Write a script that copies and converts every non-null old value into the temporary field, then sets the old field to `null` in the same row update.
-2. **Migration N+1**: Remove the old field.
-3. **Migration N+2**: Add the field back with the original name and the new type. Script copies from the temporary field, then remove the temporary field in migration N+3 (or in the same step if you can express it).
+> **Writes that land while the conversion runs are not carried across.** The original field keeps its old type until the conversion finishes, so an application can still write to it after the script has read the last row — and that value is dropped with the field rather than converted. Stop writes to the field, or accept the loss, before deploying a conversion on a live workspace.
 
-The same pattern works for switching between scalar and array.
+Some changes are still rejected and need a temporary field you add yourself — add the new field, write a script that fills it and clears the old one, then remove the old field and rename the temporary one in a later migration:
 
-> **Do not skip clearing the old field.** Removing a field from the schema does not necessarily remove its stored JSON value. Re-adding the same name with an incompatible type can deploy successfully while leaving stale values that make subsequent reads fail. Verify that every old value is `null` before removing and re-adding the field name.
+- Array-to-scalar and scalar-to-array, since collapsing an array has no answer the generated script could choose for you.
+- A field that is unique, or that an index, relationship, permission, or table-level script names. Those keep pointing at the original name, which the conversion removes.
 
 ## Testing Pending Migrations
 
@@ -363,25 +465,25 @@ The command performs the following sequence:
 6. Optionally runs an assertion script against the migrated data.
 7. Deletes an automatically-created workspace after success or failure.
 
-Both the pre-migration and final TailorDB schemas come from committed migration snapshots. Ungenerated changes in the current type source are not included in the rehearsal.
+Both the pre-migration and final TailorDB schemas come from committed migration snapshots. Ungenerated changes in the current table definitions are not included in the rehearsal.
 
 Executors are omitted from the baseline deployment so loading fixture or cloned records cannot trigger current event handlers against the older schema. Auth user profiles are also deferred until the pending migrations finish, while configured machine users remain available to run seed and migration scripts. The final deployment restores the configured executors and user profiles. Static websites are deployed so configuration references to their URLs resolve, but their workspace-bound custom domains are omitted from migration-test deployments.
 
 ### Seed mode
 
-Seed mode is the default and uses the JSONL files produced by the configured `seedPlugin`. Run `tailor generate` after adding the plugin or changing seed types, then populate its `data/*.jsonl` files:
+Seed mode is the default and uses the JSONL files produced by the configured `seedPlugin`. Run `tailor generate` after adding the plugin or changing seed tables, then populate its `data/*.jsonl` files:
 
 ```bash
 tailor tailordb migration test --data seed
 ```
 
-Rows are loaded only for types present in the deployed pre-migration snapshots (and current schemas without migrations), in foreign-key dependency order. Fields introduced by pending migrations, including timestamp and nested fields, are removed before insertion so current fixtures can be loaded into the baseline schema. Missing type files are treated as empty. IdP `_User` fixtures are not loaded by this command.
+Rows are loaded only for tables present in the deployed pre-migration snapshots (and current schemas without migrations), in foreign-key dependency order. Fields introduced by pending migrations, including timestamp and nested fields, are removed before insertion so current fixtures can be loaded into the baseline schema. Missing table files are treated as empty. IdP `_User` fixtures are not loaded by this command.
 
 Use `--machine-user` to override the seed plugin's `machineUserName`, the namespace migration setting, and the first configured Auth machine user for seed and assertion execution.
 
 ### Clone mode
 
-Clone mode copies TailorDB records from the source workspace after the identical application, namespace names, and pre-migration schemas exist in the target. For namespaces without migration history, the command reproduces the deployed source schema rather than uncommitted local type changes:
+Clone mode copies TailorDB records from the source workspace after the identical application, namespace names, and pre-migration schemas exist in the target. For namespaces without migration history, the command reproduces the deployed source schema rather than uncommitted local table changes:
 
 ```bash
 tailor tailordb migration test --data clone
@@ -428,10 +530,10 @@ When you run `tailor deploy`, the SDK detects pending migrations (anything past
 
 For each pending migration:
 
-1. **Pre-migration**: Schema changes that would be breaking are applied in a relaxed form first. A verified in-place field type change keeps its complete previous field contract until Post-migration, including field and type-level hooks or validators changed by the same migration. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the table so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped). Breaking type-level index changes are relaxed the same way: a newly-added unique index is withheld, and an index gaining a unique constraint (or a unique index changing its field set) keeps its previous definition, so `migrate.ts` can resolve duplicates first. Non-breaking changes that are part of the same migration are also applied here.
+1. **Pre-migration**: Schema changes that would be breaking are applied in a relaxed form first. A verified in-place field type change keeps its complete previous field contract until Post-migration, including field and table-level hooks or validators changed by the same migration. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the table so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped). For a renamed field, the old field is kept and the new field is added with its constraints relaxed, so the script can read the old field and write the new one. For a renamed table, the new table is created with its full constraints while the old table stays on the namespace until post-migration cleanup, so the script can copy rows between them. Breaking table-level index changes are relaxed the same way: a newly-added unique index is withheld, and an index gaining a unique constraint (or a unique index changing its field set) keeps its previous definition, so `migrate.ts` can resolve duplicates first. Non-breaking changes that are part of the same migration are also applied here.
 2. **Script execution**: If `migrate.ts` exists on disk for this migration, it is bundled and sent to the platform via the script execution API and runs as the configured machine user inside a transaction. The script is hard-required for breaking changes (`diff.requiresMigrationScript`) — deploy fails if the file is missing, unless a `--no-script` acknowledgment was recorded (see [Breaking changes without a script](#breaking-changes-without-a-script)). It is also executed when present for warning-tier diffs — see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts).
 3. **Post-migration schema**: Required constraints and the target field definitions are applied. Do not assume that removing a field clears its underlying stored JSON value.
-4. **Checkpoint and cleanup**: The `sdk-migration` label is bumped to this migration's number, then removed GQL permissions and tables are deleted. Advancing the checkpoint first prevents a failed checkpoint write from requiring the SDK to recreate irreversibly deleted records.
+4. **Checkpoint and cleanup**: The `sdk-migration` label is bumped to this migration's number, then removed GQL permissions and tables — including the old table left behind by a rename — are deleted. Advancing the checkpoint first prevents a failed checkpoint write from requiring the SDK to recreate irreversibly deleted records.
 
 This split is what allows existing rows to be backfilled before the database starts rejecting nulls, and what lets `migrate.ts` traverse foreign-key fields that the same migration removes.
 
@@ -449,7 +551,7 @@ On drift you'll see something like:
 Namespace: tailordb
   Remote migration: 0007
   Differences:
-  Type 'User':
+  Table 'User':
     - Field 'email': required: remote=false, expected=true
 ```
 
@@ -463,7 +565,7 @@ tailor tailordb migration validate
 
 It reports issues per namespace, exits with a non-zero code when any check fails, and supports `--json` for machine-readable output.
 
-With `--strict`, validation additionally fails when a migration not yet applied to the remote has data-loss warnings (see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts)) but neither a `migrate.ts` nor a recorded `--no-script` acknowledgment. The failure names the affected type and field and prints the exact command to record the acknowledgment.
+With `--strict`, validation additionally fails when a migration not yet applied to the remote has data-loss warnings (see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts)) but neither a `migrate.ts` nor a recorded `--no-script` acknowledgment. The failure names the affected table and field and prints the exact command to record the acknowledgment.
 
 To bypass both checks during deploy (not recommended outside of recovery scenarios):
 
@@ -493,7 +595,7 @@ Before running it:
 
 1. Apply the latest migration to every environment. The CLI verifies the connected workspace, but it cannot inspect other workspaces.
 2. Commit or otherwise preserve the existing migration history. Files after `0000`, including `migrate.ts` and `db.ts`, disappear from the working tree; Git history retains committed files.
-3. Make sure local type changes have been captured with `tailor tailordb migration generate`.
+3. Make sure local table changes have been captured with `tailor tailordb migration generate`.
 
 Then re-baseline one namespace:
 
@@ -501,7 +603,7 @@ Then re-baseline one namespace:
 tailor tailordb migration rebaseline --namespace tailordb
 ```
 
-The command validates the migration files, verifies that replaying the latest migration exactly reproduces the local types, and checks that the connected workspace is at that latest migration with no schema drift. After confirmation, it replaces the local history with the reconstructed baseline, records a new migration history ID in both `0000/schema.json` and remote metadata, and resets the connected workspace's `sdk-migration` label to `0000`. Use `--yes` only after arranging the same operational preconditions in non-interactive automation.
+The command validates the migration files, verifies that replaying the latest migration exactly reproduces the local table definitions, and checks that the connected workspace is at that latest migration with no schema drift. After confirmation, it replaces the local history with the reconstructed baseline, records a new migration history ID in both `0000/schema.json` and remote metadata, and resets the connected workspace's `sdk-migration` label to `0000`. Use `--yes` only after arranging the same operational preconditions in non-interactive automation.
 
 Commit the resulting `migrations/` change before generating any new migrations. For another environment still carrying the exact checkpoint and history ID that the new baseline replaced, the next `tailor deploy` checks whether its remote schema exactly matches the new `0000`. If it does, deploy offers to reset the checkpoint to `0000` and move the environment to the new history ID before applying any later local migrations. A markerless history is eligible only for the first rebaseline, at the exact migration recorded as replaced. Any other checkpoint or history ID is rejected without changing remote metadata, even if its schema happens to match the baseline.
 

package/docs/services/tailordb.md

@@ -309,11 +309,11 @@ db.string().hooks({
 });
 ```
 
-Field-level hooks operate on a single field and cannot access other fields. Use type-level hooks for cross-field logic.
+Field-level hooks operate on a single field and cannot access other fields. Use table-level hooks for cross-field logic.
 
-#### Type-level Hooks
+#### Table-level Hooks
 
-Set hooks across multiple fields using `db.table().hooks()`. The hook returns an object with the fields to override. When both field-level and type-level hooks exist for the same field, type-level hooks take priority.
+Set hooks across multiple fields using `db.table().hooks()`. The hook returns an object with the fields to override. When both field-level and table-level hooks exist for the same field, table-level hooks take priority.
 
 Create hooks receive:
 
@@ -356,7 +356,7 @@ export const order = db
   });
 ```
 
-**Note:** `.hooks()` can only be called once on a table. Duplicate type-level calls fail at compile time and throw at runtime.
+**Note:** `.hooks()` can only be called once on a table. Duplicate table-level calls fail at compile time and throw at runtime.
 
 ### Validation
 
@@ -380,7 +380,7 @@ db.string().validate(
 );
 ```
 
-#### Type-level Validation
+#### Table-level Validation
 
 Set a validator across all fields using `db.table().validate()`. The validator receives `{ newRecord, oldRecord, invoker }` and an `issues()` callback to report errors per field:
 
@@ -415,7 +415,7 @@ For datetime/date/time fields, pass `"now"` to use the operation timestamp:
 db.datetime().default("now");
 ```
 
-**Note:** `.validate()` can only be called once on a table. Duplicate type-level calls fail at compile time and throw at runtime.
+**Note:** `.validate()` can only be called once on a table. Duplicate table-level calls fail at compile time and throw at runtime.
 
 ### Vector Search
 
@@ -450,7 +450,7 @@ export const user = db.table("User", {
 
 ## Table Modifiers
 
-Table builder methods that set one type-level configuration can be called only once on the same table. Duplicate calls fail at compile time and throw at runtime. This applies to `.description()`, `.hooks()`, `.validate()`, `.features()`, `.indexes()`, `.files()`, `.permission()`, and `.gqlPermission()`.
+Table builder methods that set one table-level configuration can be called only once on the same table. Duplicate calls fail at compile time and throw at runtime. This applies to `.description()`, `.hooks()`, `.validate()`, `.features()`, `.indexes()`, `.files()`, `.permission()`, and `.gqlPermission()`.
 
 Conditional assignment is still supported when only one branch calls the method:
 

package/docs/services/workflow.md

@@ -248,6 +248,8 @@ export const approval = createWaitPoint<
 >("approval");
 ```
 
+Keys must match `[a-z0-9-]`, be 3 to 63 characters long, and start and end with `[a-z0-9]`.
+
 For multiple wait points, use `createWaitPoints` with a builder callback. Property names become wait point keys, and JSDoc on each property is preserved in IDE autocompletion:
 
 ```typescript
@@ -255,9 +257,19 @@ import { createWaitPoints } from "@tailor-platform/sdk";
 
 export const waitPoints = createWaitPoints((define) => ({
   /** Manager approval step */
-  managerApproval: define<{ amount: number }, { approved: boolean }>(),
+  "manager-approval": define<{ amount: number }, { approved: boolean }>(),
   /** Finance review step */
-  financeReview: define<{ invoiceId: string }, { validated: boolean }>(),
+  "finance-review": define<{ invoiceId: string }, { validated: boolean }>(),
+}));
+
+await waitPoints["manager-approval"].wait({ amount: 50000 });
+```
+
+Pass the key to `define` when the property name you want to read at the call site is not a valid key:
+
+```typescript
+export const waitPoints = createWaitPoints((define) => ({
+  managerApproval: define.for("manager-approval")<{ amount: number }, { approved: boolean }>(),
 }));
 
 await waitPoints.managerApproval.wait({ amount: 50000 });
@@ -335,6 +347,44 @@ export default createResolver({
 
 Wait points can be imported and used in any file (workflow jobs, resolvers, executors). For local testing, see [Jobs that wait on approval](../testing.md#jobs-that-wait-on-approval) in the testing guide.
 
+### Keys With Runtime Values
+
+A wait point key identifies one suspension inside one execution. When a job suspends more than once for the same reason — one approval per order line, one per approver — every suspension needs its own key, otherwise the second `wait()` fails because a suspension with that key is already pending.
+
+Write `$paramName` as a whole `-`-delimited segment of the key to leave a slot for a runtime value — `line-approval-$lineId` works, `line-approval$lineId` does not. Declare such a key through `createWaitPoints`, passing it to `define` **before** the `Payload` and `Result` type arguments — the param names then become the argument of `.with()`, which builds the concrete key:
+
+```typescript
+export const { lineApproval } = createWaitPoints((define) => ({
+  lineApproval: define.for("line-approval-$lineId")<{ message: string }, { approved: boolean }>(),
+}));
+
+// Suspends on "line-approval-<lineId>", so parallel lines never collide
+const result = await lineApproval.with({ lineId: line.id }).wait({ message: "Please approve" });
+```
+
+The key has to come before the type arguments because TypeScript stops inferring it as a literal type once `Payload` and `Result` are given explicitly, and the param names can only be read off a literal. `createWaitPoint` takes its type arguments first, so it cannot type `$params` at all, and `deploy` rejects such a key — one wait point per key is what it is for, and a key with `$params` stands for a family of them.
+
+`deploy` checks every declared key against the grammar above, so a key the platform would reject is reported before anything is deployed.
+
+A parameterized wait point exposes only `.with()` — there is no way to wait on the unsubstituted key.
+
+Resolve it from the same param values:
+
+```typescript
+await lineApproval.with({ lineId: input.lineId }).resolve(input.executionId, (payload) => {
+  console.log("Resolving:", payload.message);
+  return { approved: input.approved };
+});
+```
+
+Rules to keep in mind:
+
+- Param values must match `[a-z0-9-]`, cannot be empty, and cannot start or end with `-`. Record IDs work as-is; uppercase or underscored values do not.
+- The composed key still has to fit 63 characters. A UUID takes 36, so a key holding one leaves 26 characters for everything else.
+- The key needs at least one literal segment alongside its `$params`, so `"$lineId"` alone is rejected: a key made only of caller data carries no identity of its own.
+- Param values are part of the key, so they must be derived from the job's input. A value from `Date.now()` or `Math.random()` changes when the platform replays the job and the execution fails.
+- Keys are compared exactly, and the SDK does not check whether two declared keys can produce the same string. `"a-$x"` with `x = "b-c"` and `"a-b-$y"` with `y = "c"` both produce `a-b-c`. Keep the literal part of each key distinct, and prefer putting `$params` last.
+
 ## Retry Policy
 
 You can configure automatic retry behavior with exponential backoff by setting `retryPolicy` on a workflow. All fields are required when `retryPolicy` is set:

package/docs/testing.md

@@ -180,6 +180,18 @@ await approvalWaitPoint.wait({ message: "Please approve" });
 expect(approvalMock.wait).toHaveBeenCalledWith({ message: "Please approve" });
 ```
 
+For a wait point whose key contains `$params`, use `waitPointWith(definition, params)` to control one param binding at a time. Calls made with any other binding fall through to the platform mock:
+
+```typescript
+using wf = mockWorkflow();
+const lineOne = wf.waitPointWith(lineApproval, { lineId: "line-1" });
+
+lineOne.wait.mockResolvedValue({ approved: true });
+await lineApproval.with({ lineId: "line-1" }).wait({ message: "Please approve" });
+
+expect(lineOne.wait).toHaveBeenCalledWith({ message: "Please approve" });
+```
+
 Use `wf.setEnv(...)` when locally-run workflow job bodies need configuration values. Per-run `runWorkflowLocally(..., { env })` options take precedence over the mock's env.
 
 ### SecretManager Mock
@@ -649,7 +661,7 @@ describe("retryFailedWorkflow resolver", () => {
 
 ### Testing Executors
 
-Function-kind executors expose their handler as `executor.operation.body(args)`. The shape of `args` is determined by the trigger — for example, `recordCreatedTrigger({ type: user })` produces `{ newRecord }` typed against the type's output, plus runtime fields such as `env`, `actor`, and `invoker`. GraphQL, webhook, and workflow operation kinds are declarative and don't expose a user-authored body to test.
+Function-kind executors expose their handler as `executor.operation.body(args)`. The shape of `args` is determined by the trigger — for example, `recordCreatedTrigger({ type: user })` produces `{ newRecord }` typed against the table's output, plus runtime fields such as `env`, `actor`, and `invoker`. GraphQL, webhook, and workflow operation kinds are declarative and don't expose a user-authored body to test.
 
 The `executor` template extracts shared DB access into a helper (`shared.ts`) and tests the helper directly against a mocked `tailordb.Client` (same TailorDB-mocking pattern as the resolver section). Executor handlers themselves stay thin and can be tested by spying on the helper:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -169,7 +169,7 @@
     "@secretlint/secretlint-rule-preset-recommend": "13.0.4",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@toiroakr/lines-db": "0.11.0",
+    "@toiroakr/lines-db": "0.12.2",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.11",
@@ -191,7 +191,7 @@
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.1",
     "politty": "0.11.6",
-    "rolldown": "1.2.0",
+    "rolldown": "1.2.4",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.2.0",
@@ -207,7 +207,7 @@
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.10",
-    "eslint-plugin-zod": "4.9.0",
+    "eslint-plugin-zod": "4.9.1",
     "oxfmt": "0.61.0",
     "oxlint": "1.76.0",
     "oxlint-tsgolint": "7.0.2001",
@@ -215,9 +215,9 @@
     "tsdown": "0.22.14",
     "typescript": "6.0.3",
     "vitest": "4.1.10",
-    "zinfer": "0.2.7",
-    "@tailor-platform/tailor-proto": "^0.0.1",
-    "@tailor-platform/shared": "^0.0.0"
+    "zinfer": "0.2.8",
+    "@tailor-platform/shared": "^0.0.0",
+    "@tailor-platform/tailor-proto": "^0.0.1"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.2.0",
@@ -237,7 +237,7 @@
   },
   "engines": {
     "bun": ">=1.2.0",
-    "node": ">=22.15.0"
+    "node": ">=22.18.0"
   },
   "scripts": {
     "test": "vitest",