@tickernelz/paperclip-pro-shared 2026.925.0

package/dist/issue-write-denial.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Copy contract for denied issue writes (open cross-task writes: failure UX).
+ *
+ * Cross-issue issue writes are default-open for standard-trust agents on issues
+ * they can already read (see SPEC-implementation §9.3). The remaining walls are
+ * rare — but a real incident burned a full detour discovering a workaround
+ * behind an opaque 403, so every one of them must say three things:
+ *
+ *   1. which boundary fired,
+ *   2. who *can* act,
+ *   3. the sanctioned path forward.
+ *
+ * This module is the single source of truth for that copy, so the API error
+ * body an agent reads and the notice a human sees in the UI are the same words.
+ * It is the issue-write sibling of `responsible-user-denial.ts`: the two
+ * responsible-user ceiling codes delegate to that module's copy so terminology
+ * ("on behalf of {user}", never "impersonate") stays consistent.
+ */
+import { type ResponsibleUserDenialCode } from "./responsible-user-denial.js";
+export declare const ISSUE_WRITE_DENIAL_CODES: readonly ["issue_write_not_visible", "issue_write_actor_class_excluded", "issue_write_responsible_user_ceiling", "issue_write_responsible_user_unavailable", "issue_write_assignee_run_lock", "cross_issue_influence_cap_exceeded", "cross_issue_influence_run_context_required", "issue_write_attribution_spoof_rejected"];
+export type IssueWriteDenialCode = (typeof ISSUE_WRITE_DENIAL_CODES)[number];
+/**
+ * Why the write stopped, which drives icon + colour. `boundary` is an
+ * authorization wall, `lock` is run-lifecycle machinery that will clear on its
+ * own, `cap` is a rate backstop, and `attribution` is a rejected spoof.
+ */
+export type IssueWriteDenialTone = "boundary" | "lock" | "cap" | "attribution";
+export interface IssueWriteDenialCopy {
+    code: IssueWriteDenialCode;
+    /** HTTP status the server pairs with this code. */
+    status: 403 | 409 | 422 | 429;
+    tone: IssueWriteDenialTone;
+    /** The boundary that fired, as a short noun phrase for a banner title. */
+    boundary: string;
+    /** Short heading. */
+    title: string;
+    /** What happened and why, in one or two sentences. */
+    description: string;
+    /** Who is able to perform this write instead. */
+    whoCanAct: string;
+    /** The supported way to get the work moving. */
+    sanctionedPath: string;
+}
+export interface IssueWriteDenialContext {
+    /** Display name of the agent or user that attempted the write. */
+    actorLabel?: string | null;
+    /** Display name of the responsible ("on behalf of") user for the attempt. */
+    responsibleUserName?: string | null;
+    /** Display name of the target issue's current assignee. */
+    assigneeLabel?: string | null;
+    /** Target issue identifier, e.g. `TASK-482`. */
+    issueIdentifier?: string | null;
+    /** Per-run cross-issue influence cap. */
+    cap?: number | null;
+    /** Attempt count that tripped the cap. */
+    count?: number | null;
+    /** ISO timestamp at which log-only rollout becomes enforcement. */
+    enforceAt?: string | null;
+}
+export declare function isIssueWriteDenialCode(code: string | null | undefined): code is IssueWriteDenialCode;
+/**
+ * Bridge the two responsible-user ceiling codes emitted by the authorization
+ * layer into this module's code space, so a single UI notice covers every way
+ * an issue write can be refused.
+ */
+export declare function issueWriteDenialCodeForResponsibleUserDenial(code: ResponsibleUserDenialCode): IssueWriteDenialCode;
+export declare function describeIssueWriteDenial(code: IssueWriteDenialCode, context?: IssueWriteDenialContext): IssueWriteDenialCopy;
+/**
+ * Flatten a denial into the single `error` string an API client sees.
+ *
+ * Agents typically surface only `error`, so all three §6 obligations — boundary,
+ * who can act, sanctioned path — have to survive the flattening.
+ */
+export declare function issueWriteDenialApiMessage(copy: IssueWriteDenialCopy): string;
+/**
+ * Build the full `{ error, details }` body for a denied issue write. Keeping the
+ * machine-readable `code` next to the prose lets the board UI render the same
+ * copy without parsing sentences.
+ */
+export declare function issueWriteDenialResponse(code: IssueWriteDenialCode, context?: IssueWriteDenialContext): {
+    status: IssueWriteDenialCopy["status"];
+    body: {
+        error: string;
+        details: {
+            code: IssueWriteDenialCode;
+            boundary: string;
+            whoCanAct: string;
+            sanctionedPath: string;
+        } & Record<string, unknown>;
+    };
+};
+//# sourceMappingURL=issue-write-denial.d.ts.map

