@tailor-platform/sdk 2.0.0-next.4 → 2.0.0-next.5

package/docs/migration/v2.md

@@ -582,6 +582,54 @@ calls to db.table. Leave unrelated local objects with a .type() method unchanged
 
 </details>
 
+## TailorDB forward relation names derive from field names
+
+**Migration:** Partially automatic
+
+Review TailorDB relations that omit `toward.as`. Their forward GraphQL field names now derive from the relation field name with a trailing `ID`, `Id`, or `id` removed, instead of from the target table name.
+
+Preserve the v1 GraphQL field name by making it explicit:
+
+Before:
+
+```ts
+ownerId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: user },
+}),
+```
+
+After:
+
+```ts
+ownerId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: user, as: "user" },
+}),
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Tailor SDK v2 derives a default forward GraphQL relation name from the source
+field name by removing a trailing ID, Id, or id. V1 derived it from the target
+table name. Review each reported non-self relation that omits toward.as.
+
+If consumers must keep using the v1 GraphQL field name, inspect the v1 schema and
+copy that exact field name into toward.as. Otherwise, update GraphQL operations
+and consumer code to use the new field-based name. No change is needed when the old
+and new names are identical. Relations with a guaranteed non-empty toward.as,
+self-relations, and keyOnly relations are unchanged. For an empty or dynamic
+toward.as, determine whether its runtime value can be falsy; if so, treat the
+relation as using the default name.
+
+A relation field without a trailing ID, Id, or id would default to its own scalar
+field name and therefore conflict. Give that relation an explicit toward.as.
+```
+
+</details>
+
 ## executeScript arg JSON.stringify → value
 
 **Migration:** Partially automatic
