@tailor-platform/sdk 2.30.0 → 2.32.0

package/docs/ai.md

@@ -0,0 +1,92 @@
+---
+description: "Make choice, boolean, and ordered score decisions from application state through AI Gateway with the System One client from @tailor-platform/sdk/ai."
+---
+
+# System One
+
+System One makes semantic decisions from application state, a question, and a fixed answer space. It returns the selected answer and its probability without requiring prompt construction or structured-output parsing.
+
+Create a client with the URL the platform assigns to your deployed [AI Gateway](services/aigateway.md). Inside a Tailor Function, `aigateway.get()` returns it as `url`. Omit `token`; the platform authenticates the request:
+
+```typescript
+import { createSystemOne } from "@tailor-platform/sdk/ai";
+import { aigateway } from "@tailor-platform/sdk/runtime";
+
+const { url } = await aigateway.get("my-aigateway");
+const systemOne = createSystemOne({ baseURL: url });
+```
+
+External clients pass the same URL, which `tailor show` lists, directly with an access token issued by the AI Gateway's auth namespace:
+
+```typescript
+import { createSystemOne } from "@tailor-platform/sdk/ai";
+
+const systemOne = createSystemOne({
+  baseURL: "https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev",
+  token: accessToken,
+});
+```
+
+## Choice decisions
+
+Use `choice()` to select one value from an answer space. Literal types are inferred without `as const`:
+
+```typescript
+const result = await systemOne.choice({
+  state: { ticket, customer },
+  question: "Which department should handle this ticket?",
+  choices: ["billing", "sales", "support"],
+});
+
+// result.value: "billing" | "sales" | "support"
+// result.probabilities: Record<"billing" | "sales" | "support", number>
+```
+
+## Boolean decisions
+
+Use `boolean()` for a binary decision. `value` is `true` when the probability of "yes" is at least `0.5`, and `probability` is the probability of the selected answer:
+
+```typescript
+const result = await systemOne.boolean({
+  state: invoice,
+  question: "Is this invoice a duplicate?",
+});
+
+if (result.value && result.probability > 0.95) {
+  // Apply the appropriate business rule.
+}
+```
+
+## Ordered scores
+
+Use `score()` when the answer space has a meaningful order. Levels are ordered from lowest to highest, and `value` is the level with the highest probability:
+
+```typescript
+const result = await systemOne.score({
+  state: transaction,
+  question: "Assess the risk of this transaction.",
+  levels: ["low", "medium", "high"],
+});
+```
+
+## Models
+
+Decisions use `jev-1.13.0` unless a call passes `model`. `jev-latest` always points to the newest model, so its probabilities can shift when a new model is released. Use it only when your logic does not compare probabilities against fixed thresholds:
+
+```typescript
+const result = await systemOne.boolean({
+  state: invoice,
+  question: "Is this invoice a duplicate?",
+  model: "jev-latest",
+});
+```
+
+## Errors
+
+Failures throw `SystemOneError` with a provider-independent `code`. Applications can handle stable codes such as `UNAUTHORIZED`, `RATE_LIMITED`, `PROVIDER_TIMEOUT`, and `PROVIDER_UNAVAILABLE` without depending on a model provider.
+
+A decision waits until AI Gateway responds. To fail with `PROVIDER_TIMEOUT` instead, pass `timeoutMs`:
+
+```typescript
+const systemOne = createSystemOne({ baseURL: url, timeoutMs: 10_000 });
+```

package/docs/cli/tailordb.md

@@ -328,26 +328,28 @@ tailor tailordb migration test [options]
 
 **Options**
 