package/dist/issue-write-denial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-write-denial.d.ts","sourceRoot":"","sources":["../src/issue-write-denial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAC;AAEtC,eAAO,MAAM,wBAAwB,YACnC,yBAAyB,EACzB,kCAAkC,EAClC,sCAAsC,EACtC,0CAA0C,EAC1C,+BAA+B,EAC/B,oCAAoC,EACpC,4CAA4C,EAC5C,wCAAwC,CAChC,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,aAAa,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,mDAAmD;IACnD,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC9B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,IAAI,IAAI,oBAAoB,CAE9B;AAED;;;;GAIG;AACH,wBAAgB,4CAA4C,CAC1D,IAAI,EAAE,yBAAyB,GAC9B,oBAAoB,CAItB;AA6BD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,uBAA4B,GACpC,oBAAoB,CA0JtB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAO7E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,oBAAoB,EAC1B,OAAO,GAAE,uBAA4B,GACpC;IACD,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE;YACP,IAAI,EAAE,oBAAoB,CAAC;YAC3B,QAAQ,EAAE,MAAM,CAAC;YACjB,SAAS,EAAE,MAAM,CAAC;YAClB,cAAc,EAAE,MAAM,CAAC;SACxB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC7B,CAAC;CACH,CAcA"}

package/dist/issue-write-denial.js

