fix(linear): allowlist mutable IssueUpdateInput fields, drop synced-read fields (#36)

When a user edited a synced /linear/issues/<uuid>.json file in place — the
canonical workflow for the demo's bidirectional flow — buildIssueUpdate
forwarded every field as IssueUpdateInput. The path-mapper's read shape
includes denormalized fields that Linear's read API returns but
IssueUpdateInput does NOT accept (state_name, assignee_name,
priority_label, created_at, updated_at, _connection, _webhook,
descriptionData on some read paths). Linear rejected with:

  Field "state_name" is not defined by type "IssueUpdateInput".
  Did you mean "stateId"?

The denylist approach (drop only id/identifier/createdAt/...) was too
narrow — it missed every snake_case denormalized field, and would miss
any new field the path-mapper ever adds. Flip to an explicit allowlist
matching IssueUpdateInput's actual schema, mirroring how
buildIssueCreate already handles IssueCreateInput. Anything not in the
allowlist is silently dropped; only mutable fields reach the mutation.

Caught and reproduced on op_31 of workspace rw_517d60b6 during the demo
verification immediately after cloud#467 deployed.

Regression test pins the synced-read shape that hit op_31.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: khaliqgant

packages/linear/src/writeback.test.ts

@@ -106,6 +106,47 @@ describe('linear writeback', () => {
       });
     });
 
