@jam-mcp/server 1.1.0 → 1.3.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", "assignee.update"];
 /** 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", "assignee.update", "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,101 @@ export type FieldUpdateInput = {
 export type StatusTransitionInput = {
     status: string;
 };
-export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput;
+/**
+ * Who to assign an issue to, as a person would say it.
+ *
+ * A display name, or an accountId if the caller already has one. Either way it
+ * is a selector, not an identifier: nothing here is ever sent to Jira. It is
+ * resolved against Jira's own user directory first, and what gets written is
+ * the accountId that resolution produced.
+ */
+export type AssigneeUpdateInput = {
+    assignee: string;
+};
+/**
+ * A Jira user as JAM identifies them.
+ *
+ * `accountId` is the identity; `displayName` is for the human reading the
+ * receipt. They are not interchangeable - two people can share a display name,
+ * which is precisely why an assignment is verified on the accountId.
+ */
+export type AssigneeRef = {
+    accountId: string;
+    displayName: string;
+};
+/** A user Jira offered in answer to a search. */
+export type AssigneeCandidate = AssigneeRef & {
+    active: boolean;
+};
+/**
+ * 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 | AssigneeUpdateInput | 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 +150,65 @@ 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;
+    /**
+     * Who the issue was assigned to when the plan was made, by identity.
+     *
+     * Present only for `assignee.update`, and separate from `before` because
+     * `before` is what a receipt shows a human while this is what apply compares.
+     * `undefined` means the issue was unassigned.
+     */
+    baseAssigneeAccountId?: string;
+};
+/**
+ * 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 +219,28 @@ export type WriteMutation = {
 } | {
     kind: "transition";
     transitionId: string;
+} | {
+    kind: "assignee";
+    accountId: 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 +251,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 +262,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,21 @@
  * 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",
+    "assignee.update",
+];
 /** 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 +38,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,15 +1,23 @@
 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
+- assignee.update    input: { "assignee": "..." }     a display name or an accountId; JAM resolves it against Jira's own directory
+
+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.
+
+assignee.update never sends the name you pass. JAM searches Jira's user directory, and assigns only when exactly one user matches your string exactly - an exact display name (case-insensitive) or an accountId. A partial match is Jira reporting a similarity, not identifying a person, so several matches or none come back as a refusal with the candidates attached: name one exactly, or pass their accountId. JAM also checks Jira offers that person as an assignee for this issue, before planning and again before writing, and confirms the result by accountId rather than by name. Unassigning, and setting an assignee while creating, are not in this version.
 
 Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
 
@@ -21,18 +29,46 @@ 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 every operation that changes an existing issue; 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\"."),
+                assignee: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("assignee.update: who to assign, as an exact display name or an accountId. Not settable through field.update."),
+                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 +77,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 are not writable by either, and the assignee is changed through assignee.update rather than through field.update.`),
         },
         // 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/assignee-policy.d.ts

@@ -0,0 +1,60 @@
+import type { AssigneeCandidate, AssigneeRef } from "../domain/write.js";
+/**
+ * Turning a name into a person, without ever guessing which person.
+ *
+ * Jira's user search is a substring search: "min" finds Min Kim and Minho
+ * Park, and it returns them in whatever order it likes. An agent handing JAM a
+ * name is describing an intent, not identifying an account - so the search is
+ * how candidates are found, and never how one of them is chosen.
+ *
+ * The rule is that JAM assigns only when the answer is unambiguous on its own
+ * terms: one exact identity. Everything else comes back as a refusal carrying
+ * the candidates, so the next move is to name one of them precisely rather
+ * than to hope the same query resolves differently.
+ *
+ * This costs an agent a round trip on ambiguity. The alternative costs someone
+ * an issue assigned to the wrong colleague, discovered later.
+ */
+/**
+ * Which candidate the caller meant, if exactly one is certain.
+ *
+ * In order:
+ *
+ *  1. An exact accountId. The caller already had an identity; nothing to guess.
+ *  2. Exactly one candidate whose display name matches exactly, ignoring case
+ *     and surrounding space. "task" and "Task" are the same intent, and an
+ *     agent cannot learn a directory's casing before asking.
+ *
+ * Nothing else resolves. A single substring hit is still a substring hit: it
+ * is Jira saying "this contains what you typed", not "this is who you meant".
+ */
+export declare function resolveAssignee(requested: string, candidates: AssigneeCandidate[]): AssigneeRef;
+/**
+ * Refuse an assignment Jira would not permit, before asking it to.
+ *
+ * Assignability is a permission question with a per-project answer, and JAM
+ * does not model Jira's permission scheme - it asks. Called at plan time so a
+ * refusal is a JAM decision rather than a 400, and again immediately before
+ * the write, because a permission that held when the plan was made is not the
+ * same as one that still holds.
+ */
+export declare function assertAssignable(issueKey: string, target: AssigneeRef, assignable: boolean): void;
+/**
+ * Refuse an assignment that would change nothing.
+ *
+ * Not an error in Jira's eyes, and not harmful - but a write JAM reports as
+ * applied should be a write that happened. Saying so plainly is more useful
+ * than a receipt claiming to have changed something that already was.
+ */
+export declare function assertNotAlreadyAssigned(issueKey: string, current: string | undefined, target: AssigneeRef): void;
+/**
+ * The candidates this string identifies exactly, if any.
+ *
+ * Exported so the caller can tell "the search settled it" from "the search did
+ * not" without reimplementing the rule - a second copy of what counts as exact
+ * is a second answer waiting to disagree with this one.
+ *
+ * An accountId match wins outright: it is an identity, and a display name that
+ * happens to equal somebody's account id is not a reason to consider them.
+ */
+export declare function exactMatches(requested: string, candidates: AssigneeCandidate[]): AssigneeCandidate[];