@@ -0,0 +1,227 @@
+/**
+ * Copy contract for denied issue writes (open cross-task writes: failure UX).
+ *
+ * Cross-issue issue writes are default-open for standard-trust agents on issues
+ * they can already read (see SPEC-implementation §9.3). The remaining walls are
+ * rare — but a real incident burned a full detour discovering a workaround
+ * behind an opaque 403, so every one of them must say three things:
+ *
+ *   1. which boundary fired,
+ *   2. who *can* act,
+ *   3. the sanctioned path forward.
+ *
+ * This module is the single source of truth for that copy, so the API error
+ * body an agent reads and the notice a human sees in the UI are the same words.
+ * It is the issue-write sibling of `responsible-user-denial.ts`: the two
+ * responsible-user ceiling codes delegate to that module's copy so terminology
+ * ("on behalf of {user}", never "impersonate") stays consistent.
+ */
+import { describeResponsibleUserDenial, responsibleUserLabel, } from "./responsible-user-denial.js";
+export const ISSUE_WRITE_DENIAL_CODES = [
+    "issue_write_not_visible",
+    "issue_write_actor_class_excluded",
+    "issue_write_responsible_user_ceiling",
+    "issue_write_responsible_user_unavailable",
+    "issue_write_assignee_run_lock",
+    "cross_issue_influence_cap_exceeded",
+    "cross_issue_influence_run_context_required",
+    "issue_write_attribution_spoof_rejected",
+];
+export function isIssueWriteDenialCode(code) {
+    return ISSUE_WRITE_DENIAL_CODES.includes(code);
+}
+/**
+ * Bridge the two responsible-user ceiling codes emitted by the authorization
+ * layer into this module's code space, so a single UI notice covers every way
+ * an issue write can be refused.
+ */
+export function issueWriteDenialCodeForResponsibleUserDenial(code) {
+    return code === "RESPONSIBLE_USER_UNAVAILABLE"
+        ? "issue_write_responsible_user_unavailable"
+        : "issue_write_responsible_user_ceiling";
+}
+/** "this task" when the identifier is unknown, so copy never shows a raw id. */
+function issueLabel(identifier) {
+    const trimmed = identifier?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "this task";
+}
+/** "the assignee" when the name is unknown. */
+function assigneeLabel(name) {
+    const trimmed = name?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "the current assignee";
+}
+/** "this agent" when the name is unknown. */
+function actorLabel(name) {
+    const trimmed = name?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "this agent";
+}
+/**
+ * The escape hatch an earlier incident had to discover by trial and error. Naming it in
+ * every boundary denial is the point of plan §6 — an agent that reads the error
+ * should not need a detour to find the supported path.
+ */
+const CHILD_ISSUE_PATH = "create a child issue with the request in its description (issue creation is a " +
+    "separate, open write path) and let its assignee act";
+export function describeIssueWriteDenial(code, context = {}) {
+    const issue = issueLabel(context.issueIdentifier);
+    const actor = actorLabel(context.actorLabel);
+    const assignee = assigneeLabel(context.assigneeLabel);
+    const responsible = responsibleUserLabel(context.responsibleUserName);
+    switch (code) {
+        case "issue_write_not_visible":
+            return {
+                code,
+                status: 403,
+                tone: "boundary",
+                boundary: "Issue visibility",
+                title: "Task is outside this actor's visibility",
+                description: `Issue writes are open by default, but only for tasks the actor can already ` +
+                    `read. ${issue} is not visible to ${actor}, so its comment, update, child, and ` +
+                    `assignment channels are all closed — the wall is visibility, not the write itself.`,
+                whoCanAct: `${assignee}, and any agent or board member the task is visible to.`,
+                sanctionedPath: `Ask the board to widen visibility for ${actor}, or ${CHILD_ISSUE_PATH}.`,
+            };
+        case "issue_write_actor_class_excluded":
+            return {
+                code,
+                status: 403,
+                tone: "boundary",
+                boundary: "Actor-class boundary",
+                title: "This actor class cannot write to tasks",
+                description: `Default-open issue writes are a standard-trust privilege. Low-trust, ` +
+                    `skill-test, and task-bridge scopes keep their existing tight walls, so ` +
+                    `${actor} cannot write to ${issue} no matter who it acts for.`,
+                whoCanAct: `A standard-trust agent in this company, or a board member.`,
+                sanctionedPath: `Report the request upward and let a standard-trust agent make the write — ` +
+                    `actor-class scope cannot be widened per task.`,
+            };
+        case "issue_write_responsible_user_ceiling": {
+            const ceiling = describeResponsibleUserDenial("RESPONSIBLE_USER_UNAUTHORIZED", {
+                userName: context.responsibleUserName,
+            });
+            return {
+                code,
+                status: 403,
+                tone: "boundary",
+                boundary: "Responsible-user ceiling",
+                title: ceiling.title,
+                description: `${ceiling.description} The write to ${issue} was refused for that reason.`,
+                whoCanAct: `${responsible} once authorized, or anyone already permitted to write to ${issue}.`,
+                sanctionedPath: ceiling.recommendedAction,
+            };
+        }
+        case "issue_write_responsible_user_unavailable": {
+            const unavailable = describeResponsibleUserDenial("RESPONSIBLE_USER_UNAVAILABLE", {
+                userName: context.responsibleUserName,
+            });
+            return {
+                code,
+                status: 403,
+                tone: "boundary",
+                // Distinct from the title, which already says "unavailable" — the
+                // boundary names the *mechanism*, so the two do not read as a stutter.
+                boundary: "Responsible-user availability",
+                title: unavailable.title,
+                description: `${unavailable.description} The write to ${issue} was refused for that reason.`,
+                whoCanAct: `A board member, or ${actor} once it has an active responsible user.`,
+                sanctionedPath: unavailable.recommendedAction,
+            };
+        }
+        case "issue_write_assignee_run_lock":
+            return {
+                code,
+                status: 409,
+                tone: "lock",
+                boundary: "Run checkout lock",
+                title: "Another agent's run owns this task",
+                description: `${assignee} has ${issue} checked out and a run is live. Checkout and run ` +
+                    `ownership stay assignee-scoped even though writes are open, so field edits ` +
+                    `belong to the run that holds the lock until it finishes.`,
+                whoCanAct: `${assignee}'s live run, or an agent holding the manage-active-checkouts permission.`,
+                sanctionedPath: `Comment instead of patching — comments stay open and wake ${assignee} — or ` +
+                    `wait for the run to release the lock and retry.`,
+            };
+        case "cross_issue_influence_cap_exceeded": {
+            const cap = context.cap ?? 20;
+            const attempt = context.count ?? null;
+            return {
+                code,
+                status: 429,
+                tone: "cap",
+                // No parentheses: surfaces render the boundary inside their own parens.
+                boundary: `Per-run cross-issue cap of ${cap} writes`,
+                title: "This run has spent its cross-issue write budget",
+                description: `A single heartbeat run may make at most ${cap} cross-issue comments or task ` +
+                    `updates combined${attempt !== null ? `; this was attempt ${attempt}` : ""}. The cap ` +
+                    `bounds runaway comment sprays and loops — it is a rate backstop, not a ` +
+                    `permission decision, so ${actor} is still allowed to write to ${issue}.`,
+                whoCanAct: `${actor} on its next heartbeat run, or ${assignee} on ${issue} directly.`,
+                sanctionedPath: `Consolidate what is left into one comment on your own task, or end the run and ` +
+                    `continue on the next heartbeat — the budget resets per run.`,
+            };
+        }
+        case "cross_issue_influence_run_context_required":
+            return {
+                code,
+                status: 403,
+                tone: "boundary",
+                boundary: "Heartbeat run context",
+                title: "Cross-issue writes need a run to attribute them to",
+                description: `Every agent comment and task update is attributed to a heartbeat run so the ` +
+                    `cross-issue cap can be counted and the audit trail can name who acted for whom. ` +
+                    `This request arrived without a valid run, so it could not be contained.`,
+                whoCanAct: `${actor}, once the request carries its own run id.`,
+                sanctionedPath: `Send the \`X-Paperclip-Run-Id\` header with your current run (\`$PAPERCLIP_RUN_ID\`) ` +
+                    `and retry.`,
+            };
+        case "issue_write_attribution_spoof_rejected":
+            return {
+                code,
+                status: 422,
+                tone: "attribution",
+                boundary: "Server-derived attribution",
+                title: "Responsible user cannot be chosen by the caller",
+                description: `\`onBehalfOfUserId\` is derived from the authenticated actor, never from the ` +
+                    `request body — an agent cannot pick the human whose authority it rides. The ` +
+                    `attempt was recorded in the audit log.`,
+                whoCanAct: `${actor} itself: the write is allowed, only the chosen attribution is not.`,
+                sanctionedPath: `Remove \`onBehalfOfUserId\` from the request and retry; the server fills in ` +
+                    `${responsible} from your run.`,
+            };
+    }
+}
+/**
+ * Flatten a denial into the single `error` string an API client sees.
+ *
+ * Agents typically surface only `error`, so all three §6 obligations — boundary,
+ * who can act, sanctioned path — have to survive the flattening.
+ */
+export function issueWriteDenialApiMessage(copy) {
+    return [
+        `${copy.title} (${copy.boundary}).`,
+        copy.description,
+        `Who can act: ${copy.whoCanAct}`,
+        `Try this: ${copy.sanctionedPath}`,
+    ].join(" ");
+}
+/**
+ * Build the full `{ error, details }` body for a denied issue write. Keeping the
+ * machine-readable `code` next to the prose lets the board UI render the same
+ * copy without parsing sentences.
+ */
+export function issueWriteDenialResponse(code, context = {}) {
+    const copy = describeIssueWriteDenial(code, context);
+    return {
+        status: copy.status,
+        body: {
+            error: issueWriteDenialApiMessage(copy),
+            details: {
+                code: copy.code,
+                boundary: copy.boundary,
+                whoCanAct: copy.whoCanAct,
+                sanctionedPath: copy.sanctionedPath,
+            },
+        },
+    };
+}
+//# sourceMappingURL=issue-write-denial.js.map

