docs(sync): document drift guard third-round fix — strip autoNumber runtime counter from typeOptions hash (engine 2e)

CLAUDE.md: drift guard now hashes typeOptions through `fingerprintTypeOptions()`, which strips `maxUsedAutoNumber` — a read-only server counter advanced on every row creation, including by sync's own records phase. Hashing it raw (engine `2d`) made an unchanged schema abort with phantom `DRIFT` when any row landed between plan and apply, or when re-applying after a records run that

Author: ARHAEEM

CLAUDE.md

@@ -9,6 +9,16 @@ External review (PR #19) found both, with a reproduction. Sync's drift guard is
 two holes that compounded: the fingerprint usually could not see the change, and once a run was
 resuming it stopped looking.
 
+- **Third review round (same day): `2d` hashed autoNumber's runtime counter — fixed as engine `2e`.**
+  `typeOptions.maxUsedAutoNumber` is a read-only counter the server advances whenever a row is
+  created — including by this sync's OWN records phase — so hashing it raw made an unchanged
+  schema abort with a phantom `DRIFT` (review repro: counter 7 → 8, apply aborted), and a
+  re-apply after any records run could trip its own guard. The fingerprint now strips it via
+  `fingerprintTypeOptions()`, the same strip `apply.js` already performs before every write;
+  semantic `typeOptions` changes on the same field still drift. Regressions cover the synthetic
+  shape, the `normalizeSchema` parity path, and a full plan→apply run with only the counter
+  advanced. Plans saved by `2d` abort `PLAN_STALE` with a re-plan instruction. Fails safe
+  either way — the bug refused legitimate applies; it never overwrote anything.
 - **Second review round (same day): the widening itself had three defects, all fixed as engine `2d`.**
   (1) The fingerprint hashed `f.options` — a key NO normalized snapshot carries; the real key is
   `typeOptions` (`normalizeSchema`), so the widening was inert in production while its tests
@@ -45,8 +55,8 @@ resuming it stopped looking.
 - **A plan from an older engine aborts with `PLAN_STALE`, not `DRIFT`.** An older plan hashed
   fewer facets, so its digest can never match a current one. Reporting that as `DRIFT` blamed a
   collaborator; mid-resume it invited the user to wave an overwrite through to fix what was really
-  a version mismatch. `ENGINE_VERSION` is exported (now `2d` — see the second-round entry above),
-  so test fixtures track it instead of pinning a literal that goes stale on the next bump.
+  a version mismatch. `ENGINE_VERSION` is exported (now `2e` — see the rounds above), so test
+  fixtures track it instead of pinning a literal that goes stale on the next bump.
 
 ### Changed (2026-07-30 — `mirror` no longer claims more than it does)
 

packages/mcp-server/CHANGELOG.md

@@ -18,9 +18,29 @@ import { writeSyncJobStatus, readSyncJobStatus } from './job-status.js';
 // passed on synthetic shapes — external review caught it with a live reproduction. 2d hashes
 // `typeOptions` and also folds in table SECTIONS (mirror prune deletes dest-only sections by
 // id, so a renamed section must read as drift, not get deleted under its old identity).
-// A plan saved by an older engine hashed LESS, so its fingerprint can never match a current
-// one — apply detects that by version and says "re-plan", instead of blaming a collaborator.
-export const ENGINE_VERSION = '2d';
+// '2e' exists because 2d hashed typeOptions RAW, including autoNumber's maxUsedAutoNumber —
+// a read-only runtime counter Airtable advances whenever a row is created, including by this
+// sync's OWN records phase. Any row landing between plan and apply (or a re-apply after a
+// records run) produced a phantom DRIFT abort on an unchanged schema. 2e strips it, exactly
+// as apply.js already strips it before every write.
+// A plan saved by an older engine hashed a DIFFERENT basis, so its fingerprint can never match
+// a current one — apply detects that by version and says "re-plan", instead of blaming a
+// collaborator.
+export const ENGINE_VERSION = '2e';
+
+/**
+ * typeOptions as hashed by the drift fingerprint: schema SEMANTICS only, runtime state out.
+ *
+ * `maxUsedAutoNumber` is the one known runtime key — a counter the server advances on row
+ * creation, not something a collaborator edits. apply.js strips it at both of its write
+ * sites for the same reason (the API rejects it); if another runtime key ever surfaces,
+ * add it HERE and THERE together, and bump ENGINE_VERSION.
+ */
+function fingerprintTypeOptions(typeOptions) {
+  if (!typeOptions || typeof typeOptions !== 'object') return typeOptions ?? null;
+  const { maxUsedAutoNumber, ...semantic } = typeOptions;
+  return semantic;
+}
 
 /**
  * Stable JSON — object keys sorted at every depth.
@@ -74,7 +94,7 @@ export function fingerprintSchema(snap, { includeViewConfig = false } = {}) {
     // must construct fields the way normalizeSchema does.
     .map((t) => `${t.id}:${t.name}:`
       + t.fields.map((f) =>
-        `${f.id}=${f.name}=${f.type}=${stableJson(f.typeOptions ?? null)}=${f.description ?? ''}`
+        `${f.id}=${f.name}=${f.type}=${stableJson(fingerprintTypeOptions(f.typeOptions))}=${f.description ?? ''}`
       ).sort().join(',')
       + ';V:' + (t.views || []).map((v) =>
         `${v.id}=${v.name}=${v.type}` + (includeViewConfig ? `=${stableJson(v.config ?? null)}` : '')

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

@@ -103,6 +103,34 @@ describe('sync index.plan', () => {
     assert.equal(fingerprintSchema(a), fingerprintSchema(b), 'key order must not be drift');
   });
 
+  it('fingerprintSchema: autoNumber maxUsedAutoNumber is runtime state, NOT drift', () => {
+    // The counter advances whenever a row is created — including by this sync's OWN records
+    // phase — so hashing it made an unchanged schema abort with a phantom DRIFT (review repro:
+    // counter 7 → 8, fingerprint changed, apply aborted). apply.js strips it before every
+    // write for the same reason; the fingerprint must share that knowledge.
+    const mk = (typeOptions) => ({ tables: [{ id: 't1', name: 'T', fields: [
+      { id: 'f1', name: 'ID', type: 'autoNumber', typeOptions },
+    ] }] });
+    assert.equal(
+      fingerprintSchema(mk({ maxUsedAutoNumber: 7 })),
+      fingerprintSchema(mk({ maxUsedAutoNumber: 8 })),
+      'a counter-only change must NOT be drift',
+    );
+    // …but a SEMANTIC typeOptions change on the same field still is.
+    assert.notEqual(
+      fingerprintSchema(mk({ maxUsedAutoNumber: 7, format: 'A' })),
+      fingerprintSchema(mk({ maxUsedAutoNumber: 8, format: 'B' })),
+      'a real typeOptions change must still be drift even with the counter moving',
+    );
+    // And through the REAL normalizer, same asymmetry.
+    const raw = (n, fmt) => ({ data: { tableSchemas: [{
+      id: 'tbl1', name: 'T', primaryColumnId: 'fld1',
+      columns: [{ id: 'fld1', name: 'ID', type: 'autoNumber', typeOptions: { maxUsedAutoNumber: n, ...(fmt ? { format: fmt } : {}) } }],
+    }] } });
+    assert.equal(fingerprintSchema(normalizeSchema(raw(7))), fingerprintSchema(normalizeSchema(raw(8))));
+    assert.notEqual(fingerprintSchema(normalizeSchema(raw(7, 'A'))), fingerprintSchema(normalizeSchema(raw(8, 'B'))));
+  });
+
   it('fingerprintSchema: a section rename is drift in the DEFAULT mode (mirror prune deletes by id)', () => {
     // pruneSchema deletes dest-only sections by ID. If a section renamed between plan and apply
     // does not read as drift, apply deletes it under its old identity — reproduced by review:

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

@@ -11,7 +11,8 @@ import { mkdtempSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { MockClient } from './helpers/mock-client.js';
-import { apply, applyJob, ENGINE_VERSION } from '../../src/sync/index.js';
+import { apply, applyJob, ENGINE_VERSION, fingerprintSchema } from '../../src/sync/index.js';
+import { normalizeSchema } from '../../src/sync/snapshot.js';
 import { savePlan, saveIdmap } from '../../src/sync/idmap.js';
 import { newJournal, recordDone, recordFailed, saveJournal } from '../../src/sync/journal.js';
 
@@ -60,6 +61,39 @@ describe('sync index.apply — journal resume bypasses the drift guard', () => {
     assert.deepEqual(names, ['TableA'], `no action may run on an aborted resume: ${names}`);
   });
 
+  // Review reproduction, end to end: the ONLY change between plan and apply is autoNumber's
+  // maxUsedAutoNumber advancing (7 → 8) — a counter the server bumps on row creation, including
+  // by this sync's own records phase. Engine 2d hashed it and aborted DRIFT on an unchanged
+  // schema; a re-apply after any records run would trip its own guard.
+  it('an advanced maxUsedAutoNumber counter alone does NOT abort apply with DRIFT', async () => {
+    process.env.AIRTABLE_USER_MCP_HOME = mkdtempSync(join(tmpdir(), 'resume-drift-counter-'));
+    const client = new MockClient();
+    // Seed a dest table with an autoNumber field, counter at 7.
+    client.tables.push({
+      id: 'tblD1', name: 'T', primaryColumnId: 'fldD1',
+      columns: [{ id: 'fldD1', name: 'ID', type: 'autoNumber', typeOptions: { maxUsedAutoNumber: 7 }, description: null }],
+      views: [], rows: [],
+    });
+    // Plan against the CURRENT dest state (counter 7), no actions — pure drift-guard exercise.
+    // normalizeSchema takes the FULL response ({data:{tableSchemas}}), same as snapshotBase does.
+    const destAtPlanTime = normalizeSchema(await client.getApplicationData(DEST));
+    savePlan(SRC, DEST, {
+      planId: 'plnCTR', engineVersion: ENGINE_VERSION,
+      destFingerprint: fingerprintSchema({ baseId: DEST, ...destAtPlanTime }),
+      sourceBaseId: SRC, destBaseId: DEST,
+      idmap: { tables: {}, fields: {}, views: {} },
+      actions: [], orphans: [], warnings: [],
+    });
+    saveIdmap(SRC, DEST, { tables: {}, fields: {}, views: {}, records: {}, attachments: {} });
+
+    // Airtable advances the counter before apply runs.
+    client.tables[client.tables.length - 1].columns[0].typeOptions.maxUsedAutoNumber = 8;
+
+    const out = await apply({ client, sourceBaseId: SRC, destBaseId: DEST, planId: 'plnCTR', runStartedAt: 't1' });
+    assert.notEqual(out.machine.aborted, true,
+      `a counter-only change must not read as drift: ${out.human}`);
+  });
+
   // A plan from an older engine hashed fewer facets, so its digest can NEVER match. Reporting that
   // as DRIFT blames a collaborator; reporting it mid-resume as RESUME_DRIFT invites the user to
   // wave through an overwrite to fix what is really a version mismatch.