package/dist/policy/assignee-policy.js

@@ -0,0 +1,103 @@
+import { JamError } from "../domain/errors.js";
+/**
+ * Turning a name into a person, without ever guessing which person.
+ *
+ * Jira's user search is a substring search: "min" finds Min Kim and Minho
+ * Park, and it returns them in whatever order it likes. An agent handing JAM a
+ * name is describing an intent, not identifying an account - so the search is
+ * how candidates are found, and never how one of them is chosen.
+ *
+ * The rule is that JAM assigns only when the answer is unambiguous on its own
+ * terms: one exact identity. Everything else comes back as a refusal carrying
+ * the candidates, so the next move is to name one of them precisely rather
+ * than to hope the same query resolves differently.
+ *
+ * This costs an agent a round trip on ambiguity. The alternative costs someone
+ * an issue assigned to the wrong colleague, discovered later.
+ */
+/**
+ * Which candidate the caller meant, if exactly one is certain.
+ *
+ * In order:
+ *
+ *  1. An exact accountId. The caller already had an identity; nothing to guess.
+ *  2. Exactly one candidate whose display name matches exactly, ignoring case
+ *     and surrounding space. "task" and "Task" are the same intent, and an
+ *     agent cannot learn a directory's casing before asking.
+ *
+ * Nothing else resolves. A single substring hit is still a substring hit: it
+ * is Jira saying "this contains what you typed", not "this is who you meant".
+ */
+export function resolveAssignee(requested, candidates) {
+    const wanted = requested.trim();
+    if (wanted.length === 0) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "assignee.update needs a non-empty `input.assignee`.", { operation: "assignee.update" });
+    }
+    const exact = exactMatches(wanted, candidates);
+    if (exact.length === 0) {
+        throw new JamError("JAM_WRITE_ASSIGNEE_NOT_FOUND", candidates.length === 0
+            ? `Jira has no user matching "${requested}".`
+            : `No Jira user is exactly "${requested}". JAM assigns only on an exact display name or an accountId, because a partial match is Jira reporting a similarity rather than identifying a person. Name one of the candidates exactly, or pass their accountId.`, { requested, candidates: describe(candidates) });
+    }
+    if (exact.length > 1) {
+        // Two people really can share a display name. Picking either would be a
+        // coin toss whose result is somebody's issue.
+        throw new JamError("JAM_WRITE_ASSIGNEE_AMBIGUOUS", `"${requested}" matches ${exact.length} Jira users exactly. Pass the accountId of the one you mean.`, { requested, candidates: describe(exact) });
+    }
+    const match = exact[0];
+    if (!match.active) {
+        throw new JamError("JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", `${match.displayName} is a deactivated Jira account, so this issue cannot be assigned to them.`, { requested, accountId: match.accountId, reason: "INACTIVE" });
+    }
+    return { accountId: match.accountId, displayName: match.displayName };
+}
+/**
+ * Refuse an assignment Jira would not permit, before asking it to.
+ *
+ * Assignability is a permission question with a per-project answer, and JAM
+ * does not model Jira's permission scheme - it asks. Called at plan time so a
+ * refusal is a JAM decision rather than a 400, and again immediately before
+ * the write, because a permission that held when the plan was made is not the
+ * same as one that still holds.
+ */
+export function assertAssignable(issueKey, target, assignable) {
+    if (assignable)
+        return;
+    throw new JamError("JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", `Jira does not offer ${target.displayName} as an assignee for ${issueKey}. They may lack the assignable-user permission in this project, or have lost it since this plan was made.`, { issueKey, accountId: target.accountId, displayName: target.displayName });
+}
+/**
+ * Refuse an assignment that would change nothing.
+ *
+ * Not an error in Jira's eyes, and not harmful - but a write JAM reports as
+ * applied should be a write that happened. Saying so plainly is more useful
+ * than a receipt claiming to have changed something that already was.
+ */
+export function assertNotAlreadyAssigned(issueKey, current, target) {
+    if (current !== target.accountId)
+        return;
+    throw new JamError("JAM_WRITE_ASSIGNEE_ALREADY_SET", `${issueKey} is already assigned to ${target.displayName}. Nothing to change.`, { issueKey, accountId: target.accountId, displayName: target.displayName });
+}
+/**
+ * The candidates this string identifies exactly, if any.
+ *
+ * Exported so the caller can tell "the search settled it" from "the search did
+ * not" without reimplementing the rule - a second copy of what counts as exact
+ * is a second answer waiting to disagree with this one.
+ *
+ * An accountId match wins outright: it is an identity, and a display name that
+ * happens to equal somebody's account id is not a reason to consider them.
+ */
+export function exactMatches(requested, candidates) {
+    const wanted = requested.trim();
+    const byAccountId = candidates.filter((c) => c.accountId === wanted);
+    if (byAccountId.length > 0)
+        return byAccountId;
+    return candidates.filter((c) => c.displayName.trim().toLowerCase() === wanted.toLowerCase());
+}
+/** Candidates as an agent can act on them: a name to repeat, and an id to be sure. */
+function describe(candidates) {
+    return candidates.map((c) => ({
+        accountId: c.accountId,
+        displayName: c.displayName,
+        active: c.active,
+    }));
+}

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;