package/dist/issue-write-denial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-write-denial.js","sourceRoot":"","sources":["../src/issue-write-denial.ts"],"names":[],"mappings":"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"}

package/dist/issue-write-denial.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=issue-write-denial.test.d.ts.map

package/dist/issue-write-denial.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-write-denial.test.d.ts","sourceRoot":"","sources":["../src/issue-write-denial.test.ts"],"names":[],"mappings":""}

package/dist/issue-write-denial.test.js

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { ISSUE_WRITE_DENIAL_CODES, describeIssueWriteDenial, isIssueWriteDenialCode, issueWriteDenialApiMessage, issueWriteDenialCodeForResponsibleUserDenial, issueWriteDenialResponse, } from "./issue-write-denial.js";
+describe("describeIssueWriteDenial", () => {
+    it("answers all three plan §6 obligations for every code", () => {
+        for (const code of ISSUE_WRITE_DENIAL_CODES) {
+            const copy = describeIssueWriteDenial(code);
+            expect(copy.code, code).toBe(code);
+            // Boundary that fired, who can act, sanctioned path — none may be empty.
+            expect(copy.boundary.trim().length, code).toBeGreaterThan(0);
+            expect(copy.whoCanAct.trim().length, code).toBeGreaterThan(0);
+            expect(copy.sanctionedPath.trim().length, code).toBeGreaterThan(0);
+            expect(copy.title.trim().length, code).toBeGreaterThan(0);
+            expect(copy.description.trim().length, code).toBeGreaterThan(0);
+        }
+    });
+    it("never leaks a raw id or placeholder when labels are unknown", () => {
+        for (const code of ISSUE_WRITE_DENIAL_CODES) {
+            const copy = describeIssueWriteDenial(code);
+            const prose = `${copy.description} ${copy.whoCanAct} ${copy.sanctionedPath}`;
+            expect(prose, code).not.toMatch(/undefined|null/);
+            // Unknown labels degrade to generic nouns, never a bare id.
+            expect(prose, code).toMatch(/this task|this agent|the current assignee|the responsible user/);
+        }
+    });
+    it("keeps the boundary free of parentheses and distinct from the title", () => {
+        for (const code of ISSUE_WRITE_DENIAL_CODES) {
+            const copy = describeIssueWriteDenial(code, { cap: 20 });
+            // Surfaces render the boundary inside their own parens — nesting stutters.
+            expect(copy.boundary, code).not.toMatch(/[()]/);
+            // A title echoed verbatim as its own boundary reads as a mistake.
+            expect(copy.boundary.toLowerCase(), code).not.toBe(copy.title.toLowerCase());
+        }
+    });
+    it("names the actor, assignee, and task when they are known", () => {
+        const copy = describeIssueWriteDenial("issue_write_not_visible", {
+            actorLabel: "Fable",
+            assigneeLabel: "CodexCoder",
+            issueIdentifier: "TASK-482",
+        });
+        expect(copy.description).toContain("TASK-482");
+        expect(copy.description).toContain("Fable");
+        expect(copy.whoCanAct).toContain("CodexCoder");
+    });
+    it("points a visibility denial at the sanctioned child-issue path", () => {
+        const copy = describeIssueWriteDenial("issue_write_not_visible");
+        // The incident detour was discovering exactly this workaround.
+        expect(copy.sanctionedPath).toContain("child issue");
+    });
+    it("frames the per-run cap as a rate backstop, not a permission decision", () => {
+        const copy = describeIssueWriteDenial("cross_issue_influence_cap_exceeded", {
+            cap: 20,
+            count: 21,
+            actorLabel: "Fable",
+        });
+        expect(copy.status).toBe(429);
+        expect(copy.tone).toBe("cap");
+        expect(copy.boundary).toContain("20");
+        expect(copy.description).toContain("attempt 21");
+        expect(copy.description).toContain("still allowed");
+        expect(copy.sanctionedPath).toContain("next heartbeat");
+    });
+    it("defaults the cap to the shipped limit when context omits it", () => {
+        const copy = describeIssueWriteDenial("cross_issue_influence_cap_exceeded");
+        expect(copy.boundary).toContain("20");
+        expect(copy.description).not.toContain("attempt");
+    });
+    it("gives the run-context denial a copy-pasteable fix", () => {
+        const copy = describeIssueWriteDenial("cross_issue_influence_run_context_required");
+        expect(copy.sanctionedPath).toContain("X-Paperclip-Run-Id");
+        expect(copy.sanctionedPath).toContain("PAPERCLIP_RUN_ID");
+    });
+    it("tells a spoof attempt that the write itself was fine", () => {
+        const copy = describeIssueWriteDenial("issue_write_attribution_spoof_rejected", {
+            actorLabel: "Fable",
+            responsibleUserName: "Dotta",
+        });
+        expect(copy.status).toBe(422);
+        expect(copy.whoCanAct).toContain("Fable");
+        expect(copy.sanctionedPath).toContain("Dotta");
+        expect(copy.sanctionedPath).toContain("onBehalfOfUserId");
+    });
+    it("routes a run lock to comments, which stay open", () => {
+        const copy = describeIssueWriteDenial("issue_write_assignee_run_lock", {
+            assigneeLabel: "CodexCoder",
+        });
+        expect(copy.status).toBe(409);
+        expect(copy.tone).toBe("lock");
+        expect(copy.sanctionedPath).toContain("Comment instead");
+        expect(copy.sanctionedPath).toContain("CodexCoder");
+    });
+    it("reuses responsible-user ceiling copy and keeps on-behalf-of terminology", () => {
+        const ceiling = describeIssueWriteDenial("issue_write_responsible_user_ceiling", {
+            responsibleUserName: "Dotta",
+            issueIdentifier: "TASK-517",
+        });
+        expect(ceiling.title).toBe("Responsible user not authorized");
+        expect(ceiling.description).toContain("on behalf");
+        expect(ceiling.description).toContain("TASK-517");
+        expect(ceiling.description).not.toContain("impersonat");
+        expect(ceiling.whoCanAct).toContain("Dotta");
+        const unavailable = describeIssueWriteDenial("issue_write_responsible_user_unavailable", {
+            responsibleUserName: "Dotta",
+        });
+        expect(unavailable.title).toBe("Responsible user unavailable");
+        expect(unavailable.sanctionedPath).toContain("blocked");
+    });
+    it("falls back to generic phrasing when the responsible user is unknown", () => {
+        const copy = describeIssueWriteDenial("issue_write_responsible_user_ceiling");
+        expect(copy.description).toContain("the responsible user");
+    });
+});
+describe("issueWriteDenialCodeForResponsibleUserDenial", () => {
+    it("bridges both authorization-layer ceiling codes", () => {
+        expect(issueWriteDenialCodeForResponsibleUserDenial("RESPONSIBLE_USER_UNAUTHORIZED"))
+            .toBe("issue_write_responsible_user_ceiling");
+        expect(issueWriteDenialCodeForResponsibleUserDenial("RESPONSIBLE_USER_UNAVAILABLE"))
+            .toBe("issue_write_responsible_user_unavailable");
+    });
+});
+describe("isIssueWriteDenialCode", () => {
+    it("accepts shipped codes and rejects everything else", () => {
+        expect(isIssueWriteDenialCode("issue_write_not_visible")).toBe(true);
+        expect(isIssueWriteDenialCode("RESPONSIBLE_USER_UNAUTHORIZED")).toBe(false);
+        expect(isIssueWriteDenialCode(null)).toBe(false);
+        expect(isIssueWriteDenialCode(undefined)).toBe(false);
+        expect(isIssueWriteDenialCode("")).toBe(false);
+    });
+});
+describe("issueWriteDenialApiMessage", () => {
+    it("keeps boundary, who-can-act, and sanctioned path in the flattened error", () => {
+        const copy = describeIssueWriteDenial("issue_write_not_visible", {
+            actorLabel: "Fable",
+            issueIdentifier: "TASK-482",
+        });
+        const message = issueWriteDenialApiMessage(copy);
+        expect(message).toContain(copy.boundary);
+        expect(message).toContain("Who can act:");
+        expect(message).toContain("Try this:");
+        expect(message).toContain(copy.sanctionedPath);
+    });
+});
+describe("issueWriteDenialResponse", () => {
+    it("pairs the status with a machine-readable details payload", () => {
+        const { status, body } = issueWriteDenialResponse("cross_issue_influence_cap_exceeded", {
+            cap: 20,
+            count: 21,
+        });
+        expect(status).toBe(429);
+        expect(body.details.code).toBe("cross_issue_influence_cap_exceeded");
+        expect(body.details.boundary).toContain("20");
+        expect(body.error).toContain("Who can act:");
+    });
+    it("uses the status each code declares", () => {
+        expect(issueWriteDenialResponse("issue_write_assignee_run_lock").status).toBe(409);
+        expect(issueWriteDenialResponse("issue_write_attribution_spoof_rejected").status).toBe(422);
+        expect(issueWriteDenialResponse("issue_write_not_visible").status).toBe(403);
+    });
+});
+//# sourceMappingURL=issue-write-denial.test.js.map

