fix(tracking): snapshot canonical doc on /tracking load so stale-save detection covers fresh installs

ensureCanonicalDocExists creates the canonical doc via CAS when the /tracking
UI first loads settings. This guarantees expectedRaw !== null by save time,
so the field-by-field stale check always runs — including on upgrades and
fresh installs where no /tracking save has ever occurred.

Author: Jmosier69

src/index.ts

@@ -4,6 +4,7 @@ import { validateLicense, CACHE_KEY } from './lib/licensing';
 import { buildPageFragments } from './frontend/injector';
 import {
   documentToApiResponse,
+  ensureCanonicalDocExists,
   loadTrackingSettingsDocument,
   saveTrackingSettings,
   type TrackingSaveBody,
@@ -262,6 +263,9 @@ export function createPlugin() {
       'tracking/settings': {
         handler: async (ctx) => {
           const doc = await loadTrackingSettingsDocument(ctx);
+          // Snapshot current state so saveTrackingSettings can detect races
+          // with the settings-schema form even on first-ever /tracking load.
+          await ensureCanonicalDocExists(ctx, doc);
           return documentToApiResponse(doc);
         }
       },

src/lib/trackingSettingsDocument.ts

@@ -125,6 +125,22 @@ export async function loadTrackingSettingsDocument(
   return loadLegacyTrackingDocument(ctx);
 }
 
+/**
+ * Ensure the canonical doc exists so saveTrackingSettings always has a snapshot
+ * for conflict detection. Called when the /tracking UI loads settings — by save
+ * time the doc exists and the field-by-field stale check runs.
+ */
+export async function ensureCanonicalDocExists(
+  ctx: Pick<PluginContext, 'kv'>,
+  doc: TrackingSettingsDocument,
+): Promise<void> {
+  const kv = asKvWithCas(ctx.kv);
+  const existing = await kv.getRaw(TRACKING_SETTINGS_DOC_KEY);
+  if (existing === null) {
+    await kv.commitIfValueUnchanged(TRACKING_SETTINGS_DOC_KEY, null, doc);
+  }
+}
+
 export async function mirrorTrackingDocumentToSettingsKeys(
   ctx: Pick<PluginContext, 'kv'>,
   doc: TrackingSettingsDocument,