@tailor-platform/sdk 2.30.0 → 2.33.0

package/docs/services/tailordb/migration.md

@@ -173,9 +173,17 @@ During deploy, the pre-migration phase keeps the old field and adds the new fiel
 
 If you decline the prompt (or confirm the removal with `--drop`), the change stays a plain removal + addition with the usual data-loss warning.
 
+#### Changing nested member constraints
+
+Adding a required member, making an existing member required, or removing enum values inside a nested field requires a migration script, including inside arrays of objects. During Pre-migration, added or newly required members are optional and removed enum values remain allowed. Post-migration enforces the target constraints after your script fills missing values or replaces removed enum values. A newly added optional object may keep required children: those children are required only when the object is present.
+
+The generated script includes a `TODO` for each nested constraint change. Replace these with updates to the containing nested field, preserving its other members and handling objects inside arrays. A confirmed member rename generates its copy step alongside these TODOs.
+
+Changing a nested member's type, array-ness, decimal scale, or foreign key target is unsupported in a single migration. Use separate migrations to add a member with the target shape, copy or transform values in a custom script, and then remove the old member.
+
 #### Renaming a member inside a nested field
 
-Members inside a **nested field** (`db.object(...)`) are detected the same way: when `migration generate` finds a member removed from a nested field and a compatible member added under the same parent, it asks whether the member was renamed. Two members qualify only when copying the value preserves it exactly, because nested member constraints other than the new member's requiredness and unique constraint are not relaxed: the type, array-ness, requiredness, foreign key target, decimal scale, hooks, and validations must match (index, unique, and vector may differ, as for a top-level rename), enum values may be added but not removed, an object-typed member must keep the same members recursively, and serial members never qualify.
+Members inside a **nested field** (`db.object(...)`) are detected the same way: when `migration generate` finds a member removed from a nested field and a compatible member added under the same parent, it asks whether the member was renamed. Two members qualify only when copying the value preserves it exactly, because a rename copies existing values without transforming them: the type, array-ness, requiredness, foreign key target, decimal scale, hooks, and validations must match (index, unique, and vector may differ, as for a top-level rename), enum values may be added but not removed, an object-typed member must keep the same members recursively, and serial members never qualify.
 
 ```
 ? User.address.zip was removed and zipCode was added with a compatible type. Was it renamed to zipCode? (Y/n)
@@ -199,7 +207,7 @@ Warning: data loss possible:
   - User.address.zip: Nested member removed (existing values will no longer be accessible through the schema). Possibly renamed to zipCode: confirm it with --rename "User.address.zip:<newName>" to scaffold a copy script, or keep the removal and copy the values yourself
 ```
 
-The pre-migration phase keeps a removed member on the nested field until the script finishes, exactly like a removed top-level field, so a custom script can still read it. Nested fields reach the script as objects. Renaming a nested member cannot be combined in one migration with renaming its table or the nested field itself, and an object-typed member cannot be renamed in the same migration as one of its own members; split such changes into separate migrations (rename the object first, then its member).
+The pre-migration phase keeps a removed member on the nested field until the script finishes, exactly like a removed top-level field, so a custom script can still read it. Nested fields reach the script as objects. Renaming a nested member requires every ancestor, including the top-level nested field, to keep its nested type and array-ness. It cannot be combined in one migration with renaming its table or the nested field itself, and an object-typed member cannot be renamed in the same migration as one of its own members; split such changes into separate migrations (rename the object first, then its member).
 
 ### Renaming a table
 