@@ -825,6 +873,164 @@ After:
 .tailor/
 ```
 
+## ValidateFn simplification and type-level validate
+
+**Migration:** Manual
+
+Field-level `ValidateFn` is simplified from `(args: { value, data, invoker }) => boolean` to `(args: { value }) => string | void` — the function now returns the error message directly instead of a separate `[fn, message]` tuple. The `ValidateConfig` tuple form and `Validators<F>` record syntax on `db.type().validate()` are removed. Type-level validation uses `db.type().validate((args, issues) => void)` with `{ newRecord, oldRecord, invoker }` args and an `issues(field, message)` callback for cross-field rules.
+
+Field-level validate: return an error message string instead of a boolean (tuple form removed):
+
+Before:
+
+```ts
+.validate(
+  [({ value }) => value.length > 5, "Name must be longer than 5 characters"],
+)
+```
+
+After:
+
+```ts
+.validate(({ value }) =>
+  value.length <= 5 ? "Name must be longer than 5 characters" : undefined,
+)
+```
+
+Type-level validate: per-field record syntax replaced by a single function with `issues()` callback:
+
+Before:
+
+```ts
+.validate({
+  name: [({ value }) => value.length > 5, "Name must be longer than 5"],
+})
+```
+
+After:
+
+```ts
+.validate(({ newRecord }, issues) => {
+  if (newRecord.name && newRecord.name.length <= 5) {
+    issues("name", "Name must be longer than 5");
+  }
+})
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The v2 SDK simplifies field validation and introduces type-level validation.
+
+Field-level `.validate()` changes:
+- Signature: `(args: { value, data, invoker }) => boolean` → `(args: { value }) => string | void`
+- The function now returns the error message string directly (or undefined/void to pass)
+  instead of returning a boolean with the message in a separate tuple.
+- The `[fn, errorMessage]` tuple form (`ValidateConfig`) is removed.
+- `data` and `invoker` are no longer available in field-level validators.
+  Use type-level `.validate()` for cross-field or invoker-dependent rules.
+
+Type-level `.validate()` on `db.type()` changes:
+- Old: `.validate({ fieldName: fn | [fn, msg] | fn[] })` (per-field record, `Validators<F>` type)
+- New: `.validate((args, issues) => void)` (single function, `TypeValidateFn<F>` type)
+- Args: `{ newRecord, oldRecord, invoker }` — `newRecord` is the record after hooks run
+- Call `issues(field, message)` to report validation errors; `field` supports dotted paths
+- Move per-field validators that need `data`/`invoker` to the type-level function
+
+For each remaining `ValidateConfig`, `Validators<`, or old-signature `.validate()` usage:
+1. Rewrite field-level validators to return the error string directly
+2. Move cross-field / invoker-dependent validators to the type-level function
+3. Remove unused `ValidateConfig` / `Validators` type imports
+```
+
+</details>
+
+## TailorDB hook redesign: field-level args and type-level hooks
+
+**Migration:** Manual
+
+Field-level `HookFn` args change from `{ value, data, invoker }` to create `{ input, invoker, now }` / update `{ input, oldValue, invoker, now }` — `value` is renamed to `input`, matching the `input` arg on type-level hooks (same pre-hook data, narrowed to one field); `data` (the full record) is removed; `oldValue` (previous field value) is added for update hooks only; `now` (operation timestamp) is shared across all hooks. Type-level hooks on `db.type().hooks()` change from per-field mapping `{ fieldName: { create, update } }` (`Hooks<F>`) to a single `{ create, update }` object (`TypeHook<F>`) — create hooks take `{ input, invoker, now }`, update hooks take `{ input, oldRecord, invoker, now }` (oldRecord is always non-null). Both return partial field overrides.
+
+Field-level hooks: `value` renamed to `input`, `data` replaced by `oldValue` and `now`; use `now` instead of `new Date()`:
+
+Before:
+
+```ts
+db.datetime().hooks({
+  create: ({ value }) => value ?? new Date(),
+  update: () => new Date(),
+})
+```
+
+After:
+
+```ts
+db.datetime().hooks({
+  create: ({ input, now }) => input ?? now,
+  update: ({ now }) => now,
+})
+```
+
+Type-level hooks: per-field mapping replaced by single create/update functions:
+
+Before:
+
+```ts
+.hooks({
+  fullAddress: {
+    create: ({ data }) => `${data.postalCode} ${data.address}`,
+    update: ({ data }) => `${data.postalCode} ${data.address}`,
+  },
+})
+```
+
+After:
+
+```ts
+.hooks({
+  create: ({ input }) => ({
+    fullAddress: `${input.postalCode} ${input.address}`,
+  }),
+  update: ({ input }) => ({
+    fullAddress: `${input.postalCode} ${input.address}`,
+  }),
+})
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The v2 SDK redesigns TailorDB hooks at both field and type levels.
+
+Field-level `.hooks()` on individual fields:
+- Create args: `{ value, data, invoker }` → `{ input, invoker, now }` (no `oldValue`)
+- Update args: `{ value, data, invoker }` → `{ input, oldValue, invoker, now }`
+- `value` is renamed to `input`, matching the type-level hook's `input` arg — both are
+  the same pre-hook data, at different granularity
+- `data` (full record) is removed; update hooks get `oldValue` (previous field value) instead
+- `now` provides the operation timestamp — use `now` instead of `new Date()`
+- If a field-level hook needs the full record (other fields), move it to a type-level hook
+
+Type-level `.hooks()` on `db.type()`:
+- Old: `.hooks({ fieldName: { create: fn, update: fn } })` (per-field mapping, `Hooks<F>` type)
+- New: `.hooks({ create: fn, update: fn })` (single object, `TypeHook<F>` type)
+- Each function: `({ input, oldRecord, invoker, now }) => ({ fieldName: value, ... })`
+- `input` is the pre-hook input (may have nullish values for optional/defaulted fields)
+- Create hooks do not receive `oldRecord`; update hooks receive `oldRecord` (always non-null)
+- Return an object with only the fields to override; unmentioned fields are unchanged
+
+Migration steps for each `.hooks()` call on a `db.type()`:
+1. If the old per-field hooks only use `value`/`invoker` and don't reference `data`,
+   convert them to field-level hooks with the new args (`value` → `input`, plus `oldValue`, `now`)
+2. If the old hooks reference `data` (cross-field access), convert to a type-level hook
+   using `input`/`oldRecord`
+3. Remove unused `Hooks<F>` / `HookFn<>` type imports
+```
+
+</details>
+
 ## Behavioral changes (no migration required)
 
 These v2 changes alter runtime or CLI behavior; no source change is needed.

package/docs/services/aigateway.md

@@ -111,3 +111,5 @@ const { url } = await aigateway.get("my-aigateway");
 ```
 
 Type narrowing is provided by the generated `tailor.d.ts` (the `AIGatewayNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new AI Gateways to refresh it. Before the first generate run, `get()` accepts any string.
+
+The same URL is also shown by `tailor show`, which lists the URL of each AI Gateway defined in `aiGateways` once it has been deployed.

package/docs/services/tailordb.md

@@ -220,11 +220,14 @@ const user = db.table("User", {
 const userProfile = db.table("UserProfile", {
   userEmail: db.string().relation({
     type: "1-1",
-    toward: { type: user, key: "email" },
+    toward: { type: user, key: "email", as: "user" },
   }),
 });
 ```
 
+`userEmail` does not end in `ID`, `Id`, or `id`, so this example specifies the forward relation
+name with `toward.as`.
+
 Customize relation names using `toward.as` / `backward` options:
 
 ```typescript
@@ -255,52 +258,72 @@ type User {
 - `backward` - Customizes the field name for accessing this type from the related type
 
 Relation names share the same GraphQL field namespace as fields, files, and other relations on
-the type. The SDK rejects duplicate or empty relation names. Use `toward.as` when multiple fields
-on the same type point to the same target type, because their default forward names are derived
-from the target type name:
+the table. The SDK rejects duplicate or empty relation names. When `toward.as` is omitted, the
+default forward name comes from the relation field name with a trailing `ID`, `Id`, or `id`
+removed. This lets multiple fields point to the same target table with distinct forward names:
 
 ```typescript
 const post = db.table("Post", {
   authorID: db.uuid().relation({
     type: "n-1",
-    toward: { type: user, as: "author" },
+    toward: { type: user },
     backward: "authoredPosts",
   }),
   reviewerID: db.uuid().relation({
     type: "n-1",
-    toward: { type: user, as: "reviewer" },
+    toward: { type: user },
     backward: "reviewedPosts",
   }),
 });
 ```
 
+These fields generate the forward names `author` and `reviewer`. A relation field without one of
+the recognized ID suffixes needs an explicit `toward.as`, because its generated forward name
+would conflict with the field itself.
+
 Use `toward.as` or `backward` when a generated relation name would conflict with an existing
-field, files entry, or relation on the same type.
+field, files entry, or relation on the same table.
 
 ### Hooks
 
-Add hooks to execute functions during data creation or update. Hooks receive three arguments:
+Add hooks to execute functions during data creation or update.
+
+#### Field-level Hooks
+
+Set hooks directly on individual fields.
 
-- `value`: User input if provided, otherwise existing value on update or null on create
-- `data`: Entire record data (for accessing other field values)
+Create hooks receive:
+
+- `input`: The field value from the input (null when not provided)
 - `invoker`: Principal performing the operation
+- `now`: Operation timestamp (`Date`), shared across all hooks in the same operation
 
-#### Field-level Hooks
+Update hooks receive the same arguments plus:
 
-Set hooks directly on individual fields:
+- `oldValue`: The previous field value (null only for optional fields)
 
 ```typescript
 db.string().hooks({
   create: ({ invoker }) => invoker?.id ?? "",
-  update: ({ value }) => value,
+  update: ({ input, oldValue }) => input ?? oldValue,
 });
 ```
 
-**Note:** When setting hooks at the field level, the `data` argument type is `unknown` since the field doesn't know about other fields in the type. Use type-level hooks if you need to access other fields with type safety.
+Field-level hooks operate on a single field and cannot access other fields. Use type-level hooks for cross-field logic.
 
 #### Type-level Hooks
 
-Set hooks for multiple fields at once using `db.table().hooks()`:
+Set hooks across multiple fields using `db.table().hooks()`. The hook returns an object with the fields to override. When both field-level and type-level hooks exist for the same field, type-level hooks take priority.
+
+Create hooks receive:
+
+- `input`: The submitted record data. When field-level hooks or defaults exist, `input` reflects their applied results
+- `invoker`: Principal performing the operation
+- `now`: Operation timestamp (`Date`), shared across all hooks in the same operation
+
+Update hooks receive the same arguments plus:
+
+- `oldRecord`: The existing record (non-null)
 
 ```typescript
 export const customer = db
@@ -310,60 +333,56 @@ export const customer = db
     fullName: db.string(),
   })
   .hooks({
-    fullName: {
-      create: ({ data }) => `${data.firstName} ${data.lastName}`,
-      update: ({ data }) => `${data.firstName} ${data.lastName}`,
-    },
+    create: ({ input }) => ({
+      fullName: `${input.firstName} ${input.lastName}`,
+    }),
+    update: ({ input, oldRecord }) => ({
+      fullName: `${input.firstName ?? oldRecord.firstName} ${input.lastName ?? oldRecord.lastName}`,
+    }),
   });
 ```
 
-**Important:** Field-level and type-level hooks cannot coexist on the same field. TypeScript will prevent this at compile time:
+Use `now` to stamp several fields with the exact same instant:
 
 ```typescript
