@sanity/workflow-blueprint 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanity, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @sanity/workflow-blueprint
+
+[Sanity Blueprints](https://www.sanity.io/docs/blueprints/blueprints-introduction)
+integration for Editorial Workflows: declare a workflow definition deployment
+as a blueprint resource, and provision it from a blueprint resource provider.
+
+> [!NOTE]
+> Early access, restricted — and deliberately in-between. The
+> `sanity.workflow` resource type has no registered provider in the
+> blueprints service yet: **do not add this resource to a real blueprint** —
+> how the service treats an unregistered resource type is unverified and may
+> fail the whole stack operation. Until the provider is registered, the
+> workflow CLI (`sanity-workflows deploy`) remains the only working deploy
+> path; what this package delivers today is the eager manifest-evaluation
+> validation and the provider core that the registered provider will execute.
+
+## Declaring the resource
+
+`defineWorkflows` takes the same deployment shape as one
+`deployments[]` entry of a `sanity.workflow.ts` config, so an existing entry
+drops in unchanged:
+
+```ts
+// sanity.blueprint.ts
+import {defineBlueprint} from '@sanity/blueprints'
+import {defineWorkflows} from '@sanity/workflow-blueprint'
+import config from './sanity.workflow'
+
+export default defineBlueprint({
+  resources: [defineWorkflows(config.deployments[0])],
+})
+```
+
+The definer validates eagerly — definition structure, GROQ, and
+`@<handle>:` alias bindings all fail at manifest evaluation, in the author's
+terminal, never as a failed stack operation. The resulting resource is pure
+data: the deployment rides the manifest verbatim, definitions in authored
+form (alias expansion happens at provision).
+
+Blueprints matches resources by `name` (default:
+`editorial-workflows-<tag>`) — keep the name stable once instances exist.
+Definitions are **retain-only** through blueprints: the default lifecycle is
+`{deletionPolicy: 'retain'}` (removing the resource detaches the deployed
+definitions instead of deleting them), and a policy that promises deletion
+(`allow`, `replace`) is rejected at manifest evaluation.
+
+## The provider core
+
+What a `blueprints-resource-workflow` provider runs per lifecycle phase:
+
+```ts
+import {destroyWorkflowResource, provisionWorkflowResource} from '@sanity/workflow-blueprint'
+
+// create and update are the same operation: the engine's definition deploy is
+// content-addressed and create-only, so identical content is a no-op and any
+// change mints the next immutable version.
+await provisionWorkflowResource({resource, client})
+
+// destroy always refuses: definitions are retain-only through blueprints, so
+// an infrastructure teardown can never take editorial state with it. Deleting
+// a definition is a deliberate act through the workflow CLI's
+// `definition delete`, never a side effect of a manifest edit.
+destroyWorkflowResource()
+```
+
+`client` must be bound to the deployment's `workflowResource` with a token
+that can write definition documents there. Provisioning parses and validates
+the incoming resource at the boundary (`parseWorkflowResource`) — provider
+input is JSON from the stack, never a typed value.

package/dist/index.cjs

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+    value: !0
+});
+
+var blueprints = require("@sanity/blueprints"), workflowEngine = require("@sanity/workflow-engine"), define = require("@sanity/workflow-engine/define");
+
+const WORKFLOW_RESOURCE_TYPE = "sanity.workflow";
+
+function parseWorkflowDeployment(input, caller) {
+    const config = define.defineWorkflowConfig({
+        deployments: [ input ]
+    }), [deployment] = config.deployments;
+    if (deployment === void 0) throw new Error(`${caller}: expected a workflow deployment`);
+    workflowEngine.assertReaderModelAcknowledgement(deployment.expectedMinReaderModel, caller);
+    const definitions = deployment.definitions.map(def => workflowEngine.parseDefinitionInput(def, caller));
+    assertUniqueDefinitionNames(definitions, caller), definitions.forEach(workflowEngine.validateDefinition);
+    const aliases = workflowEngine.resourceAliasesToMap(deployment.resourceAliases);
+    for (const def of definitions) expandOrReattribute({
+        def: def,
+        aliases: aliases,
+        caller: caller
+    });
+    return assertAcyclicSpawnRefs(definitions, caller), {
+        ...deployment,
+        definitions: definitions
+    };
+}
+
+function assertUniqueDefinitionNames(definitions, caller) {
+    const seen = /* @__PURE__ */ new Set;
+    for (const def of definitions) {
+        if (seen.has(def.name)) throw new Error(`${caller}: duplicate definition name "${def.name}" in deployment`);
+        seen.add(def.name);
+    }
+}
+
+function expandOrReattribute({def: def, aliases: aliases, caller: caller}) {
+    try {
+        workflowEngine.expandResourceAliases(def, aliases);
+    } catch (error) {
+        throw new Error(workflowEngine.errorMessage(error).replace(/^workflow\.deployDefinitions: /, `${caller}: `), {
+            cause: error
+        });
+    }
+}
+
+function assertAcyclicSpawnRefs(definitions, caller) {
+    const remaining = new Map(definitions.map(def => [ def.name, def ]));
+    for (;remaining.size > 0; ) {
+        const referenced = new Set([ ...remaining.values() ].flatMap(def => workflowEngine.refsOf(def).map(ref => ref.name)).filter(name => remaining.has(name))), free = [ ...remaining.values() ].filter(def => !referenced.has(def.name));
+        if (free.length === 0) throw new Error(`${caller}: reference cycle among definitions ${[ ...remaining.keys() ].join(", ")}`);
+        for (const def of free) remaining.delete(def.name);
+    }
+}
+
+function defineWorkflows(deployment, options) {
+    const parsed = parseWorkflowDeployment(deployment, "defineWorkflows");
+    if (options?.name === "") throw new Error("defineWorkflows: `name` must be a non-empty string");
+    const policy = options?.lifecycle?.deletionPolicy;
+    if (policy === "allow" || policy === "replace") throw new Error(`defineWorkflows: deletionPolicy '${policy}' is not supported — Editorial Workflows definitions are retain-only through blueprints; delete deliberately with the workflow CLI's \`definition delete\`.`);
+    const resource = {
+        name: options?.name ?? `editorial-workflows-${parsed.tag}`,
+        type: WORKFLOW_RESOURCE_TYPE,
+        lifecycle: options?.lifecycle ?? {
+            deletionPolicy: "retain"
+        },
+        deployment: parsed
+    }, errors = blueprints.validateResource(resource);
+    if (errors.length > 0) throw new Error(`defineWorkflows: ${errors.map(error => error.message).join("; ")}`);
+    return resource;
+}
+
+function parseWorkflowResource(input) {
+    if (typeof input != "object" || input === null) throw new Error("workflow resource: expected an object");
+    const record = input;
+    if (record.type !== WORKFLOW_RESOURCE_TYPE) throw new Error(`workflow resource: expected type "${WORKFLOW_RESOURCE_TYPE}", got "${String(record.type)}"`);
+    if (typeof record.name != "string" || record.name === "") throw new Error("workflow resource: `name` must be a non-empty string");
+    const deployment = parseWorkflowDeployment(record.deployment, "workflow resource");
+    return {
+        ...record,
+        type: WORKFLOW_RESOURCE_TYPE,
+        name: record.name,
+        deployment: deployment
+    };
+}
+
+function engineScope({client: client, telemetry: telemetry}, deployment) {
+    return {
+        client: client,
+        tag: deployment.tag,
+        workflowResource: deployment.workflowResource,
+        ...telemetry === void 0 ? {} : {
+            telemetry: telemetry
+        }
+    };
+}
+
+async function provisionWorkflowResource({resource: resource, ...scope}) {
+    const {deployment: deployment} = parseWorkflowResource(resource);
+    return workflowEngine.workflow.deployDefinitions({
+        ...engineScope(scope, deployment),
+        expectedMinReaderModel: deployment.expectedMinReaderModel,
+        resourceAliases: workflowEngine.resourceAliasesToMap(deployment.resourceAliases),
+        definitions: deployment.definitions
+    });
+}
+
+function destroyWorkflowResource() {
+    throw new Error("workflow resource: destroy is not supported — Editorial Workflows definitions are retain-only through blueprints. Deployed definitions and their instances outlive the stack; delete deliberately with the workflow CLI's `definition delete`.");
+}
+
+exports.WORKFLOW_RESOURCE_TYPE = WORKFLOW_RESOURCE_TYPE;
+
+exports.defineWorkflows = defineWorkflows;
+
+exports.destroyWorkflowResource = destroyWorkflowResource;
+
+exports.parseWorkflowDeployment = parseWorkflowDeployment;
+
+exports.parseWorkflowResource = parseWorkflowResource;
+
+exports.provisionWorkflowResource = provisionWorkflowResource;

