fix(sync): sort fields before hashing in fingerprintSchema (27)

fingerprintSchema sorted tables and views before hashing but not fields, on
the same expression. Field-listing order isn't a stable API contract (and
CLAUDE.md already classifies field order as best-effort, non-drift), so a
field-order-only difference between plan-time and apply-time snapshots
flipped the fingerprint. The apply() drift guard treats that as a real
schema change: it hard-aborts a fresh apply (forcing a wasteful re-plan on
an unchanged schema) or, on a resume, emits a false RESUME_DRIFT_BYPASS
"someone else changed the dest" warning.

Sort the composed id=name=type strings the same way the views line already
does — equivalent to sorting by field id (unique, always the first token)
since ids can never collide, so order stops mattering while a genuine
rename/retype still changes the string content and therefore the hash.

Swept src/sync/ for sibling instances of the same pattern (identity hash
over an unsorted collection) — none found; every other join/sort site is
either already order-independent or deliberately order-sensitive for
best-effort order-drift reporting (compare.js).

Added regression coverage: same fields in different order -> same
fingerprint; add/remove/rename/retype a field -> different fingerprint.
Reverted the fix locally to confirm the new test fails without it, then
restored it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ARHAEEM

packages/mcp-server/src/sync/index.js

@@ -16,14 +16,20 @@ const ENGINE_VERSION = '2b';
 
 /**
  * Produce a deterministic SHA-256 fingerprint of a schema snapshot.
- * Order-independent: tables are sorted before hashing.
+ * Order-independent: tables, fields, and views are all sorted before hashing — field/view/
+ * column order is explicitly a "best-effort" (non-drift) concern elsewhere in the sync engine
+ * (see compare.js), and Airtable's field-listing order is not guaranteed stable between two
+ * reads of an otherwise-unchanged schema. Sorting the composed `id=name=type` strings is
+ * equivalent to sorting by `id` (a unique, stable-per-field identifier that always appears
+ * first in the string, before any content that legitimately changes the fingerprint like a
+ * rename or retype) while keeping the same shape as the views line below.
  *
  * @param {{ tables: Array<{id:string, name:string, fields:Array<{id:string,name:string,type:string}>}> }} snap
  * @returns {string}  hex digest
  */
 export function fingerprintSchema(snap) {
   const basis = snap.tables
-    .map((t) => `${t.id}:${t.name}:` + t.fields.map((f) => `${f.id}=${f.name}=${f.type}`).join(',')
+    .map((t) => `${t.id}:${t.name}:` + t.fields.map((f) => `${f.id}=${f.name}=${f.type}`).sort().join(',')
       + ';V:' + (t.views || []).map((v) => `${v.id}=${v.name}=${v.type}`).sort().join(','))
     .sort()
     .join('|');

packages/mcp-server/test/sync/test-index.test.js

@@ -20,6 +20,55 @@ describe('sync index.plan', () => {
     const b = { tables: [{ id: 't2', name: 'B', fields: [] }, { id: 't1', name: 'A', fields: [{ id: 'f1', name: 'x', type: 'text' }] }] };
     assert.equal(fingerprintSchema(a), fingerprintSchema(b));
   });
+  // Regression test (Sentry finding, Task 27): fields were NOT sorted before hashing while
+  // tables and views were — a field-order-only difference between two snapshots of an
+  // otherwise-identical schema (Airtable's field-listing order is not a stable/guaranteed
+  // contract; CLAUDE.md classifies field/view/column order as "best-effort", i.e. non-drift)
+  // flipped the fingerprint, which the apply() drift guard (index.js) treats as a real
+  // schema change — aborting mode=apply (or, on a resume, emitting a scary but false
+  // RESUME_DRIFT_BYPASS "someone else changed the dest" warning) on an unchanged schema.
+  it('fingerprintSchema: reordering a table\'s fields (no content change) does NOT change the fingerprint', () => {
+    const mkTable = (fields) => ({ id: 't1', name: 'T', fields, views: [{ id: 'v1', name: 'Grid view', type: 'grid' }] });
+    const fA = { id: 'f1', name: 'Name', type: 'text' };
+    const fB = { id: 'f2', name: 'Count', type: 'number' };
+    const fC = { id: 'f3', name: 'Status', type: 'singleSelect' };
+    const a = { tables: [mkTable([fA, fB, fC])] };
+    const b = { tables: [mkTable([fC, fA, fB])] };
+    const c = { tables: [mkTable([fB, fC, fA])] };
+    assert.equal(fingerprintSchema(a), fingerprintSchema(b), 'permutation 1 must match');
+    assert.equal(fingerprintSchema(a), fingerprintSchema(c), 'permutation 2 must match');
+  });
+  it('fingerprintSchema: a genuine field change (add/remove/rename/retype) still changes the fingerprint', () => {
+    const base = { tables: [{ id: 't1', name: 'T', fields: [
+      { id: 'f1', name: 'Name', type: 'text' },
+      { id: 'f2', name: 'Count', type: 'number' },
+    ] }] };
+    const fpBase = fingerprintSchema(base);
+
+    const added = { tables: [{ id: 't1', name: 'T', fields: [
+      { id: 'f1', name: 'Name', type: 'text' },
+      { id: 'f2', name: 'Count', type: 'number' },
+      { id: 'f3', name: 'Extra', type: 'text' },
+    ] }] };
+    assert.notEqual(fingerprintSchema(added), fpBase, 'added field must change the fingerprint');
+
+    const removed = { tables: [{ id: 't1', name: 'T', fields: [
+      { id: 'f1', name: 'Name', type: 'text' },
+    ] }] };
+    assert.notEqual(fingerprintSchema(removed), fpBase, 'removed field must change the fingerprint');
+
+    const renamed = { tables: [{ id: 't1', name: 'T', fields: [
+      { id: 'f1', name: 'Name', type: 'text' },
+      { id: 'f2', name: 'Renamed', type: 'number' },
+    ] }] };
+    assert.notEqual(fingerprintSchema(renamed), fpBase, 'renamed field must change the fingerprint');
+
+    const retyped = { tables: [{ id: 't1', name: 'T', fields: [
+      { id: 'f1', name: 'Name', type: 'text' },
+      { id: 'f2', name: 'Count', type: 'singleLineText' },
+    ] }] };
+    assert.notEqual(fingerprintSchema(retyped), fpBase, 'retyped field must change the fingerprint');
+  });
 });
 
 describe('sync index.plan — direction param (Task 10)', () => {