-// Compile error - cannot set hooks on the same field twice
-export const user = db
-  .table("User", {
-    name: db.string().hooks({ create: ({ data }) => data.firstName }), // Field-level
+export const order = db
+  .table("Order", {
+    createdAt: db.datetime(),
+    updatedAt: db.datetime(),
   })
   .hooks({
-    name: { create: ({ data }) => data.lastName }, // Type-level - ERROR
-  });
-
-// OK - set hooks on different fields
-export const user = db
-  .table("User", {
-    firstName: db.string().hooks({ create: () => "John" }), // Field-level on firstName
-    lastName: db.string(),
-  })
-  .hooks({
-    lastName: { create: () => "Doe" }, // Type-level on lastName
+    create: ({ now }) => ({ createdAt: now, updatedAt: now }),
+    update: ({ now }) => ({ updatedAt: now }),
   });
 ```
 
+**Note:** `.hooks()` can only be called once on a type. Duplicate type-level calls fail at compile time and throw at runtime.
+
 ### Validation
 
-Add validation rules to fields. Validators receive three arguments (executed after hooks):
+Add validation rules to fields. Validators run after hooks.
 
-- `value`: Field value after hook transformation
-- `data`: Entire record data after hook transformations (for accessing other field values)
-- `invoker`: Principal performing the operation
+**Note:** Custom validators run only when built-in type validation succeeds, so `value` always has the field's declared type. For array fields, the validator is called once with the complete array, not per element:
 
-Validators return `true` for success, `false` for failure. Use array form `[validator, errorMessage]` for custom error messages.
+```typescript
+// value is string[], not string
+db.string({ array: true }).validate(({ value }) => value.length >= 2);
+```
 
 #### Field-level Validation
 
-Set validators directly on individual fields:
+Set validators directly on individual fields. Each validator receives `{ value }` (the field value after hooks) and returns an error message string to fail, or void to pass:
 
 ```typescript
 db.string().validate(
-  ({ value }) => value.includes("@"),
-  [({ value }) => value.length >= 5, "Email must be at least 5 characters"],
+  ({ value }) => (value.includes("@") ? undefined : "Must contain @"),
+  ({ value }) => (value.length >= 5 ? undefined : "Must be at least 5 characters"),
 );
 ```
 
 #### Type-level Validation
 
-Set validators for multiple fields at once using `db.table().validate()`:
+Set a validator across all fields using `db.table().validate()`. The validator receives `{ newRecord, oldRecord, invoker }` and an `issues()` callback to report errors per field:
 
 ```typescript
 export const user = db
@@ -371,38 +390,33 @@ export const user = db
     name: db.string(),
     email: db.string(),
   })