package/dist/index.d.cts

@@ -0,0 +1,154 @@
+import type { BlueprintResource } from "@sanity/blueprints";
+import { BlueprintResourceLifecycle } from "@sanity/blueprints";
+import { DeployDefinitionsResult } from "@sanity/workflow-engine";
+import { WorkflowClient } from "@sanity/workflow-engine";
+import { WorkflowDeployment } from "@sanity/workflow-engine";
+import { WorkflowTelemetryLogger } from "@sanity/workflow-engine";
+
+/**
+ * Declare an Editorial Workflows deployment as a Sanity Blueprints resource —
+ * the entry for a `sanity.blueprint.ts` `resources` array. Takes the same
+ * deployment shape as one `deployments[]` entry of a `sanity.workflow.ts`
+ * config, so an existing config entry drops in unchanged.
+ *
+ * Validates eagerly ({@link parseWorkflowDeployment}) so a bad definition or
+ * an unbound `@<handle>:` alias fails at manifest evaluation, before anything
+ * ships to the blueprint service.
+ *
+ * @remarks
+ * NOT deployable yet: the blueprints service has no registered
+ * `sanity.workflow` provider, and how it treats an unregistered resource type
+ * is unverified — adding this resource to a real blueprint may fail the whole
+ * stack operation. Until the provider is registered, deploy definitions with
+ * the workflow CLI (`sanity-workflows deploy`).
+ *
+ * ```ts
+ * // sanity.blueprint.ts
+ * import {defineBlueprint} from '@sanity/blueprints'
+ * import {defineWorkflows} from '@sanity/workflow-blueprint'
+ * import config from './sanity.workflow'
+ *
+ * export default defineBlueprint({
+ *   resources: [defineWorkflows(config.deployments[0])],
+ * })
+ * ```
+ */
+export declare function defineWorkflows(
+  deployment: WorkflowDeployment,
+  options?: DefineWorkflowsOptions,
+): EditorialWorkflowsResource;
+
+export declare interface DefineWorkflowsOptions {
+  /**
+   * Blueprint resource name — the identity blueprints matches deploys on.
+   * Defaults to `editorial-workflows-<tag>`. Renaming a deployed resource is
+   * a destroy + create, so with live instances keep the name stable.
+   */
+  name?: string;
+  /**
+   * Blueprint lifecycle policy. Defaults to `{deletionPolicy: 'retain'}`:
+   * removing the resource (or destroying its stack) detaches the deployed
+   * definitions instead of deleting them. Definitions are retain-only through
+   * blueprints — a `deletionPolicy` that promises deletion (`allow`,
+   * `replace`) is rejected here, because the provider's destroy always
+   * refuses ({@link destroyWorkflowResource}) and honouring the policy would
+   * only defer that failure to the stack operation. `protect` is accepted
+   * (stricter than retain).
+   */
+  lifecycle?: BlueprintResourceLifecycle;
+}
+
+/**
+ * Refuses, always: Editorial Workflows definitions are retain-only through
+ * blueprints. Deployed definitions — immutable, versioned, with instances
+ * pinned to them — outlive any stack, so an infrastructure teardown can never
+ * take editorial state with it. Deleting a definition is a deliberate,
+ * per-definition act through the engine's `deleteDefinition` (the workflow
+ * CLI's `definition delete`), never a side effect of a manifest edit.
+ *
+ * The definer enforces the same posture eagerly by rejecting a
+ * `deletionPolicy` that promises deletion.
+ */
+export declare function destroyWorkflowResource(): never;
+
+/**
+ * An Editorial Workflows deployment declared as a Sanity Blueprints resource.
+ * Pure data: the blueprint manifest serializes it verbatim into the stack
+ * mutation, and the provider ({@link provisionWorkflowResource}) reads it back
+ * to run the definition deploy. Blueprints matches resources by `name`, so
+ * renaming one is a destroy + create, never an update.
+ */
+export declare interface EditorialWorkflowsResource extends BlueprintResource {
+  type: typeof WORKFLOW_RESOURCE_TYPE;
+  /** The deployment to provision — the same shape as one `deployments[]`
+   *  entry of a `sanity.workflow.ts` config. Definitions are carried in
+   *  authored form; `@<handle>:` aliases expand at provision, not here. */
+  deployment: WorkflowDeployment;
+}
+
+/**
+ * Validate one deployment the way the definition deploy will, so every
+ * offline-checkable author error fails here — in the author's terminal at
+ * manifest evaluation — rather than as a failed stack operation: the
+ * deployment envelope (tag, resource binding, alias bindings) through the
+ * config schema, each definition boundary-parsed and validated, definition
+ * names checked for batch uniqueness, a dry alias expansion (fail-closed on
+ * an unbound `@<handle>:` reference), and the spawn-reference walk that
+ * rejects in-set cycles.
+ *
+ * Returns the parsed deployment (definition document envelopes stripped, so a
+ * fetched definition document round-trips cleanly).
+ */
+export declare function parseWorkflowDeployment(
+  input: unknown,
+  caller: string,
+): WorkflowDeployment;
+
+/**
+ * Parse an incoming blueprint resource document into a typed
+ * {@link EditorialWorkflowsResource}, validating the deployment exactly like
+ * the definer does. The boundary for provider lifecycle calls, whose input is
+ * JSON from the stack, never a typed value.
+ */
+export declare function parseWorkflowResource(
+  input: unknown,
+): EditorialWorkflowsResource;
+
+/**
+ * Provision (create OR update) a workflow resource: run the engine's
+ * definition deploy for the resource's deployment. One function for both
+ * lifecycle phases because the deploy is content-addressed and create-only —
+ * identical content is a per-definition no-op (`unchanged`), any change mints
+ * the next immutable version, and prior versions (with the instances pinned
+ * to them) are never touched. Re-running after a partial failure converges.
+ *
+ * A definition REMOVED from the deployment since the last provision is
+ * retained, not deleted — deployed definitions only ever leave the lake
+ * through the engine's explicit `deleteDefinition` (the workflow CLI's
+ * `definition delete`), never through the blueprint lifecycle
+ * ({@link destroyWorkflowResource}).
+ */
+export declare function provisionWorkflowResource({
+  resource,
+  ...scope
+}: WorkflowResourceScope): Promise<DeployDefinitionsResult>;
+
+/**
+ * The blueprint resource type string for an Editorial Workflows definition
+ * deployment. A single constant so the manifest, the provider, and any future
+ * first-class `@sanity/blueprints` definer agree on one name.
+ */
+export declare const WORKFLOW_RESOURCE_TYPE = "sanity.workflow";
+
+/**
+ * One provider lifecycle call's scope: the resource document as it arrives
+ * from the blueprint service (parsed and validated at this boundary) and a
+ * client bound to the deployment's `workflowResource`.
+ */
+export declare interface WorkflowResourceScope {
+  resource: unknown;
+  client: WorkflowClient;
+  telemetry?: WorkflowTelemetryLogger;
+}
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import type { BlueprintResource } from "@sanity/blueprints";
+import { BlueprintResourceLifecycle } from "@sanity/blueprints";
+import { DeployDefinitionsResult } from "@sanity/workflow-engine";
+import { WorkflowClient } from "@sanity/workflow-engine";
+import { WorkflowDeployment } from "@sanity/workflow-engine";
+import { WorkflowTelemetryLogger } from "@sanity/workflow-engine";
+
+/**
+ * Declare an Editorial Workflows deployment as a Sanity Blueprints resource —
+ * the entry for a `sanity.blueprint.ts` `resources` array. Takes the same
+ * deployment shape as one `deployments[]` entry of a `sanity.workflow.ts`
+ * config, so an existing config entry drops in unchanged.
+ *
+ * Validates eagerly ({@link parseWorkflowDeployment}) so a bad definition or
+ * an unbound `@<handle>:` alias fails at manifest evaluation, before anything
+ * ships to the blueprint service.
+ *
+ * @remarks
+ * NOT deployable yet: the blueprints service has no registered
+ * `sanity.workflow` provider, and how it treats an unregistered resource type
+ * is unverified — adding this resource to a real blueprint may fail the whole
+ * stack operation. Until the provider is registered, deploy definitions with
+ * the workflow CLI (`sanity-workflows deploy`).
+ *
+ * ```ts
+ * // sanity.blueprint.ts
+ * import {defineBlueprint} from '@sanity/blueprints'
+ * import {defineWorkflows} from '@sanity/workflow-blueprint'
+ * import config from './sanity.workflow'
+ *
+ * export default defineBlueprint({
+ *   resources: [defineWorkflows(config.deployments[0])],
+ * })
+ * ```
+ */
+export declare function defineWorkflows(
+  deployment: WorkflowDeployment,
+  options?: DefineWorkflowsOptions,
+): EditorialWorkflowsResource;
+
+export declare interface DefineWorkflowsOptions {
+  /**
+   * Blueprint resource name — the identity blueprints matches deploys on.
+   * Defaults to `editorial-workflows-<tag>`. Renaming a deployed resource is
+   * a destroy + create, so with live instances keep the name stable.
+   */
+  name?: string;
+  /**
+   * Blueprint lifecycle policy. Defaults to `{deletionPolicy: 'retain'}`:
+   * removing the resource (or destroying its stack) detaches the deployed
+   * definitions instead of deleting them. Definitions are retain-only through
+   * blueprints — a `deletionPolicy` that promises deletion (`allow`,
+   * `replace`) is rejected here, because the provider's destroy always
+   * refuses ({@link destroyWorkflowResource}) and honouring the policy would
+   * only defer that failure to the stack operation. `protect` is accepted
+   * (stricter than retain).
+   */
+  lifecycle?: BlueprintResourceLifecycle;
+}
+
+/**
+ * Refuses, always: Editorial Workflows definitions are retain-only through
+ * blueprints. Deployed definitions — immutable, versioned, with instances
+ * pinned to them — outlive any stack, so an infrastructure teardown can never
+ * take editorial state with it. Deleting a definition is a deliberate,
+ * per-definition act through the engine's `deleteDefinition` (the workflow
+ * CLI's `definition delete`), never a side effect of a manifest edit.
+ *
+ * The definer enforces the same posture eagerly by rejecting a
+ * `deletionPolicy` that promises deletion.
+ */
+export declare function destroyWorkflowResource(): never;
+
+/**
+ * An Editorial Workflows deployment declared as a Sanity Blueprints resource.
+ * Pure data: the blueprint manifest serializes it verbatim into the stack
+ * mutation, and the provider ({@link provisionWorkflowResource}) reads it back
+ * to run the definition deploy. Blueprints matches resources by `name`, so
+ * renaming one is a destroy + create, never an update.
+ */
+export declare interface EditorialWorkflowsResource extends BlueprintResource {
+  type: typeof WORKFLOW_RESOURCE_TYPE;
+  /** The deployment to provision — the same shape as one `deployments[]`
+   *  entry of a `sanity.workflow.ts` config. Definitions are carried in
+   *  authored form; `@<handle>:` aliases expand at provision, not here. */
+  deployment: WorkflowDeployment;
+}
+
+/**
+ * Validate one deployment the way the definition deploy will, so every
+ * offline-checkable author error fails here — in the author's terminal at
+ * manifest evaluation — rather than as a failed stack operation: the
+ * deployment envelope (tag, resource binding, alias bindings) through the
+ * config schema, each definition boundary-parsed and validated, definition
+ * names checked for batch uniqueness, a dry alias expansion (fail-closed on
+ * an unbound `@<handle>:` reference), and the spawn-reference walk that
+ * rejects in-set cycles.
+ *
+ * Returns the parsed deployment (definition document envelopes stripped, so a
+ * fetched definition document round-trips cleanly).
+ */
+export declare function parseWorkflowDeployment(
+  input: unknown,
+  caller: string,
+): WorkflowDeployment;
+
+/**
+ * Parse an incoming blueprint resource document into a typed
+ * {@link EditorialWorkflowsResource}, validating the deployment exactly like
+ * the definer does. The boundary for provider lifecycle calls, whose input is
+ * JSON from the stack, never a typed value.
+ */
+export declare function parseWorkflowResource(
+  input: unknown,
+): EditorialWorkflowsResource;
+
+/**
+ * Provision (create OR update) a workflow resource: run the engine's
+ * definition deploy for the resource's deployment. One function for both
+ * lifecycle phases because the deploy is content-addressed and create-only —
+ * identical content is a per-definition no-op (`unchanged`), any change mints
+ * the next immutable version, and prior versions (with the instances pinned
+ * to them) are never touched. Re-running after a partial failure converges.
+ *
+ * A definition REMOVED from the deployment since the last provision is
+ * retained, not deleted — deployed definitions only ever leave the lake
+ * through the engine's explicit `deleteDefinition` (the workflow CLI's
+ * `definition delete`), never through the blueprint lifecycle
+ * ({@link destroyWorkflowResource}).
+ */
+export declare function provisionWorkflowResource({
+  resource,
+  ...scope
+}: WorkflowResourceScope): Promise<DeployDefinitionsResult>;
+
+/**
+ * The blueprint resource type string for an Editorial Workflows definition
+ * deployment. A single constant so the manifest, the provider, and any future
+ * first-class `@sanity/blueprints` definer agree on one name.
+ */
+export declare const WORKFLOW_RESOURCE_TYPE = "sanity.workflow";
+
+/**
+ * One provider lifecycle call's scope: the resource document as it arrives
+ * from the blueprint service (parsed and validated at this boundary) and a
+ * client bound to the deployment's `workflowResource`.
+ */
+export declare interface WorkflowResourceScope {
+  resource: unknown;
+  client: WorkflowClient;
+  telemetry?: WorkflowTelemetryLogger;
+}
+
+export {};

