@jam-mcp/server 1.0.1 → 1.2.0

package/dist/domain/errors.js

@@ -17,6 +17,28 @@ export const JAM_ERROR_CODES = [
     "JIRA_UNAVAILABLE",
     "JAM_SETUP_REQUIRED",
     "JAM_BINDINGS_UNREADABLE",
+    // Write plane. Each names a distinct decision an agent has to make, which is
+    // why none of them collapse into CONFIG_INVALID: "you may not write there",
+    // "someone else moved it", and "we could not confirm it happened" call for
+    // three different next steps.
+    "JAM_WRITE_SCOPE_VIOLATION",
+    "JAM_WRITE_OPERATION_NOT_ALLOWED",
+    "JAM_WRITE_FIELD_NOT_ALLOWED",
+    "JAM_WRITE_TRANSITION_NOT_AVAILABLE",
+    // Creation. Each is a refusal JAM makes before Jira is asked to act, or a
+    // premise that stopped holding between planning and applying - never a raw
+    // Jira 400 passed along. "That type is not on offer", "this project needs a
+    // field JAM cannot fill" and "the schema moved under the plan" are three
+    // different next steps for whoever is holding the agent.
+    "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE",
+    "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED",
+    "JAM_WRITE_VALUE_NOT_ALLOWED",
+    "JAM_WRITE_SCHEMA_CHANGED",
+    "JAM_WRITE_PLAN_NOT_FOUND",
+    "JAM_WRITE_PLAN_EXPIRED",
+    "JAM_WRITE_CONFLICT",
+    "JAM_WRITE_VERIFICATION_FAILED",
+    "JAM_WRITE_UNCERTAIN",
 ];
 export class JamError extends Error {
     code;

package/dist/domain/write.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The write contract.
+ *
+ * JAM's write plane is not a Jira REST proxy. An agent cannot hand JAM a
+ * mutation and have it forwarded; it describes an intent, JAM works out whether
+ * that intent is currently possible, and only a plan JAM itself produced can be
+ * applied. Everything in this file exists to keep that shape: a closed set of
+ * operations, a fixed field whitelist, and a plan that records what the issue
+ * looked like when the plan was made.
+ *
+ * Read semantics are deliberately not reused here. A read result's `meta`
+ * answers "how complete was this retrieval"; a write result answers "did this
+ * 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", "issue.create"];
+export type ExistingIssueOperation = (typeof EXISTING_ISSUE_OPERATIONS)[number];
+export type WriteOperation = (typeof WRITE_OPERATIONS)[number];
+/**
+ * Fields `field.update` may touch.
+ *
+ * A whitelist rather than an open field map: an open map turns every
+ * project-specific screen, custom field and permission quirk into a runtime
+ * surprise, and makes "what can an agent change" unanswerable. Custom fields
+ * and assignee are deliberately absent - both need resolution work (schema
+ * discovery, accountId lookup) that belongs in its own round.
+ */
+export declare const WRITABLE_FIELDS: readonly ["summary", "priority", "labels", "components"];
+export type WritableField = (typeof WRITABLE_FIELDS)[number];
+export type CommentAddInput = {
+    text: string;
+};
+export type FieldUpdateInput = {
+    summary?: string;
+    priority?: string;
+    labels?: string[];
+    components?: string[];
+};
+export type StatusTransitionInput = {
+    status: string;
+};
+/**
+ * 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;
+    name: string;
+    /** 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;
+};
+/**
+ * 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 ExistingIssueWritePlan = WritePlanCommon & {
+    kind: "existing-issue";
+    issueKey: string;
+    operation: ExistingIssueOperation;
+    baseUpdated: 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;
+};
+/**
+ * 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";
+    text: string;
+} | {
+    kind: "fields";
+    fields: Record<string, unknown>;
+} | {
+    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;
+    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";
+        /** What a direct read must show before JAM calls the write applied. */
+        expects: Record<string, unknown>;
+    };
+};
+/** 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>;
+    after: Record<string, unknown>;
+    /** Always true in an `applied` receipt - an unverified write is an error. */
+    verified: true;
+    /** Present for `comment.add`: the comment Jira created. */
+    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

@@ -0,0 +1,65 @@
+/**
+ * The write contract.
+ *
+ * JAM's write plane is not a Jira REST proxy. An agent cannot hand JAM a
+ * mutation and have it forwarded; it describes an intent, JAM works out whether
+ * that intent is currently possible, and only a plan JAM itself produced can be
+ * applied. Everything in this file exists to keep that shape: a closed set of
+ * operations, a fixed field whitelist, and a plan that records what the issue
+ * looked like when the plan was made.
+ *
+ * Read semantics are deliberately not reused here. A read result's `meta`
+ * answers "how complete was this retrieval"; a write result answers "did this
+ * 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 = [...EXISTING_ISSUE_OPERATIONS, "issue.create"];
+/**
+ * Fields `field.update` may touch.
+ *
+ * A whitelist rather than an open field map: an open map turns every
+ * project-specific screen, custom field and permission quirk into a runtime
+ * surprise, and makes "what can an agent change" unanswerable. Custom fields
+ * and assignee are deliberately absent - both need resolution work (schema
+ * 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

@@ -1,9 +1,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { JamDeps } from "../deps.js";
 export declare const SERVER_NAME = "jam";
+export declare const TOOL_COUNT: number;
 /**
- * The external contract: exactly three read tools, stable from the first
- * release. Internal changes (cache, Rovo, remote transport) must not add or
- * rename anything here.
+ * 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
+ * having been shown what it is about to change. Internal changes (cache, Rovo,
+ * remote transport) must not add or rename anything here.
  */
 export declare function createServer(deps: JamDeps): McpServer;