-  .validate({
-    name: [({ value }) => value.length > 5, "Name must be longer than 5 characters"],
-    email: [
-      ({ value }) => value.includes("@"),
-      [({ value }) => value.length >= 5, "Email must be at least 5 characters"],
-    ],
+  .validate(({ newRecord }, issues) => {
+    if (newRecord.name.length <= 5) {
+      issues("name", "Name must be longer than 5 characters");
+    }
+    if (!newRecord.email.includes("@")) {
+      issues("email", "Must contain @");
+    }
   });
 ```
 
-**Important:** Field-level and type-level validation cannot coexist on the same field. TypeScript will prevent this at compile time:
+### Defaults
+
+Set a default value for a required field on create. The field becomes optional in the create input — the default fills in when no value is provided:
 
 ```typescript
-// Compile error - cannot set validation on the same field twice
-export const user = db
-  .table("User", {
-    name: db.string().validate(({ value }) => value.length > 0), // Field-level
-  })
-  .validate({
-    name: [({ value }) => value.length < 100, "Too long"], // Type-level - ERROR
-  });
+db.int().default(0);
+db.string().default("pending");
+```
 
-// OK - set validation on different fields
-export const user = db
-  .table("User", {
-    name: db.string().validate(({ value }) => value.length > 0), // Field-level on name
-    email: db.string(),
-  })
-  .validate({
-    email: [({ value }) => value.includes("@"), "Invalid email"], // Type-level on email
-  });
+For datetime/date/time fields, pass `"now"` to use the operation timestamp:
+
+```typescript
+db.datetime().default("now");
 ```
 
+**Note:** `.validate()` can only be called once on a type. Duplicate type-level calls fail at compile time and throw at runtime.
+
 ### Vector Search
 
 ```typescript
@@ -436,6 +450,22 @@ export const user = db.table("User", {
 
 ## Type Modifiers
 
+Type builder methods that set one type-level configuration can be called only once on the same type. Duplicate calls fail at compile time and throw at runtime. This applies to `.description()`, `.hooks()`, `.validate()`, `.features()`, `.indexes()`, `.files()`, `.permission()`, and `.gqlPermission()`.
+
+Conditional assignment is still supported when only one branch calls the method:
+
+```typescript
+let user = db.type("User", {
+  name: db.string(),
+});
+
+if (enableFiles) {
+  user = user.files({
+    avatar: "profile image",
+  });
+}
+```
+
 ### Composite Indexes
 
 ```typescript
@@ -552,6 +582,8 @@ Available options:
 | `optional` | Makes the selected fields optional    |
 | `array`    | Makes the selected fields array types |
 
+**Note:** The `array` option cannot change fields with custom validation — their validators expect the original value shape. Define a new field with a matching validator instead.
+
 #### `omitFields(keys)`
 
 Return all fields except the specified ones:

package/docs/services/workflow.md

@@ -397,7 +397,7 @@ export default defineConfig({
 
 `key` accepts `[a-z0-9_:.-]` and must start with `[a-z0-9]`. An exact key must also end with `[a-z0-9]`; a wildcard prefix (`matchType: "prefix"`) may end with any of those characters, since the platform appends a trailing `*` after it. The platform-registered key — including that trailing `*` when wildcarded — is 2 to 64 characters long, so a wildcard prefix must be at most 63 characters. `foo:bar` is a valid exact key; `tenant-api` with `matchType: "prefix"` registers `tenant-api*` as a wildcard prefix.
 
-An exact-key policy applies to dispatches whose runtime key equals the policy key. A wildcard policy applies to every dispatch whose runtime key begins with the prefix; each concrete resolved key gets its own independent pool of the declared size (a `cap = 3` wildcard yields three concurrent dispatches per resolved key, not three across every match). The longest matching prefix wins when a dispatch could match more than one wildcard.
+An exact-key policy applies to dispatches whose runtime key equals the policy key. A wildcard policy applies to every dispatch whose runtime key begins with the prefix; each concrete resolved key gets its own independent pool of the declared size (a `cap = 3` wildcard yields three concurrent dispatches per resolved key, not three across every match). When a dispatch matches more than one policy (for example, an exact key that also falls under a wildcard prefix, or two wildcard prefixes where one starts with the other), every matching policy's cap is enforced independently, and the tightest one blocks.
 
 ### Referencing a Policy from a Workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.0.0-next.4",
+  "version": "2.0.0-next.5",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -157,11 +157,11 @@
     "@opentelemetry/exporter-trace-otlp-proto": "0.220.0",
     "@opentelemetry/resources": "2.9.0",
     "@opentelemetry/sdk-trace-node": "2.9.0",
-    "@opentelemetry/semantic-conventions": "1.41.1",
-    "@oxc-project/types": "0.138.0",
+    "@opentelemetry/semantic-conventions": "1.43.0",
+    "@oxc-project/types": "0.139.0",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@toiroakr/lines-db": "0.10.0",
+    "@toiroakr/lines-db": "0.10.1",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.10",
@@ -172,26 +172,26 @@
     "es-toolkit": "1.49.0",
     "find-up-simple": "1.0.1",
     "globals": "17.7.0",
-    "graphql": "17.0.1",
+    "graphql": "17.0.2",
     "inflection": "3.0.2",
-    "kysely": "0.29.2",
+    "kysely": "0.29.3",
     "madge": "8.0.0",
     "mime-types": "3.0.2",
     "open": "11.0.0",
-    "oxc-parser": "0.138.0",
+    "oxc-parser": "0.139.0",
     "p-limit": "7.3.0",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.1",
-    "politty": "0.11.0",
-    "rolldown": "1.1.4",
+    "politty": "0.11.2",
+    "rolldown": "1.1.5",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
-    "std-env": "4.1.0",
+    "std-env": "4.2.0",
     "table": "6.9.0",
     "ts-cron-validator": "1.1.5",
-    "type-fest": "5.7.0",
-    "undici": "8.6.0",
+    "type-fest": "5.8.0",
+    "undici": "8.7.0",
     "xdg-basedir": "5.1.0",
     "zod": "4.4.3"
   },
@@ -199,19 +199,19 @@
     "@opentelemetry/sdk-trace-base": "2.9.0",
     "@types/madge": "5.0.3",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.13.2",
+    "@types/node": "24.13.3",
     "@types/semver": "7.7.1",
-    "@typescript/native-preview": "7.0.0-dev.20260703.1",
-    "@vitest/coverage-v8": "4.1.9",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitest/coverage-v8": "4.1.10",
     "eslint-plugin-zod": "4.7.0",
-    "oxfmt": "0.57.0",
-    "oxlint": "1.72.0",
+    "oxfmt": "0.58.0",
+    "oxlint": "1.73.0",
     "oxlint-tsgolint": "0.24.0",
-    "sonda": "0.13.1",
-    "tsdown": "0.22.3",
+    "sonda": "0.14.0",
+    "tsdown": "0.22.4",
     "typescript": "6.0.3",
-    "vitest": "4.1.9",
-    "zinfer": "0.2.3",
+    "vitest": "4.1.10",
+    "zinfer": "0.2.5",
     "@tailor-platform/tailor-proto": "^0.0.0"
   },
   "peerDependencies": {
@@ -244,7 +244,7 @@
     "check:import-cycles": "node --experimental-strip-types scripts/check-import-cycles.ts",
     "lint:fix": "oxlint --type-aware . --fix",
     "typecheck": "tsc --noEmit",
-    "typecheck:go": "tsgo",
+    "typecheck:go": "tsgo --tsBuildInfoFile ./.tsgo.tsbuildinfo",
     "perf:typecheck": "bash scripts/perf/exec.sh",
     "perf:runtime": "bash scripts/perf/runtime-perf.sh",
     "prepublish": "pnpm run build",

package/dist/application-BO4ZF8wP.mjs

@@ -1,3 +0,0 @@
-import { n as generatePluginFilesIfNeeded, r as loadApplication, t as defineApplication } from "./application-BX13RArL.mjs";
-
-export { defineApplication, generatePluginFilesIfNeeded };