package/dist/index.js

@@ -0,0 +1,112 @@
+import { validateResource } from "@sanity/blueprints";
+
+import { assertReaderModelAcknowledgement, parseDefinitionInput, validateDefinition, resourceAliasesToMap, expandResourceAliases, errorMessage, refsOf, workflow } from "@sanity/workflow-engine";
+
+import { defineWorkflowConfig } from "@sanity/workflow-engine/define";
+
+const WORKFLOW_RESOURCE_TYPE = "sanity.workflow";
+
+function parseWorkflowDeployment(input, caller) {
+    const config = defineWorkflowConfig({
+        deployments: [ input ]
+    }), [deployment] = config.deployments;
+    if (deployment === void 0) throw new Error(`${caller}: expected a workflow deployment`);
+    assertReaderModelAcknowledgement(deployment.expectedMinReaderModel, caller);
+    const definitions = deployment.definitions.map(def => parseDefinitionInput(def, caller));
+    assertUniqueDefinitionNames(definitions, caller), definitions.forEach(validateDefinition);
+    const aliases = resourceAliasesToMap(deployment.resourceAliases);
+    for (const def of definitions) expandOrReattribute({
+        def: def,
+        aliases: aliases,
+        caller: caller
+    });
+    return assertAcyclicSpawnRefs(definitions, caller), {
+        ...deployment,
+        definitions: definitions
+    };
+}
+
+function assertUniqueDefinitionNames(definitions, caller) {
+    const seen = /* @__PURE__ */ new Set;
+    for (const def of definitions) {
+        if (seen.has(def.name)) throw new Error(`${caller}: duplicate definition name "${def.name}" in deployment`);
+        seen.add(def.name);
+    }
+}
+
+function expandOrReattribute({def: def, aliases: aliases, caller: caller}) {
+    try {
+        expandResourceAliases(def, aliases);
+    } catch (error) {
+        throw new Error(errorMessage(error).replace(/^workflow\.deployDefinitions: /, `${caller}: `), {
+            cause: error
+        });
+    }
+}
+
+function assertAcyclicSpawnRefs(definitions, caller) {
+    const remaining = new Map(definitions.map(def => [ def.name, def ]));
+    for (;remaining.size > 0; ) {
+        const referenced = new Set([ ...remaining.values() ].flatMap(def => refsOf(def).map(ref => ref.name)).filter(name => remaining.has(name))), free = [ ...remaining.values() ].filter(def => !referenced.has(def.name));
+        if (free.length === 0) throw new Error(`${caller}: reference cycle among definitions ${[ ...remaining.keys() ].join(", ")}`);
+        for (const def of free) remaining.delete(def.name);
+    }
+}
+
+function defineWorkflows(deployment, options) {
+    const parsed = parseWorkflowDeployment(deployment, "defineWorkflows");
+    if (options?.name === "") throw new Error("defineWorkflows: `name` must be a non-empty string");
+    const policy = options?.lifecycle?.deletionPolicy;
+    if (policy === "allow" || policy === "replace") throw new Error(`defineWorkflows: deletionPolicy '${policy}' is not supported — Editorial Workflows definitions are retain-only through blueprints; delete deliberately with the workflow CLI's \`definition delete\`.`);
+    const resource = {
+        name: options?.name ?? `editorial-workflows-${parsed.tag}`,
+        type: WORKFLOW_RESOURCE_TYPE,
+        lifecycle: options?.lifecycle ?? {
+            deletionPolicy: "retain"
+        },
+        deployment: parsed
+    }, errors = validateResource(resource);
+    if (errors.length > 0) throw new Error(`defineWorkflows: ${errors.map(error => error.message).join("; ")}`);
+    return resource;
+}
+
+function parseWorkflowResource(input) {
+    if (typeof input != "object" || input === null) throw new Error("workflow resource: expected an object");
+    const record = input;
+    if (record.type !== WORKFLOW_RESOURCE_TYPE) throw new Error(`workflow resource: expected type "${WORKFLOW_RESOURCE_TYPE}", got "${String(record.type)}"`);
+    if (typeof record.name != "string" || record.name === "") throw new Error("workflow resource: `name` must be a non-empty string");
+    const deployment = parseWorkflowDeployment(record.deployment, "workflow resource");
+    return {
+        ...record,
+        type: WORKFLOW_RESOURCE_TYPE,
+        name: record.name,
+        deployment: deployment
+    };
+}
+
+function engineScope({client: client, telemetry: telemetry}, deployment) {
+    return {
+        client: client,
+        tag: deployment.tag,
+        workflowResource: deployment.workflowResource,
+        ...telemetry === void 0 ? {} : {
+            telemetry: telemetry
+        }
+    };
+}
+
+async function provisionWorkflowResource({resource: resource, ...scope}) {
+    const {deployment: deployment} = parseWorkflowResource(resource);
+    return workflow.deployDefinitions({
+        ...engineScope(scope, deployment),
+        expectedMinReaderModel: deployment.expectedMinReaderModel,
+        resourceAliases: resourceAliasesToMap(deployment.resourceAliases),
+        definitions: deployment.definitions
+    });
+}
+
+function destroyWorkflowResource() {
+    throw new Error("workflow resource: destroy is not supported — Editorial Workflows definitions are retain-only through blueprints. Deployed definitions and their instances outlive the stack; delete deliberately with the workflow CLI's `definition delete`.");
+}
+
+export { WORKFLOW_RESOURCE_TYPE, defineWorkflows, destroyWorkflowResource, parseWorkflowDeployment, parseWorkflowResource, provisionWorkflowResource };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@sanity/workflow-blueprint",
+  "version": "0.0.0",
+  "description": "Sanity Blueprints integration for Editorial Workflows: the workflow resource definer and the provider core that provisions definition deploys. Early access — not deployable until the sanity.workflow provider is registered in the blueprints service.",
+  "keywords": [
+    "blueprints",
+    "sanity",
+    "sanity-io",
+    "workflow",
+    "workflows"
+  ],
+  "homepage": "https://github.com/sanity-io/workflows/tree/main/packages/workflow-blueprint#readme",
+  "bugs": {
+    "url": "https://github.com/sanity-io/workflows/issues"
+  },
+  "license": "MIT",
+  "author": "Sanity.io <hello@sanity.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sanity-io/workflows.git",
+    "directory": "packages/workflow-blueprint"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sanity/blueprints": "^0.21.0",
+    "@sanity/workflow-engine": "0.17.0"
+  },
+  "devDependencies": {
+    "@sanity/pkg-utils": "^10.5.2",
+    "@types/node": "^25.9.1",
+    "vitest": "^4.1.8",
+    "@sanity/workflow-engine-test": "0.12.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "pkg-utils build --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}