{"record":{"id":"1aec00fc157a2e19","repo":"thedotmack/claude-mem","slug":"sync-hub-status-projected-seq-exceeds-head-seq","errorCode":null,"errorMessage":"sync hub status: projected_seq exceeds head_seq","messagePattern":"sync hub status: projected_seq exceeds head_seq","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/services/sync/CloudSync.ts","lineNumber":623,"sourceCode":"      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n        throw new Error('sync hub status: response must be an object');\n      }\n      const record = parsed as Record<string, unknown>;\n      if (record.protocol_version !== 2) {\n        throw new Error('sync hub status: response requires protocol_version 2');\n      }\n      if (\n        typeof record.epoch !== 'string'\n        || typeof record.head_seq !== 'string'\n        || typeof record.projected_seq !== 'string'\n      ) {\n        throw new Error('sync hub status: response requires decimal-string epoch/head_seq/projected_seq');\n      }\n      const epoch = assertCanonicalDecimal(record.epoch, { positive: true });\n      const headSeq = assertCanonicalDecimal(record.head_seq);\n      const projectedSeq = assertCanonicalDecimal(record.projected_seq);\n      if (compareCanonicalDecimals(projectedSeq, headSeq) > 0) {\n        throw new Error('sync hub status: projected_seq exceeds head_seq');\n      }\n      this.hubStatus = {\n        checkedAt,\n        reachable: true,\n        epoch,\n        headSeq,\n        projectedSeq,\n        error: null,\n      };\n    } catch (error) {\n      const raw = error instanceof Error ? error.message : String(error);\n      const safe = this.token === '' ? raw : raw.split(this.token).join('[REDACTED]');\n      this.hubStatus = {\n        checkedAt,\n        reachable: false,\n        epoch: null,\n        headSeq: null,\n        projectedSeq: null,","sourceCodeStart":605,"sourceCodeEnd":641,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d768ba364302d12b76e69e4f021f0bb1d2d50ed6/src/services/sync/CloudSync.ts#L605-L641","documentation":"Thrown after epoch/head_seq/projected_seq are individually validated as canonical decimals, when compareCanonicalDecimals(projectedSeq, headSeq) > 0 — i.e. the hub claims a projected sequence greater than its committed head. This violates the checkpoint invariant (projected_seq <= head_seq is not required in general, but here projected must not exceed head). It indicates hub-side corruption or a logic error, not a client mistake.","triggerScenarios":"The hub returned a status where projected_seq > head_seq, which is logically impossible in a correct monotonic sequencer. Possible if the hub had a rollback bug, mixed two epochs, or emitted stale cached fields inconsistently.","commonSituations":"Hub bug after a partial write/rollback; hub restarting mid-assignment and emitting inconsistent head/projected; a misbehaving hub replica returning cached divergent state.","solutions":["Retry the status probe once — a transient inconsistent response may self-correct.","If it persists, the hub is in a corrupt/inconsistent state; report to the hub operator with the epoch/head_seq/projected_seq values.","Do not attempt to push/pull against a hub in this state, as sequence assumptions are violated.","Confirm the client is not pointed at a stale/read-only hub replica divergent from the primary."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isHubProjectedExceedsHead(e: unknown): boolean {\n  return e instanceof Error && /sync hub status: projected_seq exceeds head_seq/i.test(e.message);\n}","tryCatchPattern":"try { await cloudSync.status(); }\ncatch (e) {\n  if (isHubProjectedExceedsHead(e)) {\n    await sleep(2000); // give an inconsistent hub a moment to settle\n    try { return await cloudSync.status(); } catch { markHubCorrupt(e.message); return; }\n  }\n  throw e;\n}","preventionTips":["Do not push/pull against a hub returning projected_seq > head_seq; treat it as corrupt.","Report persistent occurrences to the hub operator with the epoch/head/projected values.","Ensure you are not reading from a stale, divergent hub replica.","Add monitoring that flags this invariant break immediately."],"tags":["cloud-sync","hub","invariant","sequence","corruption"],"backgroundTag":null,"analyzedSha":"d768ba364302d12b76e69e4f021f0bb1d2d50ed6","analyzedAt":"2026-08-12T23:52:55.241Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}