package/dist/issue-write-denial.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-write-denial.test.js","sourceRoot":"","sources":["../src/issue-write-denial.test.ts"],"names":[],"mappings":"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"}

package/dist/markdown-work-products.d.ts

@@ -0,0 +1,26 @@
+import type { AttachmentArtifactWorkProductMetadata, IssueWorkProduct } from "./types/work-product.js";
+/**
+ * Shared classification for bridging attachment-backed Markdown work products
+ * into the issue document review experience. Server materialization and UI
+ * presentation must agree on eligibility, so both sides use these helpers.
+ */
+export declare const MARKDOWN_ATTACHMENT_CONTENT_TYPES: readonly ["text/markdown", "text/x-markdown", "application/markdown", "application/x-markdown"];
+/**
+ * Maximum attachment size eligible for review-document materialization.
+ * Matches the issue-document body limit: a UTF-8 payload of at most this many
+ * bytes always fits the 524288-character body cap.
+ */
+export declare const MARKDOWN_REVIEW_DOCUMENT_MAX_BYTES: number;
+export declare const ARTIFACT_REVIEW_DOCUMENT_KEY_PREFIX = "artifact-review-";
+export declare function isMarkdownAttachmentContent(input: {
+    contentType: string | null | undefined;
+    originalFilename?: string | null;
+}): boolean;
+export type AttachmentArtifactWorkProductLike = Pick<IssueWorkProduct, "type" | "provider" | "metadata">;
+export declare function getAttachmentArtifactWorkProductMetadata(workProduct: AttachmentArtifactWorkProductLike): AttachmentArtifactWorkProductMetadata | null;
+export declare function getMarkdownWorkProductAttachmentMetadata(workProduct: AttachmentArtifactWorkProductLike): AttachmentArtifactWorkProductMetadata | null;
+export declare function isMarkdownArtifactWorkProduct(workProduct: AttachmentArtifactWorkProductLike): boolean;
+export declare function artifactReviewDocumentKey(workProductId: string): string;
+export declare function isArtifactReviewDocumentKey(key: string): boolean;
+export declare function workProductIdFromArtifactReviewDocumentKey(key: string): string | null;
+//# sourceMappingURL=markdown-work-products.d.ts.map

