fix(linear,notion): resolve Nango sync model names in path-mapper (#34)

* fix(linear,notion): resolve Nango sync model names in path-mapper

Nango emits sync records under PascalCase model names (LinearTeam,
LinearUser, LinearIssue, …, NotionPage), but the path-mapper alias
maps in adapter-linear and adapter-notion did not recognize those
names — only canonical lowercase types and a single `linearproject`
entry. Every Linear/Notion sync record was throwing
"Unsupported Linear object type: LinearXxx" inside the cloud's
`writeBatchToRelayfile`, where the rejection was swallowed by
`Promise.allSettled` and only surfaced as an `errors: N` counter
in CloudWatch with no message.

Mirror the GitHub adapter's pattern:
- Extend `OBJECT_TYPE_ALIASES` with the lowercased Linear model names.
- Add `NANGO_MODEL_MAP` + `normalizeNangoLinearModel` /
  `normalizeNangoNotionModel` for explicit Nango model resolution
  (and `try*` variants for callers that want soft failure).
- Cover every model emitted by the existing `linear-relay` and
  `notion-relay` Nango syncs in tests.

The cloud's record-writer still needs a Notion dispatch arm — that's
the follow-up PR in `cloud`. Once both land, Linear and Notion sync
records will start populating the workspace tree.

Bumps: adapter-linear 0.1.17 → 0.1.18, adapter-notion 0.1.15 → 0.1.16.

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

* revert: drop version bumps; document publish-phase ownership

Versions in packages/*/package.json are bumped by the publish workflow
(.github/workflows/publish.yml, workflow_dispatch), not by the feature
PR that introduces the change. Document the convention in AGENTS.md so
future contributors don't re-introduce the same drift between npm
versions and what cloud pins to.

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

---------

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

Author: khaliqgant

.gitignore

@@ -9,3 +9,4 @@ packages/*/tests/**/*.d.ts
 packages/*/tests/**/*.js.map
 packages/*/tests/**/*.d.ts.map
 .claude/settings.json
+.mcp.json

.trajectories/active/traj_829pqp6emgql.json

@@ -0,0 +1,46 @@
+{
+  "id": "traj_829pqp6emgql",
+  "version": 1,
+  "task": {
+    "title": "Implement docs/PATH_SLUGIFICATION_SPEC.md"
+  },
+  "status": "active",
+  "startedAt": "2026-05-04T11:59:04.694Z",
+  "agents": [
+    {
+      "name": "default",
+      "role": "lead",
+      "joinedAt": "2026-05-04T12:01:14.228Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_jhjvz9f5x1u2",
+      "title": "Work",
+      "agentName": "default",
+      "startedAt": "2026-05-04T12:01:14.228Z",
+      "events": [
+        {
+          "ts": 1777896074229,
+          "type": "decision",
+          "content": "Implement slugification as optional path parameters with ID-compatible fallback: Implement slugification as optional path parameters with ID-compatible fallback",
+          "raw": {
+            "question": "Implement slugification as optional path parameters with ID-compatible fallback",
+            "chosen": "Implement slugification as optional path parameters with ID-compatible fallback",
+            "alternatives": [],
+            "reasoning": "Existing adapter public APIs and tests depend on ID-only paths; optional title/name arguments let ingestion produce readable paths without breaking callers that only know IDs."
+          },
+          "significance": "high"
+        }
+      ]
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters",
+  "tags": [],
+  "_trace": {
+    "startRef": "78b286656657cd64b8f8fe16d9a42fe6c87043da",
+    "endRef": "78b286656657cd64b8f8fe16d9a42fe6c87043da"
+  }
+}

.trajectories/index.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "lastUpdated": "2026-05-04T12:01:14.230Z",
+  "trajectories": {
+    "traj_829pqp6emgql": {
+      "title": "Implement docs/PATH_SLUGIFICATION_SPEC.md",
+      "status": "active",
+      "startedAt": "2026-05-04T11:59:04.694Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayfile-adapters/.trajectories/active/traj_829pqp6emgql.json"
+    }
+  }
+}

AGENTS.md

@@ -150,6 +150,18 @@ Your trajectory helps others understand:
 
 Future agents can query past trajectories to learn from your decisions.
 <!-- prpm:snippet:end @agent-workforce/trail-snippet@1.1.0 -->
+
+## Repository conventions
+
+### Do not bump package versions in feature PRs
+
+Versions in `packages/*/package.json` are bumped by the publish phase, not in the PR that introduces the change. The repo's pattern (see `chore(release): bump all (patch)` commits in history) is:
+
+1. Open a feature PR with the source change only — leave `version` fields untouched.
+2. After merge, the publish workflow (`.github/workflows/publish.yml`, `workflow_dispatch`) handles the version bump and npm publish.
+
+If you bump a version in a feature PR, downstream consumers (e.g. the `cloud` repo) may pin to a version that hasn't been published yet, breaking installs. Always leave version bumps to the release flow.
+
 <!-- PRPM_MANIFEST_START -->
 
 <skills_system priority="1">

packages/linear/src/__tests__/path-mapper.test.ts

@@ -0,0 +1,81 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  computeLinearPath,
+  normalizeLinearObjectType,
+  normalizeNangoLinearModel,
+  tryNormalizeLinearObjectType,
+} from '../path-mapper.js';
+
+describe('linear path-mapper', () => {
+  describe('normalizeLinearObjectType', () => {
+    it('accepts canonical types', () => {
+      assert.equal(normalizeLinearObjectType('issue'), 'issue');
+      assert.equal(normalizeLinearObjectType('TEAM'), 'team');
+    });
+
+    it('accepts plural aliases', () => {
+      assert.equal(normalizeLinearObjectType('issues'), 'issue');
+      assert.equal(normalizeLinearObjectType('teams'), 'team');
+    });
+
+    it('accepts Nango-style PascalCase model names', () => {
+      assert.equal(normalizeLinearObjectType('LinearTeam'), 'team');
+      assert.equal(normalizeLinearObjectType('LinearUser'), 'user');
+      assert.equal(normalizeLinearObjectType('LinearIssue'), 'issue');
+      assert.equal(normalizeLinearObjectType('LinearComment'), 'comment');
+      assert.equal(normalizeLinearObjectType('LinearCycle'), 'cycle');
+      assert.equal(normalizeLinearObjectType('LinearMilestone'), 'milestone');
+      assert.equal(normalizeLinearObjectType('LinearProject'), 'project');
+      assert.equal(normalizeLinearObjectType('LinearRoadmap'), 'roadmap');
+    });
+
+    it('throws on unknown types', () => {
+      assert.throws(() => normalizeLinearObjectType('flarb'));
+    });
+  });
+
+  describe('tryNormalizeLinearObjectType', () => {
+    it('returns undefined on unknown types', () => {
+      assert.equal(tryNormalizeLinearObjectType('flarb'), undefined);
+    });
+
+    it('returns the resolved type for known input', () => {
+      assert.equal(tryNormalizeLinearObjectType('LinearIssue'), 'issue');
+    });
+  });
+
+  describe('normalizeNangoLinearModel', () => {
+    // Each Nango sync emits a single PascalCase model — see
+    // cloud/nango-integrations/linear-relay/syncs/*.ts. This test pins those
+    // contracts so any future sync rename surfaces here as a failure.
+    it('maps every Nango linear-relay sync model', () => {
+      assert.equal(normalizeNangoLinearModel('LinearComment'), 'comment');
+      assert.equal(normalizeNangoLinearModel('LinearCycle'), 'cycle');
+      assert.equal(normalizeNangoLinearModel('LinearIssue'), 'issue');
+      assert.equal(normalizeNangoLinearModel('LinearMilestone'), 'milestone');
+      assert.equal(normalizeNangoLinearModel('LinearProject'), 'project');
+      assert.equal(normalizeNangoLinearModel('LinearRoadmap'), 'roadmap');
+      assert.equal(normalizeNangoLinearModel('LinearTeam'), 'team');
+      assert.equal(normalizeNangoLinearModel('LinearUser'), 'user');
+    });
+
+    it('falls back to alias-map normalization for non-Nango input', () => {
+      assert.equal(normalizeNangoLinearModel('issues'), 'issue');
+    });
+  });
+
+  describe('computeLinearPath', () => {
+    it('produces Nango-driven paths from PascalCase model names', () => {
+      assert.equal(
+        computeLinearPath('LinearTeam', '50cf92f3-f53c-4ab6-bf05-ea76ebd21692'),
+        '/linear/teams/50cf92f3-f53c-4ab6-bf05-ea76ebd21692.json',
+      );
+      assert.equal(
+        computeLinearPath('LinearUser', 'usr_123'),
+        '/linear/users/usr_123.json',
+      );
+    });
+  });
+});

packages/linear/src/path-mapper.ts

@@ -16,23 +16,48 @@ export type LinearPathObjectType = (typeof LINEAR_OBJECT_TYPES)[number];
 const OBJECT_TYPE_ALIASES: Readonly<Record<string, LinearPathObjectType>> = {
   comment: 'comment',
   comments: 'comment',
+  linearcomment: 'comment',
   cycle: 'cycle',
   cycles: 'cycle',
+  linearcycle: 'cycle',
   issue: 'issue',
   issues: 'issue',
+  linearissue: 'issue',
   milestone: 'milestone',
   milestones: 'milestone',
   projectmilestone: 'milestone',
   projectmilestones: 'milestone',
+  linearmilestone: 'milestone',
   project: 'project',
   projects: 'project',
   linearproject: 'project',
   roadmap: 'roadmap',
   roadmaps: 'roadmap',
+  linearroadmap: 'roadmap',
   team: 'team',
   teams: 'team',
+  linearteam: 'team',
   user: 'user',
   users: 'user',
+  linearuser: 'user',
+};
+
+/**
+ * Nango sync record `model` names → canonical Linear object types. The Nango
+ * `linear-relay` integration emits records under these PascalCase model names
+ * (see `cloud/nango-integrations/linear-relay/syncs/*.ts`). Resolving them
+ * here lets the cloud's record-writer turn a Nango payload into a relayfile
+ * path without hardcoding the mapping at the dispatch site.
+ */
+const NANGO_MODEL_MAP: Readonly<Record<string, LinearPathObjectType>> = {
+  LinearComment: 'comment',
+  LinearCycle: 'cycle',
+  LinearIssue: 'issue',
+  LinearMilestone: 'milestone',
+  LinearProject: 'project',
+  LinearRoadmap: 'roadmap',
+  LinearTeam: 'team',
+  LinearUser: 'user',
 };
 
 function assertNonEmptySegment(value: string, label: string): string {
@@ -80,6 +105,20 @@ export function normalizeLinearObjectType(objectType: string): LinearPathObjectT
   return mapped;
 }
 
+export function tryNormalizeLinearObjectType(objectType: string): LinearPathObjectType | undefined {
+  try {
+    return normalizeLinearObjectType(objectType);
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeNangoLinearModel(model: string): LinearPathObjectType {
+  const direct = NANGO_MODEL_MAP[model];
+  if (direct) return direct;
+  return normalizeLinearObjectType(model);
+}
+
 export function linearIssuePath(issueId: string, title?: string): string {
   return `${LINEAR_PATH_ROOT}/issues/${titleSegmentWithId(title, issueId)}.json`;
 }

packages/notion/src/__tests__/path-mapper.test.ts

@@ -2,6 +2,7 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   computePath,
+  normalizeNangoNotionModel,
   notionDatabaseBlockPath,
   notionDatabaseMetadataPath,
   notionDatabasePageCommentsPath,
@@ -10,6 +11,7 @@ import {
   notionStandalonePageCommentsPath,
   notionStandalonePageContentPath,
   notionStandalonePagePath,
+  tryNormalizeNangoNotionModel,
 } from '../path-mapper.js';
 
 describe('path mapping', () => {
@@ -30,4 +32,30 @@ describe('path mapping', () => {
     assert.strictEqual(notionStandalonePageContentPath('page-1'), '/notion/pages/page-1/content.md');
     assert.strictEqual(notionStandalonePageCommentsPath('page-1'), '/notion/pages/page-1/comments.json');
   });
+
+  describe('normalizeNangoNotionModel', () => {
+    // The Nango notion-relay `fetch-pages` sync emits records under the
+    // `NotionPage` model — see
+    // cloud/nango-integrations/notion-relay/syncs/fetch-pages.ts. The other
+    // entries are forward-compatible for syncs we plan to add.
+    it('maps NotionPage to the standalone page object type', () => {
+      assert.strictEqual(normalizeNangoNotionModel('NotionPage'), 'page');
+    });
+
+    it('maps richer notion models for forward compatibility', () => {
+      assert.strictEqual(normalizeNangoNotionModel('NotionDatabase'), 'database');
+      assert.strictEqual(normalizeNangoNotionModel('NotionDatabasePage'), 'database_page');
+      assert.strictEqual(normalizeNangoNotionModel('NotionBlock'), 'block');
+      assert.strictEqual(normalizeNangoNotionModel('NotionComment'), 'comment');
+    });
+
+    it('throws on unknown models', () => {
+      assert.throws(() => normalizeNangoNotionModel('NotionFlarb'));
+    });
+
+    it('try-variant returns undefined on unknown models', () => {
+      assert.strictEqual(tryNormalizeNangoNotionModel('NotionFlarb'), undefined);
+      assert.strictEqual(tryNormalizeNangoNotionModel('NotionPage'), 'page');
+    });
+  });
 });

packages/notion/src/path-mapper.ts

@@ -120,6 +120,35 @@ export function notionDiscoveryManifestPath(): string {
   return `${NOTION_PATH_ROOT}/discovery/manifest.json`;
 }
 
+/**
+ * Nango sync record `model` names → canonical Notion path object types. The
+ * Nango `notion-relay` integration's `fetch-pages` sync emits records under
+ * the `NotionPage` model (see
+ * `cloud/nango-integrations/notion-relay/syncs/fetch-pages.ts`). Future
+ * notion syncs (databases, blocks, comments) extend this map.
+ */
+const NANGO_MODEL_MAP: Readonly<Record<string, NotionPathObjectType>> = {
+  NotionPage: 'page',
+  NotionDatabase: 'database',
+  NotionDatabasePage: 'database_page',
+  NotionBlock: 'block',
+  NotionComment: 'comment',
+};
+
+export function normalizeNangoNotionModel(model: string): NotionPathObjectType {
+  const mapped = NANGO_MODEL_MAP[model];
+  if (mapped) return mapped;
+  throw new Error(`Unsupported Notion Nango model: ${model}`);
+}
+
+export function tryNormalizeNangoNotionModel(model: string): NotionPathObjectType | undefined {
+  try {
+    return normalizeNangoNotionModel(model);
+  } catch {
+    return undefined;
+  }
+}
+
 export function computePath(input: ComputePathInput): string {
   switch (input.objectType) {
     case 'database':