+    it('drops denormalized synced-read fields that IssueUpdateInput does not accept', () => {
+      // Pins the bug surfaced on op_31 in workspace rw_517d60b6: the synced
+      // file the path-mapper wrote on the read side included Linear's
+      // denormalized fields (state_name, assignee_name, priority_label,
+      // _connection, _webhook, descriptionData, …). When a user edited the
+      // file in place keeping the full envelope and just changed the title,
+      // the writeback forwarded every field as IssueUpdateInput and Linear
+      // rejected with `Field "state_name" is not defined by type
+      // "IssueUpdateInput". Did you mean "stateId"?`.
+      //
+      // The fix: explicit allowlist matching IssueUpdateInput. Anything not
+      // in the schema is silently dropped; only mutable fields go through.
+      const req = resolveWritebackRequest(
+        `/linear/issues/${PAGE_UUID}.json`,
+        JSON.stringify({
+          id: PAGE_UUID,
+          identifier: 'PROJ-441',
+          title: 'edited title',
+          description: 'edited description',
+          // Denormalized read-only fields the writeback must NOT forward:
+          state_name: 'Backlog',
+          assignee_name: null,
+          priority_label: 'No priority',
+          created_at: '2026-04-03T18:38:27.932Z',
+          updated_at: '2026-04-03T18:38:28.177Z',
+          url: 'https://linear.app/x/issue/PROJ-441',
+          // Read-side metadata Linear's webhook normalizer emits:
+          _connection: { provider: 'linear' },
+          _webhook: { action: 'update' },
+          descriptionData: '{"type":"doc"}',
+        }),
+      );
+      const variables = req.body.variables as { id: string; input: Record<string, unknown> };
+      assert.strictEqual(variables.id, PAGE_UUID);
+      assert.deepStrictEqual(variables.input, {
+        title: 'edited title',
+        description: 'edited description',
+        descriptionData: '{"type":"doc"}',
+      });
+    });
+
     it('unwraps the synced envelope written by LinearAdapter.renderContent', () => {
       // This is the exact shape an agent sees when it reads a synced
       // /linear/issues/<id>.json file produced by LinearAdapter.renderContent.

packages/linear/src/writeback.ts

@@ -208,26 +208,10 @@ function buildIssueCreate(content: string): LinearWritebackRequest {
   };
 }
 
-/**
- * Server-managed fields that must never be forwarded as part of an
- * `IssueUpdateInput`. Linear rejects updates that try to mutate these.
- */
-const ISSUE_UPDATE_DENYLIST = new Set([
-  'id',
-  'identifier',
-  'createdAt',
-  'updatedAt',
-  'archivedAt',
-  'url',
-  'team',
-  'creator',
-  'parent',
-]);
-
 /**
  * Envelope marker fields written by `LinearAdapter.renderContent()`. When the
  * payload presents itself as the synced envelope (rather than a bare update
- * input), unwrap to the inner `payload` before applying the denylist.
+ * input), unwrap to the inner `payload` before applying the allowlist.
  *
  * Without this step, a round-tripped synced file would forward `provider`,
  * `workspaceId`, `objectType`, etc. into the GraphQL mutation and Linear
@@ -240,16 +224,52 @@ function looksLikeSyncedEnvelope(payload: Record<string, unknown>): boolean {
   return ENVELOPE_MARKER_KEYS.some((key) => key in payload);
 }
 
+/**
+ * Fields Linear's `IssueUpdateInput` accepts. We use an explicit allowlist
+ * (rather than a denylist) so that synced-file fields the read API returns
+ * — `state_name`, `assignee_name`, `priority_label`, `created_at`, `_webhook`,
+ * etc. — get silently dropped instead of being forwarded into the mutation
+ * and rejected with `Field "X" is not defined by type "IssueUpdateInput"`.
+ *
+ * Mirrors the field set buildIssueCreate already accepts (which is itself a
+ * subset of `IssueCreateInput`), plus update-specific fields that are
+ * commonly edited in a synced-file workflow:
+ *   - `subscriberIds`     — change watchers
+ *   - `sortOrder`         — manual reordering
+ *   - `descriptionData`   — Linear's prosemirror-doc form of `description`
+ *
+ * If you need to set a field not in this list (e.g. `addedLabelIds` /
+ * `removedLabelIds` for incremental label changes), add it here and add a
+ * regression test in `__tests__/writeback-allowlist.test.ts`.
+ */
+const ISSUE_UPDATE_ALLOWLIST: ReadonlySet<string> = new Set([
+  'title',
+  'description',
+  'descriptionData',
+  'priority',
+  'assigneeId',
+  'stateId',
+  'projectId',
+  'cycleId',
+  'labelIds',
+  'dueDate',
+  'estimate',
+  'parentId',
+  'subscriberIds',
+  'sortOrder',
+]);
+
 /**
  * Build an `issueUpdate` mutation request for the writeback engine.
  *
  * Accepts two payload shapes:
  *   - the full synced envelope produced by `LinearAdapter.renderContent()`,
  *     with editable fields under `payload`. We unwrap automatically.
- *   - a bare update input where the top-level object IS the input (the form
- *     a hand-written workflow or specialist agent typically produces).
- *
- * Server-managed fields are stripped in either case.
+ *   - a bare update input where the top-level object IS the input — covers
+ *     both hand-written workflow payloads and edits to the synced-file
+ *     denormalized read (where the user keeps the full `{state_name,
+ *     assignee_name, ...}` envelope and just changes a field). Synced-only
+ *     fields are silently dropped via the allowlist.
  */
 function buildIssueUpdate(issueId: string, content: string): LinearWritebackRequest {
   const parsed = parseJsonObject(content);
@@ -259,11 +279,14 @@ function buildIssueUpdate(issueId: string, content: string): LinearWritebackRequ
 
   const input: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(source)) {
-    if (ISSUE_UPDATE_DENYLIST.has(key)) continue;
+    if (!ISSUE_UPDATE_ALLOWLIST.has(key)) continue;
     input[key] = value;
   }
   if (Object.keys(input).length === 0) {
-    throw new Error('issues/<id>.json update writeback requires at least one mutable field');
+    throw new Error(
+      'issues/<id>.json update writeback requires at least one mutable field ' +
+        '(see ISSUE_UPDATE_ALLOWLIST in @relayfile/adapter-linear/writeback for the accepted set)',
+    );
   }
 
   return {