package/dist/mcp/create-server.js

@@ -3,13 +3,36 @@ import { createRequire } from "node:module";
 import { registerJiraContext } from "./tools/jira-context.tool.js";
 import { registerJiraFull } from "./tools/jira-full.tool.js";
 import { registerJiraSearch } from "./tools/jira-search.tool.js";
+import { registerJiraWriteApply } from "./tools/jira-write-apply.tool.js";
+import { registerJiraWritePlan } from "./tools/jira-write-plan.tool.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../../package.json");
 export const SERVER_NAME = "jam";
 /**
- * The external contract: exactly three read tools, stable from the first
- * release. Internal changes (cache, Rovo, remote transport) must not add or
- * rename anything here.
+ * Every tool registration, in one list. `TOOL_COUNT` is derived from it, so a
+ * tool added here is counted everywhere it is reported - doctor included -
+ * without anyone having to remember a second place to edit.
+ */
+const REGISTER_TOOLS = [
+    registerJiraSearch,
+    registerJiraContext,
+    registerJiraFull,
+    registerJiraWritePlan,
+    registerJiraWriteApply,
+];
+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
+ * having been shown what it is about to change. Internal changes (cache, Rovo,
+ * remote transport) must not add or rename anything here.
  */
 export function createServer(deps) {
     const server = new McpServer({ name: SERVER_NAME, version: pkg.version ?? "0.0.0" }, {
@@ -23,10 +46,16 @@ export function createServer(deps) {
             "Every result carries a `meta` block; if meta.complete is false the answer is partial and must be reported as such.",
             "meta.complete describes JAM's retrieval, not the project: it means the Jira read finished with no known loss, never that Jira holds the whole story.",
             "meta.evidenceScope and meta.limitations name what was not evaluated - the repository and every external source among them. Judge Jira evidence from these results; judge execution reality elsewhere.",
+            "",
+            "Writing Jira is two steps: jira_write_plan, then jira_write_apply with the planId it returned.",
+            "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"),
     });
-    registerJiraSearch(server, deps);
-    registerJiraContext(server, deps);
-    registerJiraFull(server, deps);
+    for (const register of REGISTER_TOOLS)
+        register(server, deps);
     return server;
 }

package/dist/mcp/tools/jira-write-apply.tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { JamDeps } from "../../deps.js";
+export declare function registerJiraWriteApply(server: McpServer, deps: JamDeps): void;

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

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { applyWritePlan } from "../../application/apply-write.js";
+import { runTool } from "../tool-result.js";
+const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
+
+Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
+
+Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
+
+After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
+
+Failures worth handling differently:
+- JAM_WRITE_CONFLICT             the issue moved; re-plan
+- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
+- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
+- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
+
+Never report an uncertain or unverified write as done.`;
+export function registerJiraWriteApply(server, deps) {
+    server.registerTool("jira_write_apply", {
+        title: "Apply a planned change to a Jira issue (writes)",
+        description: DESCRIPTION,
+        inputSchema: {
+            planId: z
+                .string()
+                .min(1)
+                .describe("The planId returned by jira_write_plan. Single use."),
+        },
+        // Mutating, but not destructive in the sense hosts warn about: every
+        // supported operation adds or changes a field, and none delete anything.
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => runTool("jira_write_apply", deps.telemetry, () => applyWritePlan(deps, { planId: args.planId })));
+}

package/dist/mcp/tools/jira-write-plan.tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { JamDeps } from "../../deps.js";
+export declare function registerJiraWritePlan(server: McpServer, deps: JamDeps): void;

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

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { planWrite } from "../../application/plan-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 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.
+
+A plan is a statement about what is possible right now, not a promise that it will happen. Nothing is written until jira_write_apply runs.`;
+export function registerJiraWritePlan(server, deps) {
+    server.registerTool("jira_write_plan", {
+        title: "Plan a change to a Jira issue (writes nothing)",
+        description: DESCRIPTION,
+        inputSchema: {
+            // 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
+                .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."),
+                components: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Component names. Replaces the whole component set."),
+            })
+                .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, {
+            ...(args.key !== undefined ? { key: args.key } : {}),
+            operation: args.operation,
+            input: args.input,
+        });
+        return receipt;
+    }));
+}

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;