@tailor-platform/sdk 2.0.0-next.10 → 2.0.0-next.11

package/docs/cli/tailordb.md

@@ -94,13 +94,14 @@ tailor tailordb migration <command>
 
 **Commands**
 
-| Command                                                       | Description                                                                                                                                          |
-| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tailordb migration generate`](#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot.                            |
-| [`tailordb migration script`](#tailordb-migration-script)     | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none. |
-| [`tailordb migration set`](#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                                                       |
-| [`tailordb migration status`](#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                 |
-| [`tailordb migration sync`](#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                |
+| Command                                                       | Description                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tailordb migration generate`](#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot.                                                                                                                                                              |
+| [`tailordb migration script`](#tailordb-migration-script)     | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.                                                                                                                                   |
+| [`tailordb migration set`](#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                         |
+| [`tailordb migration status`](#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                   |
+| [`tailordb migration sync`](#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                                                                                                                                                  |
+| [`tailordb migration validate`](#tailordb-migration-validate) | Validate the full migration history and detect schema drift (local types vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found. |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -180,6 +181,12 @@ tailor tailordb migration set [options] <number>
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+The migration number must be a 4-digit value (e.g. `0001`) or a bare integer (e.g. `1`) within 0–9999, and must exist in the local migration history; `0` is always accepted as the baseline, provided the local history passes validation. A gapped history is rejected.
+
+Metadata lookup failures (authentication, permission, or network errors) are reported as errors; only a not-yet-deployed namespace is treated as having no checkpoint.
+
 #### tailordb migration status
 
 Show the current migration status for TailorDB namespaces, including applied and pending migrations.
@@ -201,6 +208,10 @@ tailor tailordb migration status [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+Metadata lookup failures (authentication, permission, or network errors) are reported per namespace and make the command exit non-zero; only a not-yet-deployed namespace is treated as having no applied migrations.
+
 #### tailordb migration sync
 
 Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).
@@ -229,6 +240,27 @@ tailor tailordb migration sync [options] <number>
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+#### tailordb migration validate
+
+Validate the full migration history and detect schema drift (local types vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found.
+
+**Usage**
+
+```
+tailor tailordb migration validate [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`           |
+| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (validates all namespaces if not specified) | No       | -                    | -                              |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
 **See also:** For migration concepts, configuration, workflow, and troubleshooting, see the [TailorDB Migrations guide](../services/tailordb-migration.md).
 
 ### tailordb erd

package/docs/cli-reference.md

@@ -200,16 +200,17 @@ Commands for managing Tailor Platform applications (work with `tailor.config.ts`
 
 Commands for managing TailorDB tables, data, and schema migrations.
 
-| Command                                                                      | Description                                                                                                                                          |
-| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [tailordb](./cli/tailordb.md#tailordb)                                       | Manage TailorDB tables and data.                                                                                                                     |
-| [tailordb truncate](./cli/tailordb.md#tailordb-truncate)                     | Truncate (delete all records from) TailorDB tables.                                                                                                  |
-| [tailordb migration](./cli/tailordb.md#tailordb-migration)                   | Manage TailorDB schema migrations.                                                                                                                   |
-| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot.                            |
-| [tailordb migration script](./cli/tailordb.md#tailordb-migration-script)     | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none. |
-| [tailordb migration set](./cli/tailordb.md#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                                                       |
-| [tailordb migration status](./cli/tailordb.md#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                 |
-| [tailordb migration sync](./cli/tailordb.md#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                |
+| Command                                                                      | Description                                                                                                                                                                                                                                                                            |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [tailordb](./cli/tailordb.md#tailordb)                                       | Manage TailorDB tables and data.                                                                                                                                                                                                                                                       |
+| [tailordb truncate](./cli/tailordb.md#tailordb-truncate)                     | Truncate (delete all records from) TailorDB tables.                                                                                                                                                                                                                                    |
+| [tailordb migration](./cli/tailordb.md#tailordb-migration)                   | Manage TailorDB schema migrations.                                                                                                                                                                                                                                                     |
+| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot.                                                                                                                                                              |
+| [tailordb migration script](./cli/tailordb.md#tailordb-migration-script)     | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.                                                                                                                                   |
+| [tailordb migration set](./cli/tailordb.md#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                         |
+| [tailordb migration status](./cli/tailordb.md#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                   |
+| [tailordb migration sync](./cli/tailordb.md#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                                                                                                                                                  |
+| [tailordb migration validate](./cli/tailordb.md#tailordb-migration-validate) | Validate the full migration history and detect schema drift (local types vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found. |
 
 ### [Query Commands](./cli/query.md)
 

package/docs/configuration.md

@@ -86,6 +86,21 @@ export default defineConfig({
 
 **Pattern resolution**: `files` and `ignores` patterns are resolved relative to the directory of the `tailor.config.ts` file that declares them, not the directory you run the command from. This matters when deploying [multiple configs](./cli/application.md#deploy) together — each config's patterns only match files under its own directory. If a config's _relative_ patterns match nothing under its own directory, the SDK falls back to resolving them from the directory you ran the command from and logs a warning (this fallback doesn't apply to already-absolute patterns, since their resolution can't change). Update such patterns to be relative to the config's own directory — this fallback will be removed in v2.
 
+### Bundling
+
+Resolvers, executors, workflow jobs, auth hooks, HTTP adapters, TailorDB hooks and validators, functions, seeds, queries, and migration scripts are all bundled before running locally or deploying. Bundling honors `compilerOptions.paths` aliases declared in a `tsconfig.json`, resolved against the importing file's own nearest `tsconfig.json` (the first one found walking up from that file's directory, following its `extends` chain) — so a path alias works the same whether it is imported directly or through another aliased import.
+
+An import that cannot be resolved fails the command instead of shipping a broken bundle, naming the specifier, the importing file, and the tsconfig the build used:
+
+```
+Error [UNRESOLVED_IMPORT]: Could not resolve "@lib/missing" imported from "/path/to/resolver.ts".
+  Suggestion: Check that each import path is correct, and that a `compilerOptions.paths`
+  entry covering it is declared in the importing file's own tsconfig.json or an ancestor.
+  The build used "/path/to/tsconfig.json".
+```
+
+If the unresolved specifier is a Node.js built-in (e.g. `fs`, `crypto`, `path`), the suggestion explains that it is not available in the Tailor Platform runtime and, where one exists, names a Web-standard replacement (e.g. the Fetch API instead of `http`/`https`).
+
 ### External Resources
 
 You can reference resources managed by Terraform or other SDK projects to include them in your application's subgraph. External resources are not deployed by this project but can be used for shared access across multiple applications.
@@ -113,6 +128,7 @@ When using external resources:
 - You can combine external resources with locally-defined resources
 - TailorDB type names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB type names before applying changes
 - Destructive operations like `tailordb truncate` (and `tailor seed apply --truncate`) automatically exclude external resources to prevent accidental data loss in shared resources
+- Subscribing an executor to an external resource's events requires the config that owns the resource in the same `deploy`. Publishing is then enabled automatically, and `deploy` records the dependency so a later deploy without that config asks for confirmation instead of silently turning publishing off
 
 ### Built-in IdP
 
@@ -273,6 +289,40 @@ export async function main(trx: Transaction, { env }: MigrationContext): Promise
 }
 ```
 
+#### Secret Detection
+
+`env` values are deployed as plaintext, so loading a config fails when one of them looks like a credential:
+
+```
+✖ Secret detected in 'env' in /path/to/tailor.config.ts:
+  - env.SLACK_BOT_TOKEN (matched slack: SLACK_TOKEN)
+    https://github.com/secretlint/secretlint/blob/master/packages/%40secretlint/secretlint-rule-slack/README.md#SLACK_TOKEN
+```
+
+Each finding names the pattern that matched and links to its description, so a value flagged as an AWS account id is distinguishable from one flagged as an AWS secret access key.
+
+Move the value to [Secret Manager](./services/secret.md) to fix this. Detection recognizes the credential formats published by common providers, such as Slack, GitHub and AWS.
+
+A value that is merely long and random-looking, with no recognizable provider format, is reported as a warning instead and does not fail the command.
+
+When detection is wrong about a value, allow it in place with `allowSecretReason`, stating why the value is safe to deploy as plaintext:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  env: {
+    slackRelayUrl: {
+      value: process.env.SLACK_RELAY_URL ?? "",
+      allowSecretReason: "Public relay endpoint; the token it proxies stays in Secret Manager.",
+    },
+  },
+});
+```
+
+This silences both the failure and the warning, so it also covers a value that is random-looking without being a credential — say so in the reason. Only string and number values accept an allowance: a boolean is never flagged, so it never needs one.
+
+Application code still reads `env.slackRelayUrl` as the value itself: the wrapper only carries the reason and does not reach the deployed application.
+
 ### Workflow Service
 
 Configure Workflow service by specifying glob patterns for workflow files:

package/docs/migration/v2.md

@@ -668,6 +668,70 @@ already pass a plain value unchanged.
 
 </details>
 
+## defineIdp publishUserEvents → publishEvents
+
+**Migration:** Partially automatic
+
+Rename the `defineIdp` option `publishUserEvents` to `publishEvents`, matching the field name TailorDB types, resolvers, and workflows already use.
+
+Before:
+
+```ts
+import { defineIdp } from "@tailor-platform/sdk";
+
+export const idp = defineIdp("my-idp", {
+  clients: ["my-client"],
+  publishUserEvents: true,
+});
+```
+
+After:
+
+```ts
+import { defineIdp } from "@tailor-platform/sdk";
+
+export const idp = defineIdp("my-idp", {
+  clients: ["my-client"],
+  publishEvents: true,
+});
+```
+
+A shorthand option keeps reading the same local:
+
+Before:
+
+```ts
+defineIdp("my-idp", { clients, publishUserEvents });
+```
+
+After:
+
+```ts
+defineIdp("my-idp", { clients, publishEvents: publishUserEvents });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2, the IdP option `publishUserEvents` is renamed to
+`publishEvents`, so all four services that publish events use one field name.
+The codemod rewrites the option key on `defineIdp` calls whose callee resolves
+to the SDK export, including aliased and namespace imports, and rewrites a
+shorthand `{ publishUserEvents }` to `{ publishEvents: publishUserEvents }` so
+it keeps reading the same local.
+
+Also review, and migrate by hand:
+- An options object built in a variable or spread into the call — the codemod
+  only rewrites object literals passed directly to `defineIdp`.
+- A computed key (e.g. `[key]: value`) that resolves to `publishUserEvents`.
+- Type annotations or interfaces that declare the option themselves.
+- A file where a local declaration shadows the `defineIdp` import; the codemod
+  skips it because the call may not be the SDK export.
+```
+
+</details>
+
 ## defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints
 
 **Migration:** Partially automatic
@@ -694,11 +758,11 @@ export const { approval } = createWaitPoints((define) => ({
 }));
 ```
 
-## workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/startJobFunction/resumeWorkflowExecution
+## workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/execJobFunction/resumeWorkflowExecution
 
 **Migration:** Partially automatic
 
-Rename tailor.workflow call sites from the pre-alignment triggerWorkflow/triggerJobFunction/resumeWorkflow names to the canonical startWorkflow/startJobFunction/resumeWorkflowExecution names, on both the ambient tailor.workflow global and a workflow value imported from @tailor-platform/sdk/runtime(/workflow). For a renamed triggerWorkflow call, also renames a literal `invoker` option key to `authInvoker` — startWorkflow's options expect the platform shape directly, unlike the removed triggerWorkflow wrapper, which converted invoker to authInvoker internally.
+Rename tailor.workflow call sites from the pre-alignment triggerWorkflow/triggerJobFunction/resumeWorkflow names to the canonical startWorkflow/execJobFunction/resumeWorkflowExecution names, on both the ambient tailor.workflow global and a workflow value imported from @tailor-platform/sdk/runtime(/workflow). For a renamed triggerWorkflow call, also renames a literal `invoker` option key to `authInvoker` — startWorkflow's options expect the platform shape directly, unlike the removed triggerWorkflow wrapper, which converted invoker to authInvoker internally.
 
 Before:
 
@@ -736,7 +800,7 @@ await workflow.startWorkflow("myWorkflow", { data: "value" }, { authInvoker: myI
 ```text
 The pre-alignment tailor.workflow names triggerWorkflow, triggerJobFunction, and
 resumeWorkflow are removed from the SDK's type surface in v2; use the canonical
-startWorkflow, startJobFunction, and resumeWorkflowExecution names instead. The
+startWorkflow, execJobFunction, and resumeWorkflowExecution names instead. The
 codemod rewrites direct member-access call sites on the ambient tailor.workflow
 global and on a workflow value imported from @tailor-platform/sdk/runtime or
 @tailor-platform/sdk/runtime/workflow (including aliased imports). It skips a
@@ -753,7 +817,7 @@ Also review, and migrate by hand:
 - Destructured references (e.g. const { triggerWorkflow } = workflow) — the
   codemod only rewrites direct member-access calls.
 - Imported TriggerWorkflowOptions / TriggerJobFunctionOptions types — rename
-  them to StartWorkflowOptions / StartJobFunctionOptions.
+  them to StartWorkflowOptions / ExecJobFunctionOptions.
 - An invoker option passed via a variable or spread (not a literal object) —
   the codemod only inspects literal object arguments; rename the invoker key
   to authInvoker in the options object's own definition.
@@ -761,6 +825,52 @@ Also review, and migrate by hand:
 
 </details>
 
+## workflow.startJobFunction → execJobFunction
+
+**Migration:** Partially automatic
+
+`tailor.workflow.startJobFunction` and the `StartJobFunctionOptions` type are removed in v2. Use the canonical `execJobFunction` / `ExecJobFunctionOptions`: `Exec*` blocks and returns the job's result, while `Start*` returns only an execution ID. The codemod rewrites member-access call sites on the ambient `tailor.workflow` global and on a `workflow` value imported from @tailor-platform/sdk/runtime(/workflow), and renames `StartJobFunctionOptions` imports along with the type references that resolve to them.
+
+Before:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+const result = workflow.startJobFunction("myJob", { data: "value" });
+```
+
+After:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+const result = workflow.execJobFunction("myJob", { data: "value" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+startJobFunction is removed from the SDK's workflow runtime surface in v2;
+execJobFunction is the canonical name for a blocking job call that returns the
+job's result. The codemod rewrites direct member-access calls on the ambient
+tailor.workflow global and on a workflow value imported from
+@tailor-platform/sdk/runtime or @tailor-platform/sdk/runtime/workflow (including
+aliased imports), and renames the StartJobFunctionOptions type. It skips a file
+entirely when a local declaration shadows the workflow import or the ambient
+tailor name, to avoid rewriting an unrelated same-named value.
+
+Also review, and migrate by hand:
+- Destructured references (e.g. const { startJobFunction } = workflow) — the
+  codemod only rewrites direct member-access calls.
+- mockWorkflow().startJobFunction in tests — assert on the execJobFunction vi.fn
+  instead; the alias was the same mock function.
+- A file that already imports ExecJobFunctionOptions alongside the removed type —
+  rename the remaining references by hand and drop the duplicate specifier.
+```
+
+</details>
+
 ## openDownloadStream → downloadStream
 
 **Migration:** Manual
@@ -1253,9 +1363,9 @@ single generation pass and resolves once it completes.
 
 ## Generated seed exec.mjs → tailor seed CLI plugin
 
-**Migration:** Manual
+**Migration:** Partially automatic
 
-`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, type-name arguments).
+`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, type-name arguments), plus a new `--upsert` flag to update existing rows instead of failing on duplicate ids.
 
 Before:
 
@@ -1272,7 +1382,7 @@ After:
 ```
 
 <details>
-<summary>Prompt for an AI agent (to perform this migration)</summary>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
 
 ```text
 seedPlugin no longer generates the exec.mjs seed runner in v2. The tailor seed
@@ -1282,11 +1392,194 @@ CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:
   @tailor-platform/sdk.
 - Replace `node <distPath>/exec.mjs [options] [types...]` invocations with
   `tailor seed apply [options] [types...]` (same options: --machine-user/-m,
-  --namespace/-n, --skip-idp, --truncate, --yes, and type-name arguments).
+  --namespace/-n, --skip-idp, --truncate, --yes, and type-name arguments,
+  plus a new --upsert flag to update existing rows instead of failing on
+  duplicate ids).
 - Replace `node <distPath>/exec.mjs validate [path]` with
   `tailor seed validate [path]`.
+- Rewrite `fork("<distPath>/exec.mjs", ...)` call sites (test setup files
+  typically fork the runner and await a hand-rolled Promise around
+  `child.on("close", ...)`). The plugin is a CLI-dispatched binary rather
+  than a forkable JS module, so call it synchronously instead —
+  `execSync("npx tailor seed apply", { env, stdio: "inherit" })` — keeping
+  the original `env` and `stdio` forwarding, and unwind the surrounding
+  Promise wrapper (drop the now-unused `await`, and the `async` keyword when
+  nothing else in the function awaits). Note that `execSync` throws on a
+  nonzero exit, replacing the wrapper's explicit reject.
 - Delete the stale generated `<distPath>/exec.mjs` file; keep the data/
-  directory (JSONL data and generated schemas) as-is.
+  directory (JSONL data and generated schemas) as-is. Nothing removes it
+  automatically, and a leftover runner keeps working while no longer being
+  regenerated.
+```
+
+</details>
+
+## @tailor-platform/sdk/test global mocks → @tailor-platform/sdk/vitest
+
+**Migration:** Manual
+
+The global platform mocks exported from `@tailor-platform/sdk/test` (`setupTailordbMock`, `setupWorkflowMock`, `setupWaitPointMock`, `setupInvokerMock`, `setupTailorErrorsMock`) and the bundled-output helper `createImportMain` are removed in v2. Use the `tailor-runtime` environment from `@tailor-platform/sdk/vitest` together with `mockTailordb` / `mockWorkflow`: the environment injects `TailorErrors` for you, `setWaitHandler` / `setResolveHandler` replace the wait-point stubs, and the invoker is driven through `globalThis.tailor.context.getInvoker` (or passed directly to `.body()` when testing the TypeScript source). No codemod ships for this migration: it replaces per-test global stubs with a Vitest environment plus disposable mocks, which changes the Vitest config, the setup shape, and the assertions of every affected test. The other `@tailor-platform/sdk/test` exports (`createTailorDBHook`, `createStandardSchema`, `unauthenticatedTailorUser`) are unchanged.
+
+Job mocks move from a global stub to a disposable mock:
+
+Before:
+
+```ts
+import { setupWorkflowMock } from "@tailor-platform/sdk/test";
+
+const { startedJobs } = setupWorkflowMock(() => ({ ok: true }));
+```
+
+After:
+
+```ts
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+
+using wf = mockWorkflow();
+wf.setJobHandler(() => ({ ok: true }));
+// wf.startedJobs replaces the returned startedJobs array
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The global platform mocks from @tailor-platform/sdk/test are removed in v2.
+Migrate each affected test to the tailor-runtime Vitest environment:
+
+1. Add the environment for the test files that need platform globals — set
+   environment: "tailor-runtime" in the Vitest project config, or add the
+   // @vitest-environment tailor-runtime docblock to the file. The environment
+   ships in @tailor-platform/sdk/vitest and installs TailorErrors and the base
+   tailor/tailordb globals, so setupTailorErrorsMock has no replacement — delete it.
+2. Replace setupTailordbMock(resolver) with using db = mockTailordb() and
+   configure query results on that mock; read its recorded calls instead of the
+   returned executedQueries / createdClients arrays.
+3. Replace setupWorkflowMock(handler) with using wf = mockWorkflow() plus
+   wf.setJobHandler(handler) (or wf.enqueueResult(...) for order-based results),
+   and read wf.startedJobs.
+4. Replace setupWaitPointMock({ onWait, onResolve }) with the same mockWorkflow()
+   handle: wf.setWaitHandler / wf.setResolveHandler, asserting on wf.waitCalls /
+   wf.resolveCalls.
+5. Replace setupInvokerMock(invoker) with
+   vi.spyOn(globalThis.tailor.context, "getInvoker").mockReturnValue(raw) for a
+   bundled test, or pass invoker directly to .body() when unit-testing a
+   resolver/executor/workflow job against the TypeScript source.
+6. Drop createImportMain and the tests that import bundled output through it.
+   Bundling integrity is the SDK's responsibility: unit-test the TypeScript
+   source and cover deployed behavior with E2E tests instead.
+
+See the SDK testing guide for the full environment setup.
+```
+
+</details>
+
+## Programmatic CLI name options → workflow/executor definitions
+
+**Migration:** Manual
+
+The name-keyed option types exported from `@tailor-platform/sdk/cli` — `GetWorkflowOptions`, `StartWorkflowOptions`, `ListWorkflowExecutionsOptions`, `GetExecutorOptions`, `TriggerExecutorOptions`, `ListExecutorJobsOptions`, `GetExecutorJobOptions`, `WatchExecutorJobOptions` — are removed in v2, together with the function overloads that accepted them. Pass the workflow or executor definition itself instead: `{ workflow: myWorkflow, invoker: "admin" }` / `{ executor: myExecutor }`, matching the `*TypedOptions` shape that types `arg` and `payload` from the definition. No codemod ships for this migration: rewriting a name string into a definition requires importing the module that defines the workflow or executor, which a source-local transform cannot resolve.
+
+Before:
+
+```ts
+import { startWorkflow } from "@tailor-platform/sdk/cli";
+
+const { executionId } = await startWorkflow({ name: "user-sync", machineUser: "admin" });
+```
+
+After:
+
+```ts
+import { startWorkflow } from "@tailor-platform/sdk/cli";
+import userSync from "./workflows/userSync";
+
+const { executionId } = await startWorkflow({ workflow: userSync, invoker: "admin" });
+```
+
+Executor commands take the executor definition:
+
+Before:
+
+```ts
+const result = await watchExecutorJob({ executorName: "daily-sync", jobId });
+```
+
+After:
+
+```ts
+const result = await watchExecutorJob({ executor: dailySync, jobId });
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The programmatic CLI functions in @tailor-platform/sdk/cli no longer accept a
+workflow or executor name; they take the definition object instead. For each
+flagged call site:
+
+1. Import the workflow or executor definition — the module whose default export
+   is createWorkflow(...) or whose export is createExecutor(...) with that name.
+2. Replace name: "my-workflow" with workflow: myWorkflow, and
+   executorName: "my-executor" with executor: myExecutor. For
+   listWorkflowExecutions, workflowName becomes workflow.
+3. startWorkflow's machine user moves from machineUser to the required
+   invoker, typed against the machine users declared in tailor.config.ts.
+4. Replace imported option types with the *TypedOptions equivalent
+   (e.g. GetWorkflowOptions → GetWorkflowTypedOptions<typeof myWorkflow>).
+   Note that arg (startWorkflow) and payload (triggerExecutor) are now typed
+   from the definition, so a mistyped argument becomes a type error.
+
+When the name is only known at runtime (read from argv or an environment
+variable), the CLI command itself — `tailor workflow start <name>` /
+`tailor executor trigger <name>` — remains the name-keyed entry point.
+```
+
+</details>
+
+## tailor.d.ts Env uses value types instead of literal values
+
+**Migration:** Manual
+
+The `Env` interface in `tailor.d.ts` is generated from the type of each `defineConfig({ env })` value (`string`, `number`, or `boolean`) instead of the value itself, so the generated file no longer carries whatever the config resolved to when it was generated. Keys that aren't valid TypeScript identifiers are quoted, which previously produced a file that failed to parse. Run `tailor generate` to refresh the file, then widen any code that depended on the old literal types. If a `tailor.d.ts` you already committed contains a sensitive value, treat that value as exposed and rotate it; keep secrets in Secret Manager rather than `env`.
+
+An env value can no longer stand in for a literal union; narrow it explicitly:
+
+Before:
+
+```ts
+const stage: "production" | "staging" = env.STAGE;
+```
+
+After:
+
+```ts
+const stage = env.STAGE === "staging" ? "staging" : "production";
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Tailor SDK v2 generates the `Env` interface in `tailor.d.ts` from the type of
+each `defineConfig({ env })` value (`string`, `number`, `boolean`) instead of
+the resolved value, so `Env` properties no longer carry literal types.
+
+Run `tailor generate` first to refresh `tailor.d.ts`, then review the places
+that depended on the old literal types:
+
+- An env value assigned or passed where a literal union is required, e.g.
+  `const stage: "production" | "staging" = env.STAGE`. Narrow it with a
+  comparison or a validation helper instead of relying on the declared type.
+- A generic argument, conditional type, or template-literal type parameterized
+  by an env value.
+- `as const` / `satisfies` assertions that assumed one specific literal.
+
+Plain comparisons (`env.STAGE === "production"`) and arithmetic on numeric env
+values keep working and need no change. Do not restore the old behavior by
+editing `tailor.d.ts`: it is generated and will be overwritten, and embedding
+env values there is what leaked configured secrets into version control.
 ```
 
 </details>
@@ -1295,6 +1588,10 @@ CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:
 
 These v2 changes alter runtime or CLI behavior; no source change is needed.
 
+### publishEvents recomputed from the executors in each deploy
+
+An unset `publishEvents` is recomputed on every `deploy` from the executors taking part in the run, in both directions: adding a subscribing trigger turns publishing on, and removing the last one turns it back off. Previously a workflow or job kept publishing once it had been enabled, so a workflow whose subscribing trigger is already gone stops publishing on the next `deploy` — declare `publishEvents: true` on it if something outside this project consumes those events. `deploy` also stops instead of applying when a subscription cannot be satisfied: when a trigger names a resource no config in the run declares, when a workflow or job combines `publishEvents: false` with a subscribing trigger, and when a config that resolves without an `id` subscribes across configs. Each of those errors names the resource and both ways to resolve it.
+
 ### CLI tokens stored in the OS keyring
 
 CLI login tokens are stored in the OS keyring by default when available, falling back to the platform config file when it is not. No source change is required; re-login if you need tokens moved into the keyring.

package/docs/runtime.md

@@ -84,7 +84,7 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
 - `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
 - `idp` — IdP user management (`new Client({ namespace })`)
-- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `execJobFunction`, `wait`, `resolve`; `startJobFunction` is kept as an alias of `execJobFunction`)
+- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `execJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
 - `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
 - `aigateway` — AI Gateway URL resolution (`get`)