-| Option                                        | Alias | Description                                                                                                          | Required | Default              | Env                            |
-| --------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>`               | `-w`  | Workspace ID                                                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`                         | `-p`  | Workspace profile                                                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
-| `--config <CONFIG>`                           | `-c`  | Path to Tailor config file                                                                                           | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--yes`                                       | `-y`  | Acknowledge that a designated target workspace may be overwritten                                                    | No       | `false`              | -                              |
-| `--data <DATA>`                               | -     | Data source for the migration test (seed or clone)                                                                   | No       | `"seed"`             | -                              |
-| `--target-workspace-id <TARGET_WORKSPACE_ID>` | -     | Existing throwaway workspace to retain after the test (requires --yes)                                               | No       | -                    | -                              |
-| `--keep`                                      | -     | Keep the automatically created workspace after the test                                                              | No       | `false`              | -                              |
-| `--assert <ASSERT>`                           | -     | Path to a TypeScript assertion script to run after migrations                                                        | No       | -                    | -                              |
-| `--assert-namespace <ASSERT_NAMESPACE>`       | -     | TailorDB namespace exposed to the assertion script                                                                   | No       | -                    | -                              |
-| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d, so workspace prune --expired can delete it (requires --keep) | No       | -                    | -                              |
-| `--clone-timeout <CLONE_TIMEOUT>`             | -     | How long to wait for the clone to finish with --data clone, e.g. 30s or 10m (default: 30m)                           | No       | -                    | -                              |
-| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                                                                 | No       | -                    | -                              |
+| Option                                        | Alias | Description                                                                                                                                                                                                                      | Required | Default              | Env                               |
+| --------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
+| `--workspace-id <WORKSPACE_ID>`               | `-w`  | Workspace ID                                                                                                                                                                                                                     | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
+| `--profile <PROFILE>`                         | `-p`  | Workspace profile                                                                                                                                                                                                                | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
+| `--config <CONFIG>`                           | `-c`  | Path to Tailor config file                                                                                                                                                                                                       | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`              |
+| `--yes`                                       | `-y`  | Acknowledge that a designated target workspace may be overwritten                                                                                                                                                                | No       | `false`              | -                                 |
+| `--data <DATA>`                               | -     | Data source for the migration test (seed or clone)                                                                                                                                                                               | No       | `"seed"`             | -                                 |
+| `--target-workspace-id <TARGET_WORKSPACE_ID>` | -     | Existing throwaway workspace to retain after the test (requires --yes)                                                                                                                                                           | No       | -                    | -                                 |
+| `--keep`                                      | -     | Keep the automatically created workspace after the test                                                                                                                                                                          | No       | `false`              | -                                 |
+| `--organization-id <ORGANIZATION_ID>`         | -     | Organization to create the temporary workspace in, at its root unless --folder-id is given (default: the source workspace's organization and folder). With --target-workspace-id, must match the target's organization           | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`                     | -     | Folder to create the temporary workspace in (default: the source workspace's folder). Requires --organization-id when the source workspace is not in an organization. With --target-workspace-id, must match the target's folder | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--assert <ASSERT>`                           | -     | Path to a TypeScript assertion script to run after migrations                                                                                                                                                                    | No       | -                    | -                                 |
+| `--assert-namespace <ASSERT_NAMESPACE>`       | -     | TailorDB namespace exposed to the assertion script                                                                                                                                                                               | No       | -                    | -                                 |
+| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d, so workspace prune --expired can delete it (requires --keep)                                                                                                             | No       | -                    | -                                 |
+| `--clone-timeout <CLONE_TIMEOUT>`             | -     | How long to wait for the clone to finish with --data clone, e.g. 30s or 10m (default: 30m)                                                                                                                                       | No       | -                    | -                                 |
+| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                                                                                                                                                                             | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Notes**
 
-The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed.
+The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. Right after creating the workspace it records a 24h expiry (unless --keep is given without --keep-ttl), so if the run is interrupted before the command can delete the workspace, workspace prune --expired removes it later. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed. Organization and folder IDs loaded by --env-file are used the same way as the options; command-line options take precedence, and empty env-file values are ignored.
 
 #### tailordb migration validate
 

package/docs/cli/workspace.md

@@ -107,7 +107,7 @@ tailor workspace create [options]
 | Option                                | Alias | Description                                                                                                                                   | Required | Default   | Env                               |
 | ------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
 | `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                | Yes      | -         | -                                 |
-| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west)                                                                                                    | Yes      | -         | -                                 |
+| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west, europe-west)                                                                                       | Yes      | -         | -                                 |
 | `--delete-protection`                 | `-d`  | Enable delete protection                                                                                                                      | No       | `false`   | -                                 |
 | `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                                                   | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
 | `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                                                         | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |

package/docs/github-actions.md

@@ -117,6 +117,92 @@ all-added or all-removed viewer artifacts. Re-run `setup ci branch` after adding
 removing TailorDB namespaces. `setup check` reports drift when the recorded ERD
 preview namespaces no longer match the current config.
 
+#### Migration test on a labeled pull request
+
+Pass `--migration-test` on a branch target to add a job that runs
+[`tailor tailordb migration test`](./cli/tailordb.md) against a pull request on
+demand. It is opt-in and requires a config with TailorDB migrations.
+
+```bash
+tailor setup ci branch --name my-app-stg --migration-test
+```
+
+The job runs only when someone adds the `tailor:migration-test` label to a pull
+request from the same repository (change the label with
+`--migration-test-label`). It runs the pending migrations in a temporary
+workspace created next to the source workspace, writes the `--json` result to
+the job summary, and removes the label as its last step, whether the test
+succeeded, failed, or was cancelled while running. To run it again, add the label
+again. If a run is cancelled before the job starts (for example, a reviewer
+rejects the environment's approval), the label stays on the pull request: remove
+it and add it again.
+Anyone who can label pull requests in your repository can start the job, and
+each run creates and deletes a workspace. Runs for one pull request never
+cancel each other.
+
+The generated workflow also lists `labeled` in its `pull_request` types. The
+plan and ERD preview jobs skip label events, so adding an unrelated label does
+not re-run them.
+
+Runs started by a label report their result job as `tailor-result (<name>) [label]`
+instead of `tailor-result (<name>)`. A label event therefore never replaces the
+result of the check you require for branch protection. The migration test result
+appears only under the `[label]` name, so it does not block merging through the
+check you require.
+
+The job clones the source workspace's TailorDB records and passes
+`--clone-timeout 30m`, which bounds only the wait for the data clone. If the clone takes longer, the command
+fails with the clone's operation ID in the error and removes its temporary
+workspace, while the clone itself keeps running on the platform.
+
+The migration test step is limited to 50 minutes and the job to 60, so the label
+is still removed when the step times out. A step that is stopped at its limit
+(or a job cancelled at the job limit) gives the command no chance to clean up:
+delete the leftover temporary workspace with `tailor workspace delete`.
+
+##### Choosing the source workspace
+
+`migration test` reads the source workspace (it is not modified), builds a
+temporary workspace from it in the same organization and folder, and deletes
+that workspace afterwards. Because the machine user creates and deletes that
+workspace, it needs an editor or admin role on the organization or folder that
+holds the source workspace; a viewer role is not enough. The clone also needs the
+same role on the source side. The clone copies TailorDB records only: IdP users
+and file blobs are not copied.
+
+Two setups are supported:
+
+- **Source is the plan/deploy workspace (default).** The job uses the same GitHub
+  Environment as the plan and deploy jobs, so it reads the same
+  `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets. Nothing
+  extra to configure. If that workspace holds too little data to be a useful
+  test, point the job at a workspace that does with the next setup.
+- **Source is a different workspace, such as production.** Pass
+  `--migration-test-environment <env>`. The job then uses that GitHub
+  Environment and reads the source workspace from its
+  `TAILOR_PLATFORM_MIGRATION_TEST_SOURCE_WORKSPACE_ID` variable, together with the
+  machine-user secrets set on that same environment. Give this environment a
+  machine user whose role you are willing to hold on the source workspace's
+  organization or folder, since it needs the editor-or-admin role described
+  above. Pending migrations run from the source workspace's migration number up
+  to the latest, so a source that is behind the deploy target replays more
+  migrations, which is closer to what a production deploy will do.
+
+A job can declare only one GitHub Environment, and a repository secret or
+variable is read from that environment, which is why a different source needs its
+own environment. `tailor setup ci env` prints what each environment needs,
+including the dedicated one. Keep the dedicated environment separate from your
+production deploy environment: a pull request job runs on the pull request merge
+ref (`refs/pull/<number>/merge`), so if an environment restricts which branches
+may deploy or requires reviewers, check how that affects the pull request job
+before pointing the migration test at it. A required-reviewers rule makes the
+job wait for approval before it can read the environment's secrets. The job runs
+the pull request's own code with that environment's credentials, so add one when
+the source workspace holds production data.
+
+Fork pull requests cannot read secrets, so the job is skipped for them.
+`--migration-test` is not available together with several `--dir` values.
+
 ### Tag target (recommended for production)
 
 The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
@@ -501,17 +587,18 @@ tailor setup ci env --check                  # check what is registered in GitHu
 
 The list follows what each generated workflow actually reads:
 
-| Name                                         | Kind     | Targets     | Required | Where the value comes from                                                                                                                                                                                                                                                                                                                                                                 |
-| -------------------------------------------- | -------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | variable | all         | yes      | Client ID of the platform machine user CI signs in as (an existing secret of the same name still works as a deprecated fallback); it needs an editor or admin role on the organization or folder that holds the workspace. An organization or folder admin creates one in the Tailor Console and grants it a role; without the required permission you cannot view or create machine users |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | secret   | all         | yes      | Client secret of the same platform machine user                                                                                                                                                                                                                                                                                                                                            |
-| `TAILOR_PLATFORM_WORKSPACE_ID`               | variable | branch, tag | yes      | `id` printed by `tailor workspace create`, or listed by `tailor workspace list`                                                                                                                                                                                                                                                                                                            |
-| `TAILOR_PLATFORM_ORGANIZATION_ID`            | variable | preview     | yes      | Organization to create the per-PR workspaces in (a machine user cannot create a workspace without one): `organizationId` listed by `tailor organization list`                                                                                                                                                                                                                              |
-| `TAILOR_PLATFORM_FOLDER_ID`                  | variable | preview     | no       | Folder to create the per-PR workspaces in: `id` listed by `tailor organization folder list -o <organization id>`. When unset they go directly under the organization, which needs the machine user's role on the organization itself                                                                                                                                                       |
-| `TAILOR_PLATFORM_FAIL_ON_DRIFT`              | variable | all         | no       | `true` to fail the drift check when it finds drift                                                                                                                                                                                                                                                                                                                                         |
-| `TAILOR_SLACK_BOT_TOKEN`                     | secret   | branch, tag | no       | Bot User OAuth Token (`xoxb-...`) of a Slack app with the `chat:write` scope                                                                                                                                                                                                                                                                                                               |
-| `TAILOR_SLACK_CHANNEL_ID`                    | variable | branch, tag | no       | Channel ID (`C...`) from the channel details in Slack; invite the bot to the channel                                                                                                                                                                                                                                                                                                       |
-| `TAILOR_SLACK_USER_MAPPING`                  | variable | branch, tag | no       | JSON object mapping GitHub usernames to Slack member IDs (for example `{"alice":"U0123456"}`) so notifications mention the actor; read only after you uncomment the `user-mapping` input of the `tailor-notify` step                                                                                                                                                                       |
+| Name                                                 | Kind     | Targets                             | Required | Where the value comes from                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------------- | -------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`             | variable | all                                 | yes      | Client ID of the platform machine user CI signs in as (an existing secret of the same name still works as a deprecated fallback); it needs an editor or admin role on the organization or folder that holds the workspace. An organization or folder admin creates one in the Tailor Console and grants it a role; without the required permission you cannot view or create machine users |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET`         | secret   | all                                 | yes      | Client secret of the same platform machine user                                                                                                                                                                                                                                                                                                                                            |
+| `TAILOR_PLATFORM_WORKSPACE_ID`                       | variable | branch, tag                         | yes      | `id` printed by `tailor workspace create`, or listed by `tailor workspace list`                                                                                                                                                                                                                                                                                                            |
+| `TAILOR_PLATFORM_MIGRATION_TEST_SOURCE_WORKSPACE_ID` | variable | branch (migration test environment) | yes      | ID of the workspace the migration test starts from, set on the environment passed to `--migration-test-environment`; it is only read to build the temporary workspace. Needs the machine user's editor or admin role on that workspace's organization or folder                                                                                                                            |
+| `TAILOR_PLATFORM_ORGANIZATION_ID`                    | variable | preview                             | yes      | Organization to create the per-PR workspaces in (a machine user cannot create a workspace without one): `organizationId` listed by `tailor organization list`                                                                                                                                                                                                                              |
+| `TAILOR_PLATFORM_FOLDER_ID`                          | variable | preview                             | no       | Folder to create the per-PR workspaces in: `id` listed by `tailor organization folder list -o <organization id>`. When unset they go directly under the organization, which needs the machine user's role on the organization itself                                                                                                                                                       |
+| `TAILOR_PLATFORM_FAIL_ON_DRIFT`                      | variable | all                                 | no       | `true` to fail the drift check when it finds drift                                                                                                                                                                                                                                                                                                                                         |
+| `TAILOR_SLACK_BOT_TOKEN`                             | secret   | branch, tag                         | no       | Bot User OAuth Token (`xoxb-...`) of a Slack app with the `chat:write` scope                                                                                                                                                                                                                                                                                                               |
+| `TAILOR_SLACK_CHANNEL_ID`                            | variable | branch, tag                         | no       | Channel ID (`C...`) from the channel details in Slack; invite the bot to the channel                                                                                                                                                                                                                                                                                                       |
+| `TAILOR_SLACK_USER_MAPPING`                          | variable | branch, tag                         | no       | JSON object mapping GitHub usernames to Slack member IDs (for example `{"alice":"U0123456"}`) so notifications mention the actor; read only after you uncomment the `user-mapping` input of the `tailor-notify` step                                                                                                                                                                       |
 
 See [Account management](https://docs.tailor.tech/administration/account-management)
 for how organizations, folders, workspaces, and machine users relate.

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
 
@@ -465,33 +473,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 +621,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 +679,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 +699,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.

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.32.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",
@@ -160,9 +165,10 @@
     "@jridgewell/trace-mapping": "0.3.31",
     "@napi-rs/keyring": "2.1.1",
     "@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",
@@ -191,7 +197,7 @@
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.3",
-    "rolldown": "1.2.13",
+    "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",