package/dist/markdown-work-products.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-work-products.d.ts","sourceRoot":"","sources":["../src/markdown-work-products.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qCAAqC,EACrC,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAGjC;;;;GAIG;AAEH,eAAO,MAAM,iCAAiC,YAC5C,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,CAChB,CAAC;AAaX;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,QAAa,CAAC;AAE7D,eAAO,MAAM,mCAAmC,qBAAqB,CAAC;AAMtE,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACvC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,GAAG,OAAO,CAQV;AAED,MAAM,MAAM,iCAAiC,GAAG,IAAI,CAClD,gBAAgB,EAChB,MAAM,GAAG,UAAU,GAAG,UAAU,CACjC,CAAC;AAEF,wBAAgB,wCAAwC,CACtD,WAAW,EAAE,iCAAiC,GAC7C,qCAAqC,GAAG,IAAI,CAK9C;AAED,wBAAgB,wCAAwC,CACtD,WAAW,EAAE,iCAAiC,GAC7C,qCAAqC,GAAG,IAAI,CAI9C;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,iCAAiC,GAC7C,OAAO,CAET;AAED,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKhE;AAED,wBAAgB,0CAA0C,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrF"}

package/dist/markdown-work-products.js

@@ -0,0 +1,70 @@
+import { attachmentArtifactWorkProductMetadataSchema } from "./validators/work-product.js";
+/**
+ * Shared classification for bridging attachment-backed Markdown work products
+ * into the issue document review experience. Server materialization and UI
+ * presentation must agree on eligibility, so both sides use these helpers.
+ */
+export const MARKDOWN_ATTACHMENT_CONTENT_TYPES = [
+    "text/markdown",
+    "text/x-markdown",
+    "application/markdown",
+    "application/x-markdown",
+];
+const MARKDOWN_ATTACHMENT_CONTENT_TYPE_SET = new Set(MARKDOWN_ATTACHMENT_CONTENT_TYPES);
+const MARKDOWN_FALLBACK_CONTENT_TYPES = new Set([
+    "text/plain",
+    "application/octet-stream",
+    "binary/octet-stream",
+    "application/x-binary",
+]);
+const MARKDOWN_FILENAME_EXTENSIONS = [".md", ".markdown"];
+/**
+ * Maximum attachment size eligible for review-document materialization.
+ * Matches the issue-document body limit: a UTF-8 payload of at most this many
+ * bytes always fits the 524288-character body cap.
+ */
+export const MARKDOWN_REVIEW_DOCUMENT_MAX_BYTES = 512 * 1024;
+export const ARTIFACT_REVIEW_DOCUMENT_KEY_PREFIX = "artifact-review-";
+function normalizeAttachmentContentType(contentType) {
+    return (contentType ?? "").toLowerCase().split(";")[0]?.trim() ?? "";
+}
+export function isMarkdownAttachmentContent(input) {
+    const contentType = normalizeAttachmentContentType(input.contentType);
+    if (MARKDOWN_ATTACHMENT_CONTENT_TYPE_SET.has(contentType))
+        return true;
+    const filename = (input.originalFilename ?? "").toLowerCase();
+    if (!MARKDOWN_FILENAME_EXTENSIONS.some((extension) => filename.endsWith(extension))) {
+        return false;
+    }
+    return MARKDOWN_FALLBACK_CONTENT_TYPES.has(contentType);
+}
+export function getAttachmentArtifactWorkProductMetadata(workProduct) {
+    if (workProduct.type !== "artifact" || workProduct.provider !== "paperclip")
+        return null;
+    if (!workProduct.metadata)
+        return null;
+    const parsed = attachmentArtifactWorkProductMetadataSchema.safeParse(workProduct.metadata);
+    return parsed.success ? parsed.data : null;
+}
+export function getMarkdownWorkProductAttachmentMetadata(workProduct) {
+    const metadata = getAttachmentArtifactWorkProductMetadata(workProduct);
+    if (!metadata)
+        return null;
+    return isMarkdownAttachmentContent(metadata) ? metadata : null;
+}
+export function isMarkdownArtifactWorkProduct(workProduct) {
+    return getMarkdownWorkProductAttachmentMetadata(workProduct) !== null;
+}
+export function artifactReviewDocumentKey(workProductId) {
+    return `${ARTIFACT_REVIEW_DOCUMENT_KEY_PREFIX}${workProductId}`;
+}
+export function isArtifactReviewDocumentKey(key) {
+    return (key.startsWith(ARTIFACT_REVIEW_DOCUMENT_KEY_PREFIX) &&
+        key.length > ARTIFACT_REVIEW_DOCUMENT_KEY_PREFIX.length);
+}
+export function workProductIdFromArtifactReviewDocumentKey(key) {
+    if (!isArtifactReviewDocumentKey(key))
+        return null;
+    return key.slice(ARTIFACT_REVIEW_DOCUMENT_KEY_PREFIX.length);
+}
+//# sourceMappingURL=markdown-work-products.js.map

package/dist/markdown-work-products.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-work-products.js","sourceRoot":"","sources":["../src/markdown-work-products.ts"],"names":[],"mappings":"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"}

package/dist/markdown-work-products.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=markdown-work-products.test.d.ts.map

package/dist/markdown-work-products.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-work-products.test.d.ts","sourceRoot":"","sources":["../src/markdown-work-products.test.ts"],"names":[],"mappings":""}