@@ -454,6 +462,25 @@ tailor deploy --migration-skip-steps main-db/backfillUser,main-db/backfillInvoic
 
 Write every step so that running it again is safe: besides the cases above, a step can run a second time when a deploy is interrupted right after it commits. Use `where` clauses that skip rows a step already migrated, as in the example. Rows written while a migration is in progress are not seen by steps that already completed. [Maintenance mode](#maintenance-mode) blocks GraphQL writes but not the writes your resolvers, executors, or workflows make through Kysely, and without it GraphQL clients can write too, so stop such writers until the migration finishes or write steps that tolerate them.
 
+#### Rolling back instead of resuming
+
+By default a failure after another step has completed leaves the migration in progress and the namespace's tables in maintenance mode until you fix the step and deploy again. When you would rather restore the tables first and fix the script afterwards, export `onFailure` next to `steps`:
+
+```typescript
+export const onFailure = "rollback";
+
+export const steps = {
+  // ...
+} satisfies MigrationSteps;
+```
+
+- `onFailure` is `"resume"` (the default, described above) or `"rollback"`. Write it as `export const onFailure = "rollback"` with one of those two string literals; `tailor tailordb migration validate` and `tailor deploy` reject anything else. A script that runs `main` ignores it.
+- With `"rollback"`, a failed step after another step has completed, and post-migration schema changes that fail after every step completed, roll back the pre-migration schema changes like a failing `main` script: tables that already existed are restored to their previous shape and GraphQL permissions, and tables the migration newly introduced are dropped. The in-progress record is cleared before the schema is rolled back, the tables leave maintenance mode, and the checkpoint is not advanced. `tailor deploy` then fails with the step's error under the code `MIGRATION_ROLLED_BACK`, and its suggestion says the next deploy runs every step again. A migration that an earlier deploy left in progress is rolled back the same way once its script exports `"rollback"`, including the tables and GraphQL permissions its earlier Pre-phase wrote.
+- Steps that already completed stay committed. Their changes to existing fields remain in the database, and nothing is recorded as in progress, so the next deploy runs every step again from the beginning. Every step must be safe to run again, or a rolled-back run applies those changes twice. Do not rely on data a step wrote to a field or table that the rollback removed.
+- If `tailor deploy` cannot tell whether a step ran, or the migration's workflow execution may still be running (for example the connection to it was lost), it does not roll anything back even with `"rollback"`: the migration stays in progress as described for a `main` script below. A migration an earlier deploy left in progress is rolled back only when its earlier run is confirmed to have ended, so a failure before that run is inspected, such as a schema error while applying the Pre-phase, keeps it in progress.
+- If the in-progress record cannot be cleared, `tailor deploy` does not roll the schema back. It logs a warning and keeps the migration in progress with its tables in maintenance mode, because a record that outlives a rollback would make the next deploy resume against a schema its completed steps no longer match. Deploy again to resume it as described above, or roll it back without deploying with `tailor tailordb migration resolve --rollback`.
+- If the schema or GraphQL permission of some tables cannot be rolled back, `tailor deploy` still fails with the step's original error. It also warns `Migration <namespace>/<N> was not rolled back completely` and lists the tables that need manual repair, and separately the tables whose GraphQL permission could not be set back. Check them in the workspace and repair them by hand; deploying again does not release them.
+
 ### Settling a migration that stays in progress
 
 When you do not want to resume the migration with another deploy — you abandoned it, or you repaired the data by hand — settle it with `tailor tailordb migration resolve`. Pass exactly one of two options:
@@ -465,33 +492,35 @@ Tables that the failed migration removes are deleted with their data under `--co
 
 ## 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.             |
-| 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. |
-| Remove nested member              | No        | Optional          | Warning tier — see [Renaming a member inside a nested field](#renaming-a-member-inside-a-nested-field). The member stays readable from `migrate.ts` during Pre-migration.                                                                          |
-| Rename nested member              | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "Table.field.oldMember:newMember"`. Auto-generated script rewrites each row's nested value; the old member stays readable and the new member is optional 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       | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Each stored value becomes a one-element array, so the conversion needs no edits.                                                   |
+| 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. |
+| Remove nested member                                                          | No        | Optional          | Warning tier — see [Renaming a member inside a nested field](#renaming-a-member-inside-a-nested-field). The member stays readable from `migrate.ts` during Pre-migration.                                                                          |
+| Add required nested member / make member required / remove nested enum values | Yes       | Yes               | Pre-migration relaxes the member constraints. Complete the generated TODOs to transform the nested values before Post-migration.                                                                                                                   |
+| Change nested member type / array-ness / decimal scale / foreign key target   | Rejected  | —                 | Add a new member, transform and copy values, then remove the old member in separate migrations.                                                                                                                                                    |
+| Rename nested member                                                          | Yes       | Yes               | Confirmed interactively at generate time or via `--rename "Table.field.oldMember:newMember"`. Auto-generated script rewrites each row's nested value; the old member stays readable and the new member is optional 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                                                   | Yes       | Yes               | Two migrations, generated together after you confirm — see [Converting a field type](#converting-a-field-type). Each stored value becomes a one-element array, so the conversion needs no edits.                                                   |
 
 ### Field type changes
 
@@ -611,13 +640,15 @@ Some changes are still rejected and need a temporary field you add yourself —
 The command performs the following sequence:
 
 1. Reads each migration-enabled namespace's `sdk-migration` checkpoint from the source workspace and reconstructs that exact snapshot from local migration history. A deployed namespace that has no checkpoint is treated as migration 0, as `tailor deploy` does, but only when its schema matches the `0000` snapshot; otherwise the command fails and lists the differences. A namespace that was never deployed also fails.
-2. Creates a temporary workspace in the same region, organization, and folder as the source, unless `--target-workspace-id` names an existing throwaway workspace.
+2. Creates a temporary workspace in the same region as the source, unless `--target-workspace-id` names an existing throwaway workspace. By default it is created in the source's organization and folder. `--organization-id` places it at the root of that organization, and `--folder-id` places it in that folder (together with `--organization-id` when the folder is in another organization or the source is not in an organization). With `--target-workspace-id`, the given values must match where that workspace already is.
 3. Deploys the checkpoint snapshots and writes their checkpoint labels.
 4. Loads fixture data or clones source records.
 5. Runs the normal deployment pipeline, including every pending pre-migration, `migrate.ts`, and post-migration phase.
 6. Optionally runs an assertion script against the migrated data.
 7. Deletes an automatically-created workspace after success or failure.
 
+Right after creating an automatically-created workspace (step 2), the command records a 24-hour expiry on it. If the run is interrupted before step 7 — for example, a CI job is cancelled or reaches its time limit — the command cannot delete the workspace, so it stays. Once the 24 hours have passed, `tailor workspace prune --expired` (with a location option such as `--organization-root`, `--folder-id`, or `--personal`) deletes it. A workspace given with `--target-workspace-id` is not given an expiry. If recording the expiry fails, the command warns and continues the test.
+
 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.
@@ -667,6 +698,8 @@ To inspect the result after a run, pass `--keep` so the automatically created wo
 tailor tailordb migration test --keep
 ```
 
+A kept workspace records no expiry unless you also pass `--keep-ttl <age>` (for example `--keep-ttl 7d`), so `tailor workspace prune --expired` does not delete it.
+
 Alternatively, provide an empty designated throwaway workspace. This mode never deletes the target and requires explicit acknowledgment:
 
 ```bash
@@ -685,7 +718,7 @@ 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 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); members removed from a nested field are kept the same way, and the new member of a confirmed nested rename is added as optional and non-unique. 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.
+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); members removed from a nested field are kept the same way, and the new member of a confirmed nested rename is added as optional and non-unique. Added or newly required nested members are optional and removed nested enum values remain allowed until Post-migration. 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 runs on the platform as the configured machine user inside a transaction — or, for a script that exports [`steps`](#splitting-a-migration-into-steps), one transaction per step. 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 — 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.
@@ -891,10 +924,10 @@ Use `tailor tailordb migration rebaseline` rather than combining `migration gene
 
 ## Failure Recovery
 
-A script that exports `steps` follows different rules once one of its steps has completed: the migration stays in progress and the next deploy resumes it. See [Splitting a migration into steps](#splitting-a-migration-into-steps). Otherwise, if the pre-migration phase or `migrate.ts` fails:
+A script that exports `steps` follows different rules once one of its steps has completed: the migration stays in progress and the next deploy resumes it, unless the script exports `onFailure = "rollback"`. See [Splitting a migration into steps](#splitting-a-migration-into-steps) and [Rolling back instead of resuming](#rolling-back-instead-of-resuming). Otherwise, if the pre-migration phase or `migrate.ts` fails:
 
 - **The transaction rolls back** for that migration's script. Database changes the script made are undone.
-- **The pre-migration schema changes are rolled back** to the prior checkpoint: tables that already existed are restored to their previous shape, and tables the migration newly introduced are dropped. The workspace is left at its prior checkpoint and prior schema — not half-applied.
+- **The pre-migration schema changes are rolled back** to the prior checkpoint: tables that already existed are restored to their previous shape and GraphQL permissions, and tables the migration newly introduced are dropped. The workspace is left at its prior checkpoint and prior schema — not half-applied.
 - The whole `apply` aborts and the checkpoint label is not bumped. Subsequent migrations in the same run do not execute.
 
 The rollback is best-effort per table; if reverting a table fails, a warning is logged and the original migration error is still reported. The next deploy then stops with remote schema drift on that table. Run `tailor tailordb migration validate` to see which tables differ, return the namespace to its checkpoint with `tailor tailordb migration sync <N>`, where `<N>` is the checkpoint `tailor tailordb migration status` reports, and deploy again. `sync` deletes the tables and fields that are not in that migration's snapshot, together with any rows the failed migration wrote to them; the next deploy runs the failed migration again.
@@ -1023,10 +1056,12 @@ npm install -D @electric-sql/pglite
 
 The generated `db.pglite.ts` exports the `CREATE TABLE` script for the same schema `db.ts` types — the tables as the pre-migration phase leaves them while `migrate.ts` runs, including relaxed constraints, renamed fields under both names, and retained removed fields. Run it once on the PGlite instance, stage rows, then run the script in a transaction. `tailor tailordb migration script <N> --with-test` scaffolds this test too when `@electric-sql/pglite` is installed. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
 
+Relations are enforced as on the platform: a row that points at a parent that does not exist is rejected. Write the records the test starts from inside `prepareFixtures`, which leaves relations unchecked while it runs, so you can stage rows that predate a relation, such as rows whose parent does not exist that the script repairs. Relations are checked again when it returns, so the script itself still cannot write a missing parent. NOT NULL, UNIQUE, and CHECK constraints stay enforced. A relation is left unenforced while the pre-migration schema cannot satisfy it: when a pending type change leaves the field a different type from its target, when the migration retargets the relation to another table, or when the target field's unique constraint is still withheld. How relations on array fields and inside nested objects behave is described under [Real SQL execution with PGlite](../../testing.md#real-sql-execution-with-pglite-mocktailordbwithpglite).
+
 ```typescript
 // migrations/0005/migrate.pglite.test.ts
 import { PGlite } from "@electric-sql/pglite";
-import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
+import { createKyselyPGlite, prepareFixtures, type Unmigrated } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { pgliteSchema } from "./db.pglite";
 import { main } from "./migrate";
@@ -1047,13 +1082,15 @@ afterAll(async () => {
 describe("0005 add required email", () => {
   test("backfills null emails and keeps existing ones", async () => {
     const now = new Date();
-    await db
-      .insertInto("User")
-      .values([
-        { name: "a", email: null, createdAt: now, updatedAt: now },
-        { name: "b", email: "b@example.com", createdAt: now, updatedAt: now },
-      ])
-      .execute();
+    await prepareFixtures(pglite, async () => {
+      await db
+        .insertInto("User")
+        .values([
+          { name: "a", email: null, createdAt: now, updatedAt: now },
+          { name: "b", email: "b@example.com", createdAt: now, updatedAt: now },
+        ])
+        .execute();
+    });
 
     await db.transaction().execute((trx) => main(trx));
 

package/docs/testing.md

@@ -209,11 +209,12 @@ test("upserts against real rows", async () => {
 });
 ```
 
-The generated columns follow the Kysely types, not TailorDB's storage: `text` for string and enum fields, `timestamptz` for datetime, `date` and `time` for date and time, `numeric` for decimal, rounded to the configured scale and read back with exactly that many fractional digits, `jsonb` for nested objects (and arrays of them), Postgres arrays for other array fields. `id` is a generated `uuid` primary key, `.unique()` fields and unique `.indexes()` are enforced, so `ON CONFLICT` upserts behave, and `.default()` values become column defaults (`"now"` becomes the current time). `.serial()` fields are assigned by the database from the configured `start`, `maxValue`, and format. Relations are not enforced.
+The generated columns follow the Kysely types, not TailorDB's storage: `text` for string and enum fields, `timestamptz` for datetime, `date` and `time` for date and time, `numeric` for decimal, rounded to the configured scale and read back with exactly that many fractional digits, `jsonb` for nested objects (and arrays of them), Postgres arrays for other array fields. `id` is a generated `uuid` primary key, `.unique()` fields and unique `.indexes()` are enforced, so `ON CONFLICT` upserts behave, and `.default()` values become column defaults (`"now"` becomes the current time). `.serial()` fields are assigned by the database from the configured `start`, `maxValue`, and format. Relations are enforced as the platform does: a row that points at a parent that does not exist is rejected with an error containing `violates foreign key constraint`, so create parent rows before their children. This includes relations on array fields. A relation declared on a field inside a nested object is not enforced, as on the platform.
 
 What the script cannot reproduce:
 
 - Hooks, validations, and permissions do not run. A required field whose value only its own field-level create hook supplies is created nullable, so inserts that omit it succeed; give it a `.default()` if the test reads it back. A field filled by a table-level hook stays `NOT NULL`, as its Kysely type still requires it on insert.
+- Relations on array fields, and relations from a field whose type differs from the field it points at (such as a `string` field related to `id`), are checked only when a row is written. Deleting a parent that such a row still points at is rejected by the platform but not by PGlite, and changing the parent's `id` is not checked either, so a test must not expect PGlite to reject them.
 - Serial formats are reproduced for a single `%d`, `%x`, or `%X` specifier with an optional zero-padded width; an octal `%o` format fails generation with an error naming the field.
 - `gapless` is not reproduced: the numbers come from a sequence, so an insert that fails still uses up its number.
 - A date or datetime inside a nested object reads back as a string from `jsonb`, not a `Date`, or a `Temporal.PlainDate` or `Temporal.Instant` under `kyselyTypePlugin({ temporal: true })`, although the platform returns those types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.30.0",
+  "version": "2.33.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -82,6 +82,11 @@
       "import": "./dist/seed/index.mjs",
       "default": "./dist/seed/index.mjs"
     },
+    "./ai": {
+      "types": "./dist/ai/index.d.mts",
+      "import": "./dist/ai/index.mjs",
+      "default": "./dist/ai/index.mjs"
+    },
     "./vitest": {
       "types": "./dist/vitest/index.d.mts",
       "import": "./dist/vitest/index.mjs",
@@ -155,14 +160,15 @@
     "@bufbuild/protovalidate": "1.3.0",
     "@connectrpc/connect": "2.2.0",
     "@connectrpc/connect-node": "2.2.0",
-    "@inquirer/core": "12.0.4",
-    "@inquirer/prompts": "8.7.3",
+    "@inquirer/core": "12.0.5",
+    "@inquirer/prompts": "8.7.4",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@napi-rs/keyring": "2.1.1",
+    "@napi-rs/keyring": "2.1.2",
     "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/context-async-hooks": "2.12.0",
     "@opentelemetry/exporter-trace-otlp-proto": "0.223.0",
     "@opentelemetry/resources": "2.12.0",
-    "@opentelemetry/sdk-trace-node": "2.12.0",
+    "@opentelemetry/sdk-trace": "2.12.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
     "@oxc-project/types": "0.154.0",
     "@politty/zod": "0.5.2",
@@ -182,7 +188,7 @@
     "globals": "17.13.0",
     "graphql": "17.0.2",
     "inflection": "3.0.2",
-    "kysely": "0.29.6",
+    "kysely": "0.29.7",
     "lines-db": "0.18.0",
     "mime-types": "3.0.2",
     "open": "11.0.4",
@@ -190,8 +196,8 @@
     "p-limit": "7.3.3",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
-    "pkg-types": "2.3.3",
-    "rolldown": "1.2.13",
+    "pkg-types": "2.4.0",
+    "rolldown": "1.2.14",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.3.0",
@@ -203,21 +209,22 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
+    "@ark/attest": "0.57.0",
     "@electric-sql/pglite": "0.5.10",
-    "@opentelemetry/sdk-trace-base": "2.12.0",
     "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
     "@types/node": "24.19.2",
     "@types/semver": "7.8.0",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "5.0.5",
-    "eslint-plugin-zod": "5.0.0",
+    "eslint-plugin-zod": "5.2.0",
     "oxfmt": "0.73.0",
     "oxlint": "1.88.0",
     "oxlint-tsgolint": "7.0.2004",
     "sonda": "0.14.0",
     "tsdown": "0.23.1",
+    "tsrs": "0.16.0-ts7.1.0-dev.20260929",
+    "tsx": "4.23.15",
     "typescript": "6.0.3",
     "vitest": "5.0.5",
     "zinfer": "0.4.7"
@@ -256,8 +263,8 @@
     "check:import-cycles": "node --experimental-strip-types scripts/check-import-cycles.ts",
     "lint:fix": "oxlint --type-aware . --fix",
     "typecheck": "tsc --noEmit",
-    "typecheck:go": "tsgo --tsBuildInfoFile ./.tsgo.tsbuildinfo",
-    "perf:typecheck": "bash scripts/perf/exec.sh",
+    "typecheck:rs": "node scripts/typecheck-native.ts",
+    "perf:attest": "tsx scripts/perf/attest/run.ts",
     "perf:runtime": "bash scripts/perf/runtime-perf.sh",
     "postinstall": "node postinstall.mjs",
     "measure:bundle": "node ../../scripts/measure-bundle-size-sonda.js",

package/dist/application-C2bPmmbh.mjs

@@ -1 +0,0 @@
-export{t as defineApplication,n as generatePluginFilesIfNeeded}from"./application-D0xNJbag.mjs";