@jam-mcp/server 1.1.0 → 1.2.0

package/dist/domain/write.d.ts

@@ -13,8 +13,17 @@
  * change happen, and did we see it happen". Mixing them would let a confident
  * `complete: true` stand in for a verified mutation.
  */
+/**
+ * Operations that change an issue that already exists.
+ *
+ * Kept apart from creation because the two have different shapes at every
+ * layer: these name an issue, creation names a project; these compare a
+ * revision to detect a conflict, creation has no revision to compare.
+ */
+export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition"];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
-export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition"];
+export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "issue.create"];
+export type ExistingIssueOperation = (typeof EXISTING_ISSUE_OPERATIONS)[number];
 export type WriteOperation = (typeof WRITE_OPERATIONS)[number];
 /**
  * Fields `field.update` may touch.
@@ -39,7 +48,75 @@ export type FieldUpdateInput = {
 export type StatusTransitionInput = {
     status: string;
 };
-export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput;
+/**
+ * Fields `issue.create` may set.
+ *
+ * The same argument as WRITABLE_FIELDS, and the same answer: a closed list, so
+ * "what can an agent create" has an answer that does not depend on one
+ * project's screen configuration. `issueType` and `summary` are required by
+ * every Jira project JAM can serve; the rest are optional and only sent when
+ * asked for.
+ */
+export declare const CREATABLE_FIELDS: readonly ["issueType", "summary", "description", "priority", "labels", "components"];
+export type CreatableField = (typeof CREATABLE_FIELDS)[number];
+export type CreateIssueInput = {
+    issueType: string;
+    summary: string;
+    description?: string;
+    priority?: string;
+    labels?: string[];
+    components?: string[];
+};
+export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | CreateIssueInput;
+/** An issue type as Jira offers it for one project, right now. */
+export type CreateIssueType = {
+    id: string;
+    name: string;
+    subtask: boolean;
+};
+/**
+ * One field on a project's create screen, as Jira describes it.
+ *
+ * `allowedValues` is present only for fields Jira constrains (priority,
+ * components, and issue-type-scoped pickers). Absent means unconstrained, not
+ * empty - the difference decides whether a value can be resolved or must be
+ * refused.
+ */
+export type CreateFieldMetadata = {
+    /** Jira's field id, e.g. `summary` or `customfield_12345`. */
+    id: string;
+    name: string;
+    required: boolean;
+    hasDefaultValue: boolean;
+    allowedValues?: {
+        id?: string;
+        name?: string;
+    }[];
+};
+/**
+ * What a create plan depends on, recorded so apply can check it again.
+ *
+ * Not a hash of the metadata document: an unrelated optional field appearing
+ * on the create screen does not invalidate a plan, and treating it as though
+ * it did would make every plan fail on a busy project. What is recorded here
+ * is the set of premises the plan was built on, and apply re-derives whether
+ * each still holds.
+ */
+export type CreateSchemaRequirements = {
+    issueTypeId: string;
+    issueTypeName: string;
+    /** Required field ids JAM undertook to supply or knew Jira would default. */
+    requiredFieldIds: string[];
+    /**
+     * Values resolved from Jira's allowed lists at plan time, by field id. Apply
+     * refuses if any of them is no longer offered.
+     */
+    resolvedValues: {
+        fieldId: string;
+        requested: string;
+        resolved: string;
+    }[];
+};
 /** A transition as Jira currently offers it for one issue. */
 export type JiraTransition = {
     id: string;
@@ -47,33 +124,57 @@ export type JiraTransition = {
     /** The status this transition leads to, as Jira names it. */
     to: string;
 };
+/** Fields every plan carries, whatever it is a plan for. */
+type WritePlanCommon = {
+    planId: string;
+    projectKey: string;
+    /** Only the fields this operation touches. */
+    before: Record<string, unknown>;
+    intendedAfter: Record<string, unknown>;
+    createdAt: string;
+    expiresAt: string;
+    /** Normalized payload the apply step will send. Never supplied by a caller. */
+    mutation: WriteMutation;
+};
 /**
- * What a plan captured, and what it intends.
+ * A plan against an issue that already exists.
  *
  * `baseUpdated` is the issue's `updated` timestamp at plan time. Apply re-reads
  * the issue and refuses when it has moved: a plan that was valid is not the
  * same as a plan that is still valid.
  */
-export type WritePlan = {
-    planId: string;
+export type ExistingIssueWritePlan = WritePlanCommon & {
+    kind: "existing-issue";
     issueKey: string;
-    projectKey: string;
-    operation: WriteOperation;
-    /** Only the fields this operation touches. */
-    before: Record<string, unknown>;
-    intendedAfter: Record<string, unknown>;
+    operation: ExistingIssueOperation;
     baseUpdated: string;
-    createdAt: string;
-    expiresAt: string;
     /**
      * The transition Jira offered for this target status, resolved at plan time.
      * Present only for `status.transition` - a transition id is never guessed
      * from a status name.
      */
     transition?: JiraTransition;
-    /** Normalized payload the apply step will send. Never supplied by a caller. */
-    mutation: WriteMutation;
 };
+/**
+ * A plan to create an issue that does not exist yet.
+ *
+ * There is no `issueKey` and no `baseUpdated`, and neither is filled with a
+ * placeholder: nothing to name, and no revision to compare. What takes their
+ * place is `schemaRequirements` - creation's concurrency boundary is the
+ * project's create schema, not one issue's revision, so that is what apply
+ * re-checks before it sends anything.
+ */
+export type CreateIssueWritePlan = WritePlanCommon & {
+    kind: "create-issue";
+    operation: "issue.create";
+    before: {
+        issue: null;
+    };
+    schemaRequirements: CreateSchemaRequirements;
+};
+export type WritePlan = ExistingIssueWritePlan | CreateIssueWritePlan;
+/** A plan as it is handed to the store, before an id has been minted. */
+export type NewWritePlan = Omit<ExistingIssueWritePlan, "planId"> | Omit<CreateIssueWritePlan, "planId">;
 /** What apply will actually send. Produced by planning, never by an agent. */
 export type WriteMutation = {
     kind: "comment";
@@ -84,16 +185,25 @@ export type WriteMutation = {
 } | {
     kind: "transition";
     transitionId: string;
+} | {
+    kind: "create";
+    fields: Record<string, unknown>;
 };
 /** What `jira_write_plan` returns. The mutation itself is not exposed. */
 export type WritePlanReceipt = {
     status: "planned";
     planId: string;
-    issue: string;
     operation: WriteOperation;
     before: Record<string, unknown>;
     intendedAfter: Record<string, unknown>;
     expiresAt: string;
+    /**
+     * The issue this plan changes. Absent for `issue.create`, which has no issue
+     * yet - a placeholder key here would be a claim JAM cannot make.
+     */
+    issue?: string;
+    /** The project a new issue would be created in. Present for `issue.create`. */
+    project?: string;
     /** How the result of applying this plan will be confirmed. */
     verification: {
         method: "direct-issue-read";
@@ -104,6 +214,7 @@ export type WritePlanReceipt = {
 /** What `jira_write_apply` returns once a direct read has confirmed the change. */
 export type WriteApplyReceipt = {
     status: "applied";
+    /** For `issue.create`, the key Jira minted - known only after applying. */
     issue: string;
     operation: WriteOperation;
     before: Record<string, unknown>;
@@ -114,4 +225,6 @@ export type WriteApplyReceipt = {
     commentId?: string;
 };
 export declare function isWriteOperation(value: string): value is WriteOperation;
+export declare function isExistingIssueOperation(value: string): value is ExistingIssueOperation;
 export declare function isWritableField(value: string): value is WritableField;
+export {};

package/dist/domain/write.js

@@ -13,8 +13,20 @@
  * change happen, and did we see it happen". Mixing them would let a confident
  * `complete: true` stand in for a verified mutation.
  */
+/**
+ * Operations that change an issue that already exists.
+ *
+ * Kept apart from creation because the two have different shapes at every
+ * layer: these name an issue, creation names a project; these compare a
+ * revision to detect a conflict, creation has no revision to compare.
+ */
+export const EXISTING_ISSUE_OPERATIONS = [
+    "comment.add",
+    "field.update",
+    "status.transition",
+];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
-export const WRITE_OPERATIONS = ["comment.add", "field.update", "status.transition"];
+export const WRITE_OPERATIONS = [...EXISTING_ISSUE_OPERATIONS, "issue.create"];
 /**
  * Fields `field.update` may touch.
  *
@@ -25,9 +37,29 @@ export const WRITE_OPERATIONS = ["comment.add", "field.update", "status.transiti
  * discovery, accountId lookup) that belongs in its own round.
  */
 export const WRITABLE_FIELDS = ["summary", "priority", "labels", "components"];
+/**
+ * Fields `issue.create` may set.
+ *
+ * The same argument as WRITABLE_FIELDS, and the same answer: a closed list, so
+ * "what can an agent create" has an answer that does not depend on one
+ * project's screen configuration. `issueType` and `summary` are required by
+ * every Jira project JAM can serve; the rest are optional and only sent when
+ * asked for.
+ */
+export const CREATABLE_FIELDS = [
+    "issueType",
+    "summary",
+    "description",
+    "priority",
+    "labels",
+    "components",
+];
 export function isWriteOperation(value) {
     return WRITE_OPERATIONS.includes(value);
 }
+export function isExistingIssueOperation(value) {
+    return EXISTING_ISSUE_OPERATIONS.includes(value);
+}
 export function isWritableField(value) {
     return WRITABLE_FIELDS.includes(value);
 }

package/dist/mcp/create-server.d.ts

@@ -5,6 +5,10 @@ export declare const TOOL_COUNT: number;
 /**
  * The external contract: three read tools and two write tools.
  *
+ * What JAM can write grows as operations inside `jira_write_plan`, never as
+ * tools. `issue.create` arrived that way: an agent that knew the write pair
+ * already knew how to reach it.
+ *
  * The read three have been stable since the first release and do not change.
  * The write pair is a single operation split in half on purpose - deciding and
  * doing are separate calls, so an agent cannot mutate Jira without first

package/dist/mcp/create-server.js

@@ -24,6 +24,10 @@ export const TOOL_COUNT = REGISTER_TOOLS.length;
 /**
  * The external contract: three read tools and two write tools.
  *
+ * What JAM can write grows as operations inside `jira_write_plan`, never as
+ * tools. `issue.create` arrived that way: an agent that knew the write pair
+ * already knew how to reach it.
+ *
  * The read three have been stable since the first release and do not change.
  * The write pair is a single operation split in half on purpose - deciding and
  * doing are separate calls, so an agent cannot mutate Jira without first
@@ -47,6 +51,7 @@ export function createServer(deps) {
             "jira_write_plan changes nothing - it reads the issue, checks the change is possible, and describes what would happen.",
             "jira_write_apply takes only a planId. There is no way to write without planning first, and no payload to override what the plan decided.",
             "Writes are confined to the configured Jira project, and confirmed by reading the issue back. A write JAM could not verify is never reported as done.",
+            "jira_write_plan also creates issues: operation \"issue.create\", no key, and no project - the new issue goes into the project this workspace is bound to. Planning reads Jira's create schema first, so an unavailable issue type, a disallowed priority or component, and a create screen requiring a field JAM cannot set are refused before anything is sent.",
             "On JAM_WRITE_CONFLICT or JAM_WRITE_PLAN_EXPIRED, plan again against the current state. On JAM_WRITE_UNCERTAIN, read the issue - never retry the apply, which could apply the change twice.",
         ].join("\n"),
     });

package/dist/mcp/tools/jira-write-plan.tool.js

@@ -1,16 +1,21 @@
 import { z } from "zod";
 import { planWrite } from "../../application/plan-write.js";
-import { WRITABLE_FIELDS, WRITE_OPERATIONS } from "../../domain/write.js";
+import { CREATABLE_FIELDS, WRITABLE_FIELDS, WRITE_OPERATIONS } from "../../domain/write.js";
 import { runTool } from "../tool-result.js";
 const DESCRIPTION = `Work out how to change one Jira issue, and get back a plan. Changes nothing.
 
 This is the first half of every write. Call it, read what it says the issue looks like now and what it would become, then pass the returned planId to jira_write_apply. There is no way to write to Jira without a plan, and a plan cannot be assembled by hand - only jira_write_plan issues one.
 
-Operations:
+Operations on an issue that already exists - these need \`key\`:
 - comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
 - field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
 - status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
 
+Creating an issue - no \`key\`, because there is no issue yet:
+- issue.create       input: { "issueType": "Task", "summary": "...", "description"?, "priority"?, "labels"?, "components"? }
+
+issue.create goes into the project this workspace is bound to; the project is not a parameter. Planning reads Jira's create schema for that project first, so an issue type Jira does not offer, a priority or component outside its allowed values, and a project whose create screen requires a field JAM cannot set are all refused here rather than attempted. \`description\` is plain text, like a comment. Not settable in this version: assignee, reporter, parent, custom fields, attachments.
+
 Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
 
 The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
@@ -21,18 +26,41 @@ export function registerJiraWritePlan(server, deps) {
         title: "Plan a change to a Jira issue (writes nothing)",
         description: DESCRIPTION,
         inputSchema: {
-            key: z.string().min(1).describe('Issue key, e.g. "PROJECT-123". Must be in the configured project.'),
+            // Optional at the schema level because issue.create has no issue to
+            // name. Every other operation requires it, and planning refuses one
+            // that arrives without it - so the schema says "sometimes", and the
+            // server says which times.
+            key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Issue key, e.g. "PROJECT-123". Required for comment.add, field.update and status.transition; omit for issue.create, which has no issue yet. Must be in the configured project.'),
             operation: z
                 .enum(WRITE_OPERATIONS)
                 .describe(`What to do: ${WRITE_OPERATIONS.join(", ")}.`),
+            // Loose, not stripping. A strict object would refuse an unknown field
+            // with a schema error, and the default stripping one would silently
+            // drop it - which is worse: an agent that asked to set an assignee
+            // would get an issue without one and a receipt that never mentions it.
+            // Letting unknown keys through means JAM refuses them itself, by name,
+            // with the supported list attached.
             input: z
-                .object({
+                .looseObject({
                 text: z.string().min(1).optional().describe("comment.add: the comment, as plain text."),
                 status: z
                     .string()
                     .min(1)
                     .optional()
                     .describe("status.transition: the status to move to, e.g. \"Done\"."),
+                issueType: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('issue.create: the issue type by name, e.g. "Task". Matched against the types Jira offers for this project.'),
+                description: z
+                    .string()
+                    .optional()
+                    .describe("issue.create: the description, as plain text. JAM converts it; do not send ADF."),
                 summary: z.string().min(1).optional(),
                 priority: z.string().min(1).optional().describe('Priority name, e.g. "High".'),
                 labels: z.array(z.string()).optional().describe("Replaces the whole label set."),
@@ -41,14 +69,14 @@ export function registerJiraWritePlan(server, deps) {
                     .optional()
                     .describe("Component names. Replaces the whole component set."),
             })
-                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")} - custom fields and assignee are not writable.`),
+                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")}; issue.create accepts only ${CREATABLE_FIELDS.join(", ")}. Custom fields and assignee are not writable by either.`),
         },
         // Planning reads Jira and decides; it never mutates. Hosts are free to
         // run it without asking, which is what keeps the two-step shape cheap.
         annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     }, async (args) => runTool("jira_write_plan", deps.telemetry, async () => {
         const { receipt } = await planWrite(deps, {
-            key: args.key,
+            ...(args.key !== undefined ? { key: args.key } : {}),
             operation: args.operation,
             input: args.input,
         });

package/dist/policy/consistency-policy.d.ts

@@ -1,12 +1,18 @@
 /**
  * Read-after-write rule.
  *
- * JAM is read-only in this release, so nothing enforces this at runtime yet.
- * The rule is fixed here so the write adapter, when it lands, cannot quietly
- * confirm a write with a stale JQL search result.
- *
  * Normal read      -> Enhanced JQL search (`jira_search`)
  * Post-write read  -> direct issue GET for the affected key
+ *
+ * "Direct issue GET" means `JiraReadPort.getIssue` - one key, one
+ * `GET /rest/api/3/issue/{key}`. Not a search, whose index can lag behind the
+ * issue it describes, and not `getIssues`: that is a bulk endpoint taking a
+ * list, and a bulk read is free to answer from a different path than the
+ * single-issue one. The difference is invisible in a listing and decisive in
+ * the read that says whether a mutation may proceed, or whether one landed.
+ *
+ * Every read the write plane makes goes through it: the pre-write conflict
+ * check, the post-write confirmation, and the post-create confirmation.
  */
 export type ReadMode = "search" | "direct";
 export declare function readModeAfterWrite(): ReadMode;

package/dist/policy/create-policy.d.ts

@@ -0,0 +1,86 @@
+import { type CreateFieldMetadata, type CreateIssueInput, type CreateIssueType, type CreateSchemaRequirements } from "../domain/write.js";
+/**
+ * What JAM will agree to create, decided from what Jira says it accepts.
+ *
+ * Creation is the one write with no issue to look at first, so every check
+ * here is against the project's create schema instead. The rule throughout is
+ * the one the rest of the write plane follows: resolve against what Jira just
+ * reported, never against what the caller asserted or what a name suggests. An
+ * issue type id is not derived from a type name, a priority is not sent
+ * because it looked plausible, and a required field JAM cannot express is
+ * refused here rather than posted and rejected as a 400.
+ */
+/**
+ * Jira field ids for the fields JAM can put on a create.
+ *
+ * The bridge between the public contract (CREATABLE_FIELDS, which an agent
+ * sees) and Jira's own ids (which the required-field gate compares against).
+ * Both directions matter: one decides what may be asked for, the other decides
+ * what counts as "JAM supplies this".
+ */
+export declare const CREATE_FIELD_IDS: {
+    readonly issueType: "issuetype";
+    readonly summary: "summary";
+    readonly description: "description";
+    readonly priority: "priority";
+    readonly labels: "labels";
+    readonly components: "components";
+};
+/**
+ * Match a requested issue type against the ones Jira offers for this project.
+ *
+ * Case-insensitive, because "task" and "Task" are the same intent and an agent
+ * has no way to learn Jira's casing before asking. Nothing else is inferred:
+ * the id comes from Jira's own list, and a type that is not on it is refused
+ * with the list attached, so the next move is to pick one rather than to
+ * rephrase the same one.
+ *
+ * Subtask types are refused separately. They need a parent, which is not in
+ * this version's contract, so "not available" would be the wrong answer - the
+ * type exists, and JAM cannot use it yet.
+ */
+export declare function resolveIssueType(requested: string, available: CreateIssueType[]): CreateIssueType;
+/**
+ * Refuse a create whose project requires something JAM cannot put on it.
+ *
+ * The alternative - post it and let Jira answer 400 - is worse twice over: the
+ * agent gets a vendor error instead of a JAM decision, and creation is the one
+ * write where "did it happen?" is expensive to answer after the fact. So the
+ * answer is worked out before anything is sent.
+ *
+ * A field Jira says it will default is not JAM's to supply. That is Jira
+ * stating a fact about its own configuration, not JAM guessing one.
+ *
+ * Returns the required field ids, which the plan records so apply can tell a
+ * newly-required field from one that was always there.
+ */
+export declare function assertRequiredFieldsSupported(fields: CreateFieldMetadata[], input: CreateIssueInput): string[];
+/**
+ * Turn a requested value into one Jira currently offers for that field.
+ *
+ * An unconstrained field passes the value through: there is no list to check
+ * it against, and inventing one would refuse valid input. Absent and empty are
+ * different - absent means Jira did not constrain the field, empty means it
+ * constrains it and offers nothing.
+ *
+ * The shape is resolveTransition's, deliberately: human intent, then
+ * Jira-provided candidates, then a concrete Jira value. Nothing in between
+ * guesses.
+ */
+export declare function resolveAllowedValue(field: CreateFieldMetadata | undefined, requested: string, label: string): {
+    requested: string;
+    resolved: string;
+};
+/**
+ * Are this plan's premises still true?
+ *
+ * Semantic, not a document comparison. Comparing a hash of the metadata would
+ * make an unrelated optional field appearing on the create screen invalidate
+ * every outstanding plan - which is wrong, and on an active project constant.
+ * What matters is narrower: the issue type still exists, no new required field
+ * has appeared that JAM cannot fill, and every value resolved from an allowed
+ * list is still on it.
+ *
+ * Everything else about the schema may change freely between plan and apply.
+ */
+export declare function assertSchemaUnchanged(requirements: CreateSchemaRequirements, issueTypes: CreateIssueType[], fields: CreateFieldMetadata[], input: CreateIssueInput): void;

package/dist/policy/create-policy.js

@@ -0,0 +1,182 @@
+import { JamError } from "../domain/errors.js";
+import { CREATABLE_FIELDS, } from "../domain/write.js";
+/**
+ * What JAM will agree to create, decided from what Jira says it accepts.
+ *
+ * Creation is the one write with no issue to look at first, so every check
+ * here is against the project's create schema instead. The rule throughout is
+ * the one the rest of the write plane follows: resolve against what Jira just
+ * reported, never against what the caller asserted or what a name suggests. An
+ * issue type id is not derived from a type name, a priority is not sent
+ * because it looked plausible, and a required field JAM cannot express is
+ * refused here rather than posted and rejected as a 400.
+ */
+/**
+ * Jira field ids for the fields JAM can put on a create.
+ *
+ * The bridge between the public contract (CREATABLE_FIELDS, which an agent
+ * sees) and Jira's own ids (which the required-field gate compares against).
+ * Both directions matter: one decides what may be asked for, the other decides
+ * what counts as "JAM supplies this".
+ */
+export const CREATE_FIELD_IDS = {
+    issueType: "issuetype",
+    summary: "summary",
+    description: "description",
+    priority: "priority",
+    labels: "labels",
+    components: "components",
+};
+/** Always sent by JAM, so a project requiring them is still servable. */
+const ALWAYS_SUPPLIED = [CREATE_FIELD_IDS.issueType, CREATE_FIELD_IDS.summary, "project"];
+/**
+ * Fields JAM can supply when asked, and so can satisfy a required flag - but
+ * only if the caller actually asked for them. Required-and-absent is refused.
+ */
+const SUPPLIABLE_ON_REQUEST = {
+    [CREATE_FIELD_IDS.description]: "description",
+    [CREATE_FIELD_IDS.priority]: "priority",
+    [CREATE_FIELD_IDS.labels]: "labels",
+    [CREATE_FIELD_IDS.components]: "components",
+};
+/**
+ * Match a requested issue type against the ones Jira offers for this project.
+ *
+ * Case-insensitive, because "task" and "Task" are the same intent and an agent
+ * has no way to learn Jira's casing before asking. Nothing else is inferred:
+ * the id comes from Jira's own list, and a type that is not on it is refused
+ * with the list attached, so the next move is to pick one rather than to
+ * rephrase the same one.
+ *
+ * Subtask types are refused separately. They need a parent, which is not in
+ * this version's contract, so "not available" would be the wrong answer - the
+ * type exists, and JAM cannot use it yet.
+ */
+export function resolveIssueType(requested, available) {
+    const wanted = requested.trim().toLowerCase();
+    const match = available.find((t) => t.name.toLowerCase() === wanted);
+    if (!match) {
+        const creatable = available.filter((t) => !t.subtask).map((t) => t.name);
+        throw new JamError("JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", creatable.length === 0
+            ? `Jira offers no issue types this account can create in this project, so "${requested}" cannot be created.`
+            : `"${requested}" is not an issue type this account can create in this project. Available: ${creatable.join(", ")}.`, {
+            requested,
+            available: available.map((t) => ({ id: t.id, name: t.name, subtask: t.subtask })),
+        });
+    }
+    if (match.subtask) {
+        throw new JamError("JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", `"${match.name}" is a subtask type, which needs a parent issue. JAM does not set a parent, so it cannot create one.`, { requested, issueType: match.name, reason: "SUBTASK_UNSUPPORTED" });
+    }
+    return match;
+}
+/**
+ * Refuse a create whose project requires something JAM cannot put on it.
+ *
+ * The alternative - post it and let Jira answer 400 - is worse twice over: the
+ * agent gets a vendor error instead of a JAM decision, and creation is the one
+ * write where "did it happen?" is expensive to answer after the fact. So the
+ * answer is worked out before anything is sent.
+ *
+ * A field Jira says it will default is not JAM's to supply. That is Jira
+ * stating a fact about its own configuration, not JAM guessing one.
+ *
+ * Returns the required field ids, which the plan records so apply can tell a
+ * newly-required field from one that was always there.
+ */
+export function assertRequiredFieldsSupported(fields, input) {
+    const required = fields.filter((f) => f.required);
+    const unsupported = [];
+    for (const field of required) {
+        if (ALWAYS_SUPPLIED.includes(field.id))
+            continue;
+        if (field.hasDefaultValue)
+            continue;
+        const inputKey = SUPPLIABLE_ON_REQUEST[field.id];
+        if (!inputKey) {
+            unsupported.push({ id: field.id, name: field.name, reason: "NOT_IN_JAM_CREATE_CONTRACT" });
+            continue;
+        }
+        if (input[inputKey] === undefined) {
+            unsupported.push({ id: field.id, name: field.name, reason: "REQUIRED_BUT_NOT_PROVIDED" });
+        }
+    }
+    if (unsupported.length > 0) {
+        const named = unsupported.map((f) => `${f.name} (${f.id})`).join(", ");
+        const it = unsupported.length === 1 ? "it" : "them";
+        throw new JamError("JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", `This project requires ${named} when creating this issue type, and JAM cannot supply ${it}. Create this issue in Jira instead - JAM will not send a create it already knows Jira will reject.`, { unsupported, supported: [...CREATABLE_FIELDS] });
+    }
+    return required.map((f) => f.id);
+}
+/**
+ * Turn a requested value into one Jira currently offers for that field.
+ *
+ * An unconstrained field passes the value through: there is no list to check
+ * it against, and inventing one would refuse valid input. Absent and empty are
+ * different - absent means Jira did not constrain the field, empty means it
+ * constrains it and offers nothing.
+ *
+ * The shape is resolveTransition's, deliberately: human intent, then
+ * Jira-provided candidates, then a concrete Jira value. Nothing in between
+ * guesses.
+ */
+export function resolveAllowedValue(field, requested, label) {
+    if (!field?.allowedValues)
+        return { requested, resolved: requested };
+    const wanted = requested.trim().toLowerCase();
+    const match = field.allowedValues.find((v) => v.name?.toLowerCase() === wanted);
+    if (!match?.name) {
+        const allowed = field.allowedValues.map((v) => v.name).filter(Boolean);
+        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", allowed.length === 0
+            ? `Jira offers no ${label} values for this project and issue type, so "${requested}" cannot be set.`
+            : `"${requested}" is not an allowed ${label} for this project and issue type. Allowed: ${allowed.join(", ")}.`, { field: field.id, requested, allowed });
+    }
+    return { requested, resolved: match.name };
+}
+/**
+ * Are this plan's premises still true?
+ *
+ * Semantic, not a document comparison. Comparing a hash of the metadata would
+ * make an unrelated optional field appearing on the create screen invalidate
+ * every outstanding plan - which is wrong, and on an active project constant.
+ * What matters is narrower: the issue type still exists, no new required field
+ * has appeared that JAM cannot fill, and every value resolved from an allowed
+ * list is still on it.
+ *
+ * Everything else about the schema may change freely between plan and apply.
+ */
+export function assertSchemaUnchanged(requirements, issueTypes, fields, input) {
+    const stillOffered = issueTypes.find((t) => t.id === requirements.issueTypeId);
+    if (!stillOffered) {
+        throw schemaChanged(`Issue type ${requirements.issueTypeName} is no longer available to this account in this project.`, { issueTypeId: requirements.issueTypeId, issueType: requirements.issueTypeName });
+    }
+    // A required field JAM cannot fill is a refusal whether it was there at plan
+    // time or arrived since - but arriving since is a changed schema rather than
+    // a bad request, so it is reported as one.
+    try {
+        assertRequiredFieldsSupported(fields, input);
+    }
+    catch (err) {
+        if (err instanceof JamError && err.code === "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED") {
+            throw schemaChanged("The create screen for this issue type now requires a field JAM cannot supply.", { cause: err.details });
+        }
+        throw err;
+    }
+    const byId = new Map(fields.map((f) => [f.id, f]));
+    for (const resolved of requirements.resolvedValues) {
+        const allowed = byId.get(resolved.fieldId)?.allowedValues;
+        // A field that stopped being constrained is not a problem: the value JAM
+        // resolved is still a value, and Jira is no longer restricting it.
+        if (!allowed)
+            continue;
+        if (!allowed.some((v) => v.name === resolved.resolved)) {
+            throw schemaChanged(`"${resolved.resolved}" is no longer an allowed value for ${resolved.fieldId} in this project.`, {
+                field: resolved.fieldId,
+                planned: resolved.resolved,
+                allowed: allowed.map((v) => v.name).filter(Boolean),
+            });
+        }
+    }
+}
+function schemaChanged(what, details) {
+    return new JamError("JAM_WRITE_SCHEMA_CHANGED", `${what} This plan was built on the create schema as it was, so it no longer describes a create JAM can make. Nothing was created - plan again against the current schema.`, details);
+}